Randal E. Bryant - Computer Systems: A Programmer’s Perspective

Programmers should always check the error codes returned by system-level functions. There are many subtle ways that things can go wrong, and it only makes sense to use the status information that the kernel is able to provide us. Unfortunately, programmers are often reluctant to do error checking because it clutters their code, turning a single line of code into a multi-line conditional statement. Error checking is also confusing because different functions indicate errors in different ways.

We were faced with a similar problem when writing this text. On the one hand, we would like our code examples to be concise and simple to read. On the other hand, we do not want to give students the wrong impression that it is OK to skip error checking. To resolve these issues, we have adopted an approach based on error-handling wrappers that was pioneered by W. Richard Stevens in his network programming text [110].

The idea is that given some base system-level function foo, we define a wrapper function Foo with identical arguments, but with the first letter capitalized. The wrapper calls the base function and checks for errors. If it detects an error, the wrapper prints an informative message and terminates the process. Otherwise, it returns to the caller. Notice that if there are no errors, the wrapper behaves exactly like the base function. Put another way, if a program runs correctly with wrappers, it will run correctly if we render the first letter of each wrapper in lowercase and recompile.

The wrappers are packaged in a single source file (csapp.c) that is compiled and linked into each program. A separate header file (csapp.h) contains the function prototypes for the wrappers.

This appendix gives a tutorial on the different kinds of error handling in Unix systems and gives examples of the different styles of error-handling wrappers. Copies of the csapp.h and csapp.c files are available at the CS:APP Web site.

The systems-level function calls that we will encounter in this book use three different styles for returning errors: Unix-style, Posix-style, and GAI-style.

Functions such as fork and wait that were developed in the early days of Unix (as well as some older Posix functions) overload the function return value with both error codes and useful results. For example, when the Unix-style wait function encounters an error (e.g., there is no child process to reap), it returns -1 and sets the global variable errno to an error code that indicates the cause of the error. If wait completes successfully, then it returns the useful result, which is the PID of the reaped child. Unix-style error-handling code is typically of the following form:

The strerror function returns a text description for a particular value of errno.

Many of the newer Posix functions such as Pthreads use the return value only to indicate success (zero) or failure (nonzero). Any useful results are returned in function arguments that are passed by reference. We refer to this approach as Posix-style error handling. For example, the Posix-style pthread_create function indicates success or failure with its return value and returns the ID of the newly created thread (the useful result) by reference in its first argument. Posix-style error-handling code is typically of the following form:

The strerror function returns a text description for a particular value of retcode.

The getaddrinfo (GAI) and getnameinfo functions return zero on success and a nonzero value on failure. GAI error-handling code is typically of the following form:

The gai_strerror function returns a text description for a particular value of retcode.

Thoughout this book, we use the following error-reporting functions to accommodate different error-handling styles.

As their names suggest, the unix_error, posix_error, and gai_error functions report Unix-style, Posix-style, and GAI-style errors and then terminate. The app_error function is included as a convenience for application errors. It simply prints its input and then terminates. shows the code for the error-reporting functions.

Here are some examples of the different error-handling wrappers.

• Unix-style error-handling wrappers. shows the wrapper for the Unix-style kill function. Notice that this function, unlike wait, returns void on success.

• Posix-style error-handling wrappers. shows the wrapper for the Posix-style pthread_detach function. Like most Posix-style functions, it does not overload useful results with error-return codes, so the wrapper returns void on success.

• GAI-style error-handling wrappers. shows the error-handling wrapper for the GAI-style getaddrinfo function.

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c

-------------------------------------------code/src/csapp.c