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

FreeBSD Manual Pages

  
 
  

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

NAME
     procctl --	control	processes

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <sys/procctl.h>

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

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

			     PPROT_CLEAR     Clear the protected state of se-
					     lected 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 fu-
					       ture child processes.

     PROC_REAP_ACQUIRE	     Acquires the reaper status	for the	current
			     process.  Reaper status means that	children or-
			     phaned 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 re-
			     turned:

			     REAPER_STATUS_OWNED	The specified process
							has acquired reaper
							status and has not re-
							leased 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.,
							init(8).

			     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 ex-
			     isting 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 re-
			     turns the reaper pid.  The	rs_pid returns the pid
			     of	one reaper child if there are any descendants.

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

			     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 be-
			     cause 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	de-
			     scribing the descendant:

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

			     REAPER_PIDINFO_CHILD      The pi_pid field	iden-
						       tifies the direct child
						       of the reaper.

			     REAPER_PIDINFO_REAPER     The reported process is
						       itself a	reaper.	 The
						       descendants of the sub-
						       ordinate	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 re-
			     turn.

			     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 de-
			     livered.  Zero is not a valid signal number, un-
			     like for kill(2).	The rk_flags field further di-
			     rects 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 re-
			     turn 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
							     PROC_TRACE_CTL_DISABLE.
							     Only allowed for
							     self.

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

			     PROC_TRACE_CTL_DISABLE_EXEC     Same as
							     PROC_TRACE_CTL_DISABLE,
							     but the setting
							     persists for the
							     process even af-
							     ter 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 im-
			     mediately before returning	from the syscalls.

			     Possible values for the data argument are:

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

			     PROC_TRAPCAP_CTL_DISABLE	  Disable the signal
							  delivery on capabil-
							  ity mode access vio-
							  lations.  Note that
							  the global sysctl
							  kern.trap_enocap
							  might	still cause
							  the signal to	be de-
							  livered.  See
							  capsicum(4).

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

     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 sig-
			     nal that should be	delivered to the caller.  Use
			     zero to cancel a previously requested signal de-
			     livery.

     PROC_PDEATHSIG_STATUS   Query the current signal number that will be de-
			     livered 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 de-
			     livery has	not been requested, it will contain
			     zero on return.

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

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

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

     [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
			PROC_REAP_ACQUIRE or PROC_REAP_RELEASE requests.

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

     [EINVAL]		The PROC_PDEATHSIG_CTL or PROC_PDEATHSIG_STATUS	re-
			quest referenced an unsupported	id, idtype or invalid
			signal number.

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

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

BSD				 May 12, 2018				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUES | ERRORS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=procctl&sektion=2&manpath=FreeBSD+11.2-RELEASE+and+Ports>

home | help