PERFORCE change 157181 for review

[Robert Watson]

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

Change 157181 by rwatson at rwatson_freebsd_capabilities on 2009/02/04 23:29:05

	Now that the ABI for sandbox binaries is settling down, put some
	initial chicken-scratchings in the man page.

Affected files ...

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

Differences ...

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

@@ -36,8 +36,49 @@
 .Os
 .Dt RTLD-ELF-CAP 1
 .Sh NAME
+.Nm ld-elf-cap.so ,
 .Nm rtld-elf-cap
 .Nd capability-mode run-time link editor
+.Sh DESCRIPTION
+The
+.Nm
+is a version of
+.Xr ld-elf.so 1
+specific to the sandbox environment created using
+.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 .
+.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.
+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.
+.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
+.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 HISTORY
 Support for capabilities and capabilities mode was developed as part of the
 .Tn TrustedBSD