contrib/mdocml/mandoc_malloc.3

   1 .\"     $Id: mandoc_malloc.3,v 1.1 2014/08/05 05:48:56 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: August 5 2014 $
  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_strdup ,
  26 .Nm mandoc_strndup ,
  27 .Nm mandoc_asprintf
  28 .Nd memory allocation function wrappers used in the mandoc library
  29 .Sh LIBRARY
  30 .Lb libmandoc
  31 .Sh SYNOPSIS
  32 .In sys/types.h
  33 .In mandoc_aux.h
  34 .Ft "void *"
  35 .Fo mandoc_malloc
  36 .Fa "size_t size"
  37 .Fc
  38 .Ft "void *"
  39 .Fo mandoc_realloc
  40 .Fa "void *ptr"
  41 .Fa "size_t size"
  42 .Fc
  43 .Ft "void *"
  44 .Fo mandoc_reallocarray
  45 .Fa "void *ptr"
  46 .Fa "size_t nmemb"
  47 .Fa "size_t size"
  48 .Fc
  49 .Ft "void *"
  50 .Fo mandoc_calloc
  51 .Fa "size_t nmemb"
  52 .Fa "size_t size"
  53 .Fc
  54 .Ft "char *"
  55 .Fo mandoc_strdup
  56 .Fa "const char *s"
  57 .Fc
  58 .Ft "char *"
  59 .Fo mandoc_strndup
  60 .Fa "const char *s"
  61 .Fa "size_t maxlen"
  62 .Fc
  63 .Ft int
  64 .Fo mandoc_asprintf
  65 .Fa "char **ret"
  66 .Fa "const char *format"
  67 .Fa "..."
  68 .Fc
  69 .Sh DESCRIPTION
  70 These functions call the
  71 .Lb libc
  72 functions of the same names, passing through their return values when
  73 successful.
  74 In case of failure, they do not return, but instead call
  75 .Xr perror 3
  76 and
  77 .Xr exit 3 .
  78 They can be used both internally by any code in the
  79 .Lb libmandoc
  80 and externally by programs using that library, for example
  81 .Xr mandoc 1 ,
  82 .Xr apropos 1 ,
  83 and
  84 .Xr makewhatis 8 .
  85 .Pp
  86 The function
  87 .Fn mandoc_malloc
  88 allocates one new object, leaving the memory uninitialized.
  89 The functions
  90 .Fn mandoc_realloc
  91 and
  92 .Fn mandoc_reallocarray
  93 change the size of an existing object or array, possibly moving it.
  94 When shrinking the size, existing data is truncated; when growing,
  95 the additional memory is not initialized.
  96 The function
  97 .Fn mandoc_calloc
  98 allocates a new array, initializing it to zero.
  99 .Pp
 100 The argument
 101 .Fa size
 102 is the size of each object.
 103 The argument
 104 .Fa nmemb
 105 is the new number of objects in the array.
 106 The argument
 107 .Fa ptr
 108 is a pointer to the existing object or array to be resized; if it is
 109 .Dv NULL ,
 110 a new object or array is allocated.
 111 .Pp
 112 The functions
 113 .Fn mandoc_strdup
 114 and
 115 .Fn mandoc_strndup
 116 copy a string into newly allocated memory.
 117 For
 118 .Fn mandoc_strdup ,
 119 the string pointed to by
 120 .Fa s
 121 needs to be NUL-terminated.
 122 For
 123 .Fn mandoc_strndup ,
 124 at most
 125 .Fa maxlen
 126 bytes are copied.
 127 The function
 128 .Fn mandoc_asprintf
 129 writes output formatted according to
 130 .Fa format
 131 into newly allocated memory and returns a pointer to the result in
 132 .Fa ret .
 133 For all three string functions, the result is always NUL-terminated.
 134 .Pp
 135 When the objects and strings are no longer needed,
 136 the pointers returned by these functions can be passed to
 137 .Xr free 3 .
 138 .Sh RETURN VALUES
 139 The function
 140 .Fn mandoc_asprintf
 141 always returns the number of characters written, excluding the
 142 final NUL byte.
 143 It never returns -1.
 144 .Pp
 145 The other functions always return a valid pointer; they never return
 146 .Dv NULL .
 147 .Sh FILES
 148 These functions are implemented in
 149 .Pa mandoc_aux.c .
 150 .Sh SEE ALSO
 151 .Xr asprintf 3 ,
 152 .Xr exit 3 ,
 153 .Xr malloc 3 ,
 154 .Xr perror 3 ,
 155 .Xr strdup 3
 156 .Sh STANDARDS
 157 The functions
 158 .Fn malloc ,
 159 .Fn realloc ,
 160 and
 161 .Fn calloc
 162 are required by
 163 .St -ansiC .
 164 The functions
 165 .Fn strdup
 166 and
 167 .Fn strndup
 168 are required by
 169 .St -p1003.1-2008 .
 170 The function
 171 .Fn asprintf
 172 is a widespread extension that first appeared in the GNU C library.
 173 .Pp
 174 The function
 175 .Fn reallocarray
 176 is an extension that first appeared in
 177 .Ox 5.6 .
 178 If it is not provided by the operating system, the mandoc build system
 179 uses a bundled portable implementation.
 180 .Sh HISTORY
 181 The functions
 182 .Fn mandoc_malloc ,
 183 .Fn mandoc_realloc ,
 184 .Fn mandoc_calloc ,
 185 and
 186 .Fn mandoc_strdup
 187 have been available since mandoc 1.9.12,
 188 .Fn mandoc_strndup
 189 since 1.11.5,
 190 and
 191 .Fn mandoc_asprintf
 192 and
 193 .Fn mandoc_reallocarray
 194 since 1.12.4 and 1.13.0.
 195 .Sh AUTHORS
 196 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 197 .An Ingo Schwarze Aq Mt schwarze@openbsd.org