1 .\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd a DTrace provider for tracing events related to user processes
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 *"
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"
45 provider provides insight into events related to user processes: process and
46 thread creation and termination events, and process signalling.
50 probe fires when a user process is created via the
57 In particular, kernel processes created with the
59 KPI will not trigger this probe.
62 probe's first two arguments are the new child process and its parent,
64 The third argument is a mask of
66 flags indicating which process resources are to be shared between the parent and
71 probe fires when a process attempts to execute a file.
72 Its argument is the specified filename for the file.
73 If the attempt fails because of an error, the
74 .Fn proc:::exec-failure
75 probe will subsequently fire, providing the corresponding
77 value in its first argument.
79 .Fn proc:::exec-success
84 probe fires when a process exits or is terminated.
85 Its argument is the corresponding
87 signal code; valid values are documented in the
89 manual page and defined in
91 For example, when a process exits normally, the value of
97 .Fn proc:::signal-send
98 probe fires when a signal is about to be sent to a process.
100 .Fn proc:::signal-discard
101 probe fires when a signal is sent to a process that ignores it.
102 This probe will fire after the
103 .Fn proc:::signal-send
104 probe for the signal in question.
105 The arguments to these probes are the thread and process to which the signal
106 will be sent, and the signal number of the signal.
107 Valid signal numbers are defined in the
111 .Fn proc:::signal-clear
112 probe fires when a pending signal has been cleared by one of the
118 Its arguments are the signal number of the cleared signal, and a pointer to
119 the corresponding signal information.
122 for the signal can be obtained from
123 .Dv args[1]->ksi_info .
127 provider probes use native
129 arguments types, standard D types for processes and threads are available.
134 respectively, and are defined in
135 .Pa /usr/lib/dtrace/psinfo.d .
136 This file also defines two global variables,
140 which provide representations of the current process and thread using these
146 .Bl -tag -width "uintptr_t pr_addr" -offset indent
148 Number of threads in the process.
152 Process ID of the parent process, or 0 if the process does not have a parent.
154 Process ID of the process group leader.
156 Session ID, or 0 if the process does not belong to a session.
165 .It Vt uintptr_t pr_addr
169 .It Vt string pr_psargs
171 .It Vt u_int pr_arglen
172 Length of the process argument string.
173 .It Vt u_int pr_jailid
174 Jail ID of the process.
180 .Bl -tag -width "uintptr_t pr_wchar" -offset indent
186 Real scheduling priority of the thread.
192 .It Vt short pr_syscall
194 .It Vt uintptr_t pr_addr
198 .It Vt uintptr_t pr_wchan
199 Current wait address on which the thread is sleeping.
202 .Bl -tag -width "/usr/lib/dtrace/psinfo.d" -compact
203 .It Pa /usr/lib/dtrace/psinfo.d
204 DTrace type and translator definitions for the
209 The following script logs process execution events as they occur:
210 .Bd -literal -offset indent
211 #pragma D option quiet
215 printf("%s", curpsinfo->pr_psargs);
221 field is subject to the limit defined by the
222 .Va kern.ps_arg_cache_limit
224 In particular, processes with an argument list longer than the value defined by
225 this sysctl cannot be logged in this way.
231 is not compatible with the
240 types for probe arguments rather than translated types.
241 Additionally, a number of
243 provider probes found in Solaris are not currently available on
259 provider first appeared in
263 This manual page was written by
264 .An Mark Johnston Aq Mt markj@FreeBSD.org .