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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PROCCTL(2)		  FreeBSD 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 oper-
			ation and zero or more optional	flags.	The following
			operations are supported:

			PPROT_SET	Mark the selected processes as pro-
					tected.

			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 protected.
					  Future child processes will also
					  mark all of their future child pro-
					  cesses.

     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	acqui-
			sition 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 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 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 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 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
			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 descendant.
			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
						 procctl_reaper_pidinfo	struc-
						 ture was filled in by the
						 kernel.  Zero-filling the
						 rp_pids array 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 identifies
						 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 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 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 following flags:

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

			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 val-
			ues for	the data argument are:

			PROC_TRACE_CTL_ENABLE		Enable tracing,	after
							it was disabled	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 executing
							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	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 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.

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
			issued for a non-current process.

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

SEE ALSO
     dtrace(1),	kill(2), ktrace(2), ptrace(2), wait(2),	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.

FreeBSD	11.0			August 21, 2015			  FreeBSD 11.0

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.0-RELEASE+and+Ports>

home | help