### fopen -- Open Files

Format

>     #include <stdio.h>
>     FILE *fopen(const char *filename, const char *mode);

Language Level: ANSI, POSIX, XPG4
fopen opens the file specified by filename. mode is a character string specifying the type of access requested for the file. The mode variable contains one positional parameter followed by optional keyword parameters.

The possible values for the positional parameters are:

Mode | Description
r | Open a text file for reading. The file must exist.
w | Create a text file for writing. If the given file exists, its contents are destroyed.
a | Open a text file in append mode for writing at the end of the file.
r+ | Open a text file for both reading and writing. The file must exist.
w+ | Create a text file for both reading and writing. If the given file exists, its contents are cleared.
a+ | Open a text file in append mode for reading or updating at the end of the file. fopen creates the file if it does not exist.
rb | Open a binary file for reading. The file must exist.
wb | Create an empty binary file for writing. If the file exists, its contents are cleared.
ab | Open a binary file in append mode for writing at the end of the file. fopen creates the file if it does not exist.
r+b or rb+ | Open a binary file for both reading and writing. The file must exist.
w+b or wb+ | Create an empty binary file for both reading and writing. If the file exists, its contents will be cleared.
a+b or ab+ | Open a binary file in append mode for writing at the end of the file. fopen creates the file if it does not exist.

Note: Use the w, w+, wb, w+b, and wb+ parameters with care; data in existing files of the same name will be lost.

Text files contain printable characters and control characters organized into lines. Each line ends with a new-line character, except possibly the last line, depending on the compiler. The system may insert or convert control characters in an output text stream.

Note: Data output to a text stream may not compare as equal to the same data on input.

Binary files contain a series of characters. For binary files, the system does not translate control characters on input or output.

When you open a file with a, a+, ab, a+b or ab+ mode, all write operations take place at the end of the file. Although you can reposition the file pointer using fseek or rewind, the write functions move the file pointer back to the end of the file before they carry out any operation. This action prevents you from overwriting existing data.

When you specify the update mode (using + in the second or third position), you can both read from and write to the file. However, when switching between reading and writing, you must include an intervening positioning function such as fseek, fsetpos, rewind, or fflush. Output may immediately follow input if the end-of-file was detected.

The keyword parameters are:

blksize=value
  Specifies the maximum length, in bytes, of a physical block of records. For fixed-length records, the maximum size is 32760 bytes. For variable-length records, the maximum is 32756. The default buffer size is 4096 bytes.
lrecl=value
  Specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. For fixed-length records, the maximum length is 32760 bytes. For variable-length records, the maximum is 32756. If the value of LRECL is larger than the value of BLKSIZE, the LRECL value is ignored.
recfm=value
  value can be:

F | fixed-length, unblocked records
FB | fixed-length, blocked records
V | variable-length, unblocked records
VB | variable-length, blocked records

type=value
  value can be:
  memory This parameter identifies this file as a memory file that is accessible only from C programs.
  If you want to use a memory file, you must compile with the /Sv option.

For both OS/2 and Windows, IBM C and C++ Compilers does not support record I/O.

fopen generally fails if parameters are mismatched.

On OS/2 and Windows, the file attributes can be altered only if the open mode specified with the fopen function is one of the write modes (w, w+, wb, or wb+). The system deletes the existing file and creates a new file with the attributes specified in fopen.

Return Value
fopen returns a pointer to a file structure that can be used to access the open file. A NULL pointer return value indicates an error.

If the mode string passed to fopen is correct, fopen will not set errno to EBADMODE, regardless of the file type.

If the mode string passed to fopen is invalid, fopen will set errno to EBADMODE, regardless of the file type.

If the mode string passed to fopen is correct, but is invalid to that specific type of file, fopen will set errno to ENOTOPEN, EIOERROR or EIORECERR, regardless of the file type.

Example

creat -- Create New File
fclose -- Close Stream
fflush -- Write Buffer to File
fread -- Read Items
freopen -- Redirect Open Files
open -- Open File
sopen -- Open Shared File
fseek -- Reposition File Position
fsetpos -- Set File Position
fwrite -- Write Items
rewind -- Adjust Current File Position
<stdio.h>
/Sv compiler option