lib/libkvm/kvm_getpcpu.3

   1 .\" Copyright (c) 2008 Yahoo!, Inc.
   2 .\" All rights reserved.
   3 .\" Written by: John Baldwin <jhb@FreeBSD.org>
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of the author nor the names of any co-contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd August 19, 2008
  32 .Dt KVM_GETPCPU 3
  33 .Os
  34 .Sh NAME
  35 .Nm kvm_getmaxcpu ,
  36 .Nm kvm_getpcpu
  37 .Nd access per-CPU data
  38 .Sh LIBRARY
  39 .Lb libkvm
  40 .Sh SYNOPSIS
  41 .In sys/param.h
  42 .In sys/pcpu.h
  43 .In sys/sysctl.h
  44 .In kvm.h
  45 .Ft int
  46 .Fn kvm_getmaxcpu "kvm_t *kd"
  47 .Ft void *
  48 .Fn kvm_getpcpu "kvm_t *kd" "int cpu"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn kvm_getmaxcpu
  52 and
  53 .Fn kvm_getpcpu
  54 functions are used to access the per-CPU data of active processors in the
  55 kernel indicated by
  56 .Fa kd .
  57 The
  58 .Fn kvm_getmaxcpu
  59 function returns the maximum number of CPUs supported by the kernel.
  60 The
  61 .Fn kvm_getpcpu
  62 function returns a buffer holding the per-CPU data for a single CPU.
  63 This buffer is described by the
  64 .Vt "struct pcpu"
  65 type.
  66 The caller is responsible for releasing the buffer via a call to
  67 .Xr free 3
  68 when it is no longer needed.
  69 If
  70 .Fa cpu
  71 is not active, then
  72 .Dv NULL
  73 is returned instead.
  74 .Sh CACHING
  75 These functions cache the nlist values for various kernel variables which are
  76 reused in successive calls.
  77 You may call either function with
  78 .Fa kd
  79 set to
  80 .Dv NULL
  81 to clear this cache.
  82 .Sh RETURN VALUES
  83 On success, the
  84 .Fn kvm_getmaxcpu
  85 function returns the maximum number of CPUs supported by the kernel.
  86 If an error occurs,
  87 it returns -1 instead.
  88 .Pp
  89 On success, the
  90 .Fn kvm_getpcpu
  91 function returns a pointer to an allocated buffer or
  92 .Dv NULL.
  93 If an error occurs,
  94 it returns -1 instead.
  95 .Pp
  96 If either function encounters an error,
  97 then an error message may be retrieved via
  98 .Xr kvm_geterr 3.
  99 .Sh SEE ALSO
 100 .Xr free 3 ,
 101 .Xr kvm 3