Bring in a script(7) manual page which describes some details about
authorSascha Wildner <swildner@dragonflybsd.org>
Fri, 21 Dec 2007 22:14:04 +0000 (22:14 +0000)
committerSascha Wildner <swildner@dragonflybsd.org>
Fri, 21 Dec 2007 22:14:04 +0000 (22:14 +0000)
interpreter script execution.

Add references to script(7).

Taken-from: OpenBSD & NetBSD

bin/sh/sh.1
lib/libc/gen/exec.3
lib/libc/sys/execve.2
share/man/man7/Makefile
share/man/man7/script.7 [new file with mode: 0644]

index f54a54c..1cee55a 100644 (file)
@@ -35,7 +35,7 @@
 .\"
 .\"    from: @(#)sh.1  8.6 (Berkeley) 5/4/95
 .\" $FreeBSD: src/bin/sh/sh.1,v 1.124 2006/10/07 16:51:16 stefanf Exp $
-.\" $DragonFly: src/bin/sh/sh.1,v 1.11 2007/12/17 18:38:00 swildner Exp $
+.\" $DragonFly: src/bin/sh/sh.1,v 1.12 2007/12/21 22:14:04 swildner Exp $
 .\"
 .Dd October 7, 2006
 .Dt SH 1
@@ -2252,7 +2252,8 @@ will return the argument.
 .Xr execve 2 ,
 .Xr getrlimit 2 ,
 .Xr umask 2 ,
-.Xr editrc 5
+.Xr editrc 5 ,
+.Xr script 7
 .Sh HISTORY
 A
 .Nm
index 29f55b3..2af717f 100644 (file)
@@ -31,9 +31,9 @@
 .\"
 .\"     @(#)exec.3     8.3 (Berkeley) 1/24/94
 .\" $FreeBSD: src/lib/libc/gen/exec.3,v 1.7.2.8 2003/03/15 15:11:05 trhodes Exp $
-.\" $DragonFly: src/lib/libc/gen/exec.3,v 1.4 2006/05/26 19:39:36 swildner Exp $
+.\" $DragonFly: src/lib/libc/gen/exec.3,v 1.5 2007/12/21 22:14:04 swildner Exp $
 .\"
-.Dd January 24, 1994
+.Dd December 21, 2007
 .Dt EXEC 3
 .Os
 .Sh NAME
@@ -70,7 +70,11 @@ The functions described in this manual page are front-ends for the function
 .Xr execve 2 .
 (See the manual page for
 .Xr execve 2
-for detailed information about the replacement of the current process.)
+for detailed information about the replacement of the current process.
+The
+.Xr script 7
+manual page provides detailed information about the execution of
+interpreter scripts.)
 .Pp
 The initial argument for these functions is the pathname of a file which
 is to be executed.
@@ -289,7 +293,8 @@ for any of the errors specified for the library function
 .Xr fork 2 ,
 .Xr ktrace 2 ,
 .Xr ptrace 2 ,
-.Xr environ 7
+.Xr environ 7 ,
+.Xr script 7
 .Sh STANDARDS
 The
 .Fn execl ,
index 25560b0..c7e0bec 100644 (file)
@@ -31,9 +31,9 @@
 .\"
 .\"     @(#)execve.2   8.5 (Berkeley) 6/1/94
 .\" $FreeBSD: src/lib/libc/sys/execve.2,v 1.16.2.10 2001/12/22 01:21:30 jwd Exp $
-.\" $DragonFly: src/lib/libc/sys/execve.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
+.\" $DragonFly: src/lib/libc/sys/execve.2,v 1.3 2007/12/21 22:14:04 swildner Exp $
 .\"
-.Dd June 1, 1994
+.Dd December 21, 2007
 .Dt EXECVE 2
 .Os
 .Sh NAME
@@ -90,6 +90,9 @@ file becomes the first argument.  The original arguments are shifted over to
 become the subsequent arguments.
 The zeroth argument is set to the specified
 .Em interpreter .
+(See
+.Xr script 7
+for a detailed discussion of interpreter file execution.)
 .Pp
 The argument
 .Fa argv
@@ -274,6 +277,7 @@ of a super-user as well.
 .Xr a.out 5 ,
 .Xr elf 5 ,
 .Xr environ 7 ,
+.Xr script 7 ,
 .Xr mount 8
 .Sh HISTORY
 The
index ad92142..4092660 100644 (file)
@@ -1,6 +1,6 @@
 #      @(#)Makefile    8.1 (Berkeley) 6/5/93
 # $FreeBSD: src/share/man/man7/Makefile,v 1.10.2.7 2002/12/28 19:09:50 dillon Exp $
-# $DragonFly: src/share/man/man7/Makefile,v 1.11 2007/08/18 08:46:32 swildner Exp $
+# $DragonFly: src/share/man/man7/Makefile,v 1.12 2007/12/21 22:14:04 swildner Exp $
 
 #MISSING: eqnchar.7 ms.7 term.7
 MAN=   ascii.7 \
@@ -18,6 +18,7 @@ MAN=  ascii.7 \
        operator.7 \
        pkgsrc.7 \
        release.7 \
+       script.7 \
        security.7 \
        tuning.7 \
        vkernel.7
diff --git a/share/man/man7/script.7 b/share/man/man7/script.7
new file mode 100644 (file)
index 0000000..09c347d
--- /dev/null
@@ -0,0 +1,391 @@
+.\"    $OpenBSD: script.7,v 1.4 2007/05/31 19:19:58 jmc Exp $
+.\"
+.\"    $NetBSD: script.7,v 1.1 2005/05/07 02:20:34 perry Exp $
+.\"    $DragonFly: src/share/man/man7/script.7,v 1.1 2007/12/21 22:14:04 swildner Exp $
+.\"
+.\" Copyright (c) 2005 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This document was originally contributed to The NetBSD Foundation
+.\" by Perry E. Metzger of Metzger, Dowdeswell & Co. LLC.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd December 21, 2007
+.Dt SCRIPT 7
+.Os
+.Sh NAME
+.Nm script
+.Nd interpreter script execution
+.Sh DESCRIPTION
+The system is capable of treating a text file containing commands
+intended for an interpreter, such as
+.Xr sh 1
+or
+.Xr awk 1 ,
+as an executable program.
+.Pp
+An
+.Dq interpreter script
+is a file which has been set executable (see
+.Xr chmod 2 )
+and which has a first line of the form:
+.Pp
+.D1 Li #! Ar pathname Op Ar argument
+.Pp
+The
+.Sq #!
+must appear as the first two characters of the file.
+A space between the
+.Sq #!
+and
+.Ar pathname
+is optional.
+At most one
+.Ar argument
+may follow
+.Ar pathname ,
+and the length of the entire line is limited (see below).
+.Pp
+If such a file is executed (such as via the
+.Xr execve 2
+system call), the interpreter specified by the
+.Ar pathname
+is executed by the system.
+(The
+.Ar pathname
+is executed without regard to the
+.Ev PATH
+variable, so in general
+.Ar pathname
+should be an absolute path.)
+.Pp
+The arguments passed to the interpreter will be as follows.
+.Va argv[0]
+will be the path to the interpreter itself, as specified on the first
+line of the script.
+If there is an
+.Ar argument
+following
+.Ar pathname
+on the first line of the script, it will be passed as
+.Va argv[1] .
+The subsequent elements of
+.Va argv
+will be the path to the interpreter script file itself (i.e. the
+original
+.Va argv[0] )
+followed by any further arguments passed when
+.Xr execve 2
+was invoked to execute the script file.
+.Pp
+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
+.Sq #
+as a comment character, and thus will ignore the initial line of the script
+because it begins
+.Sq #! ,
+but there is no requirement for this per se.
+.Pp
+On
+.Dx ,
+the length of the
+.Sq #!
+line, excluding the
+.Sq #!
+itself, is limited to
+.Dv PATH_MAX
+(as defined in
+.Aq Pa limits.h ) .
+Other operating systems impose different limits on the length of
+the
+.Sq #!
+line (see below).
+.Pp
+Note that the interpreter may not itself be an interpreter script.
+If
+.Ar pathname
+does not point to an executable binary, execution of the interpreter
+script will fail.
+.Ss 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
+.Ev PATH .
+This makes it somewhat challenging to set the
+.Sq #!
+line of a script so that it will run identically on different systems.
+.Pp
+Since the
+.Xr env 1
+utility executes a command passed to it on its command line, it is
+often used as a
+.Dq trampoline
+to render scripts portable.
+If the leading line of a script reads
+.Pp
+.Dl #! /usr/bin/env interp
+.Pp
+then the
+.Xr env 1
+command will execute the
+.Dq interp
+command it finds in its
+.Ev PATH ,
+passing on to it all subsequent arguments with which it itself was called.
+Since
+.Pa /usr/bin/env
+is found on almost all
+.Tn POSIX
+style systems, this trick is frequently exploited by authors who need
+a script to execute without change on multiple systems.
+.Ss Historical Note: Scripts without `#!'
+Shell scripts predate the invention of the
+.Sq #!
+convention, which is implemented in the kernel.
+In the days of
+.At v7 ,
+there was only one interpreter used on the system,
+.Pa /bin/sh ,
+and the shell treated any file that failed to execute with an
+.Er ENOEXEC
+error
+(see
+.Xr intro 2 )
+as a shell script.
+.Pp
+Most shells (such as
+.Xr sh 1 )
+and certain other facilities (including
+.Xr execlp 3
+and
+.Xr execvp 3
+but not other types of
+.Xr exec 3
+calls) still pass
+interpreter scripts that do not include the
+.Sq #!
+(and thus fail to execute with
+.Er ENOEXEC )
+to
+.Pa /bin/sh .
+.Pp
+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
+.Pp
+.Dl #!/bin/sh
+.Pp
+in front of Bourne shell scripts, and to treat the traditional
+behavior as obsolete.
+.Sh EXAMPLES
+Suppose that an executable binary exists in
+.Pa /bin/interp
+and that the file
+.Pa /tmp/script
+contains:
+.Bd -literal -offset indent
+#!/bin/interp -arg
+
+[...]
+.Ed
+.Pp
+and that
+.Pa /tmp/script
+is set mode 755.
+.Pp
+Executing
+.Pp
+.Dl $ /tmp/script one two three
+.Pp
+at the shell will result in
+.Pa /bin/interp
+being executed, receiving the following arguments in
+.Va argv
+(numbered from 0):
+.Bd -ragged -offset indent
+.Qq /bin/interp ,
+.Qq "-arg" ,
+.Qq /tmp/script ,
+.Qq one ,
+.Qq two ,
+.Qq three
+.Ed
+.Ss Portability Note: Multiple arguments
+The behavior of multiple arguments on the
+.Sq #!
+line is highly non-portable between different systems.
+In general, only one argument can be assumed to work consistently.
+.Pp
+Consider the following variation on the previous example.
+Suppose that an executable binary exists in
+.Pa /bin/interp
+and that the file
+.Pa /tmp/script
+contains:
+.Bd -literal -offset indent
+#!/bin/interp -x -y
+
+[...]
+.Ed
+.Pp
+and that
+.Pa /tmp/script
+is set mode 755.
+.Pp
+Executing
+.Pp
+.Dl $ /tmp/script one two three
+.Pp
+at the shell will result in
+.Pa /bin/interp
+being executed, receiving the following arguments in
+.Va argv
+(numbered from 0):
+.Bd -ragged -offset indent
+.Qq /bin/interp ,
+.Qq "-x -y" ,
+.Qq /tmp/script ,
+.Qq one ,
+.Qq two ,
+.Qq three
+.Ed
+.Pp
+Note that
+.Qq "-x -y"
+will be passed on
+.Dx
+as a single argument.
+.Pp
+Although most
+.Tn POSIX
+style operating systems will pass only one
+.Ar argument ,
+the behavior when multiple arguments are included is not
+consistent between platforms.
+Some, such as
+.Dx ,
+will concatenate multiple arguments into a single argument (as above),
+some will truncate them, and at least one will pass them as multiple
+arguments.
+.Pp
+The
+.Dx
+behavior is common but not universal.
+Sun's
+.Tn Solaris
+would present the above argument as
+.Qq -x ,
+dropping the
+.Qq " -y"
+entirely.
+Perhaps uniquely, recent versions of Apple's
+.Tn OS X
+will actually pass multiple arguments properly, i.e.:
+.Bd -ragged -offset indent
+.Qq /bin/interp ,
+.Qq -x ,
+.Qq -y ,
+.Qq /tmp/script ,
+.Qq one ,
+.Qq two ,
+.Qq three
+.Ed
+.Pp
+The behavior of the system in the face of multiple arguments is thus
+not currently standardized, should not be relied on, and may be
+changed in future releases.
+In general, pass at most one argument, and do not rely on multiple
+arguments being concatenated.
+.Sh SEE ALSO
+.Xr awk 1 ,
+.Xr csh 1 ,
+.Xr sh 1 ,
+.Xr chmod 2 ,
+.Xr execve 2 ,
+.Xr intro 2 ,
+.Xr execlp 3 ,
+.Xr execvp 3
+.Sh STANDARDS
+The behavior of interpreter scripts is obliquely referred to, but
+never actually described in,
+.St -p1003.1-2004 .
+.Pp
+The behavior is partially (but not completely) described in the
+.St -svid4 .
+.Pp
+Although it has never been formally standardized, the behavior
+described is largely portable across
+.Tn POSIX
+style systems, with two significant exceptions: the maximum length of the
+.Sq #!
+line, and the behavior if multiple arguments are passed.
+Please be aware that the behavior in the
+face of multiple arguments is not consistent across systems.
+.Sh HISTORY
+The behavior of the kernel when encountering scripts that start in
+.Sq #!
+was not present in
+.At v7 .
+A Usenet posting to net.unix by Guy Harris on October 16, 1984 claims
+that the idea for the
+.Sq #!
+behavior was first proposed by Dennis Ritchie but that the first
+implementation was on
+.Bx .
+.Pp
+Historical manuals (specifically the exec man page) indicate that the
+behavior was present in
+.Bx 4
+at least as early as April, 1981.
+Information on precisely when it was first implemented, and in which
+version of
+.Ux ,
+is solicited.
+.Sh CAVEATS
+Numerous security problems are associated with setuid interpreter
+scripts.
+.Pp
+In addition to the fact that many interpreters (and scripts) are
+simply not designed to be robust in a setuid context, a race condition
+exists between the moment that the kernel examines the interpreter
+script file and the moment that the newly invoked interpreter opens
+the file itself.
+.Pp
+Subtle techniques can be used to subvert even seemingly well written scripts.
+Scripts executed by Bourne type shells can be subverted in numerous
+ways, such as by setting the
+.Ev IFS
+variable before executing the script.
+Other interpreters possess their own vulnerabilities.
+Setting the Set-user-ID on execution (SUID) bit
+is therefore very dangerous, and should not be done lightly, if at all.