From 4e5c9d4290312d2b2ec0b9a7ac20621cb1e923b5 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Wed, 26 Aug 2015 13:54:09 -0700
Subject: [PATCH] runtime: Document args[0] and the no-usable-args fallback

This follows Python's API, which has 'args' and 'executable' (our
PATH) for Popen [1]).  That allows most users (who don't need to
distinguish between args[0] and the executable path) to just use args,
while still providing a means to make that distinction (set 'path')
for folks who do need it.

This restores the ability to explicitly set args[0] independent of the
path, which was requested in #34 [2] and ack-ed by Micheal [3] and
Mrunal [4], but didn't match the examples that landed with #34.

[1]: https://docs.python.org/3/library/subprocess.html#subprocess.Popen
[2]: https://github.com/opencontainers/specs/pull/34#issuecomment-126116173
[3]: https://github.com/opencontainers/specs/pull/34#issuecomment-127335834
[4]: https://github.com/opencontainers/specs/pull/34#issuecomment-127350235

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 runtime.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/runtime.md b/runtime.md
index be2045b58..6063f323a 100644
--- a/runtime.md
+++ b/runtime.md
@@ -75,22 +75,24 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin
     "hooks" : {
         "prestart": [
             {
-                "path": "/usr/bin/fix-mounts",
-                "args": ["arg1", "arg2"],
+                "args": ["/usr/bin/fix-mounts", "arg1", "arg2"],
                 "env":  [ "key1=value1"]
             },
             {
-                "path": "/usr/bin/setup-network"
+                "path": "/usr/bin/setup-network",
+                "args": ["net.eth1", "start"],
             }
         ],
         "poststop": [
             {
-                "path": "/usr/sbin/cleanup.sh",
-                "args": ["-f"]
+                "args": ["/usr/sbin/cleanup.sh", "-f"]
             }
         ]
     }
 ```
 
-`path` is required for a hook.
-`args` and `env` are optional.
+`args` is passed to the executable, and includes the command as `args[0]` (which MUST be an absolute path).
+`path` is optional, but if set it MUST be an absolute path.
+When set, it takes precedence over `args[0]` when selecting for the executable, but it does not effect the arguments passed to that executable.
+For example, the `setup-network` script above will still have `net.eth1` as `args[0]`.
+`env` is optional.