+++ /dev/null
-.\" 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-12-12 "Linux" "Linux Programmer's Manual"
-.SH NAME
-dup, dup2, dup3 \- duplicate a file descriptor
-.SH SYNOPSIS
-.nf
-.B #include <unistd.h>
-.PP
-.BI "int dup(int " oldfd );
-.BI "int dup2(int " oldfd ", int " newfd );
-
-.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.BR "#include <fcntl.h>" " /* Obtain O_* constant definitions */
-.B #include <unistd.h>
-.PP
-.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 ())
-.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)
projects / thirdparty / man-pages.git / blobdiff