| blob | 8e59af16be1134c8032b7fc603858dea6f97ac6e |
1 .\" $OpenBSD: script.7,v 1.6 2008/09/19 05:41:29 djm Exp $
2 .\"
3 .\" $NetBSD: script.7,v 1.1 2005/05/07 02:20:34 perry Exp $
4 .\"
5 .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
6 .\" All rights reserved.
7 .\"
8 .\" This document was originally contributed to The NetBSD Foundation
9 .\" by Perry E. Metzger of Metzger, Dowdeswell & Co. LLC.
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
13 .\" are met:
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
24 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 .\" POSSIBILITY OF SUCH DAMAGE.
31 .\"
32 .Dd $Mdocdate: September 19 2008 $
33 .Dt SCRIPT 7
34 .Os
35 .Sh NAME
36 .Nm script
37 .Nd interpreter script execution
38 .Sh DESCRIPTION
39 The system is capable of treating a text file containing commands
40 intended for an interpreter, such as
41 .Xr sh 1
42 or
43 .Xr awk 1 ,
44 as an executable program.
45 .Pp
46 An
47 .Dq interpreter script
48 is a file which has been set executable (see
49 .Xr chmod 2 )
50 and which has a first line of the form:
51 .Pp
52 .D1 Li #! Ar pathname Op Ar argument
53 .Pp
54 The
55 .Sq #!
56 must appear as the first two characters of the file.
57 A space between the
58 .Sq #!
59 and
60 .Ar pathname
61 is optional.
62 At most one
63 .Ar argument
64 may follow
65 .Ar pathname ,
66 and the length of the entire line is limited (see below).
67 .Pp
68 If such a file is executed (such as via the
69 .Xr execve 2
70 system call), the interpreter specified by the
71 .Ar pathname
72 is executed by the system.
73 (The
74 .Ar pathname
75 is executed without regard to the
76 .Ev PATH
77 variable, so in general
78 .Ar pathname
79 should be an absolute path.)
80 .Pp
81 The arguments passed to the interpreter will be as follows.
82 .Va argv[0]
83 will be the path to the interpreter itself, as specified on the first
84 line of the script.
85 If there is an
86 .Ar argument
87 following
88 .Ar pathname
89 on the first line of the script, it will be passed as
90 .Va argv[1] .
91 The subsequent elements of
92 .Va argv
93 will be the path to the interpreter script file itself (i.e. the
94 original
95 .Va argv[0] )
96 followed by any further arguments passed when
97 .Xr execve 2
98 was invoked to execute the script file.
99 .Pp
100 By convention, it is expected that an interpreter will open the script
101 file passed as an argument and process the commands within it.
102 Typical interpreters treat
103 .Sq #
104 as a comment character, and thus will ignore the initial line of the script
105 because it begins
106 .Sq #! ,
107 but there is no requirement for this per se.
108 .Pp
109 On
110 .Ox ,
111 the length of the interpreter line following the
112 .Sq #!
113 is limited to
114 .Dv MAXINTERP ,
115 as defined in
116 .Aq Pa sys/param.h .
117 Other operating systems impose different limits on the length of
118 the
119 .Sq #!
120 line (see below).
121 .Pp
122 Note that the interpreter may not itself be an interpreter script.
123 If
124 .Ar pathname
125 does not point to an executable binary, execution of the interpreter
126 script will fail.
127 .Ss Trampolines and Portable Scripts
128 Different operating systems often have interpreters located in
129 different locations, and the kernel executes the passed interpreter
130 without regard to the setting of environment variables such as
131 .Ev PATH .
132 This makes it somewhat challenging to set the
133 .Sq #!
134 line of a script so that it will run identically on different systems.
135 .Pp
136 Since the
137 .Xr env 1
138 utility executes a command passed to it on its command line, it is
139 often used as a
140 .Dq trampoline
141 to render scripts portable.
142 If the leading line of a script reads
143 .Pp
144 .Dl #! /usr/bin/env interp
145 .Pp
146 then the
147 .Xr env 1
148 command will execute the
149 .Dq interp
150 command it finds in its
151 .Ev PATH ,
152 passing on to it all subsequent arguments with which it itself was called.
153 Since
154 .Pa /usr/bin/env
155 is found on almost all
156 .Tn POSIX
157 style systems, this trick is frequently exploited by authors who need
158 a script to execute without change on multiple systems.
159 .Ss Historical Note: Scripts without `#!'
160 Shell scripts predate the invention of the
161 .Sq #!
162 convention, which is implemented in the kernel.
163 In the days of
164 .At v7 ,
165 there was only one interpreter used on the system,
166 .Pa /bin/sh ,
167 and the shell treated any file that failed to execute with an
168 .Er ENOEXEC
169 error
170 (see
171 .Xr intro 2 )
172 as a shell script.
173 .Pp
174 Most shells (such as
175 .Xr sh 1 )
176 and certain other facilities (including
177 .Xr execlp 3
178 and
179 .Xr execvp 3
180 but not other types of
181 .Xr exec 3
182 calls) still pass
183 interpreter scripts that do not include the
184 .Sq #!
185 (and thus fail to execute with
186 .Er ENOEXEC )
187 to
188 .Pa /bin/sh .
189 .Pp
190 As this behavior is implemented outside the kernel, there is no
191 mechanism that forces it to be respected by all programs that execute
192 other programs.
193 It is thus not completely reliable.
194 It is therefore important to always include
195 .Pp
196 .Dl #!/bin/sh
197 .Pp
198 in front of Bourne shell scripts, and to treat the traditional
199 behavior as obsolete.
200 .Sh EXAMPLES
201 Suppose that an executable binary exists in
202 .Pa /bin/interp
203 and that the file
204 .Pa /tmp/script
205 contains:
206 .Bd -literal -offset indent
207 #!/bin/interp -arg
209 [...]
210 .Ed
211 .Pp
212 and that
213 .Pa /tmp/script
214 is set mode 755.
215 .Pp
216 Executing
217 .Pp
218 .Dl $ /tmp/script one two three
219 .Pp
220 at the shell will result in
221 .Pa /bin/interp
222 being executed, receiving the following arguments in
223 .Va argv
224 (numbered from 0):
225 .Bd -ragged -offset indent
226 .Qq /bin/interp ,
227 .Qq "-arg" ,
228 .Qq /tmp/script ,
229 .Qq one ,
230 .Qq two ,
231 .Qq three
232 .Ed
233 .Ss Portability Note: Multiple arguments
234 The behavior of multiple arguments on the
235 .Sq #!
236 line is highly non-portable between different systems.
237 In general, only one argument can be assumed to work consistently.
238 .Pp
239 Consider the following variation on the previous example.
240 Suppose that an executable binary exists in
241 .Pa /bin/interp
242 and that the file
243 .Pa /tmp/script
244 contains:
245 .Bd -literal -offset indent
246 #!/bin/interp -x -y
248 [...]
249 .Ed
250 .Pp
251 and that
252 .Pa /tmp/script
253 is set mode 755.
254 .Pp
255 Executing
256 .Pp
257 .Dl $ /tmp/script one two three
258 .Pp
259 at the shell will result in
260 .Pa /bin/interp
261 being executed, receiving the following arguments in
262 .Va argv
263 (numbered from 0):
264 .Bd -ragged -offset indent
265 .Qq /bin/interp ,
266 .Qq "-x -y" ,
267 .Qq /tmp/script ,
268 .Qq one ,
269 .Qq two ,
270 .Qq three
271 .Ed
272 .Pp
273 Note that
274 .Qq "-x -y"
275 will be passed on
276 .Ox
277 as a single argument.
278 .Pp
279 Although most
280 .Tn POSIX
281 style operating systems will pass only one
282 .Ar argument ,
283 the behavior when multiple arguments are included is not
284 consistent between platforms.
285 Some, such as
286 .Ox ,
287 will concatenate multiple arguments into a single argument (as above),
288 some will truncate them, and at least one will pass them as multiple
289 arguments.
290 .Pp
291 The
292 .Ox
293 behavior is common but not universal.
294 Sun's
295 .Tn Solaris
296 would present the above argument as
297 .Qq -x ,
298 dropping the
299 .Qq " -y"
300 entirely.
301 Perhaps uniquely, recent versions of Apple's
302 .Tn OS X
303 will actually pass multiple arguments properly, i.e.:
304 .Bd -ragged -offset indent
305 .Qq /bin/interp ,
306 .Qq -x ,
307 .Qq -y ,
308 .Qq /tmp/script ,
309 .Qq one ,
310 .Qq two ,
311 .Qq three
312 .Ed
313 .Pp
314 The behavior of the system in the face of multiple arguments is thus
315 not currently standardized, should not be relied on, and may be
316 changed in future releases.
317 In general, pass at most one argument, and do not rely on multiple
318 arguments being concatenated.
319 .Sh SEE ALSO
320 .Xr awk 1 ,
321 .Xr csh 1 ,
322 .Xr ksh 1 ,
323 .Xr sh 1 ,
324 .Xr chmod 2 ,
325 .Xr execve 2 ,
326 .Xr intro 2 ,
327 .Xr execlp 3 ,
328 .Xr execvp 3
329 .Sh STANDARDS
330 The behavior of interpreter scripts is obliquely referred to, but
331 never actually described in,
332 .St -p1003.1-2004 .
333 .Pp
334 The behavior is partially (but not completely) described in the
335 .St -svid4 .
336 .Pp
337 Although it has never been formally standardized, the behavior
338 described is largely portable across
339 .Tn POSIX
340 style systems, with two significant exceptions: the maximum length of the
341 .Sq #!
342 line, and the behavior if multiple arguments are passed.
343 Please be aware that the behavior in the
344 face of multiple arguments is not consistent across systems.
345 .Sh HISTORY
346 The behavior of the kernel when encountering scripts that start in
347 .Sq #!
348 was not present in
349 .At v7 .
350 A Usenet posting to net.unix by Guy Harris on October 16, 1984 claims
351 that the idea for the
352 .Sq #!
353 behavior was first proposed by Dennis Ritchie but that the first
354 implementation was on
355 .Bx .
356 .Pp
357 Historical manuals (specifically the exec man page) indicate that the
358 behavior was present in
359 .Bx 4
360 at least as early as April, 1981.
361 Information on precisely when it was first implemented, and in which
362 version of
363 .Ux ,
364 is solicited.
365 .Sh CAVEATS
366 Numerous security problems are associated with setuid interpreter
367 scripts.
368 .Pp
369 In addition to the fact that many interpreters (and scripts) are
370 simply not designed to be robust in a setuid context, a race condition
371 exists between the moment that the kernel examines the interpreter
372 script file and the moment that the newly invoked interpreter opens
373 the file itself.
374 .Pp
375 Subtle techniques can be used to subvert even seemingly well written scripts.
376 Scripts executed by Bourne type shells can be subverted in numerous
377 ways, such as by setting the
378 .Ev IFS
379 variable before executing the script.
380 Other interpreters possess their own vulnerabilities.
381 Setting the Set-user-ID on execution (SUID) bit
382 is therefore very dangerous, and should not be done lightly, if at all.