Skip to content

Commit

Permalink
Use RFC 2119's keywords (MUST, MAY, ...)
Browse files Browse the repository at this point in the history
This approach has landed in opencontainers/specs [1,2].  You can find
the RFC here [3].

[1]: opencontainers/runtime-spec#256
[2]: opencontainers/runtime-spec#260
[3]: http://tools.ietf.org/html/rfc2119

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Dec 9, 2015
1 parent 0d0c8db commit 52ca435
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions runtime.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# Operations

A conformant runtime should provide an executable (called `funC` in the following examples).
The template for supported commands is:
A conformant runtime MUST provide an executable (called `funC` in the following examples).
That executable MUST support commands with the following template:

```sh
$ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments>
```

## Global options

None are required, but the runtime may support options that start with at least one hyphen.
Global options may take positional arguments (e.g. `--log-level debug`), but the option parsing must be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` for any `<COMMAND>` that does not start with a hyphen (including commands not specified in this document).
None are required, but the runtime MAY support options that start with at least one hyphen.
Global options MAY take positional arguments (e.g. `--log-level debug`), but the option parsing MUST be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` for any `<COMMAND>` that does not start with a hyphen (including commands not specified in this document).

## Character encodings

Expand All @@ -23,14 +23,14 @@ For example, POSIX systems define [`LANG` and related environment variables][pos

Print the runtime version and exit.

* *Options* None are required, but the runtime may support options.
* *Options* None are required, but the runtime MAY support options.
* *Standard streams*
* *stdin:* The runtime may not attempt to read from its stdin.
* *stdout:* The runtime must print its name, a space, and its version as the first line to its stdout.
The name may contain any Unicode characters except a control codes and newlines.
The runtime may print additional lines its stdout, and the format for those lines is not specified in this document.
* *stderr:* The runtime may print diagnostic messages to stderr, and the format for those lines is not specified in this document.
* *Exit code:* The runtime must exit with zero.
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
* *stdout:* The runtime MUST print its name, a space, and its version as the first line to its stdout.
The name MAY contain any Unicode characters, but MUST NOT contain control codes or newlines.
The runtime MAY print additional lines its stdout, and the format for those lines is not specified in this document.
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
* *Exit code:* The runtime MUST exit with zero.

Example:
```sh
Expand All @@ -50,11 +50,11 @@ Start a container from a bundle directory.
If not set, the runtime is free to pick any ID that is not already in use.
* *`--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.
* *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.
For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the application process (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:
```sh
Expand Down

0 comments on commit 52ca435

Please sign in to comment.