| blob | 4a428e55fd688769af476bce5541cb843e3cd467 |
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 "Jun 15, 2016"
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. If an lwp has a non-empty signal mask, it will be printed.
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). Use \fBpflags\fR to see more information about currently
145 pending signals and signal masks.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fBpstack\fR\fR
152 .ad
153 .RS 10n
154 Print a hex+symbolic stack trace for each process or specified lwps in each
155 process.
156 .RE
158 .sp
159 .ne 2
160 .na
161 \fB\fBpfiles\fR\fR
162 .ad
163 .RS 10n
164 Report \fBfstat\fR(2) and \fBfcntl\fR(2) information for all open files in each
165 process. For network endpoints, the local (and peer if connected) address
166 information is also provided. For sockets, the socket type, socket options and
167 send and receive buffer sizes are also provided. In addition, a path to the
168 file is reported if the information is available from \fB/proc/pid/path\fR.
169 This is not necessarily the same name used to open the file. See \fBproc\fR(4)
170 for more information.
171 .RE
173 .sp
174 .ne 2
175 .na
176 \fB\fBpwdx\fR\fR
177 .ad
178 .RS 10n
179 Print the current working directory of each process.
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fB\fBpstop\fR\fR
186 .ad
187 .RS 10n
188 Stop each process or the specified lwps (\fBPR_REQUESTED\fR stop).
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBprun\fR\fR
195 .ad
196 .RS 10n
197 Set running each process or the specified lwps (the inverse of \fBpstop\fR).
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fBpwait\fR\fR
204 .ad
205 .RS 10n
206 Wait for all of the specified processes to terminate.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fBptime\fR\fR
213 .ad
214 .RS 10n
215 Time the \fIcommand\fR, like \fBtime\fR(1), but using microstate accounting for
216 reproducible precision. Unlike \fBtime\fR(1), children of the command are not
217 timed.
218 .sp
219 If the \fB-p\fR \fIpidlist\fR version is used, display a snapshot of timing
220 statistics for the specified processes. The \fIpidlist\fR may have a single
221 process or be a comma or space delineated list. If a space delineated list is
222 used, callers will need to ensure that it is properly quoted or escaped for
223 their shell.
224 .RE
226 .SH OPTIONS
227 .LP
228 The following general options are supported:
229 .sp
230 .ne 2
231 .na
232 \fB\fB-F\fR\fR
233 .ad
234 .RS 6n
235 Force. Grabs the target process even if another process has control.
236 .RE
238 .sp
239 .ne 2
240 .na
241 \fB\fB-n\fR\fR
242 .ad
243 .RS 6n
244 (\fBpsig\fR and \fBpfiles\fR only) Sets non-verbose mode. \fBpsig\fR displays
245 signal handler addresses rather than names. \fBpfiles\fR does not display
246 verbose information for each file descriptor. Instead, \fBpfiles\fR limits its
247 output to the information that would be retrieved if the process applied
248 \fBfstat\fR(2) to each of its file descriptors.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fB-r\fR\fR
255 .ad
256 .RS 6n
257 (\fBpflags\fR only) If the process is stopped, displays its machine registers.
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fB-v\fR\fR
264 .ad
265 .RS 6n
266 (\fBpwait\fR only) Verbose. Reports terminations to standard output.
267 .RE
269 .sp
270 .LP
271 In addition to the general options, \fBpcred\fR supports the following options:
272 .sp
273 .ne 2
274 .na
275 \fB\fB-g\fR \fIgroup/gid\fR\fR
276 .ad
277 .RS 16n
278 Sets the real, effective, and saved group ids (\fBGID\fRs) of the target
279 processes to the specified value.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fB-G\fR \fIgrouplist\fR\fR
286 .ad
287 .RS 16n
288 Sets the supplementary \fBGID\fRs of the target process to the specified list
289 of groups. The supplementary groups should be specified as a comma-separated
290 list of group names ids. An empty list clears the supplementary group list of
291 the target processes.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fB-l\fR \fIlogin\fR\fR
298 .ad
299 .RS 16n
300 Sets the real, effective, and saved \fBUID\fRs of the target processes to the
301 \fBUID\fR of the specified login. Sets the real, effective, and saved
302 \fBGID\fRs of the target processes to the \fBGID\fR of the specified login.
303 Sets the supplementary group list to the supplementary groups list of the
304 specified login.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fB-u\fR \fIuser/uid\fR\fR
311 .ad
312 .RS 16n
313 Sets the real, effective, and saved user ids (\fBUID\fRs) of the target
314 processes to the specified value.
315 .RE
317 .sp
318 .LP
319 In addition to the general options, \fBpldd\fR supports the following option:
320 .sp
321 .ne 2
322 .na
323 \fB\fB-l\fR\fR
324 .ad
325 .RS 6n
326 Shows unresolved dynamic linker map names.
327 .RE
329 .sp
330 .LP
331 In addition to the general options, \fBptime\fR supports the following options:
332 .sp
333 .ne 2
334 .na
335 \fB\fB-m\fR\fR
336 .ad
337 .RS 10n
338 Display the full set of microstate accounting statistics.
339 .sp
340 The displayed fields are as follows:
341 .sp
342 .ne 2
343 .na
344 \fB\fBreal\fR\fR
345 .ad
346 .RS 8n
347 Wall clock time.
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fBuser\fR\fR
354 .ad
355 .RS 8n
356 User level CPU time.
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBsys\fR\fR
363 .ad
364 .RS 8n
365 System call CPU time.
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBtrap\fR\fR
372 .ad
373 .RS 8n
374 Other system trap CPU time.
375 .RE
377 .sp
378 .ne 2
379 .na
380 \fB\fBtflt\fR\fR
381 .ad
382 .RS 8n
383 Text page fault sleep time.
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fBdflt\fR\fR
390 .ad
391 .RS 8n
392 Data page fault sleep time.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB\fBkflt\fR\fR
399 .ad
400 .RS 8n
401 Kernel page fault sleep time.
402 .RE
404 .sp
405 .ne 2
406 .na
407 \fB\fBlock\fR\fR
408 .ad
409 .RS 8n
410 User lock wait sleep time.
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBslp\fR\fR
417 .ad
418 .RS 8n
419 All other sleep time.
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fBlat\fR\fR
426 .ad
427 .RS 8n
428 CPU latency (wait) time.
429 .RE
431 .sp
432 .ne 2
433 .na
434 \fB\fBstop\fR\fR
435 .ad
436 .RS 8n
437 Stopped time.
438 .RE
440 .RE
442 .sp
443 .ne 2
444 .na
445 \fB\fB-p\fR \fIpid\fR\fR
446 .ad
447 .RS 10n
448 Displays a snapshot of timing statistics for the specified \fIpid\fR.
449 .RE
451 .sp
452 .LP
453 To set the credentials of another process, a process must have sufficient
454 privilege to change its user and group ids to those specified according to the
455 rules laid out in \fBsetuid\fR(2) and it must have sufficient privilege to
456 control the target process.
457 .SH USAGE
458 .LP
459 These proc tools stop their target processes while inspecting them and
460 reporting the results: \fBpfiles\fR, \fBpldd\fR, and \fBpstack\fR. A process
461 can do nothing while it is stopped. Thus, for example, if the X server is
462 inspected by one of these proc tools running in a window under the X server's
463 control, the whole window system can become deadlocked because the proc tool
464 would be attempting to print its results to a window that cannot be refreshed.
465 Logging in from from another system using \fBrlogin\fR(1) and killing the
466 offending proc tool would clear up the deadlock in this case.
467 .sp
468 .LP
469 See \fBWARNINGS\fR.
470 .sp
471 .LP
472 Caution should be exercised when using the \fB-F\fR flag. Imposing two
473 controlling processes on one victim process can lead to chaos. Safety is
474 assured only if the primary controlling process, typically a debugger, has
475 stopped the victim process and the primary controlling process is doing nothing
476 at the moment of application of the \fBproc\fR tool in question.
477 .sp
478 .LP
479 Some of the proc tools can also be applied to core files, as shown by the
480 synopsis above. A core file is a snapshot of a process's state and is produced
481 by the kernel prior to terminating a process with a signal or by the
482 \fBgcore\fR(1) utility. Some of the proc tools can need to derive the name of
483 the executable corresponding to the process which dumped core or the names of
484 shared libraries associated with the process. These files are needed, for
485 example, to provide symbol table information for \fBpstack\fR(1). If the proc
486 tool in question is unable to locate the needed executable or shared library,
487 some symbol information is unavailable for display. Similarly, if a core file
488 from one operating system release is examined on a different operating system
489 release, the run-time link-editor debugging interface (\fBlibrtld_db\fR) cannot
490 be able to initialize. In this case, symbol information for shared libraries is
491 not available.
492 .SH EXIT STATUS
493 .LP
494 The following exit values are returned:
495 .sp
496 .ne 2
497 .na
498 \fB\fB0\fR\fR
499 .ad
500 .RS 12n
501 Successful operation.
502 .RE
504 .sp
505 .ne 2
506 .na
507 \fBnon-zero\fR
508 .ad
509 .RS 12n
510 An error has occurred.
511 .RE
513 .SH FILES
514 .ne 2
515 .na
516 \fB\fB/proc/*\fR\fR
517 .ad
518 .RS 11n
519 process files
520 .RE
522 .SH ATTRIBUTES
523 .LP
524 See \fBattributes\fR(5) for descriptions of the following attributes:
525 .sp
527 .sp
528 .TS
529 box;
530 c | c
531 l | l .
532 ATTRIBUTE TYPE ATTRIBUTE VALUE
533 _
534 Interface Stability See below.
535 .TE
537 .sp
538 .LP
539 The human readable output is Uncommitted. The options are Committed.
540 .SH SEE ALSO
541 .LP
542 \fBgcore\fR(1), \fBldd\fR(1), \fBpargs\fR(1), \fBpgrep\fR(1), \fBpkill\fR(1),
543 \fBplimit\fR(1), \fBpmap\fR(1), \fBpreap\fR(1), \fBps\fR(1), \fBptree\fR(1),
544 \fBppgsz\fR(1), \fBpwd\fR(1), \fBrlogin\fR(1), \fBtime\fR(1), \fBtruss\fR(1),
545 \fBwait\fR(1), \fBfcntl\fR(2), \fBfstat\fR(2), \fBsetuid\fR(2),
546 \fBdlopen\fR(3C), \fBsignal.h\fR(3HEAD), \fBcore\fR(4), \fBproc\fR(4),
547 \fBprocess\fR(4), \fBattributes\fR(5), \fBzones\fR(5)
548 .SH WARNINGS
549 .LP
550 The following \fBproc\fR tools stop their target processes while inspecting
551 them and reporting the results: \fBpfiles\fR, \fBpldd\fR, and \fBpstack\fR.
552 However, even if \fBpstack\fR operates on an individual thread, it stops the
553 whole process.
554 .sp
555 .LP
556 A process or thread can do nothing while it is stopped. Stopping a heavily used
557 process or thread in a production environment, even for a short amount of time,
558 can cause severe bottlenecks and even hangs of these processes or threads,
559 causing them to be unavailable to users. Some databases could also terminate
560 abnormally. Thus, for example, a database server under heavy load could hang
561 when one of the database processes or threads is traced using the above
562 mentioned \fBproc\fR tools. Because of this, stopping a UNIX process or thread
563 in a production environment should be avoided.
564 .sp
565 .LP
566 A process or thread being stopped by these tools can be identified by issuing
567 \fB/usr/bin/ps\fR \fB-eflL\fR and looking for "\fBT\fR" in the first column.
568 Notice that certain processes, for example "\fBsched\fR", can show the
569 "\fBT\fR" status by default most of the time.
570 .sp
571 .LP
572 The process ID returned for locked files on network file systems might not be
573 meaningful.