PERFORCE change 164566 for review

[Robert Watson]

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

Change 164566 by rwatson at rwatson_freebsd_capabilities on 2009/06/17 11:14:10

	Update rtld-elf-cap.1 to reflect recent changes.

Affected files ...

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

Differences ...

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

@@ -45,34 +45,51 @@
 is a version of
 .Xr ld-elf.so.1 1
 specific to the sandbox environment created using
+.Xr libcapability 3 ,
+which provides certain extended or modified linker services for that
+environment:
+.Bl -bullet
+.It
+Will not attempt to use global file system namespaces that are not available
+when running under
 .Xr cap_enter 2 .
-.Nm
-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 ,
-as well as additional libraries described by the
+.It
+Expects to be directly executed using
+.Xr fexecve 2 ,
+with the desired binary to run passed as file descriptor 3.
+.It
+Recognizes the addition symbol
+.Dv cap_main ,
+which will be used in preference to the normal ELF entry point for a binary
+when in sandbox mode.
+This makes it easy a single binary to select different behavior when run in
+the different environments.
+.It Interprets the
 .Dv LD_CAPLIBINDEX
-environmental variable.
+environmental variable set by sandbox start touines, and implements
+.Fn ld_capibindex_lookup ,
+allowing file descriptors for binaries and libraries passed across
+.Xr fexecve 2
+to be used by
+.Xr libcapability 3 ,
+as well as applications.
+.It
+Implements a version of
+.Fn ld_insandbox
+that returns true, overriding the libc function that returns false.
+.El
 .Pp
-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
-.Dv main
-function which will be passed execution-time arguments explicitly, as well
-as having access to inherited environmental variables.
+Applications using
+.Dv cap_main
+will need to export it as a dynamic symbol, perhaps using
+.Xr gcc 1 's
+.Dv -rdynamic
+command line flag.
 .Pp
 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.
 .Sh SEE ALSO
 .Xr gcc 1 ,
 .Xr ld-elf.so.1 1 ,