twice revised patch: zshmisc(1) clarify non-successful exit statuses

twice revised patch: zshmisc(1) clarify non-successful exit statuses

[zeurkous]

#?patch
#
# This twice revised patch adds, to the zshmisc(1) manual page, clarity
# about the exit status on exec failure.
#
# As me said before: me doesn't use yodl. However, in this revision:
# me believes that me has fixed the use of sitem(). (Don't shoot me if
# me got it wrong again.)
#
# One person branded me earlier wording of a sentence ``ungrammatical'';
# while me doesn't necessarily agree, me sees no harm in the proposed
# change and this has hence been incorporated.
#
# Hope this is even more useful (it is to me),
#
#         --zeurkous, Thu Jul  8 20:43:33 UTC 2021.
#
--- Doc/Zsh/..v/5.8/exec.yo	Mon Dec  4 14:09:35 2017
+++ Doc/Zsh/exec.yo	Thu Jul  8 20:13:50 2021
@@ -14,10 +14,21 @@
 
 vindex(path, use of)
 Otherwise, the shell searches each element of tt($path) for a
-directory containing an executable file by that name.  If the
-search is unsuccessful, the shell prints an error message and returns
-a nonzero exit status.
+directory containing an executable file by that name.
 
+If execution fails: an error message is printed, and one of the
+following values is returned.
+
+startsitem()
+sitem(127)(The search was unsuccessful.  The error message is
+`tt(command not found:) var(cmd)'.)
+sitem(126)(The executable file has insufficient permissions, is a
+directory or special file, or is not a script and is in a format
+unrecognized by the operating system.  The exact conditions and error
+message are operating system-dependent; see
+manref(execve)(2).)
+endsitem()
+
 If execution fails because the file is not in executable format,
 and the file is not a directory, it is assumed to be a shell
 script.  tt(/bin/sh) is spawned to execute it.  If the program
@@ -29,10 +40,6 @@
 If no external command is found but a function tt(command_not_found_handler)
 exists the shell executes this function with all
 command line arguments.  The return status of the function becomes the
-status of the command.  If the function wishes to mimic the
-behaviour of the shell when the command is not found, it should
-print the message `tt(command not found:) var(cmd)' to standard error
-and return status 127.  Note that the handler is executed in a
+status of the command.  Note that the handler is executed in a
 subshell forked to execute an external command, hence changes to
 directories, shell parameters, etc. have no effect on the main shell.
-

Re: twice revised patch: zshmisc(1) clarify non-successful exit statuses

[Lawrence Velázquez]

On Thu, Jul 8, 2021, at 4:53 PM, zeurkous@volny.cz wrote:
> # One person branded me earlier wording of a sentence ``ungrammatical'';
> # while me doesn't necessarily agree, me sees no harm in the proposed
> # change and this has hence been incorporated.

Thanks, I appreciate it.

> --- Doc/Zsh/..v/5.8/exec.yo	Mon Dec  4 14:09:35 2017
> +++ Doc/Zsh/exec.yo	Thu Jul  8 20:13:50 2021
> @@ -14,10 +14,21 @@
>  
>  vindex(path, use of)
>  Otherwise, the shell searches each element of tt($path) for a
> -directory containing an executable file by that name.  If the
> -search is unsuccessful, the shell prints an error message and returns
> -a nonzero exit status.
> +directory containing an executable file by that name.
>  
> +If execution fails: an error message is printed, and one of the
> +following values is returned.
> +
> +startsitem()
> +sitem(127)(The search was unsuccessful.  The error message is
> +`tt(command not found:) var(cmd)'.)
> +sitem(126)(The executable file has insufficient permissions, is a
> +directory or special file, or is not a script and is in a format
> +unrecognized by the operating system.  The exact conditions and error
> +message are operating system-dependent; see
> +manref(execve)(2).)
> +endsitem()
> +
>  If execution fails because the file is not in executable format,
>  and the file is not a directory, it is assumed to be a shell
>  script.  tt(/bin/sh) is spawned to execute it.  If the program
> @@ -29,10 +40,6 @@
>  If no external command is found but a function tt(command_not_found_handler)
>  exists the shell executes this function with all
>  command line arguments.  The return status of the function becomes the
> -status of the command.  If the function wishes to mimic the
> -behaviour of the shell when the command is not found, it should
> -print the message `tt(command not found:) var(cmd)' to standard error
> -and return status 127.  Note that the handler is executed in a
> +status of the command.  Note that the handler is executed in a
>  subshell forked to execute an external command, hence changes to
>  directories, shell parameters, etc. have no effect on the main shell.
> -

Anyone have further feedback and/or is up for committing this?

-- 
vq

Re: twice revised patch: zshmisc(1) clarify non-successful exit statuses

[Bart Schaefer]

On Sun, Jul 18, 2021 at 3:28 PM Lawrence Velázquez <larryv@zsh.org> wrote:
>
> On Thu, Jul 8, 2021, at 4:53 PM, zeurkous@volny.cz wrote:
> > +sitem(127)(The search was unsuccessful.  The error message is
> > +`tt(command not found:) var(cmd)'.)
> > +sitem(126)(The executable file has insufficient permissions, [...]
>
> Anyone have further feedback and/or is up for committing this?

Assuming everyone agrees that the error numbers are correct, I've put
this on my list of things to commit, if no one else does so first (it
may yet be a little while before I actually reach the point of
committing the several things I'm following).