ERRNO - error indicator variable.

(ANSI Standard)

Usage:

extern int errno;

Description:

"errno" is a library variable used in error reporting. Library routines that encounter an error usually return some kind of result value that indicates an error. If the error can come from several different sources, the library routine that found the error may assign a value to "errno" to indicate the kind of error that occurred. User programs may check the value of "errno" to find out what happened.

In SS mode GCOS8, "errno" has three possible formats:

FMS Errors
For an FMS error (accessing or opening a file), the upper 18 bits of the value are zero, and the lower 18 bits are the major error status, as returned by FMS.
I/O Errors
For an I/O error (performing I/O on an open file), the upper 18 bits contain the integer value 1 and the lower 18 bits contain the major error status, as returned by the underlying I/O package.
Library Errors
For an error detected by the C library (e.g. trying to use "sqrt" to take the square root of a negative number), the upper 18 bits contain the integer value 3 and the lower 18 bits contain a value assigned by the library.

This arrangement means that there are significant differences between "errno" values on GCOS8 and on UNIX. On UNIX, possible "errno" values are assigned sequentially, beginning at 1, and have no relation to any operating system constructs.

Notes:

The "errno" concept has some flaws. First, many library routines do not use it. Second, "errno" values often have different meanings in different contexts. This is particularly a problem when library routine A calls library routine B. If B sets "errno", returns to A and A returns to the caller, the caller will interpret the "errno" value in the context of A and that may not be what B meant at all.

None of the library routines ever set "errno" to zero (indicating no error). This also causes confusion. For example, suppose your program calls a routine that sets "errno" but you do not check the "errno" value. Later on, you call another routine which works perfectly, but afterwards you check the "errno" value and find it is non-zero. Your program will believe that the error came from the good routine, even though it actually occurred much earlier.

Finally, the value of "errno" can change underneath your program when interrupts and other signals are received. For example, suppose that a library function sets "errno" to indicate some kind of error; however, before your program has a chance to check this value of "errno", an interrupt occurs because the user presses BREAK. The value of "errno" will change to reflect the interrupt, and the previous value of "errno" is lost. Even if your program eventually resumes execution at the point where the interrupt occurred, the first value of "errno" is not restored and the program has no way of knowing that the first error occurred. The same thing happens when you explicitly use "signal" to generate an event.

All of this demonstrates that the "errno" concept is less than reliable. However, it is the error reporting scheme used by UNIX and the ANSI standard, and compatibility demands that it be supported. Be very careful when using it. In particular, if you are going to check it after calling a function to see if an error has occurred, explicitly set it to zero before calling the function...or test it to see if it is non-zero before the call and decide whether execution is worth continuing at all if some unknown error has taken place undetected.

If you do not have to worry about porting the program to other systems, we recommend that you use the GCOS8-specific error handling routines of the UW Tools library (e.g. IO.ERROR, __PERR, and so on). These retain more error information than "errno" and make it easier to issue relevant diagnostic messages. You should also investigate the use of the "e" option of "fopen", which provides better error diagnostics in the case of an error on the file being opened. lets you open files in a way that provides for better error recovery than "fopen".

See Also:

expl c lib perror
prints an error message to "stderr" based on the current "errno" value.
expl c lib strerror
returns a string giving an error message describing the current "errno" value.
expl c lib fopen
for information on the "e" option.
expl b lib io.err
prints an error message describing the most recent I/O error on an open unit.
expl b lib .perror
like "perror" but takes advantage of the error posting facilities of the UW Tools library.
expl b lib .strerror
like "strerror" but takes advantage of the error posting facilities of the UW Tools library.

Copyright © 1996, Thinkage Ltd.