dup()

duplicate a file descriptor

Synopsis:

#include <unistd.h>
int dup( int filedes );

Description:

The dup() function duplicates the file descriptor given by the argument filedes. The new file descriptor refers to the same open file descriptor as the original file descriptor, and shares any locks. The new file descriptor is identical to the original, in that:

• it references the same file or device
• it has the same open mode (read and/or write)
• it will have a file position identical to the original

Changing the position with one descriptor will result in a changed position in the other.

The call

    dup_filedes = dup( filedes );

is equivalent to:

    dup_filedes = fcntl( filedes, F_DUPFD, 0 );

Returns:

If successful, the new file descriptor is returned to be used with the other functions that operate on the file. Otherwise, -1 is returned, and errno is set to indicate the error.

Errors:

EBADF

The argument filedes is not a valid open file descriptor.

EMFILE

The number of file descriptors would exceed OPEN_MAX.

Examples:

#include <fcntl.h>
#include <unistd.h>
#include <sys/stat.h>

void main()
  {
    int filedes, dup_filedes;

    filedes= open( "file",
        O_WRONLY | O_CREAT | O_TRUNC,
        S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( filedes != -1 ) {
      dup_filedes = dup( filedes );
      if( dup_filedes != -1 ) {

        /* process file */

        close( dup_filedes );
      }
      close( filedes );
    }
  }

Classification:

POSIX 1003.1

See also:

chsize(), close(), creat(), dup2(), eof(), errno, exec... functions, fcntl(), filelength(), fileno(), fstat(), isatty(), lseek(), open(), read(), setmode(), sopen(), stat(), tell(), umask(), write()