Re: [bug-gnulib] standards.texi error function

[Paul Eggert]

Richard Stallman <address@hidden> writes:

>     puts "gl_ERROR" into configure.in, and (if necessary) adjusts one's
>     usage of "error" to match the glibc API.
>
> The glibc API for what?  What does this API look like?

Here is the API, taken from the glibc manual.  The function is
declared in <error.h>.

 - Function: void error (int STATUS, int ERRNUM, const char *FORMAT,
          ...)
     The `error' function can be used to report general problems during
     program execution.  The FORMAT argument is a format string just
     like those given to the `printf' family of functions.  The
     arguments required for the format can follow the FORMAT parameter.
     Just like `perror', `error' also can report an error code in
     textual form.  But unlike `perror' the error value is explicitly
     passed to the function in the ERRNUM parameter.  This elimintates
     the problem mentioned above that the error reporting function must
     be called immediately after the function causing the error since
     otherwise `errno' might have a different value.

     The `error' prints first the program name.  If the application
     defined a global variable `error_print_progname' and points it to a
     function this function will be called to print the program name.
     Otherwise the string from the global variable `program_name' is
     used.  The program name is followed by a colon and a space which
     in turn is followed by the output produced by the format string.
     If the ERRNUM parameter is non-zero the format string output is
     followed by a colon and a space, followed by the error message for
     the error code ERRNUM.  In any case is the output terminated with
     a newline.

     The output is directed to the `stderr' stream.  If the `stderr'
     wasn't oriented before the call it will be narrow-oriented
     afterwards.

     The function will return unless the STATUS parameter has a
     non-zero value.  In this case the function will call `exit' with
     the STATUS value for its parameter and therefore never return.  If
     `error' returns the global variable `error_message_count' is
     incremented by one to keep track of the number of errors reported.