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