168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, 668651SkrisBIO_get_mem_ptr, BIO_new_mem_buf - memory BIO 768651Skris 868651Skris=head1 SYNOPSIS 968651Skris 1068651Skris #include <openssl/bio.h> 1168651Skris 1268651Skris BIO_METHOD * BIO_s_mem(void); 1368651Skris 1468651Skris BIO_set_mem_eof_return(BIO *b,int v) 1568651Skris long BIO_get_mem_data(BIO *b, char **pp) 1668651Skris BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c) 1768651Skris BIO_get_mem_ptr(BIO *b,BUF_MEM **pp) 1868651Skris 1968651Skris BIO *BIO_new_mem_buf(void *buf, int len); 2068651Skris 2168651Skris=head1 DESCRIPTION 2268651Skris 2368651SkrisBIO_s_mem() return the memory BIO method function. 2468651Skris 2568651SkrisA memory BIO is a source/sink BIO which uses memory for its I/O. Data 2668651Skriswritten to a memory BIO is stored in a BUF_MEM structure which is extended 2768651Skrisas appropriate to accommodate the stored data. 2868651Skris 2968651SkrisAny data written to a memory BIO can be recalled by reading from it. 3068651SkrisUnless the memory BIO is read only any data read from it is deleted from 3168651Skristhe BIO. 3268651Skris 3368651SkrisMemory BIOs support BIO_gets() and BIO_puts(). 3468651Skris 3568651SkrisIf the BIO_CLOSE flag is set when a memory BIO is freed then the underlying 3668651SkrisBUF_MEM structure is also freed. 3768651Skris 3868651SkrisCalling BIO_reset() on a read write memory BIO clears any data in it. On a 3968651Skrisread only BIO it restores the BIO to its original state and the read only 4068651Skrisdata can be read again. 4168651Skris 4268651SkrisBIO_eof() is true if no data is in the BIO. 4368651Skris 4468651SkrisBIO_ctrl_pending() returns the number of bytes currently stored. 4568651Skris 4668651SkrisBIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is 4768651Skrisempty. If the B<v> is zero then an empty memory BIO will return EOF (that is 4868651Skrisit will return zero and BIO_should_retry(b) will be false. If B<v> is non 4968651Skriszero then it will return B<v> when it is empty and it will set the read retry 5068651Skrisflag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal 5168651Skrispositive return value B<v> should be set to a negative value, typically -1. 5268651Skris 5368651SkrisBIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data 5468651Skrisand returns the total amount of data available. It is implemented as a macro. 5568651Skris 5668651SkrisBIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the 5768651Skrisclose flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. 5868651SkrisIt is a macro. 5968651Skris 6068651SkrisBIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is 6168651Skrisa macro. 6268651Skris 6368651SkrisBIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, 6468651Skrisif B<len> is -1 then the B<buf> is assumed to be null terminated and its 6568651Skrislength is determined by B<strlen>. The BIO is set to a read only state and 6668651Skrisas a result cannot be written to. This is useful when some data needs to be 6768651Skrismade available from a static area of memory in the form of a BIO. The 6868651Skrissupplied data is read directly from the supplied buffer: it is B<not> copied 6968651Skrisfirst, so the supplied area of memory must be unchanged until the BIO is freed. 7068651Skris 7168651Skris=head1 NOTES 7268651Skris 7368651SkrisWrites to memory BIOs will always succeed if memory is available: that is 7468651Skristheir size can grow indefinitely. 7568651Skris 7668651SkrisEvery read from a read write memory BIO will remove the data just read with 77238405Sjkiman internal copy operation, if a BIO contains a lot of data and it is 7868651Skrisread in small chunks the operation can be very slow. The use of a read only 7968651Skrismemory BIO avoids this problem. If the BIO must be read write then adding 8068651Skrisa buffering BIO to the chain will speed up the process. 8168651Skris 8268651Skris=head1 BUGS 8368651Skris 8468651SkrisThere should be an option to set the maximum size of a memory BIO. 8568651Skris 8668651SkrisThere should be a way to "rewind" a read write BIO without destroying 8768651Skrisits contents. 8868651Skris 8968651SkrisThe copying operation should not occur after every small read of a large BIO 9068651Skristo improve efficiency. 9168651Skris 9268651Skris=head1 EXAMPLE 9368651Skris 9468651SkrisCreate a memory BIO and write some data to it: 9568651Skris 9668651Skris BIO *mem = BIO_new(BIO_s_mem()); 9768651Skris BIO_puts(mem, "Hello World\n"); 9868651Skris 9968651SkrisCreate a read only memory BIO: 10068651Skris 10168651Skris char data[] = "Hello World"; 10268651Skris BIO *mem; 10368651Skris mem = BIO_new_mem_buf(data, -1); 10468651Skris 10568651SkrisExtract the BUF_MEM structure from a memory BIO and then free up the BIO: 10668651Skris 10768651Skris BUF_MEM *bptr; 10868651Skris BIO_get_mem_ptr(mem, &bptr); 10968651Skris BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ 11068651Skris BIO_free(mem); 11168651Skris 11268651Skris 11368651Skris=head1 SEE ALSO 11468651Skris 11568651SkrisTBA 116