dup

Purpose

     Duplicates an open file descriptor.

Syntax

     int dup (fildes)
     int fildes;

Description

     The dup system call returns a new file descriptor for the
     file descriptor pointed to  by the fildes parameter.  The
     fildes  parameter is  a file  descriptor obtained  from a
     creat, open, dup, fcntl, or pipe system call, or from the
     socket  or socketpair  subroutine.  The  dup system  call
     returns  a new  file descriptor  having the  following in
     common with the original:

     o   The same open file or pipe
     o   The same file pointer (that is, both file descriptors
         share one file pointer)
     o   The same access mode (read, write or read/write)
     o   The same file status flags
     o   The same locks.

     The new file descriptor is set to remain open across exec
     system calls.  (For more  information about file control,
     see "fcntl.h.")

     The file descriptor returned is the lowest one available.

Return Value

     Upon successful  completion, a file  descriptor (nonnega-
     tive integer) is returned.  If the dup system call fails,
     a value  of -1 is returned  and errno is set  to indicate
     the error.

Diagnostics

     The dup system call fails if one or more of the following
     are true:

     EBADF      fildes is not a valid open file descriptor.

     EMFILE     Two  hundred (200)  file descriptors  are cur-
                rently open.

Related Information

     In this book:  "close,"   "creat," "dup2," "exec:  execl,
     execv, execle, execve,  execlp, execvp," "open,"  "pipe,"
     "socket," "socketpair," and "fcntl.h."