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

FreeBSD Manual Pages


home | help
PROCCTL(2)		  FreeBSD System Calls Manual		    PROCCTL(2)

     procctl --	control	processes

     Standard C	Library	(libc, -lc)

     #include <sys/procctl.h>

     procctl(idtype_t idtype, id_t id, int cmd,	void *arg);

     The procctl() system call provides	for control over processes.  The
     idtype and	id arguments specify the set of	processes to control.  If mul-
     tiple processes match the identifier, procctl will	make a ``best effort''
     to	control	as many	of the selected	processes as possible.	An error is
     only returned if no selected processes successfully complete the request.
     The following identifier types are	supported:

     P_PID	Control	the process with the process ID	id.

     P_PGID	Control	processes belonging to the process group with the ID

     The control request to perform is specified by the	cmd argument.  The
     following commands	are supported:

     PROC_SPROTECT	     Set process protection state.  This is used to
			     mark a process as protected from being killed if
			     the system	exhausts the available memory and
			     swap.  The	arg parameter must point to an integer
			     containing	an operation and zero or more optional
			     flags.  The following operations are supported:

			     PPROT_SET	     Mark the selected processes as

			     PPROT_CLEAR     Clear the protected state of
					     selected processes.

			     The following optional flags are supported:

			     PPROT_DESCEND     Apply the requested operation
					       to all child processes of each
					       selected	process	in addition to
					       each selected process.

			     PPROT_INHERIT     When used with PPROT_SET, mark
					       all future child	processes of
					       each selected process as	pro-
					       tected.	Future child processes
					       will also mark all of their
					       future child processes.

     PROC_REAP_ACQUIRE	     Acquires the reaper status	for the	current
			     process.  Reaper status means that	children
			     orphaned by the reaper's descendants that were
			     forked after the acquisition of reaper status are
			     reparented	to the reaper process.	After system
			     initialization, init(8) is	the default reaper.

     PROC_REAP_RELEASE	     Release the reaper	state for the current process.
			     The reaper	of the current process becomes the new
			     reaper of the current process's descendants.

     PROC_REAP_STATUS	     Provides information about	the reaper of the
			     specified process,	or the process itself when it
			     is	a reaper.  The data argument must point	to a
			     procctl_reaper_status structure which is filled
			     in	by the syscall on successful return.

			     struct procctl_reaper_status {
				     u_int   rs_flags;
				     u_int   rs_children;
				     u_int   rs_descendants;
				     pid_t   rs_reaper;
				     pid_t   rs_pid;
			     The rs_flags may have the following flags

			     REAPER_STATUS_OWNED	The specified process
							has acquired reaper
							status and has not
							released it.  When the
							flag is	returned, the
							specified process id,
							pid, identifies	the
							reaper,	otherwise the
							rs_reaper field	of the
							structure is set to
							the pid	of the reaper
							for the	specified
							process	id.

			     REAPER_STATUS_REALINIT	The specified process
							is the root of the
							reaper tree, i.e.,

			     The rs_children field returns the number of chil-
			     dren of the reaper	among the descendants.	It is
			     possible to have a	child whose reaper is not the
			     specified process,	since the reaper for any
			     existing children is not reset on the
			     PROC_REAP_ACQUIRE operation.  The rs_descendants
			     field returns the total number of descendants of
			     the reaper(s), not	counting descendants of	the
			     reaper in the subtree.  The rs_reaper field
			     returns the reaper	pid.  The rs_pid returns the
			     pid of one	reaper child if	there are any descen-

     PROC_REAP_GETPIDS	     Queries the list of descendants of	the reaper of
			     the specified process.  The request takes a
			     pointer to	a procctl_reaper_pids structure	in the
			     data parameter.

			     struct procctl_reaper_pids	{
				     u_int   rp_count;
				     struct procctl_reaper_pidinfo *rp_pids;
			     When called, the rp_pids field must point to an
			     array of procctl_reaper_pidinfo structures, to be
			     filled in on return, and the rp_count field must
			     specify the size of the array, into which no more
			     than rp_count elements will be filled in by the

			     The struct	procctl_reaper_pidinfo structure pro-
			     vides some	information about one of the reaper's
			     descendants.  Note	that for a descendant that is
			     not a child, it may be incorrectly	identified
			     because of	a race in which	the original child
			     process exited and	the exited process's pid was
			     reused for	an unrelated process.

			     struct procctl_reaper_pidinfo {
				     pid_t   pi_pid;
				     pid_t   pi_subtree;
				     u_int   pi_flags;
			     The pi_pid	field is the process id	of the descen-
			     dant.  The	pi_subtree field provides the pid of
			     the child of the reaper, which is the
			     (grand-)parent of the process.  The pi_flags
			     field returns the following flags,	further
			     describing	the descendant:

			     REAPER_PIDINFO_VALID     Set to indicate that the
						      structure	was filled in
						      by the kernel.  Zero-
						      filling the rp_pids
						      array and	testing	the
						      flag allows the caller
						      to detect	the end	of the
						      returned array.

			     REAPER_PIDINFO_CHILD     The pi_pid field identi-
						      fies the direct child of
						      the reaper.

     PROC_REAP_KILL	     Request to	deliver	a signal to some subset	of the
			     descendants of the	reaper.	 The data parameter
			     must point	to a procctl_reaper_kill structure,
			     which is used both	for parameters and status

			     struct procctl_reaper_kill	{
				     int     rk_sig;
				     u_int   rk_flags;
				     pid_t   rk_subtree;
				     u_int   rk_killed;
				     pid_t   rk_fpid;
			     The rk_sig	field specifies	the signal to be
			     delivered.	 Zero is not a valid signal number,
			     unlike for	kill(2).  The rk_flags field further
			     directs the operation.  It	is or-ed from the fol-
			     lowing flags:

			     REAPER_KILL_CHILDREN     Deliver the specified
						      signal only to direct
						      children of the reaper.

			     REAPER_KILL_SUBTREE      Deliver the specified
						      signal only to descen-
						      dants that were forked
						      by the direct child with
						      pid specified in the
						      rk_subtree field.
			     If	neither	the REAPER_KILL_CHILDREN nor the
			     REAPER_KILL_SUBTREE flags are specified, all cur-
			     rent descendants of the reaper are	signalled.

			     If	a signal was delivered to any process, the
			     return value from the request is zero.  In	this
			     case, the rk_killed field identifies the number
			     of	processes signalled.  The rk_fpid field	is set
			     to	the pid	of the first process for which signal
			     delivery failed, e.g., due	to permission prob-
			     lems.  If no such process exists, the rk_fpid
			     field is set to -1.

     PROC_TRACE_CTL	     Enable or disable tracing of the specified
			     process(es), according to the value of the	inte-
			     ger argument.  Tracing includes attachment	to the
			     process using the ptrace(2) and ktrace(2),	debug-
			     ging sysctls, hwpmc(4), dtrace(1),	and core dump-
			     ing.  Possible values for the data	argument are:

			     PROC_TRACE_CTL_ENABLE	     Enable tracing,
							     after it was dis-
							     abled by
							     Only allowed for

			     PROC_TRACE_CTL_DISABLE	     Disable tracing
							     for the specified
							     process.  Tracing
							     is	re-enabled
							     when the process
							     changes the exe-
							     cuting program
							     with the
							     syscall.  A child
							     inherits the
							     trace settings
							     from the parent
							     on	fork(2).

							     but the setting
							     persists for the
							     process even
							     after execve(2).

     PROC_TRACE_STATUS	     Returns the current tracing status	for the	speci-
			     fied process in the integer variable pointed to
			     by	data.  If tracing is disabled, data is set to
			     -1.  If tracing is	enabled, but no	debugger is
			     attached by the ptrace(2) syscall,	data is	set to
			     0.	 If a debugger is attached, data is set	to the
			     pid of the	debugger process.

     PROC_TRAPCAP_CTL	     Controls the capability mode sandbox actions for
			     the specified sandboxed processes,	on a return
			     from any syscall which gives either a ENOTCAPABLE
			     or	ECAPMODE error.	 If the	control	is enabled,
			     such errors from the syscalls cause delivery of
			     the synchronous SIGTRAP signal to the thread
			     immediately before	returning from the syscalls.

			     Possible values for the data argument are:

							  signal delivery on
							  capability mode
							  access violations.
							  The enabled mode is
							  inherited by the
							  children of the
							  process, and is kept
							  after	fexecve(2)

			     PROC_TRAPCAP_CTL_DISABLE	  Disable the signal
							  delivery on capabil-
							  ity mode access vio-
							  lations.  Note that
							  the global sysctl
							  might	still cause
							  the signal to	be
							  delivered.  See

			     On	signal delivery, the si_errno member of	the
			     siginfo signal handler parameter is set to	the
			     syscall error value, and the si_code member is
			     set to TRAP_CAP.

			     See capsicum(4) for more information about	the
			     capability	mode.

     PROC_TRAPCAP_STATUS     Return the	current	status of signalling capabil-
			     ity mode access violations	for the	specified
			     process.  The integer value pointed to by the
			     data argument is set to the
			     PROC_TRAPCAP_CTL_ENABLE value if the process con-
			     trol enables signal delivery, and to
			     PROC_TRAPCAP_CTL_DISABLE otherwise.

			     See the note about	sysctl kern.trap_enocap	above,
			     which gives independent global control of signal

     Disabling tracing on a process should not be considered a security	fea-
     ture, as it is bypassable both by the kernel and privileged processes,
     and via other system mechanisms.  As such,	it should not be utilized to
     reliably protect cryptographic keying material or other confidential

     If	an error occurs, a value of -1 is returned and errno is	set to indi-
     cate the error.

     The procctl() system call will fail if:

     [EFAULT]		The arg	parameter points outside the process's allo-
			cated address space.

     [EINVAL]		The cmd	argument specifies an unsupported command.

			The idtype argument specifies an unsupported identi-
			fier type.

     [EPERM]		The calling process does not have permission to	per-
			form the requested operation on	any of the selected

     [ESRCH]		No processes matched the requested idtype and id.

     [EINVAL]		An invalid operation or	flag was passed	in arg for a
			PROC_SPROTECT command.

     [EPERM]		The idtype argument is not equal to P_PID, or id is
			not equal to the pid of	the calling process, for

     [EINVAL]		Invalid	or undefined flags were	passed to a
			PROC_REAP_KILL request.

     [EINVAL]		An invalid or zero signal number was requested for a
			PROC_REAP_KILL request.

     [EINVAL]		The PROC_REAP_RELEASE request was issued by the
			init(8)	process.

     [EBUSY]		The PROC_REAP_ACQUIRE request was issued by a process
			that had already acquired reaper status	and has	not
			yet released it.

     [EBUSY]		The PROC_TRACE_CTL request was issued for a process
			already	being traced.

     [EPERM]		The PROC_TRACE_CTL request to re-enable	tracing	of the
			process	(PROC_TRACE_CTL_ENABLE), or to disable persis-
			tence of PROC_TRACE_CTL_DISABLE	on execve(2) was
			issued for a non-current process.

     [EINVAL]		The value of the integer data parameter	for the
			PROC_TRACE_CTL or PROC_TRAPCAP_CTL request is invalid.

     dtrace(1),	cap_enter(2,) kill(2), ktrace(2), ptrace(2), wait(2),
     capsicum(4), hwpmc(4), init(8)

     The procctl() function appeared in	FreeBSD	10.0.  The reaper facility is
     based on a	similar	feature	of Linux and DragonflyBSD, and first appeared
     in	FreeBSD	10.2.

FreeBSD	11.1		      September	27, 2016		  FreeBSD 11.1


Want to link to this manual page? Use this URL:

home | help