Annotation of mandoc/mandoc_malloc.3, Revision 1.3
1.3 ! schwarze 1: .\" $Id: mandoc_malloc.3,v 1.2 2016/07/07 19:19:01 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.3 ! schwarze 17: .Dd $Mdocdate: July 7 2016 $
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 ,
1.3 ! schwarze 25: .Nm mandoc_recallocarray ,
1.1 schwarze 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
1.3 ! schwarze 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
1.1 schwarze 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
1.2 schwarze 76: These functions call the libc functions of the same names, passing
77: through their return values when successful.
1.1 schwarze 78: In case of failure, they do not return, but instead call
1.2 schwarze 79: .Xr err 3 .
80: They can be used both internally by any code in the mandoc libraries
1.1 schwarze 81: and externally by programs using that library, for example
82: .Xr mandoc 1 ,
1.2 schwarze 83: .Xr man 1 ,
1.1 schwarze 84: .Xr apropos 1 ,
1.2 schwarze 85: .Xr makewhatis 8 ,
1.1 schwarze 86: and
1.2 schwarze 87: .Xr man.cgi 8 .
1.1 schwarze 88: .Pp
89: The function
90: .Fn mandoc_malloc
91: allocates one new object, leaving the memory uninitialized.
92: The functions
1.3 ! schwarze 93: .Fn mandoc_realloc ,
! 94: .Fn mandoc_reallocarray ,
1.1 schwarze 95: and
1.3 ! schwarze 96: .Fn mandoc_recallocarray
1.1 schwarze 97: change the size of an existing object or array, possibly moving it.
98: When shrinking the size, existing data is truncated; when growing,
1.3 ! schwarze 99: only
! 100: .Fn mandoc_recallocarray
! 101: initializes the new elements to zero.
1.1 schwarze 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
1.3 ! schwarze 113: .Fa oldnmemb
! 114: is the number of objects in the array before the call.
! 115: The argument
1.1 schwarze 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 ,
1.2 schwarze 161: .Xr err 3 ,
1.1 schwarze 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
1.3 ! schwarze 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.
1.1 schwarze 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
1.3 ! schwarze 203: since 1.12.4,
1.1 schwarze 204: .Fn mandoc_reallocarray
1.3 ! schwarze 205: since 1.13.0, and
! 206: .Fn mandoc_recallocarray
! 207: since 1.14.2.
1.1 schwarze 208: .Sh AUTHORS
209: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
210: .An Ingo Schwarze Aq Mt schwarze@openbsd.org
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandoc_malloc.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc