contrib/mandoc/mandoc_malloc.3

   1 .\"     $Id: mandoc_malloc.3,v 1.3 2021/09/17 18:50:21 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: September 17 2021 $
  18 .Dt MANDOC_MALLOC 3
  19 .Os
  20 .Sh NAME
  21 .Nm mandoc_malloc ,
  22 .Nm mandoc_realloc ,
  23 .Nm mandoc_reallocarray ,
  24 .Nm mandoc_calloc ,
  25 .Nm mandoc_recallocarray ,
  26 .Nm mandoc_strdup ,
  27 .Nm mandoc_strndup ,
  28 .Nm mandoc_asprintf
  29 .Nd memory allocation function wrappers used in the mandoc library
  30 .Sh SYNOPSIS
  31 .In sys/types.h
  32 .In mandoc_aux.h
  33 .Ft "void *"
  34 .Fo mandoc_malloc
  35 .Fa "size_t size"
  36 .Fc
  37 .Ft "void *"
  38 .Fo mandoc_realloc
  39 .Fa "void *ptr"
  40 .Fa "size_t size"
  41 .Fc
  42 .Ft "void *"
  43 .Fo mandoc_reallocarray
  44 .Fa "void *ptr"
  45 .Fa "size_t nmemb"
  46 .Fa "size_t size"
  47 .Fc
  48 .Ft "void *"
  49 .Fo mandoc_calloc
  50 .Fa "size_t nmemb"
  51 .Fa "size_t size"
  52 .Fc
  53 .Ft "void *"
  54 .Fo mandoc_recallocarray
  55 .Fa "void *ptr"
  56 .Fa "size_t oldnmemb"
  57 .Fa "size_t nmemb"
  58 .Fa "size_t size"
  59 .Fc
  60 .Ft "char *"
  61 .Fo mandoc_strdup
  62 .Fa "const char *s"
  63 .Fc
  64 .Ft "char *"
  65 .Fo mandoc_strndup
  66 .Fa "const char *s"
  67 .Fa "size_t maxlen"
  68 .Fc
  69 .Ft int
  70 .Fo mandoc_asprintf
  71 .Fa "char **ret"
  72 .Fa "const char *format"
  73 .Fa "..."
  74 .Fc
  75 .Sh DESCRIPTION
  76 These functions call the libc functions of the same names, passing
  77 through their return values when successful.
  78 In case of failure, they do not return, but instead call
  79 .Xr err 3 .
  80 They can be used both internally by any code in the mandoc libraries
  81 and externally by programs using that library, for example
  82 .Xr mandoc 1 ,
  83 .Xr man 1 ,
  84 .Xr apropos 1 ,
  85 .Xr makewhatis 8 ,
  86 and
  87 .Xr man.cgi 8 .
  88 .Pp
  89 The function
  90 .Fn mandoc_malloc
  91 allocates one new object, leaving the memory uninitialized.
  92 The functions
  93 .Fn mandoc_realloc ,
  94 .Fn mandoc_reallocarray ,
  95 and
  96 .Fn mandoc_recallocarray
  97 change the size of an existing object or array, possibly moving it.
  98 When shrinking the size, existing data is truncated; when growing,
  99 only
 100 .Fn mandoc_recallocarray
 101 initializes the new elements to zero.
 102 The function
 103 .Fn mandoc_calloc
 104 allocates a new array, initializing it to zero.
 105 .Pp
 106 The argument
 107 .Fa size
 108 is the size of each object.
 109 The argument
 110 .Fa nmemb
 111 is the new number of objects in the array.
 112 The argument
 113 .Fa oldnmemb
 114 is the number of objects in the array before the call.
 115 The argument
 116 .Fa ptr
 117 is a pointer to the existing object or array to be resized; if it is
 118 .Dv NULL ,
 119 a new object or array is allocated.
 120 .Pp
 121 The functions
 122 .Fn mandoc_strdup
 123 and
 124 .Fn mandoc_strndup
 125 copy a string into newly allocated memory.
 126 For
 127 .Fn mandoc_strdup ,
 128 the string pointed to by
 129 .Fa s
 130 needs to be NUL-terminated.
 131 For
 132 .Fn mandoc_strndup ,
 133 at most
 134 .Fa maxlen
 135 bytes are copied.
 136 The function
 137 .Fn mandoc_asprintf
 138 writes output formatted according to
 139 .Fa format
 140 into newly allocated memory and returns a pointer to the result in
 141 .Fa ret .
 142 For all three string functions, the result is always NUL-terminated.
 143 .Pp
 144 When the objects and strings are no longer needed,
 145 the pointers returned by these functions can be passed to
 146 .Xr free 3 .
 147 .Sh RETURN VALUES
 148 The function
 149 .Fn mandoc_asprintf
 150 always returns the number of characters written, excluding the
 151 final NUL byte.
 152 It never returns -1.
 153 .Pp
 154 The other functions always return a valid pointer; they never return
 155 .Dv NULL .
 156 .Sh FILES
 157 These functions are implemented in
 158 .Pa mandoc_aux.c .
 159 .Sh SEE ALSO
 160 .Xr asprintf 3 ,
 161 .Xr err 3 ,
 162 .Xr malloc 3 ,
 163 .Xr strdup 3
 164 .Sh STANDARDS
 165 The functions
 166 .Fn malloc ,
 167 .Fn realloc ,
 168 and
 169 .Fn calloc
 170 are required by
 171 .St -ansiC .
 172 The functions
 173 .Fn strdup
 174 and
 175 .Fn strndup
 176 are required by
 177 .St -p1003.1-2008 .
 178 The function
 179 .Fn asprintf
 180 is a widespread extension that first appeared in the GNU C library.
 181 .Pp
 182 The function
 183 .Fn reallocarray
 184 is an extension that first appeared in
 185 .Ox 5.6 ,
 186 and
 187 .Fn recallocarray
 188 in
 189 .Ox 6.1 .
 190 If these two are not provided by the operating system,
 191 the mandoc build system uses bundled portable implementations.
 192 .Sh HISTORY
 193 The functions
 194 .Fn mandoc_malloc ,
 195 .Fn mandoc_realloc ,
 196 .Fn mandoc_calloc ,
 197 and
 198 .Fn mandoc_strdup
 199 have been available since mandoc 1.9.12,
 200 .Fn mandoc_strndup
 201 since 1.11.5,
 202 .Fn mandoc_asprintf
 203 since 1.12.4,
 204 .Fn mandoc_reallocarray
 205 since 1.13.0, and
 206 .Fn mandoc_recallocarray
 207 since 1.14.2.
 208 .Sh AUTHORS
 209 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 210 .An Ingo Schwarze Aq Mt schwarze@openbsd.org