Annotation of src/lib/libc/gen/exec.3, Revision 1.29
1.29 ! wiz 1: .\" $NetBSD: exec.3,v 1.28 2017/09/17 11:45:10 abhinav Exp $
1.5 cgd 2: .\"
3: .\" Copyright (c) 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.18 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.5 cgd 30: .\" @(#)exec.3 8.3 (Berkeley) 1/24/94
1.1 cgd 31: .\"
1.23 christos 32: .Dd September 26, 2014
1.1 cgd 33: .Dt EXEC 3
34: .Os
35: .Sh NAME
36: .Nm execl ,
37: .Nm execlp ,
1.28 abhinav 38: .Nm execlpe ,
1.1 cgd 39: .Nm execle ,
40: .Nm exect ,
41: .Nm execv ,
1.28 abhinav 42: .Nm execvp ,
43: .Nm execvpe
1.1 cgd 44: .Nd execute a file
1.9 perry 45: .Sh LIBRARY
46: .Lb libc
1.1 cgd 47: .Sh SYNOPSIS
1.17 wiz 48: .In unistd.h
1.1 cgd 49: .Vt extern char **environ;
50: .Ft int
51: .Fn execl "const char *path" "const char *arg" ...
52: .Ft int
53: .Fn execlp "const char *file" "const char *arg" ...
54: .Ft int
1.23 christos 55: .Fn execlpe "const char *path" "const char *arg" ... "char *const envp[]"
56: .Ft int
1.1 cgd 57: .Fn execle "const char *path" "const char *arg" ... "char *const envp[]"
58: .Ft int
1.5 cgd 59: .Fn exect "const char *path" "char *const argv[]" "char *const envp[]"
1.1 cgd 60: .Ft int
61: .Fn execv "const char *path" "char *const argv[]"
62: .Ft int
63: .Fn execvp "const char *file" "char *const argv[]"
1.23 christos 64: .Ft int
1.25 wiz 65: .Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]"
1.1 cgd 66: .Sh DESCRIPTION
67: The
1.22 abs 68: .Fn exec
1.1 cgd 69: family of functions replaces the current process image with a
70: new process image.
71: The functions described in this manual page are front-ends for the function
72: .Xr execve 2 .
73: (See the manual page for
1.10 fair 74: .Xr execve 2
1.19 perry 75: for detailed information about the replacement of the current process.
76: The
77: .Xr script 7
78: manual page provides detailed information about the execution of
79: interpreter scripts.)
1.1 cgd 80: .Pp
81: The initial argument for these functions is the pathname of a file which
82: is to be executed.
83: .Pp
84: The
85: .Fa "const char *arg"
86: and subsequent ellipses in the
87: .Fn execl ,
88: .Fn execlp ,
1.23 christos 89: .Fn execlpe ,
1.1 cgd 90: and
91: .Fn execle
92: functions can be thought of as
93: .Em arg0 ,
94: .Em arg1 ,
95: \&...,
96: .Em argn .
1.26 wiz 97: Together they describe a list of one or more pointers to NUL-terminated
1.1 cgd 98: strings that represent the argument list available to the executed program.
99: The first argument, by convention, should point to the file name associated
100: with the file being executed.
101: The list of arguments
102: .Em must
103: be terminated by a
104: .Dv NULL
105: pointer.
106: .Pp
107: The
108: .Fn exect ,
109: .Fn execv ,
1.23 christos 110: .Fn execvp ,
1.1 cgd 111: and
1.23 christos 112: .Fn execvpe
1.26 wiz 113: functions provide an array of pointers to NUL-terminated strings that
1.1 cgd 114: represent the argument list available to the new program.
115: The first argument, by convention, should point to the file name associated
1.11 groo 116: with the file being executed.
1.1 cgd 117: The array of pointers
118: .Sy must
119: be terminated by a
120: .Dv NULL
121: pointer.
122: .Pp
123: The
1.24 christos 124: .Fn execle ,
1.25 wiz 125: .Fn execlpe ,
1.26 wiz 126: .Fn exect ,
1.1 cgd 127: and
1.26 wiz 128: .Fn execvpe
1.1 cgd 129: functions also specify the environment of the executed process by following
130: the
131: .Dv NULL
132: pointer that terminates the list of arguments in the parameter list
133: or the pointer to the argv array with an additional parameter.
1.26 wiz 134: This additional parameter is an array of pointers to NUL-terminated strings
1.1 cgd 135: and
136: .Em must
137: be terminated by a
138: .Dv NULL
139: pointer.
140: The other functions take the environment for the new process image from the
141: external variable
142: .Va environ
143: in the current process.
144: .Pp
145: Some of these functions have special semantics.
146: .Pp
147: The functions
1.23 christos 148: .Fn execlp ,
149: .Fn execlpe ,
1.25 wiz 150: .Fn execvp ,
1.1 cgd 151: and
1.23 christos 152: .Fn execvpe
1.1 cgd 153: will duplicate the actions of the shell in searching for an executable file
154: if the specified file name does not contain a slash
1.12 wiz 155: .Dq Li \&/
1.1 cgd 156: character.
1.12 wiz 157: The search path is the path specified in the environment by the
158: .Ev PATH
1.1 cgd 159: variable.
1.14 yamt 160: If this variable isn't specified,
1.16 wiz 161: .Va _PATH_DEFPATH
162: from
1.21 joerg 163: .In paths.h
1.14 yamt 164: is used instead, its value being:
1.16 wiz 165: .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin .
1.4 jtc 166: In addition, certain errors are treated specially.
1.1 cgd 167: .Pp
168: If permission is denied for a file (the attempted
1.10 fair 169: .Xr execve 2
1.1 cgd 170: returned
171: .Er EACCES ) ,
172: these functions will continue searching the rest of
173: the search path.
174: If no other file is found, however, they will return with the global variable
175: .Va errno
176: set to
177: .Er EACCES .
178: .Pp
179: If the header of a file isn't recognized (the attempted
1.10 fair 180: .Xr execve 2
1.1 cgd 181: returned
182: .Er ENOEXEC ) ,
183: these functions will execute the shell with the path of
184: the file as its first argument.
185: (If this attempt fails, no further searching is done.)
186: .Pp
187: If the file is currently busy (the attempted
1.10 fair 188: .Xr execve 2
1.1 cgd 189: returned
190: .Er ETXTBUSY ) ,
191: these functions will sleep for several seconds,
192: periodically re-attempting to execute the file.
193: .Pp
194: The function
195: .Fn exect
196: executes a file with the program tracing facilities enabled (see
197: .Xr ptrace 2 ) .
198: .Sh RETURN VALUES
199: If any of the
1.22 abs 200: .Fn exec
1.1 cgd 201: functions returns, an error will have occurred.
202: The return value is \-1, and the global variable
203: .Va errno
204: will be set to indicate the error.
205: .Sh FILES
1.3 jtc 206: .Bl -tag -width /bin/sh -compact
1.1 cgd 207: .It Pa /bin/sh
208: The shell.
209: .El
210: .Sh COMPATIBILITY
211: Historically, the default path for the
212: .Fn execlp
1.23 christos 213: .Fn execlpe ,
214: .Fn execvp ,
1.1 cgd 215: and
1.23 christos 216: .Fn execvpe
1.1 cgd 217: functions was
218: .Dq Pa :/bin:/usr/bin .
1.15 yamt 219: This was changed to improve security and behaviour.
1.1 cgd 220: .Pp
221: The behavior of
1.23 christos 222: .Fn execlp ,
223: .Fn execlpe ,
224: .Fn execvp ,
1.1 cgd 225: and
1.23 christos 226: .Fn execvpe
1.1 cgd 227: when errors occur while attempting to execute the file is historic
228: practice, but has not traditionally been documented and is not specified
1.29 ! wiz 229: by the POSIX standard.
1.1 cgd 230: .Pp
231: Traditionally, the functions
1.23 christos 232: .Fn execlp ,
233: .Fn execlpe ,
234: .Fn execvp ,
1.1 cgd 235: and
1.23 christos 236: .Fn execvpe
1.1 cgd 237: ignored all errors except for the ones described above and
238: .Er ENOMEM
239: and
240: .Er E2BIG ,
241: upon which they returned.
242: They now return if any error other than the ones described above occurs.
1.22 abs 243: .Sh ERRORS
244: .Fn execl ,
245: .Fn execle ,
1.23 christos 246: .Fn execlp ,
247: .Fn execlpe ,
1.25 wiz 248: .Fn execvp ,
1.22 abs 249: and
1.23 christos 250: .Fn execvpe
1.22 abs 251: may fail and set
252: .Va errno
253: for any of the errors specified for the library functions
254: .Xr execve 2
255: and
256: .Xr malloc 3 .
257: .Pp
258: .Fn exect
259: and
260: .Fn execv
261: may fail and set
262: .Va errno
263: for any of the errors specified for the library function
264: .Xr execve 2 .
265: .Sh SEE ALSO
266: .Xr sh 1 ,
267: .Xr execve 2 ,
268: .Xr fork 2 ,
269: .Xr ptrace 2 ,
270: .Xr environ 7 ,
271: .Xr script 7
1.1 cgd 272: .Sh STANDARDS
1.8 enami 273: .Fn execl ,
1.1 cgd 274: .Fn execv ,
275: .Fn execle ,
1.25 wiz 276: .Fn execlp ,
1.1 cgd 277: and
278: .Fn execvp
279: conform to
1.6 kleink 280: .St -p1003.1-90 .
1.23 christos 281: .Pp
282: The
283: .Fn execlpe
284: function appeared first in QNX and the
285: .Fn execvpe
1.25 wiz 286: function exists on both
1.27 rin 287: .Nx
1.23 christos 288: and QNX.
CVSweb <webmaster@jp.NetBSD.org>