-.\" $OpenBSD: kvm.3,v 1.2 1996/05/05 14:56:38 deraadt Exp $
+.\" $OpenBSD: kvm.3,v 1.3 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm.3,v 1.2 1996/03/18 22:33:11 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
library provides a uniform interface for accessing kernel virtual memory
images, including live systems and crashdumps.
Access to live systems is via
-/dev/mem
+.Pa /dev/mem
while crashdumps can be examined via the core file generated by
.Xr savecore 8 .
The interface behaves identically in both cases.
.Fn kvm_open
is first called to obtain a descriptor for all subsequent calls.
.Sh COMPATIBILITY
-The kvm interface was first introduced in SunOS. A considerable
+The kvm interface was first introduced in SunOS.
+A considerable
number of programs have been developed that use this interface,
making backward compatibility highly desirable.
In most respects, the Sun kvm interface is consistent and clean.
.Fn kvm_write ,
and
.Fn kvm_nlist )
-has been incorporated into the BSD interface. Indeed, many kvm
+has been incorporated into the BSD interface.
+Indeed, many kvm
applications (i.e., debuggers and statistical monitors) use only
this subset of the interface.
.Pp
-The process interface was not kept. This is not a portability
+The process interface was not kept.
+This is not a portability
issue since any code that manipulates processes is inherently
machine dependent.
.Pp
to return (not print out) the error message
corresponding to the most recent error condition on the
given descriptor.
+.Sh FILES
+.Bl -tag -width /dev/mem -compact
+.It Pa /dev/mem
+interface to physical memory
+.El
.Sh SEE ALSO
.Xr kvm_close 3 ,
.Xr kvm_getargv 3 ,
-.\" $OpenBSD: kvm_dump.3,v 1.3 1999/07/09 13:35:25 aaron Exp $
+.\" $OpenBSD: kvm_dump.3,v 1.4 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_dump.3,v 1.1 1996/03/18 21:11:12 leo Exp $
.\"
.\" Copyright (c) 1996 Leo Weppelman
.Nd crash-dump support functions
.Sh SYNOPSIS
.Fd #include <kvm.h>
-.br
.Ft int
.Fn kvm_dump_mkheader "kvm_t *kd" "off_t dump_off"
.Ft int
.Fn kvm_dump_mkheader
checks if the physical memory file associated with
.Fa kd
-contains a valid crash-dump header as generated by a dumping kernel. When a
-valid header is found,
+contains a valid crash-dump header as generated by a dumping kernel.
+When a valid header is found,
.Fn kvm_dump_mkheader
initializes the internal kvm data structures as if a crash-dump generated by
the
.Xr savecore 8
-program was opened. This has the intentional side effect of enabling the
+program was opened.
+This has the intentional side effect of enabling the
address translation machinery.
.Pp
A call to
.Fn kvm_dump_mkheader
will most likely be followed by a call to
.Fn kvm_dump_wrtheader .
-This function takes care of generating the generic header, the CORE_CPU
-section and the section header of the CORE_DATA section. The data is written
-to the file pointed at by
+This function takes care of generating the generic header, the
+.Dv CORE_CPU
+section and the section header of the
+.Dv CORE_DATA
+section.
+The data is written to the file pointed at by
.Fa fp .
The
.Fa dumpsize
-argument is only used to properly the set the segment size of the CORE_DATA
-section. Note that this function assumes that
+argument is only used to properly the set the segment size of the
+.Dv CORE_DATA
+section.
+Note that this function assumes that
.Fa fp
-is positioned at file location 0. This function will not seek and therefore
-allows
+is positioned at file location 0.
+This function will not seek and therefore allows
.Fa fp
to be a file pointer obtained by
.Fn zopen .
.Fn kvm_dum_mkheader
was called earlier in the sequence).
.Sh RETURN VALUES
-All functions return 0 on success, \-1 on failure. In the case of failure,
+All functions return 0 on success, \-1 on failure.
+In the case of failure,
.Xr kvm_geterr 3
can be used to retrieve the cause of the error.
.Sh HISTORY
These functions first appeared in NetBSD 1.1A.
-.Sh BUGS
-There probably are...
.Sh SEE ALSO
.Xr kvm 3
-.\" $OpenBSD: kvm_geterr.3,v 1.3 1999/07/09 13:35:25 aaron Exp $
+.\" $OpenBSD: kvm_geterr.3,v 1.4 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_geterr.3,v 1.2 1996/03/18 22:33:20 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
.Nd get error message on kvm descriptor
.Sh SYNOPSIS
.Fd #include <kvm.h>
-.br
.Ft char *
.Fn kvm_geterr "kvm_t *kd"
.Sh DESCRIPTION
-.\" $OpenBSD: kvm_getfiles.3,v 1.6 2000/01/05 18:51:10 deraadt Exp $
+.\" $OpenBSD: kvm_getfiles.3,v 1.7 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_getfiles.3,v 1.3 1996/03/18 22:33:23 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
.Fd #include <sys/file.h>
.Fd #undef _KERNEL
.\" .Fa kvm_t *kd
-.br
.Ft char *
.Fn kvm_getfiles "kvm_t *kd" "int op" "int arg" "int *cnt"
.Sh DESCRIPTION
and
.Fa arg
arguments constitute a predicate which limits the set of files
-returned. No predicates are currently defined.
+returned.
+No predicates are currently defined.
.Pp
The number of processes 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.
+subsequent kvm library calls.
+Data should be copied out if it needs to be saved.
.Sh RETURN VALUES
.Fn kvm_getfiles
will return
-.\" $OpenBSD: kvm_getloadavg.3,v 1.4 1999/05/16 19:55:53 alex Exp $
+.\" $OpenBSD: kvm_getloadavg.3,v 1.5 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_getloadavg.3,v 1.2 1996/03/18 22:33:26 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
.Sh SYNOPSIS
.Fd #include <sys/resource.h>
.Fd #include <kvm.h>
-.br
.Ft int
.Fn kvm_getloadavg "kvm_t *kd" "double loadavg[]" "int nelem"
.Sh DESCRIPTION
.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,
+.Sh RETURN VALUES
+If the load average was unobtainable, \-1 is returned. Otherwise,
the number of samples actually retrieved is returned.
.Sh SEE ALSO
.Xr uptime 1 ,
-.\" $OpenBSD: kvm_getprocs.3,v 1.6 1999/07/09 13:35:25 aaron Exp $
+.\" $OpenBSD: kvm_getprocs.3,v 1.7 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_getprocs.3,v 1.3 1996/05/20 16:58:03 mrg Exp $
.\"
.\" Copyright (c) 1992, 1993
.Sh SYNOPSIS
.Fd #include <kvm.h>
.Fd #include <sys/sysctl.h>
-.\" .Fa kvm_t *kd
-.br
.Ft struct kinfo_proc *
.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
.Ft char **
and
.Fa arg
arguments constitute a predicate which limits the set of processes
-returned. The value of
+returned.
+The value of
.Fa op
describes the filtering predicate as follows:
.Pp
.Bl -tag -width 20n -offset indent -compact
-.It Sy KERN_PROC_ALL
+.It Dv KERN_PROC_ALL
all processes
-.It Sy KERN_PROC_PID
+.It Dv KERN_PROC_PID
processes with process ID
.Fa arg
-.It Sy KERN_PROC_PGRP
+.It Dv KERN_PROC_PGRP
processes with process group
.Fa arg
-.It Sy KERN_PROC_SESSION
+.It Dv KERN_PROC_SESSION
processes with session
.Fa arg
-.It Sy KERN_PROC_TTY
+.It Dv KERN_PROC_TTY
processes with tty
.Fa arg
-.It Sy KERN_PROC_UID
+.It Dv KERN_PROC_UID
processes with effective user ID
.Fa arg
-.It Sy KERN_PROC_RUID
+.It Dv KERN_PROC_RUID
processes with real user ID
.Fa arg
.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.
+The processes are returned as a contiguous array of
+.Li kinfo_proc
+structures.
This memory is locally allocated, and subsequent calls to
.Fn kvm_getprocs
and
.Fa p .
Most likely, these arguments correspond to the values passed to
.Xr exec 3
-on process creation. This information is, however,
+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
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
+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
their entirety.
.Pp
The memory allocated to the argv pointers and string storage
-is owned by the kvm library. Subsequent
+is owned by the kvm library.
+Subsequent
.Fn kvm_getprocs
and
.Xr kvm_close 3
.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.
+but returns the vector of environment strings.
+This data is also alterable by the process.
.Sh RETURN VALUES
.Fn kvm_getprocs ,
.Fn kvm_getargv ,
-.\" $OpenBSD: kvm_nlist.3,v 1.5 1999/07/07 14:22:25 aaron Exp $
+.\" $OpenBSD: kvm_nlist.3,v 1.6 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_nlist.3,v 1.3 1996/03/18 22:33:48 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
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
+an entry whose
+.Fa 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
+Each symbol is looked up using the
+.Fa n_name
+field, and if found, the
+corresponding
+.Fa n_type
+and
+.Fa n_value
+fields are filled in.
+These fields are set
to 0 if the symbol is not found.
.Pp
The program
-.\" $OpenBSD: kvm_open.3,v 1.5 1999/07/09 13:35:25 aaron Exp $
+.\" $OpenBSD: kvm_open.3,v 1.6 2000/03/04 15:29:56 aaron Exp $
.\" $NetBSD: kvm_open.3,v 1.2 1996/03/18 22:33:52 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
.Sh SYNOPSIS
.Fd #include <fcntl.h>
.Fd #include <kvm.h>
-.br
.Ft kvm_t *
.Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr"
.Ft kvm_t *
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.
+library routines.
+Both active kernels and crash dumps are accessible through this interface.
.Pp
.Fa execfile
is the executable image of the kernel being examined.
if it exists, otherwise
.Dv _PATH_UNIX
is used.
-Both are defined in <paths.h>.
+Both are defined in
+.Aq Pa paths.h .
.Pp
.Fa corefile
-is the kernel memory device file. It can be either /dev/mem
+is the kernel memory device file.
+It can be either
+.Pa /dev/mem
or a crash dump core generated by
.Xr savecore 8 .
If
.Dv NULL ,
the default indicated by
.Dv _PATH_MEM
-from <paths.h> is used.
+from
+.Aq Pa paths.h
+is used.
.Pp
.Fa swapfile
-should indicate the swap device. If
+should indicate the swap device.
+If
.Dv NULL ,
.Dv _PATH_DRUM
-from <paths.h> is used.
+from
+.Aq Pa paths.h
+is used.
.Pp
The
.Fa flags
.Pp
The
.Fn kvm_open
-function is the Sun kvm compatible open call. Here, the
+function is the Sun kvm compatible open call.
+Here, the
.Fa errstr
-argument indicates how errors should be handled. If it is
+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.
corresponding to the most recent kvm library call using
.Fn kvm_geterr
(see
-.Xr kvm_geterr 3 ).
+.Xr kvm_geterr 3 ) .
The results are undefined if the most recent kvm call did not produce
an error.
Since
.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>).
+argument.
+This buffer should be
+.Dv _POSIX2_LINE_MAX
+characters large (from
+.Aq Pa limits.h ) .
.Sh RETURN VALUES
The
.Fn kvm_open
.Fn kvm_close
function returns 0 on success and \-1 on failure.
.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 BSD left little choice.
+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 BSD left little choice.
.Sh SEE ALSO
.Xr open 2 ,
.Xr kvm 3 ,
-.\" $OpenBSD: kvm_read.3,v 1.4 1999/07/09 13:35:26 aaron Exp $
+.\" $OpenBSD: kvm_read.3,v 1.5 2000/03/04 15:29:57 aaron Exp $
.\" $NetBSD: kvm_read.3,v 1.2 1996/03/18 22:34:01 thorpej Exp $
.\"
.\" Copyright (c) 1992, 1993
and
.Fn kvm_write
functions are used to read and write kernel virtual memory (or a crash
-dump file). See
+dump file).
+See
.Fn kvm_open 3
or
.Fn kvm_openfiles 3
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.
+Upon successful completion, the number of bytes actually transferred is
+returned.
Otherwise, \-1 is returned.
.Sh SEE ALSO
.Xr kvm 3 ,
projects / openbsd / commitdiff