.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" 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 April 17, 2016
.Dt DTRACE_PROC 4
.Os
.Sh NAME
.Nm dtrace_proc
.Nd a DTrace provider for tracing events related to user processes
.Sh SYNOPSIS
.Fn proc:::create "struct proc *" "struct proc *" "int"
.Fn proc:::exec "char *"
.Fn proc:::exec-failure "int"
.Fn proc:::exec-success "char *"
.Fn proc:::exit "int"
.Fn proc:::signal-clear "int" "ksiginfo_t *"
.Fn proc:::signal-discard "struct thread *" "struct proc *" "int"
.Fn proc:::signal-send "struct thread *" "struct proc *" "int"
.Sh DESCRIPTION
The DTrace
.Nm proc
provider provides insight into events related to user processes: process and
thread creation and termination events, and process signalling.
.Pp
The
.Fn proc:::create
probe fires when a user process is created via the
.Xr fork 2 ,
.Xr vfork 2 ,
.Xr pdfork 2 ,
or
.Xr rfork 2
system calls.
In particular, kernel processes created with the
.Xr kproc 9
KPI will not trigger this probe.
The
.Fn proc:::create
probe's first two arguments are the new child process and its parent,
respectively.
The third argument is a mask of
.Xr rfork 2
flags indicating which process resources are to be shared between the parent and
child processes.
.Pp
The
.Fn proc:::exec
probe fires when a process attempts to execute a file.
Its argument is the specified filename for the file.
If the attempt fails because of an error, the
.Fn proc:::exec-failure
probe will subsequently fire, providing the corresponding
.Xr errno 2
value in its first argument.
Otherwise, the
.Fn proc:::exec-success
probe will fire.
.Pp
The
.Fn proc:::exit
probe fires when a process exits or is terminated.
Its argument is the corresponding
.Dv SIGCHLD
signal code; valid values are documented in the
.Xr siginfo 3
manual page and defined in
.Pa signal.h .
For example, when a process exits normally, the value of
.Dv args[0]
will be
.Dv CLD_EXITED .
.Pp
The
.Fn proc:::signal-send
probe fires when a signal is about to be sent to a process.
The
.Fn proc:::signal-discard
probe fires when a signal is sent to a process that ignores it.
This probe will fire after the
.Fn proc:::signal-send
probe for the signal in question.
The arguments to these probes are the thread and process to which the signal
will be sent, and the signal number of the signal.
Valid signal numbers are defined in the
.Xr signal 3
manual page.
The
.Fn proc:::signal-clear
probe fires when a pending signal has been cleared by one of the
.Xr sigwait 2 ,
.Xr sigtimedwait 2 ,
or
.Xr sigwaitinfo 2
system calls.
Its arguments are the signal number of the cleared signal, and a pointer to
the corresponding signal information.
The
.Vt siginfo_t
for the signal can be obtained from
.Dv args[1]->ksi_info .
.Sh ARGUMENTS
Though the
.Nm proc
provider probes use native
.Fx
arguments types, standard D types for processes and threads are available.
These are
.Vt psinfo_t
and
.Vt lwpsinfo_t
respectively, and are defined in
.Pa /usr/lib/dtrace/psinfo.d .
This file also defines two global variables,
.Va curpsinfo
and
.Va curlwpsinfo ,
which provide representations of the current process and thread using these
types.
.Pp
The fields of
.Vt psinfo_t
are:
.Bl -tag -width "uintptr_t pr_addr" -offset indent
.It Vt int pr_nlwp
Number of threads in the process.
.It Vt pid_t pr_pid
Process ID.
.It Vt pid_t pr_ppid
Process ID of the parent process, or 0 if the process does not have a parent.
.It Vt pid_t pr_pgid
Process ID of the process group leader.
.It Vt pid_t pr_sid
Session ID, or 0 if the process does not belong to a session.
.It Vt pid_t pr_uid
Real user ID.
.It Vt pid_t pr_euid
Effective user ID.
.It Vt pid_t pr_gid
Real group ID.
.It Vt pid_t pr_egid
Effective group ID.
.It Vt uintptr_t pr_addr
Pointer to the
.Vt struct proc
for the process.
.It Vt string pr_psargs
Process arguments.
.It Vt u_int pr_arglen
Length of the process argument string.
.It Vt u_int pr_jailid
Jail ID of the process.
.El
.Pp
The fields of
.Vt lwpsinfo_t
are:
.Bl -tag -width "uintptr_t pr_wchar" -offset indent
.It Vt id_t pr_lwpid
Thread ID.
.It Vt int pr_flag
Thread flags.
.It Vt int pr_pri
Real scheduling priority of the thread.
.It Vt char pr_state
Currently always 0.
.It Vt char pr_sname
Currently always
.Ql ? .
.It Vt short pr_syscall
Currently always 0.
.It Vt uintptr_t pr_addr
Pointer to the
.Vt struct thread
for the thread.
.It Vt uintptr_t pr_wchan
Current wait address on which the thread is sleeping.
.El
.Sh FILES
.Bl -tag -width "/usr/lib/dtrace/psinfo.d" -compact
.It Pa /usr/lib/dtrace/psinfo.d
DTrace type and translator definitions for the
.Nm proc
provider.
.El
.Sh EXAMPLES
The following script logs process execution events as they occur:
.Bd -literal -offset indent
#pragma D option quiet

proc:::exec-success
{
        printf("%s", curpsinfo->pr_psargs);
}
.Ed
.Pp
Note that the
.Dv pr_psargs
field is subject to the limit defined by the
.Va kern.ps_arg_cache_limit
sysctl.
In particular, processes with an argument list longer than the value defined by
this sysctl cannot be logged in this way.
.Sh COMPATIBILITY
The
.Nm proc
provider in
.Fx
is not compatible with the
.Nm proc
provider in Solaris.
In particular,
.Fx
uses the native
.Vt "struct proc"
and
.Vt "struct thread"
types for probe arguments rather than translated types.
Additionally, a number of
.Nm proc
provider probes found in Solaris are not currently available on
.Fx .
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr errno 2 ,
.Xr fork 2 ,
.Xr pdfork 2 ,
.Xr rfork 2 ,
.Xr vfork 2 ,
.Xr siginfo 3 ,
.Xr signal 3 ,
.Xr dtrace_sched 4 ,
.Xr kproc 9
.Sh HISTORY
The
.Nm proc
provider first appeared in
.Fx
7.1.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .