com_err: convert info page to com_err.7
authorJohn Marino <>
Fri, 3 Apr 2015 12:05:31 +0000 (14:05 +0200)
committerJohn Marino <>
Fri, 3 Apr 2015 13:20:51 +0000 (15:20 +0200)
The was already a com_err.1 man page, but it was significantly shorter
than the com_err info page.  The info page was converted to man 7 com_err
and then removed.
lib/libcom_err/com_err.7 [new file with mode: 0644]
lib/libcom_err/doc/Makefile [deleted file]
lib/libcom_err/doc/com_err.texinfo [deleted file]

index 4166093..fecf6e7 100644 (file)
@@ -3031,6 +3031,7 @@ TO_REMOVE+=/usr/share/info/
 .if ${MACHINE_ARCH} == "x86_64"
index fde280e..f5e2f2a 100644 (file)
@@ -3,12 +3,10 @@
 LIB=   com_err
 SRCS=  com_err.c error.c
 INCS=  ${COM_ERRDIR}/com_err.h ${COM_ERRDIR}/com_right.h
-MAN=   com_err.3
+MAN=   com_err.3 com_err.7
 COM_ERRDIR=    ${.CURDIR}/../../contrib/com_err
-SUBDIR=        doc
 .include <>
diff --git a/lib/libcom_err/com_err.7 b/lib/libcom_err/com_err.7
new file mode 100644 (file)
index 0000000..4d12dbe
--- /dev/null
@@ -0,0 +1,547 @@
+.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
+.\" Standard preamble:
+.\" ======================================================================== Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+.. Vb \" Begin verbatim text
+.ft CW \\$1
+.. Ve \" End verbatim text
+.ft R
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>. \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+.\" Escape single quotes in literal strings from groff's Unicode transform. \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\" Avoid warning from groff about undefined register 'F'. IX
+.. rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+.    if \nF \{
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+.        if !\nF==2 \{
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.rr rF
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.IX Title "COM_ERR 7"
+.TH COM_ERR 7 "2015-04-03" "perl v5.18.4" "DragonFly Miscellaneous Information Manual"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+com_err Manual \- Conversion of
+.SH "General Introduction"
+.IX Header "General Introduction"
+* Menu:
+What is all this for?: see \*(L"Why com_err?\*(R"
+What's an error code, anyway?: see \*(L"Error codes\*(R"
+How to describe an error table.: see \*(L"Error table source file\*(R"
+How to compile the table.: see \*(L"The error-table compiler\*(R"
+How to use from within your program.: see \*(L"Run-time support routines\*(R"
+Stylistic issues.: see \*(L"Coding Conventions\*(R"
+How to build and install.: see \*(L"Building and Installation\*(R"
+You have found a bug?  Report it.: see \*(L"Bug Reports\*(R"
+Whom to thank...: see \*(L"Acknowledgements\*(R"
+.SS "Why com_err?"
+.IX Subsection "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 \s-1SUCCESS\s0 or \s-1FAILURE,\s0 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 `\fBerrno\fR', `\fBh_errno\fR', the return
+value from `\fB\f(BIhes_err()\fB\fR', 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 \*(L"name\*(R" 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 \*(L"known\*(R" 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 `\fBunknown code foo 32\fR', where `\fBfoo\fR' would be
+the name of the table.
+.SS "Error codes"
+.IX Subsection "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 \s-1UNIX\s0 system call error table
+(`\fBsys_errlist\fR'); this allows `\fBerrno\fR' values to be used directly in the
+library (assuming that `\fBerrno\fR' is of a type with the same width as
+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
+long.  The draft proposed American National Standard for C (as of May,
+1988) requires that long variables be at least 32 bits; any system
+which does not support 32\-bit long values cannot make use of this
+package (nor much other software that assumes an ANSI-C environment
+base) without significant effort.
+.SS "Error table source file"
+.IX Subsection "Error table source file"
+The error table source file begins with the declaration of the table
+name, as
+error_table \s-1TABLENAME\s0
+Individual error codes are specified with
+error_code \s-1ERROR_NAME, \*(L"TEXT MESSAGE\*(R"\s0
+where `\fBec\fR' can also be used as a short form of `\fBerror_code\fR'.  To
+indicate the end of the table, use `\fBend\fR'.  Thus, a (short) sample error
+table might be:
+error_table     dsc
+error_code      \s-1DSC_DUP_MTG_NAME,
+\&\s0\*(L"Meeting already exists\*(R"
+ec              \s-1DSC_BAD_PATH,
+\&\*(L"A\s0 bad meeting pathname was given\*(R"
+ec              \s-1DSC_BAD_MODES,
+\&\s0\*(L"Invalid mode for this access control list\*(R"
+.SS "The error-table compiler"
+.IX Subsection "The error-table compiler"
+The error table compiler is named `\fBcompile_et\fR'.  It takes one argument,
+the pathname of a file (ending in `\\fR', e.g., `\\fR') containing
+an error table source file.  It parses the error table, and generates
+two output files \- a C header file (`\fBdiscuss_err.h\fR') 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 `\fB\-language \s-1LANG\s0\fR' argument, which
+determines for which language (or language variant) the output should be
+written.  At the moment, \s-1LANG\s0 is currently limited to `\fBANSI-C\fR' and
+`\fBK&R\-C\fR', and some abbreviated forms of each.  Eventually, this will be
+extended to include some support for \*(C+.  The default is currently
+`\fBK&R\-C\fR', though the generated sources will have ANSI-C code
+conditionalized on the symbol _\|_STDC_\|_.
+.SS "Run-time support routines"
+.IX Subsection "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 `\fB<com_err.h>\fR'.  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:
+void initialize_XXXX_error_table (void);
+One of these routines is built by the error compiler for each error
+table.  It makes the \s-1XXXX\s0 error table \*(L"known\*(R" to the error reporting
+system.  By convention, this routine should be called in the
+initialization routine of the \s-1XXXX\s0 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.
+This symbol contains the value of the first error code entry in the
+specified table.  This rarely needs be used by the programmer.
+const char *error_message (long code);
+This routine returns the character string error message associated
+with `\fBcode\fR'; 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 `\fBUnknown code \s-1XXXX NN\s0\fR' is returned,
+where \s-1XXXX\s0 is the error table name produced by reversing the compaction
+performed on the error table number implied by that error code, and \s-1NN\s0
+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 `\fBcom_err\fR' (below) unusable.
+void com_err (const char *whoami,  /* module reporting error */
+long code,           /* error code */
+const char *format,  /* format for additional detail */
+\&...);                /*  (extra parameters) */
+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.  _Provide grammatical
+context for \*(L"message.\*(R"_
+If \s-1FORMAT\s0 is `\fB(char *)NULL\fR', the formatted message will not be
+printed.  \s-1FORMAT\s0 may not be omitted.
+#include <stdarg.h>
+void com_err_va (const char *whoami,
+long code,
+const char *format,
+va_list args);
+This routine provides an interface, equivalent to `\fBcom_err\fR' above,
+which may be used by higher-level variadic functions (functions which
+accept variable numbers of arguments).
+#include <stdarg.h>
+void (*set_com_err_hook (void (*proc) ())) ();
+void (*PROC) (const char *whoami, long code, va_list args);
+void reset_com_err_hook ();
+These two routines allow a routine to be dynamically substituted for
+`\fBcom_err\fR'.  After `\fBset_com_err_hook\fR' has been called, calls to
+`\fBcom_err\fR' will turn into calls to the new hook routine.
+`\fBreset_com_err_hook\fR' turns off this hook.  This may intended to be used
+in daemons (to use a routine which calls \s-1\fISYSLOG\s0\fR\|(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 `\fBstderr\fR' stream would be inappropriate (such as in a
+daemon program which runs without a terminal attached),
+`\fBset_com_err_hook\fR' may be used to redirect output from `\fBcom_err\fR'.  The
+following is an example of an error handler which uses \s-1\fISYSLOG\s0\fR\|(3) as
+supplied in \s-1BSD 4.3:\s0
+#include <stdio.h>
+#include <stdarg.h>
+#include <syslog.h>
+/* extern openlog (const char * name, int logopt, int facility); */
+/* extern syslog (int priority, char * message, ...); */
+void hook (const char * whoami, long code,
+const char * format, va_list args)
+char buffer[\s-1BUFSIZ\s0];
+static int initialized = 0;
+if (!initialized) {
+openlog (whoami,
+initialized = 1;
+vsprintf (buffer, format, args);
+syslog (\s-1LOG_ERR, \s0\*(L"%s \f(CW%s\fR\*(R", error_message (code), buffer);
+After making the call `\fBset_com_err_hook (hook);\fR', any calls to
+`\fBcom_err\fR' will result in messages being sent to the \s-1SYSLOGD\s0 daemon for
+logging.  The name of the program, `\fBwhoami\fR', is supplied to the
+`\fB\f(BIopenlog()\fB\fR' call, and the message is formatted into a buffer and passed
+to `\fBsyslog\fR'.
+Note that since the extra arguments to `\fBcom_err\fR' are passed by
+reference via the `\fBva_list\fR' value `\fBargs\fR', the hook routine may place
+any form of interpretation on them, including ignoring them.  For
+consistency, `\fBprintf\fR'\-style interpretation is suggested, via `\fBvsprintf\fR'
+(or `\fB_doprnt\fR' on \s-1BSD\s0 systems without full support for the \s-1ANSI C\s0
+.SS "Coding Conventions"
+.IX Subsection "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 \s-1UNIX\s0 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 \*(L"error handling\*(R" 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 \*(L"null\*(R" 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:
+if ((code = initialize_world(\fIgetuid()\fR, \fIrandom()\fR)) != 0) {
+com_err(\*(L"demo\*(R", code,
+\&\*(L"when trying to initialize world\*(R");
+if ((database = open_database(\*(L"my_secrets\*(R", &code))==NULL) {
+com_err(\*(L"demo\*(R", code,
+\&\*(L"while opening my_secrets\*(R");
+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 \*(L"foobar returns value which is
+sometimes ignored\*(R" or \*(L"foobar returns value which is always ignored.\*(R"
+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 \*(L"connect\*(R" system call to
+make a network connection may reflect the system error code
+`\fB\s-1ECONNREFUSED\s0\fR' (Connection refused) to its caller, or it may return a
+\&\*(L"server not available, try again later,\*(R" or it may try a different
+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 \s-1UNIX\s0 programs is failing to close file descriptors on error
+returns; this leaves a number of \*(L"zombied\*(R" file descriptors open, which
+eventually causes the process to run out of file descriptors and fall
+\&\s-1FILE\s0 *f1=NULL, *f2=NULL, *f3=NULL;
+int status = 0;
+if ( (f1 = fopen(\s-1FILE1, \s0\*(L"r\*(R")) == \s-1NULL\s0) {
+status = errno;
+goto error;
+* Crunch for a while
+if ( (f2 = fopen(\s-1FILE2, \s0\*(L"w\*(R")) == \s-1NULL\s0) {
+status = errno;
+goto error;
+if ( (f3 = fopen(\s-1FILE3, \s0\*(L"a+\*(R")) == \s-1NULL\s0) {
+status = errno;
+goto error;
+* Do more processing.
+return 0;
+if (f1) fclose(f1);
+if (f2) fclose(f2);
+if (f3) fclose(f3);
+return status;
+.SS "Building and Installation"
+.IX Subsection "Building and Installation"
+The distribution of this package will probably be done as a compressed
+\&\*(L"tar\*(R"\-format file available via anonymous \s-1FTP\s0 from \s-1SIPB.MIT.EDU.\s0
+Retrieve `\fBpub/com_err.tar.Z\fR' and extract the contents.  A subdirectory
+profiled should be created to hold objects compiled for profiling.
+Running \*(L"make all\*(R" should then be sufficient to build the library and
+error-table compiler.  The files `\fBlibcom_err.a\fR', `\fBlibcom_err_p.a\fR',
+`\fBcom_err.h\fR', and `\fBcompile_et\fR' should be installed for use; `\fBcom_err.3\fR'
+and `\fBcompile_et.1\fR' can also be installed as manual pages.
+Potential problems:
+* Use of `\fBstrcasecmp\fR', a routine provided in \s-1BSD\s0 for
+case-insensitive string comparisons.  If an equivalent routine is
+available, you can modify `\fB\s-1CFLAGS\s0\fR' in the makefile to define
+`\fBstrcasecmp\fR' to the name of that routine.
+* Compilers that defined `\fB_\|_STDC_\|_\fR' without providing the header
+file `\fB<stdarg.h>\fR'.  One such example is Metaware's High \*(L"C\*(R"
+compiler, as provided at Project Athena on the \s-1IBM RT/PC\s0
+workstation; if `\fB_\|_HIGHC_\|_\fR' is defined, it is assumed that
+`\fB<stdarg.h>\fR' is not available, and therefore `\fB<varargs.h>\fR' must be
+used.  If the symbol `\fB\s-1VARARGS\s0\fR' is defined (e.g., in the makefile),
+`\fB<varargs.h>\fR' will be used.
+* If your linker rejects symbols that are simultaneously defined in
+two library files, edit `\fBMakefile\fR' to remove `\fBperror.c\fR' from the
+library.  This file contains a version of \s-1\fIPERROR\s0\fR\|(3) which calls
+`\fBcom_err\fR' instead of calling `\fBwrite\fR' directly.
+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.
+.SS "Bug Reports"
+.IX Subsection "Bug Reports"
+Please send any comments or bug reports to the principal author: Ken
+Raeburn, Raeburn@Athena.MIT.EDU.
+.SS "Acknowledgements"
+.IX Subsection "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 _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
+\&\s-1CMU,\s0 for catching some problems before version 1.2 left the nest; Stan
+Zanarotti and several others of \s-1MIT\s0's Student Information Processing
+Board, for getting us started with \*(L"discuss,\*(R" for which this package was
+originally written; and everyone I've talked into \*(-- I mean, asked to
+read this document and the \*(L"man\*(R" pages.
diff --git a/lib/libcom_err/doc/Makefile b/lib/libcom_err/doc/Makefile
deleted file mode 100644 (file)
index 1ff6f87..0000000
+++ /dev/null
@@ -1,8 +0,0 @@
-# $FreeBSD: src/lib/libcom_err/doc/Makefile,v 1.8 1999/08/28 00:04:09 peter Exp $
-# $DragonFly: src/lib/libcom_err/doc/Makefile,v 1.2 2003/06/17 04:26:48 dillon Exp $
-INFO=  com_err
-INFOSECTION= "Programming & development tools."
-INFOENTRY_com_err= "* libcom_err: (com_err).        A Common Error Description Library for UNIX."
-.include <>
diff --git a/lib/libcom_err/doc/com_err.texinfo b/lib/libcom_err/doc/com_err.texinfo
deleted file mode 100644 (file)
index 79208d6..0000000
+++ /dev/null
@@ -1,616 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c $FreeBSD: src/lib/libcom_err/doc/com_err.texinfo,v 1.4 1999/09/06 07:41:34 peter Exp $
-@c $DragonFly: src/lib/libcom_err/doc/com_err.texinfo,v 1.2 2003/06/17 04:26:48 dillon Exp $
-@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 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.)
-@end ifinfo
-@tolerance 10000
-@c Mutate section headers...
-  @catcode\11#=6
-  @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}}
-@end iftex
-@c %**start of header (This is for running Texinfo on a region.)
-@setfilename com_err
-@settitle A Common Error Description Library for UNIX
-@c %**end of header (This is for running Texinfo on a region.)
-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
-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
-@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.
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1987, 1988 by the Student Information Processing
-Board of the Massachusetts Institute of Technology.
-Permission to use, copy, modify, and distribute this software and its
-documentation for any purpose and without fee is hereby granted, provided
-that the above copyright notice appear in all copies and that both that
-copyright notice and this permission notice appear in supporting
-documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
-used in advertising or publicity pertaining to distribution of the software
-without specific, written prior permission.  M.I.T. and the M.I.T. S.I.P.B.
-make no representations about the suitability of this software for any
-purpose.  It is provided "as is" without express or implied warranty.
-Note that the file texinfo.tex, provided with this distribution, is from
-the Free Software Foundation, and is under different copyright restrictions
-from the remainder of this package.
-@end titlepage
-@node Top, Why com_err?, (dir), (dir)
-@comment  node-name,  next,  previous,  up
-@top General Introduction
-* Why com_err?::                What is all this for?
-* Error codes::                 What's an error code, anyway?
-* Error table source file::     How to describe an error table.
-* The error-table compiler::    How to compile the table.
-* Run-time support routines::   How to use from within your program.
-* Coding Conventions::          Stylistic issues.
-* Building and Installation::   How to build and install.
-* Bug Reports::                 You have found a bug?  Report it.
-* Acknowledgements::            Whom to thank...
-@end menu
-@end ifinfo
-@node Why com_err?, Error codes, Top, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@section Why com_err?
-In building application software packages, a programmer often has to
-deal with a number of libraries, each of which can use a different
-error-reporting mechanism.  Sometimes one of two values is returned,
-indicating simply SUCCESS or FAILURE, with no description of errors
-encountered.  Sometimes it is an index into a table of text strings,
-where the name of the table used is dependent on the library being
-used when the error is generated; since each table starts numbering at
-0 or 1, additional information as to the source of the error code is
-needed to determine which table to look at.  Sometimes no text messages are
-supplied at all, and the programmer must supply them at any point at which
-he may wish to report error conditions.
-Often, a global variable is assigned some value describing the error, but
-the programmer has to know in each case whether to look at @code{errno},
-@code{h_errno}, the return value from @code{hes_err()}, or whatever other
-variables or routines are specified.
-And what happens if something
-in the procedure of
-examining or reporting the error changes the same variable?
-The package we have developed is an attempt to present a common
-error-handling mechanism to manipulate the most common form of error code
-in a fashion that does not have the problems listed above.
-A list of up to 256 text messages is supplied to a translator we have
-written, along with the three- to four-character ``name'' of the error
-table.  The library using this error table need only call a routine
-generated from this error-table source to make the table ``known'' to the
-com_err library, and any error code the library generates can be converted
-to the corresponding error message.  There is also a default format for
-error codes accidentally returned before making the table known, which is
-of the form @samp{unknown code foo 32}, where @samp{foo} would be the name
-of the table.
-@node Error codes, Error table source file, Why com_err?, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@section Error codes
-Error codes themselves are 32 bit (signed) integers, of which the high
-order 24 bits are an identifier of which error table the error code is
-from, and the low order 8 bits are a sequential error number within
-the table.  An error code may thus be easily decomposed into its component
-parts.  Only the lowest 32 bits of an error code are considered significant
-on systems which support wider values.
-Error table 0 is defined to match the UNIX system call error table
-(@code{sys_errlist}); this allows @code{errno} values to be used directly
-in the library (assuming that @code{errno} is of a type with the same width
-as @t{long}).  Other error table numbers are formed by compacting together
-the first four characters of the error table name.  The mapping between
-characters in the name and numeric values in the error code are defined in
-a system-independent fashion, so that two systems that can pass integral
-values between them can reliably pass error codes without loss of meaning;
-this should work even if the character sets used are not the same.
-(However, if this is to be done, error table 0 should be avoided, since the
-local system call error tables may differ.)
-Any variable which is to contain an error code should be declared @t{long}.
-The draft proposed American National Standard for C (as of May, 1988)
-requires that @t{long} variables be at least 32 bits; any system which does
-not support 32-bit @t{long} values cannot make use of this package (nor
-much other software that assumes an ANSI-C environment base) without
-significant effort.
-@node Error table source file, The error-table compiler, Error codes, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@section Error table source file
-The error table source file begins with the declaration of the table name,
-error_table @var{tablename}
-@end example
-Individual error codes are
-specified with
-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:
-        error_table     dsc
-        error_code      DSC_DUP_MTG_NAME,
-                        "Meeting already exists"
-        ec              DSC_BAD_PATH,
-                        "A bad meeting pathname was given"
-        ec              DSC_BAD_MODES,
-                        "Invalid mode for this access control list"
-        end
-@end example
-@node The error-table compiler, Run-time support routines, Error table source file, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@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{}) containing an error table source file.  It parses the
-error table, and generates two output files -- a C header file
-(@samp{discuss_err.h}) which contains definitions of the numerical values
-of the error codes defined in the error table, and a C source file which
-should be compiled and linked with the executable.  The header file must be
-included in the source of a module which wishes to reference the error
-codes defined; the object module generated from the C code may be linked in
-to a program which wishes to use the printed forms of the error codes.
-This translator accepts a @kbd{-language @var{lang}} argument, which
-determines for which language (or language variant) the output should be
-written.  At the moment, @var{lang} is currently limited to @kbd{ANSI-C}
-and @kbd{K&R-C}, and some abbreviated forms of each.  Eventually, this will
-be extended to include some support for C++.  The default is currently
-@kbd{K&R-C}, though the generated sources will have ANSI-C code
-conditionalized on the symbol @t{__STDC__}.
-@node Run-time support routines, Coding Conventions, The error-table compiler, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@section Run-time support routines
-Any source file which uses the routines supplied with or produced by the
-com_err package should include the header file @file{<com_err.h>}.  It
-contains declarations and definitions which may be needed on some systems.
-(Some functions cannot be referenced properly without the return type
-declarations in this file.  Some functions may work properly on most
-architectures even without the header file, but relying on this is not
-The run-time support routines and variables provided via this package
-include the following:
-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.
-#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
-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.
-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.
-#include <stdarg.h>
-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).
-#include <stdarg.h>
-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:
-#include <stdio.h>
-#include <stdarg.h>
-#include <syslog.h>
-/* extern openlog (const char * name, int logopt, int facility); */
-/* extern syslog (int priority, char * message, ...); */
-void hook (const char * whoami, long code,
-           const char * format, va_list args)
-    char buffer[BUFSIZ];
-    static int initialized = 0;
-    if (!initialized) @{
-        openlog (whoami,
-                 LOG_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).
-@node Coding Conventions, Building and Installation, Run-time support routines, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@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
-Routines which use the first style of interface can be used from
-user-interface levels of a program as follows:
-    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
-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.
-    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;
-    if (f1) fclose(f1);
-    if (f2) fclose(f2);
-    if (f3) fclose(f3);
-    return status;
-@end example
-@node Building and Installation, Bug Reports, Coding Conventions, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@section Building and Installation
-The distribution of this package will probably be done as a compressed
-``tar''-format file available via anonymous FTP from SIPB.MIT.EDU.
-Retrieve @samp{pub/com_err.tar.Z} and extract the contents.  A subdirectory
-@t{profiled} should be created to hold objects compiled for profiling.
-Running ``make all'' should then be sufficient to build the library and
-error-table compiler.  The files @samp{libcom_err.a},
-@samp{libcom_err_p.a}, @samp{com_err.h}, and @samp{compile_et} should be
-installed for use; @samp{com_err.3} and @samp{compile_et.1} can also be
-installed as manual pages.
-Potential problems:
-@itemize @bullet
-@item Use of @code{strcasecmp}, a routine provided in BSD for
-case-insensitive string comparisons.  If an equivalent routine is
-available, you can modify @code{CFLAGS} in the makefile to define
-@code{strcasecmp} to the name of that routine.
-@item Compilers that defined @code{__STDC__} without providing the header
-file @code{<stdarg.h>}.  One such example is Metaware's High ``C''
-compiler, as provided at Project Athena on the IBM RT/PC workstation; if
-@code{__HIGHC__} is defined, it is assumed that @code{<stdarg.h>} is not
-available, and therefore @code{<varargs.h>} must be used.  If the symbol
-@code{VARARGS} is defined (e.g., in the makefile), @code{<varargs.h>} will
-be used.
-@item If your linker rejects symbols that are simultaneously defined in two
-library files, edit @samp{Makefile} to remove @samp{perror.c} from the
-library.  This file contains a version of @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.
-@node Bug Reports, Acknowledgements, Building and Installation, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@section Bug Reports
-Please send any comments or bug reports to the principal author: Ken
-Raeburn, @t{Raeburn@@Athena.MIT.EDU}.
-@node Acknowledgements, , Bug Reports, (dir)
-@comment  node-name,  next,  previous,  up
-@end ifinfo
-@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.