diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/BIO_s_mem.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/BIO_s_mem.3 | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/BIO_s_mem.3 b/secure/lib/libcrypto/man/man3/BIO_s_mem.3 new file mode 100644 index 000000000000..58320b109713 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/BIO_s_mem.3 @@ -0,0 +1,273 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "BIO_S_MEM 3ossl" +.TH BIO_S_MEM 3ossl 2025-09-30 3.5.4 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_secmem, BIO_s_dgram_mem, +BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, +BIO_get_mem_ptr, BIO_new_mem_buf \- memory BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/bio.h> +\& +\& const BIO_METHOD *BIO_s_mem(void); +\& const BIO_METHOD *BIO_s_dgram_mem(void); +\& const BIO_METHOD *BIO_s_secmem(void); +\& +\& BIO_set_mem_eof_return(BIO *b, int v); +\& long BIO_get_mem_data(BIO *b, char **pp); +\& BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c); +\& BIO_get_mem_ptr(BIO *b, BUF_MEM **pp); +\& +\& BIO *BIO_new_mem_buf(const void *buf, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_mem()\fR returns the memory BIO method function. +.PP +A memory BIO is a source/sink BIO which uses memory for its I/O. Data +written to a memory BIO is stored in a BUF_MEM structure which is extended +as appropriate to accommodate the stored data. +.PP +\&\fBBIO_s_secmem()\fR is like \fBBIO_s_mem()\fR except that the secure heap is used +for buffer storage. +.PP +\&\fBBIO_s_dgram_mem()\fR is a memory BIO that respects datagram semantics. A single +call to \fBBIO_write\fR\|(3) will write a single datagram to the memory BIO. A +subsequent call to \fBBIO_read\fR\|(3) will read the data in that datagram. The +\&\fBBIO_read\fR\|(3) call will never return more data than was written in the original +\&\fBBIO_write\fR\|(3) call even if there were subsequent \fBBIO_write\fR\|(3) calls that +wrote more datagrams. Each successive call to \fBBIO_read\fR\|(3) will read the next +datagram. If a \fBBIO_read\fR\|(3) call supplies a read buffer that is smaller than +the size of the datagram, then the read buffer will be completely filled and the +remaining data from the datagram will be discarded. +.PP +It is not possible to write a zero length datagram. Calling \fBBIO_write\fR\|(3) in +this case will return 0 and no datagrams will be written. Calling \fBBIO_read\fR\|(3) +when there are no datagrams in the BIO to read will return a negative result and +the "retry" flags will be set (i.e. calling \fBBIO_should_retry\fR\|(3) will return +true). A datagram mem BIO will never return true from \fBBIO_eof\fR\|(3). +.PP +Any data written to a memory BIO can be recalled by reading from it. +Unless the memory BIO is read only any data read from it is deleted from +the BIO. +.PP +Memory BIOs except \fBBIO_s_dgram_mem()\fR support \fBBIO_gets()\fR and \fBBIO_puts()\fR. +.PP +\&\fBBIO_s_dgram_mem()\fR supports \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) calls +and calls related to \fBBIO_ADDR\fR and MTU handling similarly to the +\&\fBBIO_s_dgram_pair\fR\|(3). +.PP +If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying +BUF_MEM structure is also freed. +.PP +Calling \fBBIO_reset()\fR on a read write memory BIO clears any data in it if the +flag BIO_FLAGS_NONCLEAR_RST is not set, otherwise it just restores the read +pointer to the state it was just after the last write was performed and the +data can be read again. On a read only BIO it similarly restores the BIO to +its original state and the read only data can be read again. +.PP +\&\fBBIO_eof()\fR is true if no data is in the BIO. +.PP +\&\fBBIO_ctrl_pending()\fR returns the number of bytes currently stored. +.PP +\&\fBBIO_set_mem_eof_return()\fR sets the behaviour of memory BIO \fBb\fR when it is +empty. If the \fBv\fR is zero then an empty memory BIO will return EOF (that is +it will return zero and BIO_should_retry(b) will be false. If \fBv\fR is non +zero then it will return \fBv\fR when it is empty and it will set the read retry +flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal +positive return value \fBv\fR should be set to a negative value, typically \-1. +Calling this macro will fail for datagram mem BIOs. +.PP +\&\fBBIO_get_mem_data()\fR sets *\fBpp\fR to a pointer to the start of the memory BIOs data +and returns the total amount of data available. It is implemented as a macro. +Note the pointer returned by this call is informative, no transfer of ownership +of this memory is implied. See notes on \fBBIO_set_close()\fR. +.PP +\&\fBBIO_set_mem_buf()\fR sets the internal BUF_MEM structure to \fBbm\fR and sets the +close flag to \fBc\fR, that is \fBc\fR should be either BIO_CLOSE or BIO_NOCLOSE. +It is a macro. +.PP +\&\fBBIO_get_mem_ptr()\fR places the underlying BUF_MEM structure in *\fBpp\fR. It is +a macro. +.PP +\&\fBBIO_new_mem_buf()\fR creates a memory BIO using \fBlen\fR bytes of data at \fBbuf\fR, +if \fBlen\fR is \-1 then the \fBbuf\fR is assumed to be nul terminated and its +length is determined by \fBstrlen\fR. The BIO is set to a read only state and +as a result cannot be written to. This is useful when some data needs to be +made available from a static area of memory in the form of a BIO. The +supplied data is read directly from the supplied buffer: it is \fBnot\fR copied +first, so the supplied area of memory must be unchanged until the BIO is freed. +.PP +All of the five functions described above return an error with +\&\fBBIO_s_dgram_mem()\fR. +.SH NOTES +.IX Header "NOTES" +Writes to memory BIOs will always succeed if memory is available: that is +their size can grow indefinitely. An exception is \fBBIO_s_dgram_mem()\fR when +\&\fBBIO_set_write_buf_size\fR\|(3) is called on it. In such case the write buffer +size will be fixed and any writes that would overflow the buffer will return +an error. +.PP +Every write after partial read (not all data in the memory buffer was read) +to a read write memory BIO will have to move the unread data with an internal +copy operation, if a BIO contains a lot of data and it is read in small +chunks intertwined with writes the operation can be very slow. Adding +a buffering BIO to the chain can speed up the process. +.PP +Calling \fBBIO_set_mem_buf()\fR on a secmem or dgram BIO will give undefined results, +including perhaps a program crash. +.PP +Switching a memory BIO from read write to read only is not supported and +can give undefined results including a program crash. There are two notable +exceptions to the rule. The first one is to assign a static memory buffer +immediately after BIO creation and set the BIO as read only. +.PP +The other supported sequence is to start with a read write BIO then temporarily +switch it to read only and call \fBBIO_reset()\fR on the read only BIO immediately +before switching it back to read write. Before the BIO is freed it must be +switched back to the read write mode. +.PP +Calling \fBBIO_get_mem_ptr()\fR on read only BIO will return a BUF_MEM that +contains only the remaining data to be read. If the close status of the +BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer +in it must be set to NULL as the data pointer does not point to an +allocated memory. +.PP +Calling \fBBIO_reset()\fR on a read write memory BIO with BIO_FLAGS_NONCLEAR_RST +flag set can have unexpected outcome when the reads and writes to the +BIO are intertwined. As documented above the BIO will be reset to the +state after the last completed write operation. The effects of reads +preceding that write operation cannot be undone. +.PP +Calling \fBBIO_get_mem_ptr()\fR prior to a \fBBIO_reset()\fR call with +BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation. +.PP +Calling \fBBIO_set_close()\fR with BIO_NOCLOSE orphans the BUF_MEM internal to the +BIO, _not_ its actual data buffer. See the examples section for the proper +method for claiming ownership of the data pointer for a deferred free operation. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_mem()\fR, \fBBIO_s_dgram_mem()\fR and \fBBIO_s_secmem()\fR return a valid memory +\&\fBBIO_METHOD\fR structure. +.PP +\&\fBBIO_set_mem_eof_return()\fR, \fBBIO_set_mem_buf()\fR and \fBBIO_get_mem_ptr()\fR +return 1 on success or a value which is less than or equal to 0 if an error occurred. +.PP +\&\fBBIO_get_mem_data()\fR returns the total number of bytes available on success, +0 if b is NULL, or a negative value in case of other errors. +.PP +\&\fBBIO_new_mem_buf()\fR returns a valid \fBBIO\fR structure on success or NULL on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create a memory BIO and write some data to it: +.PP +.Vb 1 +\& BIO *mem = BIO_new(BIO_s_mem()); +\& +\& BIO_puts(mem, "Hello World\en"); +.Ve +.PP +Create a read only memory BIO: +.PP +.Vb 2 +\& char data[] = "Hello World"; +\& BIO *mem = BIO_new_mem_buf(data, \-1); +.Ve +.PP +Extract the BUF_MEM structure from a memory BIO and then free up the BIO: +.PP +.Vb 1 +\& BUF_MEM *bptr; +\& +\& BIO_get_mem_ptr(mem, &bptr); +\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ +\& BIO_free(mem); +.Ve +.PP +Extract the BUF_MEM ptr, claim ownership of the internal data and free the BIO +and BUF_MEM structure: +.PP +.Vb 2 +\& BUF_MEM *bptr; +\& char *data; +\& +\& BIO_get_mem_data(bio, &data); +\& BIO_get_mem_ptr(bio, &bptr); +\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free orphans BUF_MEM */ +\& BIO_free(bio); +\& bptr\->data = NULL; /* Tell BUF_MEM to orphan data */ +\& BUF_MEM_free(bptr); +\& ... +\& free(data); +.Ve +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_s_dgram_mem()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |