dup2()--Duplicate Open File Descriptor to Another Descriptor

 #include <unistd.h>

 int dup2(int fildes, int fildes2);  

The dup2() function returns a descriptor with the value fildes2. The descriptor refers to the same file as fildes, and it will close the file that fildes2 was associated with. For more information about the processing which may occur when the file is closed, see close()--Close File or Socket Descriptor.

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.

The following conditions apply:

• If fildes2 is less than zero or greater than or equal to OPEN_MAX, dup2() returns -1 and sets the errno global variable to [EBADF].
  
• If fildes is a valid descriptor and is equal to fildes2, dup2() returns fildes2 without closing it.
  
• If fildes is not a valid descriptor, dup2() fails and does not close fildes2.

This function works with descriptors for any type of object.

Parameters

fildes

(Input) A descriptor to be duplicated.

fildes2

(Input) The descriptor to which the duplication is made.

Authorities

No authorization is required.

Return Value

value

dup2() was successful. The value of fildes2 is returned.

-1

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

Error Conditions

If dup2() 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. If this function is called by a thread executing one of the scan-related exit programs (or any of its created threads), it will fail with error code [ENOTSUP]. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.
   
   
2. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400

Related Information

• The <unistd.h> file (see Header Files for UNIX^®-Type Functions)
  
• close()--Close File or Socket Descriptor
  
• creat()--Create or Rewrite File
  
• dup()--Duplicate Open File 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 <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.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";
  char fn2[] = "dup2.file";

  /* create original file */
  if((file_descriptor = creat(fn, S_IRUSR | S_IWUSR)) < 0)
    perror("creat() error");
  /* create file to dup to */
  else if((file_descriptor2 = creat(fn2, S_IWUSR)) < 0)
    perror("creat()error");
  /* dup file_descriptor to file_descriptor2; print results */
  else {
    print_file_id(file_descriptor);
    print_file_id(file_descriptor2);
    if ((file_descriptor2 = dup2(file_descriptor, file_descriptor2)) < 0)
      perror("dup2() error");
    else {
      puts("After dup2()...");
      print_file_id(file_descriptor);
      print_file_id(file_descriptor2);
      puts("The file descriptors are different but they");
      puts("point to the same file which is different than");
      puts("the file that the second file_descriptor originally pointed to.");
      close(file_descriptor);
      close(file_descriptor2);
    }
    unlink(fn);
    unlink(fn2);
  }
}

Output:

The file id of file_descriptor 0 is 30
The file id of file_descriptor 3 is 58
After dup2()...
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, which is different than
the file that the second file_descriptor originally pointed to.

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