lib/libkvm/kvm_getcptime.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_GETCPTIME 3
  33 .Os
  34 .Sh NAME
  35 .Nm kvm_getcptime
  36 .Nd fetch global CPU time statistics
  37 .Sh LIBRARY
  38 .Lb libkvm
  39 .Sh SYNOPSIS
  40 .In sys/param.h
  41 .In sys/resource.h
  42 .In sys/sysctl.h
  43 .In kvm.h
  44 .Ft int
  45 .Fn kvm_getcptime "kvm_t *kd" "long *cp_time"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn kvm_getcptime
  49 function stores the global CPU time statistics from the kernel
  50 .Fa kd
  51 in the array of counters pointed to by
  52 .Fa cp_time .
  53 Note that
  54 .Fa cp_time
  55 should point to an array of
  56 .Dv CPUSTATES
  57 long integers.
  58 The format of the counters is identical to that output by the
  59 .Va kern.cp_time
  60 sysctl.
  61 .Sh CACHING
  62 This function caches the nlist values for various kernel variables which it
  63 reuses in successive calls.
  64 You may call the function with
  65 .Fa kd
  66 set to
  67 .Dv NULL
  68 to clear this cache.
  69 .Sh RETURN VALUES
  70 The
  71 .Nm kvm_getcptime
  72 function returns 0 on success and -1 on failure.
  73 If an error occurs,
  74 then an error message may be retrieved via
  75 .Xr kvm_geterr 3 .
  76 .Sh SEE ALSO
  77 .Xr kvm 3