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

FreeBSD Manual Pages

  
 
  

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

NAME
       pdfork,	pdrfork,  pdgetpid,  pdkill,  pdwait --	System calls to	manage
       process descriptors

LIBRARY
       Standard	C Library (libc, -lc)

SYNOPSIS
       #include	<sys/procdesc.h>

       pid_t
       pdfork(int *fdp,	int pdflags);

       pid_t
       pdrfork(int *fdp, int pdflags, int rfflags);

       int
       pdgetpid(int fd,	pid_t *pidp);

       int
       pdkill(int fd, int signum);

       int
       pdwait(int fd,  int *status,  int options,   struct __wrusage *wrusage,
	   struct __siginfo *info);

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 pdflags:

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

       PD_CLOEXEC
		  Set close-on-exec on process descriptor.

       The pdrfork() system call is a variant of pdfork() that also takes  the
       rfflags	argument  to  control sharing of process resources between the
       caller and the new process.  Like pdfork(),  the	 function  writes  the
       process	descriptor  referencing	 the created process into the location
       pointed to by the fdp argument.	See rfork(2) for a description of  the
       possible	 rfflag	 flags.	  The pdrfork()	system call requires that both
       the RFPROC and RFPROCDESC flags,	or RFSPAWN flag	are specified.

       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.

       The pdwait() system call	allows the calling thread to wait and retrieve
       the status information on the process referenced	by the fd process  de-
       scriptor.   See the description of the wait6 system call	for the	behav-
       ior specification.

       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.   Process state transitions can also be monitored using kqueue(2)
       filter EVFILT_PROCDESC; currently only NOTE_EXIT	is implemented.

       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.	  The  PID  of	the referenced process is not reused until the
       process descriptor is closed, whether or	 not  the  zombie  process  is
       reaped by pdwait(), wait6, or similar system calls.

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

       pdgetpid(),  pdkill(), and pdwait() return 0 on success and -1 on fail-
       ure.

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:

       [EFAULT]		  The copyout of the resulting file  descriptor	 value
			  to the memory	pointed	to by fdp failed.

			  Note that the	child process was already created when
			  this	condition is detected, and the child continues
			  execution, same as the parent.  If this  error  must
			  be  handled, it is advisable to memoize the getpid()
			  result before	the call to pdfork() or	pdrfork(), and
			  compare it to	the value returned by getpid()	after,
			  to see if code is executing in parent	or child.

       [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),  kqueue(2),  poll(2),  wait4(2),
       capsicum(4), procdesc(4)

HISTORY
       The  pdfork(),  pdgetpid(), and pdkill()	system calls first appeared in
       FreeBSD 9.0.  The pdrfork() and pdwait()	system calls first appeared in
       FreeBSD 16.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.   The	pdrfork()  and
       pdwait()	   functions	were	developed   by	 Konstantin   Belousov
       <kib@FreeBSD.org> with input from Alan Somers <asomers@FreeBSD.org>.

FreeBSD	16.0 CURRENT	       January 20, 2026			     PDFORK(2)

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

home | help