aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRobert Watson <rwatson@FreeBSD.org>2013-08-28 19:49:32 +0000
committerRobert Watson <rwatson@FreeBSD.org>2013-08-28 19:49:32 +0000
commit5ea1c4a2dfef36ff127a7ff343cf1dee8efdf50f (patch)
tree16f0ad30699623e5f37923c75b0fe5de5a642a17
parent663593f19fb0cd7717fb837aa3c0dc831f0412f7 (diff)
downloadsrc-5ea1c4a2dfef36ff127a7ff343cf1dee8efdf50f.tar.gz
src-5ea1c4a2dfef36ff127a7ff343cf1dee8efdf50f.zip
Add a simple procdesc(4) man page describing "options PROCDESC" and the
high-level facility, supplementing pdfork(2) and friends. Update capsicum.4 to xref. Suggested by: sbruno MFC after: 3 days
Notes
Notes: svn path=/head/; revision=255001
-rw-r--r--share/man/man4/Makefile1
-rw-r--r--share/man/man4/capsicum.414
-rw-r--r--share/man/man4/procdesc.493
3 files changed, 103 insertions, 5 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 3a7da855fe38..e51ad39fc080 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -367,6 +367,7 @@ MAN= aac.4 \
ppbus.4 \
ppc.4 \
ppi.4 \
+ procdesc.4 \
psm.4 \
pst.4 \
pt.4 \
diff --git a/share/man/man4/capsicum.4 b/share/man/man4/capsicum.4
index 39619f9b73b9..8f38dc42157d 100644
--- a/share/man/man4/capsicum.4
+++ b/share/man/man4/capsicum.4
@@ -1,5 +1,5 @@
.\"
-.\" Copyright (c) 2011 Robert N. M. Watson
+.\" Copyright (c) 2011, 2013 Robert N. M. Watson
.\" Copyright (c) 2011 Jonathan Anderson
.\" All rights reserved.
.\"
@@ -26,7 +26,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd September 20, 2011
+.Dd August 21, 2013
.Dt CAPSICUM 4
.Os
.Sh NAME
@@ -78,10 +78,13 @@ objects using capabilities rather than global namespaces:
.Bl -tag -width indent
.It process descriptors
File descriptors representing processes, allowing parent processes to manage
-child processes without requiring access to the PID namespace.
+child processes without requiring access to the PID namespace; described in
+greater detail in
+.Xr procdesc 4 .
.It anonymous shared memory
An extension to the POSIX shared memory API to support anonymous swap objects
-associated with file descriptors.
+associated with file descriptors; described in greater detail in
+.Xr shm_open 2 .
.El
.Sh SEE ALSO
.Xr cap_enter 2 ,
@@ -96,7 +99,8 @@ associated with file descriptors.
.Xr pdwait4 2 ,
.Xr read 2 ,
.Xr shm_open 2 ,
-.Xr write 2
+.Xr write 2 ,
+.Xr procdesc 4 ,
.Sh HISTORY
.Nm
first appeared in
diff --git a/share/man/man4/procdesc.4 b/share/man/man4/procdesc.4
new file mode 100644
index 000000000000..f7477da88243
--- /dev/null
+++ b/share/man/man4/procdesc.4
@@ -0,0 +1,93 @@
+.\"
+.\" Copyright (c) 2013 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" This software was developed by SRI International and the University of
+.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
+.\" ("CTSRD"), as part of the DARPA CRASH research programme.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd August 21, 2013
+.Dt PROCDESC 4
+.Os
+.Sh NAME
+.Nm procdesc
+.Nd process descriptor facility
+.Sh SYNOPSIS
+.Cd "options PROCDESC"
+.Sh DESCRIPTION
+.Nm
+is a file-descriptor-oriented interface to process signalling and control,
+which supplements historic
+.Ux
+.Xr fork 2 ,
+.Xr kill 2 ,
+and
+.Xr wait4 2
+primitives with
+new system calls such as
+.Xr pdfork 2 ,
+.Xr pdkill 2 ,
+and
+.Xr pdwait4 2 .
+.Nm
+is designed for use with
+.Xr capsicum 4 ,
+replacing process identifiers with capability-oriented references.
+However, it can also be used independently of
+.Xr capsicum 4 ,
+displacing PIDs, which may otherwise suffer from race conditions.
+Given a process descriptor, it is possible to query its conventional PID using
+.Xr pdgetpid 2 .
+.Sh SEE ALSO
+.Xr fork 2 ,
+.Xr kill 2 ,
+.Xr wait4 2 ,
+.Xr pdfork 2 ,
+.Xr pdgetpid 2 ,
+.Xr pdkill 2 ,
+.Xr pdwait4 ,
+.Xr capsicum 4
+.Sh HISTORY
+.Nm
+first appeared in
+.Fx 9.0 ,
+and was developed at the University of Cambridge.
+.Sh AUTHORS
+.Nm
+was developed by
+.An -nosplit
+.An "Robert Watson" Aq rwatson@FreeBSD.org
+and
+.An "Jonathan Anderson" Aq jonathan@FreeBSD.org
+at the University of Cambridge, and
+.An "Ben Laurie" Aq benl@FreeBSD.org
+and
+.An "Kris Kennaway" Aq kris@FreeBSD.org
+at Google, Inc.
+.Sh BUGS
+.Nm
+is considered experimental in
+.Fx .