The child “inherits” identical copies of a large number of attributes from the parent. Many of these attributes are specialized and irrelevant here. Thus, the following list in purposely incomplete. The following attributes are the relevant ones:

The attributes that the child inherits from the parent are all set to the same values they had in the parent at the time of the fork(). From then on, though, the two processes proceed on their merry ways, (mostly) independent of each other. For example, if the child changes directory, the parent’s directory is not affected. Similarly, if the child changes its environment, the parent’s environment is not changed.

Open files are a significant exception to this rule. Open file descriptors are shared, and an action by one process on a shared file descriptor affects the state of the file for the other process as well. This is best understood after study of Figure 9.1.

Figure 9.1. File descriptor sharing

The figure displays the kernel’s internal data structures. The key data structure is the file table. Each element refers to an open file. Besides other bookkeeping data, the file table maintains the current position (read/write offset) in the file. This is adjusted either automatically each time a file is read or written or directly with lseek() (see Section 4.5, “Random Access: Moving Around within a File,” page 102).

The file descriptor returned by open () or creat() acts as an index into a per-process array of pointers into the file table. This per-process array won’t be any larger than the value returned by getdtablesize() (see Section 4.4.1, “Understanding File Descriptors,” page 92).

Figure 9.1 shows two processes sharing standard input and standard output; for each, both point to the same entries in the file table. Thus, when process 45 (the child) does a read(), the shared offset is updated; the next time process 42 (the parent) does a read(), it starts at the position where process 45’s read() finished.

This can be seen easily at the shell level:

$ cat data                                   Show demo data file contents
line 1
line 2
line 3
line 4
$ ls -1 test1 ; cat test1                    Mode and contents of test program
-rwxr-xr-x 1 arnold devel 93 Oct 20 22:11 test1
#! /bin/sh
read line ; echo p: $line                    Read a line in parent shell, print it
( read line ; echo c: $line )                Read a line in child shell, print it
read line ; echo p: $line                    Read a line in parent shell, print it
$ test1 < data                               Run the program
p: line 1                                    Parent starts at beginning
c: line 2                                    Child picks up where parent left off
p: line 3                                    Parent picks up where child left off

The first executable line of test1 reads a line from standard input, changing the offset in the file. The second line of test1 runs the commands enclosed between the parentheses in a subshell. This is a separate shell process created—you guessed it—with fork(). The child subshell inherits standard input from the parent, including the current file offset. This process reads a line and updates the shared offset into the file. When the third line, back in the parent shell, reads the file, it starts where the child left off.

Although the read command is built into the shell, things work the same way with external commands. Some early Unix systems had a line command that read one line of input (one character at a time!) for use within shell scripts; if the file offset weren’t shared, it would be impossible to use such a command in a loop.

File descriptor sharing and inheritance play a pivotal role in shell I/O redirection; the system calls and their semantics make the shell-level primitives straightforward to implement in C, as we see later in the chapter.

The fact that multiple file descriptors can point at the same open file has an important consequence: A file is not closed until all its file descriptors are closed.

We see later in the chapter that multiple descriptors for the same file can exist not only across processes but even within the same process; this rule is particularly important for working with pipes.

If you need to know if two descriptors are open on the same file, you can use fstat() (see Section 5.4.2, “Retrieving File Information,” page 141) on the two descriptors with two different struct stat structures. If the corresponding st_dev and st_ino fields are equal, they’re the same file.

We complete the discussion of file descriptor manipulation and the file descriptor table later in the chapter.

The nice value range of -20, to 19 that Linux uses is historical; it dates back at least as far as V7. POSIX expresses the situation in more indirect language, which allows for implementation flexibility while maintaining historical compatibility. It also makes the standard harder to read and understand, but then, that’s why you’re reading this book. So, here’s how POSIX describes it.

First, the process’s nice value as maintained by the system ranges from 0 to ’(2 * NZERO) - 1’. The constant NZERO is defined in <limits.h> and must be at least 20. This gives us the range 0–39.

Second, as we described, the sum of the current nice value and the incr increment is forced into this range.

Finally, the return value from nice() is the process nice value minus NZERO. With an NZERO value of 20, this gives us the original -20 to 19 range that we initially described.

The upshot is that nice()’s return value actually ranges from ’-NZERO’ to ’NZERO-1’, and it’s best to write your code in terms of that symbolic constant. However, practically speaking, you’re unlikely to find a system where NZERO is not 20.

The simplest function to explain is execve(). It is also the underlying system call. The others are wrapper functions, as is explained shortly.

int execve(const char *filename, char *const argv[], char *const envp[])

A call to exec() should not return. If it does, there was a problem. Most commonly, either the requested program doesn’t exist, or it exists but it isn’t executable (ENOENT and EACCES for errno, respectively). Many more things can go wrong; see the execve(2) manpage.

Assuming that the call succeeds, the current contents of the process’s address space are thrown away. (The kernel does arrange to save the argv and envp data in a safe place first.) The kernel loads the executable code for the new program, along with any global and static variables. Next, the kernel initializes the environment with that passed to execve(), and then it calls the new program’s main() routine with the argv array passed to execve(). It counts the number of arguments and passes that value to main() in argc.

At that point, the new program is running. It doesn’t know (and can’t find out) what program was running in the process before it. Note that the process ID does not change. Many other attributes remain in place across the exec; we cover this in more detail shortly.

In a loose analogy, exec() is to a process what life roles are to a person. At different times during the day, a single person might function as parent, spouse, friend, student or worker, store customer, and so on. Yet it is the same underlying person performing the different roles. So too, the process—its PID, open files, current directory, etc.—doesn’t change, while the particular job it’s doing—the program run with exec() —can.

Five additional functions, acting as wrappers, provide more convenient interfaces to execve(). The first group all take a list of arguments, each one passed as an explicit function parameter:

int execl(const char *path, const char *arg, ...).

int execlp(const char *file, const char *arg, ...)

int execle(const char *path, const char *arg, ..., char *const envp[])

The second group of wrapper functions accepts an argv style array:

int execv(const char *path, char *const argv [])

int execvp(const char *file, char *const argv[])

Table 9.1 summarizes the six exec() functions.

The execlp() and execvp() functions are best avoided unless you know that the PATH environment variable contains a reasonable list of directories.

Until now, we have always treated argv[0] as the program name. We know that it may or may not contain a / character, depending on how the program is invoked; if it does, then that’s usually a good clue as to the pathname used to invoke the program.

However, as should be clear by now, argv[0] being the filename is only a convention. There’s nothing stopping you from passing an arbitrary string to the exec’d program for argv [0]. The following program, ch09-run.c, demonstrates passing an arbitrary string:

 1  /* ch09-run.c --- run a program with a different name and any arguments */
 2
 3  #include <stdio.h>
 4  #include <errno.h>
 5  #include <unistd.h>
 6
 7  /* main --- adjust argv and run named program */
 8
 9  int main(int argc, char **argv)
10  {
11      char *path;
12
13      if (argc < 3) {
14          fprintf(stderr, "usage: %s path arg0 [ arg ... ]
", argv[0]);
15          exit(1);
16      }
17
18      path = argv[1];
19
20      execv(path, argv + 2); /* skip argv[0] and argv[1] */
21
22      fprintf(stderr, "%s: execv() failed: %s
", argv[0],
23          strerror(errno));
24      exit(1);
25  }

The first argument is the pathname of the program to run and the second is the new name for the program (which most utilities ignore, other than for error messages); any other arguments are passed on to the program being exec’d.

Lines 13–16 do error checking. Line 18 saves the path in path. Line 20 does the exec; if lines 22–23 run, it’s because there was a problem. Here’s what happens when we run the program:

$ ch09-run /bin/grep whoami foo                           Run grep
a line                                                    Input line doesn't match
a line with foo in it                                     Input line that does match
a line with foo in it                                     It's printed
^D                                                        EOF

$ ch09-run nonexistent-program foo bar                    Demonstrate failure
ch09-run: execv() failed: No such file or directory

This next example is a bit bizarre: we have ch09-run run itself, passing ’foo’ as the program name. Since there aren’t enough arguments for the second run, it prints the usage message and exits:

$ ch09-run ./ch09-run foo
usage: foo path arg0 [ arg ... ]

While not very useful, ch09-run clearly shows that argv[0] need not have any relationship to the file that is actually run.

In System III (circa 1980), the cp, In, and mv commands were one executable file, with three links by those names in /bin. The program would examine argv[0] and decide what it should do. This saved a modest amount of disk space, at the expense of complicating the source code and forcing the program to choose a default action if invoked by an unrecognized name. (Some current commercial Unix systems continue this practice!) Without stating an explicit reason, the GNU Coding Standards recommends that a program not base its behavior upon its name. One reason we see is that administrators often install the GNU version of a utility alongside the standard ones on commercial Unix systems, using a g prefix: gmake, gawk, and so on. If such programs expect only the standard names, they’ll fail when run with a different name.

Also, today, disk space is cheap; if two almost identical programs can be built from the same source code, it’s better to do it that way, using #ifdef or what-have-you. For example, grep and egrep share considerable code, but the GNU version builds two separate executables.

As with fork(), a number of attributes remain in place after a program does an exec:

After an exec, signal disposition changes; see Section 10.9, “Signals Across fork() and exec(),” page 398, for more information.

All open files and directories remain open and available after the exec. This is how programs inherit standard input, output, and error: They’re in place when the program starts up.

Most of the time, when you fork and exec a separate program, you don’t want it to inherit anything but file descriptors 0,1 and 2. In this case, you can manually close all other open files in the child, after the fork but before the exec. Alternatively, you can mark a file descriptor to be automatically closed by the system upon an exec; this latter option is discussed later in the chapter (see Section 9.4.3.1, “The Close-on-exec Flag,” page 329).

The exit status (also known variously as the exit value, return code, and return value) is an 8-bit value that the parent can recover when the child exits (in Unix parlance, “when the child dies”). By convention, an exit status of 0 means that the program ran with no problems. Any nonzero exit status indicates some sort of failure; the program determines the values to use and their meanings, if any. (For example, grep uses 0 to mean that it matched the pattern at least once, 1 to mean that it did not match the pattern at all, and 2 to mean that an error occurred.) This exit status is available at the shell level (for Bourne-style shells) in the special variable $?.

The C standard defines two constants, which are all you should use for strict portability to non-POSIX systems:

EXIT_SUCCESS

EXIT_FAILURE

In practice, using only these values is rather constraining. Instead, you should pick a small set of return codes, document their meanings, and use them. (For example, 1 for command-line option and argument errors, 2 for I/O errors, 3 for bad data errors, and so on.) For readability, it pays to use #defined constants or an enum for them. Having too large a list of errors makes using them cumbersome; most of the time the invoking program (or user) only cares about zero vs. nonzero.

When the binary success/failure distinction is adequate, the pedantic programmer uses EXIT_SUCCESS and EXIT_FAILURE. Our own style is more idiomatic, using the explicit constants 0 or 1 with return and exit(). This is so common that it is learned early on and quickly becomes second nature. However, you should make youR own decision for your own projects.

A program can terminate voluntarily in one of two ways: by using one of the functions described next or by returning from main(). (A third, more drastic, way, is described later, in Section 12.4, “Committing Suicide: abort(),” page 445.) In the latter case, you should use an explicit return value instead of falling off the end of the function:

/* Good: */                          /* Bad: */
int main(int argc, char **argv)      int main(int argc, char **argv)
{                                    {
    /* code here */                      /* code here */
    return 0;                            /* ?? What does main() return ?? */
}                                    }

The 1999 C standard indicates that when main() returns by falling off the end, the behavior is as if it had returned 0. (This is also true for C++; however, the 1989 C standard leaves this case purposely undefined.) In all cases, it’s poor practice to rely on this behavior; one day you may be programming for a system with meager C runtime support or an embedded system, or somewhere else where it will make a difference. (In general, falling off the end of any non-void function is a bad idea; it can only lead to buggy code.)

The value returned from main() is automatically passed back to the system, from which the parent can recover it later. We describe how in Section 9.1.6.1, “Using POSIX Functions: wait() and waitpid(),” page 306.

The other way to voluntarily terminate a program is by calling an exiting function. The C standard defines the following functions:

#include <stdlib.h>                                         ISO C

void exit(int status);
void _Exit(int status);
int atexit(void (*function) (void));

The functions work as follows:

void exit(int status)

void _Exit(int status)

int atexit(void (*function) (void))

The following program does no useful work, but it does demonstrate how atexit() works:

/* ch09-atexit.c --- demonstrate atexit().
                     Error checking omitted for brevity. */
/*
 * The callback functions here just answer roll call.
 * In a real application, they would do more.
 */

void callback1(void) { printf("callback1 called
"); }
void callback2(void) { printf("callback2 called
"); }
void callback3(void) { printf("callback3 called
"); }

/* main --- register functions and then exit */

int main(int argc, char **argv)
{
    printf("registering callback1
");  atexit(callback1);
    printf("registering callback2
");  atexit(callback2);
    printf("registering callback3
");  atexit(callback3);

    printf("exiting now
");
    exit(0);
}

Here’s what happens when it’s run:

$ ch09-atexit
registering callback1           Main program runs
registering callback2
registering callback3
exiting now
callback3 called                Callback functions run in reverse order
callback2 called
callback1 called

As the example demonstrates, functions registered with atexit() run in the reverse order in which they were registered: most recent one first. (This is also termed last-in first-out, abbreviated LIFO.)

POSIX defines the _exit() function. Unlike exit(), which invokes callback functions and does <stdio.h> cleanup, _exit() is the “die immediately” function:

#include <unistd.h>                                  POSIX

void _exit(int status);

The status is given to the system, just as for exit(), but the process terminates immediately. The kernel still does the usual cleanup: All open files are closed, the memory used by the address space is released, and any other resources the process was using are also released.

In practice, the ISO C _Exit() function is identical to _exit(). The C standard says it’s implementation defined as to whether _Exit() calls functions registered with atexit() and closes open files. For GLIBC systems, it does not, behaving like _exit().

The time to use _exit() is when an exec fails in a forked child. In this case, you don’t want to use regular exit(), since that flushes any buffered data held by FILE* streams. When the parent later flushes its copies of the buffers, the buffered data ends up being written twice; obviously this is not good.

For example, suppose you wish to run a shell command and do the fork and exec yourself. Such code would look like this:

char *shellcommand = "...";
pid_t child;

if ((child = fork()) == 0) { /* child */
    execl("/bin/sh", "sh", "-c", shellcommand, NULL);
    _exit(errno == ENOENT ? 127 : 126);
}
/* parent continues */

The errno test and exit values follow conventions used by the POSIX shell. If a requested program doesn’t exist (ENOENT—no entry for it in a directory), then the exit value is 127. Otherwise, the file exists but couldn’t be exec’d for some other reason, so the exit status is 126. It’s a good idea to follow this convention in your own programs too.

Briefly, to make good use of exit() and atexit(), you should do the following:

The original V7 system call was wait(). The newer POSIX call, based on BSD functionality, is waitpid(). The function declarations are:

#include <sys/types.h>                                              POSIX
#include <sys/wait.h>

pid_t wait (int *status);
pid_t waitpid (pid_t pid, int *status, int options);

wait() waits for any child process to die; the information as to how it died is returned in *status. (We discuss how to interpret *status shortly.) The return value is the PID of the process that died or -1 if an error occurred.

If there is no child process, wait() returns -1 with errno set to ECHILD (no child process). Otherwise, it waits for the first child to die or for a signal to come in.

The waitpid() function lets you wait for a specific child process to exit. It provides considerable flexibility and is the preferred function to use. It too returns the PID of the process that died or -1 if an error occurred. The arguments are as follows:

pid_t pid

int *status

int options

WNOHANG

WUNTRACED

WCONTINUED

Multiple macros work on the filled-in *status value to determine what happened. They tend to come in pairs: one macro to determine if something occurred, and if that macro is true, one or more macros that retrieve the details. The macros are as follows:

WIFEXITED (status)

WEXITSTATUS (status)

WIFSIGNALED (status)

WTERMSIG (status)

WIFSTOPPED (status)

WSTOPSIG (status)

WIFCONTINUED (status)

WCOREDUMP (status)

Most programs don’t care why a child process died; they merely care that it died, perhaps noting if it exited successfully or not. The GNU Coreutils install program demonstrates such straightforward use of fork(), execlp(), and wait(). The -s option causes install to run the strip program on the binary executable being installed. (strip removes debugging and other information from an executable file. This can save considerable space, relatively speaking. On modern systems with multi-gigabyte disk drives, it’s rarely necessary to strip executables upon installation.) Here is the strip() function from install.c:

513  /* Strip the symbol table from the file PATH.
514     We could dig the magic number out of the file first to
515     determine whether to strip it, but the header files and
516     magic numbers vary so much from system to system that making
517     it portable would be very difficult. Not worth the effort. */
518
519  static void
520  strip (const char *path)
521  {
522    int status;
523    pid_t pid = fork();
524
525    switch (pid)
526      {
527      case -1:
528        error (EXIT_FAILURE, errno, _("fork system call failed"));
529        break;
530      case 0:                     /* Child. */
531        execlp ("strip", "strip", path, NULL);
532        error (EXIT_FAILURE, errno, _("cannot run strip"));
533        break;
534      default:                    /* Parent. */
535        /* Parent process. */
536        while (pid != wait (&status)) /* Wait for kid to finish. */
537          /* Do nothing. */;
538        if (status)
539          error (EXIT_FAILURE, 0, _("strip failed"));
540        break;
541      }
542  }

Line 523 calls fork(). The switch statement then takes the correct action for error return (lines 527–529), child process (lines 530–533), and parent process (lines 534–539).

The idiom on lines 536–537 is common; it waits until the specific child of interest exits. wait()’s return value is the PID of the reaped child. This is compared with that of the forked child. status is unused other than to see if it’s nonzero (line 538), in which case the child exited unsuccessfully. (The test, while correct, is coarse but simple. A test like ’if (WIFEXITED(status) && WEXITSTATUS(status) != 0)’ would be more pedantically correct.)

From the description and code presented so far, it may appear that parent programs must choose a specific point to wait for any child processes to die, possibly polling in a loop (as install.c does), waiting for all children. In Section 10.8.3, “Parental Supervision: Three Different Strategies,” page 385, we’ll see that this is not necessarily the case. Rather, signals provide a range of mechanisms to use for managing parent notification when a child process dies.

The BSD wait3() and wait4() system calls are useful if you’re interested in the resources used by a child process. They are nonstandard (meaning not part of POSIX) but widely available, including on GNU/Linux. The declarations are as follows:

#include <sys/types.h>                                                        Common
#include <sys/time.h>        Not needed under GNU/Linux, but improves portability
#include <sys/resource.h>
#include <sys/wait.h>

pid_t wait3 (int *status, int options, struct rusage *rusage);
pid_t wait4 (pid_t pid, int *status, int options, struct rusage *rusage);

The status variable is the same as for wait() and waitpid(). All the macros described earlier (WIFEXITED(), etc.) can also be used with it.

The options value is also the same as for waitpid(): either 0 or the bitwise OR of one or both of WNOHANG and WUNTRACED.

wait3() behaves like wait(), retrieving information about the first available zombie child, and wait4() is like waitpid(), retrieving information about a particular process. Both return the PID of the reaped child, -1 on error, or 0 if no process is available and WNOHANG was used. The pid argument can take on the same values as the pid argument for waitpid().

The key difference is the struct rusage pointer. If not NULL, the system fills it in with information about the process. This structure is described in POSIX and in the getrusage(2) manpage:

struct rusage {
    struct timeval ru_utime; /* user time used */
    struct timeval ru_stime; /* system time used */
    long   ru_maxrss;        /* maximum resident set size */
    long   ru_ixrss;         /* integral shared memory size */
    long   ru_idrss;         /* integral unshared data size */
    long   ru_isrss;         /* integral unshared stack size */
    long   ru_minflt;        /* page reclaims */
    long   ru_majflt;        /* page faults */
    long   ru_nswap;         /* swaps */
    long   ru_inblock;       /* block input operations */
    long   ru_oublock;       /* block output operations */
    long   ru_msgsnd;        /* messages sent */
    long   ru_msgrcv;        /* messages received */
    long   ru_nsignals;      /* signals received */
    long   ru_nvcsw;         /* voluntary context switches */
    long   ru_nivcsw;        /* involuntary context switches */
};

Pure BSD systems (4.3 Reno and later) support all of the fields. Table 9.2 describes the availability of the various fields in the struct rusage for POSIX and Linux.

Only the fields marked “POSIX” are defined by the standard. While Linux defines the full structure, the 2.4 kernel maintains only the user-time and system-time fields. The 2.6 kernel also maintains the fields related to context switching.^[3]

The fields of most interest are ru_utime and ru_stime, the user and system CPU times, respectively. (User CPU time is time spent executing user-level code. System CPU time is time spent in the kernel on behalf of the process.)

These two fields use a struct timeval, which maintains time values down to microsecond intervals. See Section 14.3.1, “Microsecond Times: gettimeofday()”, page 544, for more information on this structure.

In 4.2 and 4.3 BSD, the status argument to wait() and wait3() was a union wait. It fit into an int and provided access to the same information as the modern WIFEXITED() etc. macros do, but through the union’s members. Not all members were valid in all situations. The members and their uses are described in Table 9.3.

POSIX doesn’t standardize the union wait, and 4.4 BSD doesn’t document it, instead using the POSIX macros. GLIBC jumps through several hoops to make old code using it continue to work. We describe it here primarily so that you’ll recognize it if you see it; new code should use the macros described in Section 9.1.6.1, “Using POSIX Functions: wait() and waitpid(), page 306.

The pipe() system call creates a pipe:

#include <unistd.h>                                              POSIX

int pipe(int filedes[2]);

The argument value is the address of a two-element integer array. pipe() returns 0 upon success and -1 if there was an error.

If the call was successful, the process now has two additional open file descriptors. The value in filedes[0] is the read end of the pipe, and filedes[1] is the write end. (A handy mnemonic device is that the read end uses index 0, analogous to standard input being file descriptor 0, and the write end uses index 1, analogous to standard output being file descriptor 1.)

As mentioned, data written into the write end are read from the read end. When you’re done with a pipe, you close both ends with a call to close(). The following simple program, ch09-pipedemo.c, demonstrates pipes by creating one, writing data to it, and then reading the data back from it:

 1  /* ch09-pipedemo.c --- demonstrate I/O with a pipe. */
 2
 3  #include <stdio.h>
 4  #include <errno.h>
 5  #include <unistd.h>
 6
 7  /* main --- create a pipe, write to it, and read from it. */
 8
 9  int main(int argc, char **argv)
10  {
11      static const char mesg[] = "Don't Panic!";  /* a famous message */
12      char buf[BUFSIZ];
13      ssize_t rcount, wcount;
14      int pipefd[2];
15      size_t l;
16
17      if (pipe(pipefd) < 0) {
18          fprintf(stderr, "%s: pipe failed: %s
", argv[0],
19              strerror(errno));
20          exit(1);
21      }
22
23      printf("Read end = fd %d, write end = fd %d
",
24          pipefd[0], pipefd[1]);
25
26      l = strlen(mesg);
27      if ((wcount = write(pipefd[1], mesg, l)) != l) {
28          fprintf(stderr, "%s: write failed: %s
", argv[0],
29              strerror(errno));
30          exit(1);
31      }
32
33      if ((rcount = read(pipefd[0], buf, BUFSIZ)) != wcount) {
34          fprintf(stderr, "%s: read failed: %s
", argv[0],
35              strerror(errno));
36          exit(1);
37      }
38
39      buf[rcount] = '';
40
41      printf("Read <%s> from pipe
", buf);
42      (void) close(pipefd[0]);
43      (void) close(pipefd[1]);
44
45      return 0;
46  }

Lines 11–15 declare local variables; of most interest is mesg, which is the text that will traverse the pipe.

Lines 17–21 create the pipe, with error checking; lines 23–24 print the values of the new file descriptors (just to prove that they won’t be 0, 1, or 2).

Line 26 gets the length of the message, to use with write(). Lines 27–31 write the message down the pipe, again with error checking.

Lines 33–37 read the contents of the pipe, again with error checking.

Line 39 supplies a terminating zero byte, so that the read data can be used as a regular string. Line 41 prints the data, and lines 42–43 close both ends of the pipe. Here’s what happens when the program runs:

$ ch09-pipedemo
Read end = fd 3, write end = fd 4
Read <Don't Panic!> from pipe

This program doesn’t do anything useful, but it does demonstrate the basics. Note that there are no calls to open() or creat() and that the program isn’t using its three inherited file descriptors. Yet the write() and read() succeed, proving that the file descriptors are valid and that data that go into the pipe do come out of it.^[6] Of course, had the message been too big, our program wouldn’t have worked. This is because pipes have only so much room in them, a fact we discuss in the next section.

Like other file descriptors, those for a pipe are inherited by a child after a fork and if not closed, are still available after an exec. We see shortly how to make use of this fact and do something interesting with pipes.

Pipes buffer their data, meaning that data written to the pipe are held by the kernel until they are read. However, a pipe can hold only so much written but not yet read data. We can call the writing process the producer, and the reading process the consumer. How does the system manage full and empty pipes?

When the pipe is full, the system automatically blocks the producer the next time it attempts to write() data into the pipe. Once the pipe empties out, the system copies the data into the pipe and then allows the write() system call to return to the producer.

Similarly, if the pipe is empty, the consumer blocks in the read() until there is more data in the pipe to be read. (The blocking behavior can be turned off; this is discussed in Section 9.4.3.4, “Nonblocking I/O for Pipes and FIFOs,” page 333.)

When the producer does a close() on the pipe’s write end, the consumer can successfully read any data still buffered in the pipe. After that, further calls to read() return 0, indicating end of file.

Conversely, if the consumer closes the read end, a write() to the write end fails—drastically. In particular, the kernel sends the producer a “broken pipe” signal, whose default action is to terminate the process.

Our favorite analogy for pipes is that of a husband and wife washing and drying dishes together. One spouse washes the dishes, placing the clean but wet plates into a dish drainer by the sink. The other spouse takes the dishes from the drainer and dries them. The dish washer is the producer, the dish drainer is the pipe, and the dish dryer is the consumer.^[7]

If the drying spouse is faster than the washing one, the drainer becomes empty, and the dryer has to wait until more dishes are available. Conversely, if the washing spouse is faster, then the drainer becomes full, and the washer has to wait until it empties out before putting more clean dishes into it. This is depicted in Figure 9.3.

Figure 9.3. Synchronization of pipe processes

After a fork() and before an exec(), you should make sure that the new program inherits only the open files it needs. You don’t want a child process messing with the parent’s open files unless it’s supposed to. On the flip side, if a parent has lots of files open, that will artificially limit the number of new files the child can open. (See the accompanying sidebar.)

Organizationally, this behavior may present a problem. The part of your program that starts a new child shouldn’t particularly need access to the other part(s) of your program that manipulate open files. And a loop like the following is painful, since there may not be any open files:

int j;

for (j = getdtablesize(); j >= 3; j--)  /* close all but 0, 1, 2 */
    (void) close(j);

The solution is the close-on-exec flag. This is an attribute of the file descriptor itself, not the underlying open file. When this flag is set, the system automatically closes the file when the process does an exec. By setting this flag as soon as you open a file, you don’t have to worry about any child processes accidentally inheriting it. (The shell automatically sets this flag for all file descriptors it opens numbered 3 and above.)

The cmd argument has two values related to the close-on-exec flag:

F_GETFD

F_SETFD

At the moment, only one “file descriptor flag” is defined: FD_CLOEXEC. This symbolic constant is a POSIX invention,^[11] and most code uses a straight 1 or 0:

if (fcntl(fd, F_SETFD, 1) < 0) ...  /* set close-on-exec, handle any errors */

if (fcntl(fd, F_GETFD) == 1) ...    /* close-on-exec bit is already set */

However, the POSIX definition allows for future extension, and thus the correct way to write such code is more along these lines:

int fd;
long fd_flags;

if ((fd_flags = fcntl(fd, F_GETFD)) < 0)     Retrieve flags
    /* handle error */

fd_flags |= FD_CLOEXEC;                      Add close-on-exec flag
if (fcntl(fd, F_SETFD, fd_flags) < 0)        Set flags
    /* handle error */

print "something brilliant" > "/some/file"             Output to file
getline my_record < "/some/other/file                  Input from
 file

print "more words of wisdom" | "a_reader process"      Output to
 subprocess
"a_writer process" | getline some_input                Input from
 subprocess

When fcntl()’s cmd argument is F_DUPFD, the behavior is similar, but not quite identical, to dup2(). In this case, arg is a file descriptor representing the lowest acceptable value for the new file descriptor:

int new_fd = fcntl(old_fd, F_DUPFD, 7);       Return value is between 7 and maximum, or
 failure

int new_fd = dup2(old_fd, 7);                 Return value is 7, or failure

You can simulate the behavior of dup(), which returns the lowest free file descriptor, by using ’fcntl(old_fd, F_DUPFD, 0)’.

If you remember that file descriptors are just indexes into an internal table, understanding how this function works should be clear. The third argument merely provides the index at which the kernel should start its search for an unused file descriptor.

Whether to use fcntl() with F_DUPFD or dup() or dup2() in your own code is largely a matter of taste. All three APIs are part of POSIX and widely supported. We have a mild preference for dup() and dup2() since those are more specific in their action, and thus are more self-documenting. But because all of them are pretty simple, this reasoning may not convince you.

In Section 4.6.3, “Revisiting open()”, page 110, we provided the full list of O_xx flags that open() accepts. POSIX breaks these down by function, classifying them as described in Table 9.4.

Besides setting the various flags initially with open(), you can use fcntl() to retrieve the current settings, as well as to change them. This is done with the F_GETFL and F_SETFL values for cmd, respectively. For example, you might use these commands to change the setting of the nonblocking flag, O_NONBLOCK; like so:

int fd_flags;

if ((fd_flags = fcntl(fd, F_GETFL)) < 0)
    /* handle error */

if ((fd_flags & O_NONBLOCK) != 0) {           /* Nonblocking flag is set */
    fd_flags &= ~O_NONBLOCK;                  /* Clear it */
    if (fcntl(fd, F_SETFL, fd_flags) != 0)    /* Give kernel new value */
        /* handle error */
}

Besides the modes themselves, the O_ACCMODE symbolic constant is a mask you can use to retrieve the file access modes from the return value:

fd_flags = fcntl(fd, F_GETFL);

switch (fd_flags & O_ACCESS) {
case O_RDONLY:
    ...action for read-only...
    break;
case O_WRONLY:
    ... action for write-only...
    break;
case O_RDWR:
    ... action for read-write...
    break;
}

POSIX requires that O_RDONLY, O_RDWR, and O_WRONLY be bitwise distinct; thus, code such as just shown is guaranteed to work and is an easy way to determine how an arbitrary file descriptor was opened.

By using F_SETFL, you can change these modes as well, although permission checking still applies. According to the GNU/Linux fcntl(2) manpage, the O_APPEND flag cannot be cleared if it was used when the file was opened.

Earlier, we used the metaphor of two people washing and drying dishes, and using a dish drainer to describe the way a pipe works; when the drainer fills up, the dishwasher stops, and when it empties out, the dishdryer stops. This is blocking behavior: The producer or consumer blocks in the call to write() or read(), waiting either for more room in the pipe or for more data to come into it.

In the real world, a human being waiting for the dish drainer to empty out or fill up would not just stand by, immobile.^[12] Rather, the idle one would go and find some other kitchen task to do (such as sweeping up all the kids’ crumbs on the floor) until the dish drainer was ready again.

In Unix/POSIX parlance, this concept is termed nonblocking I/O. That is, the requested I/O either completes or returns an error value indicating no data (for the reader) or no room (for the writer). Nonblocking I/O applies to pipes and FIFOs, not to regular disk files. It can also apply to certain devices, such as terminals, and to network connections, both of which are beyond the scope of this volume.

The O_NONBLOCK flag can be used with open() to specify nonblocking I/O, and it can be set or cleared with fcntl(). For open() and read(), nonblocking I/O is straightforward.

Opening a FIFO with O_NONBLOCK set or clear displays the following behavior:

open("/fifo/file", O_RDONLY, mode)

open("/fifo/file", O_RDONLY|O_NONBLOCK, mode)

open("/fifo/file", O_WRONLY, mode)

open("/fifo/file", O_WRONLY|O_NONBLOCK, mode)

As described for regular pipes, a read() of a FIFO that is no longer open for writing returns end-of-file (a return value of 0). The O_NONBLOCK flag is irrelevant in this case. Things get more interesting for an empty pipe or FIFO: one that is still open for writing but that has no data in it:

read(fd, buf, count), and O_NONBLOCK clear

read(fd, buf, count), and O_NONBLOCK set

Finally, write() behavior is more complicated. To discuss it we have to first introduce the concept of an atomic write. An atomic write is one in which all the requested data are written together, without being interleaved with data from other writes. POSIX defines the constant PIPE_BUF in <unistd.h>. Writes of amounts less than or equal to PIPE_BUF bytes to a pipe or FIFO either succeed or block, according to the details we get into shortly. The minimum value for PIPE_BUF is _POSIX_PIPE_BUF, which is 512. PIPE_BUF itself can be larger; current GLIBC systems define it to be 4096, but in any case you should use the symbolic constant and not expect PIPE_BUF to be the same value across different systems.

In all cases, for pipes and FIFOs, a write() appends data to the end of the pipe. This derives from the fact that pipes don’t have file offsets: They aren’t seekable.

Also in all cases, as mentioned, writes of up to PIPE_BUF are atomic: The data are not interleaved with the data from other writes. Data from a write of more than PIPE_BUF bytes can be interleaved with the data from other writes on arbitrary boundaries. This last means that you cannot expect every PIPE_BUF subchunk of a large amount of data to be written atomically. The O_NONBLOCK setting does not affect this rule.

As with read(), when O_NONBLOCK is not set, write() blocks until all the data are written.

Things are most complicated with O_NONBLOCK set. For a pipe or FIFO, the behavior is as follows:

For nonpipe and non-FIFO files to which O_NONBLOCK can be applied, the behavior is as follows:

Although there is a bewildering array of behavior changes based on pipe/nonpipe, O_NONBLOCK set or clear, the space available in the pipe, and the size of the attempted write, the rules are intended to make programming straightforward:

In summary, if you intend to use nonblocking I/O, any code that uses write() has to be able to handle a short write, where less than the requested amount is successfully written. Robust code should be written this way anyway: Even for a regular file it’s possible that a disk could become full and that a write() will only partially succeed.

Furthermore, you should be prepared to handle EAGAIN, understanding that in this case write() failing isn’t necessarily a fatal error. The same is true of code that uses nonblocking I/O for reading: recognize that EAGAIN isn’t fatal here either. (It may pay, though, to count such occurrences, giving up after too many.)

Nonblocking I/O does complicate your life, no doubt about it. But for many applications, it’s a necessity that lets you get your job done. Consider the print spooler again. The spooler daemon can’t afford to sit in a blocking read() on the FIFO file to which incoming jobs are submitted. It has to be able to monitor running jobs as well and possibly periodically check the status of the printer devices (for example, to make sure they have paper or aren’t jammed).

The fcntl() system call is summarized in Table 9.5.

The file creation, status, and access flags are copied when a file descriptor is duplicated. The close-on-exec flag is not.