diff options
author | Emilia Kasper <emilia@openssl.org> | 2015-09-17 13:50:34 +0200 |
---|---|---|
committer | Emilia Kasper <emilia@openssl.org> | 2015-09-22 19:51:53 +0200 |
commit | 58e3457a82e8940ff36b36949f9c7a60e7614b2c (patch) | |
tree | 6574f87f0dbae0172274a8ad573b0dfb72b9d5a5 /doc | |
parent | de8883e11befde31d9b6cfbbd1fc017c365e0bbf (diff) |
BUF_strdup and friends: update docs
Reviewed-by: Matt Caswell <matt@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/buffer.pod | 49 |
1 files changed, 25 insertions, 24 deletions
diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod index c56cc89ab6..d4cb8a8cbd 100644 --- a/doc/crypto/buffer.pod +++ b/doc/crypto/buffer.pod @@ -2,8 +2,11 @@ =head1 NAME -BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple -character arrays structure +BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow - simple +character array structure + +BUF_strdup, BUF_strndup, BUF_memdup, BUF_strlcpy, BUF_strlcat - +standard C library equivalents =head1 SYNOPSIS @@ -13,31 +16,26 @@ character arrays structure #define BUF_MEM_FLAG_SECURE - BUF_MEM * BUF_MEM_new_ex(unsigned long flags); + BUF_MEM *BUF_MEM_new_ex(unsigned long flags); void BUF_MEM_free(BUF_MEM *a); int BUF_MEM_grow(BUF_MEM *str, int len); - char * BUF_strdup(const char *str); + char *BUF_strdup(const char *str); -=head1 DESCRIPTION + char *BUF_strndup(const char *str, size_t siz); -The buffer library handles simple character arrays. Buffers are used for -various purposes in the library, most notably memory BIOs. + void *BUF_memdup(const void *data, size_t siz); -The library uses the BUF_MEM structure defined in buffer.h: + size_t BUF_strlcpy(char *dst, const char *src, size_t size); - typedef struct buf_mem_st - { - int length; /* current number of bytes */ - char *data; - int max; /* size of buffer */ - } BUF_MEM; + size_t BUF_strlcat(char *dst, const char *src, size_t size); -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. +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. BUF_MEM_new() allocates a new buffer of zero size. @@ -52,14 +50,17 @@ 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 OPENSSL_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. +BUF_strdup(), BUF_strndup(), BUF_memdup(), BUF_strlcpy() and +BUF_strlcat() are equivalents of the standard C library functions. The +dup() functions use OPENSSL_malloc() underneath and so should be used +in preference to the standard library for memory leak checking or +replacing the malloc() function. + +Memory allocated from these functions should be freed up using the +OPENSSL_free() function. -The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() -function. +BUF_strndup makes the explicit guarantee that it will never read past +the first B<siz> bytes of B<str>. =head1 RETURN VALUES |