| .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
| .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
| .\" and Copyright (C) 2005, 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified 1993-07-21, Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1994-08-21, Michael Chastain <mec@shell.portal.com>: |
| .\" Fixed typos. |
| .\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 2002-09-28, aeb |
| .\" 2009-01-12, mtk, reordered text in DESCRIPTION and added some |
| .\" details for dup2(). |
| .\" 2008-10-09, mtk: add description of dup3() |
| .\" |
| .TH DUP 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| dup, dup2, dup3 \- duplicate a file descriptor |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .sp |
| .BI "int dup(int " oldfd ); |
| .BI "int dup2(int " oldfd ", int " newfd ); |
| .sp |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .BR "#include <fcntl.h>" " /* Obtain O_* constant definitions */ |
| .B #include <unistd.h> |
| .sp |
| .BI "int dup3(int " oldfd ", int " newfd ", int " flags ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR dup () |
| system call creates a copy of the file descriptor |
| .IR oldfd , |
| 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. |
| They refer to the same open file description (see |
| .BR open (2)) |
| 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 file descriptors, the offset is also changed for the other. |
| |
| The two file descriptors do not share file descriptor flags |
| (the close-on-exec flag). |
| The close-on-exec flag |
| .RB ( FD_CLOEXEC ; |
| see |
| .BR fcntl (2)) |
| for the duplicate descriptor is off. |
| .\" |
| .SS dup2() |
| The |
| .BR dup2 () |
| system call performs the same task as |
| .BR dup (), |
| but instead of using the lowest-numbered unused file descriptor, |
| it uses the file descriptor number specified in |
| .IR newfd . |
| If the file descriptor |
| .IR newfd |
| was previously open, it is silently closed before being reused. |
| |
| The steps of closing and reusing the file descriptor |
| .IR newfd |
| are performed |
| .IR atomically . |
| This is important, because trying to implement equivalent functionality using |
| .BR close (2) |
| and |
| .BR dup () |
| would be |
| subject to race conditions, whereby |
| .I newfd |
| might be reused between the two steps. |
| Such reuse could happen because the main program is interrupted |
| by a signal handler that allocates a file descriptor, |
| or because a parallel thread allocates a file descriptor. |
| |
| Note the following points: |
| .IP * 3 |
| If |
| .I oldfd |
| is not a valid file descriptor, then the call fails, and |
| .I newfd |
| is not closed. |
| .IP * |
| If |
| .I oldfd |
| is a valid file descriptor, and |
| .I newfd |
| has the same value as |
| .IR oldfd , |
| then |
| .BR dup2 () |
| does nothing, and returns |
| .IR newfd . |
| .\" |
| .SS dup3() |
| .BR dup3 () |
| is the same as |
| .BR dup2 (), |
| except that: |
| .IP * 3 |
| The caller can force the close-on-exec flag to be set |
| for the new file descriptor by specifying |
| .BR O_CLOEXEC |
| in |
| .IR flags . |
| See the description of the same flag in |
| .BR open (2) |
| for reasons why this may be useful. |
| .IP * |
| .\" Ulrich Drepper, LKML, 2008-10-09: |
| .\" We deliberately decided on this change. Otherwise, what is the |
| .\" result of dup3(fd, fd, O_CLOEXEC)? |
| If |
| .IR oldfd |
| equals |
| .IR newfd , |
| then |
| .BR dup3 () |
| fails with the error |
| .BR EINVAL . |
| .SH RETURN VALUE |
| On success, these system calls |
| return the new file descriptor. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I oldfd |
| isn't an open file descriptor. |
| .TP |
| .B EBADF |
| .I newfd |
| is out of the allowed range for file descriptors (see the discussion of |
| .BR RLIMIT_NOFILE |
| in |
| .BR getrlimit (2)). |
| .TP |
| .B EBUSY |
| (Linux only) This may be returned by |
| .BR dup2 () |
| or |
| .BR dup3 () |
| during a race condition with |
| .BR open (2) |
| and |
| .BR dup (). |
| .TP |
| .B EINTR |
| The |
| .BR dup2 () |
| or |
| .BR dup3 () |
| call was interrupted by a signal; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| .RB ( dup3 ()) |
| .I flags |
| contain an invalid value. |
| .TP |
| .B EINVAL |
| .RB ( dup3 ()) |
| .\" FIXME . To confirm with Al Viro that this was intended, and its rationale |
| .I oldfd |
| was equal to |
| .IR newfd . |
| .TP |
| .B EMFILE |
| The per-process limit on the number of open file descriptors has been reached |
| (see the discussion of |
| .BR RLIMIT_NOFILE |
| in |
| .BR getrlimit (2)). |
| .SH VERSIONS |
| .BR dup3 () |
| was added to Linux in version 2.6.27; |
| glibc support is available starting with |
| version 2.9. |
| .SH CONFORMING TO |
| .BR dup (), |
| .BR dup2 (): |
| POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
| |
| .BR dup3 () |
| is Linux-specific. |
| .\" SVr4 documents additional |
| .\" EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. |
| .\" The EBUSY return is Linux-specific. |
| .SH NOTES |
| The error returned by |
| .BR dup2 () |
| is different from that returned by |
| .BR fcntl( "..., " F_DUPFD ", ..." ) |
| when |
| .I newfd |
| is out of range. |
| On some systems, |
| .BR dup2 () |
| also sometimes returns |
| .B EINVAL |
| like |
| .BR F_DUPFD . |
| |
| If |
| .I newfd |
| was open, any errors that would have been reported at |
| .BR close (2) |
| time are lost. |
| If this is of concern, |
| then\(emunless the program is single-threaded and does not allocate |
| file descriptors in signal handlers\(emthe correct approach is |
| .I not |
| to close |
| .I newfd |
| before calling |
| .BR dup2 (), |
| because of the race condition described above. |
| Instead, code something like the following could be used: |
| |
| .nf |
| /* Obtain a duplicate of 'newfd' that can subsequently |
| be used to check for close() errors; an EBADF error |
| means that 'newfd' was not open. */ |
| |
| tmpfd = dup(newfd); |
| if (tmpfd == \-1 && errno != EBADF) { |
| /* Handle unexpected dup() error */ |
| } |
| |
| /* Atomically duplicate 'oldfd' on 'newfd' */ |
| |
| if (dup2(oldfd, newfd) == \-1) { |
| /* Handle dup2() error */ |
| } |
| |
| /* Now check for close() errors on the file originally |
| referred to by 'newfd' */ |
| |
| if (tmpfd != \-1) { |
| if (close(tmpfd) == \-1) { |
| /* Handle errors from close */ |
| } |
| } |
| .fi |
| .SH SEE ALSO |
| .BR close (2), |
| .BR fcntl (2), |
| .BR open (2) |