| .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" Distributed under GPL |
| .\" %%%LICENSE_END |
| .\" |
| .\" adapted glibc info page |
| .\" |
| .\" This should run as 'Guru Meditation' (amiga joke :) |
| .\" The function is quite complex and deserves an example |
| .\" |
| .\" Polished, aeb, 2003-11-01 |
| .TH FMTMSG 3 2020-06-09 "" "Linux Programmer's Manual" |
| .SH NAME |
| fmtmsg \- print formatted error messages |
| .SH SYNOPSIS |
| .nf |
| .B #include <fmtmsg.h> |
| .PP |
| .BI "int fmtmsg(long " classification ", const char *" label , |
| .BI " int " severity ", const char *" text , |
| .BI " const char *" action ", const char *" tag ); |
| .fi |
| .SH DESCRIPTION |
| This function displays a message described by its arguments on the device(s) |
| specified in the |
| .I classification |
| argument. |
| For messages written to |
| .IR stderr , |
| the format depends on the |
| .B MSGVERB |
| environment variable. |
| .PP |
| The |
| .I label |
| argument identifies the source of the message. |
| The string must consist |
| of two colon separated parts where the first part has not more |
| than 10 and the second part not more than 14 characters. |
| .PP |
| The |
| .I text |
| argument describes the condition of the error. |
| .PP |
| The |
| .I action |
| argument describes possible steps to recover from the error. |
| If it is printed, it is prefixed by "TO FIX: ". |
| .PP |
| The |
| .I tag |
| argument is a reference to the online documentation where more |
| information can be found. |
| It should contain the |
| .I label |
| value and a unique identification number. |
| .SS Dummy arguments |
| Each of the arguments can have a dummy value. |
| The dummy classification value |
| .B MM_NULLMC |
| (0L) does not specify any output, so nothing is printed. |
| The dummy severity value |
| .B NO_SEV |
| (0) says that no severity is supplied. |
| The values |
| .BR MM_NULLLBL , |
| .BR MM_NULLTXT , |
| .BR MM_NULLACT , |
| .B MM_NULLTAG |
| are synonyms for |
| .IR "((char\ *)\ 0)" , |
| the empty string, and |
| .B MM_NULLSEV |
| is a synonym for |
| .BR NO_SEV . |
| .SS The classification argument |
| The |
| .I classification |
| argument is the sum of values describing 4 types of information. |
| .PP |
| The first value defines the output channel. |
| .TP 12n |
| .B MM_PRINT |
| Output to |
| .IR stderr . |
| .TP |
| .B MM_CONSOLE |
| Output to the system console. |
| .TP |
| .B "MM_PRINT | MM_CONSOLE" |
| Output to both. |
| .PP |
| The second value is the source of the error: |
| .TP 12n |
| .B MM_HARD |
| A hardware error occurred. |
| .TP |
| .B MM_FIRM |
| A firmware error occurred. |
| .TP |
| .B MM_SOFT |
| A software error occurred. |
| .PP |
| The third value encodes the detector of the problem: |
| .TP 12n |
| .B MM_APPL |
| It is detected by an application. |
| .TP |
| .B MM_UTIL |
| It is detected by a utility. |
| .TP |
| .B MM_OPSYS |
| It is detected by the operating system. |
| .PP |
| The fourth value shows the severity of the incident: |
| .TP 12n |
| .B MM_RECOVER |
| It is a recoverable error. |
| .TP |
| .B MM_NRECOV |
| It is a nonrecoverable error. |
| .SS The severity argument |
| The |
| .I severity |
| argument can take one of the following values: |
| .TP 12n |
| .B MM_NOSEV |
| No severity is printed. |
| .TP |
| .B MM_HALT |
| This value is printed as HALT. |
| .TP |
| .B MM_ERROR |
| This value is printed as ERROR. |
| .TP |
| .B MM_WARNING |
| This value is printed as WARNING. |
| .TP |
| .B MM_INFO |
| This value is printed as INFO. |
| .PP |
| The numeric values are between 0 and 4. |
| Using |
| .BR addseverity (3) |
| or the environment variable |
| .B SEV_LEVEL |
| you can add more levels and strings to print. |
| .SH RETURN VALUE |
| The function can return 4 values: |
| .TP 12n |
| .B MM_OK |
| Everything went smooth. |
| .TP |
| .B MM_NOTOK |
| Complete failure. |
| .TP |
| .B MM_NOMSG |
| Error writing to |
| .IR stderr . |
| .TP |
| .B MM_NOCON |
| Error writing to the console. |
| .SH ENVIRONMENT |
| The environment variable |
| .B MSGVERB |
| ("message verbosity") can be used to suppress parts of |
| the output to |
| .IR stderr . |
| (It does not influence output to the console.) |
| When this variable is defined, is non-NULL, and is a colon-separated |
| list of valid keywords, then only the parts of the message corresponding |
| to these keywords is printed. |
| Valid keywords are "label", "severity", "text", "action" and "tag". |
| .PP |
| The environment variable |
| .B SEV_LEVEL |
| can be used to introduce new severity levels. |
| By default, only the five severity levels described |
| above are available. |
| Any other numeric value would make |
| .BR fmtmsg () |
| print nothing. |
| If the user puts |
| .B SEV_LEVEL |
| with a format like |
| .PP |
| .RS |
| SEV_LEVEL=[description[:description[:...]]] |
| .RE |
| .PP |
| in the environment of the process before the first call to |
| .BR fmtmsg (), |
| where each description is of the form |
| .PP |
| .RS |
| severity-keyword,level,printstring |
| .RE |
| .PP |
| then |
| .BR fmtmsg () |
| will also accept the indicated values for the level (in addition to |
| the standard levels 0\(en4), and use the indicated printstring when |
| such a level occurs. |
| .PP |
| The severity-keyword part is not used by |
| .BR fmtmsg () |
| but it has to be present. |
| The level part is a string representation of a number. |
| The numeric value must be a number greater than 4. |
| This value must be used in the severity argument of |
| .BR fmtmsg () |
| to select this class. |
| It is not possible to overwrite |
| any of the predefined classes. |
| The printstring |
| is the string printed when a message of this class is processed by |
| .BR fmtmsg (). |
| .SH VERSIONS |
| .BR fmtmsg () |
| is provided in glibc since version 2.1. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lb lb lbw23 |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR fmtmsg () |
| T} Thread safety T{ |
| glibc >= 2.16: MT-Safe |
| .br |
| glibc < 2.16: MT-Unsafe |
| T} |
| .TE |
| .PP |
| Before glibc 2.16, the |
| .BR fmtmsg () |
| function uses a static variable that is not protected, |
| so it is not thread-safe. |
| .PP |
| Since glibc 2.16, |
| .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94 |
| the |
| .BR fmtmsg () |
| function uses a lock to protect the static variable, so it is thread-safe. |
| .SH CONFORMING TO |
| The functions |
| .BR fmtmsg () |
| and |
| .BR addseverity (3), |
| and environment variables |
| .B MSGVERB |
| and |
| .B SEV_LEVEL |
| come from System V. |
| .PP |
| The function |
| .BR fmtmsg () |
| and the environment variable |
| .B MSGVERB |
| are described in POSIX.1-2001 and POSIX.1-2008. |
| .SH NOTES |
| System V and UnixWare man pages tell us that these functions |
| have been replaced by "pfmt() and addsev()" or by "pfmt(), |
| vpfmt(), lfmt(), and vlfmt()", and will be removed later. |
| .SH EXAMPLES |
| .EX |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <fmtmsg.h> |
| |
| int |
| main(void) |
| { |
| long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; |
| int err; |
| |
| err = fmtmsg(class, "util\-linux:mount", MM_ERROR, |
| "unknown mount option", "See mount(8).", |
| "util\-linux:mount:017"); |
| switch (err) { |
| case MM_OK: |
| break; |
| case MM_NOTOK: |
| printf("Nothing printed\en"); |
| break; |
| case MM_NOMSG: |
| printf("Nothing printed to stderr\en"); |
| break; |
| case MM_NOCON: |
| printf("No console output\en"); |
| break; |
| default: |
| printf("Unknown error from fmtmsg()\en"); |
| } |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .PP |
| The output should be: |
| .PP |
| .in +4n |
| .EX |
| util\-linux:mount: ERROR: unknown mount option |
| TO FIX: See mount(8). util\-linux:mount:017 |
| .EE |
| .in |
| .PP |
| and after |
| .PP |
| .in +4n |
| .EX |
| MSGVERB=text:action; export MSGVERB |
| .EE |
| .in |
| .PP |
| the output becomes: |
| .PP |
| .in +4n |
| .EX |
| unknown mount option |
| TO FIX: See mount(8). |
| .EE |
| .in |
| .SH SEE ALSO |
| .BR addseverity (3), |
| .BR perror (3) |