diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/et/ChangeLog | 7 | ||||
| -rw-r--r-- | lib/et/com_err.texinfo | 84 |
2 files changed, 59 insertions, 32 deletions
diff --git a/lib/et/ChangeLog b/lib/et/ChangeLog index 28d66500..c1104a3c 100644 --- a/lib/et/ChangeLog +++ b/lib/et/ChangeLog @@ -1,3 +1,10 @@ +2001-09-10 Theodore Tso <tytso@valinux.com> + + * com_err.texinfo: Add appropriate @node and @menu lines so that + the a valid .info file can be made. Use @deftypefun to + define functions. Change the e-mail address where bug + reports to be sent to be is the e2fsprogs maintainer. + 2001-09-02 Theodore Tso <tytso@thunk.org> * Release of E2fsprogs 1.24a diff --git a/lib/et/com_err.texinfo b/lib/et/com_err.texinfo index 2f4b2661..3914b095 100644 --- a/lib/et/com_err.texinfo +++ b/lib/et/com_err.texinfo @@ -51,8 +51,6 @@ Note that the file texinfo.tex, provided with this distribution, is from the Free Software Foundation, and is under different copyright restrictions from the remainder of this package. -@end ifinfo - @ignore Permission is granted to process this file through Tex and print the results, provided the printed document carries copying permission @@ -113,12 +111,30 @@ from the remainder of this package. @end titlepage -@ifinfo -@c should put a menu here someday.... + +@node Top, Why com_err?, (dir), (dir) + +@top A Common Error Description Library for UNIX + +This manual documents the com_err library. + +@menu +* Why com_err?:: +* Error codes:: +* Error table source file:: +* The error-table compiler:: +* Run-time support routines:: +* Coding Conventions:: +* Building and Installation:: +* Bug Reports:: +* Acknowledgements:: +@end menu + @end ifinfo @page +@node Why com_err?, Error codes, Top, Top @section Why com_err? In building application software packages, a programmer often has to @@ -154,6 +170,7 @@ error codes accidentally returned before making the table known, which is of the form @samp{unknown code foo 32}, where @samp{foo} would be the name of the table. +@node Error codes, Error table source file, Why com_err?, Top @section Error codes Error codes themselves are 32 bit (signed) integers, of which the high @@ -182,6 +199,7 @@ not support 32-bit @t{long} values cannot make use of this package (nor much other software that assumes an ANSI-C environment base) without significant effort. +@node Error table source file, The error-table compiler, Error codes, Top @section Error table source file The error table source file begins with the declaration of the table name, @@ -219,6 +237,7 @@ error table might be: @end example +@node The error-table compiler, Run-time support routines, Error table source file, Top @section The error-table compiler The error table compiler is named @code{compile_et}. It takes one @@ -240,6 +259,7 @@ be extended to include some support for C++. The default is currently @kbd{K&R-C}, though the generated sources will have ANSI-C code conditionalized on the symbol @t{__STDC__}. +@node Run-time support routines, Coding Conventions, The error-table compiler, Top @section Run-time support routines Any source file which uses the routines supplied with or produced by the @@ -276,9 +296,7 @@ specified table. This rarely needs be used by the programmer. -@example -const char *error_message (long code); -@end example +@deftypefun const char *error_message (long @var{code}); This routine returns the character string error message associated with @code{code}; if this is associated with an unknown error table, or @@ -291,56 +309,48 @@ by that error code, and @var{nn} is the offset from that base value. Although this routine is available for use when needed, its use should be left to circumstances which render @code{com_err} (below) unusable. -@example -void com_err (const char *whoami, /* module reporting error */ - long code, /* error code */ - const char *format, /* format for additional detail */ - ...); /* (extra parameters) */ -@end example +@end deftypefun + +@deftypefun +void com_err (const char *@var{whoami}, long @var{error_code}, + const char *@var{format}, ...); This routine provides an alternate way to print error messages to standard error; it allows the error message to be passed in as a parameter, rather than in an external variable. @emph{Provide grammatical context for ``message.''} +The module reporting the error should be passed in via @var{whoami}. If @var{format} is @code{(char *)NULL}, the formatted message will not be printed. @var{format} may not be omitted. -@example -#include <stdarg.h> +@end deftypefun -void com_err_va (const char *whoami, - long code, - const char *format, - va_list args); -@end example +@deftypefun +void com_err_va (const char *@var{whoami}, long @var{error_code}, const char *@var{format}, va_list @var{args}); This routine provides an interface, equivalent to @code{com_err} above, which may be used by higher-level variadic functions (functions which accept variable numbers of arguments). -@example -#include <stdarg.h> +@end deftypefun -void (*set_com_err_hook (void (*proc) ())) (); +@deftypefun void (*set_com_err_hook (void (*@var{proc}) (const char *@var{whoami}, long @var{error_code}, va_list @var{args}))) (const char *@var{whoami}, long @var{error_code}, va_list @var{args}); -void (*@var{proc}) (const char *whoami, long code, va_list args); - -void reset_com_err_hook (); -@end example +@deftypefunx void reset_com_err_hook (); These two routines allow a routine to be dynamically substituted for @samp{com_err}. After @samp{set_com_err_hook} has been called, calls to @samp{com_err} will turn into calls to the new hook routine. @samp{reset_com_err_hook} turns off this hook. This may intended to -be used in daemons (to use a routine which calls @var{syslog(3)}), or +be used in daemons (to use a routine which calls @cite{syslog(3)}), or in a window system application (which could pop up a dialogue box). If a program is to be used in an environment in which simply printing messages to the @code{stderr} stream would be inappropriate (such as in a daemon program which runs without a terminal attached), @code{set_com_err_hook} may be used to redirect output from @code{com_err}. -The following is an example of an error handler which uses @var{syslog(3)} +The following is an example of an error handler which uses @cite{syslog(3)} as supplied in BSD 4.3: @example @@ -382,6 +392,9 @@ consistency, @code{printf}-style interpretation is suggested, via @code{vsprintf} (or @code{_doprnt} on BSD systems without full support for the ANSI C library). +@end deftypefun + +@node Coding Conventions, Building and Installation, Run-time support routines, Top @section Coding Conventions The following conventions are just some general stylistic conventions @@ -492,6 +505,7 @@ error: @} @end example +@node Building and Installation, Bug Reports, Coding Conventions, Top @section Building and Installation The distribution of this package will probably be done as a compressed @@ -523,7 +537,7 @@ be used. @item If your linker rejects symbols that are simultaneously defined in two library files, edit @samp{Makefile} to remove @samp{perror.c} from the -library. This file contains a version of @var{perror(3)} which calls +library. This file contains a version of @cite{perror(3)} which calls @code{com_err} instead of calling @code{write} directly. @end itemize @@ -533,11 +547,17 @@ bugs present that may interfere with building or using this package on other systems. If they are reported to me, they can probably be fixed for the next version. +@node Bug Reports, Acknowledgements, Building and Installation, Top @section Bug Reports -Please send any comments or bug reports to the principal author: Ken -Raeburn, @t{Raeburn@@Athena.MIT.EDU}. +The principal author of this library is: Ken +Raeburn, @t{raeburn@@MIT.EDU}. + +This version of the com_err library is being maintained by Theodore +Ts'o, and so bugs and comments should be sent to @t{tytso@@thunk.org}. + +@node Acknowledgements, , Bug Reports, Top @section Acknowledgements I would like to thank: Bill Sommerfeld, for his help with some of this |