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