diff options
author | Ulf Möller <ulf@openssl.org> | 2000-01-30 22:16:47 +0000 |
---|---|---|
committer | Ulf Möller <ulf@openssl.org> | 2000-01-30 22:16:47 +0000 |
commit | 74235cc9ec3123ee7f51211ea054632ca0cf7c91 (patch) | |
tree | 6a7ca2fe3814d00dd127a3170e40242ac7364e69 /doc/crypto/buffer.pod | |
parent | da0fc5bf0f25ee488838845a66f47b444f8c7b70 (diff) |
Update docs: corrections, turn buffer docs into manpage, fold SHA1
pages into one for improved readability, add lhash manpage
Diffstat (limited to 'doc/crypto/buffer.pod')
-rw-r--r-- | doc/crypto/buffer.pod | 73 |
1 files changed, 73 insertions, 0 deletions
diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod new file mode 100644 index 0000000000..dda8e7b508 --- /dev/null +++ b/doc/crypto/buffer.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - Simple +character arrays structure + +=head1 SYNOPSIS + + #include <openssl/buffer.h> + + BUF_MEM *BUF_MEM_new(void); + + void BUF_MEM_free(BUF_MEM *a); + + int BUF_MEM_grow(BUF_MEM *str, int len); + + char * BUF_strdup(const char *str); + +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. + +The library uses the BUF_MEM structure defined in buffer.h: + + typedef struct buf_mem_st + { + int length; /* current number of bytes */ + char *data; + int max; /* size of buffer */ + } BUF_MEM; + +B<length> is the current size of the buffer in bytes, B<max> is the amount of +memory allocated to the buffer. There are three functions which handle these +and one "miscellaneous" function. + +BUF_MEM_new() allocates a new buffer of zero size. + +BUF_MEM_free() frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. + +BUF_MEM_grow() changes the size of an already existing buffer to +B<len>. Any data already in the buffer is preserved if it increases in +size. + +BUF_strdup() copies a null terminated string into a block of allocated +memory and returns a pointer to the allocated block. +Unlike the standard C library strdup() this function uses Malloc() and so +should be used in preference to the standard library strdup() because it can +be used for memory leak checking or replacing the malloc() function. + +The memory allocated from BUF_strdup() should be freed up using the Free() +function. + +=head1 RETURN VALUES + +BUF_MEM_new() returns the buffer or NULL on error. + +BUF_MEM_free() has no return value. + +BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). + +=head1 SEE ALSO + +L<bio(3)|bio(3)> + +=head1 HISTORY + +BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all +versions of SSLeay and OpenSSL. BUF_strdup() was addded in SSLeay 0.8. + +=cut |