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

Restriction: When running with POSIX(OFF) and specifying a mode parameter that includes 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.

Positional parameter points to a string that begins with one of the following sequences. Start of change

To support extended file modes, additional characters can be included either as a last character or as a character between the characters in any of the two-character strings. End of change

Table 1. Values for positional parameter under file mode
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.

Table 2. Values for positional parameter under extended file mode
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.

Attention: 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 newline character. The system may insert or convert control characters in an output text stream. For example, \r written to an MVS DASD text file will be treated as if \n (newline) was written.

Note: When compared, data output to a text stream may not be equal to data input from the same text stream.

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.

Table 3. Keyword Parameters for File Mode
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: If there is no record format for the existing DASD data set, defaults are assigned as if the data set did not exist. When append mode is used, the fopen() fails. See z/OS XL C/C++ Programming Guide for more information about fopen() default attributes.
`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: u unit type of space requested p primary amount of space requested s secondary amount of space requested d number of directory space requested 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.

Special behavior for large files for HFS: The following is a possible value of errno:

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

/* 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