BUF_strdup and friends: update docs

=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

 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.

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