dup -- Associate Second Handle with Open File

Format

#include <io.h>
int dup(int handle);

Language Level: XPG4, Extension
dup associates a second file handle with a currently open file. You can carry out operations on the file using either file handle because all handles associated with a given file use the same file pointer. Creation of a new handle does not affect the type of access allowed for the file.

For example, given:

handle2 = dup(handle1)

handle2 will have the same file access mode (text or binary) as handle1. In addition, if handle1 was originally opened with the O_APPEND flag (described in open -- Open File), handle2 will also have that attribute.

Warning!
Both handles share a single file pointer. If you reposition a file using handle1, the position in the file returned by handle2 will also change.

If you duplicate a file handle for an open stream, the resulting file handle has the same restrictions as the original file handle.

Note: In earlier releases of the C/C++ run-time library, dup began with an underscore (_dup). Because it is defined by the X/Open standard, the underscore has been removed. For compatibility, IBM C and C++ Compilers will map _dup to dup for you.

Return Value
dup returns the next available file handle for the given file. It returns -1 if an error occurs and sets errno to one of the following values:

Value Meaning
EBADF The file handle is not valid.
EMFILE No more file handles are available.
EOS2ERR The call to the operating system was not successful.

Example



close -- Close File Associated with Handle
creat -- Create New File
dup2 -- Associate Second Handle with Open File
open -- Open File
_sopen -- Open Shared File
<io.h>