home | help 
DUP(2)			       System Calls Manual			  DUP(2)

NAME
     dup, dup2 -- duplicate an existing file descriptor

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <unistd.h>

     int
     dup(int oldd);

     int
     dup2(int oldd, int newd);

DESCRIPTION
     The  dup() system call duplicates an existing object descriptor and returns
     its value to the calling process (newd = dup(oldd)).  The argument oldd  is
     a	small  non-negative  integer  index in the per-process descriptor table.
     The value must be less than the size of the table,  which	is  returned  by
     getdtablesize(2).	 The  new  descriptor returned by the call is the lowest
     numbered descriptor currently not in use by the process.

     The object referenced by the descriptor does not distinguish  between  oldd
     and  newd in any way.  Thus if newd and oldd are duplicate references to an
     open file, read(2), write(2) and lseek(2) calls all move a  single  pointer
     into  the	file, and append mode, non-blocking I/O and asynchronous I/O op-
     tions are shared between the references.  If a separate  pointer  into  the
     file  is desired, a different object reference to the file must be obtained
     by issuing an additional open(2) system call.  The  close-on-exec	flag  on
     the new file descriptor is unset.

     In  dup2(), the value of the new descriptor newd is specified.  If this de-
     scriptor is already in use and oldd != newd, the descriptor is first  deal-
     located  as  if  the  close(2) system call had been used.	If oldd is not a
     valid descriptor, then newd is not closed.  If oldd == newd and oldd  is  a
     valid descriptor, then dup2() is successful, and does nothing.

RETURN VALUES
     The  value  -1 is returned if an error occurs in either call.  The external
     variable errno indicates the cause of the error.

ERRORS
     The dup() and dup2() system calls fail if:

     [EBADF]		The oldd or newd argument is not a valid active descrip-
			tor

     [EMFILE]		Too many descriptors are active.

SEE ALSO
     accept(2),  close(2),   fcntl(2),	 getdtablesize(2),   open(2),	pipe(2),
     socket(2), socketpair(2)

STANDARDS
     The  dup()  and  dup2()  system  calls  are  expected to conform to ISO/IEC
     9945-1:1990 ("POSIX.1").

HISTORY
     The dup() and dup2() functions appeared in Version 7 AT&T UNIX.

FreeBSD 8.0			  June 4, 1993				  DUP(2)
home | help