lib/libmemstat/libmemstat.3

   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.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  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$
  26 .\"
  27 .Dd February 11, 2014
  28 .Dt LIBMEMSTAT 3
  29 .Os
  30 .Sh NAME
  31 .Nm libmemstat
  32 .Nd "library interface to retrieve kernel memory allocator statistics"
  33 .Sh LIBRARY
  34 .Lb libmemstat
  35 .Sh SYNOPSIS
  36 .In sys/types.h
  37 .In memstat.h
  38 .Ss General Functions
  39 .Ft "const char *"
  40 .Fn memstat_strerror "int error"
  41 .Ss Memory Type List Management Functions
  42 .Ft "struct memory_type_list *"
  43 .Fn memstat_mtl_alloc "void"
  44 .Ft "struct memory_type *"
  45 .Fn memstat_mtl_first "struct memory_type_list *list"
  46 .Ft "struct memory_type *"
  47 .Fn memstat_mtl_next "struct memory_type *mtp"
  48 .Ft "struct memory_type *"
  49 .Fo memstat_mtl_find
  50 .Fa "struct memory_type_list *list" "int allocator" "const char *name"
  51 .Fc
  52 .Ft void
  53 .Fn memstat_mtl_free "struct memory_type_list *list"
  54 .Ft int
  55 .Fn memstat_mtl_geterror "struct memory_type_list *list"
  56 .Ss Allocator Query Functions
  57 .Ft int
  58 .Fn memstat_kvm_all "struct memory_type_list *list" "void *kvm_handle"
  59 .Ft int
  60 .Fn memstat_kvm_malloc "struct memory_type_list *list" "void *kvm_handle"
  61 .Ft int
  62 .Fn memstat_kvm_uma "struct memory_type_list *list" "void *kvm_handle"
  63 .Ft int
  64 .Fn memstat_sysctl_all "struct memory_type_list *list" "int flags"
  65 .Ft int
  66 .Fn memstat_sysctl_malloc "struct memory_type_list *list" "int flags"
  67 .Ft int
  68 .Fn memstat_sysctl_uma "struct memory_type_list *list" "int flags"
  69 .Ss Memory Type Accessor Methods
  70 .Ft "const char *"
  71 .Fn memstat_get_name "const struct memory_type *mtp"
  72 .Ft int
  73 .Fn memstat_get_allocator "const struct memory_type *mtp"
  74 .Ft uint64_t
  75 .Fn memstat_get_countlimit "const struct memory_type *mtp"
  76 .Ft uint64_t
  77 .Fn memstat_get_byteslimit "const struct memory_type *mtp"
  78 .Ft uint64_t
  79 .Fn memstat_get_sizemask "const struct memory_type *mtp"
  80 .Ft uint64_t
  81 .Fn memstat_get_size "const struct memory_type *mtp"
  82 .Ft uint64_t
  83 .Fn memstat_get_rsize "const struct memory_type *mtp"
  84 .Ft uint64_t
  85 .Fn memstat_get_memalloced "const struct memory_type *mtp"
  86 .Ft uint64_t
  87 .Fn memstat_get_memfreed "const struct memory_type *mtp"
  88 .Ft uint64_t
  89 .Fn memstat_get_numallocs "const struct memory_type *mtp"
  90 .Ft uint64_t
  91 .Fn memstat_get_numfrees "const struct memory_type *mtp"
  92 .Ft uint64_t
  93 .Fn memstat_get_bytes "const struct memory_type *mtp"
  94 .Ft uint64_t
  95 .Fn memstat_get_count "const struct memory_type *mtp"
  96 .Ft uint64_t
  97 .Fn memstat_get_free "const struct memory_type *mtp"
  98 .Ft uint64_t
  99 .Fn memstat_get_failures "const struct memory_type *mtp"
 100 .Ft "void *"
 101 .Fn memstat_get_caller_pointer "const struct memory_type *mtp" "int index"
 102 .Ft void
 103 .Fo memstat_set_caller_pointer
 104 .Fa "struct memory_type *mtp" "int index" "void *value"
 105 .Fc
 106 .Ft uint64_t
 107 .Fn memstat_get_caller_uint64 "const struct memory_type *mtp" "int index"
 108 .Ft void
 109 .Fo memstat_set_caller_uint64
 110 .Fa "struct memory_type *mtp" "int index" "uint64_t value"
 111 .Fc
 112 .Ft uint64_t
 113 .Fn memstat_get_zonefree "const struct memory_type *mtp"
 114 .Ft uint64_t
 115 .Fn memstat_get_kegfree "const struct memory_type *mtp"
 116 .Ft uint64_t
 117 .Fn memstat_get_percpu_memalloced "const struct memory_type *mtp" "int cpu"
 118 .Ft uint64_t
 119 .Fn memstat_get_percpu_memfreed "const struct memory_type *mtp" "int cpu"
 120 .Ft uint64_t
 121 .Fn memstat_get_percpu_numallocs "const struct memory_type *mtp" "int cpu"
 122 .Ft uint64_t
 123 .Fn memstat_get_percpu_numfrees "const struct memory_type *mtp" "int cpu"
 124 .Ft uint64_t
 125 .Fn memstat_get_percpu_sizemask "const struct memory_type *mtp" "int cpu"
 126 .Ft "void *"
 127 .Fo memstat_get_percpu_caller_pointer
 128 .Fa "const struct memory_type *mtp" "int cpu" "int index"
 129 .Fc
 130 .Ft void
 131 .Fo memstat_set_percpu_caller_pointer
 132 .Fa "struct memory_type *mtp" "int cpu" "int index" "void *value"
 133 .Fc
 134 .Ft uint64_t
 135 .Fo memstat_get_percpu_caller_uint64
 136 .Fa "const struct memory_type *mtp" "int cpu" "int index"
 137 .Fc
 138 .Ft void
 139 .Fo memstat_set_percpu_caller_uint64
 140 .Fa "struct memory_type *mtp" "int cpu" "int index" "uint64_t value"
 141 .Fc
 142 .Ft uint64_t
 143 .Fn memstat_get_percpu_free "const struct memory_type *mtp" "int cpu"
 144 .Sh DESCRIPTION
 145 .Nm
 146 provides an interface to retrieve kernel memory allocator statistics, for
 147 the purposes of debugging and system monitoring, insulating applications
 148 from implementation details of the allocators, and allowing a tool to
 149 transparently support multiple allocators.
 150 .Nm
 151 supports both retrieving a single statistics snapshot, as well as
 152 incrementally updating statistics for long-term monitoring.
 153 .Pp
 154 .Nm
 155 describes each memory type using a
 156 .Vt "struct memory_type" ,
 157 an opaque memory type accessed by the application using accessor functions
 158 in the library.
 159 .Nm
 160 returns and updates chains of
 161 .Vt "struct memory_type"
 162 via a
 163 .Vt "struct memory_type_list" ,
 164 which will be allocated by calling
 165 .Fn memstat_mtl_alloc ,
 166 and freed on completion using
 167 .Fn memstat_mtl_free .
 168 Lists of memory types are populated via calls that query the kernel for
 169 statistics information; currently:
 170 .Fn memstat_kvm_all ,
 171 .Fn memstat_kvm_malloc ,
 172 .Fn memstat_kvm_uma ,
 173 .Fn memstat_sysctl_all ,
 174 .Fn memstat_sysctl_uma ,
 175 and
 176 .Fn memstat_sysctl_malloc .
 177 Repeated calls will incrementally update the list of memory types, permitting
 178 tracking over time without recreating all list state.
 179 If an error is detected during a query call, error condition information may
 180 be retrieved using
 181 .Fn memstat_mtl_geterror ,
 182 and converted to a user-readable string using
 183 .Fn memstat_strerror .
 184 .Pp
 185 Freeing the list will free all memory type data in the list, and so
 186 invalidates any outstanding pointers to entries in the list.
 187 .Vt "struct memory_type"
 188 entries in the list may be iterated over using
 189 .Fn memstat_mtl_first
 190 and
 191 .Fn memstat_mtl_next ,
 192 which respectively return the first entry in a list, and the next entry in a
 193 list.
 194 .Fn memstat_mtl_find ,
 195 which will return a pointer to the first entry matching the passed
 196 parameters.
 197 .Pp
 198 A series of accessor methods is provided to access fields of the structure,
 199 including retrieving statistics and properties, as well as setting of caller
 200 owned fields.
 201 Direct application access to the data structure fields is not supported.
 202 .Ss Library Vt memory_type Ss Fields
 203 Each
 204 .Vt "struct memory_type"
 205 holds a description of the memory type, including its name and the allocator
 206 it is managed by, as well as current statistics on use.
 207 Some statistics are directly measured, others are derived from directly
 208 measured statistics.
 209 Certain high level statistics are present across all available allocators,
 210 such as the number of allocation and free operations; other measurements,
 211 such as the quantity of free items in per-CPU caches, or administrative
 212 limit on the number of allocations, is available only for specific
 213 allocators.
 214 .Ss Caller Vt memory_type Ss Fields
 215 .Vt "struct memory_type"
 216 includes fields to allow the application to store data, in the form of
 217 pointers and 64-bit integers, with memory types.
 218 For example, the application author might make use of one of the caller
 219 pointers to reference a more complex data structure tracking long-term
 220 behavior of the memory type, or a window system object that is used to
 221 render the state of the memory type.
 222 General and per-CPU storage is provided with each
 223 .Vt "struct memory_type"
 224 in the form of an array of pointers and integers.
 225 The array entries are accessed via the
 226 .Fa index
 227 argument to the get and set accessor methods.
 228 Possible values of
 229 .Fa index
 230 range between
 231 0
 232 and
 233 .Dv MEMSTAT_MAXCALLER .
 234 .Pp
 235 Caller-owned fields are initialized to
 236 0
 237 or
 238 .Dv NULL
 239 when a new
 240 .Vt "struct memory_type"
 241 is allocated and attached to a memory type list; these fields retain their
 242 values across queries that update library-owned fields.
 243 .Ss Allocator Types
 244 Currently,
 245 .Nm
 246 supports two kernel allocators:
 247 .Dv ALLOCATOR_UMA
 248 for
 249 .Xr uma 9 ,
 250 and
 251 .Dv ALLOCATOR_MALLOC
 252 for
 253 .Xr malloc 9 .
 254 These values may be passed to
 255 .Fn memstat_mtl_find ,
 256 and will be returned by
 257 .Fn memstat_get_allocator .
 258 Two additional constants in the allocator name space are defined:
 259 .Dv ALLOCATOR_UNKNOWN ,
 260 which will only be returned as a result of a library error, and
 261 .Dv ALLOCATOR_ANY ,
 262 which can be used to specify that returning types matching any allocator is
 263 permittable from
 264 .Fn memstat_mtl_find .
 265 .Ss Access Method List
 266 The following accessor methods are defined, of which some will be valid for
 267 a given memory type:
 268 .Bl -tag -width indent
 269 .It Fn memstat_get_name
 270 Return a pointer to the name of the memory type.
 271 Memory for the name is owned by
 272 .Nm
 273 and will be valid through a call to
 274 .Fn memstat_mtl_free .
 275 Note that names will be unique with respect to a single allocator, but that
 276 the same name might be used by different memory types owned by different
 277 memory allocators.
 278 .It Fn memstat_get_allocator
 279 Return an integer identifier for the memory allocator that owns the memory
 280 type.
 281 .It Fn memstat_get_countlimit
 282 If the memory type has an administrative limit on the number of simultaneous
 283 allocations, return it.
 284 .It Fn memstat_get_byteslimit
 285 If the memory type has an administrative limit on the number of bytes of
 286 memory that may be simultaneously allocated for the memory type, return it.
 287 .It Fn memstat_get_sizemask
 288 If the memory type supports variable allocation sizes, return a bitmask of
 289 sizes allocated for the memory type.
 290 .It Fn memstat_get_size
 291 If the memory type supports a fixed allocation size, return that size.
 292 .It Fn memstat_get_rsize
 293 If the memory type supports a fixed allocation size, return real size
 294 of an allocation.
 295 Real size can exceed requested size due to alignment constraints or
 296 implicit padding.
 297 .It Fn memstat_get_memalloced
 298 Return the total number of bytes allocated for the memory type over its
 299 lifetime.
 300 .It Fn memstat_get_memfreed
 301 Return the total number of bytes freed for the memory type over its lifetime.
 302 .It Fn memstat_get_numallocs
 303 Return the total number of allocations for the memory type over its lifetime.
 304 .It Fn memstat_get_numfrees
 305 Return the total number of frees for the memory type over its lifetime.
 306 .It Fn memstat_get_bytes
 307 Return the current number of bytes allocated to the memory type.
 308 .It Fn memstat_get_count
 309 Return the current number of allocations for the memory type.
 310 .It Fn memstat_get_free
 311 If the memory allocator supports a cache, return the number of items in the
 312 cache.
 313 .It Fn memstat_get_failures
 314 If the memory allocator and type permit allocation failures, return the
 315 number of allocation failures measured.
 316 .It Fn memstat_get_caller_pointer
 317 Return a caller-owned pointer for the memory type.
 318 .It Fn memstat_set_caller_pointer
 319 Set a caller-owned pointer for the memory type.
 320 .It Fn memstat_get_caller_uint64
 321 Return a caller-owned integer for the memory type.
 322 .It Fn memstat_set_caller_uint64
 323 Set a caller-owned integer for the memory type.
 324 .It Fn memstat_get_zonefree
 325 If the memory allocator supports a multi-level allocation structure, return
 326 the number of cached items in the zone.
 327 These items will be in a fully constructed state available for immediate
 328 use.
 329 .It Fn memstat_get_kegfree
 330 If the memory allocator supports a multi-level allocation structure, return
 331 the number of cached items in the keg.
 332 These items may be in a partially constructed state, and may require further
 333 processing before they can be made available for use.
 334 .It Fn memstat_get_percpu_memalloced
 335 If the memory allocator supports per-CPU statistics, return the number of
 336 bytes of memory allocated for the memory type on the CPU over its lifetime.
 337 .It Fn memstat_get_percpu_memfreed
 338 If the memory allocator supports per-CPU statistics, return the number of
 339 bytes of memory freed from the memory type on the CPU over its lifetime.
 340 .It Fn memstat_get_percpu_numallocs
 341 If the memory allocator supports per-CPU statistics, return the number of
 342 allocations for the memory type on the CPU over its lifetime.
 343 .It Fn memstat_get_percpu_numfrees
 344 If the memory allocator supports per-CPU statistics, return the number of
 345 frees for the memory type on the CPU over its lifetime.
 346 .It Fn memstat_get_percpu_sizemask
 347 If the memory allocator supports variable size memory allocation and per-CPU
 348 statistics, return the size bitmask for the memory type on the CPU.
 349 .It Fn memstat_get_percpu_caller_pointer
 350 Return a caller-owned per-CPU pointer for the memory type.
 351 .It Fn memstat_set_percpu_caller_pointer
 352 Set a caller-owned per-CPU pointer for the memory type.
 353 .It Fn memstat_get_percpu_caller_uint64
 354 Return a caller-owned per-CPU integer for the memory type.
 355 .It Fn memstat_set_percpu_caller_uint64
 356 Set a caller-owned per-CPU integer for the memory type.
 357 .It Fn memstat_get_percpu_free
 358 If the memory allocator supports a per-CPU cache, return the number of free
 359 items in the per-CPU cache of the designated CPU.
 360 .El
 361 .Sh RETURN VALUES
 362 .Nm
 363 functions fall into three categories: functions returning a pointer to an
 364 object, functions returning an integer return value, and functions
 365 implementing accessor methods returning data from a
 366 .Vt "struct memory_type" .
 367 .Pp
 368 Functions returning a pointer to an object will generally return
 369 .Dv NULL
 370 on failure.
 371 .Fn memstat_mtl_alloc
 372 will return an error value via
 373 .Va errno ,
 374 which will consist of the value
 375 .Er ENOMEM .
 376 Functions
 377 .Fn memstat_mtl_first ,
 378 .Fn memstat_mtl_next ,
 379 and
 380 .Fn memstat_mtl_find
 381 will return
 382 .Dv NULL
 383 when there is no entry or match in the list; however, this is not considered
 384 a failure mode and no error value is available.
 385 .Pp
 386 Functions returning an integer success value will return
 387 0
 388 on success, or
 389 \-1
 390 on failure.
 391 If a failure is returned, the list error access method,
 392 .Fn memstat_mtl_geterror ,
 393 may be used to retrieve the error state.
 394 The string representation of the error may be retrieved using
 395 .Fn memstat_strerror .
 396 Possible error values are:
 397 .Bl -tag -width ".Dv MEMSTAT_ERROR_KVM_SHORTREAD"
 398 .It Dv MEMSTAT_ERROR_UNDEFINED
 399 Undefined error.
 400 Occurs if
 401 .Fn memstat_mtl_geterror
 402 is called on a list before an error associated with the list has occurred.
 403 .It Dv MEMSTAT_ERROR_NOMEMORY
 404 Insufficient memory.
 405 Occurs if library calls to
 406 .Xr malloc 3
 407 fail, or if a system call to retrieve kernel statistics fails with
 408 .Er ENOMEM .
 409 .It Dv MEMSTAT_ERROR_VERSION
 410 Returned if the current version of
 411 .Nm
 412 is unable to interpret the statistics data returned by the kernel due to an
 413 explicit version mismatch, or to differences in data structures that cannot
 414 be reconciled.
 415 .It Dv MEMSTAT_ERROR_PERMISSION
 416 Returned if a statistics source returns
 417 .Va errno
 418 values of
 419 .Er EACCES
 420 or
 421 .Er EPERM .
 422 .It Dv MEMSTAT_ERROR_DATAERROR
 423 Returned if
 424 .Nm
 425 is unable to interpret statistics data returned by the data source, even
 426 though there does not appear to be a version problem.
 427 .It Dv MEMSTAT_ERROR_KVM
 428 Returned if
 429 .Nm
 430 experiences an error while using
 431 .Xr kvm 3
 432 interfaces to query statistics data.
 433 Use
 434 .Xr kvm_geterr 3
 435 to retrieve the error.
 436 .It Dv MEMSTAT_ERROR_KVM_NOSYMBOL
 437 Returned if
 438 .Nm
 439 is unable to read a required symbol from the kernel being operated on.
 440 .It Dv MEMSTAT_ERROR_KVM_SHORTREAD
 441 Returned if
 442 .Nm
 443 attempts to read data from a live memory image or kernel core dump and
 444 insufficient data is returned.
 445 .El
 446 .Pp
 447 Finally, functions returning data from a
 448 .Vt "struct memory_type"
 449 pointer are not permitted to fail, and directly return either a statistic
 450 or pointer to a string.
 451 .Sh EXAMPLES
 452 Create a memory type list, query the
 453 .Xr uma 9
 454 memory allocator for available statistics, and print out the number of
 455 allocations performed by the
 456 .Dv mbuf
 457 zone.
 458 .Bd -literal -offset indent
 459 struct memory_type_list *mtlp;
 460 struct memory_type *mtp;
 461 uint64_t mbuf_count;
 462
 463 mtlp = memstat_mtl_alloc();
 464 if (mtlp == NULL)
 465     err(-1, "memstat_mtl_alloc");
 466 if (memstat_sysctl_uma(mtlp, 0) < 0)
 467     err(-1, "memstat_sysctl_uma");
 468 mtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf");
 469 if (mtp == NULL)
 470     errx(-1, "memstat_mtl_find: mbuf not found");
 471 mbuf_count = memstat_get_count(mtp);
 472 memstat_mtl_free(mtlp);
 473
 474 printf("mbufs: %llu\en", (unsigned long long)mbuf_count);
 475 .Ed
 476 .Sh SEE ALSO
 477 .Xr malloc 9 ,
 478 .Xr uma 9
 479 .Sh HISTORY
 480 The
 481 .Nm
 482 library appeared in
 483 .Fx 6.0 .
 484 .Sh AUTHORS
 485 The kernel memory allocator changes necessary to support a general purpose
 486 monitoring library, along with the library, were written by
 487 .An Robert Watson Aq Mt rwatson@FreeBSD.org .
 488 .Sh BUGS
 489 There are memory allocators in the kernel, such as the VM page allocator
 490 and
 491 .Nm sf_buf
 492 allocator, which are not currently supported by
 493 .Nm .
 494 .Pp
 495 Once a memory type is present on a memory type list, it will not be removed
 496 even if the kernel no longer presents information on the type via its
 497 monitoring interfaces.
 498 In order to flush removed memory types, it is necessary to free the entire
 499 list and allocate a new one.