Managing Failures

In most cases, [2] if a system call or library function is unsuccessful , it returns a value of -1 and assigns a value to an external (global) variable called errno to indicate what the actual error is. The defined constants for all error codes can be found in the header file (or in on some systems). By convention, the defined constants are in uppercase and start with the letter E . It is a good habit to have the invoking program examine the return value from a system call or library function to determine if it was successful. If the invocation fails, the program should take an appropriate action. A common action is to display a short error message and exit (terminate) the program. The library function perror can be used to produce an error message.

[2] This type of hedging is necessary, since system calls/library functions that return an integer value usually return a -1 on failure, while those that return a pointer return a NULL pointer. However, as these routines are written by a disjointed set of programmers with differing ideas on what should be done, a return value that does not meet this rule of thumb is occasionally encountered .

For each system call and library function discussed in detail in the text, a summary table is given. The summary table is a condensed version of manual page information. The format of a typical summary table (in this case the one for perror ) is shown in Figure 1.5.

Figure 1.5. Explanation of the summary table format.

The summary table for perror indicates the header file must be included if we are to use perror . Notice that the header file , which was mentioned previously, is not referenced in the summary table. The file is included only if the defined constants for specific error codes are to be referenced. The perror library function takes a single argument, which is a pointer to a character string constant (i.e., const char * ). In addition, the perror library function does not return a value (as indicated by the data type void ) and will not modify errno if it itself fails.

A program example using systems calls that provides some error checking by perror and errno is shown in Program 1.2.

Program 1.2 Using errno and perror .

File : p1.2.cxx /* Checking errno and using perror */ #include + #include // needed for perror #include // needed for exit #include // needed for read and write using namespace std; extern int errno; 10 int main(int argc, char *argv[ ]) { int n_char = 0, // # of chars read buffer[10]; // temporary buffer + // Initially n_char is set to 0 and errno is 0 by default cout << "n_char = " << n_char << " errno = " << errno << endl; // Display a prompt to stdout 20 n_char = write(1, "Enter a word: ", 15); // Use the read system call to obtain 10 characters from stdin + n_char = read(0, buffer, 10); cout << "n_char = " << n_char << " errno = " << errno << endl; if (n_char == -1) { // If the read has failed perror(argv[0]); 30 exit(1); } n_char = write(1, buffer, n_char); // Display the characters read return 0; + }

Notice that to use the errno variable it must first be declared as an external ( extern ) integer at the top of the program. If this program is run, the initial output indicates that both n_char and errno contain the value 0. Figure 1.6 shows the output if the user enters the word testing when prompted.

Figure 1.6 Initial run of Program 1.2 with no errors.

linux$ p1.2 n_char = 0 errno = 0 Enter a word: testing n_char = 8 errno = 0 testing

In this case the read system call did not fail and has instead, as defined in the manual page, returned the number of characters read from standard input (the keyboard). Note, as we have used read in the program, not cin , the newline will be one of the characters that is read and counted. As there was no error, the value in errno was not modified and remained at 0. Figure 1.7 shows the output if we run the program again and input more than 10 characters when prompted (in hopes of generating an error).

Figure 1.7 Second run of Program 1.2 with additional keyboard input.

$ p1.2 n_char = 0 errno = 0 Enter a word: testing further n_char = 10 errno = 0 testing fu$rther rther: Command not found.

This time the program reads exactly 10 characters and displays them. The remaining characters are left in the input buffer and end up being processed by the operating system after the program finishes execution. This produces the output of the strange line testing fu$rther followed by the line rther: Command not found . The characters testing fu are displayed by the program. The Command not found message is generated by the operating system when it attempts to execute the leftover input rther as a command. In this case, providing more input values than needed (i.e., extra characters) does not cause the read system call to fail, and as a result errno is not changed.

However, if we change the file number for the read system call to 3 (a file number that has not been opened versus [standard input] which is automatically opened for us by the operating system when the program runs), the read system call will fail. When run, the program output will be as shown in Figure 1.8.

Figure 1.8 Third run of Program 1.2 with an induced error.

linux$ p1.2 n_char = 0 errno = 0 Enter a word: n_char = -1 errno = 9 p1.2: Bad file descriptor

As expected, this time the return value from the read system call is -1. The external variable errno now contains the value 9 that is equivalent to the symbolic constant EBADF defined in the file. [3] If we call perror with a NULL argument, "", the message "Bad file descriptor" will be displayed (the error message the system associates with error code 9). As noted, perror does take one argument: a character pointer. If passed a character pointer to a valid string, perror will display the referenced string followed by a colon ( : ) and then append its predefined error message. Programmers often use the argument to perror to qualify the error message (e.g., to pass the name of the executing program, as was done in the prior example) or in the case of file manipulation, pass the name of the current file. Unfortunately, perror issues a new line following the error message it produces, thus preventing the user from appending additional information to the perror display line. There are two ways around this oversight.

[3] Again, in some Linux environments you may find that this constant is actually defined in the errno.h include file located in the directory /usr/include/asm directory.

Associated with perror are two additional external variables. These variables are extern const char *sys_errlist[ ] and extern int sys_nerr . The external variable sys_nerr contains a value that is one greater than the largest error message number value, while sys_errlist is a pointer to an external character array of error messages. In place of calling perror to return the specific error, we may (if we have provided the proper declarations) use the value in errno to index the sys_errlist[ ] array to obtain the error message directly.

Another approach to error message generation is to use the library function strerror (see Table 1.2).

Table 1.2. Summary of the strerror Library Function.

The strerror function maps the integer errnum argument (which is usually the errno value) to an error message and returns a reference to the message. The error message generated by strerror should be the same as the message generated by perror . If needed, additional text can be appended to the string returned by strerror .

Furthermore, Linux provides a command-line utility program called perror that returns the error message associated with a specific error code. A sample call of this utility follows :

linux$ perror 9 Error code 9: Bad file descriptor

Note that the system never clears the errno variable (even after a successful system call). It will always contain the value assigned by the system for the last failed call. Appendix B, " Linux Error Messages ," contains additional information on error messages.