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 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 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.
			   The status means that children orphaned by the
			   reaper's descendants	that were forked after the
			   acquisition of the status are reparented to the
			   reaper.  After the system initialization, init(8)
			   is the default reaper.

     PROC_REAP_RELEASE	   Releases 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 the	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 the 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.  init(8).
			   The rs_children field returns the number of chil-
			   dren	of the reaper among the	descendands.  It is
			   possible to have a child which reaper is not	the
			   specified process, since the	reaper for the exist-
			   ing 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 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	fol-
			   lowing flags, further describing 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	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 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 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
			   kill(2).  The rk_flags field	further	directs	the
			   operation.  It is or-ed from	the following flags:

			   REAPER_KILL_CHILDREN	    Deliver the	specified sig-
						    nal	only to	direct chil-
						    dren of the	reaper.

			   REAPER_KILL_SUBTREE	    Deliver the	specified sig-
						    nal	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	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	the permission prob-
			   lems.  If no	such process exist, 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 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	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 executing pro-
							   gram	with 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
							   persist 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 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 relied	on 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	per-
			sistence of the	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	10.3			August 21, 2015			  FreeBSD 10.3

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

home | help