rtems/rtems-libbsd
1
0
Fork 0
mirror of https://git.rtems.org/rtems-libbsd/ synced 2025-05-14 05:09:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add libkvm man pages

Browse Source
This commit is contained in:
Joel Sherrill 2012-10-22 10:52:19 -05:00
parent 4b8600a006
commit e9aaadb911
10 changed files with 1079 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
freebsd-userspace/lib/libkvm/kvm_getcptime.3 Normal file
View File

@ -0,0 +1,77 @@
.\" Copyright (c) 2008 Yahoo!, Inc.
.\" All rights reserved.
.\" Written by: John Baldwin <jhb@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the author nor the names of any co-contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 19, 2008
.Dt KVM_GETCPTIME 3
.Os
.Sh NAME
.Nm kvm_getcptime
.Nd fetch global CPU time statistics
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In sys/param.h
.In sys/resource.h
.In sys/sysctl.h
.In kvm.h
.Ft int
.Fn kvm_getcptime "kvm_t *kd" "long *cp_time"
.Sh DESCRIPTION
The
.Fn kvm_getcptime
function stores the global CPU time statistics from the kernel
.Fa kd
in the array of counters pointed to by
.Fa cp_time .
Note that
.Fa cp_time
should point to an array of
.Dv CPUSTATES
long integers.
The format of the counters is identical to that output by the
.Va kern.cp_time
sysctl.
.Sh CACHING
This function caches the nlist values for various kernel variables which it
reuses in successive calls.
You may call the function with
.Fa kd
set to
.Dv NULL
to clear this cache.
.Sh RETURN VALUES
The
.Nm kvm_getcptime
function returns 0 on success and -1 on failure.
If an error occurs,
then an error message may be retrieved via
.Xr kvm_geterr 3 .
.Sh SEE ALSO
.Xr kvm 3

78
freebsd-userspace/lib/libkvm/kvm_geterr.3 Normal file
View File

@ -0,0 +1,78 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_geterr.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt KVM_GETERR 3
.Os
.Sh NAME
.Nm kvm_geterr
.Nd get error message on kvm descriptor
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.Ft char *
.Fn kvm_geterr "kvm_t *kd"
.Sh DESCRIPTION
This function returns a string describing the most recent error condition
on the descriptor
.Fa kd .
The results are undefined if the most recent
.Xr kvm 3
library call did not produce an error.
The string returned is stored in memory owned by
.Xr kvm 3
so the message should be copied out and saved elsewhere if necessary.
.Sh SEE ALSO
.Xr kvm 3 ,
.Xr kvm_close 3 ,
.Xr kvm_getargv 3 ,
.Xr kvm_getenvv 3 ,
.Xr kvm_getprocs 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3
.Sh BUGS
This routine cannot be used to access error conditions due to a failed
.Fn kvm_openfiles
call, since failure is indicated by returning a
.Dv NULL
descriptor.
Therefore, errors on open are output to the special error buffer
passed to
.Fn kvm_openfiles .
This option is not available to
.Fn kvm_open .

87
freebsd-userspace/lib/libkvm/kvm_getfiles.3 Normal file
View File

@ -0,0 +1,87 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_getfiles.3 8.2 (Berkeley) 4/19/94
.\" $FreeBSD$
.\"
.Dd April 19, 1994
.Dt KVM_GETFILES 3
.Os
.Sh NAME
.Nm kvm_getfiles
.Nd survey open files
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.In sys/types.h
.Fd #define _KERNEL
.In sys/file.h
.Fd #undef _KERNEL
.\" .Fa kvm_t *kd
.Ft char *
.Fn kvm_getfiles "kvm_t *kd" "int op" "int arg" "int *cnt"
.Sh DESCRIPTION
The
.Fn kvm_getfiles
function returns a (sub-)set of the open files in the kernel indicated by
.Fa kd .
The
.Fa op
and
.Fa arg
arguments constitute a predicate which limits the set of files
returned.
No predicates are currently defined.
.Pp
The number of files found is returned in the reference parameter
.Fa cnt .
The files are returned as a contiguous array of file structures,
preceded by the address of the first file entry in the kernel.
This memory is owned by kvm and is not guaranteed to be persistent across
subsequent kvm library calls.
Data should be copied out if it needs to be
saved.
.Sh RETURN VALUES
The
.Fn kvm_getfiles
function will return NULL on failure.
.Sh SEE ALSO
.Xr kvm 3 ,
.Xr kvm_close 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3
.Sh BUGS
This routine does not belong in the kvm interface.

62
freebsd-userspace/lib/libkvm/kvm_getloadavg.3 Normal file
View File

@ -0,0 +1,62 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_getloadavg.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt KVM_GETLOADAVG 3
.Os
.Sh NAME
.Nm kvm_getloadavg
.Nd get load average of the system
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.Ft int
.Fn kvm_getloadavg "kvm_t *kd" "double loadavg[]" "int nelem"
.Sh DESCRIPTION
The
.Fn kvm_getloadavg
function returns the number of processes in the system run queue
of the kernel indicated by
.Fa kd ,
averaged over various periods of time.
Up to
.Fa nelem
samples are retrieved and assigned to successive elements of
.Fa loadavg Ns Bq .
The system imposes a maximum of 3 samples, representing averages
over the last 1, 5, and 15 minutes, respectively.
.Sh DIAGNOSTICS
If the load average was unobtainable, \-1 is returned; otherwise,
the number of samples actually retrieved is returned.
.Sh SEE ALSO
.Xr uptime 1 ,
.Xr getloadavg 3 ,
.Xr kvm 3

101
freebsd-userspace/lib/libkvm/kvm_getpcpu.3 Normal file
View File

@ -0,0 +1,101 @@
.\" Copyright (c) 2008 Yahoo!, Inc.
.\" All rights reserved.
.\" Written by: John Baldwin <jhb@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the author nor the names of any co-contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 19, 2008
.Dt KVM_GETPCPU 3
.Os
.Sh NAME
.Nm kvm_getmaxcpu ,
.Nm kvm_getpcpu
.Nd access per-CPU data
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In sys/param.h
.In sys/pcpu.h
.In sys/sysctl.h
.In kvm.h
.Ft int
.Fn kvm_getmaxcpu "kvm_t *kd"
.Ft void *
.Fn kvm_getpcpu "kvm_t *kd" "int cpu"
.Sh DESCRIPTION
The
.Fn kvm_getmaxcpu
and
.Fn kvm_getpcpu
functions are used to access the per-CPU data of active processors in the
kernel indicated by
.Fa kd .
The
.Fn kvm_getmaxcpu
function returns the maximum number of CPUs supported by the kernel.
The
.Fn kvm_getpcpu
function returns a buffer holding the per-CPU data for a single CPU.
This buffer is described by the
.Vt "struct pcpu"
type.
The caller is responsible for releasing the buffer via a call to
.Xr free 3
when it is no longer needed.
If
.Fa cpu
is not active, then
.Dv NULL
is returned instead.
.Sh CACHING
These functions cache the nlist values for various kernel variables which are
reused in successive calls.
You may call either function with
.Fa kd
set to
.Dv NULL
to clear this cache.
.Sh RETURN VALUES
On success, the
.Fn kvm_getmaxcpu
function returns the maximum number of CPUs supported by the kernel.
If an error occurs,
it returns -1 instead.
.Pp
On success, the
.Fn kvm_getpcpu
function returns a pointer to an allocated buffer or
.Dv NULL.
If an error occurs,
it returns -1 instead.
.Pp
If either function encounters an error,
then an error message may be retrieved via
.Xr kvm_geterr 3.
.Sh SEE ALSO
.Xr free 3 ,
.Xr kvm 3

181
freebsd-userspace/lib/libkvm/kvm_getprocs.3 Normal file
View File

@ -0,0 +1,181 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_getprocs.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd September 27, 2003
.Dt KVM_GETPROCS 3
.Os
.Sh NAME
.Nm kvm_getprocs ,
.Nm kvm_getargv ,
.Nm kvm_getenvv
.Nd access user process state
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.In sys/param.h
.In sys/sysctl.h
.In sys/user.h
.\" .Fa kvm_t *kd
.Ft struct kinfo_proc *
.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
.Ft char **
.Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
.Ft char **
.Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
.Sh DESCRIPTION
The
.Fn kvm_getprocs
function returns a (sub-)set of active processes in the kernel indicated by
.Fa kd .
The
.Fa op
and
.Fa arg
arguments constitute a predicate which limits the set of processes
returned.
The value of
.Fa op
describes the filtering predicate as follows:
.Pp
.Bl -tag -width 20n -offset indent -compact
.It Dv KERN_PROC_ALL
all processes and kernel visible threads
.It Dv KERN_PROC_PROC
all processes, without threads
.It Dv KERN_PROC_PID
processes with process ID
.Fa arg
.It Dv KERN_PROC_PGRP
processes with process group
.Fa arg
.It Dv KERN_PROC_SESSION
processes with session
.Fa arg
.It Dv KERN_PROC_TTY
processes with TTY
.Fa arg
.It Dv KERN_PROC_UID
processes with effective user ID
.Fa arg
.It Dv KERN_PROC_RUID
processes with real user ID
.Fa arg
.It Dv KERN_PROC_INC_THREAD
modifier to return all kernel visible threads when filtering
by process ID, process group, TTY, user ID, and real user ID
.El
.Pp
The number of processes found is returned in the reference parameter
.Fa cnt .
The processes are returned as a contiguous array of kinfo_proc structures.
This memory is locally allocated, and subsequent calls to
.Fn kvm_getprocs
and
.Fn kvm_close
will overwrite this storage.
.Pp
The
.Fn kvm_getargv
function returns a null-terminated argument vector that corresponds to the
command line arguments passed to process indicated by
.Fa p .
Most likely, these arguments correspond to the values passed to
.Xr exec 3
on process creation.
This information is, however,
deliberately under control of the process itself.
Note that the original command name can be found, unaltered,
in the p_comm field of the process structure returned by
.Fn kvm_getprocs .
.Pp
The
.Fa nchr
argument indicates the maximum number of characters, including null bytes,
to use in building the strings.
If this amount is exceeded, the string
causing the overflow is truncated and the partial result is returned.
This is handy for programs like
.Xr ps 1
and
.Xr w 1
that print only a one line summary of a command and should not copy
out large amounts of text only to ignore it.
If
.Fa nchr
is zero, no limit is imposed and all argument strings are returned in
their entirety.
.Pp
The memory allocated to the argv pointers and string storage
is owned by the kvm library.
Subsequent
.Fn kvm_getprocs
and
.Xr kvm_close 3
calls will clobber this storage.
.Pp
The
.Fn kvm_getenvv
function is similar to
.Fn kvm_getargv
but returns the vector of environment strings.
This data is
also alterable by the process.
.Sh RETURN VALUES
The
.Fn kvm_getprocs ,
.Fn kvm_getargv ,
and
.Fn kvm_getenvv
functions return
.Dv NULL
on failure.
.Sh SEE ALSO
.Xr kvm 3 ,
.Xr kvm_close 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3
.Sh BUGS
These routines do not belong in the kvm interface.
.Pp
In order for
.Xr kvm_getenvv 3
to function correctly,
.Xr procfs 5
must be mounted on
.Pa /proc .

111
freebsd-userspace/lib/libkvm/kvm_getswapinfo.3 Normal file
View File

@ -0,0 +1,111 @@
.\" Copyright (C) 1999 Matthew Dillon. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 22, 1999
.Dt KVM_SWAPINFO 3
.Os
.Sh NAME
.Nm kvm_getswapinfo
.Nd return swap summary statistics for the system
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.Ft int
.Fn kvm_getswapinfo "kvm_t *kd" "struct kvm_swap *" "int maxswap" "int flags"
.Sh DESCRIPTION
The
.Fn kvm_getswapinfo
function fills an array of
.Vt kvm_swap
structures with swap summary
information for each swap device, for up to
.Fa maxswap
\- 1 devices.
The number of devices, up to
.Fa maxswap
\- 1, is returned.
A grand
total of all swap devices (including any devices that go beyond
.Fa maxswap
\- 1) is returned in one additional array entry.
This
entry is not counted in the return value.
Thus, if you specify a
.Fa maxswap
value of 1, the function will typically return the
value 0 and the single
.Vt kvm_swap
structure will be filled with
the grand total over all swap devices.
The grand total is calculated
from all available swap devices whether or not you made room
for them all in the array.
The grand total is returned.
.Pp
The flags argument is currently unused and must be passed as 0.
.Pp
If an error occurs, -1 is returned.
.Pp
Each swap partition and the grand total is summarized in the
.Vt kvm_swap
structure.
This structure contains the following fields:
.Pp
.Bl -item -offset indent -compact
.It
.Va char ksw_devname[] ;
.It
.Va int ksw_total ;
.It
.Va int ksw_used ;
.It
.Va int ksw_flags ;
.El
.Pp
Values are in
.Dv PAGE_SIZE Ns 'd
chunks (see
.Xr getpagesize 3 ) .
.Va ksw_flags
contains
a copy of the swap device flags.
.Sh CACHING
This function caches the nlist values for various kernel variables which
it reuses in successive calls.
You may call the function with
.Fa kd
==
.Dv NULL
to clear the cache.
.Sh DIAGNOSTICS
If the load average was unobtainable, \-1 is returned; otherwise,
the number of swap devices actually retrieved is returned.
.Pp
If the name of the swap device does not fit in the static char buffer
in the structure, it is truncated.
The buffer is always zero terminated.
.Sh SEE ALSO
.Xr kvm 3

85
freebsd-userspace/lib/libkvm/kvm_nlist.3 Normal file
View File

@ -0,0 +1,85 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_nlist.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt KVM_NLIST 3
.Os
.Sh NAME
.Nm kvm_nlist
.Nd retrieve symbol table names from a kernel image
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.In nlist.h
.Ft int
.Fn kvm_nlist "kvm_t *kd" "struct nlist *nl"
.Sh DESCRIPTION
The
.Fn kvm_nlist
function retrieves the symbol table entries indicated by the name list argument
.Fa \&nl .
This argument points to an array of nlist structures, terminated by
an entry whose n_name field is
.Dv NULL
(see
.Xr nlist 3 ) .
Each symbol is looked up using the n_name field, and if found, the
corresponding n_type and n_value fields are filled in.
These fields are set
to 0 if the symbol is not found.
.Pp
The
.Xr kldsym 2
system call is used to locate the symbol.
This is a less than perfect
emulation of the nlist values but has the advantage of being aware of kernel
modules and is reasonably fast.
.Sh RETURN VALUES
The
.Fn kvm_nlist
function returns the number of invalid entries found.
If the kernel symbol table was unreadable, -1 is returned.
.Sh SEE ALSO
.Xr kldsym 2 ,
.Xr kvm 3 ,
.Xr kvm_close 3 ,
.Xr kvm_getargv 3 ,
.Xr kvm_getenvv 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_getprocs 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3

205
freebsd-userspace/lib/libkvm/kvm_open.3 Normal file
View File

@ -0,0 +1,205 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94
.\" $FreeBSD$
.\"
.Dd January 29, 2004
.Dt KVM_OPEN 3
.Os
.Sh NAME
.Nm kvm_open ,
.Nm kvm_openfiles ,
.Nm kvm_close
.Nd initialize kernel virtual memory access
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In fcntl.h
.In kvm.h
.Ft kvm_t *
.Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr"
.Ft kvm_t *
.Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf"
.Ft int
.Fn kvm_close "kvm_t *kd"
.Sh DESCRIPTION
The functions
.Fn kvm_open
and
.Fn kvm_openfiles
return a descriptor used to access kernel virtual memory
via the
.Xr kvm 3
library routines.
Both active kernels and crash dumps are accessible
through this interface.
.Pp
The
.Fa execfile
argument is the executable image of the kernel being examined.
This file must contain a symbol table.
If this argument is
.Dv NULL ,
the currently running system is assumed,
as determined from
.Xr getbootfile 3 .
.Pp
The
.Fa corefile
argument is the kernel memory device file.
It can be either
.Pa /dev/mem
or a crash dump core generated by
.Xr savecore 8 .
If
.Fa corefile
is
.Dv NULL ,
the default indicated by
.Dv _PATH_MEM
from
.In paths.h
is used.
It can also be set to a special value
.Pa /dev/null
by utilities like
.Xr ps 1
that do not directly access kernel memory.
.Pp
The
.Fa swapfile
argument is currently unused.
.Pp
The
.Fa flags
argument indicates read/write access as in
.Xr open 2
and applies only to the core file.
Only
.Dv O_RDONLY ,
.Dv O_WRONLY ,
and
.Dv O_RDWR
are permitted.
.Pp
There are two open routines which differ only with respect to
the error mechanism.
One provides backward compatibility with the SunOS kvm library, while the
other provides an improved error reporting framework.
.Pp
The
.Fn kvm_open
function is the Sun kvm compatible open call.
Here, the
.Fa errstr
argument indicates how errors should be handled.
If it is
.Dv NULL ,
no errors are reported and the application cannot know the
specific nature of the failed kvm call.
If it is not
.Dv NULL ,
errors are printed to
.Dv stderr
with
.Fa errstr
prepended to the message, as in
.Xr perror 3 .
Normally, the name of the program is used here.
The string is assumed to persist at least until the corresponding
.Fn kvm_close
call.
.Pp
The
.Fn kvm_openfiles
function provides
.Bx
style error reporting.
Here, error messages are not printed out by the library.
Instead, the application obtains the error message
corresponding to the most recent kvm library call using
.Fn kvm_geterr
(see
.Xr kvm_geterr 3 ) .
The results are undefined if the most recent kvm call did not produce
an error.
Since
.Fn kvm_geterr
requires a kvm descriptor, but the open routines return
.Dv NULL
on failure,
.Fn kvm_geterr
cannot be used to get the error message if open fails.
Thus,
.Fn kvm_openfiles
will place any error message in the
.Fa errbuf
argument.
This buffer should be _POSIX2_LINE_MAX characters large (from
<limits.h>).
.Sh RETURN VALUES
The
.Fn kvm_open
and
.Fn kvm_openfiles
functions both return a descriptor to be used
in all subsequent kvm library calls.
The library is fully re-entrant.
On failure,
.Dv NULL
is returned, in which case
.Fn kvm_openfiles
writes the error message into
.Fa errbuf .
.Pp
The
.Fn kvm_close
function returns 0 on success and -1 on failure.
.Sh SEE ALSO
.Xr open 2 ,
.Xr kvm 3 ,
.Xr kvm_getargv 3 ,
.Xr kvm_getenvv 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_getprocs 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3 ,
.Xr kmem 4 ,
.Xr mem 4
.Sh BUGS
There should not be two open calls.
The ill-defined error semantics
of the Sun library and the desire to have a backward-compatible library
for
.Bx
left little choice.

92
freebsd-userspace/lib/libkvm/kvm_read.3 Normal file
View File

@ -0,0 +1,92 @@
.\" Copyright (c) 1992, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)kvm_read.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt KVM_READ 3
.Os
.Sh NAME
.Nm kvm_read ,
.Nm kvm_write
.Nd read or write kernel virtual memory
.Sh LIBRARY
.Lb libkvm
.Sh SYNOPSIS
.In kvm.h
.Ft ssize_t
.Fn kvm_read "kvm_t *kd" "unsigned long addr" "void *buf" "size_t nbytes"
.Ft ssize_t
.Fn kvm_write "kvm_t *kd" "unsigned long addr" "const void *buf" "size_t nbytes"
.Sh DESCRIPTION
The
.Fn kvm_read
and
.Fn kvm_write
functions are used to read and write kernel virtual memory (or a crash
dump file).
See
.Fn kvm_open 3
or
.Fn kvm_openfiles 3
for information regarding opening kernel virtual memory and crash dumps.
.Pp
The
.Fn kvm_read
function transfers
.Fa nbytes
bytes of data from
the kernel space address
.Fa addr
to
.Fa buf .
Conversely,
.Fn kvm_write
transfers data from
.Fa buf
to
.Fa addr .
Unlike their SunOS counterparts, these functions cannot be used to
read or write process address spaces.
.Sh RETURN VALUES
Upon success, the number of bytes actually transferred is returned.
Otherwise, -1 is returned.
.Sh SEE ALSO
.Xr kvm 3 ,
.Xr kvm_close 3 ,
.Xr kvm_getargv 3 ,
.Xr kvm_getenvv 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_getprocs 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3