diff options
Diffstat (limited to 'man3/fopen.3')
| -rw-r--r-- | man3/fopen.3 | 405 |
1 files changed, 0 insertions, 405 deletions
diff --git a/man3/fopen.3 b/man3/fopen.3 deleted file mode 100644 index 654c697..0000000 --- a/man3/fopen.3 +++ /dev/null @@ -1,405 +0,0 @@ -'\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |