From 58e3457a82e8940ff36b36949f9c7a60e7614b2c Mon Sep 17 00:00:00 2001 From: Emilia Kasper Date: Thu, 17 Sep 2015 13:50:34 +0200 Subject: [PATCH] BUF_strdup and friends: update docs Reviewed-by: Matt Caswell --- doc/crypto/buffer.pod | 49 ++++++++++++++++++++++--------------------- 1 file 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 is the current size of the buffer in bytes, B 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. 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 bytes of B. =head1 RETURN VALUES -- 2.34.1