Import OpenSSL 1.1.0f

doc/crypto/BIO_s_mem.pod

@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+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
 
@@ -9,23 +10,27 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
 
  #include <openssl/bio.h>
 
- BIO_METHOD *	BIO_s_mem(void);
+ const BIO_METHOD *     BIO_s_mem(void);
+ const BIO_METHOD *     BIO_s_secmem(void);
 
- BIO_set_mem_eof_return(BIO *b,int v)
+ 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_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);
 
 =head1 DESCRIPTION
 
-BIO_s_mem() return the memory BIO method function. 
+BIO_s_mem() return the memory BIO method function.
 
 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.
 
+BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
+for buffer storage.
+
 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.
@@ -35,9 +40,10 @@ Memory BIOs support BIO_gets() and BIO_puts().
 If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
 BUF_MEM structure is also freed.
 
-Calling BIO_reset() on a read write memory BIO clears any data in it. On a
-read only BIO it restores the BIO to its original state and the read only
-data can be read again.
+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.
 
 BIO_eof() is true if no data is in the BIO.
 
@@ -79,22 +85,19 @@ 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.
 
+Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
+give undefined results, including perhaps a program crash.
+
 =head1 BUGS
 
 There should be an option to set the maximum size of a memory BIO.
 
-There should be a way to "rewind" a read write BIO without destroying
-its contents.
-
-The copying operation should not occur after every small read of a large BIO
-to improve efficiency.
-
 =head1 EXAMPLE
 
 Create a memory BIO and write some data to it:
 
  BIO *mem = BIO_new(BIO_s_mem());
- BIO_puts(mem, "Hello World\n"); 
+ BIO_puts(mem, "Hello World\n");
 
 Create a read only memory BIO:
 
@@ -108,8 +111,14 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
  BIO_get_mem_ptr(mem, &bptr);
  BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
  BIO_free(mem);
- 
 
-=head1 SEE ALSO
+=head1 COPYRIGHT
 
-TBA
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+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
+L<https://www.openssl.org/source/license.html>.
+
+=cut