PERFORCE change 166810 for review

[Robert Watson]

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

Change 166810 by rwatson at rwatson_freebsd_capabilities on 2009/07/30 17:42:09

	Improve commenting.

Affected files ...

.. //depot/projects/trustedbsd/capabilities/src/tools/cap/fdrpc/fdrpc.c#5 edit

Differences ...

==== //depot/projects/trustedbsd/capabilities/src/tools/cap/fdrpc/fdrpc.c#5 (text+ko) ====

@@ -52,6 +52,9 @@
 
 #define	FDRPC_SANDBOX	"./fdrpc"
 
+/*
+ * Unsandboxed host process with full user rights.
+ */
 int
 main(int argc, char *argv[])
 {
@@ -65,10 +68,16 @@
 	if (argc != 1)
 		errx(-1, "usage: fdrpc_host");
 
-	if (lch_start(FDRPC_SANDBOX, fdrpc_argv, LCH_PERMIT_STDERR, &lcsp)
-	    < 0)
+	/*
+	 * Create a sandbox, do permit access to stderr.
+	 */
+	if (lch_start(FDRPC_SANDBOX, fdrpc_argv, LCH_PERMIT_STDERR, &lcsp) < 0)
 		err(-1, "lch_start %s", FDRPC_SANDBOX);
 
+	/*
+	 * Send a one-byte message to the sandbox and attach stdin as a
+	 * right.
+	 */
 	ch = 'X';		/* RPC data. */
 	fdcount = 1;
 	fd_send = STDIN_FILENO;
@@ -85,9 +94,17 @@
 		printf("lch_rpc_rights: OK\n");
 	else
 		printf("lch_rpc_rights: fdcount %d\n", fdcount);
+
+	/*
+	 * Terminate the sandbox when done.
+	 */
 	lch_stop(lcsp);
 }
 
+/*
+ * Sandboxed process implementing an 'echo' RPC that accepts and returns file
+ * descriptors to the host.
+ */
 int
 cap_main(int argc, char *argv[])
 {
@@ -101,7 +118,14 @@
 	if (lcs_get(&lchp) < 0)
 		err(-1, "lcs_get");
 
+	/*
+	 * Serve RPCs from the host until the sandbox is killed.
+	 */
 	while (1) {
+		/*
+		 * Receive an RPC from the host, along with up to one file
+		 * descriptor.
+		 */
 		fdcount = 1;
 		if (lcs_recvrpc_rights(lchp, &opno, &seqno, &buffer, &len,
 		    &fd, &fdcount) < 0) {
@@ -114,6 +138,12 @@
 			errx(-1, "lcs_recvrpc_rights: opno %d", opno);
 		if (fdcount != 1)
 			errx(-1, "lcs_recvrpc_rights: fdcount %d", fdcount);
+
+		/*
+		 * Reply with the same message and same file descriptor.
+		 * Remember to free the message and received descriptor when
+		 * done.
+		 */
 		iov.iov_len = len;
 		iov.iov_base = buffer;
 		if (lcs_sendrpc_rights(lchp, opno, seqno, &iov, 1, &fd,