Determining Success or Failure

When a C function is called, the programmer is interested in two things upon its return:

• Did the function call succeed?

• If not, why did the call fail?

General Rules for Error Indication

The UNIX convention used by most system calls and library functions is that the return value indicates a general success or failure. Return values fall into two major categories:

• The return value is an integer value (int or long). Normally failure is indicated by a value of negative one (-1).

• The return value is a pointer type, such as pointers (char *), (void *) or a pointer to a structure. Failure is indicated by a null return pointer and success by a non-null pointer.

Exceptions to the General Rule

There are exceptions to the general rule just listed, but these are rare. When the functions wait(2), waitpid(2), wait3(2), and wait4(2) return an error indication, they return the integer value (pid_t)(-1). This is similar to the integer return case, except that the value -1 is returned in a process ID data type.

An exception to the pointer rule is the shmat(2) function call. When it returns an error indication, it returns the pointer value (void *)(-1).

Unusual exceptions to the general rule can be found in the functions strtol(3), strtoul(3), and strtod(3), which return special values like LONG_MIN, LONG_MAX, ULONG_MAX, +HUGE_VAL, and -HUGE_VAL. These will be covered in detail in Chapter 10, "Conversion Functions."

Classifying Successful Return Values

For integer return values, a successful return value is normally anything other than -1. Often this is a value that is greater than or equal to zero. For example, the UNIX open(2) call returns a file descriptor number that can be zero or greater.

For pointer return values, a successful return value is normally a non-null pointer. An example is the fopen(3) function, which returns a pointer to a FILE object.

As noted previously, under unusual circumstances the null pointer can indicate a successful return from certain exceptional functions (recall shmat(2)). For this reason, the best programming practice is for the programmer to test for failure indication upon return from a function. Anything that does not classify as a failure should be considered a successful indication.

Other Return Indications

Before leaving the topic of function return indications, it is worth pointing out that some functions offer a third indication, in addition to the normal success or failure. These generally fall into two categories:

• No more information exists (examples include waitpid(2), wait3(2), wait(4)).

• A timeout has occurred without returning any "interesting" event (examples include select(2), poll(2)).

In these examples, the designers of these functions have decided not to treat the "no information" or "timeout" case as an error. At the same time, these cases cannot be considered successful returns, since either no information is returned or a timeout has occurred.

This type of indication can be treated as an error by the programmer, with the exception that there will be no value provided in the global variable errno.