diff options
Diffstat (limited to 'e2fslib/et/com_err.texinfo')
| -rw-r--r-- | e2fslib/et/com_err.texinfo | 579 |
1 files changed, 0 insertions, 579 deletions
diff --git a/e2fslib/et/com_err.texinfo b/e2fslib/et/com_err.texinfo deleted file mode 100644 index 6ca745d..0000000 --- a/e2fslib/et/com_err.texinfo +++ /dev/null @@ -1,579 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@c $Header: /home/cvs/arcboot/e2fslib/et/com_err.texinfo,v 1.1 2004/11/29 10:39:38 ladis Exp $ -@c $Source: /home/cvs/arcboot/e2fslib/et/com_err.texinfo,v $ -@c $Locker: $ - -@c Note that although this source file is in texinfo format (more -@c or less), it is not yet suitable for turning into an ``info'' -@c file. Sorry, maybe next time. -@c -@c In order to produce hardcopy documentation from a texinfo file, -@c run ``tex com_err.texinfo'' which will load in texinfo.tex, -@c provided in this distribution. (texinfo.tex is from the Free -@c Software Foundation, and is under different copyright restrictions -@c from the rest of this package.) - -@setfilename com_err -@settitle A Common Error Description Library for UNIX - -@ifinfo -@dircategory Development -@format -START-INFO-DIR-ENTRY -* com_err: (com_err.info). A Common Error Description Library for UNIX. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@iftex -@tolerance 10000 - -@c Mutate section headers... -@begingroup - @catcode#=6 - @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}} -@endgroup -@end iftex - -@ifinfo -This file documents the use of the Common Error Description library. - -Copyright (C) 1987, 1988 Student Information Processing Board of the -Massachusetts Institute of Technology. - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, provided -that the above copyright notice appear in all copies and that both that -copyright notice and this permission notice appear in supporting -documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be -used in advertising or publicity pertaining to distribution of the software -without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B. -make no representations about the suitability of this software for any -purpose. It is provided "as is" without express or implied warranty. - -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. - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore - -@setchapternewpage odd - -@titlepage -@center @titlefont{A Common Error Description} -@center @titlefont{Library for UNIX} -@sp 2 -@center Ken Raeburn -@center Bill Sommerfeld -@sp 1 -@center MIT Student Information Processing Board -@sp 3 -@center last updated 1 January 1989 -@center for version 1.2 -@center ***DRAFT COPY ONLY*** - -@vskip 2in - -@center @b{Abstract} - -UNIX has always had a clean and simple system call interface, with a -standard set of error codes passed between the kernel and user -programs. Unfortunately, the same cannot be said of many of the -libraries layered on top of the primitives provided by the kernel. -Typically, each one has used a different style of indicating errors to -their callers, leading to a total hodgepodge of error handling, and -considerable amounts of work for the programmer. This paper describes -a library and associated utilities which allows a more uniform way for -libraries to return errors to their callers, and for programs to -describe errors and exceptional conditions to their users. - -@page -@vskip 0pt plus 1filll - -Copyright @copyright{} 1987, 1988 by the Student Information Processing -Board of the Massachusetts Institute of Technology. - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, provided -that the above copyright notice appear in all copies and that both that -copyright notice and this permission notice appear in supporting -documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be -used in advertising or publicity pertaining to distribution of the software -without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B. -make no representations about the suitability of this software for any -purpose. It is provided "as is" without express or implied warranty. - -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 titlepage - - -@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 -deal with a number of libraries, each of which can use a different -error-reporting mechanism. Sometimes one of two values is returned, -indicating simply SUCCESS or FAILURE, with no description of errors -encountered. Sometimes it is an index into a table of text strings, -where the name of the table used is dependent on the library being -used when the error is generated; since each table starts numbering at -0 or 1, additional information as to the source of the error code is -needed to determine which table to look at. Sometimes no text messages are -supplied at all, and the programmer must supply them at any point at which -he may wish to report error conditions. -Often, a global variable is assigned some value describing the error, but -the programmer has to know in each case whether to look at @code{errno}, -@code{h_errno}, the return value from @code{hes_err()}, or whatever other -variables or routines are specified. -And what happens if something -in the procedure of -examining or reporting the error changes the same variable? - -The package we have developed is an attempt to present a common -error-handling mechanism to manipulate the most common form of error code -in a fashion that does not have the problems listed above. - -A list of up to 256 text messages is supplied to a translator we have -written, along with the three- to four-character ``name'' of the error -table. The library using this error table need only call a routine -generated from this error-table source to make the table ``known'' to the -com_err library, and any error code the library generates can be converted -to the corresponding error message. There is also a default format for -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 -order 24 bits are an identifier of which error table the error code is -from, and the low order 8 bits are a sequential error number within -the table. An error code may thus be easily decomposed into its component -parts. Only the lowest 32 bits of an error code are considered significant -on systems which support wider values. - -Error table 0 is defined to match the UNIX system call error table -(@code{sys_errlist}); this allows @code{errno} values to be used directly -in the library (assuming that @code{errno} is of a type with the same width -as @t{long}). Other error table numbers are formed by compacting together -the first four characters of the error table name. The mapping between -characters in the name and numeric values in the error code are defined in -a system-independent fashion, so that two systems that can pass integral -values between them can reliably pass error codes without loss of meaning; -this should work even if the character sets used are not the same. -(However, if this is to be done, error table 0 should be avoided, since the -local system call error tables may differ.) - -Any variable which is to contain an error code should be declared @t{long}. -The draft proposed American National Standard for C (as of May, 1988) -requires that @t{long} variables be at least 32 bits; any system which does -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, -as - -@example -error_table @var{tablename} -@end example - -Individual error codes are -specified with - -@example -error_code @var{ERROR_NAME}, @var{"text message"} -@end example - -where @samp{ec} can also be used as a short form of @samp{error_code}. To -indicate the end of the table, use @samp{end}. Thus, a (short) sample -error table might be: - -@example - - error_table dsc - - error_code DSC_DUP_MTG_NAME, - "Meeting already exists" - - ec DSC_BAD_PATH, - "A bad meeting pathname was given" - - ec DSC_BAD_MODES, - "Invalid mode for this access control list" - - end - -@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 -argument, the pathname of a file (ending in @samp{.et}, e.g., -@samp{dsc_err.et}) containing an error table source file. It parses the -error table, and generates two output files -- a C header file -(@samp{discuss_err.h}) which contains definitions of the numerical values -of the error codes defined in the error table, and a C source file which -should be compiled and linked with the executable. The header file must be -included in the source of a module which wishes to reference the error -codes defined; the object module generated from the C code may be linked in -to a program which wishes to use the printed forms of the error codes. - -This translator accepts a @kbd{-language @var{lang}} argument, which -determines for which language (or language variant) the output should be -written. At the moment, @var{lang} is currently limited to @kbd{ANSI-C} -and @kbd{K&R-C}, and some abbreviated forms of each. Eventually, this will -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 -com_err package should include the header file @file{<com_err.h>}. It -contains declarations and definitions which may be needed on some systems. -(Some functions cannot be referenced properly without the return type -declarations in this file. Some functions may work properly on most -architectures even without the header file, but relying on this is not -recommended.) - -The run-time support routines and variables provided via this package -include the following: - -@example -void initialize_@var{xxxx}_error_table (void); -@end example - -One of these routines is built by the error compiler for each error table. -It makes the @var{xxxx} error table ``known'' to the error reporting -system. By convention, this routine should be called in the initialization -routine of the @var{xxxx} library. If the library has no initialization -routine, some combination of routines which form the core of the library -should ensure that this routine is called. It is not advised to leave it -the caller to make this call. - -There is no harm in calling this routine more than once. - -@example -#define ERROR_TABLE_BASE_@var{xxxx} @var{nnnnn}L -@end example - -This symbol contains the value of the first error code entry in the -specified table. -This rarely needs be used by the -programmer. - -@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 -if the code is associated with a known error table but the code is not -in the table, a string of the form @samp{Unknown code @var{xxxx nn}} is -returned, where @var{xxxx} is the error table name produced by -reversing the compaction performed on the error table number implied -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. - -@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. - -@end deftypefun - -@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). - -@end deftypefun - -@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}); - -@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 @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 @cite{syslog(3)} -as supplied in BSD 4.3: - -@example -#include <stdio.h> -#include <stdarg.h> -#include <syslog.h> - -/* extern openlog (const char * name, int logopt, int facility); */ -/* extern syslog (int priority, char * message, ...); */ - -void hook (const char * whoami, long code, - const char * format, va_list args) -@{ - char buffer[BUFSIZ]; - static int initialized = 0; - if (!initialized) @{ - openlog (whoami, - LOG_NOWAIT|LOG_CONS|LOG_PID|LOG_NDELAY, - LOG_DAEMON); - initialized = 1; - @} - vsprintf (buffer, format, args); - syslog (LOG_ERR, "%s %s", error_message (code), buffer); -@} -@end example - -After making the call -@code{set_com_err_hook (hook);}, -any calls to @code{com_err} will result in messages being sent to the -@var{syslogd} daemon for logging. -The name of the program, @samp{whoami}, is supplied to the -@samp{openlog()} call, and the message is formatted into a buffer and -passed to @code{syslog}. - -Note that since the extra arguments to @code{com_err} are passed by -reference via the @code{va_list} value @code{args}, the hook routine may -place any form of interpretation on them, including ignoring them. For -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 -to follow when writing robust libraries and programs. Conventions -similar to this are generally followed inside the UNIX kernel and most -routines in the Multics operating system. In general, a routine -either succeeds (returning a zero error code, and doing some side -effects in the process), or it fails, doing minimal side effects; in -any event, any invariant which the library assumes must be maintained. - -In general, it is not in the domain of non user-interface library -routines to write error messages to the user's terminal, or halt the -process. Such forms of ``error handling'' should be reserved for -failures of internal invariants and consistancy checks only, as it -provides the user of the library no way to clean up for himself in the -event of total failure. - -Library routines which can fail should be set up to return an error -code. This should usually be done as the return value of the -function; if this is not acceptable, the routine should return a -``null'' value, and put the error code into a parameter passed by -reference. - -Routines which use the first style of interface can be used from -user-interface levels of a program as follows: - -@example -@{ - if ((code = initialize_world(getuid(), random())) != 0) @{ - com_err("demo", code, - "when trying to initialize world"); - exit(1); - @} - if ((database = open_database("my_secrets", &code))==NULL) @{ - com_err("demo", code, - "while opening my_secrets"); - exit(1); - @} -@} -@end example - -A caller which fails to check the return status is in error. It is -possible to look for code which ignores error returns by using lint; -look for error messages of the form ``foobar returns value which is -sometimes ignored'' or ``foobar returns value which is always -ignored.'' - -Since libraries may be built out of other libraries, it is often necessary -for the success of one routine to depend on another. When a lower level -routine returns an error code, the middle level routine has a few possible -options. It can simply return the error code to its caller after doing -some form of cleanup, it can substitute one of its own, or it can take -corrective action of its own and continue normally. For instance, a -library routine which makes a ``connect'' system call to make a network -connection may reflect the system error code @code{ECONNREFUSED} -(Connection refused) to its caller, or it may return a ``server not -available, try again later,'' or it may try a different server. - -Cleanup which is typically necessary may include, but not be limited -to, freeing allocated memory which will not be needed any more, -unlocking concurrancy locks, dropping reference counts, closing file -descriptors, or otherwise undoing anything which the procedure did up -to this point. When there are a lot of things which can go wrong, it -is generally good to write one block of error-handling code which is -branched to, using a goto, in the event of failure. A common source -of errors in UNIX programs is failing to close file descriptors on -error returns; this leaves a number of ``zombied'' file descriptors -open, which eventually causes the process to run out of file -descriptors and fall over. - -@example -@{ - FILE *f1=NULL, *f2=NULL, *f3=NULL; - int status = 0; - - if ( (f1 = fopen(FILE1, "r")) == NULL) @{ - status = errno; - goto error; - @} - - /* - * Crunch for a while - */ - - if ( (f2 = fopen(FILE2, "w")) == NULL) @{ - status = errno; - goto error; - @} - - if ( (f3 = fopen(FILE3, "a+")) == NULL) @{ - status = errno; - goto error; - @} - - /* - * Do more processing. - */ - fclose(f1); - fclose(f2); - fclose(f3); - return 0; - -error: - if (f1) fclose(f1); - if (f2) fclose(f2); - if (f3) fclose(f3); - return status; -@} -@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 -``tar''-format file available via anonymous FTP from SIPB.MIT.EDU. -Retrieve @samp{pub/com_err.tar.Z} and extract the contents. A subdirectory -@t{profiled} should be created to hold objects compiled for profiling. -Running ``make all'' should then be sufficient to build the library and -error-table compiler. The files @samp{libcom_err.a}, -@samp{libcom_err_p.a}, @samp{com_err.h}, and @samp{compile_et} should be -installed for use; @samp{com_err.3} and @samp{compile_et.1} can also be -installed as manual pages. - -Potential problems: - -@itemize @bullet - -@item Use of @code{strcasecmp}, a routine provided in BSD for -case-insensitive string comparisons. If an equivalent routine is -available, you can modify @code{CFLAGS} in the makefile to define -@code{strcasecmp} to the name of that routine. - -@item Compilers that defined @code{__STDC__} without providing the header -file @code{<stdarg.h>}. One such example is Metaware's High ``C'' -compiler, as provided at Project Athena on the IBM RT/PC workstation; if -@code{__HIGHC__} is defined, it is assumed that @code{<stdarg.h>} is not -available, and therefore @code{<varargs.h>} must be used. If the symbol -@code{VARARGS} is defined (e.g., in the makefile), @code{<varargs.h>} will -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 @cite{perror(3)} which calls -@code{com_err} instead of calling @code{write} directly. - -@end itemize - -As I do not have access to non-BSD systems, there are probably -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 - -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 -documentation, and catching some of the bugs the first time around; -Honeywell Information Systems, for not killing off the @emph{Multics} -operating system before I had an opportunity to use it; Honeywell's -customers, who persuaded them not to do so, for a while; Ted Anderson of -CMU, for catching some problems before version 1.2 left the nest; Stan -Zanarotti and several others of MIT's Student Information Processing Board, -for getting us started with ``discuss,'' for which this package was -originally written; and everyone I've talked into --- I mean, asked to read -this document and the ``man'' pages. - -@bye |