man/man2/dup.2

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)dup.2       6.3 (Berkeley) 5/13/86
   6 .\"
   7 .TH DUP 2 "May 13, 1986"
   8 .UC 4
   9 .SH NAME
  10 dup, dup2 \- duplicate a descriptor
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <unistd.h>
  15
  16 int dup(int \fIoldd\fP)
  17 int dup2(int \fIoldd\fP, int \fInewd\fP)
  18 .SH DESCRIPTION
  19 .B Dup
  20 duplicates an existing descriptor.
  21 The argument \fIoldd\fP is a small non-negative integer index in
  22 the per-process descriptor table.  The value must be less
  23 than OPEN_MAX, the size of the table.
  24 The new descriptor returned by the call, let's name it
  25 .I newd,
  26 is the lowest numbered descriptor that is
  27 not currently in use by the process.
  28 .PP
  29 The object referenced by the descriptor does not distinguish
  30 between references using \fIoldd\fP and \fInewd\fP in any way.
  31 Thus if \fInewd\fP and \fIoldd\fP are duplicate references to an open
  32 file,
  33 .BR read (2),
  34 .BR write (2)
  35 and
  36 .BR lseek (2)
  37 calls all move a single pointer into the file,
  38 and append mode, non-blocking I/O and asynchronous I/O options
  39 are shared between the references.
  40 If a separate pointer into the file is desired, a different
  41 object reference to the file must be obtained by issuing an
  42 additional
  43 .BR open (2)
  44 call.
  45 The close-on-exec flag on the new file descriptor is unset.
  46 .PP
  47 In the second form of the call, the value of
  48 .IR newd
  49 desired is specified.  If this descriptor is already
  50 in use, the descriptor is first deallocated as if a
  51 .BR close (2)
  52 call had been done first.
  53 .I Newd
  54 is not closed if it equals
  55 .IR oldd .
  56 .SH "RETURN VALUE
  57 The value \-1 is returned if an error occurs in either call.
  58 The external variable
  59 .B errno
  60 indicates the cause of the error.
  61 .SH "ERRORS
  62 .B Dup
  63 and
  64 .B dup2
  65 fail if:
  66 .TP 15
  67 [EBADF]
  68 \fIOldd\fP or
  69 \fInewd\fP is not a valid active descriptor
  70 .TP 15
  71 [EMFILE]
  72 Too many descriptors are active.
  73 .SH NOTES
  74 .B Dup
  75 and
  76 .B dup2
  77 are now implemented using the
  78 .B F_DUPFD
  79 function of
  80 .BR fcntl (2),
  81 although the old system call interfaces still exist to support old programs.
  82 .SH "SEE ALSO"
  83 .BR open (2),
  84 .BR close (2),
  85 .BR fcntl (2),
  86 .BR pipe (2).