Document LISTEN_FDS for passing open file descriptors

This landed in runC with [1], but the bundle-author <-> runtime specs
explicitly avoid talking about how this is set (since the
bundle-author doesn't care about the runtime-caller <-> runtime
interface) [2].  However, *this* spec is about the runtime-caller <->
runtime interface, so we need to document it here.

I've left LISTEN_PID [3,4] out, since I don't see how the
runtime-caller would choose anything other than 1 for its value.  It
seems like something that a process would have to set for itself
(because guessing the PID of a child before spawning it seems racy ;).
In any event, the runC implementation seems to set this to 1
regardless of what systemd passes to it [4].

I've borrowed Shishir's wording for the example [4].

[1]: opencontainers/runc#231
[2]: opencontainers/runtime-spec#113 (comment)
[3]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html
[4]: opencontainers/runc#231 (comment)

Signed-off-by: W. Trevor King <wking@tremily.us>

Author: wking

runtime.md

@@ -48,6 +48,9 @@ It operates by default on the `config.json` and `runtime.json` in the current di
   * *`--config <PATH>`* Override `config.json` with an alternative path.  The path may not support seeking (e.g. `/dev/fd/3`).
   * *`--runtime <PATH>`* Override `runtime.json` with an alternative path.  The path may not support seeking (e.g. `/dev/fd/3`).
 * *Standard streams:* The runtime must attach its standard streams directly to the application process without inspection.
+* *Environment variables*
+  * *`LISTEN_FDS`:* The number of file descriptors passed.
+    For example, `LISTEN_FDS=2` would mean passing 3 and 4 (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds].
 * *Exit code:* The runtime must exit with the application process's exit code.
 
 Example:
@@ -137,3 +140,6 @@ $ funC signal --signal KILL hello-1
 $ echo $?
 0
 ```
+
+[standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors
+[systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html