1proc(1) User Commands proc(1)
2
6 proc, pflags, pcred, pldd, psig, pstack, pfiles, pwdx, pstop, prun,
7 pwait, ptime - proc tools
8
10 /usr/bin/pflags [-r] pid | core [/lwp] ...
11 /usr/bin/pcred [pid | core]...
14 /usr/bin/pcred [-u user/uid] [-g group/gid] [-G grouplist] pid...
17 /usr/bin/pcred -l login pid...
20 /usr/bin/pldd [-Fl] [pid | core]...
23 /usr/bin/psig [-n] pid...
26 /usr/bin/pstack [-F] pid | core [/lwp] ...
29 /usr/bin/pfiles [-Fn] pid...
32 /usr/bin/pwdx pid...
35 /usr/bin/pstop pid[/lwp] ...
38 /usr/bin/prun pid[/lwp] ...
41 /usr/bin/pwait [-v] pid...
44 /usr/bin/ptime [-Fm] [-p] pid...
47 /usr/bin/ptime [-m]command [arg]...
50
53 The proc tools are utilities that exercise features of /proc (see
54 proc(4)). Most of them take a list of process-ids (pid). The tools that
55 do take process-ids also accept /proc/nnn as a process-id, so the shell
56 expansion /proc/* can be used to specify all processes in the system.
57 Some of the proc tools can also be applied to core files (see core(4)).
60 The tools that apply to core files accept a list of either process IDs
61 or names of core files or both.
62 Some of the proc tools can operate on individual threads. Users can
65 examine only selected threads by appending /thread-id to the process-id
66 or core. Multiple threads can be selected using the - and , delimiters.
67 For example /1,2,7-9 examines threads 1, 2, 7, 8, and 9.
68 See WARNINGS.
71 pflags Print the /proc tracing flags, the pending and held signals,
73 and other /proc status information for each process or speci‐
74 fied lwps in each process.
75 pcred Print or set the credentials (effective, real, saved UIDs and
78 GIDs) of each process.
79 pldd List the dynamic libraries linked into each process, includ‐
82 ing shared objects explicitly attached using dlopen(3C). See
83 also ldd(1).
84 psig List the signal actions and handlers of each process. See
87 signal.h(3HEAD).
88 pstack Print a hex+symbolic stack trace for each process or speci‐
91 fied lwps in each process.
92 pfiles Report fstat(2) and fcntl(2) information for all open files
95 in each process. For network endpoints, the local (and peer
96 if connected) address information is also provided. For sock‐
97 ets, the socket type, socket options and send and receive
98 buffer sizes are also provided. In addition, a path to the
99 file is reported if the information is available from
100 /proc/pid/path. This is not necessarily the same name used to
101 open the file. See proc(4) for more information.
102 pwdx Print the current working directory of each process.
105 pstop Stop each process or the specified lwps (PR_REQUESTED stop).
108 prun Set running each process or the specified lwps (the inverse
111 of pstop).
112 pwait Wait for all of the specified processes to terminate.
115 ptime Time the command, like time(1), but using microstate account‐
118 ing for reproducible precision. Unlike time(1), children of
119 the command are not timed.
120 If the -p pid version is used, display a snapshot of timing
122 statistics for the specified pid.
123
126 The following general options are supported:
127 -F Force. Grabs the target process even if another process has con‐
129 trol.
130 -n (psig and pfiles only) Sets non-verbose mode. psig displays sig‐
133 nal handler addresses rather than names. pfiles does not display
134 verbose information for each file descriptor. Instead, pfiles
135 limits its output to the information that would be retrieved if
136 the process applied fstat(2) to each of its file descriptors.
137 -r (pflags only) If the process is stopped, displays its machine
140 registers.
141 -v (pwait only) Verbose. Reports terminations to standard output.
144 In addition to the general options, pcred supports the following
148 options:
149 -g group/gid Sets the real, effective, and saved group ids (GIDs) of
151 the target processes to the specified value.
152 -G grouplist Sets the supplementary GIDs of the target process to
155 the specified list of groups. The supplementary groups
156 should be specified as a comma-separated list of group
157 names ids. An empty list clears the supplementary group
158 list of the target processes.
159 -l login Sets the real, effective, and saved UIDs of the target
162 processes to the UID of the specified login. Sets the
163 real, effective, and saved GIDs of the target processes
164 to the GID of the specified login. Sets the supplemen‐
165 tary group list to the supplementary groups list of the
166 specified login.
167 -u user/uid Sets the real, effective, and saved user ids (UIDs) of
170 the target processes to the specified value.
171 In addition to the general options, pldd supports the following option:
175 -l Shows unresolved dynamic linker map names.
177 In addition to the general options, ptime supports the following
181 options:
182 -m Display the full set of microstate accounting statistics.
184 The displayed fields are as follows:
186 real Wall clock time.
188 user User level CPU time.
191 sys System call CPU time.
194 trap Other system trap CPU time.
197 tflt Text page fault sleep time.
200 dflt Data page fault sleep time.
203 kflt Kernel page fault sleep time.
206 lock User lock wait sleep time.
209 slp All other sleep time.
212 lat CPU latency (wait) time.
215 stop Stopped time.
218 -p pid Displays a snapshot of timing statistics for the specified
222 pid.
223 To set the credentials of another process, a process must have suffi‐
227 cient privilege to change its user and group ids to those specified
228 according to the rules laid out in setuid(2) and it must have suffi‐
229 cient privilege to control the target process.
230
232 These proc tools stop their target processes while inspecting them and
233 reporting the results: pfiles, pldd, and pstack. A process can do noth‐
234 ing while it is stopped. Thus, for example, if the X server is
235 inspected by one of these proc tools running in a window under the X
236 server's control, the whole window system can become deadlocked because
237 the proc tool would be attempting to print its results to a window that
238 cannot be refreshed. Logging in from from another system using
239 rlogin(1) and killing the offending proc tool would clear up the dead‐
240 lock in this case.
241 See WARNINGS.
244 Caution should be exercised when using the -F flag. Imposing two con‐
247 trolling processes on one victim process can lead to chaos. Safety is
248 assured only if the primary controlling process, typically a debugger,
249 has stopped the victim process and the primary controlling process is
250 doing nothing at the moment of application of the proc tool in ques‐
251 tion.
252 Some of the proc tools can also be applied to core files, as shown by
255 the synopsis above. A core file is a snapshot of a process's state and
256 is produced by the kernel prior to terminating a process with a signal
257 or by the gcore(1) utility. Some of the proc tools can need to derive
258 the name of the executable corresponding to the process which dumped
259 core or the names of shared libraries associated with the process.
260 These files are needed, for example, to provide symbol table informa‐
261 tion for pstack(1). If the proc tool in question is unable to locate
262 the needed executable or shared library, some symbol information is
263 unavailable for display. Similarly, if a core file from one operating
264 system release is examined on a different operating system release, the
265 run-time link-editor debugging interface (librtld_db) cannot be able to
266 initialize. In this case, symbol information for shared libraries is
267 not available.
268
270 The following exit values are returned:
271 0 Successful operation.
273 non-zero An error has occurred.
276
279 /proc/* process files
280
283 See attributes(5) for descriptions of the following attributes:
284 ┌─────────────────────────────┬─────────────────────────────┐
289 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
290 ├─────────────────────────────┼─────────────────────────────┤
291 │Availability │SUNWesu │
292 ├─────────────────────────────┼─────────────────────────────┤
293 │Interface Stability │See below. │
294 └─────────────────────────────┴─────────────────────────────┘
295 The human readable output is Uncommitted. The options are Committed.
298
300 gcore(1), ldd(1), pargs(1), pgrep(1), pkill(1), plimit(1), pmap(1),
301 preap(1), ps(1), ptree(1), ppgsz(1), pwd(1), rlogin(1), time(1),
302 truss(1), wait(1), fcntl(2), fstat(2), setuid(2), dlopen(3C), sig‐
303 nal.h(3HEAD), core(4), proc(4), process(4), attributes(5), zones(5)
304
306 The following proc tools stop their target processes while inspecting
307 them and reporting the results: pfiles, pldd, and pstack. However, even
308 if pstack operates on an individual thread, it stops the whole process.
309 A process or thread can do nothing while it is stopped. Stopping a
312 heavily used process or thread in a production environment, even for a
313 short amount of time, can cause severe bottlenecks and even hangs of
314 these processes or threads, causing them to be unavailable to users.
315 Some databases could also terminate abnormally. Thus, for example, a
316 database server under heavy load could hang when one of the database
317 processes or threads is traced using the above mentioned proc tools.
318 Because of this, stopping a UNIX process or thread in a production
319 environment should be avoided.
320 A process or thread being stopped by these tools can be identified by
323 issuing /usr/bin/ps -eflL and looking for "T" in the first column.
324 Notice that certain processes, for example "sched", can show the "T"
325 status by default most of the time.
326 The process ID returned for locked files on network file systems might
329 not be meaningful.
330SunOS 5.11 10 Dec 2008 proc(1)