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.
#define INCL_DOSQUEUES /* Queue values */ #define INCL_DOSERRORS /* DOS Error values */ #include <os2.h> #include <stdio.h> 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; }