fopen, fopen64 - open stream

Syntax

#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);
FILE *fopen64(const char *filename, const char *mode); 

Description

Description fopen() opens the file whose pathname is the string pointed to by filename, and associates

a stream with it.

filename can be:

• a valid POSIX file name

• a valid BS2000 file name:

  • link= linkname linkname designates a BS2000 link name.

  • (SYSDTA), (SYSOUT), (SYSLST), the corresponding system file

  • (SYSTERM), terminal I/O

  • (INCORE), temporary binary file that is created in virtual memory only.

mode is a string that specifies the desired access mode. It can have one of the following values:

r	Open text file for reading. The file must already exist.
w	Open text file for writing. If the file exists, the old contents are deleted. If the file does not exist, it is created.
wx	Open text file for writing. The file must not exist.
a	Open text file for appending to the end of the file. If the file exists, it is positioned to end of file, i.e. the old contents are preserved and the new data is appended to the end of the file. If the file does not exist, it is created.
rb	Open binary file for reading. The file must already exist.
wb	Open binary file for writing. If the file exists, the old contents are deleted. If the file does not exist, it is created.
wbx	Open binary file for writing. The file must not exist.
ab	Open binary file for appending to the end of the file. If the file exists, it is positioned to end of file, i.e. the old contents are preserved and the new data is appended to the end of the file. If the file does not exist, it is created.
r+w, r+	Open text file for reading and writing. The file must already exist. The old contents are preserved.
w+r, w+	Open text file for writing and reading. If the file exists, the old contents are deleted. If the file does not exist, it is created.
a+r, a+	Open text file for appending to the end of the file and for reading. If the file exists, it is positioned to end of file, i.e. the old contents are preserved, and new data is appended to the end of the file. For KR functionality (only available with C/C++ versions lower than V3), existing files are positioned to end of file when opened; for ANSI functionality, to the beginning of the file. If the file does not exist, it is created.
r+b, rb+	Open binary file for reading and writing. The file must already exist. The old contents are preserved.
w+b, wb+	Open binary file for writing and reading. If the file exists, the old contents are deleted. If the file does not exist, it is created.
w+bx, wb+x	Open binary file for writing and reading. The file must not exist.
a+b, ab+	Open binary file for appending to the end of the file and for reading. If the file exists, it is positioned to end of file, i.e. the old contents are preserved and the new data is appended to the end of the file. For KR functionality (only available with C/C++ versions lower than V3), existing files are positioned to end of file when opened; for ANSI functionality, to the beginning of the file. If the file does not exist, it is created.

The character b in the above access modes is ignored. Opening a file with read mode (i.e. with r as the first character in the mode argument) fails if the file does not exist or cannot be read.

Opening a file with append mode (i.e. with a as the first character in the mode argument) causes all subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening calls to fseek().

When a file is opened with update mode (i.e. with + as the second character in the mode argument), both input and output may be performed on the associated stream. However, output must not be directly followed by input without an intervening call to fflush() or to a file positioning function (fseek(), fsetpos() or rewind()), and input must not be directly followed by output without an intervening call to a file positioning function, unless the input operation encounters end-of-file.

When opened, a stream is fully buffered if and only if it can be determined not to refer to an interactive device such as the terminal. The error and end-of-file indicators for the stream are cleared.

For automatic conversion, the b for binary must not be specified in mode. Furthermore, the environment variable IO_CONVERSION must not be present or must have the value YES.

BS2000
The following must be noted when executing BS2000 files: In mode optionally further functions may be controlled by additional specifications:

Additional specification	Function
tabexp=yes/no	Handling of the tab character (\t)
lbp=yes/no	Handling of the Last Byte Pointers (LBP)
split=yes/no	Processing text files with specification of a maximum record length

Tab character (\t)

Additionally to the access mode an optional entry to control handling of the tab character (\t) may be specified in mode. This is relevant only for text files with the SAM and ISAM access methods.

"...,tabexp=yes"

The tab character is expanded into the appropriate number of blanks. This is the default setting for KR functionality (only available with C/C++ versions lower than V3).

"...,tabexp=no"

The tab character is not expanded. This is the default setting for ANSI functionality.

Last Byte Pointer (LBP)

In the mode parameter an optional entry controlling how the Last Byte Pointer (LBP) is to be handled can be specified in addition to the access mode. This is relevant only for binary files with PAM access mode. If lbp=yes is specified, a check is made to see whether LBP support is possible. If this is not the case, the fopen(), fopen64() function will fail and errno is set to ENOSYS. The switch has further effects only when the file is closed.

When an existing file is opened and read, the LBP is always taken into account independently of the lbp switch:

• • • If the file's LBP is not equal to 0, it is evaluated. Any marker which is present is ignored.

    • When LBP = 0, a marker is searched for, and the file length is determined from this. If no marker is found, the end of the last complete block is regarded as the end of file.

"...,lbp=yes"

When a file which has been modified or newly created is closed, no marker is written (even if one was present), and a valid LBP is set. In this way files with a marker can be converted to LBP without a marker. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

"...,lbp=no"

When a file which has been newly created is closed, the LBP is set to zero (=invalid). A marker is written. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

When a file which has been modified is closed, the LBP is set to zero (=invalid). A marker is written only if a marker existed before. If no marker existed, none is written and the file ends with the complete last block. If the file had a valid LBP when it was opened, no marker is written as in this case it is assumed that no marker exists. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

If the lbp switch is not specified, the behavior depends on the environment variable LAST_BYTE_POINTER (see also section “Environment variables”):

LAST_BYTE_POINTER=YES

The function behaves as if lbp=yes were specified.

LAST_BYTE_POINTER=NO

The function behaves as if lbp=no were specified.

Split/Nosplit switch

This switch controls the processing of text files with SAM access mode and variable record length when a maximum record length is also specified.

"...,split=yes"

• • • The following applies when reading: If a record has the maximum record length, it is assumed that the following record is the continuation of this record and the records are concatenated.

    • The following applies when writing: A record which is longer than the maximum record length will be split into multiple records. If a record has precisely the maximum record length, a record of the length zero is written after it.

"...,split=no"

When reading, records of maximum length are not concatenated with the following record. When reading with one of the functions fwrite(), fprintf(), printf(), vfprintf(), vprintf(), fwprintf(), wprintf(), vfwprintf(), vwprintf(), fputs(), fputws() or puts(), records which are longer than the maximum record length are truncated.

If the switch is not specified, "...,split=yes" applies.

There is no difference in functionality between fopen and fopen64 except that fopen64 returns a pointer that can point past the 2GB limit. fopen64() sets the O_LARGEFILE bit in the File status flag.

Return val.

File pointer

Null pointer

if successful.

if filename cannot be accessed, mode is invalid, or the file cannot be opened. errno is set to indicate the error.

Errors

fopen() and fopen64() will fail if: 

 

EACCES

Search permission is denied on a component of the path prefix,
or the file exists and the permissions specified by mode are denied,
or the file does not exist and write permission is denied for the parent
directory of the file to be created.

 

EINTR

A signal was caught during the fopen() system call.

 

EINVAL

The value of the mode argument is invalid.

 

EISDIR

The named file is a directory and mode requires write access.

 

EMFILE

{OPEN_MAX} file descriptors are already open for the calling process.

{FOPEN_MAX} streams are already open for the calling process.

{STREAM_MAX} streams are already open for the calling process.

 

ENAMETOOLONG

 

The length of filename exceeds {PATH_MAX} or a pathname component is
longer than {NAME_MAX}.

 

ENFILE

The maximum allowable number of files is currently open in the system.

 

ENOENT

The named file does not exist or filename points to an empty string.

 

ENOMEM

There is not enough memory available.

 

ENOSPC

The file does not exist, and the directory in which the new file is to be created cannot be expanded.

 

ENOTDIR

A component of the path is not a directory.

 

ENXIO

The named file is a character special or block special file, and the device associated with this special file does not exist.

 

EROFS

The named file resides on a read-only file system and mode requires write
access.

ETXTBSY

The file is a pure procedure file (shared text file) that is currently executing and write protection is required for mode.

EOVERFLOW

The file named is a regular file and the size of the file cannot be represented correctly in an object of type off_t.

Notes

{STREAM_MAX} is the number of streams that one process can have open at one time. If

defined, it has the same value as {FOPEN_MAX}, i.e. 2048.

The program environment determines whether fopen() is executed for a BS2000 or POSIX file.

BS2000
The BS2000 file name or link name may be entered in lowercase and uppercase letters. It is automatically converted to uppercase letters. Specifying a b as the second character in the mode parameter causes the file to be opened as a binary file. This is relevant only for SAM files, since only SAM files can be processed in both binary and text modes.

System files and ISAM files are always processed as text files. Specifying binary mode for these files leads to an error on opening.

(INCORE) and PAM files are always processed as binary files. For compatibility reasons, files may be opened as binary files without explicitly specifying the binary mode.

When a new file is created it is given the following attributes by default:

	Binary file	Text file
Access method	SAM	SAM (KR functionality, only available with C/C++ versions lower than V3) ISAM (ANSI functionality)
Record format	F	V

The following file attributes can be changed by using a link name with the SET-FILE-LINK command: access method, record length, record format, block length and block format.

Whenever the old contents of an existing file are deleted (i.e. when a file is opened for rewriting or for rewriting and reading), the catalog attributes of that file are preserved.

When a file is opened for an update, reading and writing can be performed via the same file pointer. All the same, an output should not be immediately followed by an input without a preceding positioning operation (with fseek(), fsetpos() or rewind()) or an fflush call. This also applies to an output that follows an input.

Set the file position indicator in append mode

(INCORE) files can only be opened for writing (w), for writing and reading (w+r) or for reading (r). Data must first be written. The following options are available to read in the written data: if the file was opened only for writing, it can be opened for reading with the function freopen(). If it was opened for writing and reading, the file position indicator can be set to the beginning of the file with rewind().

A file may be opened for different access modes simultaneously, provided these modes are compatible with one another within the BS2000 data management system.

When a program begins, the following three file pointers are assigned to it automatically:

stdin	file pointer for standard input (terminal)
stdout	file pointer for standard output (terminal)
stderr	file pointer for standard error output (terminal)

A maximum of _NFILE files may be open simultaneously. _NFILE is defined as 2048 in stdio.h.

For opening files with record I/O, the mode parameter has two additional options. These follow the access mode in the string (see above), each separated by a comma:

"...,type=record [,forg={seq/key}]"

type=record	The file is opened for record I/O. If this option is omitted, the file is opened for stream I/O.
forg=seq	The file is organized sequentially. Sequential files may be SAM or PAM files.
forg=key	The file is organized index-sequentially. Index-sequential files are ISAM files.

If forg() is omitted, the file organization depends on the FCB type (FCBTYP) of the file:The FCB type is defined by the catalog entry of an existing file or by a SET-FILE-LINK command. Sequential organization is assumed for SAM and PAM files, index-sequential organization for ISAM files.

If forg() is omitted and the FCB type is not defined (file does not exist, no SET-FILE-LINK command), sequential file organization is assumed, and a SAM file is created.

The following restrictions apply to record I/O. If these restrictions are ignored, the file is not opened, and an error value is returned:The file must be opened in binary mode (b specified in the access mode).

type=record is permitted for SAM, PAM and ISAM files.

forg=seq is permitted for SAM and PAM files; forg=key for ISAM files.

The append mode a is invalid for ISAM files. The position is determined by the key in the record. 

See also

creat(), fclose(), fdopen(), ferror(), freopen(), open(), stdio.h.