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