1 \input texinfo @c -*-texinfo-*-
7 @c Note that although this source file is in texinfo format (more
8 @c or less), it is not yet suitable for turning into an ``info''
9 @c file. Sorry, maybe next time.
11 @c In order to produce hardcopy documentation from a texinfo file,
12 @c run ``tex com_err.texinfo'' which will load in texinfo.tex,
13 @c provided in this distribution. (texinfo.tex is from the Free
14 @c Software Foundation, and is under different copyright restrictions
15 @c from the rest of this package.)
18 @settitle A Common Error Description Library for UNIX
21 @dircategory Development
24 * com_err: (com_err.info). A Common Error Description Library for UNIX.
32 @c Mutate section headers...
35 @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}}
40 This file documents the use of the Common Error Description library.
42 Copyright (C) 1987, 1988 Student Information Processing Board of the
43 Massachusetts Institute of Technology.
45 Permission to use, copy, modify, and distribute this software and its
46 documentation for any purpose and without fee is hereby granted, provided
47 that the above copyright notice appear in all copies and that both that
48 copyright notice and this permission notice appear in supporting
49 documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
50 used in advertising or publicity pertaining to distribution of the software
51 without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B.
52 make no representations about the suitability of this software for any
53 purpose. It is provided "as is" without express or implied warranty.
55 Note that the file texinfo.tex, provided with this distribution, is from
56 the Free Software Foundation, and is under different copyright restrictions
57 from the remainder of this package.
60 Permission is granted to process this file through Tex and print the
61 results, provided the printed document carries copying permission
62 notice identical to this one except for the removal of this paragraph
63 (this paragraph not being relevant to the printed manual).
67 @setchapternewpage odd
70 @center @titlefont{A Common Error Description}
71 @center @titlefont{Library for UNIX}
74 @center Bill Sommerfeld
76 @center MIT Student Information Processing Board
78 @center last updated 1 January 1989
79 @center for version 1.2
80 @center ***DRAFT COPY ONLY***
86 UNIX has always had a clean and simple system call interface, with a
87 standard set of error codes passed between the kernel and user
88 programs. Unfortunately, the same cannot be said of many of the
89 libraries layered on top of the primitives provided by the kernel.
90 Typically, each one has used a different style of indicating errors to
91 their callers, leading to a total hodgepodge of error handling, and
92 considerable amounts of work for the programmer. This paper describes
93 a library and associated utilities which allows a more uniform way for
94 libraries to return errors to their callers, and for programs to
95 describe errors and exceptional conditions to their users.
98 @vskip 0pt plus 1filll
100 Copyright @copyright{} 1987, 1988 by the Student Information Processing
101 Board of the Massachusetts Institute of Technology.
103 Permission to use, copy, modify, and distribute this software and its
104 documentation for any purpose and without fee is hereby granted, provided
105 that the above copyright notice appear in all copies and that both that
106 copyright notice and this permission notice appear in supporting
107 documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
108 used in advertising or publicity pertaining to distribution of the software
109 without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B.
110 make no representations about the suitability of this software for any
111 purpose. It is provided "as is" without express or implied warranty.
113 Note that the file texinfo.tex, provided with this distribution, is from
114 the Free Software Foundation, and is under different copyright restrictions
115 from the remainder of this package.
120 @node Top, Why com_err?, (dir), (dir)
122 @top A Common Error Description Library for UNIX
124 This manual documents the com_err library.
129 * Error table source file::
130 * The error-table compiler::
131 * Run-time support routines::
132 * Coding Conventions::
133 * Building and Installation::
142 @node Why com_err?, Error codes, Top, Top
143 @section Why com_err?
145 In building application software packages, a programmer often has to
146 deal with a number of libraries, each of which can use a different
147 error-reporting mechanism. Sometimes one of two values is returned,
148 indicating simply SUCCESS or FAILURE, with no description of errors
149 encountered. Sometimes it is an index into a table of text strings,
150 where the name of the table used is dependent on the library being
151 used when the error is generated; since each table starts numbering at
152 0 or 1, additional information as to the source of the error code is
153 needed to determine which table to look at. Sometimes no text messages are
154 supplied at all, and the programmer must supply them at any point at which
155 he may wish to report error conditions.
156 Often, a global variable is assigned some value describing the error, but
157 the programmer has to know in each case whether to look at @code{errno},
158 @code{h_errno}, the return value from @code{hes_err()}, or whatever other
159 variables or routines are specified.
160 And what happens if something
162 examining or reporting the error changes the same variable?
164 The package we have developed is an attempt to present a common
165 error-handling mechanism to manipulate the most common form of error code
166 in a fashion that does not have the problems listed above.
168 A list of up to 256 text messages is supplied to a translator we have
169 written, along with the three- to four-character ``name'' of the error
170 table. The library using this error table need only call a routine
171 generated from this error-table source to make the table ``known'' to the
172 com_err library, and any error code the library generates can be converted
173 to the corresponding error message. There is also a default format for
174 error codes accidentally returned before making the table known, which is
175 of the form @samp{unknown code foo 32}, where @samp{foo} would be the name
178 @node Error codes, Error table source file, Why com_err?, Top
181 Error codes themselves are 32 bit (signed) integers, of which the high
182 order 24 bits are an identifier of which error table the error code is
183 from, and the low order 8 bits are a sequential error number within
184 the table. An error code may thus be easily decomposed into its component
185 parts. Only the lowest 32 bits of an error code are considered significant
186 on systems which support wider values.
188 Error table 0 is defined to match the UNIX system call error table
189 (@code{sys_errlist}); this allows @code{errno} values to be used directly
190 in the library (assuming that @code{errno} is of a type with the same width
191 as @t{long}). Other error table numbers are formed by compacting together
192 the first four characters of the error table name. The mapping between
193 characters in the name and numeric values in the error code are defined in
194 a system-independent fashion, so that two systems that can pass integral
195 values between them can reliably pass error codes without loss of meaning;
196 this should work even if the character sets used are not the same.
197 (However, if this is to be done, error table 0 should be avoided, since the
198 local system call error tables may differ.)
200 Any variable which is to contain an error code should be declared @t{long}.
201 The draft proposed American National Standard for C (as of May, 1988)
202 requires that @t{long} variables be at least 32 bits; any system which does
203 not support 32-bit @t{long} values cannot make use of this package (nor
204 much other software that assumes an ANSI-C environment base) without
207 @node Error table source file, The error-table compiler, Error codes, Top
208 @section Error table source file
210 The error table source file begins with the declaration of the table name,
214 error_table @var{tablename}
217 Individual error codes are
221 error_code @var{ERROR_NAME}, @var{"text message"}
224 where @samp{ec} can also be used as a short form of @samp{error_code}. To
225 indicate the end of the table, use @samp{end}. Thus, a (short) sample
226 error table might be:
232 error_code DSC_DUP_MTG_NAME,
233 "Meeting already exists"
236 "A bad meeting pathname was given"
239 "Invalid mode for this access control list"
245 @node The error-table compiler, Run-time support routines, Error table source file, Top
246 @section The error-table compiler
248 The error table compiler is named @code{compile_et}. It takes one
249 argument, the pathname of a file (ending in @samp{.et}, e.g.,
250 @samp{dsc_err.et}) containing an error table source file. It parses the
251 error table, and generates two output files -- a C header file
252 (@samp{discuss_err.h}) which contains definitions of the numerical values
253 of the error codes defined in the error table, and a C source file which
254 should be compiled and linked with the executable. The header file must be
255 included in the source of a module which wishes to reference the error
256 codes defined; the object module generated from the C code may be linked in
257 to a program which wishes to use the printed forms of the error codes.
259 This translator accepts a @kbd{-language @var{lang}} argument, which
260 determines for which language (or language variant) the output should be
261 written. At the moment, @var{lang} is currently limited to @kbd{ANSI-C}
262 and @kbd{K&R-C}, and some abbreviated forms of each. Eventually, this will
263 be extended to include some support for C++. The default is currently
264 @kbd{K&R-C}, though the generated sources will have ANSI-C code
265 conditionalized on the symbol @t{__STDC__}.
267 @node Run-time support routines, Coding Conventions, The error-table compiler, Top
268 @section Run-time support routines
270 Any source file which uses the routines supplied with or produced by the
271 com_err package should include the header file @file{<com_err.h>}. It
272 contains declarations and definitions which may be needed on some systems.
273 (Some functions cannot be referenced properly without the return type
274 declarations in this file. Some functions may work properly on most
275 architectures even without the header file, but relying on this is not
278 The run-time support routines and variables provided via this package
279 include the following:
282 void initialize_@var{xxxx}_error_table (void);
285 One of these routines is built by the error compiler for each error table.
286 It makes the @var{xxxx} error table ``known'' to the error reporting
287 system. By convention, this routine should be called in the initialization
288 routine of the @var{xxxx} library. If the library has no initialization
289 routine, some combination of routines which form the core of the library
290 should ensure that this routine is called. It is not advised to leave it
291 the caller to make this call.
293 There is no harm in calling this routine more than once.
296 #define ERROR_TABLE_BASE_@var{xxxx} @var{nnnnn}L
299 This symbol contains the value of the first error code entry in the
301 This rarely needs be used by the
304 @deftypefun const char *error_message (long @var{code});
306 This routine returns the character string error message associated
307 with @code{code}; if this is associated with an unknown error table, or
308 if the code is associated with a known error table but the code is not
309 in the table, a string of the form @samp{Unknown code @var{xxxx nn}} is
310 returned, where @var{xxxx} is the error table name produced by
311 reversing the compaction performed on the error table number implied
312 by that error code, and @var{nn} is the offset from that base value.
314 Although this routine is available for use when needed, its use should be
315 left to circumstances which render @code{com_err} (below) unusable.
320 void com_err (const char *@var{whoami}, long @var{error_code},
321 const char *@var{format}, ...);
323 This routine provides an alternate way to print error messages to
324 standard error; it allows the error message to be passed in as a
325 parameter, rather than in an external variable. @emph{Provide grammatical
326 context for ``message.''}
328 The module reporting the error should be passed in via @var{whoami}.
329 If @var{format} is @code{(char *)NULL}, the formatted message will not be
330 printed. @var{format} may not be omitted.
335 void com_err_va (const char *@var{whoami}, long @var{error_code}, const char *@var{format}, va_list @var{args});
337 This routine provides an interface, equivalent to @code{com_err} above,
338 which may be used by higher-level variadic functions (functions which
339 accept variable numbers of arguments).
343 @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});
345 @deftypefunx void reset_com_err_hook ();
347 These two routines allow a routine to be dynamically substituted for
348 @samp{com_err}. After @samp{set_com_err_hook} has been called,
349 calls to @samp{com_err} will turn into calls to the new hook routine.
350 @samp{reset_com_err_hook} turns off this hook. This may intended to
351 be used in daemons (to use a routine which calls @cite{syslog(3)}), or
352 in a window system application (which could pop up a dialogue box).
354 If a program is to be used in an environment in which simply printing
355 messages to the @code{stderr} stream would be inappropriate (such as in a
356 daemon program which runs without a terminal attached),
357 @code{set_com_err_hook} may be used to redirect output from @code{com_err}.
358 The following is an example of an error handler which uses @cite{syslog(3)}
359 as supplied in BSD 4.3:
366 /* extern openlog (const char * name, int logopt, int facility); */
367 /* extern syslog (int priority, char * message, ...); */
369 void hook (const char * whoami, long code,
370 const char * format, va_list args)
373 static int initialized = 0;
376 LOG_NOWAIT|LOG_CONS|LOG_PID|LOG_NDELAY,
380 vsprintf (buffer, format, args);
381 syslog (LOG_ERR, "%s %s", error_message (code), buffer);
385 After making the call
386 @code{set_com_err_hook (hook);},
387 any calls to @code{com_err} will result in messages being sent to the
388 @var{syslogd} daemon for logging.
389 The name of the program, @samp{whoami}, is supplied to the
390 @samp{openlog()} call, and the message is formatted into a buffer and
391 passed to @code{syslog}.
393 Note that since the extra arguments to @code{com_err} are passed by
394 reference via the @code{va_list} value @code{args}, the hook routine may
395 place any form of interpretation on them, including ignoring them. For
396 consistency, @code{printf}-style interpretation is suggested, via
397 @code{vsprintf} (or @code{_doprnt} on BSD systems without full support for
402 @node Coding Conventions, Building and Installation, Run-time support routines, Top
403 @section Coding Conventions
405 The following conventions are just some general stylistic conventions
406 to follow when writing robust libraries and programs. Conventions
407 similar to this are generally followed inside the UNIX kernel and most
408 routines in the Multics operating system. In general, a routine
409 either succeeds (returning a zero error code, and doing some side
410 effects in the process), or it fails, doing minimal side effects; in
411 any event, any invariant which the library assumes must be maintained.
413 In general, it is not in the domain of non user-interface library
414 routines to write error messages to the user's terminal, or halt the
415 process. Such forms of ``error handling'' should be reserved for
416 failures of internal invariants and consistancy checks only, as it
417 provides the user of the library no way to clean up for himself in the
418 event of total failure.
420 Library routines which can fail should be set up to return an error
421 code. This should usually be done as the return value of the
422 function; if this is not acceptable, the routine should return a
423 ``null'' value, and put the error code into a parameter passed by
426 Routines which use the first style of interface can be used from
427 user-interface levels of a program as follows:
431 if ((code = initialize_world(getuid(), random())) != 0) @{
432 com_err("demo", code,
433 "when trying to initialize world");
436 if ((database = open_database("my_secrets", &code))==NULL) @{
437 com_err("demo", code,
438 "while opening my_secrets");
444 A caller which fails to check the return status is in error. It is
445 possible to look for code which ignores error returns by using lint;
446 look for error messages of the form ``foobar returns value which is
447 sometimes ignored'' or ``foobar returns value which is always
450 Since libraries may be built out of other libraries, it is often necessary
451 for the success of one routine to depend on another. When a lower level
452 routine returns an error code, the middle level routine has a few possible
453 options. It can simply return the error code to its caller after doing
454 some form of cleanup, it can substitute one of its own, or it can take
455 corrective action of its own and continue normally. For instance, a
456 library routine which makes a ``connect'' system call to make a network
457 connection may reflect the system error code @code{ECONNREFUSED}
458 (Connection refused) to its caller, or it may return a ``server not
459 available, try again later,'' or it may try a different server.
461 Cleanup which is typically necessary may include, but not be limited
462 to, freeing allocated memory which will not be needed any more,
463 unlocking concurrancy locks, dropping reference counts, closing file
464 descriptors, or otherwise undoing anything which the procedure did up
465 to this point. When there are a lot of things which can go wrong, it
466 is generally good to write one block of error-handling code which is
467 branched to, using a goto, in the event of failure. A common source
468 of errors in UNIX programs is failing to close file descriptors on
469 error returns; this leaves a number of ``zombied'' file descriptors
470 open, which eventually causes the process to run out of file
471 descriptors and fall over.
475 FILE *f1=NULL, *f2=NULL, *f3=NULL;
478 if ( (f1 = fopen(FILE1, "r")) == NULL) @{
487 if ( (f2 = fopen(FILE2, "w")) == NULL) @{
492 if ( (f3 = fopen(FILE3, "a+")) == NULL) @{
498 * Do more processing.
513 @node Building and Installation, Bug Reports, Coding Conventions, Top
514 @section Building and Installation
516 The distribution of this package will probably be done as a compressed
517 ``tar''-format file available via anonymous FTP from SIPB.MIT.EDU.
518 Retrieve @samp{pub/com_err.tar.Z} and extract the contents. A subdirectory
519 @t{profiled} should be created to hold objects compiled for profiling.
520 Running ``make all'' should then be sufficient to build the library and
521 error-table compiler. The files @samp{libcom_err.a},
522 @samp{libcom_err_p.a}, @samp{com_err.h}, and @samp{compile_et} should be
523 installed for use; @samp{com_err.3} and @samp{compile_et.1} can also be
524 installed as manual pages.
530 @item Use of @code{strcasecmp}, a routine provided in BSD for
531 case-insensitive string comparisons. If an equivalent routine is
532 available, you can modify @code{CFLAGS} in the makefile to define
533 @code{strcasecmp} to the name of that routine.
535 @item Compilers that defined @code{__STDC__} without providing the header
536 file @code{<stdarg.h>}. One such example is Metaware's High ``C''
537 compiler, as provided at Project Athena on the IBM RT/PC workstation; if
538 @code{__HIGHC__} is defined, it is assumed that @code{<stdarg.h>} is not
539 available, and therefore @code{<varargs.h>} must be used. If the symbol
540 @code{VARARGS} is defined (e.g., in the makefile), @code{<varargs.h>} will
543 @item If your linker rejects symbols that are simultaneously defined in two
544 library files, edit @samp{Makefile} to remove @samp{perror.c} from the
545 library. This file contains a version of @cite{perror(3)} which calls
546 @code{com_err} instead of calling @code{write} directly.
550 As I do not have access to non-BSD systems, there are probably
551 bugs present that may interfere with building or using this package on
552 other systems. If they are reported to me, they can probably be fixed for
555 @node Bug Reports, Acknowledgements, Building and Installation, Top
558 The principal author of this library is: Ken
559 Raeburn, @t{raeburn@@MIT.EDU}.
561 This version of the com_err library is being maintained by Theodore
562 Ts'o, and so bugs and comments should be sent to @t{tytso@@thunk.org}.
565 @node Acknowledgements, , Bug Reports, Top
566 @section Acknowledgements
568 I would like to thank: Bill Sommerfeld, for his help with some of this
569 documentation, and catching some of the bugs the first time around;
570 Honeywell Information Systems, for not killing off the @emph{Multics}
571 operating system before I had an opportunity to use it; Honeywell's
572 customers, who persuaded them not to do so, for a while; Ted Anderson of
573 CMU, for catching some problems before version 1.2 left the nest; Stan
574 Zanarotti and several others of MIT's Student Information Processing Board,
575 for getting us started with ``discuss,'' for which this package was
576 originally written; and everyone I've talked into --- I mean, asked to read
577 this document and the ``man'' pages.