share/man/man4/dtrace_proc.4

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