From owner-p4-projects@FreeBSD.ORG Wed Feb 4 23:29:45 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id E913F1065677; Wed, 4 Feb 2009 23:29:44 +0000 (UTC) Delivered-To: perforce@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A9591106566C for ; Wed, 4 Feb 2009 23:29:44 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id 7C25D8FC16 for ; Wed, 4 Feb 2009 23:29:44 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.3/8.14.3) with ESMTP id n14NTi8M022403 for ; Wed, 4 Feb 2009 23:29:44 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.3/8.14.3/Submit) id n14NTiJ5022401 for perforce@freebsd.org; Wed, 4 Feb 2009 23:29:44 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Wed, 4 Feb 2009 23:29:44 GMT Message-Id: <200902042329.n14NTiJ5022401@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to bb+lists.freebsd.perforce@cyrus.watson.org using -f From: Robert Watson To: Perforce Change Reviews Cc: Subject: PERFORCE change 157181 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 04 Feb 2009 23:29:45 -0000 http://perforce.freebsd.org/chv.cgi?CH=157181 Change 157181 by rwatson@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