Merge pull request #24431 from ntrrgc/2024-10-31-doc-interactive

doc: explain --interactive in more detail

cmd/podman/common/create.go

@@ -279,7 +279,7 @@ func DefineCreateFlags(cmd *cobra.Command, cf *entities.ContainerCreateOptions,
 		createFlags.BoolVarP(
 			&cf.Interactive,
 			"interactive", "i", false,
-			"Keep STDIN open even if not attached",
+			"Make STDIN available to the contained process",
 		)
 		ipcFlagName := "ipc"
 		createFlags.String(

cmd/podman/containers/exec.go

@@ -71,7 +71,7 @@ func execFlags(cmd *cobra.Command) {
 	flags.StringArrayVar(&envFile, envFileFlagName, []string{}, "Read in a file of environment variables")
 	_ = cmd.RegisterFlagCompletionFunc(envFileFlagName, completion.AutocompleteDefault)
 
-	flags.BoolVarP(&execOpts.Interactive, "interactive", "i", false, "Keep STDIN open even if not attached")
+	flags.BoolVarP(&execOpts.Interactive, "interactive", "i", false, "Make STDIN available to the contained process")
 	flags.BoolVar(&execOpts.Privileged, "privileged", podmanConfig.ContainersConfDefaultsRO.Containers.Privileged, "Give the process extended Linux capabilities inside the container.  The default is false")
 	flags.BoolVarP(&execOpts.Tty, "tty", "t", false, "Allocate a pseudo-TTY. The default is false")
 

cmd/podman/containers/start.go

@@ -55,7 +55,7 @@ func startFlags(cmd *cobra.Command) {
 	flags.StringVar(&startOptions.DetachKeys, detachKeysFlagName, containerConfig.DetachKeys(), "Select the key sequence for detaching a container. Format is a single character `[a-Z]` or a comma separated sequence of `ctrl-<value>`, where `<value>` is one of: `a-z`, `@`, `^`, `[`, `\\`, `]`, `^` or `_`")
 	_ = cmd.RegisterFlagCompletionFunc(detachKeysFlagName, common.AutocompleteDetachKeys)
 
-	flags.BoolVarP(&startOptions.Interactive, "interactive", "i", false, "Keep STDIN open even if not attached")
+	flags.BoolVarP(&startOptions.Interactive, "interactive", "i", false, "Make STDIN available to the contained process")
 	flags.BoolVar(&startOptions.SigProxy, "sig-proxy", false, "Proxy received signals to the process (default true if attaching, false otherwise)")
 
 	filterFlagName := "filter"

docs/source/markdown/options/interactive.md

@@ -4,4 +4,8 @@
 ####> are applicable to all of those.
 #### **--interactive**, **-i**
 
-When set to **true**, keep stdin open even if not attached. The default is **false**.
+When set to **true**, make stdin available to the contained process. If **false**, the stdin of the contained process is empty and immediately closed.
+
+If attached, stdin is piped to the contained process. If detached, reading stdin will block until later attached.
+
+**Caveat:** Podman will consume input from stdin as soon as it becomes available, even if the contained process doesn't request it.