original/man2/dup.2

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