_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 the fseek function.
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.

Note that

fopen( filename, mode );

is the same as:

_fsopen( filename, mode, SH_COMPAT );

Returns:

The _fsopen() function 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 contains a value that indicates the type of error that has been 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

Systems:

All (except DOS/PM)