Annotation of mandoc/mandoc_malloc.3, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 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$
! 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
CVSweb