dup()--Duplicate Open File Descriptor
Syntax
#include <unistd.h> int dup(int fildes);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Yes
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 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] | |
[EBUSY] | |
[ECANCEL] | |
[EINVAL] | |
[EIO] | |
[ENOSYS] | |
[ENOTAVAIL] | |
[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
- 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.
API introduced: V3R1