_wfdopen (Windows CE 5.0)

Article
09/14/2012

Developing an Application > Microsoft C Run-time Library for Windows CE > Run-time Library Reference

Associate a stream with a file that was previously opened for low-level I/O.

FILE *_wfdopen( inthandle, constwchar_t *mode);

Parameters

handle
Handle to open file.
mode
Type of file access.

Return Values

This function returns a pointer to the open stream. A null pointer value indicates an error.

Remarks

These functions are supported by all versions of the C run-time libraries.

The _wfdopen function associates an I/O stream with the file identified by handle, thus allowing a file opened for low-level I/O to be buffered and formatted. The mode argument to _wfdopen is a wide-character string.

The following table shows generic-text routine mappings for this function.

TCHAR.H Routine	_UNICODE Defined
_tfdopen	_wfdopen

For more information about TCHAR.H routines, see Generic Text Mappings.

The mode character string specifies the type of file and file access.

The character string mode specifies the type of access requested for the file, as follows:

"r"
Opens for reading. If the file does not exist or cannot be found, the fopen call fails.
"w"
Opens an empty file for writing. If the given file exists, its contents are destroyed.
"a"
Opens for writing at the end of the file (appending); creates the file first if it doesn't exist.
"r+"
Opens for both reading and writing. (The file must exist.)
"w+"
Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed.
"a+"
Opens for reading and appending; creates the file first if it doesn't exist.

When a file is opened with the "a" or "a+" access type, all write operations occur at the end of the file.

The file pointer can be repositioned using fseek, but is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten.

When the "r+", "w+", or "a+" access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening fflush, fsetpos, or fseek operation.

The current position can be specified for the fsetpos or fseek operation, if desired.

In addition to the above values, the following characters can be included in mode to specify the translation mode for newline characters:

t
Open in text (translated) mode. In this mode, carriage return–linefeed (CR-LF) combinations are translated into single linefeeds (LF) on input, and LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input.

In files opened for reading/writing, fopen checks for a CTRL+Z at the end of the file and removes it, if possible. This is done because using the fseek and ftell functions to move within a file that ends with a CTRL+Z may cause fseek to behave improperly near the end of the file.
b
Open in binary (untranslated) mode; the above translations are suppressed.
c
Enable the commit flag for the associated filename so that the contents of the file buffer are written directly to disk if either fflush or _flushall is called.
n
Reset the commit flag for the associated filename to "no-commit." This is the default.

The t, c, and nmode options are Microsoft extensions for fopen and should not be used where ANSI portability is desired.

If t or b is not given in mode, the default translation mode is defined by the global variable _fmode. If t or b is prefixed to the argument, the function fails and returns NULL.

Example

Description

This program opens a file using low- level I/O, then uses _fdopen to switch to stream access. It counts the lines in the file.

Code

#include <stdlib.h>
#include <fcntl.h>

void main( void )
{
   FILE *stream;
   int  fh, count = 0;
   char inbuf[128];

   /* Open a file handle. */
   if( (fh = _open( "_fdopen.c", _O_RDONLY )) == -1 )
      exit( 1 );

   /* Change handle access to stream access. */
   if( (stream = _fdopen( fh, "r" )) == NULL )
      exit( 1 );

   while( fgets( inbuf, 128, stream ) != NULL )
      count++;

   /* After _fdopen, close with fclose. */
   fclose( stream );
   printf( "Lines in file: %d\n", count );
}
// Output
Lines in file: 32

Requirements

OS Versions: Windows CE 2.0 and later.

Header: stdio.h, stdlib.h.

Link Library: coredll.dll.