original/man2/dup.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\" and Copyright (C) 2005, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Modified 1993-07-21, Rik Faith <faith@cs.unc.edu>
  28 .\" Modified 1994-08-21, Michael Chastain <mec@shell.portal.com>:
  29 .\"   Fixed typoes.
  30 .\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
  31 .\" Modified 2002-09-28, aeb
  32 .\" 2009-01-12, mtk, reordered text in DESCRIPTION and added some
  33 .\"     details for dup2().
  34 .\" 2008-10-09, mtk: add description of dup3()
  35 .\"
  36 .TH DUP 2 2012-02-14 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 dup, dup2, dup3 \- duplicate a file descriptor
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <unistd.h>
  42 .sp
  43 .BI "int dup(int " oldfd );
  44 .BI "int dup2(int " oldfd ", int " newfd );
  45 .sp
  46 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  47 .BR "#include <fcntl.h>" "              /* Obtain O_* constant definitions */
  48 .B #include <unistd.h>
  49 .sp
  50 .BI "int dup3(int " oldfd ", int " newfd ", int " flags );
  51 .fi
  52 .SH DESCRIPTION
  53 These system calls create a copy of the file descriptor
  54 .IR oldfd .
  55
  56 .BR dup ()
  57 uses the lowest-numbered unused descriptor for the new descriptor.
  58
  59 .BR dup2 ()
  60 .RI "makes " newfd " be the copy of " oldfd ", closing " newfd
  61 first if necessary, but note the following:
  62 .IP * 3
  63 If
  64 .I oldfd
  65 is not a valid file descriptor, then the call fails, and
  66 .I newfd
  67 is not closed.
  68 .IP *
  69 If
  70 .I oldfd
  71 is a valid file descriptor, and
  72 .I newfd
  73 has the same value as
  74 .IR oldfd ,
  75 then
  76 .BR dup2 ()
  77 does nothing, and returns
  78 .IR newfd .
  79 .PP
  80 After a successful return from one of these system calls,
  81 the old and new file descriptors may be used interchangeably.
  82 They refer to the same open file description (see
  83 .BR open (2))
  84 and thus share file offset and file status flags;
  85 for example, if the file offset is modified by using
  86 .BR lseek (2)
  87 on one of the descriptors, the offset is also changed for the other.
  88
  89 The two descriptors do not share file descriptor flags
  90 (the close-on-exec flag).
  91 The close-on-exec flag
  92 .RB ( FD_CLOEXEC ;
  93 see
  94 .BR fcntl (2))
  95 for the duplicate descriptor is off.
  96
  97 .BR dup3 ()
  98 is the same as
  99 .BR dup2 (),
 100 except that:
 101 .IP * 3
 102 The caller can force the close-on-exec flag to be set
 103 for the new file descriptor by specifying
 104 .BR O_CLOEXEC
 105 in
 106 .IR flags .
 107 See the description of the same flag in
 108 .BR open (2)
 109 for reasons why this may be useful.
 110 .IP *
 111 .\" FIXME . To confirm with Al Viro that this was intended, and its rationale
 112 If
 113 .IR oldfd
 114 equals
 115 .IR newfd ,
 116 then
 117 .BR dup3 ()
 118 fails with the error
 119 .BR EINVAL .
 120 .SH RETURN VALUE
 121 On success, these system calls
 122 return the new descriptor.
 123 On error, \-1 is returned, and
 124 .I errno
 125 is set appropriately.
 126 .SH ERRORS
 127 .TP
 128 .B EBADF
 129 .I oldfd
 130 isn't an open file descriptor, or
 131 .I newfd
 132 is out of the allowed range for file descriptors.
 133 .TP
 134 .B EBUSY
 135 (Linux only) This may be returned by
 136 .BR dup2 ()
 137 or
 138 .BR dup3 ()
 139 during a race condition with
 140 .BR open (2)
 141 and
 142 .BR dup ().
 143 .TP
 144 .B EINTR
 145 The
 146 .BR dup2 ()
 147 or
 148 .BR dup3 ()
 149 call was interrupted by a signal; see
 150 .BR signal (7).
 151 .TP
 152 .B EINVAL
 153 .RB ( dup3 ())
 154 .I flags
 155 contain an invalid value.
 156 .\" FIXME . To confirm with Al Viro that this was intended, and its rationale
 157 Or,
 158 .I oldfd
 159 was equal to
 160 .IR newfd .
 161 .TP
 162 .B EMFILE
 163 The process already has the maximum number of file
 164 descriptors open and tried to open a new one.
 165 .SH VERSIONS
 166 .BR dup3 ()
 167 was added to Linux in version 2.6.27;
 168 glibc support is available starting with
 169 version 2.9.
 170 .SH CONFORMING TO
 171 .BR dup (),
 172 .BR dup2 ():
 173 SVr4, 4.3BSD, POSIX.1-2001.
 174
 175 .BR dup3 ()
 176 is Linux-specific.
 177 .\" SVr4 documents additional
 178 .\" EINTR and ENOLINK error conditions.  POSIX.1 adds EINTR.
 179 .\" The EBUSY return is Linux-specific.
 180 .SH NOTES
 181 The error returned by
 182 .BR dup2 ()
 183 is different from that returned by
 184 .BR fcntl( "..., " F_DUPFD ", ..." )
 185 when
 186 .I newfd
 187 is out of range.
 188 On some systems,
 189 .BR dup2 ()
 190 also sometimes returns
 191 .B EINVAL
 192 like
 193 .BR F_DUPFD .
 194
 195 If
 196 .I newfd
 197 was open, any errors that would have been reported at
 198 .BR close (2)
 199 time are lost.
 200 A careful programmer will not use
 201 .BR dup2 ()
 202 or
 203 .BR dup3 ()
 204 without closing
 205 .I newfd
 206 first.
 207 .SH SEE ALSO
 208 .BR close (2),
 209 .BR fcntl (2),
 210 .BR open (2)
 211 .SH COLOPHON
 212 This page is part of release 3.68 of the Linux
 213 .I man-pages
 214 project.
 215 A description of the project,
 216 information about reporting bugs,
 217 and the latest version of this page,
 218 can be found at
 219 \%http://www.kernel.org/doc/man\-pages/.