xref: /freebsd/lib/libmemstat/libmemstat.3 (revision 33f23dc2fb7cad25edd0826bbb49b134fbf132ce)
10cddce49SRobert Watson.\" Copyright (c) 2005 Robert N. M. Watson
20cddce49SRobert Watson.\" All rights reserved.
30cddce49SRobert Watson.\"
40cddce49SRobert Watson.\" Redistribution and use in source and binary forms, with or without
50cddce49SRobert Watson.\" modification, are permitted provided that the following conditions
60cddce49SRobert Watson.\" are met:
70cddce49SRobert Watson.\" 1. Redistributions of source code must retain the above copyright
80cddce49SRobert Watson.\"    notice, this list of conditions and the following disclaimer.
90cddce49SRobert Watson.\" 2. Redistributions in binary form must reproduce the above copyright
100cddce49SRobert Watson.\"    notice, this list of conditions and the following disclaimer in the
110cddce49SRobert Watson.\"    documentation and/or other materials provided with the distribution.
120cddce49SRobert Watson.\"
130cddce49SRobert Watson.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
140cddce49SRobert Watson.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
150cddce49SRobert Watson.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
160cddce49SRobert Watson.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
170cddce49SRobert Watson.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
180cddce49SRobert Watson.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
190cddce49SRobert Watson.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
200cddce49SRobert Watson.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
210cddce49SRobert Watson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
220cddce49SRobert Watson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
230cddce49SRobert Watson.\" SUCH DAMAGE.
240cddce49SRobert Watson.\"
250cddce49SRobert Watson.\" $FreeBSD$
260cddce49SRobert Watson.\"
270cddce49SRobert Watson.Dd June 27, 2005
280cddce49SRobert Watson.Os
290cddce49SRobert Watson.Dt LIBMEMSTAT 3
300cddce49SRobert Watson.Sh NAME
310cddce49SRobert Watson.Nm libmemstat
320cddce49SRobert Watson.Nd "library interface to retrieve kernel memory allocator statistics"
330cddce49SRobert Watson.Sh LIBRARY
340cddce49SRobert Watson.Lb libmemstat
350cddce49SRobert Watson.Sh SYNOPSIS
360cddce49SRobert Watson.In sys/types.h
370cddce49SRobert Watson.In memstat.h
38e754c6bbSRobert Watson.Ss General Functions
39e754c6bbSRobert Watson.Ft const char *
40e754c6bbSRobert Watson.Fn memstat_strerror "int error"
410cddce49SRobert Watson.Ss Memory Type List Management Functions
420cddce49SRobert Watson.Ft struct memory_type_list *
430cddce49SRobert Watson.Fn memstat_mtl_alloc "void"
440cddce49SRobert Watson.Ft struct memory_type *
450cddce49SRobert Watson.Fn memstat_mtl_first "struct memory_type_list *list"
460cddce49SRobert Watson.Ft struct memory_type *
470cddce49SRobert Watson.Fn memstat_mtl_next "struct memory_type *mtp"
480cddce49SRobert Watson.Ft struct memory_type *
490cddce49SRobert Watson.Fn memstat_mtl_find "struct memory_type_list *list" "int allocator" "const char *name"
500cddce49SRobert Watson.Ft void
510cddce49SRobert Watson.Fn memstat_mtl_free "struct memory_type_list *list"
5270ee997eSRobert Watson.Ft int
5370ee997eSRobert Watson.Fn memstat_mtl_geterror "struct memory_type_list *list"
540cddce49SRobert Watson.Ss Allocator Query Functions
550cddce49SRobert Watson.Ft int
56ba23fa9bSRobert Watson.Fn memstat_kvm_all "struct memory_type_list *list" "void *kvm_handle"
57ba23fa9bSRobert Watson.Ft int
58ba23fa9bSRobert Watson.Fn memstat_kvm_malloc "struct memory_type_list *list" "void *kvm_handle"
59ba23fa9bSRobert Watson.Ft int
6033c20d18SRobert Watson.Fn memstat_kvm_uma "struct memory_type_list *list" "void *kvm_handle"
6133c20d18SRobert Watson.Ft int
620cddce49SRobert Watson.Fn memstat_sysctl_all "struct memory_type_list *list" "int flags"
630cddce49SRobert Watson.Ft int
640cddce49SRobert Watson.Fn memstat_sysctl_malloc "struct memory_type_list *list" "int flags"
650cddce49SRobert Watson.Ft int
660cddce49SRobert Watson.Fn memstat_sysctl_uma "struct memory_type_list *list" "int flags"
670cddce49SRobert Watson.Ss Memory Type Accessor Methods
680cddce49SRobert Watson.Ft const char *
690cddce49SRobert Watson.Fn memstat_get_name "const struct memory_type *mtp"
700cddce49SRobert Watson.Ft int
710cddce49SRobert Watson.Fn memstat_get_allocator "const struct memory_type *mtp"
720cddce49SRobert Watson.Ft uint64_t
730cddce49SRobert Watson.Fn memstat_get_countlimit "const struct memory_type *mtp"
740cddce49SRobert Watson.Ft uint64_t
750cddce49SRobert Watson.Fn memstat_get_byteslimit "const struct memory_type *mtp"
760cddce49SRobert Watson.Ft uint64_t
770cddce49SRobert Watson.Fn memstat_get_sizemask "const struct memory_type *mtp"
780cddce49SRobert Watson.Ft uint64_t
790cddce49SRobert Watson.Fn memstat_get_size "const struct memory_type *mtp"
800cddce49SRobert Watson.Ft uint64_t
810cddce49SRobert Watson.Fn memstat_get_memalloced "const struct memory_type *mtp"
820cddce49SRobert Watson.Ft uint64_t
830cddce49SRobert Watson.Fn memstat_get_memfreed "const struct memory_type *mtp"
840cddce49SRobert Watson.Ft uint64_t
850cddce49SRobert Watson.Fn memstat_get_numallocs "const struct memory_type *mtp"
860cddce49SRobert Watson.Ft uint64_t
870cddce49SRobert Watson.Fn memstat_get_numfrees "const struct memory_type *mtp"
880cddce49SRobert Watson.Ft uint64_t
890cddce49SRobert Watson.Fn memstat_get_bytes "const struct memory_type *mtp"
900cddce49SRobert Watson.Ft uint64_t
910cddce49SRobert Watson.Fn memstat_get_count "const struct memory_type *mtp"
920cddce49SRobert Watson.Ft uint64_t
930cddce49SRobert Watson.Fn memstat_get_free "const struct memory_type *mtp"
940cddce49SRobert Watson.Ft uint64_t
950cddce49SRobert Watson.Fn memstat_get_failures "const struct memory_type *mtp"
960cddce49SRobert Watson.Ft void *
970cddce49SRobert Watson.Fn memstat_get_caller_pointer "const struct memory_type *mtp" "int index"
980cddce49SRobert Watson.Ft void
990cddce49SRobert Watson.Fn memstat_set_caller_pointer "struct memory_type *mtp" "int index" "void *value"
1000cddce49SRobert Watson.Ft uint64_t
1010cddce49SRobert Watson.Fn memstat_get_caller_uint64 "const struct memory_type *mtp" "int index"
1020cddce49SRobert Watson.Ft void
1030cddce49SRobert Watson.Fn memstat_set_caller_uint64 "struct memory_type *mtp" "int index" "uint64_t value"
1040cddce49SRobert Watson.Ft uint64_t
1050cddce49SRobert Watson.Fn memstat_get_zonefree "const struct memory_type *mtp"
1060cddce49SRobert Watson.Ft uint64_t
107ca108fe2SRobert Watson.Fn memstat_get_kegfree "const struct memory_type *mtp"
108ca108fe2SRobert Watson.Ft uint64_t
1090cddce49SRobert Watson.Fn memstat_get_percpu_memalloced "const struct memory_type *mtp" "int cpu"
1100cddce49SRobert Watson.Ft uint64_t
1110cddce49SRobert Watson.Fn memstat_get_percpu_memfreed "const struct memory_type *mtp" "int cpu"
1120cddce49SRobert Watson.Ft uint64_t
1130cddce49SRobert Watson.Fn memstat_get_percpu_numallocs "const struct memory_type *mtp" "int cpu"
1140cddce49SRobert Watson.Ft uint64_t
1150cddce49SRobert Watson.Fn memstat_get_percpu_numfrees "const struct memory_type *mtp" "int cpu"
1160cddce49SRobert Watson.Ft uint64_t
1170cddce49SRobert Watson.Fn memstat_get_percpu_sizemask "const struct memory_type *mtp" "int cpu"
1180cddce49SRobert Watson.Ft void *
1190cddce49SRobert Watson.Fn memstat_get_percpu_caller_pointer "const struct memory_type *mtp" "int cpu" "int index"
1200cddce49SRobert Watson.Ft void
1210cddce49SRobert Watson.Fn memstat_set_percpu_caller_pointer "struct memory_type *mtp" "int cpu" "int index" "void *value"
1220cddce49SRobert Watson.Ft uint64_t
1230cddce49SRobert Watson.Fn memstat_get_percpu_caller_uint64 "const struct memory_type *mtp" "int cpu" "int index"
1240cddce49SRobert Watson.Ft void
1250cddce49SRobert Watson.Fn memstat_set_percpu_caller_uint64 "struct memory_type *mtp" "int cpu" "int index" "uint64_t value"
1260cddce49SRobert Watson.Ft uint64_t
1270cddce49SRobert Watson.Fn memstat_get_percpu_free "const struct memory_type *mtp" "int cpu"
1280cddce49SRobert Watson.Sh DESCRIPTION
1290cddce49SRobert Watson.Nm
1300cddce49SRobert Watsonprovides an interface to retrieve kernel memory allocator statistics, for
1310cddce49SRobert Watsonthe purposes of debugging and system monitoring, insulating applications
1320cddce49SRobert Watsonfrom implementation details of the allocators, and allowing a tool to
1330cddce49SRobert Watsontransparently support multiple allocators.
1340cddce49SRobert Watson.Nm
1350cddce49SRobert Watsonsupports both retrieving a single statistics snapshot, as well as
1360cddce49SRobert Watsonincrementally updating statistics for long-term monitoring.
1370cddce49SRobert Watson.Pp
1380cddce49SRobert Watson.Nm
1390cddce49SRobert Watsondescribes each memory type using a
1400cddce49SRobert Watson.Vt struct memory_type ,
1410cddce49SRobert Watsonan opaque memory type accessed by the application using accessor functions
1420cddce49SRobert Watsonin the library.
1430cddce49SRobert Watson.Nm
1440cddce49SRobert Watsonreturns and updates chains of
1450cddce49SRobert Watson.Vt struct memory_type
1460cddce49SRobert Watsonvia a
1470cddce49SRobert Watson.Vt struct memory_type_list ,
1480cddce49SRobert Watsonwhich will be allocated by calling
1490cddce49SRobert Watson.Fn memstat_mtl_alloc ,
1500cddce49SRobert Watsonand freed on completion using
1510cddce49SRobert Watson.Fn memstat_mtl_free .
1520cddce49SRobert WatsonLists of memory types are populated via calls that query the kernel for
1530cddce49SRobert Watsonstatistics information; currently:
154ba23fa9bSRobert Watson.Fn memstat_kvm_all ,
155ba23fa9bSRobert Watson.Fn memstat_kvm_malloc ,
15633c20d18SRobert Watson.Fn memstat_kvm_uma ,
1570cddce49SRobert Watson.Fn memstat_sysctl_all ,
1580cddce49SRobert Watson.Fn memstat_sysctl_uma ,
1590cddce49SRobert Watsonand
1600cddce49SRobert Watson.Fn memstat_sysctl_malloc .
1610cddce49SRobert WatsonRepeated calls will incrementally update the list of memory types, permitting
1620cddce49SRobert Watsontracking over time without recreating all list state.
16370ee997eSRobert WatsonIf an error is detected during a query call, error condition information may
16470ee997eSRobert Watsonbe retrieved using
165e754c6bbSRobert Watson.Fn memstat_mtl_geterror ,
166e754c6bbSRobert Watsonand converted to a user-readable string using
167e754c6bbSRobert Watson.Fn memstat_strerror .
16870ee997eSRobert Watson.Pp
1690cddce49SRobert WatsonFreeing the list will free all memory type data in the list, and so
1700cddce49SRobert Watsoninvalidates any outstanding pointers to entries in the list.
1710cddce49SRobert Watson.Vt struct memory_type
1720cddce49SRobert Watsonentries in the list may be iterated over using
1730cddce49SRobert Watson.Fn memstat_mtl_first
1740cddce49SRobert Watsonand
1750cddce49SRobert Watson.fn memstat_mtl_next ,
1760cddce49SRobert Watsonwhich respectively return the first entry in a list, and the next entry in a
1770cddce49SRobert Watsonlist.
1780cddce49SRobert Watson.Fn memstat_mtl_find ,
1790cddce49SRobert Watsonwhich will return a pointer to the first entry matching the passed
1800cddce49SRobert Watsonparameters.
1810cddce49SRobert Watson.Pp
1820cddce49SRobert WatsonA series of accessor methods is provided to access fields of the structure,
1830cddce49SRobert Watsonincluding retrieving statistics and properties, as well as setting of caller
1840cddce49SRobert Watsonowned fields.
1850cddce49SRobert WatsonDirect application access to the data structure fields is not supported.
1860cddce49SRobert Watson.Ss Library memory_type Fields
1870cddce49SRobert WatsonEach
1880cddce49SRobert Watson.Vt struct memory_type
1890cddce49SRobert Watsonholds a description of the memory type, including its name and the allocator
1900cddce49SRobert Watsonit is managed by, as well as current statistics on use.
1910cddce49SRobert WatsonSome statistics are directly measured, others are derived from directly
1920cddce49SRobert Watsonmeasured statistics.
1930cddce49SRobert WatsonCertain high level statistics are present across all available allocators,
1940cddce49SRobert Watsonsuch as the number of allocation and free operations; other measurements,
1950cddce49SRobert Watsonsuch as the quantity of free items in per-CPU caches, or administrative
1960cddce49SRobert Watsonlimit on the number of allocations, is available only for specific
1970cddce49SRobert Watsonallocators.
198e86bb57bSRobert Watson.Ss Caller memory_type Fields
1990cddce49SRobert Watson.Vt struct memory_type
200e86bb57bSRobert Watsonincludes fields to allow the application to store data, in the form of
201e86bb57bSRobert Watsonpointers and 64-bit integers, with memory types.
2020cddce49SRobert WatsonFor example, the application author might make use of one of the caller
2030cddce49SRobert Watsonpointers to reference a more complex data structure tracking long-term
2040cddce49SRobert Watsonbehavior of the memory type, or a window system object that is used to
2050cddce49SRobert Watsonrender the state of the memory type.
206e86bb57bSRobert WatsonGeneral and per-CPU storage is provided with each
2070cddce49SRobert Watson.Vt struct memory_type
208e86bb57bSRobert Watsonin the form of an array of pointers and integers.
209e86bb57bSRobert WatsonThe array entries are accessed via the
210e86bb57bSRobert Watson.Fa index
211e86bb57bSRobert Watsonargument to the get and set accessor methods.
212e86bb57bSRobert WatsonPossible values of
213e86bb57bSRobert Watson.Fa index
214e86bb57bSRobert Watsonrange between
215e86bb57bSRobert Watson.Dv 0
216e86bb57bSRobert Watsonand
217e86bb57bSRobert Watson.Dv MEMSTAT_MAXCALLER .
218e86bb57bSRobert Watson.Pp
219e86bb57bSRobert WatsonCaller-owned fields are initialized to
2200cddce49SRobert Watson.Dv 0
2210cddce49SRobert Watsonor
2220cddce49SRobert Watson.Dv NULL
223e86bb57bSRobert Watsonwhen a new
224e86bb57bSRobert Watson.Vt struct memory_type
225e86bb57bSRobert Watsonis allocated and attached to a memory type list; these fields retain their
226e86bb57bSRobert Watsonvalues across queries that update library-owned fields.
22709df0a9aSRobert Watson.Ss Allocator Types
22809df0a9aSRobert WatsonCurrently,
22909df0a9aSRobert Watson.Nm
23009df0a9aSRobert Watsonsupports two kernel allocators:
23109df0a9aSRobert Watson.Dv ALLOCATOR_UMA
23209df0a9aSRobert Watsonfor
23309df0a9aSRobert Watson.Xr uma 9 ,
23409df0a9aSRobert Watsonand
23509df0a9aSRobert Watson.Dv ALLOCATOR_MALLOC
23609df0a9aSRobert Watsonfor
23709df0a9aSRobert Watson.Xr malloc 9 .
23809df0a9aSRobert WatsonThese values may be passed to
23909df0a9aSRobert Watson.Fn memstat_mtl_find ,
24009df0a9aSRobert Watsonand will be returned by
24109df0a9aSRobert Watson.Fn memstat_get_allocator .
24209df0a9aSRobert WatsonTwo additional constants in the allocator name space are defined:
24309df0a9aSRobert Watson.Dv ALLOCATOR_UNKNOWN ,
24409df0a9aSRobert Watsonwhich will only be returned as a result of a library error, and
24509df0a9aSRobert Watson.Dv ALLOCATOR_ANY ,
24609df0a9aSRobert Watsonwhich can be used to specify that returning types matching any allocator is
24709df0a9aSRobert Watsonpermittible from
24809df0a9aSRobert Watson.Fn memstat_mtl_find .
24970ee997eSRobert Watson.Ss Access Method List
25070ee997eSRobert WatsonThe following accessor methods are defined, of which some will be valid for
25170ee997eSRobert Watsona given memory type:
25270ee997eSRobert Watson.Pp
25370ee997eSRobert Watson.Bl -tag -width "memstat_get_name" -compact -offset wee
25470ee997eSRobert Watson.It memstat_get_name
25570ee997eSRobert WatsonReturn a pointer to the name of the memory type.
25670ee997eSRobert WatsonMemory for the name is owned by
25770ee997eSRobert Watson.Nm
25870ee997eSRobert Watsonand will be valid through a call to
25970ee997eSRobert Watson.Fn memstat_mtl_free .
26070ee997eSRobert WatsonNote that names will be unique with respect to a single allocator, but that
26170ee997eSRobert Watsonthe same name might be used by different memory types owned by different
26270ee997eSRobert Watsonmemory allocators.
26370ee997eSRobert Watson.It memstat_get_allocator
26470ee997eSRobert WatsonReturn an integer identifier for the memory allocator that owns the memory
26570ee997eSRobert Watsontype.
26670ee997eSRobert Watson.It memstat_get_countlimit
26770ee997eSRobert WatsonIf the memory type has an administrative limit on the number of simultaneous
26870ee997eSRobert Watsonallocations, return it.
26970ee997eSRobert Watson.It memstat_get_byteslimit
27070ee997eSRobert WatsonIf the memory type has an administrative limit on the number of bytes of
27170ee997eSRobert Watsonmemory that may be simultaenously allocated for the memory type, return it.
27270ee997eSRobert Watson.It memstat_get_sizemask
27370ee997eSRobert WatsonIf the memory type supports variable allocation sizes, return a bitmask of
27470ee997eSRobert Watsonsizes allocated for the memory type.
27570ee997eSRobert Watson.It memstat_get_size
27670ee997eSRobert WatsonIf the memory type supports a fixed allocation size, return that size.
27770ee997eSRobert Watson.It memstat_get_memalloced
27870ee997eSRobert WatsonReturn the total number of bytes allocated for the memory type over its
27970ee997eSRobert Watsonlifetime.
28070ee997eSRobert Watson.It memstat_get_memfreed
28170ee997eSRobert WatsonReturn the total number of bytes freed for the memory type over its lifetime.
28270ee997eSRobert Watson.It memstat_get_numallocs
28370ee997eSRobert WatsonReturn the total number of allocations for the memory type over its lifetime.
28470ee997eSRobert Watson.It memstat_get_numfrees
28570ee997eSRobert WatsonReturn the total number of frees for the memory type over its lifetime.
28670ee997eSRobert Watson.It memstat_get_bytes
28770ee997eSRobert WatsonReturn the current number of bytes allocated to the memory type.
28870ee997eSRobert Watson.It memstat_get_count
28970ee997eSRobert WatsonReturn the current number of allocations for the memory type.
29070ee997eSRobert Watson.It memstat_get_free
29170ee997eSRobert WatsonIf the memory allocator supports a cache, return the number of items in the
29270ee997eSRobert Watsoncache.
29370ee997eSRobert Watson.It memstat_get_failures
29470ee997eSRobert WatsonIf the memory allocator and type permit allocation failures, return the
29570ee997eSRobert Watsonnumber of allocation failures measured.
29670ee997eSRobert Watson.It memstat_get_caller_pointer
29770ee997eSRobert WatsonReturn a caller-owned pointer for the memory type.
29870ee997eSRobert Watson.It memstat_set_caller_pointer
29970ee997eSRobert WatsonSet a caller-owned pointer for the memory type.
30070ee997eSRobert Watson.It memstat_get_caller_uint64
30170ee997eSRobert WatsonReturn a caller-owned integer for the memory type.
30270ee997eSRobert Watson.It memstat_set_caller_uint64
30370ee997eSRobert WatsonSet a caller-owned integer for the memory type.
30470ee997eSRobert Watson.It memstat_get_zonefree
30570ee997eSRobert WatsonIf the memory allocator supports a multi-level allocation structure, return
30670ee997eSRobert Watsonthe number of cached items in the zone.
30770ee997eSRobert WatsonThese items will be in a fully constructed state available for immediate
30870ee997eSRobert Watsonuse.
30970ee997eSRobert Watson.It memstat_get_kegfree
31070ee997eSRobert WatsonIf the memory allocator supports a multi-level allocation structure, return
31170ee997eSRobert Watsonthe number of cached items in the keg.
31270ee997eSRobert WatsonThese items may be in a partially constructed state, and may require further
31370ee997eSRobert Watsonprocessing before they can be made available for use.
31470ee997eSRobert Watson.It memstat_get_percpu_memalloced
31570ee997eSRobert WatsonIf the memory allocator supports per-CPU statistics, return the number of
31670ee997eSRobert Watsonbytes of memory allocated for the memory type on the CPU over its lifetime.
31770ee997eSRobert Watson.It memstat_get_percpu_memfreed
31870ee997eSRobert WatsonIf the memory allocator supports per-CPU statistics, return the number of
31970ee997eSRobert Watsonbytes of memory freed from the memory type on the CPU over its lifetime.
32070ee997eSRobert Watson.It memstat_get_percpu_numallocs
32170ee997eSRobert WatsonIf the memory allocator supports per-CPU statistics, return the number of
32270ee997eSRobert Watsonallocations for the memory type on the CPU over its lifetime.
32370ee997eSRobert Watson.It memstat_get_percpu_numfrees
32470ee997eSRobert WatsonIf the memory allocator supports per-CPU statistics, return the number of
32570ee997eSRobert Watsonfrees for the memory type on the CPU over its lifetime.
32670ee997eSRobert Watson.It memstat_get_percpu_sizemask
32770ee997eSRobert WatsonIf the memory allocator supports variable size memory allocation and per-CPU
32870ee997eSRobert Watsonstatistics, return the size bitmask for the memory type on the CPU.
32970ee997eSRobert Watson.It memstat_get_percpu_caller_pointer
33070ee997eSRobert WatsonReturn a caller-owned per-CPU pointer for the memory type.
33170ee997eSRobert Watson.It memstat_set_percpu_caller_pointer
33270ee997eSRobert WatsonSet a caller-owned per-CPU pointer for the memory type.
33370ee997eSRobert Watson.It memstat_get_percpu_caller_uint64
33470ee997eSRobert WatsonReturn a caller-owned per-CPU integer for the memory type.
33570ee997eSRobert Watson.It memsttat_set_percpu_caller_uint64
33670ee997eSRobert WatsonSet a caller-owned per-CPU integer for the memory type.
33770ee997eSRobert Watson.It memstat_get_percpu_free
33870ee997eSRobert WatsonIf the memory allocator supports a per-CPU cache, return the number of free
33970ee997eSRobert Watsonitems in the per-CPU cache of the designated CPU.
34070ee997eSRobert Watson.El
34170ee997eSRobert Watson.Sh RETURN VALUES
34270ee997eSRobert Watson.Nm
34370ee997eSRobert Watsonfunctions fall into three categories: functions returning a pointer to an
34470ee997eSRobert Watsonobject, functions returning an integer return value, and functions
34570ee997eSRobert Watsonimplementing accessor methods returning data from a
34670ee997eSRobert Watson.Vt struct memory_type .
34770ee997eSRobert Watson.Pp
34870ee997eSRobert WatsonFunctions returning a pointer to an object will generally return
34970ee997eSRobert Watson.Dv NULL
35070ee997eSRobert Watsonon failure.
35170ee997eSRobert Watson.Fn memstat_mtl_alloc
35270ee997eSRobert Watsonwill return an error value via
35370ee997eSRobert Watson.Va errno ,
35470ee997eSRobert Watsonwhich will consist of the value
35570ee997eSRobert Watson.Dv ENOMEM .
35670ee997eSRobert WatsonFunctions
35770ee997eSRobert Watson.Fn memstat_mtl_first ,
35870ee997eSRobert Watson.Fn memstat_mtl_next ,
35970ee997eSRobert Watsonand
36070ee997eSRobert Watson.Fn memstat_mtl_find
36170ee997eSRobert Watsonwill return
36270ee997eSRobert Watson.Dv NULL
36370ee997eSRobert Watsonwhen there is no entry or match in the list; however, this is not considered
36470ee997eSRobert Watsona failure mode and no error value is available.
36570ee997eSRobert Watson.Pp
36670ee997eSRobert WatsonFunctions returning a integer success valuye will return
36770ee997eSRobert Watson.Dv 0
36870ee997eSRobert Watsonon success, or
36970ee997eSRobert Watson.Dv -1
37070ee997eSRobert Watsonon failure.
37170ee997eSRobert WatsonIf a failure is returned, the list error access method,
37270ee997eSRobert Watson.Fn memstat_mtl_geterror ,
373e754c6bbSRobert Watsonmay be used to retrieve the error state.
374e754c6bbSRobert WatsonThe string representation of the error may be retrieved using
375e754c6bbSRobert Watson.Fn memstat_strerror .
376e754c6bbSRobert WatsonPossible error values are:
37770ee997eSRobert Watson.Pp
378513c89ceSRobert Watson.Bl -tag -width "MEMSTAT_ERROR_KVM_SHORTREAD" -compact -offset wee
37970ee997eSRobert Watson.It Dv MEMSTAT_ERROR_UNDEFINED
38070ee997eSRobert WatsonUndefined error.  Occurs if
38170ee997eSRobert Watson.Fn memstat_mtl_geterror
38270ee997eSRobert Watsonis called on a list before an error associated with the list has occurred.
38370ee997eSRobert Watson.It Dv MEMSTAT_ERROR_NOMEMORY
38470ee997eSRobert WatsonInsufficient memory.  Occurs if library calls to
38570ee997eSRobert Watson.Xr malloc 3
38670ee997eSRobert Watsonfail, or if a system call to retrieve kernel statistics fails with
38770ee997eSRobert Watson.Er ENOMEM .
38870ee997eSRobert Watson.It Dv MEMSTAT_ERROR_VERSION
38970ee997eSRobert WatsonReturned if the current version of
39070ee997eSRobert Watson.Nm
39170ee997eSRobert Watsonis unable to interpret the statistics data returned by the kernel due to an
39270ee997eSRobert Watsonexplicit version mismatch, or to differences in data structures that cannot
39370ee997eSRobert Watsonbe reconciled.
39470ee997eSRobert Watson.It Dv MEMSTAT_ERROR_PERMISSION
39570ee997eSRobert WatsonReturned if a statistics source returns
39670ee997eSRobert Watson.Va errno
39770ee997eSRobert Watsonvalues of
39870ee997eSRobert Watson.Dv EACCES
39970ee997eSRobert Watsonor
40070ee997eSRobert Watson.Dv EPERM .
40170ee997eSRobert Watson.It Dv MEMSTAT_ERROR_TOOMANYCPUS
40270ee997eSRobert WatsonReturned if the compile-time limit on the number of CPUs in
40370ee997eSRobert Watson.Nm
40470ee997eSRobert Watsonis lower than the number of CPUs returned by a statistics data source.
40570ee997eSRobert Watson.It Dv MEMSTAT_ERROR_DATAERROR
40670ee997eSRobert WatsonReturned if
40770ee997eSRobert Watson.Nm
40870ee997eSRobert Watsonis unable to interpret statistics data returned by the data source, even
40970ee997eSRobert Watsonthough there does not appear to be a version problem.
410513c89ceSRobert Watson.It Dv MEMSTAT_ERROR_KVM
411513c89ceSRobert WatsonReturned if
412513c89ceSRobert Watson.Nm
413513c89ceSRobert Watsonexperiences an error while using
414513c89ceSRobert Watson.Xr kvm 3
415513c89ceSRobert Watsoninterfaces to query statistics data.
416513c89ceSRobert WatsonUse
417513c89ceSRobert Watson.Xr kvm_geterr 3
418513c89ceSRobert Watsonto retrieve the error.
419513c89ceSRobert Watson.It Dv MEMSTAT_ERROR_KVM_NOSYMBOL
420513c89ceSRobert WatsonReturned if
421513c89ceSRobert Watson.Nm
422513c89ceSRobert Watsonis unable to read a required symbol from the kernel being operated on.
423513c89ceSRobert Watson.It Dv MEMSTAT_ERROR_KVM_SHORTREAD
424513c89ceSRobert WatsonReturned if
425513c89ceSRobert Watson.Nm
426513c89ceSRobert Watsonattempts to read data from a live memory image or kernel core dump and
427513c89ceSRobert Watsoninsufficient data is returned.
42870ee997eSRobert Watson.El
42970ee997eSRobert Watson.Pp
43070ee997eSRobert WatsonFinally, functions returning data from a
43170ee997eSRobert Watson.Dt struct memory_type
43270ee997eSRobert Watsonpointer are not permitted to fail, and directly return either a statistic
43370ee997eSRobert Watsonor pointer to a string.
4340cddce49SRobert Watson.Sh EXAMPLES
4350cddce49SRobert WatsonCreate a memory type list, query the
4360cddce49SRobert Watson.Xr uma 9
4370cddce49SRobert Watsonmemory allocator for available statistics, and print out the number of
4380cddce49SRobert Watsonallocations performed by the
43933f23dc2SRobert Watson.Dv mbuf
4400cddce49SRobert Watsonzone.
4410cddce49SRobert Watson.Bd -literal -offset indent
4420cddce49SRobert Watsonstruct memory_type_list *mtlp;
4430cddce49SRobert Watsonstruct memory_type *mtp;
4440cddce49SRobert Watsonuint64_t mbuf_count;
4450cddce49SRobert Watson
4460cddce49SRobert Watsonmtlp = memstat_mtl_alloc();
4470cddce49SRobert Watsonif (mtlp == NULL)
4480cddce49SRobert Watson    err(-1, "memstat_mtl_alloc");
4490cddce49SRobert Watsonif (memstat_sysctl_uma(mtlp, 0) < 0)
4500cddce49SRobert Watson    err(-1, "memstat_sysctl_uma");
45133f23dc2SRobert Watsonmtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf");
4520cddce49SRobert Watsonif (mtp == NULL)
45333f23dc2SRobert Watson    errx(-1, "memstat_mtl_find: mbuf not found");
4540cddce49SRobert Watsonmbuf_count = memstat_get_count(mtp);
4550cddce49SRobert Watsonmemstat_mtl_free(mtlp);
4560cddce49SRobert Watson
45733f23dc2SRobert Watsonprintf("mbufs: %llu\\n", (unsigned long long)mbuf_count);
4580cddce49SRobert Watson.Ed
4590cddce49SRobert Watson.Sh SEE ALSO
4600cddce49SRobert Watson.Xr malloc 9 ,
4610cddce49SRobert Watson.Xr uma 9
4620cddce49SRobert Watson.Sh HISTORY
4630cddce49SRobert WatsonThe
464e754c6bbSRobert Watson.Nm libmemstat
4650cddce49SRobert Watsonlibrary appeared in
4660cddce49SRobert Watson.Fx 6.0 .
4670cddce49SRobert Watson.Sh AUTHORS
4680cddce49SRobert WatsonThe kernel memory allocator changes necessary to support a general purpose
4690cddce49SRobert Watsonmonitoring library, along with the library, were written by
4700cddce49SRobert Watson.An Robert Watson Aq rwatson@FreeBSD.org
4710cddce49SRobert Watson.Sh BUGS
472ba23fa9bSRobert WatsonThere are memory allocators in the kernel, such as the VM page allocator
473ba23fa9bSRobert Watsonand sf_buf allocator, which are not currently supported by
474513c89ceSRobert Watson.Nm
4750cddce49SRobert Watson.Pp
4760cddce49SRobert WatsonOnce a memory type is present on a memory type list, it will not be removed
4770cddce49SRobert Watsoneven if the kernel no longer presents information on the type via its
4780cddce49SRobert Watsonmonitoring interfaces.
4790cddce49SRobert WatsonIn order to flush removed memory types, it is necessary to free the entire
4800cddce49SRobert Watsonlist and allocate a new one.
481