126 lines
5.9 KiB
HTML
126 lines
5.9 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<title>BIO_s_mem</title>
|
||
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
|
<link rev="made" href="mailto:nwani@atx-osx1010-2.corp.continuum.io" />
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<ul id="index">
|
||
|
|
<li><a href="#NAME">NAME</a></li>
|
||
|
|
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||
|
|
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
|
||
|
|
<li><a href="#NOTES">NOTES</a></li>
|
||
|
|
<li><a href="#BUGS">BUGS</a></li>
|
||
|
|
<li><a href="#EXAMPLE">EXAMPLE</a></li>
|
||
|
|
<li><a href="#RETURN-VALUES">RETURN VALUES</a></li>
|
||
|
|
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h1 id="NAME">NAME</h1>
|
||
|
|
|
||
|
|
<p>BIO_s_secmem, 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</p>
|
||
|
|
|
||
|
|
<h1 id="SYNOPSIS">SYNOPSIS</h1>
|
||
|
|
|
||
|
|
<pre><code> #include <openssl/bio.h>
|
||
|
|
|
||
|
|
const BIO_METHOD *BIO_s_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);</code></pre>
|
||
|
|
|
||
|
|
<h1 id="DESCRIPTION">DESCRIPTION</h1>
|
||
|
|
|
||
|
|
<p>BIO_s_mem() returns the memory BIO method function.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used for buffer storage.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Memory BIOs support BIO_gets() and BIO_puts().</p>
|
||
|
|
|
||
|
|
<p>If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying BUF_MEM structure is also freed.</p>
|
||
|
|
|
||
|
|
<p>Calling BIO_reset() on a read write memory BIO clears any data in it if the flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and the data can be read again.</p>
|
||
|
|
|
||
|
|
<p>BIO_eof() is true if no data is in the BIO.</p>
|
||
|
|
|
||
|
|
<p>BIO_ctrl_pending() returns the number of bytes currently stored.</p>
|
||
|
|
|
||
|
|
<p>BIO_set_mem_eof_return() sets the behaviour of memory BIO <b>b</b> when it is empty. If the <b>v</b> 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 <b>v</b> is non zero then it will return <b>v</b> 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 <b>v</b> should be set to a negative value, typically -1.</p>
|
||
|
|
|
||
|
|
<p>BIO_get_mem_data() sets *<b>pp</b> 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.</p>
|
||
|
|
|
||
|
|
<p>BIO_set_mem_buf() sets the internal BUF_MEM structure to <b>bm</b> and sets the close flag to <b>c</b>, that is <b>c</b> should be either BIO_CLOSE or BIO_NOCLOSE. It is a macro.</p>
|
||
|
|
|
||
|
|
<p>BIO_get_mem_ptr() places the underlying BUF_MEM structure in *<b>pp</b>. It is a macro.</p>
|
||
|
|
|
||
|
|
<p>BIO_new_mem_buf() creates a memory BIO using <b>len</b> bytes of data at <b>buf</b>, if <b>len</b> is -1 then the <b>buf</b> is assumed to be nul terminated and its length is determined by <b>strlen</b>. 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 <b>not</b> copied first, so the supplied area of memory must be unchanged until the BIO is freed.</p>
|
||
|
|
|
||
|
|
<h1 id="NOTES">NOTES</h1>
|
||
|
|
|
||
|
|
<p>Writes to memory BIOs will always succeed if memory is available: that is their size can grow indefinitely.</p>
|
||
|
|
|
||
|
|
<p>Every read from a read write memory BIO will remove the data just read with an internal copy operation, if a BIO contains a lot of data and it is read in small chunks the operation can be very slow. The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a buffering BIO to the chain will speed up the process.</p>
|
||
|
|
|
||
|
|
<p>Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will give undefined results, including perhaps a program crash.</p>
|
||
|
|
|
||
|
|
<h1 id="BUGS">BUGS</h1>
|
||
|
|
|
||
|
|
<p>There should be an option to set the maximum size of a memory BIO.</p>
|
||
|
|
|
||
|
|
<h1 id="EXAMPLE">EXAMPLE</h1>
|
||
|
|
|
||
|
|
<p>Create a memory BIO and write some data to it:</p>
|
||
|
|
|
||
|
|
<pre><code> BIO *mem = BIO_new(BIO_s_mem());
|
||
|
|
|
||
|
|
BIO_puts(mem, "Hello World\n");</code></pre>
|
||
|
|
|
||
|
|
<p>Create a read only memory BIO:</p>
|
||
|
|
|
||
|
|
<pre><code> char data[] = "Hello World";
|
||
|
|
BIO *mem = BIO_new_mem_buf(data, -1);</code></pre>
|
||
|
|
|
||
|
|
<p>Extract the BUF_MEM structure from a memory BIO and then free up the BIO:</p>
|
||
|
|
|
||
|
|
<pre><code> 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);</code></pre>
|
||
|
|
|
||
|
|
<h1 id="RETURN-VALUES">RETURN VALUES</h1>
|
||
|
|
|
||
|
|
<p>BIO_s_mem() and BIO_s_secmem() return a valid memory <b>BIO_METHOD</b> structure.</p>
|
||
|
|
|
||
|
|
<p>BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr() return 1 on success or a value which is less than or equal to 0 if an error occurred.</p>
|
||
|
|
|
||
|
|
<p>BIO_new_mem_buf() returns a valid <b>BIO</b> structure on success or NULL on error.</p>
|
||
|
|
|
||
|
|
<h1 id="COPYRIGHT">COPYRIGHT</h1>
|
||
|
|
|
||
|
|
<p>Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
|
|
||
|
|
<p>Licensed under the OpenSSL license (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 <a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
|
||
|
|
</html>
|
||
|
|
|
||
|
|
|