| blob | e00553581061729c3e282849d3c8d49e7552189b |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" Portions Copyright 2008 Chad Mynhier
4 .\" Copyright 2012 DEY Storage Systems, Inc. All rights reserved.
5 .\" Copyright 2016 Joyent, Inc.
6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
9 .TH PROC 1 "Apr 01, 2013"
10 .SH NAME
11 proc, pflags, pcred, pldd, psig, pstack, pfiles, pwdx, pstop, prun, pwait,
12 ptime \- proc tools
13 .SH SYNOPSIS
14 .LP
15 .nf
16 \fB/usr/bin/pflags\fR [\fB-r\fR] \fIpid\fR | \fIcore\fR [/\fIlwp\fR] ...
17 .fi
19 .LP
20 .nf
21 \fB/usr/bin/pcred\fR [\fIpid\fR | \fIcore\fR]...
22 .fi
24 .LP
25 .nf
26 \fB/usr/bin/pcred\fR [\fB-u\fR \fIuser/uid\fR] [\fB-g\fR \fIgroup/gid\fR] [\fB-G\fR \fIgrouplist\fR] pid...
27 .fi
29 .LP
30 .nf
31 \fB/usr/bin/pcred\fR \fB-l\fR \fIlogin\fR \fIpid\fR...
32 .fi
34 .LP
35 .nf
36 \fB/usr/bin/pldd\fR [\fB-Fl\fR] [\fIpid\fR | \fIcore\fR]...
37 .fi
39 .LP
40 .nf
41 \fB/usr/bin/psig\fR [\fB-n\fR] \fIpid\fR...
42 .fi
44 .LP
45 .nf
46 \fB/usr/bin/pstack\fR [\fB-F\fR] \fIpid\fR | \fIcore\fR [/\fIlwp\fR] ...
47 .fi
49 .LP
50 .nf
51 \fB/usr/bin/pfiles\fR [\fB-Fn\fR] \fIpid\fR | \fIcore\fR...
52 .fi
54 .LP
55 .nf
56 \fB/usr/bin/pwdx\fR \fIpid\fR...
57 .fi
59 .LP
60 .nf
61 \fB/usr/bin/pstop\fR \fIpid\fR[/\fIlwp\fR] ...
62 .fi
64 .LP
65 .nf
66 \fB/usr/bin/prun\fR \fIpid\fR[/\fIlwp\fR] ...
67 .fi
69 .LP
70 .nf
71 \fB/usr/bin/pwait\fR [\fB-v\fR] \fIpid\fR...
72 .fi
74 .LP
75 .nf
76 \fB/usr/bin/ptime\fR [\fB-Fm\fR] \fB-p pidlist\fR
77 .fi
79 .LP
80 .nf
81 \fB/usr/bin/ptime\fR [\fB-m\fR]\fIcommand\fR [\fIarg\fR]...
82 .fi
84 .SH DESCRIPTION
85 .LP
86 The proc tools are utilities that exercise features of \fB/proc\fR (see
87 \fBproc\fR(4)). Most of them take a list of process-ids (\fIpid\fR). The tools
88 that do take process-ids also accept \fB/proc/\fR\fInnn\fR as a process-id, so
89 the shell expansion \fB/proc/*\fR can be used to specify all processes in the
90 system.
91 .sp
92 .LP
93 Some of the proc tools can also be applied to core files (see \fBcore\fR(4)).
94 The tools that apply to core files accept a list of either process \fBID\fRs or
95 names of core files or both.
96 .sp
97 .LP
98 Some of the \fBproc\fR tools can operate on individual threads. Users can
99 examine only selected threads by appending \fI/thread-id\fR to the process-id
100 or core. Multiple threads can be selected using the \fB-\fR and \fB,\fR
101 delimiters. For example \fB/1,2,7-9\fR examines threads \fB1\fR, \fB2\fR,
102 \fB7\fR, \fB8\fR, and \fB9\fR.
103 .sp
104 .LP
105 See \fBWARNINGS\fR.
106 .sp
107 .ne 2
108 .na
109 \fB\fBpflags\fR\fR
110 .ad
111 .RS 10n
112 Print the \fB/proc\fR tracing flags, the pending and held signals, and other
113 \fB/proc\fR status information for each process or specified lwps in each
114 process.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fBpcred\fR\fR
121 .ad
122 .RS 10n
123 Print or set the credentials (effective, real, saved \fBUID\fRs and \fBGID\fRs)
124 of each process.
125 .RE
127 .sp
128 .ne 2
129 .na
130 \fB\fBpldd\fR\fR
131 .ad
132 .RS 10n
133 List the dynamic libraries linked into each process, including shared objects
134 explicitly attached using \fBdlopen\fR(3C). See also \fBldd\fR(1).
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fB\fBpsig\fR\fR
141 .ad
142 .RS 10n
143 List the signal actions and handlers of each process. See
144 \fBsignal.h\fR(3HEAD).
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fBpstack\fR\fR
151 .ad
152 .RS 10n
153 Print a hex+symbolic stack trace for each process or specified lwps in each
154 process.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fBpfiles\fR\fR
161 .ad
162 .RS 10n
163 Report \fBfstat\fR(2) and \fBfcntl\fR(2) information for all open files in each
164 process. For network endpoints, the local (and peer if connected) address
165 information is also provided. For sockets, the socket type, socket options and
166 send and receive buffer sizes are also provided. In addition, a path to the
167 file is reported if the information is available from \fB/proc/pid/path\fR.
168 This is not necessarily the same name used to open the file. See \fBproc\fR(4)
169 for more information.
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fBpwdx\fR\fR
176 .ad
177 .RS 10n
178 Print the current working directory of each process.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fBpstop\fR\fR
185 .ad
186 .RS 10n
187 Stop each process or the specified lwps (\fBPR_REQUESTED\fR stop).
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fBprun\fR\fR
194 .ad
195 .RS 10n
196 Set running each process or the specified lwps (the inverse of \fBpstop\fR).
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fBpwait\fR\fR
203 .ad
204 .RS 10n
205 Wait for all of the specified processes to terminate.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fBptime\fR\fR
212 .ad
213 .RS 10n
214 Time the \fIcommand\fR, like \fBtime\fR(1), but using microstate accounting for
215 reproducible precision. Unlike \fBtime\fR(1), children of the command are not
216 timed.
217 .sp
218 If the \fB-p\fR \fIpidlist\fR version is used, display a snapshot of timing
219 statistics for the specified processes. The \fIpidlist\fR may have a single
220 process or be a comma or space delineated list. If a space delineated list is
221 used, callers will need to ensure that it is properly quoted or escaped for
222 their shell.
223 .RE
225 .SH OPTIONS
226 .LP
227 The following general options are supported:
228 .sp
229 .ne 2
230 .na
231 \fB\fB-F\fR\fR
232 .ad
233 .RS 6n
234 Force. Grabs the target process even if another process has control.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fB-n\fR\fR
241 .ad
242 .RS 6n
243 (\fBpsig\fR and \fBpfiles\fR only) Sets non-verbose mode. \fBpsig\fR displays
244 signal handler addresses rather than names. \fBpfiles\fR does not display
245 verbose information for each file descriptor. Instead, \fBpfiles\fR limits its
246 output to the information that would be retrieved if the process applied
247 \fBfstat\fR(2) to each of its file descriptors.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fB-r\fR\fR
254 .ad
255 .RS 6n
256 (\fBpflags\fR only) If the process is stopped, displays its machine registers.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fB-v\fR\fR
263 .ad
264 .RS 6n
265 (\fBpwait\fR only) Verbose. Reports terminations to standard output.
266 .RE
268 .sp
269 .LP
270 In addition to the general options, \fBpcred\fR supports the following options:
271 .sp
272 .ne 2
273 .na
274 \fB\fB-g\fR \fIgroup/gid\fR\fR
275 .ad
276 .RS 16n
277 Sets the real, effective, and saved group ids (\fBGID\fRs) of the target
278 processes to the specified value.
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fB\fB-G\fR \fIgrouplist\fR\fR
285 .ad
286 .RS 16n
287 Sets the supplementary \fBGID\fRs of the target process to the specified list
288 of groups. The supplementary groups should be specified as a comma-separated
289 list of group names ids. An empty list clears the supplementary group list of
290 the target processes.
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fB\fB-l\fR \fIlogin\fR\fR
297 .ad
298 .RS 16n
299 Sets the real, effective, and saved \fBUID\fRs of the target processes to the
300 \fBUID\fR of the specified login. Sets the real, effective, and saved
301 \fBGID\fRs of the target processes to the \fBGID\fR of the specified login.
302 Sets the supplementary group list to the supplementary groups list of the
303 specified login.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fB\fB-u\fR \fIuser/uid\fR\fR
310 .ad
311 .RS 16n
312 Sets the real, effective, and saved user ids (\fBUID\fRs) of the target
313 processes to the specified value.
314 .RE
316 .sp
317 .LP
318 In addition to the general options, \fBpldd\fR supports the following option:
319 .sp
320 .ne 2
321 .na
322 \fB\fB-l\fR\fR
323 .ad
324 .RS 6n
325 Shows unresolved dynamic linker map names.
326 .RE
328 .sp
329 .LP
330 In addition to the general options, \fBptime\fR supports the following options:
331 .sp
332 .ne 2
333 .na
334 \fB\fB-m\fR\fR
335 .ad
336 .RS 10n
337 Display the full set of microstate accounting statistics.
338 .sp
339 The displayed fields are as follows:
340 .sp
341 .ne 2
342 .na
343 \fB\fBreal\fR\fR
344 .ad
345 .RS 8n
346 Wall clock time.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBuser\fR\fR
353 .ad
354 .RS 8n
355 User level CPU time.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBsys\fR\fR
362 .ad
363 .RS 8n
364 System call CPU time.
365 .RE
367 .sp
368 .ne 2
369 .na
370 \fB\fBtrap\fR\fR
371 .ad
372 .RS 8n
373 Other system trap CPU time.
374 .RE
376 .sp
377 .ne 2
378 .na
379 \fB\fBtflt\fR\fR
380 .ad
381 .RS 8n
382 Text page fault sleep time.
383 .RE
385 .sp
386 .ne 2
387 .na
388 \fB\fBdflt\fR\fR
389 .ad
390 .RS 8n
391 Data page fault sleep time.
392 .RE
394 .sp
395 .ne 2
396 .na
397 \fB\fBkflt\fR\fR
398 .ad
399 .RS 8n
400 Kernel page fault sleep time.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fBlock\fR\fR
407 .ad
408 .RS 8n
409 User lock wait sleep time.
410 .RE
412 .sp
413 .ne 2
414 .na
415 \fB\fBslp\fR\fR
416 .ad
417 .RS 8n
418 All other sleep time.
419 .RE
421 .sp
422 .ne 2
423 .na
424 \fB\fBlat\fR\fR
425 .ad
426 .RS 8n
427 CPU latency (wait) time.
428 .RE
430 .sp
431 .ne 2
432 .na
433 \fB\fBstop\fR\fR
434 .ad
435 .RS 8n
436 Stopped time.
437 .RE
439 .RE
441 .sp
442 .ne 2
443 .na
444 \fB\fB-p\fR \fIpid\fR\fR
445 .ad
446 .RS 10n
447 Displays a snapshot of timing statistics for the specified \fIpid\fR.
448 .RE
450 .sp
451 .LP
452 To set the credentials of another process, a process must have sufficient
453 privilege to change its user and group ids to those specified according to the
454 rules laid out in \fBsetuid\fR(2) and it must have sufficient privilege to
455 control the target process.
456 .SH USAGE
457 .LP
458 These proc tools stop their target processes while inspecting them and
459 reporting the results: \fBpfiles\fR, \fBpldd\fR, and \fBpstack\fR. A process
460 can do nothing while it is stopped. Thus, for example, if the X server is
461 inspected by one of these proc tools running in a window under the X server's
462 control, the whole window system can become deadlocked because the proc tool
463 would be attempting to print its results to a window that cannot be refreshed.
464 Logging in from from another system using \fBrlogin\fR(1) and killing the
465 offending proc tool would clear up the deadlock in this case.
466 .sp
467 .LP
468 See \fBWARNINGS\fR.
469 .sp
470 .LP
471 Caution should be exercised when using the \fB-F\fR flag. Imposing two
472 controlling processes on one victim process can lead to chaos. Safety is
473 assured only if the primary controlling process, typically a debugger, has
474 stopped the victim process and the primary controlling process is doing nothing
475 at the moment of application of the \fBproc\fR tool in question.
476 .sp
477 .LP
478 Some of the proc tools can also be applied to core files, as shown by the
479 synopsis above. A core file is a snapshot of a process's state and is produced
480 by the kernel prior to terminating a process with a signal or by the
481 \fBgcore\fR(1) utility. Some of the proc tools can need to derive the name of
482 the executable corresponding to the process which dumped core or the names of
483 shared libraries associated with the process. These files are needed, for
484 example, to provide symbol table information for \fBpstack\fR(1). If the proc
485 tool in question is unable to locate the needed executable or shared library,
486 some symbol information is unavailable for display. Similarly, if a core file
487 from one operating system release is examined on a different operating system
488 release, the run-time link-editor debugging interface (\fBlibrtld_db\fR) cannot
489 be able to initialize. In this case, symbol information for shared libraries is
490 not available.
491 .SH EXIT STATUS
492 .LP
493 The following exit values are returned:
494 .sp
495 .ne 2
496 .na
497 \fB\fB0\fR\fR
498 .ad
499 .RS 12n
500 Successful operation.
501 .RE
503 .sp
504 .ne 2
505 .na
506 \fBnon-zero\fR
507 .ad
508 .RS 12n
509 An error has occurred.
510 .RE
512 .SH FILES
513 .ne 2
514 .na
515 \fB\fB/proc/*\fR\fR
516 .ad
517 .RS 11n
518 process files
519 .RE
521 .SH ATTRIBUTES
522 .LP
523 See \fBattributes\fR(5) for descriptions of the following attributes:
524 .sp
526 .sp
527 .TS
528 box;
529 c | c
530 l | l .
531 ATTRIBUTE TYPE ATTRIBUTE VALUE
532 _
533 Interface Stability See below.
534 .TE
536 .sp
537 .LP
538 The human readable output is Uncommitted. The options are Committed.
539 .SH SEE ALSO
540 .LP
541 \fBgcore\fR(1), \fBldd\fR(1), \fBpargs\fR(1), \fBpgrep\fR(1), \fBpkill\fR(1),
542 \fBplimit\fR(1), \fBpmap\fR(1), \fBpreap\fR(1), \fBps\fR(1), \fBptree\fR(1),
543 \fBppgsz\fR(1), \fBpwd\fR(1), \fBrlogin\fR(1), \fBtime\fR(1), \fBtruss\fR(1),
544 \fBwait\fR(1), \fBfcntl\fR(2), \fBfstat\fR(2), \fBsetuid\fR(2),
545 \fBdlopen\fR(3C), \fBsignal.h\fR(3HEAD), \fBcore\fR(4), \fBproc\fR(4),
546 \fBprocess\fR(4), \fBattributes\fR(5), \fBzones\fR(5)
547 .SH WARNINGS
548 .LP
549 The following \fBproc\fR tools stop their target processes while inspecting
550 them and reporting the results: \fBpfiles\fR, \fBpldd\fR, and \fBpstack\fR.
551 However, even if \fBpstack\fR operates on an individual thread, it stops the
552 whole process.
553 .sp
554 .LP
555 A process or thread can do nothing while it is stopped. Stopping a heavily used
556 process or thread in a production environment, even for a short amount of time,
557 can cause severe bottlenecks and even hangs of these processes or threads,
558 causing them to be unavailable to users. Some databases could also terminate
559 abnormally. Thus, for example, a database server under heavy load could hang
560 when one of the database processes or threads is traced using the above
561 mentioned \fBproc\fR tools. Because of this, stopping a UNIX process or thread
562 in a production environment should be avoided.
563 .sp
564 .LP
565 A process or thread being stopped by these tools can be identified by issuing
566 \fB/usr/bin/ps\fR \fB-eflL\fR and looking for "\fBT\fR" in the first column.
567 Notice that certain processes, for example "\fBsched\fR", can show the
568 "\fBT\fR" status by default most of the time.
569 .sp
570 .LP
571 The process ID returned for locked files on network file systems might not be
572 meaningful.