From 4ecb35c8702ae9bf7de323d549724d7f1d436a06 Mon Sep 17 00:00:00 2001
From: schwarze <>
Date: Sun, 24 May 2015 15:44:52 +0000
Subject: Maximilian dot Fillinger at uni-duesseldorf dot de starts helping
 with the pod2mdoc(1)-based conversion of LibreSSL crypto manuals from
 perlpod(1) to mdoc(7). Here comes the first file, slightly tweaked by me.

---
 src/lib/libcrypto/man/BUF_MEM_new.3 | 107 ++++++++++++++++++++++++++++++++++++
 src/lib/libcrypto/man/Makefile      |   4 +-
 2 files changed, 109 insertions(+), 2 deletions(-)
 create mode 100644 src/lib/libcrypto/man/BUF_MEM_new.3

(limited to 'src/lib/libcrypto')

diff --git a/src/lib/libcrypto/man/BUF_MEM_new.3 b/src/lib/libcrypto/man/BUF_MEM_new.3
new file mode 100644
index 0000000000..a423d4e0bc
--- /dev/null
+++ b/src/lib/libcrypto/man/BUF_MEM_new.3
@@ -0,0 +1,107 @@
+.Dd $Mdocdate: May 24 2015 $
+.Dt BUF_MEM_NEW 3
+.Os
+.Sh NAME
+.Nm BUF_MEM_new ,
+.Nm BUF_MEM_free ,
+.Nm BUF_MEM_grow ,
+.Nm BUF_strdup
+.Nd simple character arrays structure
+.Sh SYNOPSIS
+.In openssl/buffer.h
+.Ft BUF_MEM *
+.Fo BUF_MEM_new
+.Fa void
+.Fc
+.Ft void
+.Fo BUF_MEM_free
+.Fa "BUF_MEM *a"
+.Fc
+.Ft int
+.Fo BUF_MEM_grow
+.Fa "BUF_MEM *str"
+.Fa "size_t len"
+.Fc
+.Ft char *
+.Fo BUF_strdup
+.Fa "const char *str"
+.Fc
+.Sh DESCRIPTION
+The buffer library handles simple character arrays.
+Buffers are used for various purposes in the library, most notably
+memory BIOs.
+.Pp
+The library uses the
+.Vt BUF_MEM
+structure defined in buffer.h:
+.Bd -literal
+typedef struct buf_mem_st
+{
+	size_t length;	/* current number of bytes */
+	char *data;
+	size_t max;	/* size of buffer */
+} BUF_MEM;
+.Ed
+.Pp
+.Fa length
+is the current size of the buffer in bytes,
+.Fa max
+is the amount of memory allocated to the buffer.
+There are three functions which handle these and one
+.Dq miscellaneous
+function.
+.Pp
+.Fn BUF_MEM_new
+allocates a new buffer of zero size.
+.Pp
+.Fn BUF_MEM_free
+frees up an already existing buffer.
+The data is zeroed before freeing up in case the buffer contains
+sensitive data.
+.Pp
+.Fn BUF_MEM_grow
+changes the size of an already existing buffer to
+.Fa len .
+Any data already in the buffer is preserved if it increases in size.
+.Pp
+.Fn BUF_strdup
+copies a NUL terminated string into a block of allocated memory and
+returns a pointer to the allocated block.
+Unlike the system
+.Xr strdup 3
+function,
+.Fn BUF_strdup
+will accept a
+.Dv NULL
+argument and will return
+.Dv NULL
+in that case.
+Its use in new programes is discouraged.
+.Pp
+The memory allocated from
+.Fn BUF_strdup
+should be freed up using the
+.Xr free 3
+function.
+.Sh RETURN VALUES
+.Fn BUF_MEM_new
+returns the buffer or
+.Dv NULL
+on error.
+.Pp
+.Fn BUF_MEM_free
+returns no value.
+.Pp
+.Fn BUF_MEM_grow
+returns zero on error or the new size (i.e.
+.Fa len Ns ).
+.Sh SEE ALSO
+.Xr bio 3
+.Sh HISTORY
+.Fn BUF_MEM_new ,
+.Fn BUF_MEM_free
+and
+.Fn BUF_MEM_grow
+are available in all versions of SSLeay and OpenSSL.
+.Fn BUF_strdup
+was added in SSLeay 0.8.
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index bce02f647f..872391db3e 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.19 2015/02/23 17:43:24 schwarze Exp $
+# $OpenBSD: Makefile,v 1.20 2015/05/24 15:44:52 schwarze Exp $
 
 .include <bsd.own.mk>		# for NOMAN
 
@@ -51,9 +51,9 @@ MAN=	\
 	BN_set_bit.3 \
 	BN_swap.3 \
 	BN_zero.3 \
+	BUF_MEM_new.3 \
 
 GENMAN= \
-	BUF_MEM_new.3 \
 	CONF_modules_free.3 \
 	CONF_modules_load_file.3 \
 	CRYPTO_set_ex_data.3 \
-- 
cgit v1.2.3-55-g6feb