+++ /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>
-.\"
-.\" %%%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 typoes.
-.\" 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 2012-02-14 "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
-These system calls create a copy of the file descriptor
-.IR oldfd .
-
-.BR dup ()
-uses the lowest-numbered unused descriptor for the new descriptor.
-
-.BR dup2 ()
-.RI "makes " newfd " be the copy of " oldfd ", closing " newfd
-first if necessary, but note the following:
-.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 .
-.PP
-After a successful return from one of these system calls,
-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 descriptors, the offset is also changed for the other.
-
-The two 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.
-
-.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 *
-.\" FIXME . To confirm with Al Viro that this was intended, and its rationale
-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 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, or
-.I newfd
-is out of the allowed range for file descriptors.
-.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.
-.\" FIXME . To confirm with Al Viro that this was intended, and its rationale
-Or,
-.I oldfd
-was equal to
-.IR newfd .
-.TP
-.B EMFILE
-The process already has the maximum number of file
-descriptors open and tried to open a new one.
-.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 ():
-SVr4, 4.3BSD, POSIX.1-2001.
-
-.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.
-A careful programmer will not use
-.BR dup2 ()
-or
-.BR dup3 ()
-without closing
-.I newfd
-first.
-.SH SEE ALSO
-.BR close (2),
-.BR fcntl (2),
-.BR open (2)
projects / thirdparty / man-pages.git / blobdiff