diff options
Diffstat (limited to 'man/man3/fopen.3')
| -rw-r--r-- | man/man3/fopen.3 | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/man/man3/fopen.3 b/man/man3/fopen.3 new file mode 100644 index 0000000..bf09c62 --- /dev/null +++ b/man/man3/fopen.3 @@ -0,0 +1,405 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" Modified, aeb, 960421, 970806 +.\" Modified, joey, aeb, 2002-01-03 +.\" +.TH fopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fopen, fdopen, freopen \- stream open functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *fopen(const char *restrict " pathname \ +", const char *restrict " mode ); +.BI "FILE *fdopen(int " fd ", const char *" mode ); +.BI "FILE *freopen(const char *restrict " pathname \ +", const char *restrict " mode , +.BI " FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdopen (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR fopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates a stream with it. +.P +The argument +.I mode +points to a string beginning with one of the following sequences +(possibly followed by additional characters, as described below): +.TP +.B r +Open text file for reading. +The stream is positioned at the beginning of the file. +.TP +.B r+ +Open for reading and writing. +The stream is positioned at the beginning of the file. +.TP +.B w +Truncate file to zero length or create text file for writing. +The stream is positioned at the beginning of the file. +.TP +.B w+ +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +The stream is positioned at the beginning of +the file. +.TP +.B a +Open for appending (writing at end of file). +The file is created if it does not exist. +The stream is positioned at the end of the file. +.TP +.B a+ +Open for reading and appending (writing at end of file). +The file is created if it does not exist. +Output is always appended to the end of the file. +POSIX is silent on what the initial read position is when using this mode. +For glibc, the initial file position for reading is at +the beginning of the file, but for Android/BSD/MacOS, the +initial file position for reading is at the end of the file. +.P +The +.I mode +string can also include the letter \[aq]b\[aq] either as a last character or as +a character between the characters in any of the two-character strings +described above. +This is strictly for compatibility with ISO C +and has no effect; the \[aq]b\[aq] is ignored on all POSIX +conforming systems, including Linux. +(Other systems may treat text files and binary files differently, +and adding the \[aq]b\[aq] may be a good idea if you do I/O to a binary +file and expect that your program may be ported to non-UNIX +environments.) +.P +See NOTES below for details of glibc extensions for +.IR mode . +.P +Any created file will have the mode +.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH +(0666), as modified by the process's umask value (see +.BR umask (2)). +.P +Reads and writes may be intermixed on read/write streams in any order. +Note that ANSI C requires that a file positioning function intervene +between output and input, unless an input operation encounters end-of-file. +(If this condition is not met, then a read is allowed to return the +result of writes other than the most recent.) +Therefore it is good practice (and indeed sometimes necessary +under Linux) to put an +.BR fseek (3) +or +.BR fsetpos (3) +operation between write and read operations on such a stream. +This operation may be an apparent no-op +(as in \fIfseek(..., 0L, SEEK_CUR)\fP +called for its synchronizing side effect). +.P +Opening a file in append mode (\fBa\fP as the first character of +.IR mode ) +causes all subsequent write operations to this stream to occur +at end-of-file, as if preceded by the call: +.P +.in +4n +.EX +fseek(stream, 0, SEEK_END); +.EE +.in +.P +The file descriptor associated with the stream is opened as if by a call to +.BR open (2) +with the following flags: +.RS +.TS +allbox; +lb lb +c l. +fopen() mode open() flags +\fIr\fP O_RDONLY +\fIw\fP O_WRONLY | O_CREAT | O_TRUNC +\fIa\fP O_WRONLY | O_CREAT | O_APPEND +\fIr+\fP O_RDWR +\fIw+\fP O_RDWR | O_CREAT | O_TRUNC +\fIa+\fP O_RDWR | O_CREAT | O_APPEND +.TE +.RE +.\" +.SS fdopen() +The +.BR fdopen () +function associates a stream with the existing file descriptor, +.IR fd . +The +.I mode +of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") +must be compatible with the mode of the file descriptor. +The file position indicator of the new stream is set to that +belonging to +.IR fd , +and the error and end-of-file indicators are cleared. +Modes "w" or "w+" do not cause truncation of the file. +The file descriptor is not dup'ed, and will be closed when +the stream created by +.BR fdopen () +is closed. +The result of applying +.BR fdopen () +to a shared memory object is undefined. +.\" +.SS freopen() +The +.BR freopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates the stream pointed to by +.I stream +with it. +The original stream (if it exists) is closed. +The +.I mode +argument is used just as in the +.BR fopen () +function. +.P +If the +.I pathname +argument is a null pointer, +.BR freopen () +changes the mode of the stream to that specified in +.IR mode ; +that is, +.BR freopen () +reopens the pathname that is associated with the stream. +The specification for this behavior was added in the C99 standard, which says: +.P +.RS +In this case, +the file descriptor associated with the stream need not be closed +if the call to +.BR freopen () +succeeds. +It is implementation-defined which changes of mode are permitted (if any), +and under what circumstances. +.RE +.P +The primary use of the +.BR freopen () +function is to change the file associated with a standard text stream +.RI ( stderr ", " stdin ", or " stdout ). +.SH RETURN VALUE +Upon successful completion +.BR fopen (), +.BR fdopen (), +and +.BR freopen () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I mode +provided to +.BR fopen (), +.BR fdopen (), +or +.BR freopen () +was invalid. +.P +The +.BR fopen (), +.BR fdopen (), +and +.BR freopen () +functions may also fail and set +.I errno +for any of the errors specified for the routine +.BR malloc (3). +.P +The +.BR fopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR open (2). +.P +The +.BR fdopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR fcntl (2). +.P +The +.BR freopen () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR open (2), +.BR fclose (3), +and +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fopen (), +.BR fdopen (), +.BR freopen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR fopen () +.TQ +.BR freopen () +C11, POSIX.1-2008. +.TP +.BR fdopen () +POSIX.1-2008. +.SH HISTORY +.TP +.BR fopen () +.TQ +.BR freopen () +POSIX.1-2001, C89. +.TP +.BR fdopen () +POSIX.1-2001. +.SH NOTES +.SS glibc notes +The GNU C library allows the following extensions for the string specified in +.IR mode : +.TP +.BR c " (since glibc 2.3.3)" +Do not make the open operation, +or subsequent read and write operations, +thread cancelation points. +This flag is ignored for +.BR fdopen (). +.TP +.BR e " (since glibc 2.7)" +Open the file with the +.B O_CLOEXEC +flag. +See +.BR open (2) +for more information. +This flag is ignored for +.BR fdopen (). +.TP +.BR m " (since glibc 2.3)" +Attempt to access the file using +.BR mmap (2), +rather than I/O system calls +.RB ( read (2), +.BR write (2)). +Currently, +.\" As at glibc 2.4: +use of +.BR mmap (2) +is attempted only for a file opened for reading. +.TP +.B x +.\" Since glibc 2.0? +.\" FIXME . C11 specifies this flag +Open the file exclusively +(like the +.B O_EXCL +flag of +.BR open (2)). +If the file already exists, +.BR fopen () +fails, and sets +.I errno +to +.BR EEXIST . +This flag is ignored for +.BR fdopen (). +.P +In addition to the above characters, +.BR fopen () +and +.BR freopen () +support the following syntax +in +.IR mode : +.P +.BI " ,ccs=" string +.P +The given +.I string +is taken as the name of a coded character set and +the stream is marked as wide-oriented. +Thereafter, internal conversion functions convert I/O +to and from the character set +.IR string . +If the +.BI ,ccs= string +syntax is not specified, +then the wide-orientation of the stream is +determined by the first file operation. +If that operation is a wide-character operation, +the stream is marked wide-oriented, +and functions to convert to the coded character set are loaded. +.SH BUGS +When parsing for individual flag characters in +.I mode +(i.e., the characters preceding the "ccs" specification), +the glibc implementation of +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 +.BR fopen () +and +.BR freopen () +limits the number of characters examined in +.I mode +to 7 (or, before glibc 2.14, to 6, +which was not enough to include possible specifications such as "rb+cmxe"). +The current implementation of +.BR fdopen () +parses at most 5 characters in +.IR mode . +.SH SEE ALSO +.BR open (2), +.BR fclose (3), +.BR fileno (3), +.BR fmemopen (3), +.BR fopencookie (3), +.BR open_memstream (3) |