lib/libc/sys/dup.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)dup.2       8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/sys/dup.2,v 1.9.2.6 2001/12/14 18:34:00 ru Exp $
  34 .\" $DragonFly: src/lib/libc/sys/dup.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt DUP 2
  38 .Os
  39 .Sh NAME
  40 .Nm dup ,
  41 .Nm dup2
  42 .Nd duplicate an existing file descriptor
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In unistd.h
  47 .Ft int
  48 .Fn dup "int oldd"
  49 .Ft int
  50 .Fn dup2 "int oldd" "int newd"
  51 .Sh DESCRIPTION
  52 .Fn Dup
  53 duplicates an existing object descriptor and returns its value to
  54 the calling process
  55 .Fa ( newd
  56 =
  57 .Fn dup oldd ) .
  58 The argument
  59 .Fa oldd
  60 is a small non-negative integer index in
  61 the per-process descriptor table.  The value must be less
  62 than the size of the table, which is returned by
  63 .Xr getdtablesize 2 .
  64 The new descriptor returned by the call
  65 is the lowest numbered descriptor
  66 currently not in use by the process.
  67 .Pp
  68 The object referenced by the descriptor does not distinguish
  69 between
  70 .Fa oldd
  71 and
  72 .Fa newd
  73 in any way.
  74 Thus if
  75 .Fa newd
  76 and
  77 .Fa oldd
  78 are duplicate references to an open
  79 file,
  80 .Xr read 2 ,
  81 .Xr write 2
  82 and
  83 .Xr lseek 2
  84 calls all move a single pointer into the file,
  85 and append mode, non-blocking I/O and asynchronous I/O options
  86 are shared between the references.
  87 If a separate pointer into the file is desired, a different
  88 object reference to the file must be obtained by issuing an
  89 additional
  90 .Xr open 2
  91 call.
  92 The close-on-exec flag on the new file descriptor is unset.
  93 .Pp
  94 In
  95 .Fn dup2 ,
  96 the value of the new descriptor
  97 .Fa newd
  98 is specified.  If this descriptor is already in use and
  99 .Fa oldd
 100 \*(Ne
 101 .Fa newd ,
 102 the descriptor is first deallocated as if a
 103 .Xr close 2
 104 call had been used.
 105 If
 106 .Fa oldd
 107 is not a valid descriptor, then
 108 .Fa newd
 109 is not closed.
 110 If
 111 .Fa oldd
 112 ==
 113 .Fa newd
 114 and
 115 .Fa oldd
 116 is a valid descriptor, then
 117 .Fn dup2
 118 is successful, and does nothing.
 119 .Sh RETURN VALUES
 120 The value -1 is returned if an error occurs in either call.
 121 The external variable
 122 .Va errno
 123 indicates the cause of the error.
 124 .Sh ERRORS
 125 .Fn Dup
 126 and
 127 .Fn dup2
 128 fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EBADF
 131 .Fa Oldd
 132 or
 133 .Fa newd
 134 is not a valid active descriptor
 135 .It Bq Er EMFILE
 136 Too many descriptors are active.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr accept 2 ,
 140 .Xr close 2 ,
 141 .Xr fcntl 2 ,
 142 .Xr getdtablesize 2 ,
 143 .Xr open 2 ,
 144 .Xr pipe 2 ,
 145 .Xr socket 2 ,
 146 .Xr socketpair 2
 147 .Sh STANDARDS
 148 The
 149 .Fn dup
 150 and
 151 .Fn dup2
 152 function calls are expected to conform to
 153 .St -p1003.1-90 .
 154 .Sh HISTORY
 155 A
 156 .Fn dup
 157 and a
 158 .Fn dup2
 159 function call appeared in
 160 .At v7 .