Skip to content

Commit 2424618

Browse files
wkingwking
committed
command-line-interface: Add a 'kill' command
Partially catch up with be59415 (Split create and start, 2016-04-01, #384). The interface is based on POSIX [1], util-linux [2], and GNU coreutils [3]. The TERM/KILL requirement is a minimum portability requirement for soft/hard stops. Windows lacks POSIX signals [4], and currently supports soft stops in Docker with whatever is behind hcsshim.ShutdownComputeSystem [5]. The docs I'm landing here explicitly allow that sort of substitution, because we need to have soft/hard stop on those platforms but *can't* use POSIX signals. They borrow wording from 35b0e9e (config: Clarify MUST for platform.os and .arch, 2016-05-19, #441) to recommend runtime authors document the alternative technology so bundle-authors can prepare (e.g. by installing the equivalent to a SIGTERM signal handler). [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/kill.html [2]: http://man7.org/linux/man-pages/man1/kill.1.html [3]: http://www.gnu.org/software/coreutils/manual/html_node/kill-invocation.html [4]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/PlGKu7QUwLE Subject: Fwd: Windows support for OCI stop/signal/kill (runtime-spec#356) Date: Thu, 26 May 2016 11:03:29 -0700 Message-ID: <[email protected]> [5]: https://github.com/docker/docker/pull/16997/files#diff-5d0b72cccc4809455d52aadc62329817R230 Signed-off-by: W. Trevor King <[email protected]>
1 parent f6ebd05 commit 2424618

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

‎command-line-interface.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,10 +102,46 @@ $ echo $?
102102
0
103103
```
104104

105+
### kill
106+
107+
[Send a signal][kill] to the container process.
108+
109+
* *Arguments*
110+
* *`<ID>`* The container being signaled.
111+
* *Options*
112+
* *`--signal <SIGNAL>`* The signal to send (defaults to `TERM`).
113+
The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals].
114+
The runtime MAY support additional signal names.
115+
On platforms that support [POSIX signals][posix-signals], the runtime MUST implement this command using POSIX signals.
116+
On platforms that do not support POSIX signals, the runtime MAY implement this command with alternative technology as long as `TERM` and `KILL` retain their POSIX semantics.
117+
Runtime authors on non-POSIX platforms SHOULD submit documentation for their TERM implementation to this specificiation, so runtime callers can configure the container process to gracefully handle the signals.
118+
* *Standard streams:*
119+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
120+
* *stdout:* The runtime MAY print diagnostic messaged to stdout, and the format for those lines is not specified in this document.
121+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
122+
* *Exit code:* Zero if the signal was successfully sent to the container process and non-zero on errors.
123+
Successfully sent does not mean that the signal was successfully received or handled by the container process.
124+
125+
#### Example
126+
127+
```
128+
# in a bundle directory with a process ignores TERM
129+
$ funC start --id sleeper-1 &
130+
$ funC kill sleeper-1
131+
$ echo $?
132+
0
133+
$ funC kill --signal KILL sleeper-1
134+
$ echo $?
135+
0
136+
```
137+
105138
[bundle]: bundle.md
139+
[kill]: runtime.md#kill
140+
[kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html
106141
[posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02
107142
[posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
108143
[posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup
144+
[posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03
109145
[runtime]: glossary.md#runtime
110146
[start]: runtime.md#start
111147
[state]: runtime.md#state

0 commit comments

Comments
 (0)