# dup

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           dup, dup2 — duplicate an open file descriptor
    


## SYNOPSIS



           #include <unistd.h>
    
           int dup(int _fildes_);
           int dup2(int _fildes_ , int _fildes2_);
    


## DESCRIPTION



           The _dup_() function provides an alternative interface to the
           service provided by _fcntl_() using the F_DUPFD command. The call
           _dup_(_fildes_) shall be equivalent to:
    
               fcntl(fildes, F_DUPFD, 0);
    
           The _dup2_() function shall cause the file descriptor _fildes2_ to
           refer to the same open file description as the file descriptor
           _fildes_ and to share any locks, and shall return _fildes2_.  If
           _fildes2_ is already a valid open file descriptor, it shall be
           closed first, unless _fildes_ is equal to _fildes2_ in which case
           _dup2_() shall return _fildes2_ without closing it. If the close
           operation fails to close _fildes2_ , _dup2_() shall return -1 without
           changing the open file description to which _fildes2_ refers. If
           _fildes_ is not a valid file descriptor, _dup2_() shall return -1 and
           shall not close _fildes2_.  If _fildes2_ is less than 0 or greater
           than or equal to {OPEN_MAX}, _dup2_() shall return -1 with _errno_ set
           to **[EBADF]**.
    
           Upon successful completion, if _fildes_ is not equal to _fildes2_ , the
           FD_CLOEXEC flag associated with _fildes2_ shall be cleared. If
           _fildes_ is equal to _fildes2_ , the FD_CLOEXEC flag associated with
           _fildes2_ shall not be changed.
    
           If _fildes_ refers to a typed memory object, the result of the
           _dup2_() function is unspecified.
    


## RETURN VALUE



           Upon successful completion a non-negative integer, namely the file
           descriptor, shall be returned; otherwise, -1 shall be returned and
           _errno_ set to indicate the error.
    


## ERRORS



           The _dup_() function shall fail if:
    
           **EBADF** The _fildes_ argument is not a valid open file descriptor.
    
           **EMFILE** All file descriptors available to the process are currently
                  open.
    
           The _dup2_() function shall fail if:
    
           **EBADF** The _fildes_ argument is not a valid open file descriptor or
                  the argument _fildes2_ is negative or greater than or equal
                  to {OPEN_MAX}.
    
           **EINTR** The _dup2_() function was interrupted by a signal.
    
           The _dup2_() function may fail if:
    
           **EIO** An I/O error occurred while attempting to close _fildes2_.
    
           _The following sections are informative._
    


## EXAMPLES



       **Redirecting Standard Output to a File S**
           The following example closes standard output for the current
           processes, re-assigns standard output to go to the file referenced
           by _pfd_ , and closes the original file descriptor to clean up.
    
               #include <unistd.h>
               ...
               int pfd;
               ...
               close(1);
               dup(pfd);
               close(pfd);
               ...
    
       **Redirecting Error Messages**
           The following example redirects messages from _stderr_ to _stdout_.
    
               #include <unistd.h>
               ...
               dup2(1, 2);
               ...
    


## APPLICATION USAGE



           Implementations may use file descriptors that must be inherited
           into child processes for the child process to remain conforming,
           such as for message catalog or tracing purposes. Therefore, an
           application that calls _dup2_() with an arbitrary integer for
           _fildes2_ risks non-conforming behavior, and _dup2_() can only
           portably be used to overwrite file descriptor values that the
           application has obtained through explicit actions, or for the
           three file descriptors corresponding to the standard file streams.
           In order to avoid a race condition of leaking an unintended file
           descriptor into a child process, an application should consider
           opening all file descriptors with the FD_CLOEXEC bit set unless
           the file descriptor is intended to be inherited across _exec_.
    


## RATIONALE



           The _dup_() function is redundant. Its services are also provided by
           the _fcntl_() function. It has been included in this volume of
           POSIX.1‐2017 primarily for historical reasons, since many existing
           applications use it. On the other hand, the _dup2_() function
           provides unique services, as no other interface is able to
           atomically replace an existing file descriptor.
    
           The _dup2_() function is not marked obsolescent because it presents
           a type-safe version of functionality provided in a type-unsafe
           version by _fcntl_().  It is used in the POSIX Ada binding.
    
           The _dup2_() function is not intended for use in critical regions as
           a synchronization mechanism.
    
           In the description of **[EBADF]** , the case of _fildes_ being out of
           range is covered by the given case of _fildes_ not being valid. The
           descriptions for _fildes_ and _fildes2_ are different because the only
           kind of invalidity that is relevant for _fildes2_ is whether it is
           out of range; that is, it does not matter whether _fildes2_ refers
           to an open file when the _dup2_() call is made.
    


## FUTURE DIRECTIONS



           None.
    


* * *