Microsoft KB Archive/99173

{|
 * width="100%"|

INFO: Types of File I/O Under Win32

 * }

Q99173

-

The information in this article applies to:


 * Microsoft Win32 Application Programming Interface (API), used with:
 * the operating system: Microsoft Windows NT, versions 3.1, 3.5, 3.51, 4.0
 * Microsoft Windows 95
 * the operating system: Microsoft Windows 2000

-

SUMMARY
There are multiple types of file handles that can be opened using the Win32 API and the C Run-time:

  Returned Type  File Creation API      API Set -  HANDLE         CreateFile           Win32 HFILE         OpenFile/_lcreat   Win32 int           _creat/_open       C Run-time FILE *        fopen                C Run-time In general, these file I/O &quot;families&quot; are incompatible with each other. On some implementations of the Win32 application programming interfaces (APIs), the OpenFile/_lcreat family of file I/O APIs are implemented as &quot;wrappers&quot; around the CreateFile family of file I/O APIs, meaning that OpenFile, _lcreat, and _lopen end up calling CreateFile, returning the handle returned by CreateFile, and do not maintain any state information about the file themselves. However, this is an implementation detail only and is NOT a design feature.

NOTE: You cannot count on this being true on other implementations of the Win32 APIs. Win32 file I/O APIs may be written using different methods on other platforms, so reliance on this implementation detail may cause your application to fail.

The rule to follow is to use one family of file I/O APIs and stick with them--do not open a file with _lopen and read from it with ReadFile, for example. This kind of incorrect use of the file I/O APIs can easily be caught by the compiler, because the file types (HFILE and HANDLE respectively) are incompatible with each other and the compiler will warn you (at warning level /w3 or higher) when you have incorrectly passed one type of file handle to a file I/O API that is expecting another, such as passing an HFILE type to ReadFile(HANDLE, ...) in the above example.

Compatibility
The OpenFile family of file I/O functions is provided only for compatibility with earlier versions of Windows. New Win32-based applications should use the CreateFile family of file I/O APIs, which provide added functionality that the earlier file I/O APIs do not provide.

Each of the two families of C Run-time file I/O APIs are incompatible with any of the other file I/O families. It is incorrect to open a file handle with one of the C Run-time file I/O APIs and operate on that file handle with any other family of file I/O APIs, nor can a C Run-time file I/O family operate on file handles opened by any other file I/O family.

_get_osfhandle
For the C Run-time unbuffered I/O family of APIs [_open, and so forth], it is possible to extract the operating system handle that is associated with that C run-time handle via the _get_osfhandle C Run-time API. The operating system handle is the handle stored in a C Run-time internal structure associated with that C Run-time file handle. This operating system handle is the handle that is returned from an operating system call made by the C Run-time to open a file [CreateFile in this case] when you call one of the C Run-time unbuffered I/O APIs [_open, _creat, _sopen, and so forth].

The _get_osfhandle C Run-time call is provided for informational purposes only. Problems may occur if you read or write to the file using the operating system handle returned from _get_osfhandle; for these reasons we recommend that you do not use the returned handle to read or write to the file.

_open_osfhandle
It is also possible to construct a C Run-time unbuffered file I/O handle from an operating system handle [a CreateFile handle] with the _open_osfhandle C Run-time API. In this case, the C Run-time uses the existing operating system handle that you pass in rather than opening the file itself. It is possible to use the original operating system handle to read or write to the file, but it is very important that you use only the original handle or the returned C Run-time handle to access the file, but not both, because the C Run-time maintains state information that will not be updated if you use the operating system handle to read or write to the file.

Additional query words: 3.10 3.50

Keywords : kbAPI kbFileIO kbKernBase kbOSWinNT310 kbOSWinNT350 kbOSWinNT351 kbOSWinNT400 kbOSWin2000 kbOSWin95 kbDSupport kbGrpDSKernBase

Issue type : kbinfo

Technology : kbAudDeveloper kbWin32sSearch kbWin32API