contrib/mandoc/mandoc_malloc.3

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