| libmemstat.3 (148170) | libmemstat.3 (148358) |
|---|---|
| 1.\" Copyright (c) 2005 Robert N. M. Watson 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 8 unchanged lines hidden (view full) --- 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" | 1.\" Copyright (c) 2005 Robert N. M. Watson 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 8 unchanged lines hidden (view full) --- 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" |
| 25.\" $FreeBSD: head/lib/libmemstat/libmemstat.3 148170 2005-07-20 09:17:40Z rwatson $ | 25.\" $FreeBSD: head/lib/libmemstat/libmemstat.3 148358 2005-07-24 01:29:30Z rwatson $ |
| 26.\" 27.Dd June 27, 2005 28.Os 29.Dt LIBMEMSTAT 3 30.Sh NAME 31.Nm libmemstat 32.Nd "library interface to retrieve kernel memory allocator statistics" 33.Sh LIBRARY --- 7 unchanged lines hidden (view full) --- 41.Ft struct memory_type * 42.Fn memstat_mtl_first "struct memory_type_list *list" 43.Ft struct memory_type * 44.Fn memstat_mtl_next "struct memory_type *mtp" 45.Ft struct memory_type * 46.Fn memstat_mtl_find "struct memory_type_list *list" "int allocator" "const char *name" 47.Ft void 48.Fn memstat_mtl_free "struct memory_type_list *list" | 26.\" 27.Dd June 27, 2005 28.Os 29.Dt LIBMEMSTAT 3 30.Sh NAME 31.Nm libmemstat 32.Nd "library interface to retrieve kernel memory allocator statistics" 33.Sh LIBRARY --- 7 unchanged lines hidden (view full) --- 41.Ft struct memory_type * 42.Fn memstat_mtl_first "struct memory_type_list *list" 43.Ft struct memory_type * 44.Fn memstat_mtl_next "struct memory_type *mtp" 45.Ft struct memory_type * 46.Fn memstat_mtl_find "struct memory_type_list *list" "int allocator" "const char *name" 47.Ft void 48.Fn memstat_mtl_free "struct memory_type_list *list" |
| 49.Ft int 50.Fn memstat_mtl_geterror "struct memory_type_list *list" |
|
| 49.Ss Allocator Query Functions 50.Ft int 51.Fn memstat_sysctl_all "struct memory_type_list *list" "int flags" 52.Ft int 53.Fn memstat_sysctl_malloc "struct memory_type_list *list" "int flags" 54.Ft int 55.Fn memstat_sysctl_uma "struct memory_type_list *list" "int flags" 56.Ss Memory Type Accessor Methods --- 84 unchanged lines hidden (view full) --- 141Lists of memory types are populated via calls that query the kernel for 142statistics information; currently: 143.Fn memstat_sysctl_all , 144.Fn memstat_sysctl_uma , 145and 146.Fn memstat_sysctl_malloc . 147Repeated calls will incrementally update the list of memory types, permitting 148tracking over time without recreating all list state. | 51.Ss Allocator Query Functions 52.Ft int 53.Fn memstat_sysctl_all "struct memory_type_list *list" "int flags" 54.Ft int 55.Fn memstat_sysctl_malloc "struct memory_type_list *list" "int flags" 56.Ft int 57.Fn memstat_sysctl_uma "struct memory_type_list *list" "int flags" 58.Ss Memory Type Accessor Methods --- 84 unchanged lines hidden (view full) --- 143Lists of memory types are populated via calls that query the kernel for 144statistics information; currently: 145.Fn memstat_sysctl_all , 146.Fn memstat_sysctl_uma , 147and 148.Fn memstat_sysctl_malloc . 149Repeated calls will incrementally update the list of memory types, permitting 150tracking over time without recreating all list state. |
| 151If an error is detected during a query call, error condition information may 152be retrieved using 153.Fn memstat_mtl_geterror . 154.Pp |
|
| 149Freeing the list will free all memory type data in the list, and so 150invalidates any outstanding pointers to entries in the list. 151.Vt struct memory_type 152entries in the list may be iterated over using 153.Fn memstat_mtl_first 154and 155.fn memstat_mtl_next , 156which respectively return the first entry in a list, and the next entry in a --- 64 unchanged lines hidden (view full) --- 221.Fn memstat_get_allocator . 222Two additional constants in the allocator name space are defined: 223.Dv ALLOCATOR_UNKNOWN , 224which will only be returned as a result of a library error, and 225.Dv ALLOCATOR_ANY , 226which can be used to specify that returning types matching any allocator is 227permittible from 228.Fn memstat_mtl_find . | 155Freeing the list will free all memory type data in the list, and so 156invalidates any outstanding pointers to entries in the list. 157.Vt struct memory_type 158entries in the list may be iterated over using 159.Fn memstat_mtl_first 160and 161.fn memstat_mtl_next , 162which respectively return the first entry in a list, and the next entry in a --- 64 unchanged lines hidden (view full) --- 227.Fn memstat_get_allocator . 228Two additional constants in the allocator name space are defined: 229.Dv ALLOCATOR_UNKNOWN , 230which will only be returned as a result of a library error, and 231.Dv ALLOCATOR_ANY , 232which can be used to specify that returning types matching any allocator is 233permittible from 234.Fn memstat_mtl_find . |
| 235.Ss Access Method List 236The following accessor methods are defined, of which some will be valid for 237a given memory type: 238.Pp 239.Bl -tag -width "memstat_get_name" -compact -offset wee 240.It memstat_get_name 241Return a pointer to the name of the memory type. 242Memory for the name is owned by 243.Nm 244and will be valid through a call to 245.Fn memstat_mtl_free . 246Note that names will be unique with respect to a single allocator, but that 247the same name might be used by different memory types owned by different 248memory allocators. 249.It memstat_get_allocator 250Return an integer identifier for the memory allocator that owns the memory 251type. 252.It memstat_get_countlimit 253If the memory type has an administrative limit on the number of simultaneous 254allocations, return it. 255.It memstat_get_byteslimit 256If the memory type has an administrative limit on the number of bytes of 257memory that may be simultaenously allocated for the memory type, return it. 258.It memstat_get_sizemask 259If the memory type supports variable allocation sizes, return a bitmask of 260sizes allocated for the memory type. 261.It memstat_get_size 262If the memory type supports a fixed allocation size, return that size. 263.It memstat_get_memalloced 264Return the total number of bytes allocated for the memory type over its 265lifetime. 266.It memstat_get_memfreed 267Return the total number of bytes freed for the memory type over its lifetime. 268.It memstat_get_numallocs 269Return the total number of allocations for the memory type over its lifetime. 270.It memstat_get_numfrees 271Return the total number of frees for the memory type over its lifetime. 272.It memstat_get_bytes 273Return the current number of bytes allocated to the memory type. 274.It memstat_get_count 275Return the current number of allocations for the memory type. 276.It memstat_get_free 277If the memory allocator supports a cache, return the number of items in the 278cache. 279.It memstat_get_failures 280If the memory allocator and type permit allocation failures, return the 281number of allocation failures measured. 282.It memstat_get_caller_pointer 283Return a caller-owned pointer for the memory type. 284.It memstat_set_caller_pointer 285Set a caller-owned pointer for the memory type. 286.It memstat_get_caller_uint64 287Return a caller-owned integer for the memory type. 288.It memstat_set_caller_uint64 289Set a caller-owned integer for the memory type. 290.It memstat_get_zonefree 291If the memory allocator supports a multi-level allocation structure, return 292the number of cached items in the zone. 293These items will be in a fully constructed state available for immediate 294use. 295.It memstat_get_kegfree 296If the memory allocator supports a multi-level allocation structure, return 297the number of cached items in the keg. 298These items may be in a partially constructed state, and may require further 299processing before they can be made available for use. 300.It memstat_get_percpu_memalloced 301If the memory allocator supports per-CPU statistics, return the number of 302bytes of memory allocated for the memory type on the CPU over its lifetime. 303.It memstat_get_percpu_memfreed 304If the memory allocator supports per-CPU statistics, return the number of 305bytes of memory freed from the memory type on the CPU over its lifetime. 306.It memstat_get_percpu_numallocs 307If the memory allocator supports per-CPU statistics, return the number of 308allocations for the memory type on the CPU over its lifetime. 309.It memstat_get_percpu_numfrees 310If the memory allocator supports per-CPU statistics, return the number of 311frees for the memory type on the CPU over its lifetime. 312.It memstat_get_percpu_sizemask 313If the memory allocator supports variable size memory allocation and per-CPU 314statistics, return the size bitmask for the memory type on the CPU. 315.It memstat_get_percpu_caller_pointer 316Return a caller-owned per-CPU pointer for the memory type. 317.It memstat_set_percpu_caller_pointer 318Set a caller-owned per-CPU pointer for the memory type. 319.It memstat_get_percpu_caller_uint64 320Return a caller-owned per-CPU integer for the memory type. 321.It memsttat_set_percpu_caller_uint64 322Set a caller-owned per-CPU integer for the memory type. 323.It memstat_get_percpu_free 324If the memory allocator supports a per-CPU cache, return the number of free 325items in the per-CPU cache of the designated CPU. 326.El 327.Sh RETURN VALUES 328.Nm 329functions fall into three categories: functions returning a pointer to an 330object, functions returning an integer return value, and functions 331implementing accessor methods returning data from a 332.Vt struct memory_type . 333.Pp 334Functions returning a pointer to an object will generally return 335.Dv NULL 336on failure. 337.Fn memstat_mtl_alloc 338will return an error value via 339.Va errno , 340which will consist of the value 341.Dv ENOMEM . 342Functions 343.Fn memstat_mtl_first , 344.Fn memstat_mtl_next , 345and 346.Fn memstat_mtl_find 347will return 348.Dv NULL 349when there is no entry or match in the list; however, this is not considered 350a failure mode and no error value is available. 351.Pp 352Functions returning a integer success valuye will return 353.Dv 0 354on success, or 355.Dv -1 356on failure. 357If a failure is returned, the list error access method, 358.Fn memstat_mtl_geterror , 359may be used to retrieve the error state. Possible error values are: 360.Pp 361.Bl -tag -width "MEMSTAT_ERROR_TOOMANYCPUS" -compact -offset wee 362.It Dv MEMSTAT_ERROR_UNDEFINED 363Undefined error. Occurs if 364.Fn memstat_mtl_geterror 365is called on a list before an error associated with the list has occurred. 366.It Dv MEMSTAT_ERROR_NOMEMORY 367Insufficient memory. Occurs if library calls to 368.Xr malloc 3 369fail, or if a system call to retrieve kernel statistics fails with 370.Er ENOMEM . 371.It Dv MEMSTAT_ERROR_VERSION 372Returned if the current version of 373.Nm 374is unable to interpret the statistics data returned by the kernel due to an 375explicit version mismatch, or to differences in data structures that cannot 376be reconciled. 377.It Dv MEMSTAT_ERROR_PERMISSION 378Returned if a statistics source returns 379.Va errno 380values of 381.Dv EACCES 382or 383.Dv EPERM . 384.It Dv MEMSTAT_ERROR_TOOMANYCPUS 385Returned if the compile-time limit on the number of CPUs in 386.Nm 387is lower than the number of CPUs returned by a statistics data source. 388.It Dv MEMSTAT_ERROR_DATAERROR 389Returned if 390.Nm 391is unable to interpret statistics data returned by the data source, even 392though there does not appear to be a version problem. 393.El 394.Pp 395Finally, functions returning data from a 396.Dt struct memory_type 397pointer are not permitted to fail, and directly return either a statistic 398or pointer to a string. |
|
| 229.Sh EXAMPLES 230Create a memory type list, query the 231.Xr uma 9 232memory allocator for available statistics, and print out the number of 233allocations performed by the 234.Dv Mbuf 235zone. 236.Bd -literal -offset indent --- 39 unchanged lines hidden --- | 399.Sh EXAMPLES 400Create a memory type list, query the 401.Xr uma 9 402memory allocator for available statistics, and print out the number of 403allocations performed by the 404.Dv Mbuf 405zone. 406.Bd -literal -offset indent --- 39 unchanged lines hidden --- |