diff options
Diffstat (limited to 'man/man2/dup.2')
| -rw-r--r-- | man/man2/dup.2 | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/man/man2/dup.2 b/man/man2/dup.2 new file mode 100644 index 000000000..4948e6dd4 --- /dev/null +++ b/man/man2/dup.2 @@ -0,0 +1,284 @@ +.\" 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> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +dup, dup2, dup3 \- duplicate a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int dup(int " oldfd ); +.BI "int dup2(int " oldfd ", int " newfd ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" +.B #include <unistd.h> +.P +.BI "int dup3(int " oldfd ", int " newfd ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR dup () +system call allocates a new file descriptor that refers to the same +open file description as the descriptor +.IR oldfd . +(For an explanation of open file descriptions, see +.BR open (2).) +The new file descriptor number is guaranteed to be the lowest-numbered +file descriptor that was unused in the calling process. +.P +After a successful return, +the old and new file descriptors may be used interchangeably. +Since the two file descriptors refer to the same open file description, +they 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 file descriptor. +.P +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 . +In other words, +the file descriptor +.I newfd +is adjusted so that it now refers to the same open file description as +.IR oldfd . +.P +If the file descriptor +.I newfd +was previously open, it is closed before being reused; +the close is performed silently +(i.e., any errors during the close are not reported by +.BR dup2 ()). +.P +The steps of closing and reusing the file descriptor +.I 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. +.P +Note the following points: +.IP \[bu] 3 +If +.I oldfd +is not a valid file descriptor, then the call fails, and +.I newfd +is not closed. +.IP \[bu] +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 \[bu] 3 +The caller can force the close-on-exec flag to be set +for the new file descriptor by specifying +.B O_CLOEXEC +in +.IR flags . +See the description of the same flag in +.BR open (2) +for reasons why this may be useful. +.IP \[bu] +.\" Ulrich Drepper, LKML, 2008-10-09: +.\" We deliberately decided on this change. Otherwise, what is the +.\" result of dup3(fd, fd, O_CLOEXEC)? +If +.I 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 to indicate the error. +.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 +.B 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 ()) +.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 +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.SH STANDARDS +.TP +.BR dup () +.TQ +.BR dup2 () +POSIX.1-2008. +.TP +.BR dup3 () +Linux. +.SH HISTORY +.TP +.BR dup () +.TQ +.BR dup2 () +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents additional +.\" EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. +.\" The EBUSY return is Linux-specific. +.TP +.BR dup3 () +Linux 2.6.27, +glibc 2.9. +.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 . +.P +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\[em]unless the program is single-threaded and does not allocate +file descriptors in signal handlers\[em]the 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: +.P +.in +4n +.EX +/* Obtain a duplicate of \[aq]newfd\[aq] that can subsequently + be used to check for close() errors; an EBADF error + means that \[aq]newfd\[aq] was not open. */ +\& +tmpfd = dup(newfd); +if (tmpfd == \-1 && errno != EBADF) { + /* Handle unexpected dup() error. */ +} +\& +/* Atomically duplicate \[aq]oldfd\[aq] on \[aq]newfd\[aq]. */ +\& +if (dup2(oldfd, newfd) == \-1) { + /* Handle dup2() error. */ +} +\& +/* Now check for close() errors on the file originally + referred to by \[aq]newfd\[aq]. */ +\& +if (tmpfd != \-1) { + if (close(tmpfd) == \-1) { + /* Handle errors from close. */ + } +} +.EE +.in +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR open (2), +.BR pidfd_getfd (2) |