Annotation of mandoc/mandoc_malloc.3, Revision 1.2
1.2 ! schwarze 1: .\" $Id: mandoc_malloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $
1.1 schwarze 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: .\"
1.2 ! schwarze 17: .Dd $Mdocdate: August 5 2014 $
1.1 schwarze 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
1.2 ! schwarze 68: These functions call the libc functions of the same names, passing
! 69: through their return values when successful.
1.1 schwarze 70: In case of failure, they do not return, but instead call
1.2 ! schwarze 71: .Xr err 3 .
! 72: They can be used both internally by any code in the mandoc libraries
1.1 schwarze 73: and externally by programs using that library, for example
74: .Xr mandoc 1 ,
1.2 ! schwarze 75: .Xr man 1 ,
1.1 schwarze 76: .Xr apropos 1 ,
1.2 ! schwarze 77: .Xr makewhatis 8 ,
1.1 schwarze 78: and
1.2 ! schwarze 79: .Xr man.cgi 8 .
1.1 schwarze 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 ,
1.2 ! schwarze 147: .Xr err 3 ,
1.1 schwarze 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
CVSweb