Merge pull request #3271 from thaJeztah/kill_canonical_signal_name

docker kill: don't set default signal on the client side

cli/command/container/kill.go

@@ -34,7 +34,7 @@ func NewKillCommand(dockerCli command.Cli) *cobra.Command {
 	}
 
 	flags := cmd.Flags()
-	flags.StringVarP(&opts.signal, "signal", "s", "KILL", "Signal to send to the container")
+	flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
 	return cmd
 }
 

docs/reference/commandline/kill.md

@@ -13,7 +13,7 @@ Kill one or more running containers
 
 Options:
       --help            Print usage
-  -s, --signal string   Signal to send to the container (default "KILL")
+  -s, --signal string   Signal to send to the container
 ```
 
 ## Description

man/src/container/kill.md

@@ -1,2 +1,20 @@
-The main process inside each container specified will be sent SIGKILL,
+The `docker kill` subcommand kills one or more containers. The main process
- or any signal specified with option --signal.
+inside the container is sent `SIGKILL` signal (default), or the signal that is
+specified with the `--signal` option. You can reference a container by its
+ID, ID-prefix, or name.
+
+The `--signal` flag sets the system call signal that is sent to the container.
+This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGINT`,
+or an unsigned number that matches a position in the kernel's syscall table,
+for instance `2`.
+
+While the default (`SIGKILL`) signal will terminate the container, the signal
+set through `--signal` may be non-terminal, depending on the container's main
+process. For example, the `SIGHUP` signal in most cases will be non-terminal,
+and the container will continue running after receiving the signal.
+
+> **Note**
+>
+> `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of
+> `/bin/sh -c`, which does not pass signals. This means that the executable is
+> not the container’s PID 1 and does not receive Unix signals.