From: Emilia Kasper <emilia@openssl.org>
Date: Thu, 17 Sep 2015 11:50:34 +0000 (+0200)
Subject: BUF_strdup and friends: update docs
X-Git-Tag: OpenSSL_1_0_1q~55
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=456b9820ebaa7e9bfec8eec27326478cc0a3b0fa

BUF_strdup and friends: update docs

Reviewed-by: Matt Caswell <matt@openssl.org>
(cherry picked from commit 58e3457a82e8940ff36b36949f9c7a60e7614b2c)
(cherry picked from commit be250ee2d353a9c8ed858bf8ca274d3107ae2f64)
---

diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod
index 781f5b11ee..9d6de53e8e 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
 
@@ -15,25 +18,20 @@ character arrays structure
 
  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.
 
@@ -44,14 +42,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