Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 406 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man3/fopen.3 b/upstream/opensuse-tumbleweed/man3/fopen.3
new file mode 100644
index 00000000..e96303c9
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man3/fopen.3
@@ -0,0 +1,406 @@
+'\" 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-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+fopen, fdopen, freopen \- stream open functions
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.PP
+.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
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.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.
+.PP
+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.
+.PP
+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.)
+.PP
+See NOTES below for details of glibc extensions for
+.IR mode .
+.PP
+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)).
+.PP
+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).
+.PP
+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:
+.PP
+.in +4n
+.EX
+fseek(stream, 0, SEEK_END);
+.EE
+.in
+.PP
+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.
+.PP
+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:
+.PP
+.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
+.PP
+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.
+.PP
+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).
+.PP
+The
+.BR fopen ()
+function may also fail and set
+.I errno
+for any of the errors specified for the routine
+.BR open (2).
+.PP
+The
+.BR fdopen ()
+function may also fail and set
+.I errno
+for any of the errors specified for the routine
+.BR fcntl (2).
+.PP
+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
+.sp 1
+.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 ().
+.PP
+In addition to the above characters,
+.BR fopen ()
+and
+.BR freopen ()
+support the following syntax
+in
+.IR mode :
+.PP
+.BI "    ,ccs=" string
+.PP
+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)