xref: /freebsd/usr.bin/procstat/procstat.1 (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
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 November 24, 2020
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.Nm pargs
106.Op Fl -libxo
107.Ar pid ...
108.Nm penv
109.Op Fl -libxo
110.Ar pid ...
111.Nm pwdx
112.Op Fl -libxo
113.Ar pid ...
114.Sh DESCRIPTION
115.Nm
116utility displays detailed information about the processes identified by the
117.Ar pid
118arguments, or if the
119.Fl a
120flag is used, all processes.
121It can also display information extracted from a process core file, if
122the core file is specified as the argument.
123.Pp
124The
125.Nm pargs ,
126.Nm penv
127and
128.Nm pwdx
129utilities display the arguments, environment, and current working directory,
130respectively of the process specified by
131.Ar pid
132argument.
133They mimic the behavior of Solaris utilities of the same names.
134.Pp
135If the
136.Fl -libxo
137flag is specified the output is generated via
138.Xr libxo 3
139in a selection of different human and machine readable formats.
140See
141.Xr xo_parse_args 3
142for details on command line arguments.
143.Pp
144The following commands are available for
145.Nm :
146.Bl -tag -width indent
147.It Ar basic
148Print basic process statistics (this is the default).
149.It Ar binary | Fl b
150Display binary information for the process.
151.Pp
152Substring commands are accepted.
153.It Ar argument(s) | Fl c
154Display command line arguments for the process.
155.Pp
156Substring commands are accepted.
157.It Ar environment | Fl e
158Display environment variables for the process.
159.Pp
160Substring commands are accepted.
161.It Ar file(s) | Ar fd(s) | Fl f
162Display file descriptor information for the process.
163.Pp
164If the
165.Fl C
166subcommand flag is used then additional capability information is printed.
167.It Ar signal(s) | Fl i
168Display signal pending and disposition information for the process.
169.Pp
170If the
171.Fl n
172subcommand option is used, the signal numbers are shown instead of signal
173names.
174.Pp
175Substring commands are accepted.
176.It Ar tsignal(s) | Fl j
177Display signal pending and blocked information for the process's threads.
178.Pp
179If the
180.Fl n
181subcommand option is used, the signal numbers are shown instead of signal
182names.
183.Pp
184Substring commands are accepted.
185.It Ar kstack | Fl k
186Display the stacks of kernel threads in the process, excluding stacks of
187threads currently running on a CPU and threads with stacks swapped to disk.
188.Pp
189If the
190.Fl v
191subcommand option is used (or the command flag is repeated), function
192offsets as well as function names are printed.
193.It Ar rlimit | Fl l
194Display resource limits for the process.
195.It Ar ptlwpinfo | Fl L
196Display LWP info for the process pertaining to its signal driven exit.
197.It Ar rusage | Fl r
198Display resource usage information for the process.
199.Pp
200If the
201.Fl v
202.Pq or Fl H
203subcommand flag
204is used then per-thread statistics are printed, rather than per-process
205statistics.
206The second field in the table will list the thread ID to which the row of
207information corresponds.
208.It Ar credential(s) | Fl s
209Display security credential information for the process.
210.Pp
211Substring commands are accepted.
212.It Ar cpuset | Ar cs | Fl S
213Display the cpuset information for the thread.
214.It Ar thread(s) | Fl t
215Display thread information for the process.
216.It Ar vm | Fl v
217Display virtual memory mappings for the process.
218.It Ar auxv | Fl x
219Display ELF auxiliary vector for the process.
220.It Ar pargs
221Display arguments for the process.
222.It Ar penv
223Display environment variables for the process.
224.It Ar pwdx
225Display current working directory for the process.
226.El
227.Pp
228All options generate output in the format of a table, the first field of
229which is the process ID to which the row of information corresponds.
230The
231.Fl h
232flag may be used to suppress table headers.
233.Pp
234The
235.Fl w
236flag may be used to specify a wait interval at which to repeat the printing
237of the requested process information.
238If the
239.Fl w
240flag is not specified, the output will not repeat.
241.Pp
242Information for VM, file descriptor, and cpuset options is available
243only to the owner of a process or the superuser.
244A cpuset value displayed as -1 means that the information is either invalid
245or not available.
246.Ss Binary Information
247Display the process ID, command, and path to the process binary:
248.Pp
249.Bl -tag -width indent -compact
250.It PID
251process ID
252.It COMM
253command
254.It OSREL
255osreldate for process binary
256.It PATH
257path to process binary (if available)
258.El
259.Ss Command Line Arguments
260Display the process ID, command, and command line arguments:
261.Pp
262.Bl -tag -width indent -compact
263.It PID
264process ID
265.It COMM
266command
267.It ARGS
268command line arguments (if available)
269.El
270.Ss Environment Variables
271Display the process ID, command, and environment variables:
272.Pp
273.Bl -tag -width "ENVIRONMENT" -compact
274.It PID
275process ID
276.It COMM
277command
278.It ENVIRONMENT
279environment variables (if available)
280.El
281.Ss File Descriptors
282Display detailed information about each file descriptor referenced by a
283process, including the process ID, command, file descriptor number, and
284per-file descriptor object information, such as object type and file system
285path.
286By default, the following information will be printed:
287.Pp
288.Bl -tag -width indent -compact
289.It PID
290process ID
291.It COMM
292command
293.It FD
294file descriptor number or cwd/root/jail
295.It T
296file descriptor type
297.It V
298vnode type
299.It FLAGS
300file descriptor flags
301.It REF
302file descriptor reference count
303.It OFFSET
304file descriptor offset
305.It PRO
306network protocol
307.It NAME
308file path or socket addresses (if available)
309.El
310.Pp
311The following file descriptor types may be displayed:
312.Pp
313.Bl -tag -width X -compact
314.It e
315POSIX semaphore
316.It E
317eventfd
318.It f
319fifo
320.It h
321shared memory
322.It k
323kqueue
324.It m
325message queue
326.It P
327process descriptor
328.It p
329pipe
330.It s
331socket
332.It t
333pseudo-terminal master
334.It v
335vnode
336.El
337.Pp
338The following vnode types may be displayed:
339.Pp
340.Bl -tag -width X -compact
341.It -
342not a vnode
343.It b
344block device
345.It c
346character device
347.It d
348directory
349.It f
350fifo
351.It l
352symbolic link
353.It r
354regular file
355.It s
356socket
357.It x
358revoked device
359.El
360.Pp
361The following file descriptor flags may be displayed:
362.Pp
363.Bl -tag -width X -compact
364.It r
365read
366.It w
367write
368.It a
369append
370.It s
371async
372.It f
373fsync
374.It n
375non-blocking
376.It d
377direct I/O
378.It l
379lock held
380.El
381.Pp
382If the
383.Fl C
384flag is specified, the vnode type, reference count, and offset fields will be
385omitted, and a new capabilities field will be included listing capabilities,
386as described in
387.Xr cap_rights_limit 2 ,
388present for each capability descriptor.
389.Pp
390The following network protocols may be displayed (grouped by address family):
391.Pp
392.Dv AF_INET ,
393.Dv AF_INET6
394.Pp
395.Bl -tag -width indent -compact
396.It ICM
397.Dv IPPROTO_ICMP ;
398see
399.Xr icmp 4 .
400.It IPD
401.Dv IPPROTO_DIVERT ;
402see
403.Xr divert 4 .
404.It IP?
405unknown protocol.
406.It RAW
407.Dv IPPROTO_RAW ;
408see
409.Xr ip 4 .
410.It SCT
411.Dv IPPROTO_SCTP ;
412see
413.Xr sctp 4 .
414.It TCP
415.Dv IPPROTO_TCP ;
416see
417.Xr tcp 4 .
418.It UDP
419.Dv IPPROTO_UDP ;
420see
421.Xr udp 4 .
422.El
423.Pp
424.Dv AF_LOCAL
425.Pp
426.Bl -tag -width indent -compact
427.It UDD
428.Dv IPPROTO_UDP ;
429see
430.Xr udp 4 .
431.It UDS
432.Dv IPPROTO_TCP ;
433see
434.Xr tcp 4 .
435.It UD?
436unknown protocol.
437.El
438.Pp
439.Bl -tag -width indent -compact
440.It ?
441unknown address family.
442.El
443.Ss Signal Disposition Information
444Display signal pending and disposition for a process:
445.Pp
446.Bl -tag -width indent -compact
447.It PID
448process ID
449.It COMM
450command
451.It SIG
452signal name
453.It FLAGS
454process signal disposition details, three symbols
455.Bl -tag -width X -compact
456.It P
457if signal is pending in the global process queue; - otherwise.
458.It I
459if signal delivery disposition is
460.Dv SIG_IGN ;
461- otherwise.
462.It C
463if the signal will be caught; - otherwise.
464.El
465.El
466.Pp
467If
468.Fl n
469switch is given, the signal numbers are shown instead of signal names.
470.Ss Thread Signal Information
471Display signal pending and blocked for a process's threads:
472.Pp
473.Bl -tag -width indent -compact
474.It PID
475process ID
476.It TID
477thread ID
478.It COMM
479command
480.It SIG
481signal name
482.It FLAGS
483thread signal delivery status, two symbols
484.Bl -tag -width X -compact
485.It P
486if signal is pending for the thread, - otherwise
487.It B
488if signal is blocked in the thread signal mask, - if not blocked
489.El
490.El
491.Pp
492The
493.Fl n
494switch has the same effect as for the
495.Fl i
496switch: the signal numbers are shown instead of signal names.
497.Ss Kernel Thread Stacks
498Display kernel thread stacks for a process, allowing further interpretation
499of thread wait channels.
500If the
501.Fl k
502flag is repeated, function offsets, not just function names, are printed.
503.Pp
504This feature requires
505.Cd "options STACK"
506or
507.Cd "options DDB"
508to be compiled into the kernel.
509.Pp
510.Bl -tag -width indent -compact
511.It PID
512process ID
513.It TID
514thread ID
515.It COMM
516command
517.It TDNAME
518thread name
519.It KSTACK
520kernel thread call stack
521.El
522.Ss Resource Limits
523Display resource limits for a process:
524.Pp
525.Bl -tag -width indent -compact
526.It PID
527process ID
528.It COMM
529command
530.It RLIMIT
531resource limit name
532.It SOFT
533soft limit
534.It HARD
535hard limit
536.El
537.Ss Resource Usage
538Display resource usage for a process.
539If the
540.Fl H
541flag is specified,
542resource usage for individual threads is displayed instead.
543.Pp
544.Bl -tag -width "RESOURCE" -compact
545.It PID
546process ID
547.It TID
548thread ID
549.Po
550if
551.Fl H
552is specified
553.Pc
554.It COMM
555command
556.It RESOURCE
557resource name
558.It VALUE
559current usage
560.El
561.Ss Security Credentials
562Display process credential information:
563.Pp
564.Bl -tag -width indent -compact
565.It PID
566process ID
567.It COMM
568command
569.It EUID
570effective user ID
571.It RUID
572real user ID
573.It SVUID
574saved user ID
575.It EGID
576effective group ID
577.It RGID
578real group ID
579.It SVGID
580saved group ID
581.It UMASK
582file creation mode mask
583.It FLAGS
584credential flags
585.It GROUPS
586group set
587.El
588.Pp
589The following credential flags may be displayed:
590.Pp
591.Bl -tag -width X -compact
592.It C
593capability mode
594.El
595.Ss Thread Information
596Display per-thread information, including process ID, per-thread ID, name,
597CPU, and execution state:
598.Pp
599.Bl -tag -width indent -compact
600.It PID
601process ID
602.It TID
603thread ID
604.It COMM
605command
606.It TDNAME
607thread name
608.It CPU
609current or most recent CPU run on
610.It PRI
611thread priority
612.It STATE
613thread state
614.It WCHAN
615thread wait channel
616.El
617.Ss Virtual Memory Mappings
618Display process virtual memory mappings, including addresses, mapping
619meta-data, and mapped object information:
620.Pp
621.Bl -tag -width indent -compact
622.It PID
623process ID
624.It START
625starting address of mapping
626.It END
627ending address of mapping
628.It PRT
629protection flags
630.It RES
631resident pages
632.It PRES
633private resident pages
634.It REF
635reference count
636.It SHD
637shadow page count
638.It FLAG
639mapping flags
640.It TP
641VM object type
642.El
643.Pp
644The following protection flags may be displayed:
645.Pp
646.Bl -tag -width X -compact
647.It r
648read
649.It w
650write
651.It x
652execute
653.El
654.Pp
655The following VM object types may be displayed:
656.Pp
657.Bl -tag -width XX -compact
658.It --
659none
660.It dd
661dead
662.It df
663default
664.It dv
665device
666.It md
667device with managed pages
668.Pq GEM/TTM
669.It ph
670physical
671.It sg
672scatter/gather
673.It sw
674swap
675.It vn
676vnode
677.El
678.Pp
679The following mapping flags may be displayed:
680.Pp
681.Bl -tag -width X -compact
682.It C
683copy-on-write
684.It N
685needs copy
686.It S
687one or more superpage mappings are used
688.It D
689grows down (top-down stack)
690.It U
691grows up (bottom-up stack)
692.It W
693pages in this range are locked by
694.Xr mlock 2
695or
696.Xr mlockall 2
697.El
698.Ss ELF Auxiliary Vector
699Display ELF auxiliary vector values:
700.Pp
701.Bl -tag -width indent -compact
702.It PID
703process ID
704.It COMM
705command
706.It AUXV
707auxiliary vector name
708.It VALUE
709auxiliary vector value
710.El
711.Sh EXIT STATUS
712.Ex -std
713.Sh EXAMPLES
714Show binary information about the current shell:
715.Bd -literal -offset indent
716$ procstat binary $$
717  PID COMM                OSREL PATH
71846620 bash              1201000 /usr/local/bin/bash
719.Ed
720.Pp
721Same as above but showing information about open file descriptors:
722.Bd -literal -offset indent
723$ procstat files $$
724  PID COMM                FD T V FLAGS    REF  OFFSET PRO NAME
72546620 bash              text v r r-------   -       - -   /usr/local/bin/bash
72646620 bash              ctty v c rw------   -       - -   /dev/pts/12
72746620 bash               cwd v d r-------   -       - -   /tmp
72846620 bash              root v d r-------   -       - -   /
72946620 bash                 0 v c rw------   7  372071 -   /dev/pts/12
73046620 bash                 1 v c rw------   7  372071 -   /dev/pts/12
73146620 bash                 2 v c rw------   7  372071 -   /dev/pts/12
73246620 bash               255 v c rw------   7  372071 -   /dev/pts/12
733.Ed
734.Pp
735Show the arguments used to launch
736.Xr init 8 :
737.Bd -literal -offset indent
738$ procstat arguments 1
739  PID COMM             ARGS
740    1 init             /sbin/init --
741.Ed
742.Pp
743Extract binary information from a core dump:
744.Bd -literal -offset indent
745$ procstat binary core.36642
746  PID COMM                OSREL PATH
74736642 top               1201000 /usr/bin/top
748.Ed
749.Pp
750Trying to extract information from a core file generated in a different major
751.Fx
752version might show an error like this:
753.Bd -literal -offset indent
754$ procstat mplayer.core
755procstat: kinfo_proc structure size mismatch
756procstat: procstat_getprocs()
757.Ed
758.Sh SEE ALSO
759.Xr fstat 1 ,
760.Xr ps 1 ,
761.Xr sockstat 1 ,
762.Xr cap_enter 2 ,
763.Xr cap_rights_limit 2 ,
764.Xr mlock 2 ,
765.Xr mlockall 2 ,
766.Xr libprocstat 3 ,
767.Xr libxo 3 ,
768.Xr signal 3 ,
769.Xr xo_parse_args 3 ,
770.Xr ddb 4 ,
771.Xr divert 4 ,
772.Xr icmp 4 ,
773.Xr ip 4 ,
774.Xr sctp 4 ,
775.Xr tcp 4 ,
776.Xr udp 4 ,
777.Xr stack 9
778.Sh AUTHORS
779.An Robert N M Watson Aq Mt rwatson@FreeBSD.org .
780.br
781.Xr libxo 3
782support was added by
783.An -nosplit
784Allan Jude
785.Aq Mt allanjude@FreeBSD.org .
786.br
787.An Juraj Lutter
788.Aq Mt juraj@lutter.sk
789added the pargs, penv and pwdx functionality.
790.Sh BUGS
791The display of open file or memory mapping pathnames is implemented using the
792kernel's name cache.
793If a file system does not use the name cache, or the path to a file is not in
794the cache, a path will not be displayed.
795.Pp
796.Nm
797currently supports extracting data only from a live kernel, and not from
798kernel crash dumps.
799