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

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