lib/libkvm/kvm_getswapinfo.3

   1 .\" Copyright (c) 1999 Matthew Dillon.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided under the terms of the BSD
   5 .\" Copyright as found in /usr/src/COPYRIGHT in the FreeBSD source tree.
   6 .\"
   7 .\" $FreeBSD: src/lib/libkvm/kvm_getswapinfo.3,v 1.5.2.6 2001/12/17 10:08:30 ru Exp $
   8 .\" $DragonFly: src/lib/libkvm/kvm_getswapinfo.3,v 1.3 2004/06/28 02:57:10 drhodus Exp $
   9 .\"
  10 .Dd January 22, 1999
  11 .Dt KVM_SWAPINFO 3
  12 .Os
  13 .Sh NAME
  14 .Nm kvm_getswapinfo
  15 .Nd return swap summary statistics for the system
  16 .Sh LIBRARY
  17 .Lb libkvm
  18 .Sh SYNOPSIS
  19 .In sys/types.h
  20 .In kvm.h
  21 .Ft int
  22 .Fn kvm_getswapinfo "kvm_t *kd" "struct kvm_swap *" "int maxswap" "int flags"
  23 .Sh DESCRIPTION
  24 The
  25 .Fn kvm_getswapinfo
  26 function fills an array of
  27 .Vt kvm_swap
  28 structures with swap summary
  29 information for each swap device, for up to
  30 .Fa maxswap
  31 \- 1 devices.
  32 The number of devices, up to
  33 .Fa maxswap
  34 \- 1, is returned.  A grand
  35 total of all swap devices (including any devices that go beyond
  36 .Fa maxswap
  37 \- 1) is returned in one additional array entry.  This
  38 entry is not counted in the return value.
  39 Thus, if you specify a
  40 .Fa maxswap
  41 value of 1, the function will typically return the
  42 value 0 and the single
  43 .Vt kvm_swap
  44 structure will be filled with
  45 the grand total over all swap devices.  The grand total is calculated
  46 from all available swap devices whether or not you made room
  47 for them all in the array.
  48 The grand total is returned.
  49 .Pp
  50 The flags argument is currently unused and must be passed as 0.
  51 .Pp
  52 If an error occurs, -1 is returned.
  53 .Pp
  54 Each swap partition and the grand total is summarized in the
  55 .Vt kvm_swap
  56 structure.  This structure contains the following fields:
  57 .Pp
  58 .Bl -item -offset indent -compact
  59 .It
  60 .Va char ksw_devname[] ;
  61 .It
  62 .Va u_int ksw_total ;
  63 .It
  64 .Va u_int ksw_used ;
  65 .It
  66 .Va int ksw_flags ;
  67 .El
  68 .Pp
  69 Values are in
  70 .Dv PAGE_SIZE Ns 'd
  71 chunks (see
  72 .Xr getpagesize 3 ) .
  73 .Va ksw_flags
  74 contains
  75 a copy of the swap device flags.
  76 .Sh WARNING
  77 At the current juncture this structure can only represent up to 16TB of
  78 swap per device, and the totalizer field will overflow at 16TB (4TB per
  79 device).  The fields need to be converted to long's.
  80 .Sh CACHING
  81 This function caches the nlist values for various kernel variables which
  82 it reuses in successive calls.
  83 You may call the function with
  84 .Fa kd
  85 ==
  86 .Dv NULL
  87 to clear the cache.
  88 .Sh DIAGNOSTICS
  89 If the load average was unobtainable, \-1 is returned; otherwise,
  90 the number of swap devices actually retrieved is returned.
  91 .Pp
  92 If the name of the swap device does not fit in the static char buffer
  93 in the structure, it is truncated.  The buffer is always zero terminated.
  94 .Sh SEE ALSO
  95 .Xr kvm 3