PERFORCE change 164121 for review

[Robert Watson]

http://perforce.freebsd.org/chv.cgi?CH=164121

Change 164121 by rwatson at rwatson_freebsd_capabilities on 2009/06/11 17:02:44

	Update man page.

Affected files ...

.. //depot/projects/trustedbsd/capabilities/src/libexec/rtld-elf-cap/rtld-elf-cap.1#4 edit

Differences ...

==== //depot/projects/trustedbsd/capabilities/src/libexec/rtld-elf-cap/rtld-elf-cap.1#4 (text+ko) ====

@@ -32,7 +32,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 30, 2009
+.Dd June 11, 2009
 .Os
 .Dt RTLD-ELF-CAP 1
 .Sh NAME
@@ -50,11 +50,14 @@
 is intended to be directly executed using the
 .Xr fexeve 2
 system call, and expects the binary to be passed as file descriptor
-.Dv 3 .
+.Dv 3 ,
+as well as additional libraries described by the
+.Dv LD_CAPLIBINDEX
+environmental variable.
 .Pp
-Binaries for the sandbox environment are relocatable shared objects with the
-addition of C start-up code (CSU) normally linked only into binaries
-intended for direct execution.
+Binaries for the sandbox environment are normal, dynamically linked binaries
+as created by
+.Xr gcc 1 .
 As with traditional
 .Fx
 binaries, the C run-time expects to begin execution with a
@@ -62,28 +65,20 @@
 function which will be passed execution-time arguments explicitly, as well
 as having access to inherited environmental variables.
 .Pp
-A typical
-.Xr gcc 1
-command line to build a sandbox-mode binary might be:
-.Bd -literal -offset indent
-gcc -o main.so main.c -shared /usr/lib/crt1.o
-.Ed
+Most capability-mode applications will be started using the APIs defined in
+.Xr libcapability 3 ,
+which properly set up the run-time environment for
+.Nm .
 .Sh IMPLEMENTATION NOTES
 Linking sandbox binaries as relocatable shared objects rather than linking
 them with a fixed virtual address allows them to be directly linked into
 consumers, if desired, for debugging or performance analysis purposes.
-.Pp
-The C run-time start-up code (CSU) is included to provide an ELF brand as
-well as
-.Dv _start
-function sufficient to properly align the stack, start C run-time services
-such as profiling and thread-local storage, and to provide and pass command
-line arguments and environmental variables to the executing binary.
 .Sh SEE ALSO
 .Xr gcc 1 ,
 .Xr ld-elf.so.1 1 ,
 .Xr cap_enter 2 ,
-.Xr fexecve 2
+.Xr fexecve 2 ,
+.Xr libcapability 3
 .Sh HISTORY
 Support for capabilities and capabilities mode was developed as part of the
 .Tn TrustedBSD
@@ -91,6 +86,10 @@
 .Sh BUGS
 WARNING: THIS IS EXPERIMENTAL SECURITY SOFTWARE THAT MUST NOT BE RELIED ON IN
 PRODUCTION SYSTEMS.  IT WILL BREAK YOUR SOFTWARE IN NEW AND UNEXPECTED WAYS.
+.Pp
+The format of
+.Dv LD_CAPLIBINDEX
+is not documented, and may change.
 .Sh AUTHORS
 .Nm
 is derived from