Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DTRACE_PROC(4)	       FreeBSD Kernel Interfaces Manual		DTRACE_PROC(4)

NAME
     dtrace_proc -- a DTrace provider for tracing events related to user pro-
     cesses

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 process resources are to be shared	be-
     tween 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 subse-
     quently fire, providing the corresponding errno(2)	value in its first ar-
     gument.  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 docu-
     mented in the siginfo(3) manual page and defined in signal.h.  For	exam-
     ple, 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, stan-
     dard 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
			       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 argu-
     ment 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.  Addition-
     ally, 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	13.0			April 17, 2016			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | FILES | EXAMPLES | COMPATIBILITY | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dtrace_proc&sektion=4&manpath=FreeBSD+12.0-RELEASE>

home | help