131567Ssef=pod 231899Ssef 331899Ssef=head1 NAME 431899Ssef 531899SsefBIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, 631899SsefBIO_get_mem_ptr, BIO_new_mem_buf - memory BIO 731899Ssef 831899Ssef=head1 SYNOPSIS 931899Ssef 1031899Ssef #include <openssl/bio.h> 1131899Ssef 1231899Ssef BIO_METHOD * BIO_s_mem(void); 1331899Ssef 1431899Ssef BIO_set_mem_eof_return(BIO *b,int v) 1531899Ssef long BIO_get_mem_data(BIO *b, char **pp) 1631899Ssef BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c) 1731899Ssef BIO_get_mem_ptr(BIO *b,BUF_MEM **pp) 1831899Ssef 1931899Ssef BIO *BIO_new_mem_buf(const void *buf, int len); 2031899Ssef 2131899Ssef=head1 DESCRIPTION 2231899Ssef 2331899SsefBIO_s_mem() return the memory BIO method function. 2431899Ssef 2531899SsefA memory BIO is a source/sink BIO which uses memory for its I/O. Data 2631899Ssefwritten to a memory BIO is stored in a BUF_MEM structure which is extended 2731899Ssefas appropriate to accommodate the stored data. 2831899Ssef 2931899SsefAny data written to a memory BIO can be recalled by reading from it. 3031899SsefUnless the memory BIO is read only any data read from it is deleted from 3131899Ssefthe BIO. 3232275Scharnier 3332275ScharnierMemory BIOs support BIO_gets() and BIO_puts(). 3450477Speter 3532275ScharnierIf the BIO_CLOSE flag is set when a memory BIO is freed then the underlying 3632275ScharnierBUF_MEM structure is also freed. 3731899Ssef 3831567SsefCalling BIO_reset() on a read write memory BIO clears any data in it. On a 3931567Ssefread only BIO it restores the BIO to its original state and the read only 4031567Ssefdata can be read again. 4131567Ssef 4231567SsefBIO_eof() is true if no data is in the BIO. 4385301Sdes 4485301SdesBIO_ctrl_pending() returns the number of bytes currently stored. 4585301Sdes 46104581SmikeBIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is 4785301Sdesempty. If the B<v> is zero then an empty memory BIO will return EOF (that is 4832275Scharnierit will return zero and BIO_should_retry(b) will be false. If B<v> is non 4932275Scharnierzero then it will return B<v> when it is empty and it will set the read retry 5032275Scharnierflag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal 5132275Scharnierpositive return value B<v> should be set to a negative value, typically -1. 5231567Ssef 5331567SsefBIO_get_mem_data() sets *B<pp> to a pointer to the start of the memory BIOs data 5431567Ssefand returns the total amount of data available. It is implemented as a macro. 55101423Smdodd 5631579SpeterBIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the 5731567Ssefclose flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. 58101282SmdoddIt is a macro. 5987703Smarkm 6031567SsefBIO_get_mem_ptr() places the underlying BUF_MEM structure in *B<pp>. It is 6131567Ssefa macro. 62101282Smdodd 63101282SmdoddBIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, 6431567Ssefif B<len> is -1 then the B<buf> is assumed to be nul terminated and its 6531567Sseflength is determined by B<strlen>. The BIO is set to a read only state and 6631567Ssefas a result cannot be written to. This is useful when some data needs to be 6731567Ssefmade available from a static area of memory in the form of a BIO. The 68100357Smarkmsupplied data is read directly from the supplied buffer: it is B<not> copied 6932275Scharnierfirst, so the supplied area of memory must be unchanged until the BIO is freed. 7032275Scharnier 7132275Scharnier=head1 NOTES 72101289Smdodd 73101289SmdoddWrites to memory BIOs will always succeed if memory is available: that is 7431567Sseftheir size can grow indefinitely. 7531567Ssef 7631567SsefEvery read from a read write memory BIO will remove the data just read with 7738897Ssefan internal copy operation, if a BIO contains a lot of data and it is 7838897Ssefread in small chunks the operation can be very slow. The use of a read only 7938897Ssefmemory BIO avoids this problem. If the BIO must be read write then adding 8038897Ssefa buffering BIO to the chain will speed up the process. 8131567Ssef 8287703Smarkm=head1 BUGS 83101282Smdodd 84101282SmdoddThere should be an option to set the maximum size of a memory BIO. 8531567Ssef 8639908SsefThere should be a way to "rewind" a read write BIO without destroying 8739908Ssefits contents. 8839908Ssef 8939908SsefThe copying operation should not occur after every small read of a large BIO 9031567Ssefto improve efficiency. 9131580Speter 92101288Smdodd=head1 EXAMPLE 9331567Ssef 9439908SsefCreate a memory BIO and write some data to it: 95101320Sjake 96101320Sjake BIO *mem = BIO_new(BIO_s_mem()); 97101320Sjake BIO_puts(mem, "Hello World\n"); 9831567Ssef 9931567SsefCreate a read only memory BIO: 10031567Ssef 10131567Ssef char data[] = "Hello World"; 10231567Ssef BIO *mem; 10331567Ssef mem = BIO_new_mem_buf(data, -1); 10431567Ssef 10531567SsefExtract the BUF_MEM structure from a memory BIO and then free up the BIO: 10631567Ssef 10731567Ssef BUF_MEM *bptr; 108101282Smdodd BIO_get_mem_ptr(mem, &bptr); 10931567Ssef BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ 11031567Ssef BIO_free(mem); 11187703Smarkm 11231567Ssef 11331567Ssef=head1 SEE ALSO 114101282Smdodd 11531567SsefTBA 11687703Smarkm