ERROR(3C) COMMAND REFERENCE ERROR(3C)
NAME
ERROR - an error handling routine
SYNOPSIS
#include <errdefs.h>
ERROR (exitcode, tag, outcode, format, args)
int exitcode
char *tag
out_code is a macro described in the section Output Codes.
char *format
DESCRIPTION
ERROR prints error messages in standard formats and keeps
track of warnings. This subroutine works with special
versions of exit(3c) and crt0(3c). Each of the arguments is
described in the sections below.
Exit codes
The first argument to ERROR is the exit code number. Some
special exit codes are defined in the include file
errdefs.h. The following paragraphs describe the actions and
error message formats for different exit codes. In these
sections, program refers to the basename of the program
calling ERROR, user_message refers to the message text given
by the format and args arguments given to ERROR, and
systemmessage refers to the message from the system error
list which corresponds to the system error which occurred
before the call to ERROR (see intro(2) for a more detailed
description of these messages). The exit code descriptions
also refer to the "warning code". This is described in the
Exit Interface section.
The exit code NOERRS has the value 0. This causes the
warning code to be set to 0, and no message is printed.
Exit codes from 1 to 120 are not special to ERROR and should
be used to give useful information to the user via the exit
code. These codes cause the warning code to be set to the
value of the exit code and an error message to be printed.
The error messages produced for these codes are in the
format:
program : user_message (tag)
The exit code NOCMD is used by the program sh(1sh) to
signal that the given command could not be executed.
The exit code NPWARN causes the warning code to be set to
the value of NPWARN and a message to be printed in the
format:
program : user_message (tag)
Printed 10/17/86 1
ERROR(3C) COMMAND REFERENCE ERROR(3C)
The exit code NPERR causes the program to exit with the
value of NPWARN after printing a message in the format:
program : user_message (tag)
The exit code PWARN is used to print a warning message when
a system call such as open(2) fails. This code causes the
warning code to be set to the value of PWARN and a message
to be printed in the format:
program : user_message : system_message (tag)
The exit code PERR is used to print an error message when a
system call such as open(2) fails. This code causes the
program to exit with the value of PERR after printing a
message in the format:
program : user_message : system_message (tag)
The exit code USAGE is used to print a synopsis of the
command line syntax of the program. This code causes the
program to exit with the value of USAGE after printing a
message in the format:
program : usage : program user_message
The exit code INTERNAL is used to print error messages when
an error occurs that should never occur. This code causes
the program to dump core and exit after printing a message
in the format:
program : INTERNAL ERROR : user_message (tag)
At line line_number in Source file source_file
Tags
The second argument to ERROR is a special 'tag' which is
printed in parentheses after the error message. This tag is
an index into the verbose error message utilities, about
which very little is currently known.
If the exit_code argument is either PWARN or PERR and the
tag argument has a value of NULL or "" (the null string),
the tag printed will be '(sys#)', where '#' is the system
error number (errno). Otherwise, a null tag will cause no
tag to be printed.
If the exit_code argument is USAGE, the tag argument is
ignored.
If the environment variable NOTAGS is set, no tags will be
printed.
Printed 10/17/86 2
ERROR(3C) COMMAND REFERENCE ERROR(3C)
Output Codes
The output code argument tells ERROR whether or not to print
a message, and where to print it. The output codes are
described in the include file errdefs.h. These codes are
macros which send the output code number, the source code
file name and the line number to ERROR, and only these
macros should be used. The defined output codes and
corresponding actions are described in the next three
paragraphs.
The output code OERR tells ERROR to print the error message
on standard error.
The output code OERROUT tells ERROR to print the error
message on the standard output.
The output code NOOUT tells ERROR not to print any error
message.
User Error Messages (format and args)
The user may specify the error message to be printed by
providing a format and arguments in the same way as with
printf(3s). Unless the output code is NOOUT, a format must
be specified, even if it is null.
Debugging with ERROR
ERROR has a special feature which can be useful while
debugging programs. To use this feature, programs must be
compiled with the macro ERROR_DEBUG defined. When the
environment variable PRLINE is set, each error message is
followed by a line of the format:
At line line_number in Source file source_file
The source file is the file containing the call to ERROR and
the line number is the line on which ERROR is called.
Exit Interface
When ERROR is called with an exit code that does not cause
an immediate exit, such as NPWARN, an internal warning code
is set. When the program exits by calling the subroutine
exit with a value of NOERRS, or via the C statement return
with a value of NOERRS, the exit code is replaced by the
value of the internal warning code. This way, programs do
not need to keep track of warnings and programs that print
warning messages do not always exit with a value of 0.
EXAMPLES
The following example shows a use of ERROR with the PWARN
exit code. Assume that the program is called "example".
Printed 10/17/86 3
ERROR(3C) COMMAND REFERENCE ERROR(3C)
char *file;
FILE *fp;
...
if ((fp = fopen(file, "r")) == NULL) {
ERROR (P_WARN, "open1", O_ERR, "%s", file);
}
...
exit (NO_ERRS);
}
In this case, if the program tried to open the file "foo"
for reading and the file did not exist, the message:
example : foo : No such file or directory
would be printed. When the program exits, the exit code
would be the value of PWARN.
VARIABLES
PRLINE Causes the source file name and line number
to be printed after any message.
NOTAGS Suppresses the printing of tags.
CAVEATS
If the format or its arguments are invalid, errors will
occur. No attempt is made to check the validity of these
arguments. For example, the call:
ERROR (P_ERR, "open1", O_ERR, file);
may cause problems if the string file contains any '%'
characters.
If a null format is given to ERROR with the exit codes
PWARN or PERR, the error message will contain two colons
separated by a space. For example, the code fragment :
if ((fp = fopen ("file", "r")) == NULL) {
ERROR (P_WARN, "open1", O_ERR, "");
}
Will print the error message :
program : : No such file or directory
SEE ALSO
msghlp(1), sh(1sh), intro(2), abort(3c), crt0(3c), exit(3c),
fopen(3s), printf(3s), errtag(5).
Printed 10/17/86 4
%%index%%
na:72,69;
sy:141,884;
de:1025,2525;3694,3056;6894,3045;
ex:9939,230;10313,564;
va:10877,236;
ca:11113,818;
se:11931,274;
%%index%%000000000154