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 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 sys-
			  tem exhausts the available memory and	swap.  The arg
			  parameter must point to an integer containing	an op-
			  eration and zero or more optional flags.  The	fol-
			  lowing operations are	supported:

			  PPROT_SET    Mark the	selected processes as pro-

			  PPROT_CLEAR  Clear the protected state of selected

			  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

			  PPROT_INHERIT	 When used with	PPROT_SET, mark	all
					 future	child processes	of each	se-
					 lected	process	as protected.  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 ac-
			  quisition 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 speci-
			  fied 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 returned:

			  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, oth-
						  erwise 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.,	init(8).

			  The rs_children field	returns	the number of children
			  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 descen-
			  dants	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 ar-
			  ray 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 ker-

			  The struct procctl_reaper_pidinfo structure provides
			  some information about one of	the reaper's descen-
			  dants.  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

			  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 follow-
			  ing flags, further describing	the descendant:

			  REAPER_PIDINFO_VALID	 Set to	indicate that the
						 procctl_reaper_pidinfo	struc-
						 ture was filled in by the
						 kernel.  Zero-filling the
						 rp_pids array and testing the
						 REAPER_PIDINFO_VALID flag al-
						 lows the caller to detect the
						 end of	the returned array.

			  REAPER_PIDINFO_CHILD	 The pi_pid field identifies
						 the direct child of the

			  REAPER_PIDINFO_REAPER	 The reported process is it-
						 self a	reaper.	 The descen-
						 dants of the subordinate
						 reaper	are not	reported.

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

			  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 deliv-
			  ered.	 Zero is not a valid signal number, unlike for
			  kill(2).  The	rk_flags field further directs the op-
			  eration.  It is or-ed	from the following flags:

			  REAPER_KILL_CHILDREN	Deliver	the specified signal
						only to	direct children	of the

			  REAPER_KILL_SUBTREE	Deliver	the specified signal
						only to	descendants 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 current
			  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 problems.  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 integer
			  argument.  Tracing includes attachment to the
			  process using	the ptrace(2) and ktrace(2), debugging
			  sysctls, hwpmc(4), dtrace(1),	and core dumping.
			  Possible values for the data argument	are:

			  PROC_TRACE_CTL_ENABLE	       Enable tracing, after
						       it was disabled by
						       Only allowed for	self.

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

						       but the setting per-
						       sists for the process
						       even after execve(2).

     PROC_TRACE_STATUS	  Returns the current tracing status for the specified
			  process in the integer variable pointed to by	data.
			  If tracing is	disabled, data is set to -1.  If trac-
			  ing 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

     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 re-
			  turning from the syscalls.

			  Possible values for the data argument	are:

			  PROC_TRAPCAP_CTL_ENABLE   Enable the SIGTRAP signal
						    delivery on	capability
						    mode access	violations.
						    The	enabled	mode is	inher-
						    ited by the	children of
						    the	process, and is	kept
						    after fexecve(2) calls.

			  PROC_TRAPCAP_CTL_DISABLE  Disable the	signal deliv-
						    ery	on capability mode ac-
						    cess violations.  Note
						    that the global sysctl
						    kern.trap_enocap 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 capa-
			  bility mode.

     PROC_TRAPCAP_STATUS  Return the current status of signalling capability
			  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 control enables signal delivery, and to

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

     PROC_PDEATHSIG_CTL	  Request the delivery of a signal when	the parent of
			  the calling process exits.  idtype must be P_PID and
			  id must be the either	caller's pid or	zero, with no
			  difference in	effect.	 The value is cleared for
			  child	processes and when executing set-user-ID or
			  set-group-ID binaries.  arg must point to a value of
			  type int indicating the signal that should be	deliv-
			  ered to the caller.  Use zero	to cancel a previously
			  requested signal delivery.

			  Query	the current signal number that will be deliv-
			  ered when the	parent of the calling process exits.
			  idtype must be P_PID and id must be the either
			  caller's pid or zero,	with no	difference in effect.
			  arg must point to a memory location that can hold a
			  value	of type	int.  If signal	delivery has not been
			  requested, it	will contain zero on return.

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

			quest referenced an unsupported	id, idtype or invalid
			signal number.

     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.  The PROC_PDEATHSIG_CTL facility is based	on the
     prctl(PR_SET_PDEATHSIG, ...) feature of Linux, and	first appeared in
     FreeBSD 11.2.

FreeBSD	13.0		       February	23, 2019		  FreeBSD 13.0


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

home | help