X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FBIO_s_mem.pod;h=56d10bd8dd08bae2766d88f52d61bf450ad5e49f;hp=0c5f58ed1bcce17883c95da4b60537a3bad3de79;hb=5e0dc5c9992ad53d12b07eb5d12a0e23dd5be670;hpb=8eec1389fb8e649fe971046b4108a66544955017 diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod index 0c5f58ed1b..56d10bd8dd 100644 --- a/doc/crypto/BIO_s_mem.pod +++ b/doc/crypto/BIO_s_mem.pod @@ -9,23 +9,27 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO #include - 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) 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(void *buf, int len); + 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 +39,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. @@ -61,7 +66,7 @@ BIO_get_mem_ptr() places the underlying BUF_MEM structure in B. It is a macro. BIO_new_mem_buf() creates a memory BIO using B bytes of data at B, -if B is -1 then the B is assumed to be null terminated and its +if B is -1 then the B is assumed to be nul terminated and its length is determined by 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 @@ -74,29 +79,24 @@ Writes to memory BIOs will always succeed if memory is available: that is their size can grow indefinitely. Every read from a read write memory BIO will remove the data just read with -an internal copy operation, if a BIO contains a lots of data and it is +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. +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 efficieny. - -There shoy - =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: @@ -110,8 +110,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 + +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. -TBA +=cut