start: Add a --state option

This gives us an easy way to share state JSON (because sometimes the
PID is insufficient, e.g. on Linux you may need externalFds for
efficient checkpointing [1,2]) [3].

Possible alternatives for transmitting state information, and why I
feel this approach is superior:

* Writing a state file from a pre-start hook [4].  This is pretty
  close to the --state option, but the --state option allows callers
  to recover the JSON via a named pipe like /dev/fd/3.  That sort of
  direct connection would be trickier to setup with a hook-based
  approach.  Pre-start and post-stop hooks may still be the best
  solution for (de)registering a container with a monitoring service,
  but that's not quite the same application.

* Writing a state file to a global directory [5].  Atomic changes,
  change-monitoring, garbage collection, and ownership/access issues
  on a global directory are all hard to get right (or have ambiguous
  values of "right") [6].

* Requiring runtimes to maintain an internal registry of containers
  they launch [7].  This gives runtimes more flexibility than having a
  single, global directory.  But ownership/access issues are still
  difficult (if one unprivileged user registers a container, can
  another unprivileged user see that entry?  What elevated permissions
  would you need to see that entry?  To remove that entry?).  And the
  easiest way to get atomic changes and garbage-collection is by
  registering with a daemon, while not requiring a daemon is currently
  the #1 feature listed on [8].

In the event that any of those arguments seem leaky, callers that
prefer a different approach can easily use hooks (without setting
--state) or write wrappers that use a named pipe approach like
(--state /dev/fd/3) to collect the JSON and then write it to their
preferred registry.  So the --state approach seems easy for the
runtime to implement reliably, and also compatible with any of the
suggested alternatives.  The converse is not true; requiring a write
to a global or per-runtime registry is not compatible with use-cases
that prefer the anonymity of not writing the state at all (which is
possible just by leaving off the --state option).

[1]: opencontainers/runtime-spec#87 (comment)
[2]: https://groups.google.com/a/opencontainers.org/d/msg/dev/z25xQsF3pHA/ixyeTrxyFwAJ
     Subject: Re: Drop /run/opencontainer entirely?
     Date: Fri, 4 Sep 2015 21:30:24 -0700
     Message-ID: <20150905043024.GB25638@odin.tremily.us>
[3]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/W1RVyCXCCQAJ
     Subject: Re: removal of /run/opencontainer/containers, add --state?
     Date: Tue, 8 Dec 2015 15:49:57 -0800
     Message-ID: <20151208234957.GK2767@odin.tremily.us>
[4]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/GQs0zkRHBwAJ
     Subject: Re: removal of /run/opencontainer/containers
     Date: Mon, 30 Nov 2015 13:55:40 -0800
     Message-ID: <20151130215540.GF23595@odin.tremily.us>
[5]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime.md#state
[6]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/JRm4auylBQAJ
     Subject: removal of /run/opencontainer/containers
     Date: Wed, 25 Nov 2015 14:29:35 +0000
     Message-ID: <CAD2oYtNipt3i_C6=J4Bc-jwauo5YAvKXUqTROnPNP3vZ9+C5Vw@mail.gmail.com>
[7]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/wHYucS-rBQAJ
     Subject: Re: removal of /run/opencontainer/containers
     Date: Wed, 25 Nov 2015 08:06:10 -0800
     Message-ID: <CANEZBD7VCWj6w5dFAEbULrL6WsY=FSRhVsWFreYXUOHwsUJkwA@mail.gmail.com>
[8]: http://runc.io/
     Embeddable
     Containers are started as a child process of runC and can be
     embedded into various other systems without having to run a
     Docker daemon.

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

runtime.md

@@ -52,6 +52,8 @@ Start a container from a bundle directory.
   * *`--id <ID>`* Set the container ID when creating or joining a container.
     If not set, the runtime is free to pick any ID that is not already in use.
   * *`--bundle <PATH>`* Override the path to the bundle directory (defaults to the current working directory).
+  * *`--state <PATH>`* The runtime MUST write the state JSON to this path (creating a new file or truncating a previous file as necessary).
+    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.
@@ -61,11 +63,18 @@ Start a container from a bundle directory.
 Example:
 ```sh
 # in a bundle directory with a process that echos "hello" and exits 42
-$ funC start --id hello-1
+$ funC start --id hello-1 --state hello.json
 hello
 
 $ echo $?
 42
+$ cat hello.json
+{
+  "version": "0.1.0",
+  "id": "hello-1",
+  "pid": 4422,
+  "root": "/var/lib/oci/hello"
+}
 ```
 
 [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02