dup()--Duplicate Open File Descriptor

 #include <unistd.h>

 int dup(int fildes);  

The dup() function returns a new open file descriptor. The new descriptor refers to the same open file as fildes and shares any locks.

If the original file descriptor was opened in text mode, data conversion is also done on the duplicated file descriptor.

The FD_CLOEXEC flag that is associated with the new file descriptor is cleared. Refer to fcntl()--Perform File Control Command for additional information about the FD_CLOEXEC flag.

Parameters

fildes

(Input) A descriptor to be duplicated.

The following operations are equivalent:

  fd = dup(fildes);
  fd = fcntl(fildes,F_DUPFD,0);

For further information, see fcntl()--Perform File Control Command.

Authorities

No authorization is required.

Return Value

value

dup() was successful. The value returned is the new descriptor.

-1

dup() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If dup() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [EBADF] when fildes is a scan descriptor that was passed to one of the scan-related exit programs. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.
   
   

Related Information

• The <unistd.h> file (see Header Files for UNIX^®-Type Functions)
  
• close()--Close File or Socket Descriptor
  
• creat()--Create or Rewrite File
  
• dup2()--Duplicate Open File Descriptor to Another Descriptor
  
• fcntl()--Perform File Control Command
  
• open()--Open File

Example

The following example duplicates an open descriptor.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <fcntl.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <errno.h>

void print_file_id(int file_descriptor) {
  struct stat info;
  if (fstat(file_descriptor, &info) != 0)
    fprintf(stderr, "stat() error for file_descriptor %d: %s\n",
            strerror(errno));
  else
    printf("The file id of file_descriptor %d is %d\n",
           file_descriptor,(int) info.st_ino);
}

main() {
  int file_descriptor, file_descriptor2;
  char fn[]="original.file";

  /* create original file */
  if((file_descriptor = creat(fn,S_IRUSR | S_IWUSR)) < 0)
    perror("creat() error");
  /* generate a duplicate file descriptor of file_descriptor */
  else {
    if ((file_descriptor2 = dup(file_descriptor)) < 0)
      perror("dup() error");
    /* print resulting information */
    else {
      print_file_id(file_descriptor);
      print_file_id(file_descriptor2);
      puts("The file descriptors are different but");
      puts("they point to the same file.");
      close(file_descriptor);
      close(file_descriptor2);
    }
    unlink(fn);
  }
}

Output:

The file id of file_descriptor 0 is 30
The file id of file_descriptor 3 is 30
The file descriptors are different but
they point to the same file.

[ Back to top | UNIX-Type APIs | APIs by category ]