Go to the previous, next section.

File Status Flags

File status flags are used to specify attributes of the opening of a file. Unlike the file descriptor flags discussed in section File Descriptor Flags, the file status flags are shared by duplicated file descriptors resulting from a single opening of the file.

The file status flags are initialized by the open function from the flags argument of the open function. Some of the flags are meaningful only in open and are not remembered subsequently; many of the rest cannot subsequently be changed, though you can read their values by examining the file status flags.

A few file status flags can be changed at any time using fcntl. These include O_APPEND and O_NONBLOCK.

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

Macro: int F_GETFL

This macro is used as the command argument to fcntl, to read the file status flags for the open file with descriptor filedes.

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. The flags are encoded like the flags argument to open (see section Opening and Closing Files), but only the file access modes and the O_APPEND and O_NONBLOCK flags are meaningful here. Since the file access modes are not single-bit values, you can mask off other bits in the returned flags with O_ACCMODE to compare them.

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_SETFL

This macro is used as the command argument to fcntl, to set the file status flags for the open file corresponding to the filedes argument. This command requires a third int argument to specify the new flags, so the call looks like this:

fcntl (filedes, F_SETFL, new_flags)

You can't change the access mode for the file in this way; that is, whether the file descriptor was opened for reading or writing. You can only change the O_APPEND and O_NONBLOCK flags.

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

The following macros are defined for use in analyzing and constructing file status flag values:

O_APPEND

The bit that enables append mode for the file. If set, then all write operations write the data at the end of the file, extending it, regardless of the current file position.

O_NONBLOCK

The bit that enables nonblocking mode for the file. If this bit is set, read requests on the file can return immediately with a failure status if there is no input immediately available, instead of blocking. Likewise, write requests can also return immediately with a failure status if the output can't be written immediately.

O_NDELAY

This is a synonym for O_NONBLOCK, provided for compatibility with BSD.

Macro: int O_ACCMODE

This macro stands for a mask that can be bitwise-ANDed with the file status flag value to produce a value representing the file access mode. The mode will be O_RDONLY, O_WRONLY, or O_RDWR.

O_RDONLY

Open the file for read access.

O_WRONLY

Open the file for write access.

O_RDWR

Open the file for both reading and writing.

If you want to modify the file status flags, you should get the current flags with F_GETFL 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 O_NONBLOCK without altering any other flags:

/* Set the O_NONBLOCK 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_nonblock_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFL, 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 |= O_NONBLOCK;
  else
    oldflags &= ~O_NONBLOCK;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFL, oldflags);
}

Go to the previous, next section.