podman unshare keep exit code

In case the command inside the podman unshare env failed podman unshare
always exits with 125 and prints `Error: exit status 125`. This is a
bad user experience and makes it difficult to use in scripts which could
expect certain exit codes.
This commit makes sure podman unshare uses the same exit code as the
command and does not print the useless `exit status X` message.

Also to match podman run/exec it should return 126 for EPERM
and 127 for ENOENT.

Signed-off-by: Paul Holzinger <pholzing@redhat.com>

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/source/markdown/podman-unshare.1.md b/docs/source/markdown/podman-unshare.1.md
index 2e7adfd34..72821b6e5 100644
--- a/docs/source/markdown/podman-unshare.1.md
+++ b/docs/source/markdown/podman-unshare.1.md
@@ -37,6 +37,35 @@ connect to a rootless container via IP address (CNI networking). This is otherwi
 not possible from the host network namespace.
 _Note: Using this option with more than one unshare session can have unexpected results._
 
+## Exit Codes
+
+The exit code from `podman unshare` gives information about why the container
+failed to run or why it exited.  When `podman unshare` commands exit with a non-zero code,
+the exit codes follow the `chroot` standard, see below:
+
+  **125** The error is with podman **_itself_**
+
+    $ podman unshare --foo; echo $?
+    Error: unknown flag: --foo
+    125
+
+  **126** Executing a _contained command_ and the _command_ cannot be invoked
+
+    $ podman unshare /etc; echo $?
+    Error: fork/exec /etc: permission denied
+    126
+
+  **127** Executing a _contained command_ and the _command_ cannot be found
+
+    $ podman run busybox foo; echo $?
+    Error: fork/exec /usr/bin/bogus: no such file or directory
+    127
+
+  **Exit code** _contained command_ exit code
+
+    $ podman run busybox /bin/sh -c 'exit 3'; echo $?
+    3
+
 ## EXAMPLE
 
 ```