fopen, fopen64, freopen, freopen64 or fdopen Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

fopen, fopen64, freopen, freopen64 or fdopen Subroutine

Purpose

Opens a stream.

Library

Standard C Library (libc.a)

Syntax

#include <stdio.h>
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;

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.

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.

Parameters

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). Note: The operating system does not distinguish between text and binary files. The b value in the Type parameter value is ignored.
Stream	Specifies the input stream.
FileDescriptor	Specifies a valid open file descriptor.

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.

Error Codes

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

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.
ENFILE	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:

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:

EOVERFLOW

The named file is a size larger than 2 Gigabytes.

The fdopen subroutine is unsuccessful if the following is true:

EBADF

The value of the File Descriptor parameter is not valid.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

POSIX

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.

Related Information

The fclose or fflush subroutine, fseek, fseeko, fseeko64, rewind, ftell, ftello, ftello64, fgetpos, fgetpos64 or fsetpos subroutine, open, open64, openx, or creat subroutine, setbuf, setvbuf, setbuffer, or setlinebuf subroutine.

The Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.