Manpages - error.3

error, error_at_line, error_message_count, error_one_per_line, error_print_progname - glibc error reporting functions

  #include <error.h>

  void error(int status, int errnum, const char *format, ...);
  void error_at_line(int status, int errnum, const char *filename,
   unsigned int linenum, const char *format, ...);

  extern unsigned int error_message_count;
  extern int error_one_per_line;

  extern void (*error_print_progname)(void);

*error*() is a general error-reporting function. It flushes stdout, and then outputs to stderr the program name, a colon and a space, the message specified by the *printf*(3)-style format string format, and, if errnum is nonzero, a second colon and a space followed by the string given by strerror(errnum). Any arguments required for format should follow format in the argument list. The output is terminated by a newline character.

The program name printed by *error*() is the value of the global variable *program_invocation_name*(3). program_invocation_name initially has the same value as main/()’s /argv[0]. The value of this variable can be modified to change the output of *error*().

If status has a nonzero value, then *error*() calls *exit*(3) to terminate the program using the given value as the exit status; otherwise it returns after printing the error message.

The error_at_line*() function is exactly the same as *error*(), except for the addition of the arguments filename and linenum. The output produced is as for *error*(), except that after the program name are written: a colon, the value of filename, a colon, and the value of linenum. The preprocessor values *__LINE__ and __FILE__ may be useful when calling *error_at_line*(), but other values can also be used. For example, these arguments could refer to a location in an input file.

If the global variable error_one_per_line is set nonzero, a sequence of *error_at_line*() calls with the same value of filename and linenum will result in only one message (the first) being output.

The global variable error_message_count counts the number of messages that have been output by *error*() and *error_at_line*().

If the global variable error_print_progname 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 stderr.

For an explanation of the terms used in this section, see *attributes*(7).

The internal error_one_per_line variable is accessed (without any form of synchronization, but since it’s an int used once, it should be safe enough) and, if 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 cancellation, so it can be interrupted only after one of the two variables is modified. After that, *error_at_line*() is very much like *error*().

These functions and variables are GNU extensions, and should not be used in programs intended to be portable.

*err*(3), *errno*(3), *exit*(3), *perror*(3), *program_invocation_name*(3), *strerror*(3)

This page is part of release 5.13 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.