Annotation of src/lib/libc/gen/exec.3, Revision 1.18
1.18 ! agc 1: .\" $NetBSD: exec.3,v 1.17 2003/04/16 13:34:36 wiz 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.16 wiz 32: .Dd August 10, 2002
1.1 cgd 33: .Dt EXEC 3
34: .Os
35: .Sh NAME
36: .Nm execl ,
37: .Nm execlp ,
38: .Nm execle ,
39: .Nm exect ,
40: .Nm execv ,
41: .Nm execvp
42: .Nd execute a file
1.9 perry 43: .Sh LIBRARY
44: .Lb libc
1.1 cgd 45: .Sh SYNOPSIS
1.17 wiz 46: .In unistd.h
1.1 cgd 47: .Vt extern char **environ;
48: .Ft int
49: .Fn execl "const char *path" "const char *arg" ...
50: .Ft int
51: .Fn execlp "const char *file" "const char *arg" ...
52: .Ft int
53: .Fn execle "const char *path" "const char *arg" ... "char *const envp[]"
54: .Ft int
1.5 cgd 55: .Fn exect "const char *path" "char *const argv[]" "char *const envp[]"
1.1 cgd 56: .Ft int
57: .Fn execv "const char *path" "char *const argv[]"
58: .Ft int
59: .Fn execvp "const char *file" "char *const argv[]"
60: .Sh DESCRIPTION
61: The
62: .Nm exec
63: family of functions replaces the current process image with a
64: new process image.
65: The functions described in this manual page are front-ends for the function
66: .Xr execve 2 .
67: (See the manual page for
1.10 fair 68: .Xr execve 2
1.1 cgd 69: for detailed information about the replacement of the current process.)
70: .Pp
71: The initial argument for these functions is the pathname of a file which
72: is to be executed.
73: .Pp
74: The
75: .Fa "const char *arg"
76: and subsequent ellipses in the
77: .Fn execl ,
78: .Fn execlp ,
79: and
80: .Fn execle
81: functions can be thought of as
82: .Em arg0 ,
83: .Em arg1 ,
84: \&...,
85: .Em argn .
86: Together they describe a list of one or more pointers to null-terminated
87: strings that represent the argument list available to the executed program.
88: The first argument, by convention, should point to the file name associated
89: with the file being executed.
90: The list of arguments
91: .Em must
92: be terminated by a
93: .Dv NULL
94: pointer.
95: .Pp
96: The
97: .Fn exect ,
98: .Fn execv ,
99: and
100: .Fn execvp
101: functions provide an array of pointers to null-terminated strings that
102: represent the argument list available to the new program.
103: The first argument, by convention, should point to the file name associated
1.11 groo 104: with the file being executed.
1.1 cgd 105: The array of pointers
106: .Sy must
107: be terminated by a
108: .Dv NULL
109: pointer.
110: .Pp
111: The
112: .Fn execle
113: and
114: .Fn exect
115: functions also specify the environment of the executed process by following
116: the
117: .Dv NULL
118: pointer that terminates the list of arguments in the parameter list
119: or the pointer to the argv array with an additional parameter.
120: This additional parameter is an array of pointers to null-terminated strings
121: and
122: .Em must
123: be terminated by a
124: .Dv NULL
125: pointer.
126: The other functions take the environment for the new process image from the
127: external variable
128: .Va environ
129: in the current process.
130: .Pp
131: Some of these functions have special semantics.
132: .Pp
133: The functions
134: .Fn execlp
135: and
136: .Fn execvp
137: will duplicate the actions of the shell in searching for an executable file
138: if the specified file name does not contain a slash
1.12 wiz 139: .Dq Li \&/
1.1 cgd 140: character.
1.12 wiz 141: The search path is the path specified in the environment by the
142: .Ev PATH
1.1 cgd 143: variable.
1.14 yamt 144: If this variable isn't specified,
1.16 wiz 145: .Va _PATH_DEFPATH
146: from
1.14 yamt 147: .Pa <paths.h>
148: is used instead, its value being:
1.16 wiz 149: .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin .
1.4 jtc 150: In addition, certain errors are treated specially.
1.1 cgd 151: .Pp
152: If permission is denied for a file (the attempted
1.10 fair 153: .Xr execve 2
1.1 cgd 154: returned
155: .Er EACCES ) ,
156: these functions will continue searching the rest of
157: the search path.
158: If no other file is found, however, they will return with the global variable
159: .Va errno
160: set to
161: .Er EACCES .
162: .Pp
163: If the header of a file isn't recognized (the attempted
1.10 fair 164: .Xr execve 2
1.1 cgd 165: returned
166: .Er ENOEXEC ) ,
167: these functions will execute the shell with the path of
168: the file as its first argument.
169: (If this attempt fails, no further searching is done.)
170: .Pp
171: If the file is currently busy (the attempted
1.10 fair 172: .Xr execve 2
1.1 cgd 173: returned
174: .Er ETXTBUSY ) ,
175: these functions will sleep for several seconds,
176: periodically re-attempting to execute the file.
177: .Pp
178: The function
179: .Fn exect
180: executes a file with the program tracing facilities enabled (see
181: .Xr ptrace 2 ) .
182: .Sh RETURN VALUES
183: If any of the
1.16 wiz 184: .Nm exec
1.1 cgd 185: functions returns, an error will have occurred.
186: The return value is \-1, and the global variable
187: .Va errno
188: will be set to indicate the error.
189: .Sh FILES
1.3 jtc 190: .Bl -tag -width /bin/sh -compact
1.1 cgd 191: .It Pa /bin/sh
192: The shell.
193: .El
194: .Sh ERRORS
1.8 enami 195: .Fn execl ,
1.1 cgd 196: .Fn execle ,
197: .Fn execlp
198: and
199: .Fn execvp
200: may fail and set
201: .Va errno
202: for any of the errors specified for the library functions
203: .Xr execve 2
204: and
205: .Xr malloc 3 .
206: .Pp
1.8 enami 207: .Fn exect
1.1 cgd 208: and
209: .Fn execv
210: may fail and set
211: .Va errno
212: for any of the errors specified for the library function
213: .Xr execve 2 .
214: .Sh SEE ALSO
215: .Xr sh 1 ,
216: .Xr execve 2 ,
217: .Xr fork 2 ,
218: .Xr ptrace 2 ,
1.7 enami 219: .Xr environ 7
1.1 cgd 220: .Sh COMPATIBILITY
221: Historically, the default path for the
222: .Fn execlp
223: and
224: .Fn execvp
225: functions was
226: .Dq Pa :/bin:/usr/bin .
1.15 yamt 227: This was changed to improve security and behaviour.
1.1 cgd 228: .Pp
229: The behavior of
230: .Fn execlp
231: and
232: .Fn execvp
233: when errors occur while attempting to execute the file is historic
234: practice, but has not traditionally been documented and is not specified
235: by the
236: .Tn POSIX
237: standard.
238: .Pp
239: Traditionally, the functions
240: .Fn execlp
241: and
242: .Fn execvp
243: ignored all errors except for the ones described above and
244: .Er ENOMEM
245: and
246: .Er E2BIG ,
247: upon which they returned.
248: They now return if any error other than the ones described above occurs.
249: .Sh STANDARDS
1.8 enami 250: .Fn execl ,
1.1 cgd 251: .Fn execv ,
252: .Fn execle ,
253: .Fn execlp
254: and
255: .Fn execvp
256: conform to
1.6 kleink 257: .St -p1003.1-90 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to exec.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen