kernel - Deal with lost IPIs (VM related)
[dragonfly.git] / contrib / mdocml / mandoc_malloc.3
blobc16798424af6daa87ab25fe11941876d44308d9f
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.
112 The functions
113 .Fn mandoc_strdup
115 .Fn mandoc_strndup
116 copy a string into newly allocated memory.
118 .Fn mandoc_strdup ,
119 the string pointed to by
120 .Fa s
121 needs to be NUL-terminated.
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.
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.
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 ,
161 .Fn calloc
162 are required by
163 .St -ansiC .
164 The functions
165 .Fn strdup
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.
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 ,
186 .Fn mandoc_strdup
187 have been available since mandoc 1.9.12,
188 .Fn mandoc_strndup
189 since 1.11.5,
191 .Fn mandoc_asprintf
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