From 911ceb823a688396dd874cd763d0fa887cb2722c Mon Sep 17 00:00:00 2001 From: Ed Santiago <santiago@redhat.com> Date: Wed, 14 Sep 2022 15:12:32 -0600 Subject: Man pages: Refactor common options: --sig-proxy Unusually, I discarded the podman-run version and went with the one common to attach and start. (The defaults are left out of the common file, because 'start' is different by necessity). Please review extra-carefully to make sure the new wording applies to podman-run, in particular the "non-TTY mode" words. Signed-off-by: Ed Santiago <santiago@redhat.com> --- docs/source/markdown/.gitignore | 1 + docs/source/markdown/options/sig-proxy.md | 3 ++ docs/source/markdown/podman-attach.1.md | 58 ------------------------------ docs/source/markdown/podman-attach.1.md.in | 57 +++++++++++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 4 +-- docs/source/markdown/podman-start.1.md.in | 4 +-- 6 files changed, 65 insertions(+), 62 deletions(-) create mode 100644 docs/source/markdown/options/sig-proxy.md delete mode 100644 docs/source/markdown/podman-attach.1.md create mode 100644 docs/source/markdown/podman-attach.1.md.in (limited to 'docs') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index af4c5360b..57a64e1c1 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -1,3 +1,4 @@ +podman-attach.1.md podman-auto-update.1.md podman-build.1.md podman-container-clone.1.md diff --git a/docs/source/markdown/options/sig-proxy.md b/docs/source/markdown/options/sig-proxy.md new file mode 100644 index 000000000..bb940aed3 --- /dev/null +++ b/docs/source/markdown/options/sig-proxy.md @@ -0,0 +1,3 @@ +#### **--sig-proxy** + +Proxy received signals to the container process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md deleted file mode 100644 index c073fccf8..000000000 --- a/docs/source/markdown/podman-attach.1.md +++ /dev/null @@ -1,58 +0,0 @@ -% podman-attach 1 - -## NAME -podman\-attach - Attach to a running container - -## SYNOPSIS -**podman attach** [*options*] *container* - -**podman container attach** [*options*] *container* - -## DESCRIPTION -**podman attach** attaches to a running *container* using the *container's name* or *ID*, to either view its ongoing output or to control it interactively.\ -The *container* can be detached from (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** OPTION, or specifying it in the `containers.conf` file: see **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. - -## OPTIONS -#### **--detach-keys**=**sequence** - -Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature.\ -The default is `ctrl-p,ctrl-q`. - -#### **--latest**, **-l** - -Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\ -The default is **false**.\ -*IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.* - -#### **--no-stdin** - -Do not attach STDIN. The default is **false**. - -#### **--sig-proxy** - -Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.\ -The default is **true**. - -## EXAMPLES -Attach to a container called "foobar". -``` -$ podman attach foobar -``` - -Attach to the latest created container. -``` -$ podman attach --latest -``` - -Attach to a container that start with the ID "1234". -``` -$ podman attach 1234 -``` - -Attach to a container without attaching STDIN. -``` -$ podman attach --no-stdin foobar -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-exec(1)](podman-exec.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** diff --git a/docs/source/markdown/podman-attach.1.md.in b/docs/source/markdown/podman-attach.1.md.in new file mode 100644 index 000000000..427f764dc --- /dev/null +++ b/docs/source/markdown/podman-attach.1.md.in @@ -0,0 +1,57 @@ +% podman-attach 1 + +## NAME +podman\-attach - Attach to a running container + +## SYNOPSIS +**podman attach** [*options*] *container* + +**podman container attach** [*options*] *container* + +## DESCRIPTION +**podman attach** attaches to a running *container* using the *container's name* or *ID*, to either view its ongoing output or to control it interactively.\ +The *container* can be detached from (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** OPTION, or specifying it in the `containers.conf` file: see **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. + +## OPTIONS +#### **--detach-keys**=**sequence** + +Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature.\ +The default is `ctrl-p,ctrl-q`. + +#### **--latest**, **-l** + +Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.* + +#### **--no-stdin** + +Do not attach STDIN. The default is **false**. + +@@option sig-proxy + +The default is **true**. + +## EXAMPLES +Attach to a container called "foobar". +``` +$ podman attach foobar +``` + +Attach to the latest created container. +``` +$ podman attach --latest +``` + +Attach to a container that start with the ID "1234". +``` +$ podman attach 1234 +``` + +Attach to a container without attaching STDIN. +``` +$ podman attach --no-stdin foobar +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-exec(1)](podman-exec.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 2109a0e33..1259f0e37 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -439,9 +439,9 @@ Note: Labeling can be disabled for all containers by setting **label=false** in @@option shm-size -#### **--sig-proxy** +@@option sig-proxy -Sets whether the signals sent to the **podman run** command are proxied to the container process. SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is **true**. +The default is **true**. @@option stop-signal diff --git a/docs/source/markdown/podman-start.1.md.in b/docs/source/markdown/podman-start.1.md.in index 6fa41018b..a1ccc4120 100644 --- a/docs/source/markdown/podman-start.1.md.in +++ b/docs/source/markdown/podman-start.1.md.in @@ -60,9 +60,9 @@ Valid filters are listed below: Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--sig-proxy** +@@option sig-proxy -Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise. +The default is **true** when attaching, **false** otherwise. ## EXAMPLE -- cgit v1.2.3-54-g00ecf