Update.

2001-08-16  Ulrich Drepper  <drepper@redhat.com>

	* misc/err.c: Handle wide oriented stderr.

1 files changed, 238 insertions, 4 deletions

diff --git a/manual/errno.texi b/manual/errno.texi
index 5abb823..ee0a621 100644
--- a/manual/errno.texi
+++ b/manual/errno.texi
@@ -1272,7 +1272,8 @@ This function @code{strerror_r} is a GNU extension and it is declared in
 @comment ISO
 @deftypefun void perror (const char *@var{message})
 This function prints an error message to the stream @code{stderr};
-see @ref{Standard Streams}.
+see @ref{Standard Streams}.  The orientation of @code{stderr} is not
+changed.
 
 If you call @code{perror} with a @var{message} that is either a null
 pointer or an empty string, @code{perror} just prints the error message
@@ -1292,9 +1293,8 @@ GNU system, the messages are fairly short; there are no multi-line
 messages or embedded newlines.  Each error message begins with a capital
 letter and does not include any terminating punctuation.
 
-@strong{Compatibility Note:}  The @code{strerror} function is a new
-feature of @w{ISO C}.  Many older C systems do not support this function
-yet.
+@strong{Compatibility Note:} The @code{strerror} function was introduced
+in @w{ISO C89}.  Many older C systems do not support this function yet.
 
 @cindex program name
 @cindex name of running program
@@ -1367,3 +1367,237 @@ open_sesame (char *name)
     return stream;
 @}
 @end smallexample
+
+Using @code{perror} has the advantage that the function is portable and
+available on all systems implementing @w{ISO C}.  But often the text
+@code{perror} generates is not what is wanted and there is no way to
+extend or change what @code{perror} does.  The GNU coding standard, for
+instance, requires error messages to be preceded by the program name and
+programs which read some input files should should provide information
+about the input file name and the line number in case an error is
+encountered while reading the file.  For these occasions there are two
+functions available which are widely used throughout the GNU project.
+These functions are declared in @file{error.h}.
+
+@comment error.h
+@comment GNU
+@deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{})
+The @code{error} function can be used to report general problems during
+program execution.  The @var{format} argument is a format string just
+like those given to the @code{printf} family of functions.  The
+arguments required for the format can follow the @var{format} parameter.
+Just like @code{perror}, @code{error} also can report an error code in
+textual form.  But unlike @code{perror} the error value is explicitly
+passed to the function in the @var{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
+@code{errno} might have a different value.
+
+The @code{error} prints first the program name.  If the application
+defined a global variable @code{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 @code{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
+@var{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
+@var{errnum}.  In any case is the output terminated with a newline.
+
+The output is directed to the @code{stderr} stream.  If the
+@code{stderr} wasn't oriented before the call it will be narrow-oriented
+afterwards.
+
+The function will return unless the @var{status} parameter has a
+non-zero value.  In this case the function will call @code{exit} with
+the @var{status} value for its parameter and therefore never return.  If
+@code{error} returns the global variable @code{error_message_count} is
+incremented by one to keep track of the number of errors reported.
+@end deftypefun
+
+@comment error.h
+@comment GNU
+@deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{})
+
+The @code{error_at_line} function is very similar to the @code{error}
+function.  The only difference are the additional parameters @var{fname}
+and @var{lineno}.  The handling of the other parameters is identical to
+that of @code{error} except that between the program name and the string
+generated by the format string additional text is inserted.
+
+Directly following the program name a colon, followed by the file name
+pointer to by @var{fname}, another colon, and a value of @var{lineno} is
+printed.
+
+This additional output of course is meant to be used to locate an error
+in an input file (like a programming language source code file etc).
+
+If the global variable @code{error_one_per_line} is set to a non-zero
+value @code{error_at_line} will avoid printing consecutive messages for
+the same file anem line.  Repetition which are not directly following
+each other are not caught.
+
+Just like @code{error} this function only returned if @var{status} is
+zero.  Otherwise @code{exit} is called with the non-zero value.  If
+@code{error} returns the global variable @code{error_message_count} is
+incremented by one to keep track of the number of errors reported.
+@end deftypefun
+
+As mentioned above the @code{error} and @code{error_at_line} functions
+can be customized by defining a variable named
+@code{error_print_progname}.
+
+@comment error.h
+@comment GNU
+@deftypevar {void (*} error_print_progname ) (void)
+If the @code{error_print_progname} variable is defined to a non-zero
+value the function pointed to is called by @code{error} or
+@code{error_at_line}.  It is expected to print the program name or do
+something similarly useful.
+
+The function is expected to be print to the @code{stderr} stream and
+must be able to handle whatever orientation the stream has.
+
+The variable is global and shared by all threads.
+@end deftypevar
+
+@comment error.h
+@comment GNU
+@deftypevar {unsigned int} error_message_count
+The @code{error_message_count} variable is incremented whenever one of
+the functions @code{error} or @code{error_at_line} returns.  The
+variable is global and shared by all threads.
+@end deftypevar
+
+@comment error.h
+@comment GNU
+@deftypevar int error_one_per_line
+The @code{error_one_per_line} variable influences only
+@code{error_at_line}.  Normally the @code{error_at_line} function
+creates output for every invocation.  If @code{error_one_per_line} is
+set to a non-zero value @code{error_at_line} keeps track of the last
+file name and line number for which an error was reported and avoid
+directly following messages for the same file and line.  This variable
+is global and shared by all threads.
+@end deftypevar
+
+@noindent
+A program which read some input file and reports errors in it could look
+like this:
+
+@smallexample
+@{
+  char *line = NULL;
+  size_t len = 0;
+  unsigned int lineno = 0;
+
+  error_message_count = 0;
+  while (! feof_unlocked (fp))
+    @{
+      ssize_t n = getline (&line, &len, fp);
+      if (n <= 0)
+        /* @r{End of file or error.}  */
+        break;
+      ++lineno;
+
+      /* @r{Process the line.}  */
+      @dots{}
+
+      if (@r{Detect error in line})
+        error_at_line (0, errval, filename, lineno,
+                       "some error text %s", some_variable);
+    @}
+
+  if (error_message_count != 0)
+    error (EXIT_FAILURE, 0, "%u errors found", error_message_count);
+@}
+@end smallexample
+
+@code{error} and @code{error_at_line} are clearly the functions of
+choice and enable the programmer to write applications which follow the
+GNU coding standard.  The GNU libc additionally contains functions which
+are used in BSD for the same purpose.  These functions are declared in
+@file{err.h}.  It is generally advised to not use these functions.  They
+are included only for compatibility.
+
+@comment err.h
+@comment BSD
+@deftypefun void warn (const char *@var{format}, @dots{})
+The @code{warn} function is roughly equivalent to a call like
+@smallexample
+  error (0, errno, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void vwarn (const char *@var{format}, va_list)
+The @code{vwarn} function is just like @code{warn} except that the
+parameters for the handling of the format string @var{format} are passed
+in as an value of type @code{va_list}.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void warnx (const char *@var{format}, @dots{})
+The @code{warnx} function is roughly equivalent to a call like
+@smallexample
+  error (0, 0, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used.  The difference to @code{warn} is that no error number
+string is printed.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void vwarnx (const char *@var{format}, va_list)
+The @code{vwarnx} function is just like @code{warnx} except that the
+parameters for the handling of the format string @var{format} are passed
+in as an value of type @code{va_list}.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void err (int @var{status}, const char *@var{format}, @dots{})
+The @code{err} function is roughly equivalent to a call like
+@smallexample
+  error (status, errno, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used and that the program is exited even if @var{status} is zero.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void verr (int @var{status}, const char *@var{format}, va_list)
+The @code{verr} function is just like @code{err} except that the
+parameters for the handling of the format string @var{format} are passed
+in as an value of type @code{va_list}.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void errx (int @var{status}, const char *@var{format}, @dots{})
+The @code{errx} function is roughly equivalent to a call like
+@smallexample
+  error (status, 0, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used and that the program is exited even if @var{status}
+is zero.  The difference to @code{err} is that no error number
+string is printed.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void verrx (int @var{status}, const char *@var{format}, va_list)
+The @code{verrx} function is just like @code{errx} except that the
+parameters for the handling of the format string @var{format} are passed
+in as an value of type @code{va_list}.
+@end deftypefun