Merging upstream version 6.8.

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

1 files changed, 352 insertions, 0 deletions

diff --git a/man/man3/fmemopen.3 b/man/man3/fmemopen.3
new file mode 100644
index 0000000..eb68fd3
--- /dev/null
+++ b/man/man3/fmemopen.3
@@ -0,0 +1,352 @@
+'\" t
+.\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.TH fmemopen 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+fmemopen \-  open memory as stream
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.P
+.BI "FILE *fmemopen(void " buf [. size "], size_t " size ", \
+const char *" mode );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR fmemopen ():
+.nf
+    Since glibc 2.10:
+        _POSIX_C_SOURCE >= 200809L
+    Before glibc 2.10:
+        _GNU_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR fmemopen ()
+function opens a stream that permits the access specified by
+.IR mode .
+The stream allows I/O to be performed on the string or memory buffer
+pointed to by
+.IR buf .
+.P
+The
+.I mode
+argument specifies the semantics of I/O on the stream,
+and is one of the following:
+.TP
+.I r
+The stream is opened for reading.
+.TP
+.I w
+The stream is opened for writing.
+.TP
+.I a
+Append; open the stream for writing,
+with the initial buffer position set to the first null byte.
+.TP
+.I r+
+Open the stream for reading and writing.
+.TP
+.I w+
+Open the stream for reading and writing.
+The buffer contents are truncated
+(i.e., \[aq]\e0\[aq] is placed in the first byte of the buffer).
+.TP
+.I a+
+Append; open the stream for reading and writing,
+with the initial buffer position set to the first null byte.
+.P
+The stream maintains the notion of a current position,
+the location where the next I/O operation will be performed.
+The current position is implicitly updated by I/O operations.
+It can be explicitly updated using
+.BR fseek (3),
+and determined using
+.BR ftell (3).
+In all modes other than append,
+the initial position is set to the start of the buffer.
+In append mode, if no null byte is found within the buffer,
+then the initial position is
+.IR size+1 .
+.P
+If
+.I buf
+is specified as NULL, then
+.BR fmemopen ()
+allocates a buffer of
+.I size
+bytes.
+This is useful for an application that wants to write data to
+a temporary buffer and then read it back again.
+The initial position is set to the start of the buffer.
+The buffer is automatically freed when the stream is closed.
+Note that the caller has no way to obtain a pointer to the
+temporary buffer allocated by this call (but see
+.BR open_memstream (3)).
+.P
+If
+.I buf
+is not NULL, then it should point to a buffer of at least
+.I size
+bytes allocated by the caller.
+.P
+When a stream that has been opened for writing is flushed
+.RB ( fflush (3))
+or closed
+.RB ( fclose (3)),
+a null byte is written at the end of the buffer if there is space.
+The caller should ensure that an extra byte is available in the
+buffer
+(and that
+.I size
+counts that byte)
+to allow for this.
+.P
+In a stream opened for reading,
+null bytes (\[aq]\e0\[aq]) in the buffer do not cause read
+operations to return an end-of-file indication.
+A read from the buffer will indicate end-of-file
+only when the current buffer position advances
+.I size
+bytes past the start of the buffer.
+.P
+Write operations take place either at the current position
+(for modes other than append), or at the current size of the stream
+(for append modes).
+.P
+Attempts to write more than
+.I size
+bytes to the buffer result in an error.
+By default, such errors will be visible
+(by the absence of data) only when the
+.I stdio
+buffer is flushed.
+Disabling buffering with the following call
+may be useful to detect errors at the time of an output operation:
+.P
+.in +4n
+.EX
+setbuf(stream, NULL);
+.EE
+.in
+.SH RETURN VALUE
+Upon successful completion,
+.BR fmemopen ()
+returns a
+.I FILE
+pointer.
+Otherwise, NULL is returned and
+.I errno
+is set to indicate the error.
+.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 fmemopen (),
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 1.0.x.
+POSIX.1-2008.
+.P
+POSIX.1-2008 specifies that \[aq]b\[aq] in
+.I mode
+shall be ignored.
+However, Technical Corrigendum 1
+.\" http://austingroupbugs.net/view.php?id=396
+adjusts the standard to allow implementation-specific treatment for this case,
+thus permitting the glibc treatment of \[aq]b\[aq].
+.P
+With glibc 2.22, binary mode (see below) was removed,
+many longstanding bugs in the implementation of
+.BR fmemopen ()
+were fixed, and a new versioned symbol was created for this interface.
+.\"
+.SS Binary mode
+From glibc 2.9 to glibc 2.21, the glibc implementation of
+.BR fmemopen ()
+supported a "binary" mode,
+enabled by specifying the letter \[aq]b\[aq] as the second character in
+.IR mode .
+In this mode,
+writes don't implicitly add a terminating null byte, and
+.BR fseek (3)
+.B SEEK_END
+is relative to the end of the buffer (i.e., the value specified by the
+.I size
+argument), rather than the current string length.
+.P
+An API bug afflicted the implementation of binary mode:
+to specify binary mode, the \[aq]b\[aq] must be the
+.I second
+character in
+.IR mode .
+Thus, for example, "wb+" has the desired effect, but "w+b" does not.
+This is inconsistent with the treatment of
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836
+.I mode
+by
+.BR fopen (3).
+.P
+Binary mode was removed in glibc 2.22; a \[aq]b\[aq] specified in
+.I mode
+has no effect.
+.SH NOTES
+There is no file descriptor associated with the file stream
+returned by this function
+(i.e.,
+.BR fileno (3)
+will return an error if called on the returned stream).
+.SH BUGS
+Before glibc 2.22, if
+.I size
+is specified as zero,
+.BR fmemopen ()
+fails with the error
+.BR EINVAL .
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=11216
+It would be more consistent if this case successfully created
+a stream that then returned end-of-file on the first attempt at reading;
+since glibc 2.22, the glibc implementation provides that behavior.
+.P
+Before glibc 2.22,
+specifying append mode ("a" or "a+") for
+.BR fmemopen ()
+sets the initial buffer position to the first null byte, but
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13152
+(if the current position is reset to a location other than
+the end of the stream)
+does not force subsequent writes to append at the end of the stream.
+This bug is fixed in glibc 2.22.
+.P
+Before glibc 2.22, if the
+.I mode
+argument to
+.BR fmemopen ()
+specifies append ("a" or "a+"), and the
+.I size
+argument does not cover a null byte in
+.IR buf ,
+then, according to POSIX.1-2008,
+the initial buffer position should be set to
+the next byte after the end of the buffer.
+However, in this case the glibc
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13151
+.BR fmemopen ()
+sets the buffer position to \-1.
+This bug is fixed in glibc 2.22.
+.P
+Before glibc 2.22,
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292
+when a call to
+.BR fseek (3)
+with a
+.I whence
+value of
+.B SEEK_END
+was performed on a stream created by
+.BR fmemopen (),
+the
+.I offset
+was
+.I subtracted
+from the end-of-stream position, instead of being added.
+This bug is fixed in glibc 2.22.
+.P
+The glibc 2.9 addition of "binary" mode for
+.BR fmemopen ()
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
+silently changed the ABI: previously,
+.BR fmemopen ()
+ignored \[aq]b\[aq] in
+.IR mode .
+.SH EXAMPLES
+The program below uses
+.BR fmemopen ()
+to open an input buffer, and
+.BR open_memstream (3)
+to open a dynamically sized output buffer.
+The program scans its input string (taken from the program's
+first command-line argument) reading integers,
+and writes the squares of these integers to the output buffer.
+An example of the output produced by this program is the following:
+.P
+.in +4n
+.EX
+.RB "$" " ./a.out \[aq]1 23 43\[aq]"
+size=11; ptr=1 529 1849
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (fmemopen.c)
+.EX
+#define _GNU_SOURCE
+#include <err.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    FILE *out, *in;
+    int v, s;
+    size_t size;
+    char *ptr;
+\&
+    if (argc != 2) {
+        fprintf(stderr, "Usage: %s \[aq]<num>...\[aq]\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    in = fmemopen(argv[1], strlen(argv[1]), "r");
+    if (in == NULL)
+        err(EXIT_FAILURE, "fmemopen");
+\&
+    out = open_memstream(&ptr, &size);
+    if (out == NULL)
+        err(EXIT_FAILURE, "open_memstream");
+\&
+    for (;;) {
+        s = fscanf(in, "%d", &v);
+        if (s <= 0)
+            break;
+\&
+        s = fprintf(out, "%d ", v * v);
+        if (s == \-1)
+            err(EXIT_FAILURE, "fprintf");
+    }
+\&
+    fclose(in);
+    fclose(out);
+\&
+    printf("size=%zu; ptr=%s\en", size, ptr);
+\&
+    free(ptr);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR fopen (3),
+.BR fopencookie (3),
+.BR open_memstream (3)