xref: /freebsd/usr.bin/procstat/procstat.1 (revision 38069501) 
1.\"-
2.\" Copyright (c) 2007-2009 Robert N. M. Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd October 14, 2017
29.Dt PROCSTAT 1
30.Os
31.Sh NAME
32.Nm procstat
33.Nd get detailed process information
34.Sh SYNOPSIS
35.Nm
36.Op Fl -libxo
37.Op Fl h
38.Op Fl M Ar core
39.Op Fl N Ar system
40.Op Fl w Ar interval
41.Ar command
42.Op Ar pid ... | Ar core ...
43.Nm
44.Op Fl -libxo
45.Fl a
46.Op Fl h
47.Op Fl M Ar core
48.Op Fl N Ar system
49.Op Fl w Ar interval
50.Ar command
51.Nm
52.Op Fl -libxo
53.Op Fl h
54.Op Fl M Ar core
55.Op Fl N Ar system
56.Op Fl w Ar interval
57.Oo
58.Fl b |
59.Fl c |
60.Fl e |
61.Fl f Oo Fl C Oc |
62.Fl i Oo Fl n Oc |
63.Fl j Oo Fl n Oc |
64.Fl k Oo Fl k Oc |
65.Fl l |
66.Fl r Oo Fl H Oc |
67.Fl s |
68.Fl S |
69.Fl t |
70.Fl v |
71.Fl x
72.Oc
73.Op Ar pid ... | Ar core ...
74.Nm
75.Op Fl -libxo
76.Fl a
77.Op Fl h
78.Op Fl M Ar core
79.Op Fl N Ar system
80.Op Fl w Ar interval
81.Oo
82.Fl b |
83.Fl c |
84.Fl e |
85.Fl f Oo Fl C Oc |
86.Fl i Oo Fl n Oc |
87.Fl j Oo Fl n Oc |
88.Fl k Oo Fl k Oc |
89.Fl l |
90.Fl r Oo Fl H Oc |
91.Fl s |
92.Fl S |
93.Fl t |
94.Fl v |
95.Fl x
96.Oc
97.Nm
98.Op Fl -libxo
99.Fl L
100.Op Fl h
101.Op Fl M Ar core
102.Op Fl N Ar system
103.Op Fl w Ar interval
104.Ar core ...
105.Sh DESCRIPTION
106.Nm
107utility displays detailed information about the processes identified by the
108.Ar pid
109arguments, or if the
110.Fl a
111flag is used, all processes.
112It can also display information extracted from a process core file, if
113the core file is specified as the argument.
114.Pp
115If the
116.Fl -libxo
117flag is specified the output is generated via
118.Xr libxo 3
119in a selection of different human and machine readable formats.
120See
121.Xr xo_parse_args 3
122for details on command line arguments.
123.Pp
124The following commands are available:
125.Bl -tag -width indent
126.It Ar basic
127Print basic process statistics (this is the default).
128.It Ar binary | Fl b
129Display binary information for the process.
130.Pp
131Substring commands are accepted.
132.It Ar argument(s) | Fl c
133Display command line arguments for the process.
134.Pp
135Substring commands are accepted.
136.It Ar environment | Fl e
137Display environment variables for the process.
138.Pp
139Substring commands are accepted.
140.It Ar file(s) | Ar fd(s) | Fl f
141Display file descriptor information for the process.
142.Pp
143If the
144.Fl C
145subcommand flag is used then additional capability information is printed.
146.It Ar signal(s) | Fl i
147Display signal pending and disposition information for the process.
148.Pp
149If the
150.Fl n
151subcommand option is used, the signal numbers are shown instead of signal
152names.
153.Pp
154Substring commands are accepted.
155.It Ar tsignal(s) | Fl j
156Display signal pending and blocked information for the process's threads.
157.Pp
158If the
159.Fl n
160subcommand option is used, the signal numbers are shown instead of signal
161names.
162.Pp
163Substring commands are accepted.
164.It Ar kstack | Fl k
165Display the stacks of kernel threads in the process, excluding stacks of
166threads currently running on a CPU and threads with stacks swapped to disk.
167.Pp
168If the
169.Fl v
170subcommand option is used (or the command flag is repeated), function
171offsets as well as function names are printed.
172.It Ar rlimit | Fl l
173Display resource limits for the process.
174.It Ar ptlwpinfo | Fl L
175Display LWP info for the process pertaining to its signal driven exit.
176.It Ar rusage | Fl r
177Display resource usage information for the process.
178.Pp
179If the
180.Fl v
181.Pq or Fl H
182subcommand flag
183is used then per-thread statistics are printed, rather than per-process
184statistics.
185The second field in the table will list the thread ID to which the row of
186information corresponds.
187.It Ar credential(s) | Fl s
188Display security credential information for the process.
189.Pp
190Substring commands are accepted.
191.It Ar cpuset | Ar cs | Fl S
192Display the cpuset information for the thread.
193.It Ar thread(s) | Fl t
194Display thread information for the process.
195.It Ar vm | Fl v
196Display virtual memory mappings for the process.
197.It Ar auxv | Fl x
198Display ELF auxiliary vector for the process.
199.El
200.Pp
201All options generate output in the format of a table, the first field of
202which is the process ID to which the row of information corresponds.
203The
204.Fl h
205flag may be used to suppress table headers.
206.Pp
207The
208.Fl w
209flag may be used to specify a wait interval at which to repeat the printing
210of the requested process information.
211If the
212.Fl w
213flag is not specified, the output will not repeat.
214.Pp
215Information for VM, file descriptor, and cpuset options is available
216only to the owner of a process or the superuser.
217A cpuset value displayed as -1 means that the information is either invalid
218or not available.
219.Ss Binary Information
220Display the process ID, command, and path to the process binary:
221.Pp
222.Bl -tag -width indent -compact
223.It PID
224process ID
225.It COMM
226command
227.It OSREL
228osreldate for process binary
229.It PATH
230path to process binary (if available)
231.El
232.Ss Command Line Arguments
233Display the process ID, command, and command line arguments:
234.Pp
235.Bl -tag -width indent -compact
236.It PID
237process ID
238.It COMM
239command
240.It ARGS
241command line arguments (if available)
242.El
243.Ss Environment Variables
244Display the process ID, command, and environment variables:
245.Pp
246.Bl -tag -width "ENVIRONMENT" -compact
247.It PID
248process ID
249.It COMM
250command
251.It ENVIRONMENT
252environment variables (if available)
253.El
254.Ss File Descriptors
255Display detailed information about each file descriptor referenced by a
256process, including the process ID, command, file descriptor number, and
257per-file descriptor object information, such as object type and file system
258path.
259By default, the following information will be printed:
260.Pp
261.Bl -tag -width indent -compact
262.It PID
263process ID
264.It COMM
265command
266.It FD
267file descriptor number or cwd/root/jail
268.It T
269file descriptor type
270.It V
271vnode type
272.It FLAGS
273file descriptor flags
274.It REF
275file descriptor reference count
276.It OFFSET
277file descriptor offset
278.It PRO
279network protocol
280.It NAME
281file path or socket addresses (if available)
282.El
283.Pp
284The following file descriptor types may be displayed:
285.Pp
286.Bl -tag -width X -compact
287.It c
288crypto
289.It e
290POSIX semaphore
291.It f
292fifo
293.It h
294shared memory
295.It k
296kqueue
297.It m
298message queue
299.It P
300process descriptor
301.It p
302pipe
303.It s
304socket
305.It t
306pseudo-terminal master
307.It v
308vnode
309.El
310.Pp
311The following vnode types may be displayed:
312.Pp
313.Bl -tag -width X -compact
314.It -
315not a vnode
316.It b
317block device
318.It c
319character device
320.It d
321directory
322.It f
323fifo
324.It l
325symbolic link
326.It r
327regular file
328.It s
329socket
330.It x
331revoked device
332.El
333.Pp
334The following file descriptor flags may be displayed:
335.Pp
336.Bl -tag -width X -compact
337.It r
338read
339.It w
340write
341.It a
342append
343.It s
344async
345.It f
346fsync
347.It n
348non-blocking
349.It d
350direct I/O
351.It l
352lock held
353.El
354.Pp
355If the
356.Fl C
357flag is specified, the vnode type, reference count, and offset fields will be
358omitted, and a new capabilities field will be included listing capabilities,
359as described in
360.Xr cap_rights_limit 2 ,
361present for each capability descriptor.
362.Pp
363The following network protocols may be displayed (grouped by address family):
364.Pp
365.Dv AF_INET ,
366.Dv AF_INET6
367.Pp
368.Bl -tag -width indent -compact
369.It ICM
370.Dv IPPROTO_ICMP ;
371see
372.Xr icmp 4 .
373.It IPD
374.Dv IPPROTO_DIVERT ;
375see
376.Xr divert 4 .
377.It IP\?
378unknown protocol.
379.It RAW
380.Dv IPPROTO_RAW ;
381see
382.Xr ip 4 .
383.It SCT
384.Dv IPPROTO_SCTP ;
385see
386.Xr sctp 4 .
387.It TCP
388.Dv IPPROTO_TCP ;
389see
390.Xr tcp 4 .
391.It UDP
392.Dv IPPROTO_UDP ;
393see
394.Xr udp 4 .
395.El
396.Pp
397.Dv AF_LOCAL
398.Pp
399.Bl -tag -width indent -compact
400.It UDD
401.Dv IPPROTO_UDP ;
402see
403.Xr udp 4 .
404.It UDS
405.Dv IPPROTO_TCP ;
406see
407.Xr tcp 4 .
408.It UD\?
409unknown protocol.
410.El
411.Pp
412.Bl -tag -width indent -compact
413.It \?
414unknown address family.
415.El
416.Ss Signal Disposition Information
417Display signal pending and disposition for a process:
418.Pp
419.Bl -tag -width indent -compact
420.It PID
421process ID
422.It COMM
423command
424.It SIG
425signal name
426.It FLAGS
427process signal disposition details, three symbols
428.Bl -tag -width X -compact
429.It P
430if signal is pending in the global process queue; - otherwise.
431.It I
432if signal delivery disposition is
433.Dv SIG_IGN;
434- otherwise.
435.It C
436if the signal will be caught; - otherwise.
437.El
438.El
439.Pp
440If
441.Fl n
442switch is given, the signal numbers are shown instead of signal names.
443.Ss Thread Signal Information
444Display signal pending and blocked for a process's threads:
445.Pp
446.Bl -tag -width indent -compact
447.It PID
448process ID
449.It TID
450thread ID
451.It COMM
452command
453.It SIG
454signal name
455.It FLAGS
456thread signal delivery status, two symbols
457.Bl -tag -width X -compact
458.It P
459if signal is pending for the thread, - otherwise
460.It B
461if signal is blocked in the thread signal mask, - if not blocked
462.El
463.El
464.Pp
465The
466.Fl n
467switch has the same effect as for the
468.Fl i
469switch: the signal numbers are shown instead of signal names.
470.Ss Kernel Thread Stacks
471Display kernel thread stacks for a process, allowing further interpretation
472of thread wait channels.
473If the
474.Fl k
475flag is repeated, function offsets, not just function names, are printed.
476.Pp
477This feature requires
478.Cd "options STACK"
479or
480.Cd "options DDB"
481to be compiled into the kernel.
482.Pp
483.Bl -tag -width indent -compact
484.It PID
485process ID
486.It TID
487thread ID
488.It COMM
489command
490.It TDNAME
491thread name
492.It KSTACK
493kernel thread call stack
494.El
495.Ss Resource Limits
496Display resource limits for a process:
497.Pp
498.Bl -tag -width indent -compact
499.It PID
500process ID
501.It COMM
502command
503.It RLIMIT
504resource limit name
505.It SOFT
506soft limit
507.It HARD
508hard limit
509.El
510.Ss Resource Usage
511Display resource usage for a process.
512If the
513.Fl H
514flag is specified,
515resource usage for individual threads is displayed instead.
516.Pp
517.Bl -tag -width "RESOURCE" -compact
518.It PID
519process ID
520.It TID
521thread ID
522.Po
523if
524.Fl H
525is specified
526.Pc
527.It COMM
528command
529.It RESOURCE
530resource name
531.It VALUE
532current usage
533.El
534.Ss Security Credentials
535Display process credential information:
536.Pp
537.Bl -tag -width indent -compact
538.It PID
539process ID
540.It COMM
541command
542.It EUID
543effective user ID
544.It RUID
545real user ID
546.It SVUID
547saved user ID
548.It EGID
549effective group ID
550.It RGID
551real group ID
552.It SVGID
553saved group ID
554.It UMASK
555file creation mode mask
556.It FLAGS
557credential flags
558.It GROUPS
559group set
560.El
561.Pp
562The following credential flags may be displayed:
563.Pp
564.Bl -tag -width X -compact
565.It C
566capability mode
567.El
568.Ss Thread Information
569Display per-thread information, including process ID, per-thread ID, name,
570CPU, and execution state:
571.Pp
572.Bl -tag -width indent -compact
573.It PID
574process ID
575.It TID
576thread ID
577.It COMM
578command
579.It TDNAME
580thread name
581.It CPU
582current or most recent CPU run on
583.It PRI
584thread priority
585.It STATE
586thread state
587.It WCHAN
588thread wait channel
589.El
590.Ss Virtual Memory Mappings
591Display process virtual memory mappings, including addresses, mapping
592meta-data, and mapped object information:
593.Pp
594.Bl -tag -width indent -compact
595.It PID
596process ID
597.It START
598starting address of mapping
599.It END
600ending address of mapping
601.It PRT
602protection flags
603.It RES
604resident pages
605.It PRES
606private resident pages
607.It REF
608reference count
609.It SHD
610shadow page count
611.It FLAG
612mapping flags
613.It TP
614VM object type
615.El
616.Pp
617The following protection flags may be displayed:
618.Pp
619.Bl -tag -width X -compact
620.It r
621read
622.It w
623write
624.It x
625execute
626.El
627.Pp
628The following VM object types may be displayed:
629.Pp
630.Bl -tag -width XX -compact
631.It --
632none
633.It dd
634dead
635.It df
636default
637.It dv
638device
639.It md
640device with managed pages
641.Pq GEM/TTM
642.It ph
643physical
644.It sg
645scatter/gather
646.It sw
647swap
648.It vn
649vnode
650.El
651.Pp
652The following mapping flags may be displayed:
653.Pp
654.Bl -tag -width X -compact
655.It C
656copy-on-write
657.It N
658needs copy
659.It S
660one or more superpage mappings are used
661.It D
662grows down (top-down stack)
663.It U
664grows up (bottom-up stack)
665.El
666.Ss ELF Auxiliary Vector
667Display ELF auxiliary vector values:
668.Pp
669.Bl -tag -width indent -compact
670.It PID
671process ID
672.It COMM
673command
674.It AUXV
675auxiliary vector name
676.It VALUE
677auxiliary vector value
678.El
679.Sh EXIT STATUS
680.Ex -std
681.Sh SEE ALSO
682.Xr fstat 1 ,
683.Xr ps 1 ,
684.Xr sockstat 1 ,
685.Xr cap_enter 2 ,
686.Xr cap_rights_limit 2 ,
687.Xr libprocstat 3 ,
688.Xr libxo 3 ,
689.Xr signal 3 ,
690.Xr xo_parse_args 3 ,
691.Xr ddb 4 ,
692.Xr divert 4 ,
693.Xr icmp 4 ,
694.Xr ip 4 ,
695.Xr sctp 4 ,
696.Xr tcp 4 ,
697.Xr udp 4 ,
698.Xr stack 9
699.Sh AUTHORS
700.An Robert N M Watson Aq Mt rwatson@FreeBSD.org .
701.br
702.Xr libxo 3
703support was added by
704.An -nosplit
705Allan Jude
706.Aq Mt allanjude@FreeBSD.org .
707.Sh BUGS
708The display of open file or memory mapping pathnames is implemented using the
709kernel's name cache.
710If a file system does not use the name cache, or the path to a file is not in
711the cache, a path will not be displayed.
712.Pp
713.Nm
714currently supports extracting data only from a live kernel, and not from
715kernel crash dumps.
716