lib/libcr/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 .\"
  35 .Dd June 4, 1993
  36 .Dt DUP 2
  37 .Os
  38 .Sh NAME
  39 .Nm dup ,
  40 .Nm dup2
  41 .Nd duplicate an existing file descriptor
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In unistd.h
  46 .Ft int
  47 .Fn dup "int oldd"
  48 .Ft int
  49 .Fn dup2 "int oldd" "int newd"
  50 .Sh DESCRIPTION
  51 .Fn Dup
  52 duplicates an existing object descriptor and returns its value to
  53 the calling process
  54 .Fa ( newd
  55 =
  56 .Fn dup oldd ) .
  57 The argument
  58 .Fa oldd
  59 is a small non-negative integer index in
  60 the per-process descriptor table.  The value must be less
  61 than the size of the table, which is returned by
  62 .Xr getdtablesize 2 .
  63 The new descriptor returned by the call
  64 is the lowest numbered descriptor
  65 currently not in use by the process.
  66 .Pp
  67 The object referenced by the descriptor does not distinguish
  68 between
  69 .Fa oldd
  70 and
  71 .Fa newd
  72 in any way.
  73 Thus if
  74 .Fa newd
  75 and
  76 .Fa oldd
  77 are duplicate references to an open
  78 file,
  79 .Xr read 2 ,
  80 .Xr write 2
  81 and
  82 .Xr lseek 2
  83 calls all move a single pointer into the file,
  84 and append mode, non-blocking I/O and asynchronous I/O options
  85 are shared between the references.
  86 If a separate pointer into the file is desired, a different
  87 object reference to the file must be obtained by issuing an
  88 additional
  89 .Xr open 2
  90 call.
  91 The close-on-exec flag on the new file descriptor is unset.
  92 .Pp
  93 In
  94 .Fn dup2 ,
  95 the value of the new descriptor
  96 .Fa newd
  97 is specified.  If this descriptor is already in use and
  98 .Fa oldd
  99 \*(Ne
 100 .Fa newd ,
 101 the descriptor is first deallocated as if a
 102 .Xr close 2
 103 call had been used.
 104 If
 105 .Fa oldd
 106 is not a valid descriptor, then
 107 .Fa newd
 108 is not closed.
 109 If
 110 .Fa oldd
 111 ==
 112 .Fa newd
 113 and
 114 .Fa oldd
 115 is a valid descriptor, then
 116 .Fn dup2
 117 is successful, and does nothing.
 118 .Sh RETURN VALUES
 119 The value -1 is returned if an error occurs in either call.
 120 The external variable
 121 .Va errno
 122 indicates the cause of the error.
 123 .Sh ERRORS
 124 .Fn Dup
 125 and
 126 .Fn dup2
 127 fail if:
 128 .Bl -tag -width Er
 129 .It Bq Er EBADF
 130 .Fa Oldd
 131 or
 132 .Fa newd
 133 is not a valid active descriptor
 134 .It Bq Er EMFILE
 135 Too many descriptors are active.
 136 .El
 137 .Sh SEE ALSO
 138 .Xr accept 2 ,
 139 .Xr close 2 ,
 140 .Xr fcntl 2 ,
 141 .Xr getdtablesize 2 ,
 142 .Xr open 2 ,
 143 .Xr pipe 2 ,
 144 .Xr socket 2 ,
 145 .Xr socketpair 2
 146 .Sh STANDARDS
 147 The
 148 .Fn dup
 149 and
 150 .Fn dup2
 151 function calls are expected to conform to
 152 .St -p1003.1-90 .
 153 .Sh HISTORY
 154 A
 155 .Fn dup
 156 and a
 157 .Fn dup2
 158 function call appeared in
 159 .At v7 .