Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MANDOC_MALLOC(3)	 BSD Library Functions Manual	      MANDOC_MALLOC(3)

NAME
     mandoc_malloc, mandoc_realloc, mandoc_reallocarray, mandoc_calloc,
     mandoc_strdup, mandoc_strndup, mandoc_asprintf -- memory allocation func-
     tion wrappers used	in the mandoc library

SYNOPSIS
     #include <sys/types.h>
     #include <mandoc_aux.h>

     void *
     mandoc_malloc(size_t size);

     void *
     mandoc_realloc(void *ptr, size_t size);

     void *
     mandoc_reallocarray(void *ptr, size_t nmemb, size_t size);

     void *
     mandoc_calloc(size_t nmemb, size_t	size);

     char *
     mandoc_strdup(const char *s);

     char *
     mandoc_strndup(const char *s, size_t maxlen);

     int
     mandoc_asprintf(char **ret, const char *format, ...);

DESCRIPTION
     These functions call the libc functions of	the same names,	passing
     through their return values when successful.  In case of failure, they do
     not return, but instead call err(3).  They	can be used both internally by
     any code in the mandoc libraries and externally by	programs using that
     library, for example mandoc(1), man(1), apropos(1), makewhatis(8),	and
     man.cgi(8).

     The function mandoc_malloc() allocates one	new object, leaving the	memory
     uninitialized.  The functions mandoc_realloc() and	mandoc_reallocarray()
     change the	size of	an existing object or array, possibly moving it.  When
     shrinking the size, existing data is truncated; when growing, the addi-
     tional memory is not initialized.	The function mandoc_calloc() allocates
     a new array, initializing it to zero.

     The argument size is the size of each object.  The	argument nmemb is the
     new number	of objects in the array.  The argument ptr is a	pointer	to the
     existing object or	array to be resized; if	it is NULL, a new object or
     array is allocated.

     The functions mandoc_strdup() and mandoc_strndup()	copy a string into
     newly allocated memory.  For mandoc_strdup(), the string pointed to by s
     needs to be NUL-terminated.  For mandoc_strndup(),	at most	maxlen bytes
     are copied.  The function mandoc_asprintf() writes	output formatted ac-
     cording to	format into newly allocated memory and returns a pointer to
     the result	in ret.	 For all three string functions, the result is always
     NUL-terminated.

     When the objects and strings are no longer	needed,	the pointers returned
     by	these functions	can be passed to free(3).

RETURN VALUES
     The function mandoc_asprintf() always returns the number of characters
     written, excluding	the final NUL byte.  It	never returns -1.

     The other functions always	return a valid pointer;	they never return
     NULL.

FILES
     These functions are implemented in	mandoc_aux.c.

SEE ALSO
     asprintf(3), err(3), malloc(3), strdup(3)

STANDARDS
     The functions malloc(), realloc(),	and calloc() are required by ANSI
     X3.159-1989 ("ANSI	C89").	The functions strdup() and strndup() are re-
     quired by IEEE Std	1003.1-2008 ("POSIX.1").  The function asprintf() is a
     widespread	extension that first appeared in the GNU C library.

     The function reallocarray() is an extension that first appeared in
     OpenBSD 5.6.  If it is not	provided by the	operating system, the mandoc
     build system uses a bundled portable implementation.

HISTORY
     The functions mandoc_malloc(), mandoc_realloc(), mandoc_calloc(), and
     mandoc_strdup() have been available since mandoc 1.9.12, mandoc_strndup()
     since 1.11.5, and mandoc_asprintf() and mandoc_reallocarray() since
     1.12.4 and	1.13.0.

AUTHORS
     Kristaps Dzonsons <kristaps@bsd.lv>
     Ingo Schwarze <schwarze@openbsd.org>

BSD				 July 7, 2016				   BSD

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | FILES | SEE ALSO | STANDARDS | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mandoc_malloc&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help