dup2 - clone file handles
Standard C Library (libc, -lc)
#include <unistd.h>
int
dup2(int oldfd, int newfd);
dup2 clones the file handle oldfd onto the file handle newfd. If newfd names an already-open file, that file is closed.
The two handles refer to the same "open" of the file -- that is, they are references to the same object and share the same seek pointer. Note that this is different from opening the same file twice.
dup2 is most commonly used to relocate opened files onto STDIN_FILENO, STDOUT_FILENO, and/or STDERR_FILENO.
Both filehandles must be non-negative, and, if applicable, smaller than the maximum allowed file handle number.
The call (like all system calls) should be atomic; for single-threaded processes this is trivial. Multithreaded processes should never e.g. see an intermediate state where newfd has been closed but oldfd has not yet been cloned onto it. Similarly, if two threads attempt e.g. dup2(3, 4) and dup2(4, 3) simultaneously, the results must be equivalent to one of the calls completing before the other starts.
Using dup2 to clone a file handle onto itself has no effect.
(The "2" in "dup2" arises from the existence of an older and less powerful Unix system call "dup".)
dup2 returns newfd. On error, -1 is returned, and errno is set according to the error encountered.
The following error codes should be returned under the conditions given. Other error codes may be returned for other cases not mentioned here.
| EBADF | oldfd is not a valid file handle, or newfd is a value that cannot be a valid file handle. | |
| EMFILE | The process's file table was full, or a process-specific limit on open files was reached. | |
| ENFILE | The system's file table was full, if such a thing is possible, or a global limit on open files was reached. |