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: Printed 3/13/89 1
ERROR(3C) COMMAND REFERENCE ERROR(3C) program : user_message (tag) 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. Printed 3/13/89 2
ERROR(3C) COMMAND REFERENCE ERROR(3C) If the environment variable NOTAGS is set, no tags will be printed. 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 Printed 3/13/89 3
ERROR(3C) COMMAND REFERENCE ERROR(3C) 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". 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 Printed 3/13/89 4
ERROR(3C) COMMAND REFERENCE ERROR(3C) SEE ALSO msghlp(1), sh(1sh), intro(2), abort(3c), crt0(3c), exit(3c), fopen(3s), printf(3s), and errtag(5). Printed 3/13/89 5
%%index%% na:288,85; sy:373,1318; de:1691,2727;4778,3481;8619,3654;12633,61; ex:12694,876; va:13570,272; ca:13842,892; se:15094,355; %%index%%000000000156