fopen.3p (9717B)
- '\" et
- .TH FOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- fopen
- \(em open a stream
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdio.h>
- .P
- FILE *fopen(const char *restrict \fIpathname\fP, const char *restrict \fImode\fP);
- .fi
- .SH DESCRIPTION
- The functionality described on this reference page is aligned with the
- ISO\ C standard. Any conflict between the requirements described here and the
- ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
- .P
- The
- \fIfopen\fR()
- function shall open the file whose pathname is the string pointed to by
- .IR pathname ,
- and associates a stream with it.
- .P
- The
- .IR mode
- 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.
- .IP "\fIr\fP\ or\ \fIrb\fP" 14
- Open file for reading.
- .IP "\fIw\fP\ or\ \fIwb\fP" 14
- Truncate to zero length or create file for writing.
- .IP "\fIa\fP\ or\ \fIab\fP" 14
- Append; open or create file for writing at end-of-file.
- .IP "\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP" 14
- Open file for update (reading and writing).
- .IP "\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP" 14
- Truncate to zero length or create file for update.
- .IP "\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP" 14
- Append; open or create file for update, writing at end-of-file.
- .P
- The character
- .BR 'b'
- 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
- .IR mode
- argument) shall fail if the file does not exist or cannot be read.
- .P
- Opening a file with append mode (\fIa\fP as the first character in the
- .IR mode
- 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\fR().
- .P
- When a file is opened with update mode (\c
- .BR '+'
- as the second or third character in the
- .IR mode
- 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\fR()
- or to a file positioning function (\c
- \fIfseek\fR(),
- \fIfsetpos\fR(),
- or
- \fIrewind\fR()),
- 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.
- .P
- 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.
- .P
- If
- .IR mode
- is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+,
- \fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file
- did not previously exist, upon successful completion,
- \fIfopen\fR()
- shall mark for update the last data access, last data modification, and
- last file status change timestamps of the file and the last file status
- change and last data modification timestamps of the parent directory.
- .P
- If
- .IR mode
- is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+,
- \fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file
- did not previously exist, the
- \fIfopen\fR()
- function shall create a file as if it called the
- \fIcreat\fR()
- function with a value appropriate for the
- .IR path
- argument interpreted from
- .IR pathname
- and a value of S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH |
- S_IWOTH for the
- .IR mode
- argument.
- .P
- If
- .IR mode
- is \fIw\fR, \fIwb\fR, \fIw\fR+, \fIwb\fR+, or \fIw\fR+\fIb\fR, and the
- file did previously exist, upon successful completion,
- \fIfopen\fR()
- shall mark for update the last data modification and last file
- status change timestamps of the file.
- .P
- After a successful call to the
- \fIfopen\fR()
- function, the orientation of the stream shall be cleared,
- the encoding rule shall be cleared,
- and the associated
- .BR mbstate_t
- object shall be set to describe an initial conversion state.
- .P
- The file descriptor associated with the opened stream shall be allocated
- and opened as if by a call to
- \fIopen\fR()
- with the following flags:
- .TS
- center box tab(!);
- cB | cB
- l | l.
- \fIfopen\fP(\^) Mode!\fIopen\fP(\^) Flags
- _
- \fIr\fR or \fIrb\fR!O_RDONLY
- \fIw\fR or \fIwb\fR!O_WRONLY|O_CREAT|O_TRUNC
- \fIa\fR or \fIab\fR!O_WRONLY|O_CREAT|O_APPEND
- \fIr+\fR or \fIrb+\fR or \fIr+b\fR!O_RDWR
- \fIw+\fR or \fIwb+\fR or \fIw+b\fR!O_RDWR|O_CREAT|O_TRUNC
- \fIa+\fR or \fIab+\fR or \fIa+b\fR!O_RDWR|O_CREAT|O_APPEND
- .TE
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIfopen\fR()
- shall return a pointer to the object controlling the stream. Otherwise,
- a null pointer shall be returned,
- and
- .IR errno
- shall be set to indicate the error.
- .SH ERRORS
- The
- \fIfopen\fR()
- function shall fail if:
- .TP
- .BR EACCES
- Search permission is denied on a component of the path prefix, or the
- file exists and the permissions specified by
- .IR mode
- are denied, or the file does not exist and write permission is denied
- for the parent directory of the file to be created.
- .TP
- .BR EINTR
- A signal was caught during
- \fIfopen\fR().
- .TP
- .BR EISDIR
- The named file is a directory and
- .IR mode
- requires write access.
- .TP
- .BR ELOOP
- A loop exists in symbolic links encountered during resolution of the
- .IR path
- argument.
- .TP
- .BR EMFILE
- All file descriptors available to the process are currently open.
- .TP
- .BR EMFILE
- {STREAM_MAX}
- streams are currently open in the calling process.
- .TP
- .BR ENAMETOOLONG
- .br
- The length of a pathname exceeds
- {PATH_MAX},
- or pathname resolution of a symbolic link produced an intermediate
- result with a length that exceeds
- {PATH_MAX}.
- .TP
- .BR ENFILE
- The maximum allowable number of files is currently open in the system.
- .TP
- .BR ENOENT
- The
- .IR mode
- string begins with
- .BR 'r'
- and a component of
- .IR pathname
- does not name an existing file, or
- .IR mode
- begins with
- .BR 'w'
- or
- .BR 'a'
- and a component of the path prefix of
- .IR pathname
- does not name an existing file, or
- .IR pathname
- is an empty string.
- .TP
- .BR ENOENT " or " ENOTDIR
- .br
- The
- .IR pathname
- argument contains at least one non-\c
- <slash>
- character and ends with one or more trailing
- <slash>
- characters. If
- .IR pathname
- without the trailing
- <slash>
- characters would name an existing file, an
- .BR [ENOENT]
- error shall not occur.
- .TP
- .BR 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
- .BR ENOTDIR
- A component of the path prefix names an existing file that is neither
- a directory nor a symbolic link to a directory, or the
- .IR pathname
- argument contains at least one non-\c
- <slash>
- character and ends with one or more trailing
- <slash>
- characters and the last pathname component names an existing file that
- is neither a directory nor a symbolic link to a directory.
- .TP
- .BR ENXIO
- The named file is a character special or block special file,
- and the device associated with this special file does not exist.
- .TP
- .BR EOVERFLOW
- The named file is a regular file and the size of the file cannot be
- represented correctly in an object of type
- .BR off_t .
- .TP
- .BR EROFS
- The named file resides on a read-only file system and
- .IR mode
- requires write access.
- .P
- The
- \fIfopen\fR()
- function may fail if:
- .TP
- .BR EINVAL
- The value of the
- .IR mode
- argument is not valid.
- .TP
- .BR ELOOP
- More than
- {SYMLOOP_MAX}
- symbolic links were encountered during resolution of the
- .IR path
- argument.
- .TP
- .BR EMFILE
- {FOPEN_MAX}
- streams are currently open in the calling process.
- .TP
- .BR ENAMETOOLONG
- .br
- The length of a component of a pathname is longer than
- {NAME_MAX}.
- .TP
- .BR ENOMEM
- Insufficient storage space is available.
- .TP
- .BR ETXTBSY
- The file is a pure procedure (shared text) file that is being executed
- and
- .IR mode
- requires write access.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Opening a File"
- .P
- The following example tries to open the file named
- .BR file
- for reading. The
- \fIfopen\fR()
- function returns a file pointer that is used in subsequent
- \fIfgets\fR()
- and
- \fIfclose\fR()
- calls. If the program cannot open the file, it just ignores it.
- .sp
- .RS 4
- .nf
- #include <stdio.h>
- \&...
- FILE *fp;
- \&...
- void rgrep(const char *file)
- {
- \&...
- if ((fp = fopen(file, "r")) == NULL)
- return;
- \&...
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.5" ", " "Standard I/O Streams",
- .IR "\fIcreat\fR\^(\|)",
- .IR "\fIfclose\fR\^(\|)",
- .IR "\fIfdopen\fR\^(\|)",
- .IR "\fIfmemopen\fR\^(\|)",
- .IR "\fIfreopen\fR\^(\|)",
- .IR "\fIopen_memstream\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<stdio.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .