[apple/libc.git] / gen / FreeBSD / exec.3

.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" 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 University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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.
.\"
.\"     @(#)exec.3	8.3 (Berkeley) 1/24/94
.\" $FreeBSD: src/lib/libc/gen/exec.3,v 1.23 2003/09/10 19:24:32 ru Exp $
.\"
.Dd January 24, 1994
.Dt EXEC 3
.Os
.Sh NAME
.Nm execl ,
.Nm execlp ,
.Nm execle ,
.Nm exect ,
.Nm execv ,
.Nm execvp ,
.Nm execvP
.Nd execute a file
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Vt extern char **environ ;
.Ft int
.Fn execl "const char *path" "const char *arg" ... /* "(char *)0" */
.Ft int
.Fn execlp "const char *file" "const char *arg" ... /* "(char *)0" */
.Ft int
.Fo execle
.Fa "const char *path" "const char *arg" ...
.Fa /*
.Bk -words
.Fa "(char *)0" "char *const envp[]" */
.Ek
.Fc
.Ft int
.Fn exect "const char *path" "char *const argv[]" "char *const envp[]"
.Ft int
.Fn execv "const char *path" "char *const argv[]"
.Ft int
.Fn execvp "const char *file" "char *const argv[]"
.Ft int
.Fn execvP "const char *file" "const char *search_path" "char *const argv[]"
.Sh DESCRIPTION
The
.Nm exec
family of functions replaces the current process image with a
new process image.
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.)
.Pp
The initial argument for these functions is the pathname of a file which
is to be executed.
.Pp
The
.Fa "const char *arg"
and subsequent ellipses in the
.Fn execl ,
.Fn execlp ,
and
.Fn execle
functions can be thought of as
.Em arg0 ,
.Em arg1 ,
\&...,
.Em argn .
Together they describe a list of one or more pointers to null-terminated
strings that represent the argument list available to the executed program.
The first argument, by convention, should point to the file name associated
with the file being executed.
The list of arguments
.Em must
be terminated by a
.Dv NULL
pointer.
.Pp
The
.Fn exect ,
.Fn execv ,
.Fn execvp ,
and
.Fn execvP
functions provide an array of pointers to null-terminated strings that
represent the argument list available to the new program.
The first argument, by convention, should point to the file name associated
with the file being executed.
The array of pointers
.Sy must
be terminated by a
.Dv NULL
pointer.
.Pp
The
.Fn execle
and
.Fn exect
functions also specify the environment of the executed process by following
the
.Dv NULL
pointer that terminates the list of arguments in the argument list
or the pointer to the argv array with an additional argument.
This additional argument is an array of pointers to null-terminated strings
and
.Em must
be terminated by a
.Dv NULL
pointer.
The other functions take the environment for the new process image from the
external variable
.Va environ
in the current process.
.Pp
Some of these functions have special semantics.
.Pp
The functions
.Fn execlp ,
.Fn execvp ,
and
.Fn execvP
will duplicate the actions of the shell in searching for an executable file
if the specified file name does not contain a slash
.Dq Li /
character.
For
.Fn execlp
and
.Fn execvp ,
search path is the path specified in the environment by
.Dq Ev PATH
variable.
If this variable isn't specified,
the default path is set according to the
.Dv _PATH_DEFPATH
definition in
.In paths.h ,
which is set to
.Dq Ev /usr/bin:/bin .
For
.Fn execvP ,
the search path is specified as an argument to the function.
In addition, certain errors are treated specially.
.Pp
If an error is ambiguous (for simplicity, we shall consider all
errors except
.Er ENOEXEC
as being ambiguous here, although only the critical error
.Er EACCES
is really ambiguous),
then these functions will act as if they stat the file to determine
whether the file exists and has suitable execute permissions.
If it does, they will return immediately with the global variable
.Va errno
restored to the value set by
.Fn execve .
Otherwise, the search will be continued.
If the search completes without performing a successful
.Fn execve
or terminating due to an error,
these functions will return with the global variable
.Va errno
set to
.Er EACCES
or
.Er ENOENT
according to whether at least one file with suitable execute permissions
was found.
.Pp
If the header of a file isn't recognized (the attempted
.Fn execve
returned
.Er ENOEXEC ) ,
these functions will execute the shell with the path of
the file as its first argument.
(If this attempt fails, no further searching is done.)
.Pp
The function
.Fn exect
executes a file with the program tracing facilities enabled (see
.Xr ptrace 2 ) .
.Sh RETURN VALUES
If any of the
.Fn exec
functions returns, an error will have occurred.
The return value is \-1, and the global variable
.Va errno
will be set to indicate the error.
.Sh FILES
.Bl -tag -width /bin/sh -compact
.It Pa /bin/sh
The shell.
.El
.Sh ERRORS
The
.Fn execl ,
.Fn execle ,
.Fn execlp ,
.Fn execvp
and
.Fn execvP
functions
may fail and set
.Va errno
for any of the errors specified for the library functions
.Xr execve 2
and
.Xr malloc 3 .
.Pp
The
.Fn exect
and
.Fn execv
functions
may fail and set
.Va errno
for any of the errors specified for the library function
.Xr execve 2 .
.Sh SEE ALSO
.Xr sh 1 ,
.Xr execve 2 ,
.Xr fork 2 ,
.Xr ktrace 2 ,
.Xr ptrace 2 ,
.Xr environ 7
.Sh COMPATIBILITY
Historically, the default path for the
.Fn execlp
and
.Fn execvp
functions was
.Dq Pa :/bin:/usr/bin .
This was changed to place the current directory last to enhance system
security.
.Pp
The behavior of
.Fn execlp
and
.Fn execvp
when errors occur while attempting to execute the file is not quite historic
practice, and has not traditionally been documented and is not specified
by the
.Tn POSIX
standard.
.Pp
Traditionally, the functions
.Fn execlp
and
.Fn execvp
ignored all errors except for the ones described above and
.Er ETXTBSY ,
upon which they retried after sleeping for several seconds, and
.Er ENOMEM
and
.Er E2BIG ,
upon which they returned.
They now return for
.Er ETXTBSY ,
and determine existence and executability more carefully.
In particular,
.Er EACCES
for inaccessible directories in the path prefix is no longer
confused with
.Er EACCES
for files with unsuitable execute permissions.
In
.Bx 4.4 ,
they returned upon all errors except
.Er EACCES ,
.Er ENOENT ,
.Er ENOEXEC
and
.Er ETXTBSY .
This was inferior to the traditional error handling,
since it breaks the ignoring of errors for path prefixes
and only improves the handling of the unusual ambiguous error
.Er EFAULT
and the unusual error
.Er EIO .
The behaviour was changed to match the behaviour of
.Xr sh 1 .
.Sh STANDARDS
The
.Fn execl ,
.Fn execv ,
.Fn execle ,
.Fn execlp
and
.Fn execvp
functions
conform to
.St -p1003.1-88 .
The
.Fn execvP
function first appeared in
.Fx 5.2 .
Commit	Line	Data
5b2abdfb A	1	.\" Copyright (c) 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)exec.3 8.3 (Berkeley) 1/24/94
3d9156a7	33	.\" $FreeBSD: src/lib/libc/gen/exec.3,v 1.23 2003/09/10 19:24:32 ru Exp $
5b2abdfb A	34	.\"
	35	.Dd January 24, 1994
	36	.Dt EXEC 3
	37	.Os
	38	.Sh NAME
	39	.Nm execl ,
	40	.Nm execlp ,
	41	.Nm execle ,
	42	.Nm exect ,
	43	.Nm execv ,
3d9156a7 A	44	.Nm execvp ,
3d9156a7 A	45	.Nm execvP
5b2abdfb A	46	.Nd execute a file
	47	.Sh LIBRARY
	48	.Lb libc
	49	.Sh SYNOPSIS
	50	.In unistd.h
	51	.Vt extern char **environ ;
	52	.Ft int
3d9156a7	53	.Fn execl "const char path" "const char arg" ... /* "(char )0" /
5b2abdfb	54	.Ft int
3d9156a7	55	.Fn execlp "const char file" "const char arg" ... /* "(char )0" /
5b2abdfb	56	.Ft int
3d9156a7 A	57	.Fo execle
	58	.Fa "const char path" "const char arg" ...
	59	.Fa /*
	60	.Bk -words
	61	.Fa "(char )0" "char const envp[]" */
	62	.Ek
	63	.Fc
5b2abdfb A	64	.Ft int
	65	.Fn exect "const char path" "char const argv[]" "char *const envp[]"
	66	.Ft int
	67	.Fn execv "const char path" "char const argv[]"
	68	.Ft int
	69	.Fn execvp "const char file" "char const argv[]"
3d9156a7 A	70	.Ft int
3d9156a7 A	71	.Fn execvP "const char file" "const char search_path" "char *const argv[]"
5b2abdfb A	72	.Sh DESCRIPTION
	73	The
	74	.Nm exec
	75	family of functions replaces the current process image with a
	76	new process image.
	77	The functions described in this manual page are front-ends for the function
	78	.Xr execve 2 .
	79	(See the manual page for
	80	.Xr execve 2
	81	for detailed information about the replacement of the current process.)
	82	.Pp
	83	The initial argument for these functions is the pathname of a file which
	84	is to be executed.
	85	.Pp
	86	The
	87	.Fa "const char *arg"
	88	and subsequent ellipses in the
	89	.Fn execl ,
	90	.Fn execlp ,
	91	and
	92	.Fn execle
	93	functions can be thought of as
	94	.Em arg0 ,
	95	.Em arg1 ,
	96	\&...,
	97	.Em argn .
	98	Together they describe a list of one or more pointers to null-terminated
	99	strings that represent the argument list available to the executed program.
	100	The first argument, by convention, should point to the file name associated
	101	with the file being executed.
	102	The list of arguments
	103	.Em must
	104	be terminated by a
	105	.Dv NULL
	106	pointer.
	107	.Pp
	108	The
	109	.Fn exect ,
	110	.Fn execv ,
3d9156a7	111	.Fn execvp ,
5b2abdfb	112	and
3d9156a7	113	.Fn execvP
5b2abdfb A	114	functions provide an array of pointers to null-terminated strings that
	115	represent the argument list available to the new program.
	116	The first argument, by convention, should point to the file name associated
	117	with the file being executed.
	118	The array of pointers
	119	.Sy must
	120	be terminated by a
	121	.Dv NULL
	122	pointer.
	123	.Pp
	124	The
	125	.Fn execle
	126	and
	127	.Fn exect
	128	functions also specify the environment of the executed process by following
	129	the
	130	.Dv NULL
9385eb3d A	131	pointer that terminates the list of arguments in the argument list
	132	or the pointer to the argv array with an additional argument.
	133	This additional argument is an array of pointers to null-terminated strings
5b2abdfb A	134	and
	135	.Em must
	136	be terminated by a
	137	.Dv NULL
	138	pointer.
	139	The other functions take the environment for the new process image from the
	140	external variable
	141	.Va environ
	142	in the current process.
	143	.Pp
	144	Some of these functions have special semantics.
	145	.Pp
	146	The functions
3d9156a7 A	147	.Fn execlp ,
3d9156a7 A	148	.Fn execvp ,
5b2abdfb	149	and
3d9156a7	150	.Fn execvP
5b2abdfb A	151	will duplicate the actions of the shell in searching for an executable file
	152	if the specified file name does not contain a slash
	153	.Dq Li /
	154	character.
3d9156a7 A	155	For
	156	.Fn execlp
	157	and
	158	.Fn execvp ,
	159	search path is the path specified in the environment by
5b2abdfb A	160	.Dq Ev PATH
	161	variable.
	162	If this variable isn't specified,
	163	the default path is set according to the
	164	.Dv _PATH_DEFPATH
	165	definition in
3d9156a7	166	.In paths.h ,
5b2abdfb A	167	which is set to
5b2abdfb A	168	.Dq Ev /usr/bin:/bin .
3d9156a7 A	169	For
	170	.Fn execvP ,
	171	the search path is specified as an argument to the function.
5b2abdfb A	172	In addition, certain errors are treated specially.
	173	.Pp
	174	If an error is ambiguous (for simplicity, we shall consider all
	175	errors except
	176	.Er ENOEXEC
	177	as being ambiguous here, although only the critical error
	178	.Er EACCES
	179	is really ambiguous),
	180	then these functions will act as if they stat the file to determine
	181	whether the file exists and has suitable execute permissions.
	182	If it does, they will return immediately with the global variable
	183	.Va errno
	184	restored to the value set by
	185	.Fn execve .
	186	Otherwise, the search will be continued.
	187	If the search completes without performing a successful
	188	.Fn execve
	189	or terminating due to an error,
	190	these functions will return with the global variable
	191	.Va errno
	192	set to
	193	.Er EACCES
	194	or
	195	.Er ENOENT
	196	according to whether at least one file with suitable execute permissions
	197	was found.
	198	.Pp
	199	If the header of a file isn't recognized (the attempted
	200	.Fn execve
	201	returned
	202	.Er ENOEXEC ) ,
	203	these functions will execute the shell with the path of
	204	the file as its first argument.
	205	(If this attempt fails, no further searching is done.)
	206	.Pp
	207	The function
	208	.Fn exect
	209	executes a file with the program tracing facilities enabled (see
	210	.Xr ptrace 2 ) .
	211	.Sh RETURN VALUES
	212	If any of the
	213	.Fn exec
	214	functions returns, an error will have occurred.
	215	The return value is \-1, and the global variable
	216	.Va errno
	217	will be set to indicate the error.
	218	.Sh FILES
	219	.Bl -tag -width /bin/sh -compact
	220	.It Pa /bin/sh
	221	The shell.
	222	.El
	223	.Sh ERRORS
9385eb3d A	224	The
9385eb3d A	225	.Fn execl ,
5b2abdfb	226	.Fn execle ,
3d9156a7	227	.Fn execlp ,
5b2abdfb	228	.Fn execvp
3d9156a7 A	229	and
3d9156a7 A	230	.Fn execvP
9385eb3d	231	functions
5b2abdfb A	232	may fail and set
	233	.Va errno
	234	for any of the errors specified for the library functions
	235	.Xr execve 2
	236	and
	237	.Xr malloc 3 .
	238	.Pp
9385eb3d A	239	The
9385eb3d A	240	.Fn exect
5b2abdfb A	241	and
5b2abdfb A	242	.Fn execv
9385eb3d	243	functions
5b2abdfb A	244	may fail and set
	245	.Va errno
	246	for any of the errors specified for the library function
	247	.Xr execve 2 .
	248	.Sh SEE ALSO
	249	.Xr sh 1 ,
	250	.Xr execve 2 ,
	251	.Xr fork 2 ,
	252	.Xr ktrace 2 ,
	253	.Xr ptrace 2 ,
	254	.Xr environ 7
	255	.Sh COMPATIBILITY
	256	Historically, the default path for the
	257	.Fn execlp
	258	and
	259	.Fn execvp
	260	functions was
	261	.Dq Pa :/bin:/usr/bin .
	262	This was changed to place the current directory last to enhance system
	263	security.
	264	.Pp
	265	The behavior of
	266	.Fn execlp
	267	and
	268	.Fn execvp
	269	when errors occur while attempting to execute the file is not quite historic
	270	practice, and has not traditionally been documented and is not specified
	271	by the
	272	.Tn POSIX
	273	standard.
	274	.Pp
	275	Traditionally, the functions
	276	.Fn execlp
	277	and
	278	.Fn execvp
	279	ignored all errors except for the ones described above and
	280	.Er ETXTBSY ,
	281	upon which they retried after sleeping for several seconds, and
	282	.Er ENOMEM
	283	and
	284	.Er E2BIG ,
	285	upon which they returned.
	286	They now return for
	287	.Er ETXTBSY ,
	288	and determine existence and executability more carefully.
	289	In particular,
	290	.Er EACCES
	291	for inaccessible directories in the path prefix is no longer
	292	confused with
	293	.Er EACCES
	294	for files with unsuitable execute permissions.
	295	In
	296	.Bx 4.4 ,
	297	they returned upon all errors except
	298	.Er EACCES ,
	299	.Er ENOENT ,
	300	.Er ENOEXEC
	301	and
	302	.Er ETXTBSY .
	303	This was inferior to the traditional error handling,
	304	since it breaks the ignoring of errors for path prefixes
	305	and only improves the handling of the unusual ambiguous error
	306	.Er EFAULT
	307	and the unusual error
308	.Er EIO .
309	The behaviour was changed to match the behaviour of
310	.Xr sh 1 .
311	.Sh STANDARDS
9385eb3d A	312	The
9385eb3d A	313	.Fn execl ,
5b2abdfb A	314	.Fn execv ,
	315	.Fn execle ,
	316	.Fn execlp
	317	and
	318	.Fn execvp
9385eb3d	319	functions
5b2abdfb A	320	conform to
5b2abdfb A	321	.St -p1003.1-88 .
3d9156a7 A	322	The
	323	.Fn execvP
	324	function first appeared in
	325	.Fx 5.2 .