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