Clean up #include's in the SYNOPSIS.
[dragonfly.git] / 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 int ksw_total ;
63 .It
64 .Va 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 CACHING
77 This function caches the nlist values for various kernel variables which
78 it reuses in successive calls.
79 You may call the function with
80 .Fa kd
81 ==
82 .Dv NULL
83 to clear the cache.
84 .Sh DIAGNOSTICS
85 If the load average was unobtainable, \-1 is returned; otherwise,
86 the number of swap devices actually retrieved is returned.
87 .Pp
88 If the name of the swap device does not fit in the static char buffer
89 in the structure, it is truncated.  The buffer is always zero terminated.
90 .Sh SEE ALSO
91 .Xr kvm 3