DosDupHandle

Gets a new handle for an open file.

Syntax
DosDupHandle(hFile, pHfile)

Parameters

 * hFile (HFILE) - input : File handle to duplicate, or alias.
 * pHfile (PHFILE) - in/out : A pointer to the HFILE in which file handle information is stored.
 * Input - Contents of the address describes how the handle is to be duplicated. Possible values are shown in the list below:
 * 0xFFFFFFFF - Allocate a new file handle and return it here.
 * Any other value - Assign this value as the new file handle. A valid value is any of the handles assigned to standard I/O, or the handle of a file currently opened by the process.
 * Output - Contents of the address contains the duplicate file handle.
 * A value of 0xFFFFFFFF returns a value for pHfile, allocated by the operating system.

Return Code

 * ulrc (APIRET) - returns:DosDupHandle returns one of the following values:
 * 0 NO_ERROR
 * 4 ERROR_TOO_MANY_OPEN_FILES
 * 6 ERROR_INVALID_HANDLE
 * 114 ERROR_INVALID_TARGET_HANDLE

Remarks
Duplicating the handle duplicates and ties all handle-specific information between hFile and pHfile. For example, if you move the read/write pointer of either handle with DosRead, DosSetFilePtr, or DosWrite, the pointer for the other handle also is changed.

The valid values for pHfile include the following handles for standard I/O, which are always available to the process:
 * 0x00000000 Standard input
 * 0x00000001 Standard output
 * 0x00000002 Standard error.

If a file-handle value of a currently open file is specified in pHfile the file handle is closed before it is redefined as the duplicate of hFile. Avoid using arbitrary values for pHfile.

Issuing DosClose for a file handle does not affect the duplicate handle.

Protected file handles cannot be duplicated.

Example Code
This example creates a pipe and duplicates its read/write handles. 
 * 1) define INCL_DOSQUEUES       /* Queue values */
 * 2) define INCL_DOSERRORS       /* DOS Error values */
 * 3) include 
 * 4) include 

int main(VOID) {

HFILE   ReadHandle     = NULLHANDLE; /* Read handle of pipe */ HFILE   WriteHandle    = NULLHANDLE; /* Write handle of pipe */ HFILE   NewReadHandle  = (HFILE) -1; /* Duplicate read handle */ HFILE   NewWriteHandle = (HFILE) 10; /* Duplicate write handle */ ULONG   PipeSize       = 42;         /* Size of pipe */ APIRET  rc             = NO_ERROR;   /* API return code */

rc = DosCreatePipe ( &ReadHandle, &WriteHandle, PipeSize ); if (rc != NO_ERROR) { printf("DosCreatePipe error: return code = %u\n", rc); return 1; }     /* Duplicate Read Handle of Pipe - use next available handle */

rc = DosDupHandle ( ReadHandle, &NewReadHandle ); if (rc != NO_ERROR) { printf("DosDupHandle error: return code = %u\n", rc); return 1; }     /* Duplicate Write Handle of Pipe - use handle 10 */

rc = DosDupHandle ( ReadHandle, &NewWriteHandle ); if (rc != NO_ERROR) { printf("DosDupHandle error: return code = %u\n", rc); return 1; }

printf("Handles are: Read:%u Write:%u  NewRead:%u  NewWrite:%u\n",            ReadHandle, WriteHandle, NewReadHandle, NewWriteHandle);

return NO_ERROR; } 

Related Functions

 * DosClose
 * DosCreatePipe
 * DosOpen
 * DosRead
 * DosSetFHState
 * DosSetFilePtr
 * DosSetMaxFH
 * DosSetRelMaxFH
 * DosWrite