From 2bb07095a0782aca27ae27f29951964f13b2204a Mon Sep 17 00:00:00 2001 From: aaron Date: Sat, 4 Mar 2000 15:29:56 +0000 Subject: [PATCH] Various cleanups and mdoc'ing. --- lib/libkvm/kvm.3 | 18 +++++++++++---- lib/libkvm/kvm_dump.3 | 34 +++++++++++++++------------ lib/libkvm/kvm_geterr.3 | 3 +-- lib/libkvm/kvm_getfiles.3 | 10 ++++---- lib/libkvm/kvm_getloadavg.3 | 7 +++--- lib/libkvm/kvm_getprocs.3 | 38 ++++++++++++++++-------------- lib/libkvm/kvm_nlist.3 | 17 ++++++++++---- lib/libkvm/kvm_open.3 | 46 +++++++++++++++++++++++-------------- lib/libkvm/kvm_read.3 | 8 ++++--- 9 files changed, 109 insertions(+), 72 deletions(-) diff --git a/lib/libkvm/kvm.3 b/lib/libkvm/kvm.3 index 6a4ecd98a36..c834906f705 100644 --- a/lib/libkvm/kvm.3 +++ b/lib/libkvm/kvm.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -50,7 +50,7 @@ The 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. @@ -61,7 +61,8 @@ be gathered. .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. @@ -72,11 +73,13 @@ Accordingly, the generic portion of the interface (i.e., .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 @@ -90,6 +93,11 @@ routine, 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 , diff --git a/lib/libkvm/kvm_dump.3 b/lib/libkvm/kvm_dump.3 index fa51b1bc1c8..52e73f2d4d3 100644 --- a/lib/libkvm/kvm_dump.3 +++ b/lib/libkvm/kvm_dump.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -41,7 +41,6 @@ .Nd crash-dump support functions .Sh SYNOPSIS .Fd #include -.br .Ft int .Fn kvm_dump_mkheader "kvm_t *kd" "off_t dump_off" .Ft int @@ -56,30 +55,36 @@ The function .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 . @@ -93,12 +98,11 @@ that .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 diff --git a/lib/libkvm/kvm_geterr.3 b/lib/libkvm/kvm_geterr.3 index d1977d8f1de..564a0d5cf9a 100644 --- a/lib/libkvm/kvm_geterr.3 +++ b/lib/libkvm/kvm_geterr.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -46,7 +46,6 @@ .Nd get error message on kvm descriptor .Sh SYNOPSIS .Fd #include -.br .Ft char * .Fn kvm_geterr "kvm_t *kd" .Sh DESCRIPTION diff --git a/lib/libkvm/kvm_getfiles.3 b/lib/libkvm/kvm_getfiles.3 index cfce6f754ad..3c94fdf8ceb 100644 --- a/lib/libkvm/kvm_getfiles.3 +++ b/lib/libkvm/kvm_getfiles.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -51,7 +51,6 @@ .Fd #include .Fd #undef _KERNEL .\" .Fa kvm_t *kd -.br .Ft char * .Fn kvm_getfiles "kvm_t *kd" "int op" "int arg" "int *cnt" .Sh DESCRIPTION @@ -63,15 +62,16 @@ The 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 diff --git a/lib/libkvm/kvm_getloadavg.3 b/lib/libkvm/kvm_getloadavg.3 index 2b254b7efdb..fc59c01688c 100644 --- a/lib/libkvm/kvm_getloadavg.3 +++ b/lib/libkvm/kvm_getloadavg.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -43,7 +43,6 @@ .Sh SYNOPSIS .Fd #include .Fd #include -.br .Ft int .Fn kvm_getloadavg "kvm_t *kd" "double loadavg[]" "int nelem" .Sh DESCRIPTION @@ -59,8 +58,8 @@ 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, +.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 , diff --git a/lib/libkvm/kvm_getprocs.3 b/lib/libkvm/kvm_getprocs.3 index 3b6b2d07b39..c9c82dde57f 100644 --- a/lib/libkvm/kvm_getprocs.3 +++ b/lib/libkvm/kvm_getprocs.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -49,8 +49,6 @@ .Sh SYNOPSIS .Fd #include .Fd #include -.\" .Fa kvm_t *kd -.br .Ft struct kinfo_proc * .Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt" .Ft char ** @@ -66,36 +64,39 @@ The 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 @@ -108,7 +109,8 @@ 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, +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 @@ -119,7 +121,8 @@ field of the process structure returned by 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 @@ -133,7 +136,8 @@ 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 +is owned by the kvm library. +Subsequent .Fn kvm_getprocs and .Xr kvm_close 3 @@ -143,8 +147,8 @@ 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. +but returns the vector of environment strings. +This data is also alterable by the process. .Sh RETURN VALUES .Fn kvm_getprocs , .Fn kvm_getargv , diff --git a/lib/libkvm/kvm_nlist.3 b/lib/libkvm/kvm_nlist.3 index 150bf2267a9..9b84240a476 100644 --- a/lib/libkvm/kvm_nlist.3 +++ b/lib/libkvm/kvm_nlist.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -54,12 +54,21 @@ 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 diff --git a/lib/libkvm/kvm_open.3 b/lib/libkvm/kvm_open.3 index 56620ace6a8..e1a694d39cd 100644 --- a/lib/libkvm/kvm_open.3 +++ b/lib/libkvm/kvm_open.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -49,7 +49,6 @@ .Sh SYNOPSIS .Fd #include .Fd #include -.br .Ft kvm_t * .Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr" .Ft kvm_t * @@ -64,8 +63,8 @@ and 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. @@ -78,10 +77,13 @@ which is indicated by if it exists, otherwise .Dv _PATH_UNIX is used. -Both are defined in . +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 @@ -90,13 +92,18 @@ is .Dv NULL , the default indicated by .Dv _PATH_MEM -from 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 is used. +from +.Aq Pa paths.h +is used. .Pp The .Fa flags @@ -117,9 +124,11 @@ other provides an improved error reporting framework. .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. @@ -142,7 +151,7 @@ Instead, the application obtains the error message 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 @@ -156,8 +165,11 @@ Thus, .Fn kvm_openfiles will place any error message in the .Fa errbuf -argument. This buffer should be _POSIX2_LINE_MAX characters large (from -). +argument. +This buffer should be +.Dv _POSIX2_LINE_MAX +characters large (from +.Aq Pa limits.h ) . .Sh RETURN VALUES The .Fn kvm_open @@ -177,9 +189,9 @@ The .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 , diff --git a/lib/libkvm/kvm_read.3 b/lib/libkvm/kvm_read.3 index 43017b7b835..1584129a536 100644 --- a/lib/libkvm/kvm_read.3 +++ b/lib/libkvm/kvm_read.3 @@ -1,4 +1,4 @@ -.\" $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 @@ -57,7 +57,8 @@ The 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 @@ -81,7 +82,8 @@ to 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 , -- 2.20.1