PERFORCE change 164072 for review

[Robert Watson]

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

Change 164072 by rwatson at rwatson_freebsd_capabilities on 2009/06/11 07:11:08

	Document lch_start_flags().

Affected files ...

.. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#11 edit

Differences ...

==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#11 (text+ko) ====

@@ -48,6 +48,8 @@
 .Fn lc_limitfd "int fd" "cap_rights_t rights"
 .Ft int
 .Fn lch_start "const char *sandbox" "char *const argv[]" "struct lc_sandbox **lcsp"
+.Ft int
+.Fn lch_start_flags "const char *sandbox" "char *const argv[]" "u_int flags" "struct lc_sandbox **lcsp"
 .Ft void
 .Fn lch_stop "struct lc_sandbox *lcsp"
 .Ft int
@@ -85,13 +87,31 @@
 .Dt "struct lc_sandbox" ,
 which is returned by
 .Fn lch_start
+and
+.Fn lch_start_flags
 for successfully started sandboxes, and passed into other APIs to indicate
 which sandbox should be acted on.
-.Fn lch_start
-creates a new executing sandbox, given the name of the sandbox binary via
-.Va sandbox .
-Executing sandboxes may be stopped (and state freed) using
+Both calls create new executing sandboxes, given the name of the sandbox
+binary via
+.Va sandbox ,
+and command line arguments
+.Va argv .
+.Pp
+.Fn lch_start_flags
+accepts an optional flags field to fine-tune aspects of sandbox operation;
+the only currently defined flag is
+.Dv LCH_PERMIT_STDERR ,
+which allows the sandbox to write to the current process's
+.Dv stderr .
+By default, this is not permitted.
+.Pp
+Executing sandboxes may be stopped (and all state freed) using
 .Fn lch_stop .
+Following a call to
+.Fn lch_stop ,
+the
+.Va lchp
+argument will no longer be valid.
 .Pp
 Properties of the sandbox, such as the socket used to communicate with it,
 the proces descriptor for the sandbox process, and the pid, may be queried