From e9aaadb911140e21c79b621ce63f1f5991498d3d Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 22 Oct 2012 10:52:19 -0500 Subject: [PATCH] Add libkvm man pages --- freebsd-userspace/lib/libkvm/kvm_getcptime.3 | 77 +++++++ freebsd-userspace/lib/libkvm/kvm_geterr.3 | 78 +++++++ freebsd-userspace/lib/libkvm/kvm_getfiles.3 | 87 ++++++++ freebsd-userspace/lib/libkvm/kvm_getloadavg.3 | 62 ++++++ freebsd-userspace/lib/libkvm/kvm_getpcpu.3 | 101 +++++++++ freebsd-userspace/lib/libkvm/kvm_getprocs.3 | 181 ++++++++++++++++ .../lib/libkvm/kvm_getswapinfo.3 | 111 ++++++++++ freebsd-userspace/lib/libkvm/kvm_nlist.3 | 85 ++++++++ freebsd-userspace/lib/libkvm/kvm_open.3 | 205 ++++++++++++++++++ freebsd-userspace/lib/libkvm/kvm_read.3 | 92 ++++++++ 10 files changed, 1079 insertions(+) create mode 100644 freebsd-userspace/lib/libkvm/kvm_getcptime.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_geterr.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_getfiles.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_getloadavg.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_getpcpu.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_getprocs.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_getswapinfo.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_nlist.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_open.3 create mode 100644 freebsd-userspace/lib/libkvm/kvm_read.3 diff --git a/freebsd-userspace/lib/libkvm/kvm_getcptime.3 b/freebsd-userspace/lib/libkvm/kvm_getcptime.3 new file mode 100644 index 00000000..2ddc272d --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_getcptime.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2008 Yahoo!, Inc. +.\" All rights reserved. +.\" Written by: John Baldwin +.\" +.\" 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 diff --git a/freebsd-userspace/lib/libkvm/kvm_geterr.3 b/freebsd-userspace/lib/libkvm/kvm_geterr.3 new file mode 100644 index 00000000..3ce5c72a --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_geterr.3 @@ -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 . diff --git a/freebsd-userspace/lib/libkvm/kvm_getfiles.3 b/freebsd-userspace/lib/libkvm/kvm_getfiles.3 new file mode 100644 index 00000000..22bfd92d --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_getfiles.3 @@ -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. diff --git a/freebsd-userspace/lib/libkvm/kvm_getloadavg.3 b/freebsd-userspace/lib/libkvm/kvm_getloadavg.3 new file mode 100644 index 00000000..6587b1a9 --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_getloadavg.3 @@ -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 diff --git a/freebsd-userspace/lib/libkvm/kvm_getpcpu.3 b/freebsd-userspace/lib/libkvm/kvm_getpcpu.3 new file mode 100644 index 00000000..40f16ac7 --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_getpcpu.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 2008 Yahoo!, Inc. +.\" All rights reserved. +.\" Written by: John Baldwin +.\" +.\" 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 diff --git a/freebsd-userspace/lib/libkvm/kvm_getprocs.3 b/freebsd-userspace/lib/libkvm/kvm_getprocs.3 new file mode 100644 index 00000000..92e858e3 --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_getprocs.3 @@ -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 . diff --git a/freebsd-userspace/lib/libkvm/kvm_getswapinfo.3 b/freebsd-userspace/lib/libkvm/kvm_getswapinfo.3 new file mode 100644 index 00000000..edd2068d --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_getswapinfo.3 @@ -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 diff --git a/freebsd-userspace/lib/libkvm/kvm_nlist.3 b/freebsd-userspace/lib/libkvm/kvm_nlist.3 new file mode 100644 index 00000000..a151a3b2 --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_nlist.3 @@ -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 diff --git a/freebsd-userspace/lib/libkvm/kvm_open.3 b/freebsd-userspace/lib/libkvm/kvm_open.3 new file mode 100644 index 00000000..1b62482d --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_open.3 @@ -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 +). +.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. diff --git a/freebsd-userspace/lib/libkvm/kvm_read.3 b/freebsd-userspace/lib/libkvm/kvm_read.3 new file mode 100644 index 00000000..a2efd3c2 --- /dev/null +++ b/freebsd-userspace/lib/libkvm/kvm_read.3 @@ -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