Various pages: Word "descriptor" more precisely

Use either "file descriptor" or message queue descriptor".

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2016-01-01 11:45:50 +01:00
parent 0fa890e0d8
commit d9cb0d7d3f
44 changed files with 97 additions and 95 deletions

View File

@ -179,7 +179,7 @@ flag in
for reasons why this may be useful.
.SH RETURN VALUE
On success,
these system calls return a nonnegative integer that is a descriptor
these system calls return a nonnegative integer that is a file descriptor
for the accepted socket.
On error, \-1 is returned, and
.I errno

View File

@ -176,7 +176,7 @@ See the discussion of
.TP
.B EBADF
.I sockfd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B EINVAL
The socket is already bound to an address.

View File

@ -57,7 +57,7 @@ is the last file descriptor referring to the underlying
open file description (see
.BR open (2)),
the resources associated with the open file description are freed;
if the descriptor was the last reference to a file which has been
if the file descriptor was the last reference to a file which has been
removed using
.BR unlink (2),
the file is deleted.
@ -103,7 +103,7 @@ In particular
.BR close ()
should not be retried after an
.B EINTR
since this may cause a reused descriptor from another thread to be closed.
since this may cause a reused file descriptor from another thread to be closed.
.PP
A successful close does not guarantee that the data has been successfully
saved to disk, as the kernel defers writes.

View File

@ -55,7 +55,7 @@ The
.BR dup ()
system call creates a copy of the file descriptor
.IR oldfd ,
using the lowest-numbered unused descriptor for the new descriptor.
using the lowest-numbered unused file descriptor for the new descriptor.
After a successful return,
the old and new file descriptors may be used interchangeably.
@ -64,9 +64,9 @@ They refer to the same open file description (see
and thus share file offset and file status flags;
for example, if the file offset is modified by using
.BR lseek (2)
on one of the descriptors, the offset is also changed for the other.
on one of the file descriptors, the offset is also changed for the other.
The two descriptors do not share file descriptor flags
The two file descriptors do not share file descriptor flags
(the close-on-exec flag).
The close-on-exec flag
.RB ( FD_CLOEXEC ;
@ -80,9 +80,9 @@ The
system call performs the same task as
.BR dup (),
but instead of using the lowest-numbered unused file descriptor,
it uses the descriptor number specified in
it uses the file descriptor number specified in
.IR newfd .
If the descriptor
If the file descriptor
.IR newfd
was previously open, it is silently closed before being reused.
@ -149,7 +149,7 @@ fails with the error
.BR EINVAL .
.SH RETURN VALUE
On success, these system calls
return the new descriptor.
return the new file descriptor.
On error, \-1 is returned, and
.I errno
is set appropriately.

View File

@ -19,7 +19,7 @@
.\"
.TH EPOLL_CTL 2 2015-05-07 "Linux" "Linux Programmer's Manual"
.SH NAME
epoll_ctl \- control interface for an epoll descriptor
epoll_ctl \- control interface for an epoll file descriptor
.SH SYNOPSIS
.B #include <sys/epoll.h>
.sp

View File

@ -113,9 +113,9 @@ and make it be a copy of
.IR fd .
This is different from
.BR dup2 (2),
which uses exactly the descriptor specified.
which uses exactly the file descriptor specified.
.IP
On success, the new descriptor is returned.
On success, the new file descriptor is returned.
.IP
See
.BR dup (2)
@ -125,7 +125,7 @@ for further details.
As for
.BR F_DUPFD ,
but additionally set the
close-on-exec flag for the duplicate descriptor.
close-on-exec flag for the duplicate file descriptor.
Specifying this flag permits a program to avoid an additional
.BR fcntl ()
.B F_SETFD
@ -1052,8 +1052,8 @@ refer to the same lease, and this lease may be modified
or released using any of these descriptors.
Furthermore, the lease is released by either an explicit
.B F_UNLCK
operation on any of these duplicate descriptors, or when all
such descriptors have been closed.
operation on any of these duplicate file descriptors, or when all
such file descriptors have been closed.
.P
Leases may be taken out only on regular files.
An unprivileged process may take out a lease only on a file whose
@ -1159,7 +1159,7 @@ then the handler will receive a
.I siginfo_t
structure as its second argument, and the
.I si_fd
field of this argument will hold the descriptor of the leased file
field of this argument will hold the file descriptor of the leased file
that has been accessed by another process.
(This is useful if the caller holds leases against multiple files.)
.SS File and directory change notification (dnotify)
@ -1465,7 +1465,7 @@ all outstanding writes will be discarded.
For a successful call, the return value depends on the operation:
.TP 0.9i
.B F_DUPFD
The new descriptor.
The new file descriptor.
.TP
.B F_GETFD
Value of file descriptor flags.
@ -1477,7 +1477,7 @@ Value of file status flags.
Type of lease held on file descriptor.
.TP
.B F_GETOWN
Value of descriptor owner.
Value of file descriptor owner.
.TP
.B F_GETSIG
Value of signal sent when read or write becomes possible, or zero

View File

@ -80,20 +80,20 @@ This means that duplicate file descriptors (created by, for example,
or
.BR dup (2))
refer to the same lock, and this lock may be modified
or released using any of these descriptors.
or released using any of these file descriptors.
Furthermore, the lock is released either by an explicit
.B LOCK_UN
operation on any of these duplicate descriptors, or when all
such descriptors have been closed.
operation on any of these duplicate file descriptors, or when all
such file descriptors have been closed.
If a process uses
.BR open (2)
(or similar) to obtain more than one descriptor for the same file,
these descriptors are treated independently by
(or similar) to obtain more than one file descriptor for the same file,
these file descriptors are treated independently by
.BR flock ().
An attempt to lock the file using one of these file descriptors
may be denied by a lock that the calling process has
already placed via another descriptor.
already placed via another file descriptor.
A process may hold only one type of lock (shared or exclusive)
on a file.

View File

@ -174,7 +174,7 @@ Each file descriptor in the child refers to the same
open file description (see
.BR open (2))
as the corresponding file descriptor in the parent.
This means that the two descriptors share open file status flags,
This means that the two file descriptors share open file status flags,
current file offset,
and signal-driven I/O attributes (see the description of
.B F_SETOWN
@ -186,10 +186,10 @@ in
The child inherits copies of the parent's set of open message
queue descriptors (see
.BR mq_overview (7)).
Each descriptor in the child refers to the same
Each file descriptor in the child refers to the same
open message queue description
as the corresponding descriptor in the parent.
This means that the two descriptors share the same flags
as the corresponding file descriptor in the parent.
This means that the two file descriptors share the same flags
.RI ( mq_flags ).
.IP *
The child inherits copies of the parent's set of open directory streams (see

View File

@ -75,7 +75,7 @@ is set appropriately.
.B EBADF
The argument
.I sockfd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B EFAULT
The

View File

@ -74,7 +74,7 @@ is set appropriately.
.B EBADF
The argument
.I sockfd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B EFAULT
The

View File

@ -142,7 +142,7 @@ options, the return value on success is the value returned by the handler.
.B EBADF
The argument
.I sockfd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B EFAULT
The address pointed to by

View File

@ -95,7 +95,7 @@ is set appropriately.
.TP 0.7i
.B EBADF
.I fd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B EFAULT
.I argp
@ -113,7 +113,7 @@ is not associated with a character special device.
.TP
.B ENOTTY
The specified request does not apply to the kind of object that the
descriptor
file descriptor
.I fd
references.
.SH CONFORMING TO

View File

@ -195,10 +195,11 @@ The
system call is similar to
.BR kexec_load (),
but it takes a different set of arguments.
It reads the kernel to be loaded from the file referred to by the descriptor
It reads the kernel to be loaded from the file referred to by
the file descriptor
.IR kernel_fd ,
and the initrd (initial RAM disk)
to be loaded from file referred to by the descriptor
to be loaded from file referred to by the file descriptor
.IR initrd_fd .
The
.IR cmdline

View File

@ -105,7 +105,7 @@ in
.B EBADF
The argument
.I sockfd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B ENOTSOCK
The file descriptor

View File

@ -109,7 +109,7 @@ This file descriptor is opened for both reading and writing
.RB ( O_RDWR )
and
.B O_LARGEFILE
is set for the descriptor.
is set for the file descriptor.
With respect to
.BR fork (2)
@ -337,7 +337,7 @@ file created by
.BR memfd_create ()
by opening the
.IR /proc/PID/fd
file that corresponds to the descriptor opened by
file that corresponds to the file descriptor opened by
.BR memfd_create ().
Using that pathname, we inspect the content of the
.IR /proc/PID/fd

View File

@ -236,7 +236,7 @@ and various other Linux system calls provide an equivalent of the
.BR O_CLOEXEC
flag to deal with this problem.)
.\" This flag fixes only one form of the race condition;
.\" The race can also occur with, for example, descriptors
.\" The race can also occur with, for example, file descriptors
.\" returned by accept(), pipe(), etc.
.TP
.B O_CREAT
@ -1311,10 +1311,10 @@ is a logical error, and certainly does not have the same meaning as
Linux reserves the special, nonstandard access mode 3 (binary 11) in
.I flags
to mean:
check for read and write permission on the file and return a descriptor
check for read and write permission on the file and return a file descriptor
that can't be used for reading or writing.
This nonstandard access mode is used by some Linux drivers to return a
descriptor that is to be used only for device-specific
file descriptor that is to be used only for device-specific
.BR ioctl (2)
operations.
.\" See for example util-linux's disk-utils/setfdprm.c

View File

@ -171,7 +171,7 @@ the child inherits a duplicate set of file
descriptors that refer to the same pipe.
After the
.BR fork (2),
each process closes the descriptors that it doesn't need for the pipe
each process closes the file descriptors that it doesn't need for the pipe
(see
.BR pipe (7)).
The parent then writes the string contained in the program's

View File

@ -448,7 +448,7 @@ so a portable application should check for both possibilities.
.B EBADF
The argument
.I sockfd
is an invalid descriptor.
is an invalid file descriptor.
.TP
.B ECONNREFUSED
A remote host refused to allow the network connection (typically

View File

@ -79,7 +79,7 @@ _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
is used to efficiently monitor multiple file descriptors,
to see if any of them is, or becomes, "ready";
that is, to see whether I/O becomes possible,
or an "exceptional condition" has occurred on any of the descriptors.
or an "exceptional condition" has occurred on any of the file descriptors.
Its principal arguments are three "sets" of file descriptors:
\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP.
@ -313,7 +313,7 @@ main(int argc, char *argv[])
.SS Practical
So what is the point of
.BR select ()?
Can't I just read and write to my descriptors whenever I want?
Can't I just read and write to my file descriptors whenever I want?
The point of
.BR select ()
is that it watches
@ -434,11 +434,11 @@ and
.BR send (2)
fail with errors other than those listed in \fB7.\fP,
or one of the input functions returns 0, indicating end of file,
then you should \fInot\fP pass that descriptor to
then you should \fInot\fP pass that file descriptor to
.BR select ()
again.
In the example below,
I close the descriptor immediately, and then set it to \-1
I close the file descriptor immediately, and then set it to \-1
to prevent it being included in a set.
.TP
10.

View File

@ -354,7 +354,8 @@ in
.BR ip (7).
.TP
.B EBADF
An invalid descriptor was specified.
.I sockfd
is not a valid open file descriptor.
.TP
.B ECONNRESET
Connection reset by peer.

View File

@ -274,7 +274,7 @@ main(int argc, char *argv[])
exit(EXIT_FAILURE);
}
fd = open(argv[1], O_RDONLY); /* Get descriptor for namespace */
fd = open(argv[1], O_RDONLY); /* Get file descriptor for namespace */
if (fd == \-1)
errExit("open");

View File

@ -75,7 +75,7 @@ is set appropriately.
.TP
.B EBADF
.I sockfd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.B EINVAL
An invalid value was specified in

View File

@ -62,13 +62,13 @@ argument is \-1,
then the call creates a new file descriptor and associates the
signal set specified in
.I mask
with that descriptor.
with that file descriptor.
If
.I fd
is not \-1,
then it must specify a valid existing signalfd file descriptor, and
.I mask
is used to replace the signal set associated with that descriptor.
is used to replace the signal set associated with that file descriptor.
Starting with Linux 2.6.27, the following values may be bitwise ORed in
.IR flags
@ -327,11 +327,11 @@ on different file descriptors.
.BR poll (2),
or
.BR epoll (7):
the arrival of different signals will make different descriptors ready.)
the arrival of different signals will make different file descriptors ready.)
If a signal appears in the
.I mask
of more than one of the file descriptors, then occurrences
of that signal can be read (once) from any one of the descriptors.
of that signal can be read (once) from any one of the file descriptors.
.SS C library/kernel differences
The underlying Linux system call requires an additional argument,
.IR "size_t sizemask" ,

View File

@ -61,7 +61,7 @@ and using the optionally specified
For further details of these arguments, see
.BR socket (2).
The descriptors used in referencing the new sockets are returned in
The file descriptors used in referencing the new sockets are returned in
.IR sv [0]
and
.IR sv [1].

View File

@ -46,7 +46,7 @@ bytes of data from the file descriptor
.I fd_in
to the file descriptor
.IR fd_out ,
where one of the descriptors must refer to a pipe.
where one of the file descriptors must refer to a pipe.
The following semantics apply for
.I fd_in
@ -164,7 +164,7 @@ Target filesystem doesn't support splicing;
target file is opened in append mode;
.\" The append-mode error is given since 2.6.27; in earlier kernels,
.\" splice() in append mode was broken
neither of the descriptors refers to a pipe; or
neither of the file descriptors refers to a pipe; or
offset given for nonseekable device.
.TP
.B ENOMEM

View File

@ -188,7 +188,7 @@ we now have things that can be wrong with the file descriptor,
.TP
.B EBADF
.I fd
is not a valid descriptor.
is not a valid file descriptor.
.TP
.BR EBADF " or " EINVAL
.I fd

View File

@ -57,7 +57,7 @@ The function
returns the file descriptor associated with the directory stream
.IR dirp .
.LP
This descriptor is the one used internally by the directory stream.
This file descriptor is the one used internally by the directory stream.
As a result, it is useful only for functions which do not depend on
or alter the file position, such as
.BR fstat (2)

View File

@ -89,7 +89,7 @@ The function
.BR fileno ()
examines the argument
.I stream
and returns its integer descriptor.
and returns its integer file descriptor.
.PP
For nonlocking counterparts, see
.BR unlocked_stdio (3).

View File

@ -26,7 +26,7 @@
.\"
.TH GETDTABLESIZE 3 2015-03-02 "Linux" "Linux Programmer's Manual"
.SH NAME
getdtablesize \- get descriptor table size
getdtablesize \- get file descriptor table size
.SH SYNOPSIS
.B #include <unistd.h>
.sp

View File

@ -53,7 +53,7 @@ set to indicate the error.
.SH ERRORS
.TP
.B EBADF
The descriptor specified in
The message quueue descriptor specified in
.I mqdes
is invalid.
.SH ATTRIBUTES

View File

@ -42,7 +42,7 @@ Link with \fI\-lrt\fP.
and
.BR mq_setattr ()
respectively retrieve and modify attributes of the message queue
referred to by the descriptor
referred to by the message queue descriptor
.IR mqdes .
.BR mq_getattr ()
@ -126,7 +126,7 @@ set to indicate the error.
.SH ERRORS
.TP
.B EBADF
The descriptor specified in
The message queue descriptor specified in
.I mqdes
is invalid.
.TP

View File

@ -38,7 +38,7 @@ Link with \fI\-lrt\fP.
.BR mq_notify ()
allows the calling process to register or unregister for delivery of
an asynchronous notification when a new message arrives on
the empty message queue referred to by the descriptor
the empty message queue referred to by the message queue descriptor
.IR mqdes .
The
@ -140,7 +140,7 @@ set to indicate the error.
.SH ERRORS
.TP
.B EBADF
The descriptor specified in
The message queue descriptor specified in
.I mqdes
is invalid.
.TP

View File

@ -57,7 +57,7 @@ _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
.SH DESCRIPTION
.BR mq_receive ()
removes the oldest message with the highest priority from
the message queue referred to by the descriptor
the message queue referred to by the message queue descriptor
.IR mqdes ,
and places it in the buffer pointed to by
.IR msg_ptr .
@ -127,7 +127,7 @@ flag was set for the message queue description referred to by
.IR mqdes .
.TP
.B EBADF
The descriptor specified in
The file descriptor specified in
.I mqdes
was invalid.
.TP

View File

@ -58,7 +58,7 @@ _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
.BR mq_send ()
adds the message pointed to by
.I msg_ptr
to the message queue referred to by the descriptor
to the message queue referred to by the message queue descriptor
.IR mqdes .
The
.I msg_len
@ -132,7 +132,7 @@ flag was set for the message queue description referred to by
.IR mqdes .
.TP
.B EBADF
The descriptor specified in
The file descriptor specified in
.I mqdes
was invalid.
.TP

View File

@ -47,7 +47,7 @@ _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
The function
.BR posix_fallocate ()
ensures that disk space is allocated for the file referred to by the
descriptor
file descriptor
.I fd
for the bytes in the range starting at
.I offset

View File

@ -63,7 +63,7 @@ Do not make this device the controlling terminal for the process.
On success,
.BR posix_openpt ()
returns a nonnegative file descriptor which is the lowest
numbered unused descriptor.
numbered unused file descriptor.
On failure, \-1 is returned, and
.I errno
is set to indicate the error.

View File

@ -98,7 +98,7 @@ on privileged port numbers.
The
.BR rresvport ()
function
returns a descriptor to a socket
returns a file descriptor to a socket
with an address in the privileged port space.
The
.BR iruserok ()
@ -138,7 +138,7 @@ and
If
.I fd2p
is nonzero, then an auxiliary channel to a control
process will be set up, and a descriptor for it will be placed
process will be set up, and a file descriptor for it will be placed
in
.IR *fd2p .
The control process will return diagnostic

View File

@ -98,7 +98,7 @@ and
If
.I fd2p
is nonzero, then an auxiliary channel to a control
process will be setup, and a descriptor for it will be placed
process will be setup, and a file descriptor for it will be placed
in
.IR *fd2p .
The control process will return diagnostic

View File

@ -714,7 +714,7 @@ or any creation routines.
.IP
Similar to
.BR svc_fdset ,
but limited to 32 descriptors.
but limited to 32 file descriptors.
This interface is obsoleted by
.BR svc_fdset .
.LP
@ -773,7 +773,7 @@ have been serviced.
.IP
Similar to
.BR svc_getreqset (),
but limited to 32 descriptors.
but limited to 32 file descriptors.
This interface is obsoleted by
.BR svc_getreqset ().
.LP
@ -923,8 +923,8 @@ The routine calls
.BI " unsigned int " recvsize );
.fi
.IP
Create a service on top of any open descriptor.
Typically, this descriptor is a connected socket for a stream protocol such
Create a service on top of any open file descriptor.
Typically, this file descriptor is a connected socket for a stream protocol such
as TCP.
.I sendsize
and

View File

@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see
_BSD_SOURCE
.SH DESCRIPTION
.BR closelog ()
closes the descriptor being used to write to the system logger.
closes the file descriptor being used to write to the system logger.
The use of
.BR closelog ()
is optional.

View File

@ -25,7 +25,7 @@ directory.
Each file descriptor obtained by opening
.IR /dev/ptmx
is an independent PTM with its own associated PTS, whose path can
be found by passing the descriptor to
be found by passing the file descriptor to
.BR ptsname (3).
.PP
Before opening the pseudoterminal slave, you must pass the master's file
@ -37,7 +37,7 @@ and
Once both the pseudoterminal master and slave are open, the slave provides
processes with an interface that is identical to that of a real terminal.
.PP
Data written to the slave is presented on the master descriptor as input.
Data written to the slave is presented on the master file descriptor as input.
Data written to the master is presented to the slave as input.
.PP
In practice, pseudoterminals are used for implementing terminal emulators

View File

@ -619,7 +619,7 @@ The files in this directory are readable only by the owner of the process.
The contents of each file can be read to obtain information
about the corresponding file descriptor.
The content depends on the type of file referred to by the
corresponding descriptor.
corresponding file descriptor.
For regular files and directories, we see something like:
.in +4n

View File

@ -351,19 +351,19 @@ However, it is possible to add a duplicate
.BR dup2 (2),
.BR fcntl (2)
.BR F_DUPFD )
descriptor to the same
file descriptor to the same
.B epoll
instance.
.\" But a descriptor duplicated by fork(2) can't be added to the
.\" But a file descriptor duplicated by fork(2) can't be added to the
.\" set, because the [file *, fd] pair is already in the epoll set.
.\" That is a somewhat ugly inconsistency. On the one hand, a child process
.\" cannot add the duplicate file descriptor to the epoll set. (In every
.\" other case that I can think of, descriptors duplicated by fork have
.\" similar semantics to descriptors duplicated by dup() and friends.) On
.\" other case that I can think of, file descriptors duplicated by fork have
.\" similar semantics to file descriptors duplicated by dup() and friends.) On
.\" the other hand, the very fact that the child has a duplicate of the
.\" descriptor means that even if the parent closes its descriptor, then
.\" epoll_wait() in the parent will continue to receive notifications for
.\" that descriptor because of the duplicated descriptor in the child.
.\" file descriptor means that even if the parent closes its file descriptor,
.\" then epoll_wait() in the parent will continue to receive notifications for
.\" that file descriptor because of the duplicated file descriptor in the child.
.\"
.\" See http://thread.gmane.org/gmane.linux.kernel/596462/
.\" "epoll design problems with common fork/exec patterns"
@ -434,7 +434,7 @@ sets automatically?
Yes, but be aware of the following point.
A file descriptor is a reference to an open file description (see
.BR open (2)).
Whenever a descriptor is duplicated via
Whenever a file descriptor is duplicated via
.BR dup (2),
.BR dup2 (2),
.BR fcntl (2)
@ -449,7 +449,7 @@ A file descriptor is removed from an
.B epoll
set only after all the file descriptors referring to the underlying
open file description have been closed
(or before if the descriptor is explicitly removed using
(or before if the file descriptor is explicitly removed using
.BR epoll_ctl (2)
.BR EPOLL_CTL_DEL ).
This means that even after a file descriptor that is part of an

View File

@ -74,8 +74,8 @@ After a
.BR fork (2),
a child inherits copies of its parent's message queue descriptors,
and these descriptors refer to the same open message queue descriptions
as the corresponding descriptors in the parent.
Corresponding descriptors in the two processes share the flags
as the corresponding message queue descriptors in the parent.
Corresponding message queue descriptors in the two processes share the flags
.RI ( mq_flags )
that are associated with the open message queue description.