fopen() — Open a file
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
ISO C
POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 |
both |
Format
#include <stdio.h>
FILE *fopen(const char *__restrict__filename, const char *__restrict__mode);
General description
The fopen() function opens the file specified by filename and associates a stream with it. The mode variable 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 positional parameters are described in Table 1 and Table 3.
The positional parameters must be passed as lowercase characters.
The keyword parameters can be passed in mixed case. They must be separated by commas. Only one instance of a keyword can be specified.
The file name passed to fopen() often determines the type of file that is opened. A set of file-naming rules exist, which allow you to create an application that references both MVS™ and HFS files specifically. For details on how fopen() determines the type of file from the filename and mode strings, see the topics about opening files in z/OS XL C/C++ Programming Guide.
Large file support for z/OS® UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.
Named pipes in multithreaded environment: Do not use fopen() to open named pipes in multithreaded environment. If used, a deadlock will occur. See z/OS XL C/C++ Programming Guide for a detailed explanation.
File mode
t
, for example, rt
, rt+
,
r+t
, wt
, wt+
, w+t
,
at
, at+
or a+t
, the fopen() request will fail
with a message indicating a non-valid mode was specified.File mode | General description |
---|---|
r | Open a text file for reading. (The file must exist.) |
w | Open a text file for writing. If the w mode is specified for a ddname that
has DISP=MOD, the behavior is the same as if a had been specified. Otherwise, if
the file already exists, its contents are destroyed. |
a | Open a text file in append mode for writing at the end of the file. fopen() creates the file if it does not exist. |
r+ | Open a text file for both reading and writing. (The file must exist.) |
w+ | Open a text file for both reading and writing. If the w+ mode is specified
for a ddname that has DISP=MOD, the behavior is the same as if a+ had been
specified. Otherwise, if the file already exists, its contents are destroyed. |
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 | Open an empty binary file for writing. If the wb mode is specified for a
ddname that has DISP=MOD, the behavior is the same as if ab had been specified.
Otherwise, if the file already exists, its contents are destroyed. |
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. |
rt | Open a text file for reading. (The file must exist.) |
wt | Open a text file for writing. If the file already exists, its contents are destroyed. |
at | Open a text 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+ | Open an empty binary file for both reading and writing. If the w+b (or
wb+ ) mode is specified for a ddname that has DISP=MOD, the behavior is the same as
if ab+ had been specified. Otherwise, if the file already exists, its contents are
destroyed. |
a+b or ab+ | Open a binary file in append mode for reading or updating at the end of the file. fopen() creates the file if it does not exist. |
r+t or rt+ | Open a text file for both reading and writing. (The file must exist.) |
w+t or wt+ | Open a text file for both reading and writing. If the file already exists, its contents are destroyed. |
a+t or at+ | 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. |
Extended file mode | General description |
---|---|
e | Open the z/OS
UNIX file system file with the O_CLOEXEC flag. This
flag is ignored for fdopen() . This flag is ignored if the file not a z/OS
UNIX system file. |
w
, w+
, wb
, w+b
,
and wb+
parameters with care; data in existing files
of the same name will be lost.\r
written to an MVS DASD text file will be treated as if \n
(newline)
was written. Binary files contain a series of characters. For binary files, the system does not translate control characters on input or output. Under z/OS XL C/C++, some types of files are always treated as binary files, even when opened in text mode.
In such cases, a control character is written to the file as binary data. On input, the control character will be read back as it was written. See the topic about the byte stream model in z/OS XL C/C++ Programming Guide for more information.
z/OS XL C/C++ has Record I/O and Blocked
I/O file extensions. These files are binary in nature—no data
interpretation—and require additional qualifiers: type=record
and
type=blocked
. See the topics about writing to record I/O files and writing to
blocked I/O files in z/OS XL C/C++ Programming Guide for more information.
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(), fsetpos(), or rewind(), the write functions move the file
pointer back to the end of the file before they carry out any output
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 EOF was detected.
Parameter | Description |
---|---|
abend= value |
Controls whether the runtime library should attempt to recover from an abend issued during OS I/O operations against the stream being opened. The value can be abend or recover. See z/OS XL C/C++ Programming Guide for more information. |
acc= value |
Indicator of the direction of the access of the VSAM data set. The value can be fwd or bwd. |
acc=bwd |
Sets the file position indicator to the last record. The access direction may be changed by a call to flocate(). |
asis |
Indicates that the file name is not to be converted to uppercase but used as is. This option is the default under POSIX. It is also the default for HFS file names (see z/OS XL C/C++ Programming Guide for more information). |
blksize= value |
Specifies the maximum length, in bytes, of a physical block of records. To check whether your
blksize parameter is valid and is within its limits, see the appropriate topic in
z/OS XL C/C++ Programming Guide for the
type of file you are opening. |
byteseek |
Indicator to allow byte seeks for a binary file. For more information, see the ftell() and fseek() functions. |
lrecl= value |
Specifies the length, in bytes, for fixed-length records and the maximum length for
variable-length records. To check whether your lrecl parameter is valid and is
within its limits, see the appropriate topic in z/OS XL C/C++ Programming Guide for the type of file you are opening. |
noseek |
Indicates that the stream may not use any of the reposition functions. This may improve performance. |
password= xxxxxxx |
Specifies the password for a VSAM data set. |
recfm=A |
ASA print-control characters |
recfm=F |
Fixed-length, unblocked |
recfm=FA |
Fixed-length, ASA print-control characters |
recfm=FB |
Fixed-length, blocked |
recfm=FM |
Fixed-length, machine print-control codes |
recfm=FS |
Fixed-length, unblocked, standard |
recfm=FBA |
Fixed-length, blocked, ASA print-control characters |
recfm=FBM |
Fixed-length, blocked, machine print-control codes |
recfm=FBS |
Fixed-length, unblocked, standard ASA print-control characters |
recfm=FSA |
Fixed-length, unblocked, standard, ASA print-control characters |
recfm=FSM |
Fixed-length, unblocked, standard, machine print-control codes |
recfm=FBSA |
Fixed-length, blocked, standard, ASA print-control characters |
recfm=FBSM |
Fixed-length, blocked, standard, machine print-control codes |
recfm=U |
Undefined-length |
recfm=UA |
Undefined-length, ASA print control characters |
recfm=UM |
Undefined-length, machine print control codes |
recfm=V |
Variable, unblocked |
recfm=VA |
Variable, ASA print-control characters |
recfm=VB |
Variable, blocked |
recfm=VM |
Variable, machine print-control codes |
recfm=VS |
Variable, unblocked, spanned |
recfm=VBA |
Variable, blocked, ASA print-control characters |
recfm=VBM |
Variable, blocked, machine print-control codes |
recfm=VBS |
Variable, blocked, spanned |
recfm=VSA |
Variable, unblocked, spanned, ASA print-control characters |
recfm=VSM |
Variable, unblocked, spanned, machine print-control codes |
recfm=VBSA |
Variable, blocked, spanned, ASA print-control characters |
recfm=VBSM |
Variable, blocked, spanned, machine print-control codes |
recfm=* |
Existing file attributes are used if file is opened in write
mode. Note: Using
recfm=* is only valid for existing
DASD data sets. It is ignored in all other cases. |
recfm=+ |
Identical to recfm=* with the following exceptions:
|
samethread |
This parameter specifies that I/O operations against the stream are restricted to the thread in which the stream was opened. The library will not lock the stream in a multithread environment. Use of this keyword can improve performance when the stream does not need to be accessed on different threads. |
space | Space attributes for MVS data sets. Within the
parameter, you cannot have any imbedded blanks. Where:
See the topic about fopen() and freopen() parameters in z/OS XL C/C++ Programming Guide for more information about the syntax of this parameter. |
type=blocked |
This parameter specifies that the file is to be opened for sequential blocked I/O. The file must be opened as a binary file; otherwise, fopen() fails. Read and write operations are done with the fread() and fwrite() functions. |
type=memory |
This parameter identifies this file as a memory file that is accessible only from C programs. |
type=memory(hiperspace) |
If you are using MVS/ESA, you can specify the HIPERSPACE suboption to open a hiperspace memory file. Restriction: For AMODE 64 applications,
type=memory(hiperspace) is
treated as type=memory . |
type=record |
This parameter specifies that the file is to be opened for sequential record I/O. The file must be opened as a binary file; otherwise, fopen() fails. Read and write operations are done with the fread() and fwrite() functions. This is the default fopen() mode for accessing VSAM clusters. |
Returned value
If successful, fopen() returns a pointer to the object controlling the associated stream.
If unsuccessful, fopen() returns a NULL pointer.
fopen() generally fails if parameters are mismatched.
- Error Code
- Description
- EOVERFLOW
- The named file is a regular file and the size of the file cannot
be represented correctly in an object of type
off_t
.
Example
/* CELEBF26
This example attempts to open two files for reading, myfile.dat
and myfile2.dat.
*/
#include <stdio.h>
int main(void)
{
FILE *stream;
/* The following call opens a text file for reading */
if ((stream = fopen("myfile.dat", "r")) == NULL)
printf("Could not open data file for reading\n");
/* The following call opens:
the file myfile2.dat,
a binary file for reading and writing,
whose record length is 80 bytes,
and maximum length of a physical block is 240 bytes,
fixed-length, blocked record format
for sequential record I/O.
*/
if ( (stream = fopen("myfile2.dat", "rb+, lrecl=80,\
blksize=240, recfm=fb, type=record")) == NULL )
printf("Could not open data file for read update\n");
}
Related information
- See the topics about dealing with I/O in z/OS XL C/C++ Programming Guide.
- stdio.h — Standard input and output
- fclose() — Close file
- fldata() — Retrieve file information
- freopen() — Redirect an open file
- open() — Open a file