Skip to content

Commit 24ce5cc

Browse files
committed
Use RFC 2119's keywords (MUST, MAY, ...)
This is likely where opencontainers/specs is going [1], although the PR hasn't landed yet [2]. [1]: opencontainers/runtime-spec#256 [2]: opencontainers/runtime-spec#260
1 parent 10d55ac commit 24ce5cc

File tree

1 file changed

+15
-16
lines changed

1 file changed

+15
-16
lines changed

runtime.md

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
11
# Operations
22

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

66
```sh
77
$ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments>
88
```
99

1010
## Global options
1111

12-
None are required, but the runtime may support options that start with at least one hyphen.
13-
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).
12+
None are required, but the runtime MAY support options that start with at least one hyphen.
13+
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).
1414

1515
## Commands
1616

1717
### version
1818

1919
Print the runtime version and exit.
2020

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

3030
Example:
3131
```sh
@@ -38,19 +38,18 @@ $ echo $?
3838

3939
### start
4040

41-
Starts a container from a bundle directory.
42-
It operates by default on the `config.json` and `runtime.json` in the current directory.
41+
Start a container from a bundle directory.
4342

4443
* *Options*
4544
* *`--id <ID>`* Set the container ID when creating or joining a container.
4645
If not set, the runtime is free to pick any ID that is not already in use.
4746
* *`--config <PATH>`* Override `config.json` with an alternative path. The path may not support seeking (e.g. `/dev/fd/3`).
4847
* *`--runtime <PATH>`* Override `runtime.json` with an alternative path. The path may not support seeking (e.g. `/dev/fd/3`).
49-
* *Standard streams:* The runtime must attach its standard streams directly to the application process without inspection.
48+
* *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection.
5049
* *Environment variables*
5150
* *`LISTEN_FDS`:* The number of file descriptors passed.
52-
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].
53-
* *Exit code:* The runtime must exit with the application process's exit code.
51+
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].
52+
* *Exit code:* The runtime MUST exit with the application process's exit code.
5453

5554
Example:
5655
```sh

0 commit comments

Comments
 (0)