Linux libc-doc

Files
file	errno.h

Variables
int	errno
	Error code set by various library functions.

Detailed Description

The errno variable is an integer variable and set by system calls and library functions to indicate the source of an error. The errno is undefined, except when a system call or library function indicates an error (e.g., by a special return value) and the corresponding manpage states that in case of an error the errno variable is set. From this follows that the value of the errno is undefined after a successful call to a system call or library function. Furthermore, no system call or library functions sets the errno to 0.

There are rare cases, where the errno is not only used to indicate the source of an error, but is also used to detect an error (e.g., readdir()). If the errno is used to detect an error (and not, as usually, the return value) it is explicitly stated in the manpages. In this case the errno must be manually set to 0 before calling the function to be able to check if the function changed the value. Except for these rare cases setting the errno manually is never correct, unless one is writing a library function (e.g., malloc()).

The errno variable is a thread-local variable, which means every POSIX thread has a separate errno. Hence, the access of errno must not be synchronized against other POSIX threads.

Wrong usage of errno:

char *s = malloc(1024);
if (s == NULL) {
    fprintf(stderr, "malloc: ");
  
    // now the errno is undefined, because of a successful
    // or unsuccessful call to fprintf()
  
    // wrong: strerror() uses an undefined value to generate the string
    fprintf(stderr, "%s\n", strerror(errno));
    exit(EXIT_FAILURE);
}

char *s = malloc(1024);
if (s == NULL) {
    // wrong: original errno value is overwritten!
    errno = ENOMEM;
    perror("malloc");
    exit(EXIT_FAILURE);
}

errno = 0; // wrong: setting errno has no effect here
char *s = malloc(1024);
if (errno != 0) {
    // wrong: errno can be != 0 even if malloc() is successful
    // NOTE: There are rare exceptions (e.g., readdir()).
    perror("malloc");
    exit(EXIT_FAILURE);
}

Correct usage of errno:

char *s = malloc(1024);
if (s == NULL) {
    perror("malloc");
    exit(EXIT_FAILURE);
}

errno = 0;
struct dirent *entry = readdir(dirp);
if (entry != NULL) {
    // process entry
} else if (errno != 0) { // explicitly stated in man page
    perror("readdir");
    exit(EXIT_FAILURE);
}

Files

Variables

Detailed Description