NAME

fopen, freopen, fdopen – open a stream

SYNOPSIS

#include <stdio.h>

FILE *fopen( const char *filename , const char *type );

FILE *freopen( const char *filename , const char *type , FILE *stream );

FILE *fdopen( int fildes , const char *type );

DESCRIPTION

fopen() opens the file named by filename and associates a stream with it. fopen() returns a pointer to the FILE structure associated with the stream.

filename points to a character string that contains the name of the file to be opened.

type is a character string beginning with one of the following sequences:

freopen() substitutes the named file in place of the open stream . A flush is first attempted, and then the original stream is closed, regardless of whether the open ultimately succeeds. Failure to flush or close stream successfully is ignored. freopen() returns a pointer to the FILE structure associated with stream .

freopen() is typically used to attach the preopened streams associated with stdin, stdout, and stderr to other files. stderr is by default unbuffered, but the use of freopen() will cause it to become buffered or line-buffered.

fdopen() associates a stream with a file descriptor. File descriptors are obtained from open(), creat() which open files but do not return pointers to a FILE structure stream. The type of stream must agree with the mode of the open file. The file position indicator associated with stream is set to the position indicated by the file offset associated with fildes.

When a file is opened for update, both input and output may be done on the resulting stream. However, output may not be directly followed by input without an intervening fflush(), fseek(), or rewind(), and input may not be directly followed by output without an intervening fseek(), fsetpos(), or rewind(), or an input operation that encounters end-of-file.

When a file is opened for append (that is, when type is “a”, “ab”, “a+”, or “ab+”), it is impossible to overwrite information already in the file. fseek() may be used to reposition the file pointer to any position in the file, but when output is written to the file, the current file pointer is disregarded. All output is written at the end of the file and causes the file pointer to be repositioned at the end of the output. If two separate processes open the same file for append, each process may write freely to the file without fear of destroying output being written by the other. The output from the two processes will be intermixed in the file in the order in which it is written.

When opened, a stream is fully buffered if and only if it can be determined not to refer to an interactive device. The error and end-of-file indicators are cleared for the stream.

RETURN VALUES

The functions fopen() and freopen() return a null pointer if path cannot be accessed, or if type is invalid, or if the file cannot be opened.

The function fdopen() returns a null pointer if fildes is not an open file descriptor, or if type is invalid, or if the file cannot be opened.

The functions fopen() or fdopen() may fail and not set errno if there are no free stdio streams.

File descriptors used by fdopen() must be less than 255.

ERRORS

This function is a member of Unison’s STDIO implementation. The STDIO implementation rests on top of IOLIB and inherits IOLIB’s dependency on each specific server to report an appropriate error code for its usage.

For an exact list of error codes returned by a particular server, refer to that server’s documentation in the Unison Programmer’s Guide for each specific platform.

Servers may implement these errors codes in response to this function.

[EACCES]

Search permission is denied on a component of the path prefix, or the file exists and the permissions specified by mode are denied, or the file does not exist and write permission is denied for the parent directory of the file to be created.

[EISDIR]

The named file is a directory and mode requires write access.

[EMFILE]

{OPEN_MAX} file descriptors are currently open. Or, {FOPEN_MAX} or {STREAM_MAX} streams are currently open.

[ENAMETOOLONG]

The length of the filename argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

[ENFILE]

The maximum allowable number of files is currently open in the system.

[ENOENT]

A component of filename does not name an existing file or filename is an empty string.

[ENOSPC]

The directory or file system that would contain the new file cannot be expanded, the file does not exist, and the file was to be created.

[ENOTDIR]

A component of the path prefix is not a directory.

[ENXIO]

The named file is a character special or block special file, and the device associated with this special file does not exist.

[EROFS]

The named file resides on a read-only file system and mode requires write access.

[EINVAL]

The value of the mode argument is not valid.

[ENOMEM]

Insufficient storage space is available.

SEE ALSO

close(), creat(), open(), write(), fclose(), fseek(), setbuf()