com_err.texinfo revision 22176
15622Swollman\input texinfo @c -*-texinfo-*- 25622Swollman 322176Sjoerg@c $Header: /home/ncvs/src/lib/libcom_err/doc/com_err.texinfo,v 1.1.1.1 1995/01/14 22:23:41 wollman Exp $ 422176Sjoerg@c $Source: /home/ncvs/src/lib/libcom_err/doc/com_err.texinfo,v $ 55622Swollman 65622Swollman@c Note that although this source file is in texinfo format (more 75622Swollman@c or less), it is not yet suitable for turning into an ``info'' 85622Swollman@c file. Sorry, maybe next time. 95622Swollman@c 105622Swollman@c In order to produce hardcopy documentation from a texinfo file, 115622Swollman@c run ``tex com_err.texinfo'' which will load in texinfo.tex, 125622Swollman@c provided in this distribution. (texinfo.tex is from the Free 135622Swollman@c Software Foundation, and is under different copyright restrictions 145622Swollman@c from the rest of this package.) 155622Swollman 165622Swollman@ifinfo 175622Swollman@barfo 185622Swollman@end ifinfo 195622Swollman 205622Swollman@iftex 215622Swollman@tolerance 10000 225622Swollman 235622Swollman@c Mutate section headers... 245622Swollman@begingroup 255622Swollman @catcode#=6 265622Swollman @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}} 275622Swollman@endgroup 285622Swollman@end iftex 295622Swollman 3022176Sjoerg@c %**start of header (This is for running Texinfo on a region.) 315622Swollman@setfilename com_err 325622Swollman@settitle A Common Error Description Library for UNIX 3322176Sjoerg@c %**end of header (This is for running Texinfo on a region.) 345622Swollman 355622Swollman@ifinfo 365622SwollmanThis file documents the use of the Common Error Description library. 375622Swollman 385622SwollmanCopyright (C) 1987, 1988 Student Information Processing Board of the 395622SwollmanMassachusetts Institute of Technology. 405622Swollman 415622SwollmanPermission to use, copy, modify, and distribute this software and its 425622Swollmandocumentation for any purpose and without fee is hereby granted, provided 435622Swollmanthat the above copyright notice appear in all copies and that both that 445622Swollmancopyright notice and this permission notice appear in supporting 455622Swollmandocumentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 465622Swollmanused in advertising or publicity pertaining to distribution of the software 475622Swollmanwithout specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B. 485622Swollmanmake no representations about the suitability of this software for any 495622Swollmanpurpose. It is provided "as is" without express or implied warranty. 505622Swollman 515622SwollmanNote that the file texinfo.tex, provided with this distribution, is from 525622Swollmanthe Free Software Foundation, and is under different copyright restrictions 535622Swollmanfrom the remainder of this package. 545622Swollman 555622Swollman@end ifinfo 565622Swollman 575622Swollman@ignore 585622SwollmanPermission is granted to process this file through Tex and print the 595622Swollmanresults, provided the printed document carries copying permission 605622Swollmannotice identical to this one except for the removal of this paragraph 615622Swollman(this paragraph not being relevant to the printed manual). 625622Swollman 635622Swollman@end ignore 645622Swollman 655622Swollman@setchapternewpage odd 665622Swollman 675622Swollman@titlepage 685622Swollman@center @titlefont{A Common Error Description} 695622Swollman@center @titlefont{Library for UNIX} 705622Swollman@sp 2 715622Swollman@center Ken Raeburn 725622Swollman@center Bill Sommerfeld 735622Swollman@sp 1 745622Swollman@center MIT Student Information Processing Board 755622Swollman@sp 3 765622Swollman@center last updated 1 January 1989 775622Swollman@center for version 1.2 785622Swollman@center ***DRAFT COPY ONLY*** 795622Swollman 805622Swollman@vskip 2in 815622Swollman 825622Swollman@center @b{Abstract} 835622Swollman 845622SwollmanUNIX has always had a clean and simple system call interface, with a 855622Swollmanstandard set of error codes passed between the kernel and user 865622Swollmanprograms. Unfortunately, the same cannot be said of many of the 875622Swollmanlibraries layered on top of the primitives provided by the kernel. 885622SwollmanTypically, each one has used a different style of indicating errors to 895622Swollmantheir callers, leading to a total hodgepodge of error handling, and 905622Swollmanconsiderable amounts of work for the programmer. This paper describes 915622Swollmana library and associated utilities which allows a more uniform way for 925622Swollmanlibraries to return errors to their callers, and for programs to 935622Swollmandescribe errors and exceptional conditions to their users. 945622Swollman 955622Swollman@page 965622Swollman@vskip 0pt plus 1filll 975622Swollman 985622SwollmanCopyright @copyright{} 1987, 1988 by the Student Information Processing 995622SwollmanBoard of the Massachusetts Institute of Technology. 1005622Swollman 1015622SwollmanPermission to use, copy, modify, and distribute this software and its 1025622Swollmandocumentation for any purpose and without fee is hereby granted, provided 1035622Swollmanthat the above copyright notice appear in all copies and that both that 1045622Swollmancopyright notice and this permission notice appear in supporting 1055622Swollmandocumentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 1065622Swollmanused in advertising or publicity pertaining to distribution of the software 1075622Swollmanwithout specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B. 1085622Swollmanmake no representations about the suitability of this software for any 1095622Swollmanpurpose. It is provided "as is" without express or implied warranty. 1105622Swollman 1115622SwollmanNote that the file texinfo.tex, provided with this distribution, is from 1125622Swollmanthe Free Software Foundation, and is under different copyright restrictions 1135622Swollmanfrom the remainder of this package. 1145622Swollman 1155622Swollman@end titlepage 1165622Swollman 1175622Swollman@ifinfo 11822176Sjoerg@node Top, Why com_err?, (dir), (dir) 11922176Sjoerg@comment node-name, next, previous, up 12022176Sjoerg@top General Introduction 12122176Sjoerg 12222176Sjoerg@menu 12322176Sjoerg* Why com_err?:: What is all this for? 12422176Sjoerg* Error codes:: What's an error code, anyway? 12522176Sjoerg* Error table source file:: How to describe an error table. 12622176Sjoerg* The error-table compiler:: How to compile the table. 12722176Sjoerg* Run-time support routines:: How to use from within your program. 12822176Sjoerg* Coding Conventions:: Stylistic issues. 12922176Sjoerg* Building and Installation:: How to build and install. 13022176Sjoerg* Bug Reports:: You have found a bug? Report it. 13122176Sjoerg* Acknowledgements:: Whom to thank... 13222176Sjoerg 13322176Sjoerg@end menu 13422176Sjoerg 1355622Swollman@end ifinfo 1365622Swollman 1375622Swollman@page 1385622Swollman 13922176Sjoerg@ifinfo 14022176Sjoerg@node Why com_err?, Error codes, Top, (dir) 14122176Sjoerg@comment node-name, next, previous, up 14222176Sjoerg@end ifinfo 14322176Sjoerg 1445622Swollman@section Why com_err? 1455622Swollman 1465622SwollmanIn building application software packages, a programmer often has to 1475622Swollmandeal with a number of libraries, each of which can use a different 1485622Swollmanerror-reporting mechanism. Sometimes one of two values is returned, 1495622Swollmanindicating simply SUCCESS or FAILURE, with no description of errors 1505622Swollmanencountered. Sometimes it is an index into a table of text strings, 1515622Swollmanwhere the name of the table used is dependent on the library being 1525622Swollmanused when the error is generated; since each table starts numbering at 1535622Swollman0 or 1, additional information as to the source of the error code is 1545622Swollmanneeded to determine which table to look at. Sometimes no text messages are 1555622Swollmansupplied at all, and the programmer must supply them at any point at which 1565622Swollmanhe may wish to report error conditions. 1575622SwollmanOften, a global variable is assigned some value describing the error, but 1585622Swollmanthe programmer has to know in each case whether to look at @code{errno}, 1595622Swollman@code{h_errno}, the return value from @code{hes_err()}, or whatever other 1605622Swollmanvariables or routines are specified. 1615622SwollmanAnd what happens if something 1625622Swollmanin the procedure of 1635622Swollmanexamining or reporting the error changes the same variable? 1645622Swollman 1655622SwollmanThe package we have developed is an attempt to present a common 1665622Swollmanerror-handling mechanism to manipulate the most common form of error code 1675622Swollmanin a fashion that does not have the problems listed above. 1685622Swollman 1695622SwollmanA list of up to 256 text messages is supplied to a translator we have 1705622Swollmanwritten, along with the three- to four-character ``name'' of the error 1715622Swollmantable. The library using this error table need only call a routine 1725622Swollmangenerated from this error-table source to make the table ``known'' to the 1735622Swollmancom_err library, and any error code the library generates can be converted 1745622Swollmanto the corresponding error message. There is also a default format for 1755622Swollmanerror codes accidentally returned before making the table known, which is 1765622Swollmanof the form @samp{unknown code foo 32}, where @samp{foo} would be the name 1775622Swollmanof the table. 1785622Swollman 17922176Sjoerg@ifinfo 18022176Sjoerg@node Error codes, Error table source file, Why com_err?, (dir) 18122176Sjoerg@comment node-name, next, previous, up 18222176Sjoerg@end ifinfo 18322176Sjoerg 1845622Swollman@section Error codes 1855622Swollman 1865622SwollmanError codes themselves are 32 bit (signed) integers, of which the high 1875622Swollmanorder 24 bits are an identifier of which error table the error code is 1885622Swollmanfrom, and the low order 8 bits are a sequential error number within 1895622Swollmanthe table. An error code may thus be easily decomposed into its component 1905622Swollmanparts. Only the lowest 32 bits of an error code are considered significant 1915622Swollmanon systems which support wider values. 1925622Swollman 1935622SwollmanError table 0 is defined to match the UNIX system call error table 1945622Swollman(@code{sys_errlist}); this allows @code{errno} values to be used directly 1955622Swollmanin the library (assuming that @code{errno} is of a type with the same width 1965622Swollmanas @t{long}). Other error table numbers are formed by compacting together 1975622Swollmanthe first four characters of the error table name. The mapping between 1985622Swollmancharacters in the name and numeric values in the error code are defined in 1995622Swollmana system-independent fashion, so that two systems that can pass integral 2005622Swollmanvalues between them can reliably pass error codes without loss of meaning; 2015622Swollmanthis should work even if the character sets used are not the same. 2025622Swollman(However, if this is to be done, error table 0 should be avoided, since the 2035622Swollmanlocal system call error tables may differ.) 2045622Swollman 2055622SwollmanAny variable which is to contain an error code should be declared @t{long}. 2065622SwollmanThe draft proposed American National Standard for C (as of May, 1988) 2075622Swollmanrequires that @t{long} variables be at least 32 bits; any system which does 2085622Swollmannot support 32-bit @t{long} values cannot make use of this package (nor 2095622Swollmanmuch other software that assumes an ANSI-C environment base) without 2105622Swollmansignificant effort. 2115622Swollman 21222176Sjoerg@ifinfo 21322176Sjoerg@node Error table source file, The error-table compiler, Error codes, (dir) 21422176Sjoerg@comment node-name, next, previous, up 21522176Sjoerg@end ifinfo 21622176Sjoerg 2175622Swollman@section Error table source file 2185622Swollman 2195622SwollmanThe error table source file begins with the declaration of the table name, 2205622Swollmanas 2215622Swollman 2225622Swollman@example 2235622Swollmanerror_table @var{tablename} 2245622Swollman@end example 2255622Swollman 2265622SwollmanIndividual error codes are 2275622Swollmanspecified with 2285622Swollman 2295622Swollman@example 2305622Swollmanerror_code @var{ERROR_NAME}, @var{"text message"} 2315622Swollman@end example 2325622Swollman 2335622Swollmanwhere @samp{ec} can also be used as a short form of @samp{error_code}. To 2345622Swollmanindicate the end of the table, use @samp{end}. Thus, a (short) sample 2355622Swollmanerror table might be: 2365622Swollman 2375622Swollman@example 2385622Swollman 2395622Swollman error_table dsc 2405622Swollman 2415622Swollman error_code DSC_DUP_MTG_NAME, 2425622Swollman "Meeting already exists" 2435622Swollman 2445622Swollman ec DSC_BAD_PATH, 2455622Swollman "A bad meeting pathname was given" 2465622Swollman 2475622Swollman ec DSC_BAD_MODES, 2485622Swollman "Invalid mode for this access control list" 2495622Swollman 2505622Swollman end 2515622Swollman 2525622Swollman@end example 2535622Swollman 25422176Sjoerg@ifinfo 25522176Sjoerg@node The error-table compiler, Run-time support routines, Error table source file, (dir) 25622176Sjoerg@comment node-name, next, previous, up 25722176Sjoerg@end ifinfo 25822176Sjoerg 2595622Swollman@section The error-table compiler 2605622Swollman 2615622SwollmanThe error table compiler is named @code{compile_et}. It takes one 2625622Swollmanargument, the pathname of a file (ending in @samp{.et}, e.g., 2635622Swollman@samp{dsc_err.et}) containing an error table source file. It parses the 2645622Swollmanerror table, and generates two output files -- a C header file 2655622Swollman(@samp{discuss_err.h}) which contains definitions of the numerical values 2665622Swollmanof the error codes defined in the error table, and a C source file which 2675622Swollmanshould be compiled and linked with the executable. The header file must be 2685622Swollmanincluded in the source of a module which wishes to reference the error 2695622Swollmancodes defined; the object module generated from the C code may be linked in 2705622Swollmanto a program which wishes to use the printed forms of the error codes. 2715622Swollman 2725622SwollmanThis translator accepts a @kbd{-language @var{lang}} argument, which 2735622Swollmandetermines for which language (or language variant) the output should be 2745622Swollmanwritten. At the moment, @var{lang} is currently limited to @kbd{ANSI-C} 2755622Swollmanand @kbd{K&R-C}, and some abbreviated forms of each. Eventually, this will 2765622Swollmanbe extended to include some support for C++. The default is currently 2775622Swollman@kbd{K&R-C}, though the generated sources will have ANSI-C code 2785622Swollmanconditionalized on the symbol @t{__STDC__}. 2795622Swollman 28022176Sjoerg@ifinfo 28122176Sjoerg@node Run-time support routines, Coding Conventions, The error-table compiler, (dir) 28222176Sjoerg@comment node-name, next, previous, up 28322176Sjoerg@end ifinfo 28422176Sjoerg 2855622Swollman@section Run-time support routines 2865622Swollman 2875622SwollmanAny source file which uses the routines supplied with or produced by the 2885622Swollmancom_err package should include the header file @file{<com_err.h>}. It 2895622Swollmancontains declarations and definitions which may be needed on some systems. 2905622Swollman(Some functions cannot be referenced properly without the return type 2915622Swollmandeclarations in this file. Some functions may work properly on most 2925622Swollmanarchitectures even without the header file, but relying on this is not 2935622Swollmanrecommended.) 2945622Swollman 2955622SwollmanThe run-time support routines and variables provided via this package 2965622Swollmaninclude the following: 2975622Swollman 2985622Swollman@example 2995622Swollmanvoid initialize_@var{xxxx}_error_table (void); 3005622Swollman@end example 3015622Swollman 3025622SwollmanOne of these routines is built by the error compiler for each error table. 3035622SwollmanIt makes the @var{xxxx} error table ``known'' to the error reporting 3045622Swollmansystem. By convention, this routine should be called in the initialization 3055622Swollmanroutine of the @var{xxxx} library. If the library has no initialization 3065622Swollmanroutine, some combination of routines which form the core of the library 3075622Swollmanshould ensure that this routine is called. It is not advised to leave it 3085622Swollmanthe caller to make this call. 3095622Swollman 3105622SwollmanThere is no harm in calling this routine more than once. 3115622Swollman 3125622Swollman@example 3135622Swollman#define ERROR_TABLE_BASE_@var{xxxx} @var{nnnnn}L 3145622Swollman@end example 3155622Swollman 3165622SwollmanThis symbol contains the value of the first error code entry in the 3175622Swollmanspecified table. 3185622SwollmanThis rarely needs be used by the 3195622Swollmanprogrammer. 3205622Swollman 3215622Swollman@example 3225622Swollmanconst char *error_message (long code); 3235622Swollman@end example 3245622Swollman 3255622SwollmanThis routine returns the character string error message associated 3265622Swollmanwith @code{code}; if this is associated with an unknown error table, or 3275622Swollmanif the code is associated with a known error table but the code is not 3285622Swollmanin the table, a string of the form @samp{Unknown code @var{xxxx nn}} is 3295622Swollmanreturned, where @var{xxxx} is the error table name produced by 3305622Swollmanreversing the compaction performed on the error table number implied 3315622Swollmanby that error code, and @var{nn} is the offset from that base value. 3325622Swollman 3335622SwollmanAlthough this routine is available for use when needed, its use should be 3345622Swollmanleft to circumstances which render @code{com_err} (below) unusable. 3355622Swollman 3365622Swollman@example 3375622Swollmanvoid com_err (const char *whoami, /* module reporting error */ 3385622Swollman long code, /* error code */ 3395622Swollman const char *format, /* format for additional detail */ 3405622Swollman ...); /* (extra parameters) */ 3415622Swollman@end example 3425622Swollman 3435622SwollmanThis routine provides an alternate way to print error messages to 3445622Swollmanstandard error; it allows the error message to be passed in as a 3455622Swollmanparameter, rather than in an external variable. @emph{Provide grammatical 3465622Swollmancontext for ``message.''} 3475622Swollman 3485622SwollmanIf @var{format} is @code{(char *)NULL}, the formatted message will not be 3495622Swollmanprinted. @var{format} may not be omitted. 3505622Swollman 3515622Swollman@example 3525622Swollman#include <stdarg.h> 3535622Swollman 3545622Swollmanvoid com_err_va (const char *whoami, 3555622Swollman long code, 3565622Swollman const char *format, 3575622Swollman va_list args); 3585622Swollman@end example 3595622Swollman 3605622SwollmanThis routine provides an interface, equivalent to @code{com_err} above, 3615622Swollmanwhich may be used by higher-level variadic functions (functions which 3625622Swollmanaccept variable numbers of arguments). 3635622Swollman 3645622Swollman@example 3655622Swollman#include <stdarg.h> 3665622Swollman 3675622Swollmanvoid (*set_com_err_hook (void (*proc) ())) (); 3685622Swollman 3695622Swollmanvoid (*@var{proc}) (const char *whoami, long code, va_list args); 3705622Swollman 3715622Swollmanvoid reset_com_err_hook (); 3725622Swollman@end example 3735622Swollman 3745622SwollmanThese two routines allow a routine to be dynamically substituted for 3755622Swollman@samp{com_err}. After @samp{set_com_err_hook} has been called, 3765622Swollmancalls to @samp{com_err} will turn into calls to the new hook routine. 3775622Swollman@samp{reset_com_err_hook} turns off this hook. This may intended to 3785622Swollmanbe used in daemons (to use a routine which calls @var{syslog(3)}), or 3795622Swollmanin a window system application (which could pop up a dialogue box). 3805622Swollman 3815622SwollmanIf a program is to be used in an environment in which simply printing 3825622Swollmanmessages to the @code{stderr} stream would be inappropriate (such as in a 3835622Swollmandaemon program which runs without a terminal attached), 3845622Swollman@code{set_com_err_hook} may be used to redirect output from @code{com_err}. 3855622SwollmanThe following is an example of an error handler which uses @var{syslog(3)} 3865622Swollmanas supplied in BSD 4.3: 3875622Swollman 3885622Swollman@example 3895622Swollman#include <stdio.h> 3905622Swollman#include <stdarg.h> 3915622Swollman#include <syslog.h> 3925622Swollman 3935622Swollman/* extern openlog (const char * name, int logopt, int facility); */ 3945622Swollman/* extern syslog (int priority, char * message, ...); */ 3955622Swollman 3965622Swollmanvoid hook (const char * whoami, long code, 3975622Swollman const char * format, va_list args) 3985622Swollman@{ 3995622Swollman char buffer[BUFSIZ]; 4005622Swollman static int initialized = 0; 4015622Swollman if (!initialized) @{ 4025622Swollman openlog (whoami, 4035622Swollman LOG_NOWAIT|LOG_CONS|LOG_PID|LOG_NDELAY, 4045622Swollman LOG_DAEMON); 4055622Swollman initialized = 1; 4065622Swollman @} 4075622Swollman vsprintf (buffer, format, args); 4085622Swollman syslog (LOG_ERR, "%s %s", error_message (code), buffer); 4095622Swollman@} 4105622Swollman@end example 4115622Swollman 4125622SwollmanAfter making the call 4135622Swollman@code{set_com_err_hook (hook);}, 4145622Swollmanany calls to @code{com_err} will result in messages being sent to the 4155622Swollman@var{syslogd} daemon for logging. 4165622SwollmanThe name of the program, @samp{whoami}, is supplied to the 4175622Swollman@samp{openlog()} call, and the message is formatted into a buffer and 4185622Swollmanpassed to @code{syslog}. 4195622Swollman 4205622SwollmanNote that since the extra arguments to @code{com_err} are passed by 4215622Swollmanreference via the @code{va_list} value @code{args}, the hook routine may 4225622Swollmanplace any form of interpretation on them, including ignoring them. For 4235622Swollmanconsistency, @code{printf}-style interpretation is suggested, via 4245622Swollman@code{vsprintf} (or @code{_doprnt} on BSD systems without full support for 4255622Swollmanthe ANSI C library). 4265622Swollman 42722176Sjoerg@ifinfo 42822176Sjoerg@node Coding Conventions, Building and Installation, Run-time support routines, (dir) 42922176Sjoerg@comment node-name, next, previous, up 43022176Sjoerg@end ifinfo 43122176Sjoerg 4325622Swollman@section Coding Conventions 4335622Swollman 4345622SwollmanThe following conventions are just some general stylistic conventions 4355622Swollmanto follow when writing robust libraries and programs. Conventions 4365622Swollmansimilar to this are generally followed inside the UNIX kernel and most 4375622Swollmanroutines in the Multics operating system. In general, a routine 4385622Swollmaneither succeeds (returning a zero error code, and doing some side 4395622Swollmaneffects in the process), or it fails, doing minimal side effects; in 4405622Swollmanany event, any invariant which the library assumes must be maintained. 4415622Swollman 4425622SwollmanIn general, it is not in the domain of non user-interface library 4435622Swollmanroutines to write error messages to the user's terminal, or halt the 4445622Swollmanprocess. Such forms of ``error handling'' should be reserved for 4455622Swollmanfailures of internal invariants and consistancy checks only, as it 4465622Swollmanprovides the user of the library no way to clean up for himself in the 4475622Swollmanevent of total failure. 4485622Swollman 4495622SwollmanLibrary routines which can fail should be set up to return an error 4505622Swollmancode. This should usually be done as the return value of the 4515622Swollmanfunction; if this is not acceptable, the routine should return a 4525622Swollman``null'' value, and put the error code into a parameter passed by 4535622Swollmanreference. 4545622Swollman 4555622SwollmanRoutines which use the first style of interface can be used from 4565622Swollmanuser-interface levels of a program as follows: 4575622Swollman 4585622Swollman@example 4595622Swollman@{ 4605622Swollman if ((code = initialize_world(getuid(), random())) != 0) @{ 4615622Swollman com_err("demo", code, 4625622Swollman "when trying to initialize world"); 4635622Swollman exit(1); 4645622Swollman @} 4655622Swollman if ((database = open_database("my_secrets", &code))==NULL) @{ 4665622Swollman com_err("demo", code, 4675622Swollman "while opening my_secrets"); 4685622Swollman exit(1); 4695622Swollman @} 4705622Swollman@} 4715622Swollman@end example 4725622Swollman 4735622SwollmanA caller which fails to check the return status is in error. It is 4745622Swollmanpossible to look for code which ignores error returns by using lint; 4755622Swollmanlook for error messages of the form ``foobar returns value which is 4765622Swollmansometimes ignored'' or ``foobar returns value which is always 4775622Swollmanignored.'' 4785622Swollman 4795622SwollmanSince libraries may be built out of other libraries, it is often necessary 4805622Swollmanfor the success of one routine to depend on another. When a lower level 4815622Swollmanroutine returns an error code, the middle level routine has a few possible 4825622Swollmanoptions. It can simply return the error code to its caller after doing 4835622Swollmansome form of cleanup, it can substitute one of its own, or it can take 4845622Swollmancorrective action of its own and continue normally. For instance, a 4855622Swollmanlibrary routine which makes a ``connect'' system call to make a network 4865622Swollmanconnection may reflect the system error code @code{ECONNREFUSED} 4875622Swollman(Connection refused) to its caller, or it may return a ``server not 4885622Swollmanavailable, try again later,'' or it may try a different server. 4895622Swollman 4905622SwollmanCleanup which is typically necessary may include, but not be limited 4915622Swollmanto, freeing allocated memory which will not be needed any more, 4925622Swollmanunlocking concurrancy locks, dropping reference counts, closing file 4935622Swollmandescriptors, or otherwise undoing anything which the procedure did up 4945622Swollmanto this point. When there are a lot of things which can go wrong, it 4955622Swollmanis generally good to write one block of error-handling code which is 4965622Swollmanbranched to, using a goto, in the event of failure. A common source 4975622Swollmanof errors in UNIX programs is failing to close file descriptors on 4985622Swollmanerror returns; this leaves a number of ``zombied'' file descriptors 4995622Swollmanopen, which eventually causes the process to run out of file 5005622Swollmandescriptors and fall over. 5015622Swollman 5025622Swollman@example 5035622Swollman@{ 5045622Swollman FILE *f1=NULL, *f2=NULL, *f3=NULL; 5055622Swollman int status = 0; 5065622Swollman 5075622Swollman if ( (f1 = fopen(FILE1, "r")) == NULL) @{ 5085622Swollman status = errno; 5095622Swollman goto error; 5105622Swollman @} 5115622Swollman 5125622Swollman /* 5135622Swollman * Crunch for a while 5145622Swollman */ 5155622Swollman 5165622Swollman if ( (f2 = fopen(FILE2, "w")) == NULL) @{ 5175622Swollman status = errno; 5185622Swollman goto error; 5195622Swollman @} 5205622Swollman 5215622Swollman if ( (f3 = fopen(FILE3, "a+")) == NULL) @{ 5225622Swollman status = errno; 5235622Swollman goto error; 5245622Swollman @} 5255622Swollman 5265622Swollman /* 5275622Swollman * Do more processing. 5285622Swollman */ 5295622Swollman fclose(f1); 5305622Swollman fclose(f2); 5315622Swollman fclose(f3); 5325622Swollman return 0; 5335622Swollman 5345622Swollmanerror: 5355622Swollman if (f1) fclose(f1); 5365622Swollman if (f2) fclose(f2); 5375622Swollman if (f3) fclose(f3); 5385622Swollman return status; 5395622Swollman@} 5405622Swollman@end example 5415622Swollman 54222176Sjoerg@ifinfo 54322176Sjoerg@node Building and Installation, Bug Reports, Coding Conventions, (dir) 54422176Sjoerg@comment node-name, next, previous, up 54522176Sjoerg@end ifinfo 54622176Sjoerg 5475622Swollman@section Building and Installation 5485622Swollman 5495622SwollmanThe distribution of this package will probably be done as a compressed 5505622Swollman``tar''-format file available via anonymous FTP from SIPB.MIT.EDU. 5515622SwollmanRetrieve @samp{pub/com_err.tar.Z} and extract the contents. A subdirectory 5525622Swollman@t{profiled} should be created to hold objects compiled for profiling. 5535622SwollmanRunning ``make all'' should then be sufficient to build the library and 5545622Swollmanerror-table compiler. The files @samp{libcom_err.a}, 5555622Swollman@samp{libcom_err_p.a}, @samp{com_err.h}, and @samp{compile_et} should be 5565622Swollmaninstalled for use; @samp{com_err.3} and @samp{compile_et.1} can also be 5575622Swollmaninstalled as manual pages. 5585622Swollman 5595622SwollmanPotential problems: 5605622Swollman 5615622Swollman@itemize @bullet 5625622Swollman 5635622Swollman@item Use of @code{strcasecmp}, a routine provided in BSD for 5645622Swollmancase-insensitive string comparisons. If an equivalent routine is 5655622Swollmanavailable, you can modify @code{CFLAGS} in the makefile to define 5665622Swollman@code{strcasecmp} to the name of that routine. 5675622Swollman 5685622Swollman@item Compilers that defined @code{__STDC__} without providing the header 5695622Swollmanfile @code{<stdarg.h>}. One such example is Metaware's High ``C'' 5705622Swollmancompiler, as provided at Project Athena on the IBM RT/PC workstation; if 5715622Swollman@code{__HIGHC__} is defined, it is assumed that @code{<stdarg.h>} is not 5725622Swollmanavailable, and therefore @code{<varargs.h>} must be used. If the symbol 5735622Swollman@code{VARARGS} is defined (e.g., in the makefile), @code{<varargs.h>} will 5745622Swollmanbe used. 5755622Swollman 5765622Swollman@item If your linker rejects symbols that are simultaneously defined in two 5775622Swollmanlibrary files, edit @samp{Makefile} to remove @samp{perror.c} from the 5785622Swollmanlibrary. This file contains a version of @var{perror(3)} which calls 5795622Swollman@code{com_err} instead of calling @code{write} directly. 5805622Swollman 5815622Swollman@end itemize 5825622Swollman 5835622SwollmanAs I do not have access to non-BSD systems, there are probably 5845622Swollmanbugs present that may interfere with building or using this package on 5855622Swollmanother systems. If they are reported to me, they can probably be fixed for 5865622Swollmanthe next version. 5875622Swollman 58822176Sjoerg@ifinfo 58922176Sjoerg@node Bug Reports, Acknowledgements, Building and Installation, (dir) 59022176Sjoerg@comment node-name, next, previous, up 59122176Sjoerg@end ifinfo 59222176Sjoerg 5935622Swollman@section Bug Reports 5945622Swollman 5955622SwollmanPlease send any comments or bug reports to the principal author: Ken 5965622SwollmanRaeburn, @t{Raeburn@@Athena.MIT.EDU}. 5975622Swollman 59822176Sjoerg@ifinfo 59922176Sjoerg@node Acknowledgements, , Bug Reports, (dir) 60022176Sjoerg@comment node-name, next, previous, up 60122176Sjoerg@end ifinfo 60222176Sjoerg 6035622Swollman@section Acknowledgements 6045622Swollman 6055622SwollmanI would like to thank: Bill Sommerfeld, for his help with some of this 6065622Swollmandocumentation, and catching some of the bugs the first time around; 6075622SwollmanHoneywell Information Systems, for not killing off the @emph{Multics} 6085622Swollmanoperating system before I had an opportunity to use it; Honeywell's 6095622Swollmancustomers, who persuaded them not to do so, for a while; Ted Anderson of 6105622SwollmanCMU, for catching some problems before version 1.2 left the nest; Stan 6115622SwollmanZanarotti and several others of MIT's Student Information Processing Board, 6125622Swollmanfor getting us started with ``discuss,'' for which this package was 6135622Swollmanoriginally written; and everyone I've talked into --- I mean, asked to read 6145622Swollmanthis document and the ``man'' pages. 6155622Swollman 6165622Swollman@bye 617