add LBL credit line

[unix-history] / usr / src / lib / libkvm / kvm_getprocs.3

.\" Copyright (c) 1992 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.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)kvm_getprocs.3      5.3 (Berkeley) %G%
.\"
.Dd 
.Dt KVM_GETPROCS 3
.Os
.Sh NAME
.Nm kvm_getprocs ,
.Nm kvm_getargv ,
.Nm kvm_getenvv 
.Nd access user process state
.Sh SYNOPSIS
.Fd #include <kvm.h>
.Fd #include <sys/kinfo.h>
.Fd #include <sys/kinfo_proc.h>
.\" .Fa kvm_t *kd
.br
.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
.Fn kvm_getprocs
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 Sy KINFO_PROC_ALL
all processes
.It Sy KINFO_PROC_PID
processes with process id 
.Fa arg
.It Sy KINFO_PROC_PGRP
processes with process group
.Fa arg
.It Sy KINFO_PROC_SESSION
processes with session
.Fa arg
.It Sy KINFO_PROC_TTY
processes with tty
.Fa arg
.It Sy KINFO_PROC_UID
processes with effective user id
.Fa arg
.It Sy KINFO_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.
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.
.Pp
.Fn kvm_getargv
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.  Since subsequent kvm calls may clobber
this storage, data must be copied out if it needs to be saved.
.Pp
The
.Fn kvm_getenvv
function is similar to
.Fn kvm_getargv
but returns the vector of environment strings.  This is data is
also alterable by the process.
.Sh RETURN VALUES
.Fn kvm_getprocs ,
.Fn kvm_getargv ,
and
.Fn kvm_getenvv ,
all return
.Dv NULL
on failure.
.Pp
.Sh BUGS
These routines do not belong in the kvm interface.
.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