.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH FORKSTAT 8 "4 December, 2018"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
forkstat \- a tool to show process fork/exec/exit activity
.br

.SH SYNOPSIS
.B forkstat
.RI [ \-c ]
.RI [ \-d ]
.RI [ \-D ]
.RI [ \-e ]
.RI [ \-E ]
.RI [ \-g ]
.RI [ \-h ]
.RI [ \-l ]
.RI [ \-r ]
.RI [ \-s ]
.RI [ \-S ]
.RI [ \-q ]
.RI [ \-x ]
.RI [ \-X ]
.br

.SH DESCRIPTION
Forkstat is a program that logs process fork(), exec(), exit(), coredump and
process name change activity.
It is useful for monitoring system behaviour and to track down rogue processes
that are spawning off processes and potentially abusing the system.

Note that forkstat uses the Linux netlink connector to gather process activity
and this may miss events if the system is overly busy. Netlink connector also requires
root privilege.

Forkstat will display several columns of process related information:
.TS
l l.
\fBTitle	Description\fR
Time	When the fork/exec/exit event occurred.
Event	Type of event.
PID	Process or thread ID.
Info	Parent or child if a fork, or process exit(2) value.
Duration	T{
On exit, the duration the command ran for in seconds.
T}
Process	T{
The process name. The name will be in [ ] brackets if it is a kernel thread.
T}
.TE
.SH OPTIONS
forkstat options are as follow:
.TP
.B \-c
use the process 16 character comm field for the process name rather than command
line information.
.TP
.B \-d
strip off the directory path from the process name.
.TP
.B \-D seconds
specify duration in seconds to run forkstat.
.TP
.B \-e
specify events to trace as a comma seperated list. By default the fork, exec and exit 
events are traced. Available events are:
.TS
l lw(4i).
\fBEvent	Description\fR
fork	forks
exec	execs
exit	exits
core	core dumps
comm	process name changes in comm field
clone	clone (normally on thread creation)
ptrce	ptrace attach or detach
uid	uid/gid events
sid	sid events
all	all the events above
.TE
.TP
.B \-E
enable all events, equivalent to \-e all
.TP
.B \-g
show glyph annotations of events, useful for easier identification of 
different events.
.TP
.B \-h
show brief help summary.
.TP
.B \-l
set stdout to line-buffered mode.
.TP
.B \-r
run with real time FIFO scheduling with maximum priority to keep up with high volumes
of process events.
.TP
.B \-s
show short process name information.
.TP
.B \-S
show event statistics.
.TP
.B \-q
run quietly and enable the \-S option.
.TP
.B \-x
show extra process related information: user ID and TTY of the process.
.TP
.B \-X
equivalent to options \-E \-g \-r \-S \-x, all events, glyphs, real time FIFO
scheduling, statistics and extra process information.
.SH EXAMPLES
.LP
Show process activity with short process names and directory base path stripped off:
.RS 8
forkstat \-s \-d
.RE
.LP
Trace forks and core dumps only:
.RS 8
forkstat \-e fork,core
.RE
.LP
Trace all events and print statistics at end:
.RS 8
forkstat \-e all \-S
.RE
.LP
Trace all events for 10 minutes:
.RS 8
forkstat \-E \-D 600
.RE
.LP
Trace clones for 1 minute:
.RS 8
forkstat \-e clone \-D 60
.RE
.SH SEE ALSO
.BR vmstat (8)
.SH AUTHOR
forkstat was written by Colin King <colin.king@canonical.com>. Thanks also
for contributions from Philipp Gesang.
.PP
This manual page was written by Colin King <colin.king@canonical.com>,
for the Ubuntu project (but may be used by others).
.SH COPYRIGHT
Copyright \(co 2014-2018 Canonical Ltd.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.