lib/libcrypto/man/BUF_MEM_new.3

   1 .\"     $OpenBSD: BUF_MEM_new.3,v 1.14 2018/03/23 04:34:23 schwarze Exp $
   2 .\"     OpenSSL doc/crypto/buffer.pod 18edda0f Sep 20 03:28:54 2000 +0000
   3 .\"     not merged: 74924dcb, 58e3457a, 21b0fa91, 7644a9ae
   4 .\"     OpenSSL doc/crypto/BUF_MEM_new.pod 53934822 Jun 9 16:39:19 2016 -0400
   5 .\"     not merged: c952780c, 91da5e77
   6 .\"     OpenSSL doc/man3/BUF_MEM_new.pod 498180de Dec 12 15:35:09 2016 +0300
   7 .\"
   8 .\" This file was written by Ralf S. Engelschall <rse@openssl.org>.
   9 .\" Copyright (c) 1999, 2000, 2016 The OpenSSL Project.  All rights reserved.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\"
  15 .\" 1. Redistributions of source code must retain the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer.
  17 .\"
  18 .\" 2. Redistributions in binary form must reproduce the above copyright
  19 .\"    notice, this list of conditions and the following disclaimer in
  20 .\"    the documentation and/or other materials provided with the
  21 .\"    distribution.
  22 .\"
  23 .\" 3. All advertising materials mentioning features or use of this
  24 .\"    software must display the following acknowledgment:
  25 .\"    "This product includes software developed by the OpenSSL Project
  26 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  27 .\"
  28 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  29 .\"    endorse or promote products derived from this software without
  30 .\"    prior written permission. For written permission, please contact
  31 .\"    openssl-core@openssl.org.
  32 .\"
  33 .\" 5. Products derived from this software may not be called "OpenSSL"
  34 .\"    nor may "OpenSSL" appear in their names without prior written
  35 .\"    permission of the OpenSSL Project.
  36 .\"
  37 .\" 6. Redistributions of any form whatsoever must retain the following
  38 .\"    acknowledgment:
  39 .\"    "This product includes software developed by the OpenSSL Project
  40 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  41 .\"
  42 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  43 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  44 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  45 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  46 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  47 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  48 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  49 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  50 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  51 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  52 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  53 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  54 .\"
  55 .Dd $Mdocdate: March 23 2018 $
  56 .Dt BUF_MEM_NEW 3
  57 .Os
  58 .Sh NAME
  59 .Nm BUF_MEM_new ,
  60 .Nm BUF_MEM_free ,
  61 .Nm BUF_MEM_grow ,
  62 .Nm BUF_MEM_grow_clean ,
  63 .Nm BUF_reverse ,
  64 .Nm BUF_strdup
  65 .Nd simple character arrays structure
  66 .Sh SYNOPSIS
  67 .In openssl/buffer.h
  68 .Ft BUF_MEM *
  69 .Fo BUF_MEM_new
  70 .Fa void
  71 .Fc
  72 .Ft void
  73 .Fo BUF_MEM_free
  74 .Fa "BUF_MEM *a"
  75 .Fc
  76 .Ft int
  77 .Fo BUF_MEM_grow
  78 .Fa "BUF_MEM *str"
  79 .Fa "size_t len"
  80 .Fc
  81 .Ft int
  82 .Fo BUF_MEM_grow_clean
  83 .Fa "BUF_MEM *str"
  84 .Fa "size_t len"
  85 .Fc
  86 .Ft void
  87 .Fo BUF_reverse
  88 .Fa "unsigned char *out"
  89 .Fa "const unsigned char *in"
  90 .Fa "size_t len"
  91 .Fc
  92 .Ft char *
  93 .Fo BUF_strdup
  94 .Fa "const char *str"
  95 .Fc
  96 .Sh DESCRIPTION
  97 The buffer library handles simple character arrays.
  98 Buffers are used for various purposes in the library, most notably
  99 memory BIOs.
 100 .Pp
 101 The library uses the
 102 .Vt BUF_MEM
 103 structure defined in buffer.h:
 104 .Bd -literal
 105 typedef struct buf_mem_st
 106 {
 107         size_t length;  /* current number of bytes */
 108         char *data;
 109         size_t max;     /* size of buffer */
 110 } BUF_MEM;
 111 .Ed
 112 .Pp
 113 .Fa length
 114 is the current size of the buffer in bytes;
 115 .Fa max
 116 is the amount of memory allocated to the buffer.
 117 There are three functions which handle these and one miscellaneous function.
 118 .Pp
 119 .Fn BUF_MEM_new
 120 allocates a new buffer of zero size.
 121 .Pp
 122 .Fn BUF_MEM_free
 123 frees up an already existing buffer.
 124 The data is zeroed before freeing up in case the buffer contains
 125 sensitive data.
 126 If
 127 .Fa a
 128 is a
 129 .Dv NULL
 130 pointer, no action occurs.
 131 .Pp
 132 .Fn BUF_MEM_grow
 133 changes the size of an already existing buffer to
 134 .Fa len .
 135 Any data already in the buffer is preserved if it increases in size.
 136 .Pp
 137 .Fn BUF_MEM_grow_clean
 138 is similar to
 139 .Fn BUF_MEM_grow ,
 140 but it sets any freed or additionally allocated memory to zero.
 141 .Pp
 142 .Fn BUF_reverse
 143 reverses
 144 .Fa len
 145 bytes at
 146 .Fa in
 147 into
 148 .Fa out .
 149 If
 150 .Fa in
 151 is
 152 .Dv NULL ,
 153 .Fa out
 154 is reversed in place.
 155 .Pp
 156 .Fn BUF_strdup
 157 copies a NUL terminated string into a block of allocated memory and
 158 returns a pointer to the allocated block.
 159 Unlike the system
 160 .Xr strdup 3
 161 function,
 162 .Fn BUF_strdup
 163 will accept a
 164 .Dv NULL
 165 argument and will return
 166 .Dv NULL
 167 in that case.
 168 Its use in new programs is discouraged.
 169 .Pp
 170 The memory allocated from
 171 .Fn BUF_strdup
 172 should be freed up using the
 173 .Xr free 3
 174 function.
 175 .Sh RETURN VALUES
 176 .Fn BUF_MEM_new
 177 returns the buffer or
 178 .Dv NULL
 179 on error.
 180 .Pp
 181 .Fn BUF_MEM_grow
 182 and
 183 .Fn BUF_MEM_grow_clean
 184 return zero on error or the new size (i.e.\&
 185 .Fa len ) .
 186 .Sh SEE ALSO
 187 .Xr BIO_new 3
 188 .Sh HISTORY
 189 .Fn BUF_MEM_new ,
 190 .Fn BUF_MEM_free ,
 191 and
 192 .Fn BUF_MEM_grow
 193 appeared before SSLeay 0.8.
 194 .Fn BUF_strdup
 195 first appeared in SSLeay 0.8.
 196 All these functions  have been available since
 197 .Ox 2.4 .
 198 .Pp
 199 .Fn BUF_MEM_grow_clean
 200 first appeared in OpenSSL 0.9.7 and has been available since
 201 .Ox 3.2 .
 202 .Pp
 203 .Fn BUF_reverse
 204 first appeared in OpenSSL 1.0.0 and has been available since
 205 .Ox 4.9 .