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;
}

Related Functions

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