| blob | 92e858e35ad8990ce04f1e9cc2f9a63329f3bca1 |
1 .\" Copyright (c) 1992, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" This code is derived from software developed by the Computer Systems
5 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
6 .\" BG 91-66 and contributed to Berkeley.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" @(#)kvm_getprocs.3 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD$
34 .\"
35 .Dd September 27, 2003
36 .Dt KVM_GETPROCS 3
37 .Os
38 .Sh NAME
39 .Nm kvm_getprocs ,
40 .Nm kvm_getargv ,
41 .Nm kvm_getenvv
42 .Nd access user process state
43 .Sh LIBRARY
44 .Lb libkvm
45 .Sh SYNOPSIS
46 .In kvm.h
47 .In sys/param.h
48 .In sys/sysctl.h
49 .In sys/user.h
50 .\" .Fa kvm_t *kd
51 .Ft struct kinfo_proc *
52 .Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
53 .Ft char **
54 .Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
55 .Ft char **
56 .Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
57 .Sh DESCRIPTION
58 The
59 .Fn kvm_getprocs
60 function returns a (sub-)set of active processes in the kernel indicated by
61 .Fa kd .
62 The
63 .Fa op
64 and
65 .Fa arg
66 arguments constitute a predicate which limits the set of processes
67 returned.
68 The value of
69 .Fa op
70 describes the filtering predicate as follows:
71 .Pp
72 .Bl -tag -width 20n -offset indent -compact
73 .It Dv KERN_PROC_ALL
74 all processes and kernel visible threads
75 .It Dv KERN_PROC_PROC
76 all processes, without threads
77 .It Dv KERN_PROC_PID
78 processes with process ID
79 .Fa arg
80 .It Dv KERN_PROC_PGRP
81 processes with process group
82 .Fa arg
83 .It Dv KERN_PROC_SESSION
84 processes with session
85 .Fa arg
86 .It Dv KERN_PROC_TTY
87 processes with TTY
88 .Fa arg
89 .It Dv KERN_PROC_UID
90 processes with effective user ID
91 .Fa arg
92 .It Dv KERN_PROC_RUID
93 processes with real user ID
94 .Fa arg
95 .It Dv KERN_PROC_INC_THREAD
96 modifier to return all kernel visible threads when filtering
97 by process ID, process group, TTY, user ID, and real user ID
98 .El
99 .Pp
100 The number of processes found is returned in the reference parameter
101 .Fa cnt .
102 The processes are returned as a contiguous array of kinfo_proc structures.
103 This memory is locally allocated, and subsequent calls to
104 .Fn kvm_getprocs
105 and
106 .Fn kvm_close
107 will overwrite this storage.
108 .Pp
109 The
110 .Fn kvm_getargv
111 function returns a null-terminated argument vector that corresponds to the
112 command line arguments passed to process indicated by
113 .Fa p .
114 Most likely, these arguments correspond to the values passed to
115 .Xr exec 3
116 on process creation.
117 This information is, however,
118 deliberately under control of the process itself.
119 Note that the original command name can be found, unaltered,
120 in the p_comm field of the process structure returned by
121 .Fn kvm_getprocs .
122 .Pp
123 The
124 .Fa nchr
125 argument indicates the maximum number of characters, including null bytes,
126 to use in building the strings.
127 If this amount is exceeded, the string
128 causing the overflow is truncated and the partial result is returned.
129 This is handy for programs like
130 .Xr ps 1
131 and
132 .Xr w 1
133 that print only a one line summary of a command and should not copy
134 out large amounts of text only to ignore it.
135 If
136 .Fa nchr
137 is zero, no limit is imposed and all argument strings are returned in
138 their entirety.
139 .Pp
140 The memory allocated to the argv pointers and string storage
141 is owned by the kvm library.
142 Subsequent
143 .Fn kvm_getprocs
144 and
145 .Xr kvm_close 3
146 calls will clobber this storage.
147 .Pp
148 The
149 .Fn kvm_getenvv
150 function is similar to
151 .Fn kvm_getargv
152 but returns the vector of environment strings.
153 This data is
154 also alterable by the process.
155 .Sh RETURN VALUES
156 The
157 .Fn kvm_getprocs ,
158 .Fn kvm_getargv ,
159 and
160 .Fn kvm_getenvv
161 functions return
162 .Dv NULL
163 on failure.
164 .Sh SEE ALSO
165 .Xr kvm 3 ,
166 .Xr kvm_close 3 ,
167 .Xr kvm_geterr 3 ,
168 .Xr kvm_nlist 3 ,
169 .Xr kvm_open 3 ,
170 .Xr kvm_openfiles 3 ,
171 .Xr kvm_read 3 ,
172 .Xr kvm_write 3
173 .Sh BUGS
174 These routines do not belong in the kvm interface.
175 .Pp
176 In order for
177 .Xr kvm_getenvv 3
178 to function correctly,
179 .Xr procfs 5
180 must be mounted on
181 .Pa /proc .