NAME
dtrace_proc —
a DTrace provider for tracing events
related to user processes
SYNOPSIS
proc:::create(struct
proc *, struct proc
*, int);
proc:::exec(char
*);
proc:::exec-failure(int);
proc:::exec-success(char
*);
proc:::exit(int);
proc:::signal-clear(int,
ksiginfo_t *);
proc:::signal-discard(struct
thread *, struct proc
*, int);
proc:::signal-send(struct
thread *, struct proc
*, int);
DESCRIPTION
The DTraceproc provider provides insight into events
related to user processes: process and thread creation and termination events,
and process signalling.
The
proc:::create()
probe fires when a user process is created via the
fork(2),
vfork(2),
pdfork(2), or
rfork(2) system calls. In particular, kernel processes created with
the kproc(9) KPI will not trigger this probe. The
proc:::create() probe's first two arguments are the
new child process and its parent, respectively. The third argument is a mask
of rfork(2) flags indicating which process resources are to be shared
between the parent and child processes.
The
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
proc:::exec-failure()
probe will subsequently fire, providing the corresponding
errno(2) value in its first argument. Otherwise, the
proc:::exec-success()
probe will fire.
The
proc:::exit()
probe fires when a process exits or is terminated. Its argument is the
corresponding SIGCHLD signal code; valid values are
documented in the
siginfo(3) manual page and defined in
signal.h. For example, when a process exits
normally, the value of args[0] will be
CLD_EXITED.
The
proc:::signal-send()
probe fires when a signal is about to be sent to a process. The
proc:::signal-discard()
probe fires when a signal is sent to a process that ignores it. This probe
will fire after the 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
signal(3) manual page. The
proc:::signal-clear()
probe fires when a pending signal has been cleared by one of the
sigwait(2),
sigtimedwait(2), or
sigwaitinfo(2) system calls. Its arguments are the signal
number of the cleared signal, and a pointer to the corresponding signal
information. The siginfo_t for the signal can be
obtained from args[1]->ksi_info.
ARGUMENTS
Though the proc provider probes use native
FreeBSD arguments types, standard D types for
processes and threads are available. These are
psinfo_t and lwpsinfo_t
respectively, and are defined in
/usr/lib/dtrace/psinfo.d. This file also defines two
global variables, curpsinfo and
curlwpsinfo, which provide representations of the
current process and thread using these types.
The fields of psinfo_t are:
- int pr_nlwp
- Number of threads in the process.
- pid_t pr_pid
- Process ID.
- pid_t pr_ppid
- Process ID of the parent process, or 0 if the process does not have a parent.
- pid_t pr_pgid
- Process ID of the process group leader.
- pid_t pr_sid
- Session ID, or 0 if the process does not belong to a session.
- pid_t pr_uid
- Real user ID.
- pid_t pr_euid
- Effective user ID.
- pid_t pr_gid
- Real group ID.
- pid_t pr_egid
- Effective group ID.
- uintptr_t pr_addr
- Pointer to the struct proc for the process.
- string pr_psargs
- Process arguments.
- u_int pr_arglen
- Length of the process argument string.
- u_int pr_jailid
- Jail ID of the process.
The fields of lwpsinfo_t are:
- id_t pr_lwpid
- Thread ID.
- int pr_flag
- Thread flags.
- int pr_pri
- Real scheduling priority of the thread.
- char pr_state
- Currently always 0.
- char pr_sname
- Currently always ‘
’?. - short pr_syscall
- Currently always 0.
- uintptr_t pr_addr
- Pointer to the struct thread for the thread.
- uintptr_t pr_wchan
- Current wait address on which the thread is sleeping.
FILES
- /usr/lib/dtrace/psinfo.d
- DTrace type and translator definitions for the
procprovider.
EXAMPLES
The following script logs process execution events as they occur:
#pragma D option quiet
proc:::exec-success
{
printf("%s", curpsinfo->pr_psargs);
}
Note that the pr_psargs field is subject
to the limit defined by the 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.
COMPATIBILITY
The proc provider in
FreeBSD is not compatible with the
proc provider in Solaris. In particular,
FreeBSD uses the native struct
proc and struct thread types for probe arguments
rather than translated types. Additionally, a number of
proc provider probes found in Solaris are not
currently available on FreeBSD.
SEE ALSO
dtrace(1), errno(2), fork(2), pdfork(2), rfork(2), vfork(2), siginfo(3), signal(3), dtrace_sched(4), kproc(9)
HISTORY
The proc provider first appeared in
FreeBSD 7.1.
AUTHORS
This manual page was written by Mark Johnston <markj@FreeBSD.org>.