xref: /netbsd/lib/libkvm/kvm_getprocs.3 (revision c4a72b64) 
1.\"	$NetBSD: kvm_getprocs.3,v 1.11 2002/10/02 10:59:45 wiz 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
76which limits the set of processes returned.
77The value of
78.Fa op
79describes the filtering predicate as follows:
80.Pp
81.Bl -tag -width 20n -offset indent -compact
82.It Sy KERN_PROC_ALL
83all processes
84.It Sy KERN_PROC_PID
85processes with process id
86.Fa arg
87.It Sy KERN_PROC_PGRP
88processes with process group
89.Fa arg
90.It Sy KERN_PROC_SESSION
91processes with session id
92.Fa arg
93.It Sy KERN_PROC_TTY
94processes with tty device
95.Fa arg
96.It Sy KERN_PROC_UID
97processes with effective user id
98.Fa arg
99.It Sy KERN_PROC_RUID
100processes with real user id
101.Fa arg
102.It Sy KERN_PROC_GID
103processes with effective group id
104.Fa arg
105.It Sy KERN_PROC_RGID
106processes with real group id
107.Fa arg
108.El
109.Pp
110The number of processes found is returned in the reference parameter
111.Fa cnt .
112The processes are returned as a contiguous array of
113.Sy kinfo_proc
114structures.
115This memory is locally allocated, and subsequent calls to
116.Fn kvm_getprocs
117and
118.Fn kvm_close
119will overwrite this storage.
120.Pp
121If the
122.Fa op
123argument for
124.Fn kvm_getprocs
125is
126.Sy KERN_PROC_TTY ,
127.Fa arg
128can also be
129.Sy KERN_PROC_TTY_NODEV
130to select processes with no controlling tty and
131.Sy KERN_PROC_TTY_REVOKE
132to select processes which have had their controlling tty
133revoked.
134.Pp
135.Fn kvm_getargv
136returns a null-terminated argument vector that corresponds to the
137command line arguments passed to process indicated by
138.Fa p .
139Most likely, these arguments correspond to the values passed to
140.Xr exec 3
141on process creation.
142This information is, however,
143deliberately under control of the process itself.
144Note that the original command name can be found, unaltered,
145in the p_comm field of the process structure returned by
146.Fn kvm_getprocs .
147.Pp
148The
149.Fa nchr
150argument indicates the maximum number of characters, including null bytes,
151to use in building the strings.
152If this amount is exceeded, the string
153causing the overflow is truncated and the partial result is returned.
154This is handy for programs like
155.Xr ps 1
156and
157.Xr w 1
158that print only a one line summary of a command and should not copy
159out large amounts of text only to ignore it.
160If
161.Fa nchr
162is zero, no limit is imposed and all argument strings are returned in
163their entirety.
164.Pp
165The memory allocated to the argv pointers and string storage
166is owned by the kvm library.
167Subsequent
168.Fn kvm_getprocs
169and
170.Xr kvm_close 3
171calls will clobber this storage.
172.Pp
173The
174.Fn kvm_getenvv
175function is similar to
176.Fn kvm_getargv
177but returns the vector of environment strings.
178This data is also alterable by the process.
179.Pp
180.Fn kvm_getproc2
181is similar to
182.Fn kvm_getprocs
183but returns an array of
184.Sy kinfo_proc2
185structures.
186Additionally, only the first
187.Fa elemsize
188bytes of each array entry are returned.
189If the size of the
190.Sy kinfo_proc2
191structure increases in size in a future release of
192.Nx
193the kernel will only return the requested amount of data for
194each array entry and programs that use
195.Fn kvm_getproc2
196will continue to function without the need for recompilation.
197.Pp
198The
199.Fn kvm_getargv2
200and
201.Fn kvm_getenvv2
202are equivalents to the
203.Fn kvm_getargv
204and
205.Fn kvm_getenvv
206functions but use a
207.Sy kinfo_proc2
208structure to specify the process.
209.Pp
210If called against an active kernel, the
211.Fn kvm_getproc2 ,
212.Fn kvm_getargv2 ,
213and
214.Fn kvm_getenvv2
215functions will use the
216.Xr sysctl 3
217interface and do not require access to the kernel memory device
218file or swap device.
219.Sh RETURN VALUES
220.Fn kvm_getprocs ,
221.Fn kvm_getargv ,
222.Fn kvm_getenvv ,
223.Fn kvm_getproc2 ,
224.Fn kvm_getargv2 ,
225and
226.Fn kvm_getenvv2
227all return
228.Dv NULL
229on failure.
230.Sh SEE ALSO
231.Xr kvm 3 ,
232.Xr kvm_close 3 ,
233.Xr kvm_geterr 3 ,
234.Xr kvm_nlist 3 ,
235.Xr kvm_open 3 ,
236.Xr kvm_openfiles 3 ,
237.Xr kvm_read 3 ,
238.Xr kvm_write 3
239.Sh BUGS
240These routines do not belong in the kvm interface.
241