DosDupHandle
Description
Gets a new handle for an open file.
Syntax
#define INCL_DOSFILEMGR #include <os2.h> HFILE hFile; /* File handle to duplicate, or alias. */ PHFILE pHfile; /* A pointer to the HFILE in which file handle informtion is stored. */ APIRET ulrc; /* Return Code. */ ulrc = 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;
}