DTRACE-PROC(4)	       FreeBSD Kernel Interfaces Manual 	DTRACE-PROC(4)

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 DTrace proc 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 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 a name for the selected 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 provided.  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
			       proc provider.

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>.

FreeBSD 11.0-CURRENT		March 22, 2015		  FreeBSD 11.0-CURRENT