diff options
Diffstat (limited to 'man/man3/fmemopen.3')
| -rw-r--r-- | man/man3/fmemopen.3 | 352 |
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) |