The system is capable of treating a text file containing commands intended for an interpreter, such as
sh(1) or
awk(1), as an executable program.
An “interpreter script” is a file which has been set executable (see
chmod(2)) and which has a first line of the form:
#! pathname [argument]
The “#!” must appear as the first two characters of the file. A space between the “#!” and
pathname is optional. At most one
argument may follow
pathname, and the length of the entire line is limited (see below).
If such a file is executed (such as via the
execve(2) system call), the interpreter specified by the
pathname is executed by the system. (The
pathname is executed without regard to the
PATH variable, so in general
pathname should be an absolute path.)
The arguments passed to the interpreter will be as follows.
argv[0] will be the path to the interpreter itself, as specified on the first line of the script. If there is an
argument following
pathname on the first line of the script, it will be passed as
argv[1]. The subsequent elements of
argv will be the path to the interpreter script file itself (i.e. the original
argv[0]) followed by any further arguments passed when
execve(2) was invoked to execute the script file.
By convention, it is expected that an interpreter will open the script file passed as an argument and process the commands within it. Typical interpreters treat ‘#' as a comment character, and thus will ignore the initial line of the script because it begins “#!”, but there is no requirement for this per se.
On
NetBSD, the length of the “#!” line, excluding the “#!” itself, is limited to
PATH_MAX (as defined in
<limits.h>). Other operating systems impose much smaller limits on the length of the “#!” line (see below).
Note that the interpreter may not itself be an interpreter script. If
pathname does not point to an executable binary, execution of the interpreter script will fail.
Trampolines and Portable Scripts
Different operating systems often have interpreters located in different locations, and the kernel executes the passed interpreter without regard to the setting of environment variables such as
PATH. This makes it somewhat challenging to set the “#!” line of a script so that it will run identically on different systems.
Since the
env(1) utility executes a command passed to it on its command line, it is often used as a “trampoline” to render scripts portable. If the leading line of a script reads
#! /usr/bin/env interp
then the
env(1) command will execute the “interp” command it finds in its
PATH, passing on to it all subsequent arguments with which it itself was called. Since
/usr/bin/env is found on almost all POSIX style systems, this trick is frequently exploited by authors who need a script to execute without change on multiple systems.
Historical Note: Scripts without Dq #!
Shell scripts predate the invention of the “#!” convention, which is implemented in the kernel. In the days of Version 7 AT&T UNIX, there was only one interpreter used on the system,
/bin/sh, and the shell treated any file that failed to execute with an
ENOEXEC error (see
intro(2)) as a shell script.
Most shells (such as
sh(1)) and certain other facilities (including
execlp(3) and
execvp(3) but not other types of
exec(3) calls) still pass interpreter scripts that do not include the “#!” (and thus fail to execute with
ENOEXEC) to
/bin/sh.
As this behavior is implemented outside the kernel, there is no mechanism that forces it to be respected by all programs that execute other programs. It is thus not completely reliable. It is therefore important to always include
#!/bin/sh
in front of Bourne shell scripts, and to treat the traditional behavior as obsolete.