diff options
Diffstat (limited to 'man3/fmtmsg.3')
| -rw-r--r-- | man3/fmtmsg.3 | 338 |
1 files changed, 0 insertions, 338 deletions
diff --git a/man3/fmtmsg.3 b/man3/fmtmsg.3 deleted file mode 100644 index b2da3085c..000000000 --- a/man3/fmtmsg.3 +++ /dev/null @@ -1,338 +0,0 @@ -'\" t -.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) -.\" -.\" SPDX-License-Identifier: GPL-1.0-or-later -.\" -.\" 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 (date) "Linux man-pages (unreleased)" -.SH NAME -fmtmsg \- print formatted error messages -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.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\[en]4), 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 ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.ad l -.nh -.TS -allbox; -lb lb lbx -l l l. -Interface Attribute Value -T{ -.BR fmtmsg () -T} Thread safety T{ -glibc\ >=\ 2.16: MT-Safe; -glibc\ <\ 2.16: MT-Unsafe -T} -.TE -.hy -.ad -.sp 1 -.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 STANDARDS -.TP -.BR fmtmsg () -.TQ -.B MSGVERB -POSIX.1-2008. -.SH HISTORY -.TP -.BR fmtmsg () -System V. -POSIX.1-2001 and POSIX.1-2008. -glibc 2.1. -.TP -.B MSGVERB -System V. -POSIX.1-2001 and POSIX.1-2008. -.TP -.B SEV_LEVEL -System V. -.PP -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 -.\" SRC BEGIN (fmtmsg.c) -.EX -#include <fmtmsg.h> -#include <stdio.h> -#include <stdlib.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 -.\" SRC END -.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) |