1 files changed, 262 insertions, 0 deletions
diff --git a/static/freebsd/man4/dtrace_proc.4 b/static/freebsd/man4/dtrace_proc.4
new file mode 100644
index 00000000..5e217eb0
--- /dev/null
+++ b/static/freebsd/man4/dtrace_proc.4
@@ -0,0 +1,262 @@
+.\" 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.
+.\"
+.Dd March 3, 2023
+.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 .