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

FreeBSD Manual Pages

  
 
  

home | help 
PDFORK(2)		      System Calls Manual		     PDFORK(2)

NAME
       pdfork, pdgetpid, pdkill, pdwait4 -- System calls to manage process de-
       scriptors

LIBRARY
       Standard	C Library (libc, -lc)

SYNOPSIS
       #include	<sys/procdesc.h>

       int
       pdfork(int *fdp,	int flags);

       int
       pdgetpid(int fd,	pid_t *pidp);

       int
       pdkill(int fd, int signum);

       int
       pdwait4(int fd, int *status, int	options, struct	rusage *rusage);

DESCRIPTION
       Process	 descriptors  are  special  file  descriptors  that  represent
       processes, and are created using	pdfork(), a variant of fork(2),	which,
       if successful, returns a	process	descriptor in the integer  pointed  to
       by  fdp.	 Processes created via pdfork()	will not cause SIGCHLD on ter-
       mination.  pdfork() can accept the flags:

       PD_DAEMON  Instead of the default terminate-on-close  behaviour,	 allow
		  the  process	to  live  until	 it  is	explicitly killed with
		  kill(2).

		  This option is not permitted in capsicum(4) capability  mode
		  (see cap_enter(2)).

       pdgetpid() queries the process ID (PID) in the process descriptor fd.

       pdkill()	is functionally	identical to kill(2), except that it accepts a
       process descriptor, fd, rather than a PID.

       pdwait4() behaves identically to	wait4(2), but operates with respect to
       a process descriptor argument rather than a PID.

       The  following  system  calls also have effects specific	to process de-
       scriptors:

       fstat(2)	queries	status of a process  descriptor;  currently  only  the
       st_mode,	 st_birthtime,	st_atime, st_ctime and st_mtime	fields are de-
       fined.  If the owner read, write, and execute bits  are	set  then  the
       process represented by the process descriptor is	still alive.

       poll(2) and select(2) allow waiting for process state transitions; cur-
       rently  only  POLLHUP  is  defined, and will be raised when the process
       dies.

       close(2)	will close the process descriptor unless PD_DAEMON is set;  if
       the  process  is	 still	alive  and  this  is the last reference	to the
       process descriptor, the process will  be	 terminated  with  the	signal
       SIGKILL.

       pdfork and associated functions depend on options PROCDESC described in
       procdesc(4).

RETURN VALUES
       pdfork()	returns	a PID, 0 or -1,	as fork(2) does.

       pdgetpid() and pdkill() return 0	on success and -1 on failure.

       pdwait4() returns a PID on success and -1 on failure.

ERRORS
       These  functions	 may  return the same error numbers as their PID-based
       equivalents (e.g.  pdfork()  may	 return	 the  same  error  numbers  as
       fork(2)), with the following additions:

       [EINVAL]		  The signal number given to pdkill() is invalid.

       [ENOTCAPABLE]	  The  process descriptor being	operated on has	insuf-
			  ficient rights (e.g.	CAP_PDKILL for pdkill()).

SEE ALSO
       close(2), fork(2), fstat(2), kill(2), poll(2),  wait4(2),  capsicum(4),
       procdesc(4)

HISTORY
       The pdfork(), pdgetpid(), pdkill() and pdwait4()	system calls first ap-
       peared in FreeBSD 9.0.

       Support	for  process  descriptors  mode	 was  developed	as part	of the
       TrustedBSD Project.

AUTHORS
       These functions and the capability facility were	created	by  Robert  N.
       M.     Watson	 <rwatson@FreeBSD.org>	   and	  Jonathan    Anderson
       <jonathan@FreeBSD.org> at the University	of Cambridge Computer  Labora-
       tory with support from a	grant from Google, Inc.

BUGS
       pdwait4() has not yet been implemented.

FreeBSD	10.0			August 28, 2013			     PDFORK(2)

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

home | help