fopen, fopen64, freopen, freopen64, fopen_s or fdopen Subroutine

Purpose

Opens a stream and handles runtime constraint violations.

Library

Standard C Library (libc.a)

Syntax

#include <stdio.h>
#define STDC_WANT_LIB_EXT1 1
FILE  *fopen ( Path,  Type)
const char *Path, *Type;

FILE  *fopen64 ( Path,  Type)
char  *Path, *Type;

FILE  *freopen (Path, Type,  Stream)
const char *Path, *Type;
FILE  *Stream;

FILE  *freopen64 (Path, Type,  Stream)
char  *Path, *Type;
FILE  *Stream;

FILE  *fdopen ( FileDescriptor, Type)
int   FileDescriptor;
const char *Type;

errno_t fopen_s ( streamptr, filename, mode)
FILE * *streamptr ;
const char * filename ;
const char * mode ;

Description

The fopen and fopen64 subroutines open the file named by the Path parameter and associate a stream with it and return a pointer to the FILE structure of this stream.

When you open a file for update, you can perform both input and output operations on the resulting stream. However, an output operation cannot be directly followed by an input operation without an intervening fflush subroutine call or a file positioning operation (fseek, fseeko, fseeko64, fsetpos, fsetpos64 or rewind subroutine). Also, an input operation cannot be directly followed by an output operation without an intervening flush or file positioning operation, unless the input operation encounters the end of the file.

When you open a file for appending (that is, when the Type parameter is set to a), it is impossible to overwrite information already in the file.

If two separate processes open the same file for append, each process can write freely to the file without destroying the output being written by the other. The output from the two processes is intermixed in the order in which it is written to the file.

Note: If the data is buffered, it is not actually written until it is flushed.

The freopen and freopen64 subroutines first attempt to flush the stream and close any file descriptor associated with the Stream parameter. Failure to flush the stream or close the file descriptor is ignored.

The freopen and freopen64 subroutines substitute the named file in place of the open stream. The original stream is closed regardless of whether the subsequent open succeeds. The freopen and freopen64 subroutines returns a pointer to the FILE structure associated with the Stream parameter. The freopen and freopen64 subroutines is typically used to attach the pre-opened streams associated with standard input (stdin), standard output (stdout), and standard error (stderr) streams to other files.

The fdopen subroutine associates a stream with a file descriptor obtained from an openx subroutine, dup subroutine, creat subroutine, or pipe subroutine. These subroutines open files but do not return pointers to FILE structures. Many of the standard I/O package subroutines require pointers to FILE structures.

The Type parameter for the fdopen subroutine specifies the mode of the stream, such as r to open a file for reading, or a to open a file for appending (writing at the end of the file). The mode value of the Type parameter specified with the fdopen subroutine must agree with the mode of the file specified when the file was originally opened or created.

Note: Using the fdopen subroutine with a file descriptor obtained from a call to the shm_open subroutine must be avoided and might result in an error on the next fread, fwrite or fflush call.

The largest value that can be represented correctly in an object of type off_t will be established as the offset maximum in the open file description.

The fopen_s subroutine opens the file by using the name of the string pointed to by the filename parameter, and associates a stream with the file.

Files are opened for writing with exclusive (also known as non shared) access. If the file is created, and the first character of the mode parameter is not u, and if the underlying system supports exclusive mode concept, the file has a permission that prevents other users on the system from accessing the file.

If the file is created and the first character of the mode parameter is u, the file retains the system default file access permissions until the file is closed.

If the file is opened successfully, the pointer to the FILE structure that is pointed to by the streamptr parameter is set to the pointer that points to the object controlling the opened file. Otherwise, the pointer to the FILE structure pointed to by the streamptr parameter is set to a null pointer, and the file retains the system default file access permissions until the file is closed.

Runtime Constraints

  1. For the fopen_s subroutine, the streamptr, filename or mode parameters must not be a null pointer.
  2. If there is a runtime constraint violation, the fopen_s subroutine does not attempt to open a file. If the streamptr parameter is not a null pointer, the fopen_s subroutine sets the streamptr parameter to the null pointer.

Parameters

Item Description
Path Points to a character string that contains the name of the file to be opened.
Type Points to a character string that has one of the following values:
r
Opens a text file for reading.
w
Creates a new text file for writing, or opens and truncates a file to 0 length.
a
Appends (opens a text file for writing at the end of the file, or creates a file for writing).
rb
Opens a binary file for reading.
wb
Creates a binary file for writing, or opens and truncates a file to 0.
ab
Appends (opens a binary file for writing at the end of the file, or creates a file for writing).
r+
Opens a file for update (reading and writing).
w+
Truncates or creates a file for update.
a+
Appends (opens a text file for writing at end of file, or creates a file for writing).
r+b , rb+
Opens a binary file for update (reading and writing).
w+b , wb+
Creates a binary file for update, or opens and truncates a file to 0 length.
a+b , ab+
Appends (opens a binary file for update, writing at the end of the file, or creates a file for writing).
wx
Creates a text file for writing.
wbx
Creates a binary file for writing.
w+x
Creates a text file for updating.
w+bx or wb+x
Creates a binary file for updating.
Note:
  • The operating system does not distinguish between text and binary files.
  • The b value in the Type parameter is ignored.
  • Opening a file with exclusive mode (x as the last character in the mode argument) fails, if the file already exists or cannot be created. Otherwise, the file is created with exclusive (also known as non shared) access if the underlying system supports exclusive access.
  • The fdopen subroutine has no impact on exclusive mode.
Stream Specifies the input stream.
FileDescriptor Specifies a valid open file descriptor.
streamptr Specifies the stream that is associated with the file name, and the value cannot be null.
filename Specifies the file name to be opened, and the value cannot be null.
mode The value cannot be null. The mode parameter is the same as the Type parameter described for fopen subroutine, with the addition that the modes starting with the character w or a can be preceded by the character u as shown below:
uw
Truncates to 0 or creates a text file for writing and has default permissions.
uwx
Creates a text file for writing and has default permissions.
ua
Opens or creates a text file for writing at the end of the file and has default permissions.
uwb
Truncates to 0 or creates a binary file for writing and has default permissions.
uwbx
Creates a binary file for writing and has default permissions.
uab
Opens or creates a binary file for writing at the end of the file and has default permissions.
uw+
Truncates to 0 or creates a text file for update and has default permissions.
uw+x
Creates a text file for update and has default permissions.
ua+ append
Opens or creates a text file for update and writing at the end-of-file and has default permissions.
uw+b or uwb+
Truncates to 0 or creates a binary file for update and has default permissions.
uw+bx or uwb+x
Creates a binary file for update and has default permissions.
ua+b or uab+ append
Opens or creates a binary file for update and writing at the end-of-file and has default permissions.
Note: If the mode parameter is not preceded with u, the file permissions are user only.

Return Values

If the fdopen, fopen, fopen64, freopen or freopen64 subroutine is unsuccessful, a null pointer is returned and the errno global variable is set to indicate the error.

The fopen_s subroutine returns a zero if it opens the file. If the file is not opened or if there is a runtime constraint violation, the fopen_s subroutine returns a nonzero value.

Error Codes

The fopen, fopen64, freopen and freopen64 subroutines are unsuccessful if the following is true:

Item Description
EACCES Search permission is denied on a component of the path prefix, the file exists and the permissions specified by the mode are denied, or the file does not exist and write permission is denied for the parent directory of the file to be created.
ELOOP Too many symbolic links were encountered in resolving path.
EINTR A signal was received during the process.
EISDIR The named file is a directory and the process does not have write access to it.
ENAMETOOLONG The length of the filename exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
EMFILE The maximum number of files allowed are currently open.
ENOENT The named file does not exist or the File Descriptor parameter points to an empty string.
ENOSPC The file is not yet created and the directory or file system to contain the new file cannot be expanded.
ENOTDIR A component of the path prefix is not a directory.
ENXIO The named file is a character- or block-special file, and the device associated with this special file does not exist.
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.
EROFS The named file resides on a read-only file system and does not have write access.
ETXTBSY The file is a pure-procedure (shared-text) file that is being executed and the process does not have write access.

The fdopen, fopen, fopen64, freopen and freopen64 subroutines are unsuccessful if the following is true:

Item Description
EINVAL The value of the Type argument is not valid.
EINVAL The value of the mode argument is not valid.
EMFILE FOPEN_MAX streams are currently open in the calling process.
EMFILE STREAM_MAX streams are currently open in the calling process.
ENAMETOOLONG Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.
ENOMEM Insufficient storage space is available.

The freopen and fopen subroutines are unsuccessful if the following is true:

Item Description
EOVERFLOW The named file is a size larger than 2 Gigabytes.

The fdopen subroutine is unsuccessful if the following is true:

Item Description
EBADF The value of the File Descriptor parameter is not valid.

POSIX

Item Description
w Truncates to 0 length or creates text file for writing.
w+ Truncates to 0 length or creates text file for update.
a Opens or creates text file for writing at end of file.
a+ Opens or creates text file for update, writing at end of file.

SAA

At least eight streams, including three standard text streams, can open simultaneously. Both binary and text modes are supported.