NAME
dup
, dup2
,
dup3
—
duplicate an existing file
descriptor
LIBRARY
library “libc”
SYNOPSIS
#include
<unistd.h>
int
dup
(int
oldfd);
int
dup2
(int
oldfd, int
newfd);
int
dup3
(int
oldfd, int newfd,
int flags);
DESCRIPTION
Thedup
()
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 withEPIPE
.
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
() anddup3
(), 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.