Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosDupHandle(hfOld, phfNew)
HFILE hfOld;      /* handle of existing file                        */
PHFILE phfNew;    /* pointer to variable containing new file handle */
 
The DosDupHandle function duplicates a file handle. The new handle has the
same handle-specific information as the existing handle, such as its
file-pointer position and access method. The original handle and the
duplicate are interchangeable, since most changes to one affect the other.
For example, moving the file pointer for the original handle moves the
pointer for the new handle. Closing the original handle by using the
DosClose function does not close the duplicate handle, however, and closing
the duplicate does not close the original. A file is not closed until its
last handle is closed.
 
The DosDupHandle function is a family API function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hfOld      Identifies the file handle to duplicate. This handle must have
           been created previously by using the DosOpen function. The
           DosDupHandle function closes the file before duplicating its
           handle.
 
phfNew     Points to the variable that contains the new file handle. If this
           parameter is 0xFFFF, the DosDupHandle function creates a new
           handle and copies it to the variable pointed to by the phfNew
           parameter. Any specified value other than 0xFFFF is used as the
           handle.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_INVALID_HANDLE
     ERROR_INVALID_TARGET_HANDLE
     ERROR_TOO_MANY_OPEN_FILES
 
Comments
 
You can change the inheritance, fail-on-error, and write-through flags for
the duplicate file handle by using the DosSetFHandState function.
 
Example
 
This example calls the DosDupHandle function to duplicate the standard
output handle, and then writes "Hello World" to the new handle:
 
HFILE hfNew;
USHORT, cbBytesWritten;
hfNew = 0xFFFF;                  /* create new handle         */
DosDupHandle(1, &hfNew);         /* duplicate standard output */
DosWrite(hfNew, "Hello World\r\n", 13, &cbBytesWritten);
 
See Also
 
DosChgFilePtr, DosClose, DosExecPgm, DosMakePipe, DosOpen, DosRead,
DosSetFHandState, DosWrite
 
                                      ♦