NAME
dup,
dup2,
dup3 —
duplicate an existing file descriptor
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
int
dup(
int
oldfd);
int
dup2(
int
oldfd,
int newfd);
int
dup3(
int
oldfd,
int newfd,
int flags);
DESCRIPTION
The
dup() family of calls duplicates an existing file
descriptor
oldfd. A new file descriptor is produced; it
is a new reference to the same underlying system object. The object in
question does not distinguish between the descriptors referencing it in any
way. Thus for files,
read(2),
write(2) and
lseek(2) calls all move a single
shared seek position. Similarly, all object modes, settings, properties, and
behavior other than the close-on-exec flag are shared between references. This
includes the setting of append mode, non-blocking I/O actions, asynchronous
I/O operations in progress, socket options, and so forth. The close-on-exec
flag, however, is a property of the descriptor rather than the object and can
be set independently for each reference.
To get an independent handle with its own seek position and settings, an
additional
open(2) call must be
issued. (This is not generally possible for pipes and sockets.)
The
dup() call chooses the new descriptor: it is the
lowest-numbered descriptor not currently in use. The
dup2()
and
dup3() calls allow the caller to choose the new
descriptor by passing
newfd, which must be within the
range of valid descriptors. If
newfd is the same as
oldfd, the call has no effect. Otherwise, if
newfd is already in use, it is closed as if
close(2) had been called.
File descriptors are small non-negative integers that index into the per-process
file table. Values 0, 1, and 2 have the special property that they are treated
as standard input, standard output, and standard error respectively. (The
constants
STDIN_FILENO
,
STDOUT_FILENO
, and
STDERR_FILENO
are provided as symbolic forms for these
values.) The maximum value for a file descriptor is one less than the file
table size. The file table size can be interrogated with
getdtablesize(3) and can
to some extent be adjusted with
setrlimit(2).
The
dup3() call includes an additional
flags argument supporting a subset of the
open(2) flags:
-
-
O_CLOEXEC
- Set the close-on-exec flag on
newfd.
-
-
O_NONBLOCK
- Sets non-blocking I/O.
-
-
O_NOSIGPIPE
- For pipes and sockets, do not raise
SIGPIPE
when a write is made to a broken pipe.
Instead, the write will fail with EPIPE
.
As described above, only the close-on-exec flag is per-file-descriptor, so
passing any of the other
flags will affect both
oldfd and
newfd. These settings
are, however, applied atomically along with the rest of the
dup3() operation.
In the case of
dup() and
dup2() the
close-on-exec flag on the new file descriptor is always left unset and all the
modes and settings of the underlying object are left unchanged.
Functionality similar to
dup() with slightly different
semantics is also available via
fcntl(2).
RETURN VALUES
These calls return the new file descriptor value. In the case of
dup2() and
dup3() this is always the same
as
newfd. If an error occurs, the value -1 is returned
and
errno is set to indicate what happened.
EXAMPLES
A common use for these functions is to set up a pipe as the standard input or
standard output of a subprocess. That is done approximately as follows (error
handling omitted for clarity):
#include <unistd.h>
int fds[2];
pid_t pid;
pipe(fds);
pid = fork();
if (pid == 0) {
/* child; use read end of pipe to stdin */
dup2(fds[0], STDIN_FILENO);
close(fds[0]);
close(fds[1]);
execv("/some/program", args);
}
/* parent process; return write end of pipe */
close(fds[0]);
return fds[1];
ERRORS
These functions fail if:
-
-
- [
EBADF
]
- oldfd is not a valid active
descriptor, or for dup2() and dup3(),
newfd is not in the range of valid file
descriptors.
-
-
- [
EINVAL
]
- flags contained an invalid value.
Only dup3() can generate this error.
-
-
- [
EMFILE
]
- Too many descriptors are active. Only
dup() can generate this error.
SEE ALSO
accept(2),
close(2),
fcntl(2),
getrlimit(2),
open(2),
pipe(2),
setrlimit(2),
socket(2),
socketpair(2),
getdtablesize(3)
STANDARDS
The
dup() and
dup2() functions conform to
IEEE Std 1003.1-1990 (“POSIX.1”).
HISTORY
The
dup3() function originated in Linux and appeared in
NetBSD 6.0.