Update some copyright notices to become more legal compliant.
[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 kvm.h
20 .Ft int
21 .Fn kvm_getswapinfo "kvm_t *kd" "struct kvm_swap *" "int maxswap" "int flags"
22 .Sh DESCRIPTION
23 The
24 .Fn kvm_getswapinfo
25 function fills an array of
26 .Vt kvm_swap
27 structures with swap summary
28 information for each swap device, for up to
29 .Fa maxswap
30 \- 1 devices.
31 The number of devices, up to
32 .Fa maxswap
33 \- 1, is returned.  A grand
34 total of all swap devices (including any devices that go beyond
35 .Fa maxswap
36 \- 1) is returned in one additional array entry.  This
37 entry is not counted in the return value.
38 Thus, if you specify a
39 .Fa maxswap
40 value of 1, the function will typically return the
41 value 0 and the single
42 .Vt kvm_swap
43 structure will be filled with
44 the grand total over all swap devices.  The grand total is calculated
45 from all available swap devices whether or not you made room
46 for them all in the array.
47 The grand total is returned.
48 .Pp
49 The flags argument is currently unused and must be passed as 0.
50 .Pp
51 If an error occurs, -1 is returned.
52 .Pp
53 Each swap partition and the grand total is summarized in the
54 .Vt kvm_swap
55 structure.  This structure contains the following fields:
56 .Pp
57 .Bl -item -offset indent -compact
58 .It
59 .Va char ksw_devname[] ;
60 .It
61 .Va int ksw_total ;
62 .It
63 .Va int ksw_used ;
64 .It
65 .Va int ksw_flags ;
66 .El
67 .Pp
68 Values are in
69 .Dv PAGE_SIZE Ns 'd
70 chunks (see
71 .Xr getpagesize 3 ) .
72 .Va ksw_flags
73 contains
74 a copy of the swap device flags.
75 .Sh CACHING
76 This function caches the nlist values for various kernel variables which
77 it reuses in successive calls.
78 You may call the function with
79 .Fa kd
80 ==
81 .Dv NULL
82 to clear the cache.
83 .Sh DIAGNOSTICS
84 If the load average was unobtainable, \-1 is returned; otherwise,
85 the number of swap devices actually retrieved is returned.
86 .Pp
87 If the name of the swap device does not fit in the static char buffer
88 in the structure, it is truncated.  The buffer is always zero terminated.
89 .Sh SEE ALSO
90 .Xr kvm 3