Specification of file descriptors

Question

I am trying to understand flags and modes of file descriptors.

The man page for

fcntl - manipulate file descriptor

int fcntl(int fd, int cmd);

states:

File descriptor flags

The following commands manipulate the flags associated with a file descriptor. Currently, only one such flag is defined: FD_CLOEXEC,...

File status flags

Each open file description has certain associated status flags, initialized by open(2)... The file status flags and their semantics are described in open(2).

Given that fcntl refers entirely to file descriptors (no dealing with streams), I guess the second title should be "File descriptor status flags". So now we have for a FD "flags" and "status flags". This man page also mentions that when cmd=F_GETFL, the return value of fcntl is "the file access mode and the file status flags". So now we have also a file access mode.

Now in the man page for open there are flags and modes, as if they were two different items. There is even a prototype that makes explicit the difference

int open(const char *pathname, int flags, mode_t mode);

So now we have, for each file descriptor, "flags", "status flags", "file access modes", and "modes" (I would identify the latter two as the same). To begin with,
1. I don't know the difference between these three categories.

Traversing both quoted man pages, I collected a list of "entities" (below, in order of appearance, some are repeated).
2. I don't know which category each belongs to.

FD_CLOEXEC, O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC, O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, O_NONBLOCK, O_DSYNC, O_SYNC, O_CLOEXEC
O_CREAT, O_DIRECTORY, O_EXCL, O_NOCTTY, O_NOFOLLOW, O_TMPFILE, O_TRUNC, O_LARGEFILE, O_NDELAY, O_PATH

I couldn't find a simple list telling "X, Y, Z are flags, W, V are modes, etc." Perhaps they are terms that are used interchangeably, or the mode is a subset of the flags, or...

Related:

Difference between "file pointer", "stream", "file descriptor" and ... "file"? (answers there may be a guide in the present OP, even if not the same).

How to make sense of O_RDONLY = 0?

Difference between "file pointer", "stream", "file descriptor" and ... "file"?

How to get the mode of a file descriptor?

https://www.gnu.org/software/libc/manual/html_node/Access-Modes.html

https://www.gnu.org/software/libc/manual/html_node/File-Status-Flags.html#File-Status-Flags

Answer 1

File descriptors can be duplicated. For example, when a process forks, it gets its own set of FDs that the parent doesn't affect, and the dup syscall can be used to explicitly duplicate individual FDs.

When file descriptors get duplicated, every descriptor has its own set of file descriptor flags, but they'll all share the same file status flags. For example, consider this code:

int fdA = open('/tmp/somefile', O_WRONLY);
int fdB = dup(fdA);
fcntl(fdA, F_SETFD, FD_CLOEXEC);
fcntl(fdA, F_SETFL, O_APPEND);

After running it, fdA will be close-on-exec and in append mode, and fdB will be in append mode but not close-on-exec. This is because close-on-exec is a file descriptor flag and append mode is a file status flag.

The file access mode and file creation flags are passed along with the file status flags when they're supported.

The third parameter to open, also confusingly called mode, is unrelated to everything else discussed so far. If the file is created by the call to open, then that mode is used as the permissions for the new file. Otherwise, it has no effect.

• FD_CLOEXEC - file descriptor flag
• O_RDONLY - file access mode
• O_WRONLY - file access mode
• O_RDWR - file access mode
• O_CLOEXEC - file creation flag
• O_CREAT - file creation flag
• O_DIRECTORY - file creation flag
• O_EXCL - file creation flag
• O_NOCTTY - file creation flag
• O_NOFOLLOW - file creation flag
• O_TMPFILE - file creation flag
• O_TRUNC - file creation flag

The rest of the flags you listed are file status flags.

And one final note: O_CLOEXEC is only relevant for a new FD. For existing FDs, you'll only ever use FD_CLOEXEC.

Answer 2

I will summarize the description by Joseph Sible-Reinstate Monica and add a few remarks on possibly confusing wording across man pages, likely the cause of the OP.

As per headings in http://man7.org/linux/man-pages/man2/fcntl.2.html (as cited in the OP) Flags = File descriptor flags + File status flags.
Remark 1: this usage of File status flags is not consistent with the rest of available information, so it should rather be called something like

Flags = File descriptor flags + Non-FD flags.

The distinction between these two groups of flags is given by Joseph Sible-Reinstate Monica.

As per http://man7.org/linux/man-pages/man2/open.2.html,

Non-FD Flags = Access mode + File creation flags + File status flags

Note that:

1. The man page does not use the name Non-FD Flags. It simply calls this flags, as the name of the argument in the prototypes listed. But this should not be taken as if, conceptually, these flags encompass all flags since File descriptor flags are not included.

2. "The distinction between these two groups of flags is that the file creation flags affect the semantics of the open operation itself, while the file status flags affect the semantics of subsequent I/O operations." [ref]

3. This is the most common usage of File status flags.

This is the basic classification of "entities".
Remark 2: I use quotes since the general use of flags is quite misleading. Access mode are not flags in the usual sense, and this is clarified in How to make sense of O_RDONLY = 0?.

Remark 3: GNU uses a different naming, adding to the confusion. The translation POSIX.1 <-> GNU is shown below. Usage of File Status Flags in GNU may be especially confusing.

POSIX.1               GNU
Non-FD Flags*         File Status Flags
Access modes          Access mode
File creation flags   Open-time Flags
File status flags     Operating Modes

As for the listings enumerating each category, they are given by Joseph Sible-Reinstate Monica. GNU also has its own Access modes, File creation flags (Open-time Flags) and File status flags (Operating Modes).