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