Add malloc_usable_size(3).

Discussed with:		arch@

include/Makefile

@@ -13,7 +13,7 @@ INCS=	a.out.h ar.h assert.h bitstring.h complex.h cpio.h _ctype.h ctype.h \
 	fts.h ftw.h getopt.h glob.h grp.h gssapi.h \
 	histedit.h ieeefp.h ifaddrs.h \
 	inttypes.h iso646.h kenv.h langinfo.h libgen.h limits.h link.h \
-	locale.h malloc.h memory.h monetary.h mpool.h mqueue.h \
+	locale.h malloc.h malloc_np.h memory.h monetary.h mpool.h mqueue.h \
 	ndbm.h netconfig.h \
 	netdb.h nl_types.h nlist.h nss.h nsswitch.h objformat.h paths.h \
 	printf.h proc_service.h pthread.h \

include/malloc_np.h

@@ -0,0 +1,37 @@
+/*-
+ * Copyright (C) 2006 Jason Evans <jasone@FreeBSD.org>.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice(s), this list of conditions and the following disclaimer as
+ *    the first lines of this file unmodified other than the possible
+ *    addition of one or more copyright notices.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice(s), this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+ * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+ * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * $FreeBSD$
+ */
+
+#ifndef _MALLOC_NP_H_
+#define	_MALLOC_NP_H_
+
+size_t	malloc_usable_size(const void *ptr);
+
+#endif /* _MALLOC_NP_H_ */

lib/libc/stdlib/Makefile.inc

@@ -46,5 +46,5 @@ MLINKS+=strtod.3 strtof.3 strtod.3 strtold.3
 MLINKS+=strtol.3 strtoll.3 strtol.3 strtoq.3 strtol.3 strtoimax.3
 MLINKS+=strtoul.3 strtoull.3 strtoul.3 strtouq.3 strtoul.3 strtoumax.3
 MLINKS+=malloc.3 calloc.3 malloc.3 free.3 malloc.3 malloc.conf.5 \
-	malloc.3 realloc.3 malloc.3 reallocf.3
+	malloc.3 realloc.3 malloc.3 reallocf.3 malloc.3 malloc_usable_size.3
 MLINKS+=tsearch.3 tdelete.3 tsearch.3 tfind.3 tsearch.3 twalk.3

lib/libc/stdlib/Symbol.map

@@ -53,6 +53,7 @@ FBSD_1.0 {
 	calloc;
 	realloc;
 	free;
+	malloc_usable_size;
 	mergesort;
 	putenv;
 	qsort_r;

lib/libc/stdlib/malloc.3

@@ -32,11 +32,11 @@
 .\"     @(#)malloc.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd March 9, 2006
+.Dd March 28, 2006
 .Dt MALLOC 3
 .Os
 .Sh NAME
-.Nm malloc , calloc , realloc , free , reallocf
+.Nm malloc , calloc , realloc , free , reallocf , malloc_usable_size
 .Nd general purpose memory allocation functions
 .Sh LIBRARY
 .Lb libc
@@ -58,6 +58,9 @@
 .Fo \*(lp*_malloc_message\*(rp
 .Fa "const char *p1" "const char *p2" "const char *p3" "const char *p4"
 .Fc
+.In malloc_np.h
+.Ft size_t
+.Fn malloc_usable_size "const void *ptr"
 .Sh DESCRIPTION
 The
 .Fn malloc
@@ -133,6 +136,21 @@ If
 is
 .Dv NULL ,
 no action occurs.
+.Pp
+The
+.Fn malloc_usable_size
+function returns the usable size of the allocation pointed to by
+.Fa ptr .
+The return value may be larger than the size that was requested during
+allocation.
+.Fn malloc_usable_size
+is not a mechanism for in-place
+.Fn realloc ;
+rather it is provided soley as a tool for introspection purposes.
+Any discrepancy between the requested allocation size and the size reported by
+.Fn malloc_usable_size
+should not be depended on, since such behavior is entirely
+implementation-dependent.
 .Sh TUNING
 Once, when the first call is made to one of these memory allocation
 routines, various flags will be set or reset, which affect the
@@ -443,3 +461,8 @@ The
 .Fn reallocf
 function first appeared in
 .Fx 3.0 .
+.Pp
+The
+.Fn malloc_usable_size
+function first appeared in
+.Fx 7.0 .

lib/libc/stdlib/malloc.c

@@ -3488,6 +3488,26 @@ free(void *ptr)
  * End malloc(3)-compatible functions.
  */
 /******************************************************************************/
+/*
+ * Begin non-standard functions.
+ */
+
+size_t
+malloc_usable_size(const void *ptr)
+{
+
+	assert(ptr != NULL);
+
+	if (ptr == &nil)
+		return (0);
+	else
+		return (isalloc(ptr));
+}
+
+/*
+ * End non-standard functions.
+ */
+/******************************************************************************/
 /*
  * Begin library-private functions, used by threading libraries for protection
  * of malloc during fork().  These functions are only called if the program is