1.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd March 3, 2023 26.Dt DTRACE_PROC 4 27.Os 28.Sh NAME 29.Nm dtrace_proc 30.Nd a DTrace provider for tracing events related to user processes 31.Sh SYNOPSIS 32.Fn proc:::create "struct proc *" "struct proc *" "int" 33.Fn proc:::exec "char *" 34.Fn proc:::exec-failure "int" 35.Fn proc:::exec-success "char *" 36.Fn proc:::exit "int" 37.Fn proc:::signal-clear "int" "ksiginfo_t *" 38.Fn proc:::signal-discard "struct thread *" "struct proc *" "int" 39.Fn proc:::signal-send "struct thread *" "struct proc *" "int" 40.Sh DESCRIPTION 41The DTrace 42.Nm proc 43provider provides insight into events related to user processes: process and 44thread creation and termination events, and process signalling. 45.Pp 46The 47.Fn proc:::create 48probe fires when a user process is created via the 49.Xr fork 2 , 50.Xr vfork 2 , 51.Xr pdfork 2 , 52or 53.Xr rfork 2 54system calls. 55In particular, kernel processes created with the 56.Xr kproc 9 57KPI will not trigger this probe. 58The 59.Fn proc:::create 60probe's first two arguments are the new child process and its parent, 61respectively. 62The third argument is a mask of 63.Xr rfork 2 64flags indicating which process resources are to be shared between the parent and 65child processes. 66.Pp 67The 68.Fn proc:::exec 69probe fires when a process attempts to execute a file. 70Its argument is the specified filename for the file. 71If the attempt fails because of an error, the 72.Fn proc:::exec-failure 73probe will subsequently fire, providing the corresponding 74.Xr errno 2 75value in its first argument. 76Otherwise, the 77.Fn proc:::exec-success 78probe will fire. 79.Pp 80The 81.Fn proc:::exit 82probe fires when a process exits or is terminated. 83Its argument is the corresponding 84.Dv SIGCHLD 85signal code; valid values are documented in the 86.Xr siginfo 3 87manual page and defined in 88.Pa signal.h . 89For example, when a process exits normally, the value of 90.Dv args[0] 91will be 92.Dv CLD_EXITED . 93.Pp 94The 95.Fn proc:::signal-send 96probe fires when a signal is about to be sent to a process. 97The 98.Fn proc:::signal-discard 99probe fires when a signal is sent to a process that ignores it. 100This probe will fire after the 101.Fn proc:::signal-send 102probe for the signal in question. 103The arguments to these probes are the thread and process to which the signal 104will be sent, and the signal number of the signal. 105Valid signal numbers are defined in the 106.Xr signal 3 107manual page. 108The 109.Fn proc:::signal-clear 110probe fires when a pending signal has been cleared by one of the 111.Xr sigwait 2 , 112.Xr sigtimedwait 2 , 113or 114.Xr sigwaitinfo 2 115system calls. 116Its arguments are the signal number of the cleared signal, and a pointer to 117the corresponding signal information. 118The 119.Vt siginfo_t 120for the signal can be obtained from 121.Dv args[1]->ksi_info . 122.Sh ARGUMENTS 123Though the 124.Nm proc 125provider probes use native 126.Fx 127arguments types, standard D types for processes and threads are available. 128These are 129.Vt psinfo_t 130and 131.Vt lwpsinfo_t 132respectively, and are defined in 133.Pa /usr/lib/dtrace/psinfo.d . 134This file also defines two global variables, 135.Va curpsinfo 136and 137.Va curlwpsinfo , 138which provide representations of the current process and thread using these 139types. 140.Pp 141The fields of 142.Vt psinfo_t 143are: 144.Bl -tag -width "uintptr_t pr_addr" -offset indent 145.It Vt int pr_nlwp 146Number of threads in the process. 147.It Vt pid_t pr_pid 148Process ID. 149.It Vt pid_t pr_ppid 150Process ID of the parent process, or 0 if the process does not have a parent. 151.It Vt pid_t pr_pgid 152Process ID of the process group leader. 153.It Vt pid_t pr_sid 154Session ID, or 0 if the process does not belong to a session. 155.It Vt pid_t pr_uid 156Real user ID. 157.It Vt pid_t pr_euid 158Effective user ID. 159.It Vt pid_t pr_gid 160Real group ID. 161.It Vt pid_t pr_egid 162Effective group ID. 163.It Vt uintptr_t pr_addr 164Pointer to the 165.Vt struct proc 166for the process. 167.It Vt string pr_psargs 168Process arguments. 169.It Vt u_int pr_arglen 170Length of the process argument string. 171.It Vt u_int pr_jailid 172Jail ID of the process. 173.El 174.Pp 175The fields of 176.Vt lwpsinfo_t 177are: 178.Bl -tag -width "uintptr_t pr_wchar" -offset indent 179.It Vt id_t pr_lwpid 180Thread ID. 181.It Vt int pr_flag 182Thread flags. 183.It Vt int pr_pri 184Real scheduling priority of the thread. 185.It Vt char pr_state 186Currently always 0. 187.It Vt char pr_sname 188Currently always 189.Ql \&? . 190.It Vt short pr_syscall 191Currently always 0. 192.It Vt uintptr_t pr_addr 193Pointer to the 194.Vt struct thread 195for the thread. 196.It Vt uintptr_t pr_wchan 197Current wait address on which the thread is sleeping. 198.El 199.Sh FILES 200.Bl -tag -width "/usr/lib/dtrace/psinfo.d" -compact 201.It Pa /usr/lib/dtrace/psinfo.d 202DTrace type and translator definitions for the 203.Nm proc 204provider. 205.El 206.Sh EXAMPLES 207The following script logs process execution events as they occur: 208.Bd -literal -offset indent 209#pragma D option quiet 210 211proc:::exec-success 212{ 213 printf("%s", curpsinfo->pr_psargs); 214} 215.Ed 216.Pp 217Note that the 218.Dv pr_psargs 219field is subject to the limit defined by the 220.Va kern.ps_arg_cache_limit 221sysctl. 222In particular, processes with an argument list longer than the value defined by 223this sysctl cannot be logged in this way. 224.Sh COMPATIBILITY 225The 226.Nm proc 227provider in 228.Fx 229is not compatible with the 230.Nm proc 231provider in Solaris. 232In particular, 233.Fx 234uses the native 235.Vt "struct proc" 236and 237.Vt "struct thread" 238types for probe arguments rather than translated types. 239Additionally, a number of 240.Nm proc 241provider probes found in Solaris are not currently available on 242.Fx . 243.Sh SEE ALSO 244.Xr dtrace 1 , 245.Xr errno 2 , 246.Xr fork 2 , 247.Xr pdfork 2 , 248.Xr rfork 2 , 249.Xr vfork 2 , 250.Xr siginfo 3 , 251.Xr signal 3 , 252.Xr dtrace_sched 4 , 253.Xr kproc 9 254.Sh HISTORY 255The 256.Nm proc 257provider first appeared in 258.Fx 2597.1. 260.Sh AUTHORS 261This manual page was written by 262.An Mark Johnston Aq Mt markj@FreeBSD.org . 263