Descriptor Flags - The GNU C Library

Next: File Status Flags, Previous: Duplicating Descriptors, Up: Low-Level I/O

### 13.13 File Descriptor Flags

File descriptor flags are miscellaneous attributes of a file descriptor. These flags are associated with particular file descriptors, so that if you have created duplicate file descriptors from a single opening of a file, each descriptor has its own set of flags.

Currently there is just one file descriptor flag: `FD_CLOEXEC`, which causes the descriptor to be closed if you use any of the `exec...` functions (see Executing a File).

The symbols in this section are defined in the header file `fcntl.h`.

— Macro: int F_GETFD

> This macro is used as the command argument to `fcntl`, to specify that it should return the file descriptor flags associated with the filedes argument.

> The normal return value from `fcntl` with this command is a nonnegative number which can be interpreted as the bitwise OR of the individual flags (except that currently there is only one flag to use).

> In case of an error, `fcntl` returns -1. The following `errno` error conditions are defined for this command:

> `EBADF`
>   The filedes argument is invalid.

— Macro: int F_SETFD

> This macro is used as the command argument to `fcntl`, to specify that it should set the file descriptor flags associated with the filedes argument. This requires a third `int` argument to specify the new flags, so the form of the call is:

>               fcntl (filedes, F_SETFD, new-flags)

> The normal return value from `fcntl` with this command is an unspecified value other than -1, which indicates an error. The flags and error conditions are the same as for the `F_GETFD` command.

The following macro is defined for use as a file descriptor flag with the `fcntl` function. The value is an integer constant usable as a bit mask value.

— Macro: int FD_CLOEXEC

> This flag specifies that the file descriptor should be closed when an `exec` function is invoked; see Executing a File. When a file descriptor is allocated (as with `open` or `dup`), this bit is initially cleared on the new file descriptor, meaning that descriptor will survive into the new program after `exec`.

If you want to modify the file descriptor flags, you should get the current flags with `F_GETFD` and modify the value. Don't assume that the flags listed here are the only ones that are implemented; your program may be run years from now and more flags may exist then. For example, here is a function to set or clear the flag `FD_CLOEXEC` without altering any other flags:

         /* Set the FD_CLOEXEC flag of desc if value is nonzero,
            or clear the flag if value is 0.
            Return 0 on success, or -1 on error with errno set. */

         int
         set_cloexec_flag (int desc, int value)
         {
           int oldflags = fcntl (desc, F_GETFD, 0);
           /* If reading the flags failed, return error indication now. */
           if (oldflags < 0)
             return oldflags;
           /* Set just the flag we want to set. */
           if (value != 0)
             oldflags |= FD_CLOEXEC;
           else
             oldflags &= ~FD_CLOEXEC;
           /* Store modified flag word in the descriptor. */
           return fcntl (desc, F_SETFD, oldflags);
         }