_fsopen()

open a file and associate a stream with it

Synopsis:

#include <stdio.h>
#include <share.h>

FILE *_fsopen( const char *filename,
               const char *mode,
               int share );

Description:

The _fsopen() function opens the file whose name is the string pointed to by filename, and associates a stream with it. The arguments mode and share control shared reading or writing. The argument mode points to a string beginning with one of the following sequences:

r

open file for reading

w

create file for writing, or truncate to zero length

a

append: open text file or create for writing at end-of-file

r+

open file for update (reading and/or writing); use default file translation

w+

create file for update, or truncate to zero length; use default file translation

a+

append; open file or create for update, writing at end-of-file; use default file translation

The letter b may be added to any of the above sequences in the second or third position to indicate that the file is (or must be) a binary file (an ANSI requirement for portability to systems that make a distinction between text and binary files). Under QNX, there is no difference between text files and binary files.

• Opening a file with read mode (r as the first character in the mode argument) fails if the file doesn't exist or it cannot be read.
• Opening a file with append mode (a as the first character in the mode argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of previous calls to fseek().
• When a file is opened with update mode (+ as the second or third character of the mode argument), both input and output may be performed on the associated stream.

When a stream is opened in update mode, both reading and writing may be performed. However, writing may not be followed by reading without an intervening call to the fflush() function or to a file positioning function (fseek(), fsetpos(), rewind()). Similarly, reading may not be followed by writing without an intervening call to a file positioning function, unless the read resulted in end-of-file.

The shared access for the file, share, is established by a combination of bits defined in the <share.h> header file. The following values may be set:

SH_COMPAT

Set compatibility mode.

SH_DENYRW

Prevent read or write access to the file.

SH_DENYWR

Prevent write access of the file.

SH_DENYRD

Prevent read access to the file.

SH_DENYNO

Permit both read and write access to the file.

fopen( filename, mode ); is the same as: _fsopen( filename, mode, SH_COMPAT );

Returns:

A pointer to the object controlling the stream. This pointer must be passed as a parameter to subsequent functions for performing operations on the file. If the open operation fails, _fsopen() returns NULL. When an error has occurred, errno indicates the type of error detected.

Examples:

#include <stdio.h>
#include <share.h>

void main()
  {
    FILE *fp;

    /*
      Open a file, and prevent others from writing to it.
    */
    fp = _fsopen( "report.dat", "w", SH_DENYWR );
    if( fp != NULL ) {
      /* rest of code goes here */
      fclose( fp );
    }
  }

Classification:

WATCOM

See also:

errno, fclose(), fcloseall(), fdopen(), fopen(), freopen()