From d37438c4870726f59219d0e999cc98a910622036 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sun, 24 May 2015 15:44:52 +0000 Subject: [PATCH] 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. --- lib/libcrypto/man/BUF_MEM_new.3 | 107 ++++++++++++++++++++++ lib/libcrypto/man/Makefile | 4 +- lib/libssl/src/doc/crypto/BUF_MEM_new.pod | 72 --------------- 3 files changed, 109 insertions(+), 74 deletions(-) create mode 100644 lib/libcrypto/man/BUF_MEM_new.3 delete mode 100644 lib/libssl/src/doc/crypto/BUF_MEM_new.pod diff --git a/lib/libcrypto/man/BUF_MEM_new.3 b/lib/libcrypto/man/BUF_MEM_new.3 new file mode 100644 index 00000000000..a423d4e0bc9 --- /dev/null +++ b/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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index bce02f647f4..872391db3ef 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 # 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 \ diff --git a/lib/libssl/src/doc/crypto/BUF_MEM_new.pod b/lib/libssl/src/doc/crypto/BUF_MEM_new.pod deleted file mode 100644 index 28057558692..00000000000 --- a/lib/libssl/src/doc/crypto/BUF_MEM_new.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple -character arrays structure - -=head1 SYNOPSIS - - #include - - BUF_MEM *BUF_MEM_new(void); - - void BUF_MEM_free(BUF_MEM *a); - - int BUF_MEM_grow(BUF_MEM *str, size_t len); - - char * BUF_strdup(const char *str); - -=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 - { - size_t length; /* current number of bytes */ - char *data; - size_t max; /* size of buffer */ - } BUF_MEM; - -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. - -BUF_MEM_new() allocates a new buffer of zero size. - -BUF_MEM_free() frees up an already existing buffer. The data is zeroed -before freeing up in case the buffer contains sensitive data. - -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 system strdup() -function, BUF_strdup() will accept a NULL argument and will return NULL in -that case. Its use in new programes is discouraged. - -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. - -BUF_MEM_free() has no return value. - -BUF_MEM_grow() returns zero on error or the new size (i.e. B). - -=head1 SEE ALSO - -L - -=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. - -=cut -- 2.20.1