dup2()--Duplicate Open File Descriptor to Another Descriptor
Syntax
#include <unistd.h> int dup2(int fildes, int fildes2);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
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 condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EBADF] | |
[EBADFID] | |
[EIO] | |
[ENOTSAFE] | |
[ENOTSUP] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- 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.
- 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
- Where multiple threads exist in the job.
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.
API introduced: V3R1