xref: /netbsd/lib/libkvm/kvm_getprocs.3 (revision bf9ec67e) 
1.\"	$NetBSD: kvm_getprocs.3,v 1.9 2002/02/07 07:00:48 ross Exp $
2.\"
3.\" Copyright (c) 1992, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" This code is derived from software developed by the Computer Systems
7.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
8.\" BG 91-66 and contributed to Berkeley.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. All advertising materials mentioning features or use of this software
19.\"    must display the following acknowledgement:
20.\"	This product includes software developed by the University of
21.\"	California, Berkeley and its contributors.
22.\" 4. Neither the name of the University nor the names of its contributors
23.\"    may be used to endorse or promote products derived from this software
24.\"    without specific prior written permission.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36.\" SUCH DAMAGE.
37.\"
38.\"     @(#)kvm_getprocs.3	8.1 (Berkeley) 6/4/93
39.\"
40.Dd June 4, 1993
41.Dt KVM_GETPROCS 3
42.Os
43.Sh NAME
44.Nm kvm_getprocs ,
45.Nm kvm_getargv ,
46.Nm kvm_getenvv
47.Nd access user process state
48.Sh LIBRARY
49.Lb libkvm
50.Sh SYNOPSIS
51.Fd #include \*[Lt]kvm.h\*[Gt]
52.Fd #include \*[Lt]sys/sysctl.h\*[Gt]
53.\" .Fa kvm_t *kd
54.br
55.Ft struct kinfo_proc *
56.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
57.Ft char **
58.Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
59.Ft char **
60.Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
61.Ft struct kinfo_proc2 *
62.Fn kvm_getproc2 "kvm_t *kd" "int op" "int arg" "int elemsize" "int *cnt"
63.Ft char **
64.Fn kvm_getargv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
65.Ft char **
66.Fn kvm_getenvv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
67.Sh DESCRIPTION
68.Fn kvm_getprocs
69returns a (sub-)set of active processes in the kernel indicated by
70.Fa kd .
71The
72.Fa op
73and
74.Fa arg
75arguments constitute a predicate which limits the set of processes
76returned.  The value of
77.Fa op
78describes the filtering predicate as follows:
79.Pp
80.Bl -tag -width 20n -offset indent -compact
81.It Sy KERN_PROC_ALL
82all processes
83.It Sy KERN_PROC_PID
84processes with process id
85.Fa arg
86.It Sy KERN_PROC_PGRP
87processes with process group
88.Fa arg
89.It Sy KERN_PROC_SESSION
90processes with sessiod id
91.Fa arg
92.It Sy KERN_PROC_TTY
93processes with tty device
94.Fa arg
95.It Sy KERN_PROC_UID
96processes with effective user id
97.Fa arg
98.It Sy KERN_PROC_RUID
99processes with real user id
100.Fa arg
101.It Sy KERN_PROC_GID
102processes with effective group id
103.Fa arg
104.It Sy KERN_PROC_RGID
105processes with real group id
106.Fa arg
107.El
108.Pp
109The number of processes found is returned in the reference parameter
110.Fa cnt .
111The processes are returned as a contiguous array of
112.Sy kinfo_proc
113structures.
114This memory is locally allocated, and subsequent calls to
115.Fn kvm_getprocs
116and
117.Fn kvm_close
118will overwrite this storage.
119.Pp
120If the
121.Fa op
122argument for
123.Fn kvm_getprocs
124is
125.Sy KERN_PROC_TTY ,
126.Fa arg
127can also be
128.Sy KERN_PROC_TTY_NODEV
129to select processes with no controlling tty and
130.Sy KERN_PROC_TTY_REVOKE
131to select processes which have had their controlling tty
132revoked.
133.Pp
134.Fn kvm_getargv
135returns a null-terminated argument vector that corresponds to the
136command line arguments passed to process indicated by
137.Fa p .
138Most likely, these arguments correspond to the values passed to
139.Xr exec 3
140on process creation.  This information is, however,
141deliberately under control of the process itself.
142Note that the original command name can be found, unaltered,
143in the p_comm field of the process structure returned by
144.Fn kvm_getprocs .
145.Pp
146The
147.Fa nchr
148argument indicates the maximum number of characters, including null bytes,
149to use in building the strings.  If this amount is exceeded, the string
150causing the overflow is truncated and the partial result is returned.
151This is handy for programs like
152.Xr ps 1
153and
154.Xr w 1
155that print only a one line summary of a command and should not copy
156out large amounts of text only to ignore it.
157If
158.Fa nchr
159is zero, no limit is imposed and all argument strings are returned in
160their entirety.
161.Pp
162The memory allocated to the argv pointers and string storage
163is owned by the kvm library.  Subsequent
164.Fn kvm_getprocs
165and
166.Xr kvm_close 3
167calls will clobber this storage.
168.Pp
169The
170.Fn kvm_getenvv
171function is similar to
172.Fn kvm_getargv
173but returns the vector of environment strings.  This data is
174also alterable by the process.
175.Pp
176.Fn kvm_getproc2
177is similar to
178.Fn kvm_getprocs
179but returns an array of
180.Sy kinfo_proc2
181structures.  Additionally, only the first
182.Fa elemsize
183bytes of each array entry are returned.
184If the size of the
185.Sy kinfo_proc2
186structure increases in size in a future release of
187.Nx
188the kernel will only return the requested amount of data for
189each array entry and programs that use
190.Fn kvm_getproc2
191will continue to function without the need for recompilation.
192.Pp
193The
194.Fn kvm_getargv2
195and
196.Fn kvm_getenvv2
197are equivalents to the
198.Fn kvm_getargv
199and
200.Fn kvm_getenvv
201functions but use a
202.Sy kinfo_proc2
203structure to specify the process.
204.Pp
205If called against an active kernel, the
206.Fn kvm_getproc2 ,
207.Fn kvm_getargv2 ,
208and
209.Fn kvm_getenvv2
210functions will use the
211.Xr sysctl 3
212interface and do not require access to the kernel memory device
213file or swap device.
214.Sh RETURN VALUES
215.Fn kvm_getprocs ,
216.Fn kvm_getargv ,
217.Fn kvm_getenvv ,
218.Fn kvm_getproc2 ,
219.Fn kvm_getargv2 ,
220and
221.Fn kvm_getenvv2
222all return
223.Dv NULL
224on failure.
225.Sh SEE ALSO
226.Xr kvm 3 ,
227.Xr kvm_close 3 ,
228.Xr kvm_geterr 3 ,
229.Xr kvm_nlist 3 ,
230.Xr kvm_open 3 ,
231.Xr kvm_openfiles 3 ,
232.Xr kvm_read 3 ,
233.Xr kvm_write 3
234.Sh BUGS
235These routines do not belong in the kvm interface.
236