Write X509_dup, PEM_read, etc.

[openssl.git] / doc / crypto / buffer.pod

diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod
index 1a02f9754ffdb5f61fdf77aa7ae347f4b184b214..16fe3daa844c23df8423304529c3825a447a19aa 100644 (file)
--- a/doc/crypto/buffer.pod
+++ b/doc/crypto/buffer.pod
@@ -2,8 +2,10 @@
 
 =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
+
+standard C library equivalents
 
 =head1 SYNOPSIS
 
@@ -11,32 +13,25 @@ character arrays structure
 
  BUF_MEM *BUF_MEM_new(void);
 
- void  BUF_MEM_free(BUF_MEM *a);
+ #define BUF_MEM_FLAG_SECURE
+
+ BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
 
- int   BUF_MEM_grow(BUF_MEM *str, int len);
+ void   BUF_MEM_free(BUF_MEM *a);
 
- char *        BUF_strdup(const char *str);
+ int    BUF_MEM_grow(BUF_MEM *str, int len);
 
 =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_new_ex() allocates a buffer with the specified flags.
+The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer
+should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>.
+
 BUF_MEM_free() frees up an already existing buffer. The data is zeroed
 before freeing up in case the buffer contains sensitive data.
 
@@ -44,15 +39,6 @@ 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.
@@ -63,11 +49,20 @@ BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>).
 
 =head1 SEE ALSO
 
-L<bio(3)|bio(3)>
+L<bio(3)>,
+L<CRYPTO_secure_malloc(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 added in SSLeay 0.8.
+BUF_MEM_new_ex() was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
 
 =cut