diff options
Diffstat (limited to 'man/man3/error.3')
| -rw-r--r-- | man/man3/error.3 | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/man/man3/error.3 b/man/man3/error.3 new file mode 100644 index 000000000..95a964103 --- /dev/null +++ b/man/man3/error.3 @@ -0,0 +1,171 @@ +'\" t +.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com> +.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH error 3 (date) "Linux man-pages (unreleased)" +.SH NAME +error, error_at_line, error_message_count, error_one_per_line, +error_print_progname \- glibc error reporting functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <error.h> +.P +.BI "void error(int " status ", int " errnum ", const char *" format ", ...);" +.BI "void error_at_line(int " status ", int " errnum ", const char *" filename , +.BI " unsigned int " linenum ", const char *" format ", ...);" +.P +.BI "extern unsigned int " error_message_count ; +.BI "extern int " error_one_per_line ; +.P +.BI "extern void (*" error_print_progname ")(void);" +.fi +.SH DESCRIPTION +.BR error () +is a general error-reporting function. +It flushes +.IR stdout , +and then outputs to +.I stderr +the program name, a colon and a space, the message specified by the +.BR printf (3)-style +format string \fIformat\fP, and, if \fIerrnum\fP is +nonzero, a second colon and a space followed by the string given by +.IR strerror(errnum) . +Any arguments required for +.I format +should follow +.I format +in the argument list. +The output is terminated by a newline character. +.P +The program name printed by +.BR error () +is the value of the global variable +.BR program_invocation_name (3). +.I program_invocation_name +initially has the same value as +.IR main ()'s +.IR argv[0] . +The value of this variable can be modified to change the output of +.BR error (). +.P +If \fIstatus\fP has a nonzero value, then +.BR error () +calls +.BR exit (3) +to terminate the program using the given value as the exit status; +otherwise it returns after printing the error message. +.P +The +.BR error_at_line () +function is exactly the same as +.BR error (), +except for the addition of the arguments +.I filename +and +.IR linenum . +The output produced is as for +.BR error (), +except that after the program name are written: a colon, the value of +.IR filename , +a colon, and the value of +.IR linenum . +The preprocessor values \fB__LINE__\fP and +\fB__FILE__\fP may be useful when calling +.BR error_at_line (), +but other values can also be used. +For example, these arguments could refer to a location in an input file. +.P +If the global variable \fIerror_one_per_line\fP is set nonzero, +a sequence of +.BR error_at_line () +calls with the +same value of \fIfilename\fP and \fIlinenum\fP will result in only +one message (the first) being output. +.P +The global variable \fIerror_message_count\fP counts the number of +messages that have been output by +.BR error () +and +.BR error_at_line (). +.P +If the global variable \fIerror_print_progname\fP +is assigned the address of a function +(i.e., is not NULL), then that function is called +instead of prefixing the message with the program name and colon. +The function should print a suitable string to +.IR stderr . +.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 error () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR error_at_line () +T} Thread safety T{ +.na +.nh +MT-Unsafe\ race: error_at_line/\:error_one_per_line locale +T} +.TE +.P +The internal +.I error_one_per_line +variable is accessed (without any form of synchronization, but since it's an +.I int +used once, it should be safe enough) and, if +.I error_one_per_line +is set nonzero, the internal static variables (not exposed to users) +used to hold the last printed filename and line number are accessed +and modified without synchronization; the update is not atomic and it +occurs before disabling cancelation, so it can be interrupted only after +one of the two variables is modified. +After that, +.BR error_at_line () +is very much like +.BR error (). +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR exit (3), +.BR perror (3), +.BR program_invocation_name (3), +.BR strerror (3) |