1 files changed, 462 insertions, 0 deletions
diff --git a/usr.bin/procstat/procstat.1 b/usr.bin/procstat/procstat.1
new file mode 100644
index 0000000..6587bd3
--- /dev/null
+++ b/usr.bin/procstat/procstat.1
@@ -0,0 +1,462 @@
+.\"-
+.\" Copyright (c) 2007-2009 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd March 23, 2012
+.Dt PROCSTAT 1
+.Os
+.Sh NAME
+.Nm procstat
+.Nd get detailed process information
+.Sh SYNOPSIS
+.Nm
+.Op Fl h
+.Op Fl n
+.Op Fl C
+.Op Fl w Ar interval
+.Op Fl b | c | e | f | i | j | k | l | s | t | v | x
+.Op Fl a | Ar pid ...
+.Sh DESCRIPTION
+The
+.Nm
+utility displays detailed information about the processes identified by the
+.Ar pid
+arguments, or if the
+.Fl a
+flag is used, all processes.
+.Pp
+By default, basic process statistics are printed; one of the following
+options may be specified in order to select more detailed process information
+for printing:
+.Bl -tag -width indent
+.It Fl b
+Display binary information for the process.
+.It Fl c
+Display command line arguments for the process.
+.It Fl e
+Display environment variables for the process.
+.It Fl f
+Display file descriptor information for the process.
+.It Fl i
+Display signal pending and disposition information for the process.
+.It Fl j
+Display signal pending and blocked information for the process threads.
+.It Fl k
+Display the stacks of kernel threads in the process, excluding stacks of
+threads currently running on a CPU and threads with stacks swapped to disk.
+If the flag is repeated, function offsets as well as function names are
+printed.
+.It Fl l
+Display resource limits for the process.
+.It Fl s
+Display security credential information for the process.
+.It Fl t
+Display thread information for the process.
+.It Fl v
+Display virtual memory mappings for the process.
+.It Fl x
+Display ELF auxiliary vector for the process.
+.El
+.Pp
+All options generate output in the format of a table, the first field of
+which is the process ID to which the row of information corresponds.
+The
+.Fl h
+flag may be used to suppress table headers.
+.Pp
+The
+.Fl w
+flag may be used to specify a wait interval at which to repeat the printing
+of the requested process information.
+If the
+.Fl w
+flag is not specified, the output will not repeat.
+.Pp
+The
+.Fl C
+flag requests the printing of additional capability information in the file
+descriptor view.
+.Pp
+Some information, such as VM and file descriptor information, is available
+only to the owner of a process or the superuser.
+.Ss Binary Information
+Display the process ID, command, and path to the process binary:
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It COMM
+command
+.It OSREL
+osreldate for process binary
+.It PATH
+path to process binary (if available)
+.El
+.Ss Command Line Arguments
+Display the process ID, command, and command line arguments:
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It COMM
+command
+.It ARGS
+command line arguments (if available)
+.El
+.Ss File Descriptors
+Display detailed information about each file descriptor referenced by a
+process, including the process ID, command, file descriptor number, and
+per-file descriptor object information, such as object type and file system
+path.
+By default, the following information will be printed:
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It COMM
+command
+.It FD
+file descriptor number or cwd/root/jail
+.It T
+file descriptor type
+.It V
+vnode type
+.It FLAGS
+file descriptor flags
+.It REF
+file descriptor reference count
+.It OFFSET
+file descriptor offset
+.It PRO
+network protocol
+.It NAME
+file path or socket addresses (if available)
+.El
+.Pp
+The following file descriptor types may be displayed:
+.Pp
+.Bl -tag -width X -compact
+.It c
+crypto
+.It e
+POSIX semaphore
+.It f
+fifo
+.It h
+shared memory
+.It k
+kqueue
+.It m
+message queue
+.It p
+pipe
+.It s
+socket
+.It t
+pseudo-terminal master
+.It v
+vnode
+.El
+.Pp
+The following vnode types may be displayed:
+.Pp
+.Bl -tag -width X -compact
+.It -
+not a vnode
+.It b
+block device
+.It c
+character device
+.It d
+directory
+.It f
+fifo
+.It l
+symbolic link
+.It r
+regular file
+.It s
+socket
+.It x
+revoked device
+.El
+.Pp
+The following file descriptor flags may be displayed:
+.Pp
+.Bl -tag -width X -compact
+.It r
+read
+.It w
+write
+.It a
+append
+.It s
+async
+.It f
+fsync
+.It n
+non-blocking
+.It d
+direct I/O
+.It l
+lock held
+.It c
+descriptor is a capability
+.El
+.Pp
+If the
+.Fl C
+flag is specified, the vnode type, reference count, and offset fields will be
+omitted, and a new capabilities field will be included listing capabilities,
+as described in
+.Xr cap_new 2 ,
+present for each capability descriptor.
+.Ss Signal Disposition Information
+Display signal pending and disposition for a process:
+.Pp
+.Bl -tag -width ident -compact
+.It PID
+process ID
+.It COMM
+command
+.It SIG
+signal name
+.It FLAGS
+process signal disposition details, three symbols
+.Bl -tag -width X -compact
+.It P
+if signal is pending in the global process queue, - otherwise
+.It I
+if signal delivery disposition is SIGIGN, - otherwise
+.It C
+if signal delivery is to catch it, - otherwise
+.El
+.El
+.Pp
+If
+.Fl n
+switch is given, the signal numbers are shown instead of signal names.
+.Ss Thread Signal Information
+Display signal pending and blocked for a process threads:
+.Pp
+.Bl -tag -width ident -compact
+.It PID
+process ID
+.It COMM
+command
+.It TID
+thread ID
+.It SIG
+signal name
+.It FLAGS
+thread signal delivery status, two symbols
+.Bl -tag -width X -compact
+.It P
+if signal is pending for the thread, - otherwise
+.It B
+if signal is blocked in the thread signal mask, - if not blocked
+.El
+.El
+.Pp
+The
+.Fl n
+switch has the same effect as for the
+.Fl i
+switch, the signals numbers are shown instead of signal names.
+.Ss Kernel Thread Stacks
+Display kernel thread stacks for a process, allowing further interpretation
+of thread wait channels.
+If the
+.Fl k
+flag is repeated, function offsets, not just function names, are printed.
+.Pp
+This feature requires
+.Cd "options STACK"
+or
+.Cd "options DDB"
+to be compiled into the kernel.
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It TID
+thread ID
+.It COMM
+command
+.It TDNAME
+thread name
+.It KSTACK
+kernel thread call stack
+.El
+.Ss Security Credentials
+Display process credential information:
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It COMM
+command
+.It EUID
+effective user ID
+.It RUID
+real user ID
+.It SVUID
+saved user ID
+.It EGID
+effective group ID
+.It RGID
+real group ID
+.It SVGID
+saved group ID
+.It UMASK
+file creation mode mask
+.It FLAGS
+credential flags
+.It GROUPS
+group set
+.El
+.Pp
+The following credential flags may be displayed:
+.Pp
+.Bl -tag -width X -compact
+.It C
+capability mode
+.El
+.Ss Thread Information
+Display per-thread information, including process ID, per-thread ID, name,
+CPU, and execution state:
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It TID
+thread ID
+.It COMM
+command
+.It TDNAME
+thread name
+.It CPU
+current or most recent CPU run on
+.It PRI
+thread priority
+.It STATE
+thread state
+.It WCHAN
+thread wait channel
+.El
+.Ss Virtual Memory Mappings
+Display process virtual memory mappings, including addresses, mapping
+meta-data, and mapped object information:
+.Pp
+.Bl -tag -width indent -compact
+.It PID
+process ID
+.It START
+starting address of mapping
+.It END
+ending address of mapping
+.It PRT
+protection flags
+.It RES
+resident pages
+.It PRES
+private resident pages
+.It REF
+reference count
+.It SHD
+shadow page count
+.It FL
+mapping flags
+.It TP
+VM object type
+.El
+.Pp
+The following protection flags may be displayed:
+.Pp
+.Bl -tag -width X -compact
+.It r
+read
+.It w
+write
+.It x
+execute
+.El
+.Pp
+The following VM object types may be displayed:
+.Pp
+.Bl -tag -width XX -compact
+.It --
+none
+.It dd
+dead
+.It df
+default
+.It dv
+device
+.It ph
+physical
+.It sw
+swap
+.It vn
+vnode
+.El
+.Pp
+The following mapping flags may be displayed:
+.Pp
+.Bl -tag -width X -compact
+.It C
+copy-on-write
+.It N
+needs copy
+.It S
+one or more superpage mappings are used
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh SEE ALSO
+.Xr fstat 1 ,
+.Xr ps 1 ,
+.Xr sockstat 1 ,
+.Xr cap_enter 2 ,
+.Xr cap_new 2 ,
+.Xr ddb 4 ,
+.Xr stack 9
+.Sh AUTHORS
+.An Robert N M Watson
+.Sh BUGS
+Some field values may include spaces, which limits the extent to which the
+output of
+.Nm
+may be mechanically parsed.
+.Pp
+The display of open file or memory mapping pathnames is implemented using the
+kernel's name cache.
+If a file system does not use the name cache, or the path to a file is not in
+the cache, a path will not be displayed.
+.Pp
+.Nm
+currently supports extracting data only from a live kernel, and not from
+kernel crash dumps.