diff options
Diffstat (limited to 'man/man3/fmtmsg.3')
| -rw-r--r-- | man/man3/fmtmsg.3 | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/man/man3/fmtmsg.3 b/man/man3/fmtmsg.3 new file mode 100644 index 000000000..699db65e7 --- /dev/null +++ b/man/man3/fmtmsg.3 @@ -0,0 +1,337 @@ +'\" 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> +.P +.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. +.P +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. +.P +The +.I text +argument describes the condition of the error. +.P +The +.I action +argument describes possible steps to recover from the error. +If it is printed, it is prefixed by "TO FIX: ". +.P +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. +.P +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. +.P +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. +.P +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. +.P +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. +.P +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". +.P +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 +.P +.RS +SEV_LEVEL=[description[:description[:...]]] +.RE +.P +in the environment of the process before the first call to +.BR fmtmsg (), +where each description is of the form +.P +.RS +severity-keyword,level,printstring +.RE +.P +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. +.P +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). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmtmsg () +T} Thread safety T{ +.na +.nh +glibc\ >=\ 2.16: MT-Safe; +glibc\ <\ 2.16: MT-Unsafe +T} +.TE +.P +Before glibc 2.16, the +.BR fmtmsg () +function uses a static variable that is not protected, +so it is not thread-safe. +.P +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. +.P +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 +.P +The output should be: +.P +.in +4n +.EX +util\-linux:mount: ERROR: unknown mount option +TO FIX: See mount(8). util\-linux:mount:017 +.EE +.in +.P +and after +.P +.in +4n +.EX +MSGVERB=text:action; export MSGVERB +.EE +.in +.P +the output becomes: +.P +.in +4n +.EX +unknown mount option +TO FIX: See mount(8). +.EE +.in +.SH SEE ALSO +.BR addseverity (3), +.BR perror (3) |