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

.\" Copyright (c) 1992 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)kvm_getprocs.3	5.1 (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_getargv "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 an 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.  However, this information exists only the
process address space, and is therefore alterable by 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
that print only a one line summary of a command and should copy
out large numbers arguments that will not be printed.
.Pp
The memory allocated to the argv pointers as well as the string storage
are owned by the kvm library.  Data must be copied out of this
structure before calling another kvm function.
.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 NULL on failure.
.Pp
.Sh BUGS
These routines do not belong in the kvm interface.
.Sh SEE ALSO
.Xr kvm 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3 ,
.Xr kvm_close 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_geterr 3
Commit	Line	Data
b8b13822 KM	1	.\" Copyright (c) 1992 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" %sccs.include.redist.man%
	5	.\"
	6	.\" @(#)kvm_getprocs.3 5.1 (Berkeley) %G%
	7	.\"
	8	.Dd
	9	.Dt KVM_GETPROCS 3
	10	.Os
	11	.Sh NAME
	12	.Nm kvm_getprocs ,
	13	.Nm kvm_getargv ,
	14	.Nm kvm_getenvv
	15	.Nd access user process state
	16	.Sh SYNOPSIS
	17	.Fd #include <kvm.h>
	18	.Fd #include <sys/kinfo.h>
	19	.Fd #include <sys/kinfo_proc.h>
	20	.\" .Fa kvm_t *kd
	21	.br
	22	.Ft struct kinfo_proc *
	23	.Fn kvm_getprocs "kvm_t kd" "int op" "int arg" "int cnt"
	24	.Ft char **
	25	.Fn kvm_getargv "kvm_t kd" "const struct kinfo_proc p" "int nchr"
	26	.Ft char **
	27	.Fn kvm_getargv "kvm_t kd" "const struct kinfo_proc p" "int nchr"
	28	.Sh DESCRIPTION
	29	.Fn kvm_getprocs
	30	returns a (sub-)set of active processes in the kernel indicated by
	31	.Fa kd.
	32	The
	33	.Fa op
	34	and
	35	.Fa arg
	36	arguments constitute a predicate which limits the set of processes
	37	returned. The value of
	38	.Fa op
	39	describes the filtering predicate as follows:
	40	.Pp
	41	.Bl -tag -width 20n -offset indent -compact
	42	.It Sy KINFO_PROC_ALL
	43	all processes
	44	.It Sy KINFO_PROC_PID
	45	processes with process id
	46	.Fa arg
	47	.It Sy KINFO_PROC_PGRP
	48	processes with process group
	49	.Fa arg
	50	.It Sy KINFO_PROC_SESSION
	51	processes with session
	52	.Fa arg
	53	.It Sy KINFO_PROC_TTY
	54	processes with tty
	55	.Fa arg
	56	.It Sy KINFO_PROC_UID
	57	processes with effective user id
	58	.Fa arg
	59	.It Sy KINFO_PROC_RUID
	60	processes with real user id
	61	.Fa arg
	62	.El
	63	.Pp
	64	The number of processes found is returned in the reference parameter
65	.Fa cnt .
66	The processes are returned as a contiguous array of kinfo_proc structures.
67	This memory is owned by kvm and is not guaranteed to be persistent across
68	subsequent kvm library calls. Data should be copied out if it needs to be
69	saved.
70	.Pp
71	.Fn kvm_getargv
72	returns an null-terminated argument vector that corresponds to the
73	command line arguments passed to process indicated by
74	.Fa p .
75	Most likely, these arguments correspond to the values passed to
76	.Xr exec 3
77	on process creation. However, this information exists only the
78	process address space, and is therefore alterable by the process
79	itself. Note that the original command name can be found, unaltered,
80	in the p_comm field of the process structure returned by
81	.Fn kvm_getprocs .
82	.Pp
83	The
84	.Fa nchr
85	argument indicates the maximum number of characters, including null bytes,
86	to use in building the strings. If this amount is exceeded, the string
87	causing the overflow is truncated and the partial result is returned.
88	This is handy for programs like
89	.Xr ps 1
90	and
91	.Xr w
92	that print only a one line summary of a command and should copy
93	out large numbers arguments that will not be printed.
94	.Pp
95	The memory allocated to the argv pointers as well as the string storage
96	are owned by the kvm library. Data must be copied out of this
97	structure before calling another kvm function.
98	.Pp
99	The
100	.Fn kvm_getenvv
101	function is similar to
102	.Fn kvm_getargv
103	but returns the vector of environment strings. This is data is
104	also alterable by the process.
105	.Sh RETURN VALUES
106	.Fn kvm_getprocs ,
107	.Fn kvm_getargv ,
108	and
109	.Fn kvm_getenvv ,
110	all return NULL on failure.
111	.Pp
112	.Sh BUGS
113	These routines do not belong in the kvm interface.
114	.Sh SEE ALSO
115	.Xr kvm 3 ,
116	.Xr kvm_open 3 ,
117	.Xr kvm_openfiles 3 ,
118	.Xr kvm_close 3 ,
119	.Xr kvm_read 3 ,
120	.Xr kvm_write 3 ,
121	.Xr kvm_nlist 3 ,
122	.Xr kvm_geterr 3