dup(2)

dup -- duplicate an open file descriptor

Synopsis

   #include <unistd.h>
   
   int dup(int fildes);

Description

dup duplicates an open file descriptor. fildes is a file descriptor obtained from a creat, open, dup, fcntl, pipe, or ioctl system call. dup returns a new file descriptor having the following in common with the original:

Same open file (or pipe).
Same file pointer (i.e., both file descriptors share one file pointer).
Same access mode (read, write or read/write).

The new file descriptor is set to remain open across exec system calls [see fcntl(2)].

The file descriptor returned is the lowest one available.

Return values

On success, dup returns a non-negative integer, namely the file descriptor. On failure, dup returns -1 and sets errno to identify the error.

Errors

In the following conditions, dup fails and sets errno to:

EBADF: fildes is not a valid open file descriptor.
EINTR: A signal was caught during the dup system call.
EMFILE: The process has too many open files [see getrlimit(2)].
ENOLINK: fildes is on a remote machine and the link to that machine is no longer active.

References

close(2), creat(2), dup2(3C), exec(2), fcntl(2), getrlimit(2), lockf(3C), open(2), pipe(2)

Notices

Considerations for threads programming

Open file descriptors are a process resource and available to any sibling thread; if used concurrently, actions by one thread can interfere with those of a sibling.