1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple 6*2175Sjp161948character arrays structure 7*2175Sjp161948 8*2175Sjp161948=head1 SYNOPSIS 9*2175Sjp161948 10*2175Sjp161948 #include <openssl/buffer.h> 11*2175Sjp161948 12*2175Sjp161948 BUF_MEM *BUF_MEM_new(void); 13*2175Sjp161948 14*2175Sjp161948 void BUF_MEM_free(BUF_MEM *a); 15*2175Sjp161948 16*2175Sjp161948 int BUF_MEM_grow(BUF_MEM *str, int len); 17*2175Sjp161948 18*2175Sjp161948 char * BUF_strdup(const char *str); 19*2175Sjp161948 20*2175Sjp161948=head1 DESCRIPTION 21*2175Sjp161948 22*2175Sjp161948The buffer library handles simple character arrays. Buffers are used for 23*2175Sjp161948various purposes in the library, most notably memory BIOs. 24*2175Sjp161948 25*2175Sjp161948The library uses the BUF_MEM structure defined in buffer.h: 26*2175Sjp161948 27*2175Sjp161948 typedef struct buf_mem_st 28*2175Sjp161948 { 29*2175Sjp161948 int length; /* current number of bytes */ 30*2175Sjp161948 char *data; 31*2175Sjp161948 int max; /* size of buffer */ 32*2175Sjp161948 } BUF_MEM; 33*2175Sjp161948 34*2175Sjp161948B<length> is the current size of the buffer in bytes, B<max> is the amount of 35*2175Sjp161948memory allocated to the buffer. There are three functions which handle these 36*2175Sjp161948and one "miscellaneous" function. 37*2175Sjp161948 38*2175Sjp161948BUF_MEM_new() allocates a new buffer of zero size. 39*2175Sjp161948 40*2175Sjp161948BUF_MEM_free() frees up an already existing buffer. The data is zeroed 41*2175Sjp161948before freeing up in case the buffer contains sensitive data. 42*2175Sjp161948 43*2175Sjp161948BUF_MEM_grow() changes the size of an already existing buffer to 44*2175Sjp161948B<len>. Any data already in the buffer is preserved if it increases in 45*2175Sjp161948size. 46*2175Sjp161948 47*2175Sjp161948BUF_strdup() copies a null terminated string into a block of allocated 48*2175Sjp161948memory and returns a pointer to the allocated block. 49*2175Sjp161948Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so 50*2175Sjp161948should be used in preference to the standard library strdup() because it can 51*2175Sjp161948be used for memory leak checking or replacing the malloc() function. 52*2175Sjp161948 53*2175Sjp161948The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() 54*2175Sjp161948function. 55*2175Sjp161948 56*2175Sjp161948=head1 RETURN VALUES 57*2175Sjp161948 58*2175Sjp161948BUF_MEM_new() returns the buffer or NULL on error. 59*2175Sjp161948 60*2175Sjp161948BUF_MEM_free() has no return value. 61*2175Sjp161948 62*2175Sjp161948BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). 63*2175Sjp161948 64*2175Sjp161948=head1 SEE ALSO 65*2175Sjp161948 66*2175Sjp161948L<bio(3)|bio(3)> 67*2175Sjp161948 68*2175Sjp161948=head1 HISTORY 69*2175Sjp161948 70*2175Sjp161948BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all 71*2175Sjp161948versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. 72*2175Sjp161948 73*2175Sjp161948=cut 74