bsd/man/man2/dup.2

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