Bug 84701 - execve(2) manual page ".sh" usage exposes implementation detail
Summary: execve(2) manual page ".sh" usage exposes implementation detail
Status: RESOLVED CODE_FIX
Alias: None
Product: Documentation
Classification: Unclassified
Component: man-pages (show other bugs)
Hardware: All Linux
: P1 normal
Assignee: documentation_man-pages@kernel-bugs.osdl.org
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2014-09-17 00:15 UTC by Alex
Modified: 2014-09-23 04:23 UTC (History)
1 user (show)

See Also:
Kernel Version:
Subsystem:
Regression: No
Bisected commit-id:


Attachments

Description Alex 2014-09-17 00:15:55 UTC
This content:

       We can also use these programs to  demonstrate  the  use  of  a  script
       interpreter.   To do this we create a script whose "interpreter" is our
       myecho program:

           $ cat > script.sh
           #! ./myecho script-arg
           ^D
           $ chmod +x script.sh

       We can then use our program to exec the script:

           $ ./execve ./script.sh
           argv[0]: ./myecho
           argv[1]: script-arg
           argv[2]: ./script.sh
           argv[3]: hello
           argv[4]: world

Should probably instead read:

       We can also use these programs to  demonstrate  the  use  of  a  script
       interpreter.   To do this we create a script whose "interpreter" is our
       myecho program:

           $ cat > script
           #!./myecho script-arg
           ^D
           $ chmod +x script

       We can then use our program to exec the script:

           $ ./execve ./script
           argv[0]: ./myecho
           argv[1]: script-arg
           argv[2]: ./script
           argv[3]: hello
           argv[4]: world

Rationale:

1) Command name extensions considered harmful: Adding ".sh", or any other unneeded extension, unnecessarily duplicates meta information already present in the interpreter directive, exposing an implementation detail that then ends up explicitly part of other programs running this one.  Later, when such a script is replaced with a new version in Python, C, etc., the useless ".sh" has to be retained to avoid breaking those other programs' calls to this one, and now has a stark antifunction of lying about the script's content and occasionally causing admins to run undefined experiments as root (like "bash  -x ./reallyperlscript.sh"). Such extensions, while fine in DOS which ignores extensions explicitly, is a serious flaw in Unix-targeted script writing.  Canonical documentation from the Linux manual should not support such a flawed idiom - recommending against it would be preferred.

A more extensive rant against them can be found at:
http://www.talisman.org/~erlkonig/documents/commandname-extensions-considered-harmful

2) The space after "#!" in the interpreter directive is minor - and the kernel's fs/binfmt_script.c specifically allows for it -  but versions of unix have length limits from ~30 characters to linux's 127 or so (if that number's correct) so the space does have a cost.  Most scripts I've seen lack that space, and there's no real reason to encourage it.
Comment 1 Michael Kerrisk 2014-09-23 04:23:32 UTC
Alex, thanks for the detailed report. I've applied the patch below.

Cheers,

Michael

diff --git a/man2/execve.2 b/man2/execve.2
index 0b06974..dfa933b 100644
--- a/man2/execve.2
+++ b/man2/execve.2
@@ -729,10 +729,10 @@ program:
 
 .in +4n
 .nf
-.RB "$" " cat > script.sh"
-.B #! ./myecho script-arg
+.RB "$" " cat > script"
+.B #!./myecho script-arg
 .B ^D
-.RB "$" " chmod +x script.sh"
+.RB "$" " chmod +x script"
 .fi
 .in
 
@@ -740,10 +740,10 @@ We can then use our program to exec the script:
 
 .in +4n
 .nf
-.RB "$" " ./execve ./script.sh"
+.RB "$" " ./execve ./script"
 argv[0]: ./myecho
 argv[1]: script-arg
-argv[2]: ./script.sh
+argv[2]: ./script
 argv[3]: hello
 argv[4]: world
 .fi

Note You need to log in before you can comment on or make changes to this bug.