mirror of https://github.com/mkerrisk/man-pages
237 lines
7.3 KiB
Plaintext
237 lines
7.3 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "FOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" fopen
|
|
.SH NAME
|
|
fopen \- open a stream
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdio.h>
|
|
.br
|
|
.sp
|
|
FILE *fopen(const char *restrict\fP \fIfilename\fP\fB, const char
|
|
*restrict\fP \fImode\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIfopen\fP() function shall open the file whose pathname is the
|
|
string pointed to by \fIfilename\fP, and associates a
|
|
stream with it.
|
|
.LP
|
|
The \fImode\fP argument points to a string. If the string is one of
|
|
the following, the file shall be opened in the indicated
|
|
mode. Otherwise, the behavior is undefined.
|
|
.TP 7
|
|
\fIr\fP\ or\ \fIrb\fP
|
|
Open file for reading.
|
|
.TP 7
|
|
\fIw\fP\ or\ \fIwb\fP
|
|
Truncate to zero length or create file for writing.
|
|
.TP 7
|
|
\fIa\fP\ or\ \fIab\fP
|
|
Append; open or create file for writing at end-of-file.
|
|
.TP 7
|
|
\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP
|
|
Open file for update (reading and writing).
|
|
.TP 7
|
|
\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP
|
|
Truncate to zero length or create file for update.
|
|
.TP 7
|
|
\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP
|
|
Append; open or create file for update, writing at end-of-file.
|
|
.sp
|
|
.LP
|
|
The
|
|
character \fB'b'\fP shall have no effect, but is allowed for ISO\ C
|
|
standard conformance. Opening a file with read mode (\fIr\fP as the
|
|
first character in the \fImode\fP argument) shall
|
|
fail if the file does not exist or cannot be read.
|
|
.LP
|
|
Opening a file with append mode (\fIa\fP as the first character in
|
|
the \fImode\fP argument) shall cause all subsequent writes
|
|
to the file to be forced to the then current end-of-file, regardless
|
|
of intervening calls to \fIfseek\fP().
|
|
.LP
|
|
When a file is opened with update mode ( \fB'+'\fP as the second or
|
|
third character in the \fImode\fP argument), both input
|
|
and output may be performed on the associated stream. However, the
|
|
application shall ensure that output is not directly followed by
|
|
input without an intervening call to \fIfflush\fP() or to a file positioning
|
|
function ( \fIfseek\fP(), \fIfsetpos\fP(), or \fIrewind\fP()), and
|
|
input is not directly followed by output without an intervening call
|
|
to a file
|
|
positioning function, unless the input operation encounters end-of-file.
|
|
.LP
|
|
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 for the stream shall be cleared.
|
|
.LP
|
|
If
|
|
\fImode\fP is \fIw\fP, \fIwb\fP, \fIa\fP, \fIab\fP, \fIw\fP+, \fIwb\fP+,
|
|
\fIw\fP+\fIb\fP, \fIa\fP+, \fIab\fP+, or
|
|
\fIa\fP+\fIb\fP, and the file did not previously exist, upon successful
|
|
completion, the \fIfopen\fP() function shall mark for
|
|
update the \fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP fields
|
|
of the file and the \fIst_ctime\fP and \fIst_mtime\fP
|
|
fields of the parent directory.
|
|
.LP
|
|
If \fImode\fP is \fIw\fP, \fIwb\fP, \fIw\fP+, \fIwb\fP+, or \fIw\fP+\fIb\fP,
|
|
and the file did previously exist, upon
|
|
successful completion, \fIfopen\fP() shall mark for update the \fIst_ctime\fP
|
|
and \fIst_mtime\fP fields of the file. The
|
|
\fIfopen\fP() function shall allocate a file descriptor as \fIopen\fP()
|
|
does.
|
|
.LP
|
|
After a successful call to the \fIfopen\fP() function, the orientation
|
|
of the stream shall be cleared, \ the encoding
|
|
rule shall be cleared, and the associated \fBmbstate_t\fP object
|
|
shall be set to describe an initial conversion state.
|
|
.LP
|
|
The
|
|
largest value that can be represented correctly in an object of type
|
|
\fBoff_t\fP shall be established as the offset maximum in the
|
|
open file description.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIfopen\fP() shall return a pointer to
|
|
the object controlling the stream. Otherwise, a null
|
|
pointer shall be returned, \ and \fIerrno\fP shall be set to indicate
|
|
the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIfopen\fP() function shall fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
Search permission is denied on a component of the path prefix, or
|
|
the file exists and the permissions specified by \fImode\fP are
|
|
denied, or the file does not exist and write permission is denied
|
|
for the parent directory of the file to be created.
|
|
.TP 7
|
|
.B EINTR
|
|
A
|
|
signal was caught during \fIfopen\fP().
|
|
.TP 7
|
|
.B EISDIR
|
|
The named file is a directory and \fImode\fP requires write access.
|
|
.TP 7
|
|
.B ELOOP
|
|
A
|
|
loop exists in symbolic links encountered during resolution of the
|
|
\fIpath\fP argument.
|
|
.TP 7
|
|
.B EMFILE
|
|
{OPEN_MAX} file descriptors are currently open in the calling process.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
The length of the \fIfilename\fP argument exceeds {PATH_MAX} or a
|
|
pathname component is longer than {NAME_MAX}.
|
|
.TP 7
|
|
.B ENFILE
|
|
The maximum allowable number of files is currently open in the system.
|
|
.TP 7
|
|
.B ENOENT
|
|
A
|
|
component of \fIfilename\fP does not name an existing file or \fIfilename\fP
|
|
is an empty string.
|
|
.TP 7
|
|
.B 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.
|
|
.TP 7
|
|
.B ENOTDIR
|
|
A
|
|
component of the path prefix is not a directory.
|
|
.TP 7
|
|
.B ENXIO
|
|
The named file is a character special or block special file, and the
|
|
device associated with this special file does not exist.
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The named file is a regular file and the size of the file cannot be
|
|
represented correctly in an object of type \fBoff_t\fP.
|
|
.TP 7
|
|
.B EROFS
|
|
The named file resides on a read-only file system and \fImode\fP requires
|
|
write access.
|
|
.sp
|
|
.LP
|
|
The \fIfopen\fP() function may fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The value of the \fImode\fP argument is not valid.
|
|
.TP 7
|
|
.B ELOOP
|
|
More than {SYMLOOP_MAX} symbolic links were encountered during resolution
|
|
of the \fIpath\fP argument.
|
|
.TP 7
|
|
.B EMFILE
|
|
{FOPEN_MAX} streams are currently open in the calling process.
|
|
.TP 7
|
|
.B EMFILE
|
|
{STREAM_MAX} streams are currently open in the calling process.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
Pathname resolution of a symbolic link produced an intermediate result
|
|
whose length exceeds {PATH_MAX}.
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient storage space is available.
|
|
.TP 7
|
|
.B ETXTBSY
|
|
The file is a pure procedure (shared text) file that is being executed
|
|
and \fImode\fP requires write access.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Opening a File
|
|
.LP
|
|
The following example tries to open the file named \fBfile\fP for
|
|
reading. The \fIfopen\fP() function returns a file pointer
|
|
that is used in subsequent \fIfgets\fP() and \fIfclose\fP() calls.
|
|
If the program cannot open the file, it just ignores it.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stdio.h>
|
|
\&...
|
|
FILE *fp;
|
|
\&...
|
|
void rgrep(const char *file)
|
|
{
|
|
\&...
|
|
if ((fp = fopen(file, "r")) == NULL)
|
|
return;
|
|
\&...
|
|
}
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIfclose\fP() , \fIfdopen\fP() , \fIfreopen\fP() , the Base Definitions
|
|
volume of IEEE\ Std\ 1003.1-2001, \fI<stdio.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|