diff --git a/lib/libcom_err/Makefile b/lib/libcom_err/Makefile new file mode 100644 index 000000000000..d702d365a2a4 --- /dev/null +++ b/lib/libcom_err/Makefile @@ -0,0 +1,16 @@ +# $Id$ + +LIB= com_err +SRCS= com_err.c error_message.c et_name.c init_et.c +CFLAGS+= -I. +MAN3= com_err.3 + +SUBDIR= doc + +beforeinstall: + -cd ${.CURDIR}; cmp -s com_err.h ${DESTDIR}/usr/include/com_err.h || \ + install -c -o ${BINOWN} -g ${BINGRP} -m 444 com_err.h \ + ${DESTDIR}/usr/include + +.include + diff --git a/lib/libcom_err/com_err.3 b/lib/libcom_err/com_err.3 new file mode 100644 index 000000000000..ee4375b0262e --- /dev/null +++ b/lib/libcom_err/com_err.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 1988 Massachusetts Institute of Technology, +.\" Student Information Processing Board. All rights reserved. +.\" +.\" $Header$ +.\" +.TH COM_ERR 3 "22 Nov 1988" SIPB +.SH NAME +com_err \- common error display routine +.SH SYNOPSIS +.nf + #include +.PP +void com_err (whoami, code, format, ...); + const char *whoami; + long code; + const char *format; +.PP +proc = set_com_err_hook (proc); +.fi +void (* +.I proc +) (const char *, long, const char *, va_list); +.nf +.PP +proc = reset_com_err_hook (); +.PP +void initialize_XXXX_error_table (); +.fi +.SH DESCRIPTION +.I Com_err +displays an error message on the standard error stream +.I stderr +(see +.IR stdio (3S)) +composed of the +.I whoami +string, which should specify the program name or some subportion of +a program, followed by an error message generated from the +.I code +value (derived from +.IR compile_et (1)), +and a string produced using the +.I format +string and any following arguments, in the same style as +.IR fprintf (3). + +The behavior of +.I com_err +can be modified using +.I set_com_err_hook; +this defines a procedure which is called with the arguments passed to +.I com_err, +instead of the default internal procedure which sends the formatted +text to error output. Thus the error messages from a program can all +easily be diverted to another form of diagnostic logging, such as +.IR syslog (3). +.I Reset_com_err_hook +may be used to restore the behavior of +.I com_err +to its default form. Both procedures return the previous ``hook'' +value. These ``hook'' procedures must have the declaration given for +.I proc +above in the synopsis. + +The +.I initialize_XXXX_error_table +routine is generated mechanically by +.IR compile_et (1) +from a source file containing names and associated strings. Each +table has a name of up to four characters, which is used in place of +the +.B XXXX +in the name of the routine. These routines should be called before +any of the corresponding error codes are used, so that the +.I com_err +library will recognize error codes from these tables when they are +used. + +The +.B com_err.h +header file should be included in any source file that uses routines +from the +.I com_err +library; executable files must be linked using +.I ``-lcom_err'' +in order to cause the +.I com_err +library to be included. + +.\" .IR for manual entries +.\" .PP for paragraph breaks + +.SH "SEE ALSO" +compile_et (1), syslog (3). + +Ken Raeburn, "A Common Error Description Library for UNIX". diff --git a/lib/libcom_err/com_err.c b/lib/libcom_err/com_err.c new file mode 100644 index 000000000000..d077cad3d4ea --- /dev/null +++ b/lib/libcom_err/com_err.c @@ -0,0 +1,142 @@ +/* + * Copyright 1987, 1988 by MIT Student Information Processing Board. + * + * For copyright info, see mit-sipb-copyright.h. + */ + +#include +#include "mit-sipb-copyright.h" + +/* + * Our environment only provides for ANSI's when using GNU + * C. Grump grump... + */ +#if ! __GNUC__ +#define VARARGS 1 +#endif + +/* We don't have the v*printf routines... */ +#define vfprintf(stream,fmt,args) _doprnt(fmt,args,stream) + +#if __STDC__ && !VARARGS +# include +#else /* varargs: not STDC or no */ + /* Non-ANSI, always take path. */ +# undef VARARGS +# define VARARGS 1 +# include +# undef vfprintf +# define vfprintf(stream,fmt,args) _doprnt(fmt,args,stream) +#endif /* varargs */ + +#include "error_table.h" +#include "internal.h" + +/* + * Protect us from header version (externally visible) of com_err, so + * we can survive in a environment. I think. + */ +#define com_err com_err_external +#include "com_err.h" +#undef com_err + +/* BSD. sigh. */ +#undef vfprintf +#define vfprintf(stream,fmt,args) _doprnt(fmt,args,stream) + +#if ! lint +static const char rcsid[] = + "$Header: /afs/rel-eng.athena.mit.edu/project/release/current/source/athena/athena.lib/et/RCS/com_err.c,v 1.2 90/03/23 13:22:20 epeisach Exp $"; +#endif /* ! lint */ + +static void +#ifdef __STDC__ + default_com_err_proc (const char *whoami, long code, const char *fmt, va_list args) +#else + default_com_err_proc (whoami, code, fmt, args) + const char *whoami; + long code; + const char *fmt; + va_list args; +#endif +{ + if (whoami) { + fputs(whoami, stderr); + fputs(": ", stderr); + } + if (code) { + fputs(error_message(code), stderr); + fputs(" ", stderr); + } + if (fmt) { + vfprintf (stderr, fmt, args); + } + putc('\n', stderr); + /* should do this only on a tty in raw mode */ + putc('\r', stderr); + fflush(stderr); +} + +#ifdef __STDC__ +typedef void (*errf) (const char *, long, const char *, va_list); +#else +typedef void (*errf) (); +#endif + +errf com_err_hook = default_com_err_proc; + +void com_err_va (whoami, code, fmt, args) + const char *whoami; + long code; + const char *fmt; + va_list args; +{ + (*com_err_hook) (whoami, code, fmt, args); +} + +#if ! VARARGS +void com_err (const char *whoami, + long code, + const char *fmt, ...) +{ +#else +void com_err (va_alist) + va_dcl +{ + const char *whoami, *fmt; + long code; +#endif + va_list pvar; + + if (!com_err_hook) + com_err_hook = default_com_err_proc; +#if VARARGS + va_start (pvar); + whoami = va_arg (pvar, const char *); + code = va_arg (pvar, long); + fmt = va_arg (pvar, const char *); +#else + va_start(pvar, fmt); +#endif + com_err_va (whoami, code, fmt, pvar); + va_end(pvar); +} + +errf set_com_err_hook (new_proc) + errf new_proc; +{ + errf x = com_err_hook; + + if (new_proc) + com_err_hook = new_proc; + else + com_err_hook = default_com_err_proc; + + return x; +} + +errf reset_com_err_hook () { + errf x = com_err_hook; + com_err_hook = default_com_err_proc; + return x; +} diff --git a/lib/libcom_err/com_err.h b/lib/libcom_err/com_err.h new file mode 100644 index 000000000000..7bea01004317 --- /dev/null +++ b/lib/libcom_err/com_err.h @@ -0,0 +1,36 @@ +/* + * Header file for common error description library. + * + * Copyright 1988, Student Information Processing Board of the + * Massachusetts Institute of Technology. + * + * For copyright and distribution info, see the documentation supplied + * with this package. + */ + +#ifndef __COM_ERR_H + +#ifdef __STDC__ +#ifndef __HIGHC__ /* gives us STDC but not stdarg */ +#include +#else +#include +#endif +/* ANSI C -- use prototypes etc */ +void com_err (const char *, long, const char *, ...); +char const *error_message (long); +void (*com_err_hook) (const char *, long, const char *, va_list); +void (*set_com_err_hook (void (*) (const char *, long, const char *, va_list))) + (const char *, long, const char *, va_list); +void (*reset_com_err_hook ()) (const char *, long, const char *, va_list); +#else +/* no prototypes */ +void com_err (); +char *error_message (); +void (*com_err_hook) (); +void (*set_com_err_hook ()) (); +void (*reset_com_err_hook ()) (); +#endif + +#define __COM_ERR_H +#endif /* ! defined(__COM_ERR_H) */ diff --git a/lib/libcom_err/doc/Makefile b/lib/libcom_err/doc/Makefile new file mode 100644 index 000000000000..7ac02619267e --- /dev/null +++ b/lib/libcom_err/doc/Makefile @@ -0,0 +1,5 @@ +# $Id$ + +INFO= com_err + +.include diff --git a/lib/libcom_err/doc/com_err.texinfo b/lib/libcom_err/doc/com_err.texinfo new file mode 100644 index 000000000000..2f4b26612975 --- /dev/null +++ b/lib/libcom_err/doc/com_err.texinfo @@ -0,0 +1,554 @@ +\input texinfo @c -*-texinfo-*- + +@c $Header$ +@c $Source$ +@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.) + +@ifinfo +@barfo +@end ifinfo + +@iftex +@tolerance 10000 + +@c Mutate section headers... +@begingroup + @catcode#=6 + @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}} +@endgroup +@end iftex + +@setfilename com_err +@settitle A Common Error Description Library for UNIX + +@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. + +@end ifinfo + +@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 + +@ifinfo +@c should put a menu here someday.... +@end ifinfo + +@page + +@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. + +@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. + +@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 + +@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__}. + +@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{}. 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. + +@example +const char *error_message (long code); +@end example + +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. + +@example +void com_err (const char *whoami, /* module reporting error */ + long code, /* error code */ + const char *format, /* format for additional detail */ + ...); /* (extra parameters) */ +@end example + +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.''} + +If @var{format} is @code{(char *)NULL}, the formatted message will not be +printed. @var{format} may not be omitted. + +@example +#include + +void com_err_va (const char *whoami, + long code, + const char *format, + va_list args); +@end example + +This routine provides an interface, equivalent to @code{com_err} above, +which may be used by higher-level variadic functions (functions which +accept variable numbers of arguments). + +@example +#include + +void (*set_com_err_hook (void (*proc) ())) (); + +void (*@var{proc}) (const char *whoami, long code, va_list args); + +void reset_com_err_hook (); +@end example + +These two routines allow a routine to be dynamically substituted for +@samp{com_err}. After @samp{set_com_err_hook} has been called, +calls to @samp{com_err} will turn into calls to the new hook routine. +@samp{reset_com_err_hook} turns off this hook. This may intended to +be used in daemons (to use a routine which calls @var{syslog(3)}), or +in a window system application (which could pop up a dialogue box). + +If a program is to be used in an environment in which simply printing +messages to the @code{stderr} stream would be inappropriate (such as in a +daemon program which runs without a terminal attached), +@code{set_com_err_hook} may be used to redirect output from @code{com_err}. +The following is an example of an error handler which uses @var{syslog(3)} +as supplied in BSD 4.3: + +@example +#include +#include +#include + +/* 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). + +@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 + +@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{}. 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{} is not +available, and therefore @code{} must be used. If the symbol +@code{VARARGS} is defined (e.g., in the makefile), @code{} 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 @var{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. + +@section Bug Reports + +Please send any comments or bug reports to the principal author: Ken +Raeburn, @t{Raeburn@@Athena.MIT.EDU}. + +@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 diff --git a/lib/libcom_err/error_message.c b/lib/libcom_err/error_message.c new file mode 100644 index 000000000000..99dab1e582c8 --- /dev/null +++ b/lib/libcom_err/error_message.c @@ -0,0 +1,71 @@ +/* + * $Header: error_message.c,v 1.2 89/01/25 09:08:57 shanzer Exp $ + * $Source: /paris/source/4.3/athena.lib/et.new/RCS/error_message.c,v $ + * $Locker: $ + * + * Copyright 1987 by the Student Information Processing Board + * of the Massachusetts Institute of Technology + * + * For copyright info, see "mit-sipb-copyright.h". + */ + +#include +#include "error_table.h" +#include "mit-sipb-copyright.h" +#include "internal.h" + +static const char rcsid[] = + "$Header: error_message.c,v 1.2 89/01/25 09:08:57 shanzer Exp $"; +static const char copyright[] = + "Copyright 1986, 1987, 1988 by the Student Information Processing Board\nand the department of Information Systems\nof the Massachusetts Institute of Technology"; + +static char buffer[25]; + +struct et_list * _et_list = (struct et_list *) NULL; + +const char * error_message (code) +long code; +{ + int offset; + struct et_list *et; + int table_num; + int started = 0; + char *cp; + + offset = code & ((1<next) { + if (et->table->base == table_num) { + /* This is the right table */ + if (et->table->n_msgs <= offset) + goto oops; + return(et->table->msgs[offset]); + } + } +oops: + strcpy (buffer, "Unknown code "); + if (table_num) { + strcat (buffer, error_table_name (table_num)); + strcat (buffer, " "); + } + for (cp = buffer; *cp; cp++) + ; + if (offset >= 100) { + *cp++ = '0' + offset / 100; + offset %= 100; + started++; + } + if (started || offset >= 10) { + *cp++ = '0' + offset / 10; + offset %= 10; + } + *cp++ = '0' + offset; + *cp = '\0'; + return(buffer); +} diff --git a/lib/libcom_err/error_table.h b/lib/libcom_err/error_table.h new file mode 100644 index 000000000000..78f7db200f77 --- /dev/null +++ b/lib/libcom_err/error_table.h @@ -0,0 +1,30 @@ +/* + * Copyright 1988 by the Student Information Processing Board of the + * Massachusetts Institute of Technology. + * + * For copyright info, see mit-sipb-copyright.h. + */ + +#ifndef _ET_H +/* Are we using ANSI C? */ +#ifndef __STDC__ +#define const +#endif +extern int errno; +struct error_table { + char const * const * msgs; + long base; + int n_msgs; +}; +struct et_list { + struct et_list *next; + const struct error_table *table; +}; +extern struct et_list * _et_list; + +#define ERRCODE_RANGE 8 /* # of bits to shift table number */ +#define BITS_PER_CHAR 6 /* # bits to shift per character in name */ + +extern const char *error_table_name(); +#define _ET_H +#endif diff --git a/lib/libcom_err/et_name.c b/lib/libcom_err/et_name.c new file mode 100644 index 000000000000..a896bab84e18 --- /dev/null +++ b/lib/libcom_err/et_name.c @@ -0,0 +1,43 @@ +/* + * Copyright 1987 by MIT Student Information Processing Board + * + * For copyright info, see mit-sipb-copyright.h. + */ + +#include "error_table.h" +#include "mit-sipb-copyright.h" +#include "internal.h" + +#ifndef lint +static const char copyright[] = + "Copyright 1987,1988 by Student Information Processing Board, Massachusetts Institute of Technology"; +static const char rcsid_et_name_c[] = + "$Header: et_name.c,v 1.7 89/01/01 06:14:56 raeburn Exp $"; +#endif + +static const char char_set[] = + "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_"; + +static char buf[6]; + +const char * error_table_name(num) + int num; +{ + int ch; + int i; + char *p; + + /* num = aa aaa abb bbb bcc ccc cdd ddd d?? ??? ??? */ + p = buf; + num >>= ERRCODE_RANGE; + /* num = ?? ??? ??? aaa aaa bbb bbb ccc ccc ddd ddd */ + num &= 077777777; + /* num = 00 000 000 aaa aaa bbb bbb ccc ccc ddd ddd */ + for (i = 4; i >= 0; i--) { + ch = (num >> BITS_PER_CHAR * i) & ((1 << BITS_PER_CHAR) - 1); + if (ch != 0) + *p++ = char_set[ch-1]; + } + *p = '\0'; + return(buf); +} diff --git a/lib/libcom_err/init_et.c b/lib/libcom_err/init_et.c new file mode 100644 index 000000000000..630c2ac4a0b3 --- /dev/null +++ b/lib/libcom_err/init_et.c @@ -0,0 +1,55 @@ +/* + * $Header: init_et.c,v 1.5 88/10/27 08:34:54 raeburn Exp $ + * $Source: /mit/raeburn/Work/et/src/RCS/init_et.c,v $ + * $Locker: $ + * + * Copyright 1986, 1987, 1988 by MIT Information Systems and + * the MIT Student Information Processing Board. + * + * For copyright info, see mit-sipb-copyright.h. + */ + +#include +#include "error_table.h" +#include "mit-sipb-copyright.h" + +#ifndef __STDC__ +#define const +#endif + +#ifndef lint +static const char rcsid_init_et_c[] = + "$Header: init_et.c,v 1.5 88/10/27 08:34:54 raeburn Exp $"; +#endif + +extern char *malloc(), *realloc(); + +struct foobar { + struct et_list etl; + struct error_table et; +}; + +extern struct et_list * _et_list; + +int init_error_table(msgs, base, count) + const char * const * msgs; + int base; + int count; +{ + struct foobar * new_et; + + if (!base || !count || !msgs) + return 0; + + new_et = (struct foobar *) malloc(sizeof(struct foobar)); + if (!new_et) + return errno; /* oops */ + new_et->etl.table = &new_et->et; + new_et->et.msgs = msgs; + new_et->et.base = base; + new_et->et.n_msgs= count; + + new_et->etl.next = _et_list; + _et_list = &new_et->etl; + return 0; +} diff --git a/lib/libcom_err/internal.h b/lib/libcom_err/internal.h new file mode 100644 index 000000000000..880fe7686217 --- /dev/null +++ b/lib/libcom_err/internal.h @@ -0,0 +1,18 @@ +/* + * internal include file for com_err package + */ +#include "mit-sipb-copyright.h" +#ifndef __STDC__ +#undef const +#define const +#endif + +extern int errno; +extern char const * const sys_errlist[]; +extern /* const */ int sys_nerr; + +#ifdef __STDC__ +void perror (const char *); +#else +int perror (); +#endif diff --git a/lib/libcom_err/mit-sipb-copyright.h b/lib/libcom_err/mit-sipb-copyright.h new file mode 100644 index 000000000000..2f7eb295014d --- /dev/null +++ b/lib/libcom_err/mit-sipb-copyright.h @@ -0,0 +1,19 @@ +/* + +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. + +*/ + diff --git a/lib/libcom_err/test/test.c b/lib/libcom_err/test/test.c new file mode 100644 index 000000000000..955cb964aaa8 --- /dev/null +++ b/lib/libcom_err/test/test.c @@ -0,0 +1,47 @@ +#include +#include +#include "com_err.h" +#include "test1.h" +#include "test2.h" + +extern int sys_nerr, errno; + +main() +{ + printf("Before initiating error table:\n\n"); + printf("Table name '%s'\n", error_table_name(KRB_MK_AP_TGTEXP)); + printf("UNIX name '%s'\n", error_table_name(EPERM)); + printf("Msg TGT-expired is '%s'\n", error_message(KRB_MK_AP_TGTEXP)); + printf("Msg EPERM is '%s'\n", error_message(EPERM)); + printf("Msg FOO_ERR is '%s'\n", error_message(FOO_ERR)); + printf("Msg {sys_nerr-1} is '%s'\n", error_message(sys_nerr-1)); + printf("Msg {sys_nerr} is '%s'\n", error_message(sys_nerr)); + + printf("With 0: tgt-expired -> %s\n", error_message(KRB_MK_AP_TGTEXP)); + + initialize_krb_error_table(); + printf("KRB error table initialized: base %d (%s), name %s\n", + ERROR_TABLE_BASE_krb, error_message(ERROR_TABLE_BASE_krb), + error_table_name(ERROR_TABLE_BASE_krb)); + initialize_krb_error_table(); + printf("With krb: tgt-expired -> %s\n", + error_message(KRB_MK_AP_TGTEXP)); + + initialize_quux_error_table(); + printf("QUUX error table initialized: base %d (%s), name %s\n", + ERROR_TABLE_BASE_quux, error_message(ERROR_TABLE_BASE_quux), + error_table_name(ERROR_TABLE_BASE_quux)); + + printf("Msg for TGT-expired is '%s'\n", + error_message(KRB_MK_AP_TGTEXP)); + printf("Msg {sys_nerr-1} is '%s'\n", error_message(sys_nerr-1)); + printf("Msg FOO_ERR is '%s'\n", error_message(FOO_ERR)); + printf("Msg KRB_SKDC_CANT is '%s'\n", + error_message(KRB_SKDC_CANT)); + printf("Msg 1e6 (8B 64) is '%s'\n", error_message(1000000)); + printf("\n\nCOM_ERR tests:\n"); + com_err("whoami", FOO_ERR, (char *)NULL); + com_err("whoami", FOO_ERR, " -- message goes %s", "here"); + com_err("whoami", 0, (char *)0); + com_err("whoami", 0, "error number %d\n", 0); +} diff --git a/lib/libcom_err/test/test1.et b/lib/libcom_err/test/test1.et new file mode 100644 index 000000000000..4c7b77f0e255 --- /dev/null +++ b/lib/libcom_err/test/test1.et @@ -0,0 +1,69 @@ + error_table krb + + error_code KRB_MK_AP_TKFIL, + "Can't read ticket file" + + ec KRB_MK_AP_NOTKT, + "Can't find ticket or TGT" + + ec KRB_MK_AP_TGTEXP, + "TGT expired" + + ec KRB_RD_AP_UNDEC, + "Can't decode authenticator" + + ec KRB_RD_AP_EXP, + "Ticket expired" + + ec KRB_RD_AP_REPEAT, + "Repeated request" + + ec KRB_RD_AP_NOT_US, + "The ticket isn't for us" + + ec KRB_RD_AP_INCON, + "Request is inconsistent" + + ec KRB_RD_AP_TIME, + "Delta-T too big" + + ec KRB_RD_AP_BADD, + "Incorrect net address" + + ec KRB_RD_AP_VERSION, + "Protocol version mismatch" + + ec KRB_RD_AP_MSG_TYPE, + "Invalid message type" + + ec KRB_RD_AP_MODIFIED, + "Message stream modified" + + ec KRB_RD_AP_ORDER, + "Message out of order" + + ec KRB_RD_AP_UNAUTHOR, + "Unauthorized request" + + ec KRB_GT_PW_NULL, + "Current password is null" + + ec KRB_GT_PW_BADPW, + "Incorrect current password" + + ec KRB_GT_PW_PROT, + "Protocol error" + + ec KRB_GT_PW_KDCERR, + "Error returned by KDC" + + ec KRB_GT_PW_NULLTKT, + "Null ticket returned by KDC" + + ec KRB_SKDC_RETRY, + "Retry count exceeded" + + ec KRB_SKDC_CANT, + "Can't send request" + + end diff --git a/lib/libcom_err/test/test2.et b/lib/libcom_err/test/test2.et new file mode 100644 index 000000000000..55ad74ead071 --- /dev/null +++ b/lib/libcom_err/test/test2.et @@ -0,0 +1,9 @@ + error_table quux + + ec FOO_ERR, "foo" + + ec BAR_ERR, "bar" + + ec BAZ_ERR, "meow" + + end