Share via


Retrieves the operating-system file handle that is associated with the specified file descriptor.


intptr_t _get_osfhandle(
   int fd


An existing file descriptor.

Return value

Returns an operating-system file handle if fd is valid. Otherwise, the invalid parameter handler is invoked, as described in Parameter validation. If execution is allowed to continue, it returns INVALID_HANDLE_VALUE (-1). It also sets errno to EBADF, indicating an invalid file handle. To avoid a warning when the result is used as a Win32 file handle, cast it to a HANDLE type.


When stdin, stdout, and stderr aren't associated with a stream (for example, in a Windows application without a console window), the file descriptor values for these streams are returned from _fileno as the special value -2. Similarly, if you use a 0, 1, or 2 as the file descriptor parameter instead of the result of a call to _fileno, _get_osfhandle also returns the special value -2 when the file descriptor is not associated with a stream, and does not set errno. However, this is not a valid file handle value, and subsequent calls that attempt to use it are likely to fail.

For more information about EBADF and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.


To close a file whose operating system (OS) file handle is obtained by _get_osfhandle, call _close on the file descriptor fd. Never call CloseHandle on the return value of this function. The underlying OS file handle is owned by the fd file descriptor, and is closed when _close is called on fd. If the file descriptor is owned by a FILE * stream, then calling fclose on that FILE * stream closes both the file descriptor and the underlying OS file handle. In this case, don't call _close on the file descriptor.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.


Routine Required header
_get_osfhandle <io.h>

For more compatibility information, see Compatibility.

See also

File handling
_creat, _wcreat
_dup, _dup2
_open, _wopen