[BACK]Return to mandoc_malloc.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

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