Index of Section 2 Manual Pages
| Interix / SUA | execvp.2 | Interix / SUA |
execvp(2) execvp(2)
exec()
NAME
execl(), execle(), execlp(), execv(), execve(), execvp() - execute a file
SYNOPSIS
#include
extern char **environ;
int execl (const char *path, const char *arg ...)
int execle (const char *path, const char *arg ... char *const envp[])
int execlp (const char *file, const char *arg ...)
int execv (const char *path, char *const argv[])
int execve (const char *path, char *const argv[], char *const envp[])
int execvp (const char *file, char *const argv[])
DESCRIPTION
The exec(2) family of functions replaces the current process image with a
new process image. The first argument is the name of the file to be
executed; most of the functions require a full path name, but execlp(2)
and execvp(2) will search the directories named in the PATH environment
variable.
The second argument to the function is the argument vector (represented in
a C main() function by argv The execl functions take a const char *
argument, while the execv* functions take a char *const array as the
argument. The third argument, where present, is an environment for the new
process image. For execl(2), execv(2), execlp(2), and execvp(2), the new
process image inherits the environment of the calling process image,
stored in extern char **environ
The arguments are:
const char *path
For the functions execl(2), execv(2), execle(2), and execve(2), the
path is a path name that points to the file to be executed. If the
file doesn't exist or has the wrong permissions, the functions return
-1 and set errno. The path can also specify a data file for an
interpreter program; an interpreter file begins with a line of the
form:
#! interpreter [arguments]
For more information about interpreter files, see Interpreter Files later
in this reference page.
const char *file
For the functions execlp(2) and execvp(2), the file is the name of the
file to be executed; if file doesn't begin with a slash (/) the call
constructs the path name by searching the directories named in the PATH
environment variable.
Once the file is found, the exec functions try to execute it as a POSIX
process, then as a Win32 process, and last as an interpreter file.
const char *arg ...
The arg and subsequent ellipse can be thought of as arg0 arg1 ..., argn a
variable-length list of pointers to null-terminated character strings that
represent the argument list available to the new program. The first
argument should be the file name of the new process; the last argument
should be a NULL pointer.
This argument is treated slightly differently by execle(2): after the NULL
pointer, there is another character pointer which contains the new
process's environment, as if it were declared as
char *const envp[]
char *const argv[]
An array of character pointers to null-terminated strings; the last member
of the array is a NULL pointer. argv[0] should contain the name of the
file being executed.
char *const envp[]
An array of character pointers to null-terminated strings that make up the
environment array of the new process image.
The total space available for the combined argument and environment lists
of the new process image is {ARG_MAX}.
When the call succeeds, it creates a new process image; if the new process
is a C program, the entry point is main where argc is the number of
elements in the argument list (not counting the terminating NULL pointer)
and argv is the argument list itself. The functions also set up
extern char **environ
which contains the process's environment.
Once these calls have successfully completed, they mark the st_atime field
of path, since it was successfully open(2)'ed.
Inherited Properties
Here are the guidelines as to which attributes and resources are and are
not inherited by the new process:
Calling Process Attribute Behavior
Open file descriptors Remain open, unless close-on-exec
flag FD_CLOEXEC is set
Directory streams Closed
Signals set to default action Set to default action
Signals set to be ignored Set to be ignored
Signals set to be caught Set to default action
Real user ID Inherited
Real group ID Inherited
Supplementary group ID Inherited
Effective user ID Inherited, unless path has set-
user-ID set. Interix must be
configured to execute files with
set-user-ID set; see [ENOSETUID] in
ERRORS later in this topic.
Effective group ID Inherited, unless path has set-
group-ID set. Interix must be
configured to execute files with
set-group-ID set; see [ENOSETUID]
in ERRORS later in this topic.
Process ID Inherited
Parent process ID Inherited
Process group ID Inherited
Session membership Inherited
Time left until alarm clock signal Inherited
Current working directory Inherited
Root directory Inherited
File mode creation mask Inherited
Process signal mask Inherited
Pending signals Inherited
If the saved-set-user-ID mode bit is set on the new process image file,
then the effective user ID of the new process image is set to the owner ID
of the file.
If the saved-set-group-ID mode bit is set on the new process image file,
then the effective group ID of the new process image is set to the group
ID of the file.
If {_POSIX_SAVED_IDS} is defined, the effective user ID and the effective
group ID are saved for use by the setuid(2) function.
Interpreter Files
If the file specified by path is a text file and the first line has the
form:
#! interpreter [arguments]
then the exec functions run the program specified by interpreter with the
given arguments The maximum length of the line is 255 characters; the
interpreter can be invoked with as many arguments as will fit on the
command line.
The interpreter line specifies an interpreter according to the following
rules:
1. If the string begins with /, INTERIX searches in the INTERIX root
directory space.
2. If the file is not found there, the path is assumed to be on the
local drive.
3. If the file is still not found, the exec fails.
The first line can be recursive; that is, interpreter can specify a file
that begins with a #! interpreter line, and so on, nested eight levels.
For each level, the exec functions first try to create a process image of
the file as a POSIX executable, then as a Win32 executable, and last as an
interpreter file.
WIN32 EXEC LIMITATIONS
A POSIX process can exec a Win32 image file, but there are several
limitations.
The POSIX process will remain in the Interix subsystem's process table
until the corresponding Win32 process exits. The exit status of this
process will always indicate a normal return, as if by a call to exit(3),
with the exit value being the low order 8 bits of the Win32 process's 32
bit exit status. There is currently no way to detect the fact that a Win32
process was terminated by an exception.
None of the processes spawned by the Win32 process will show up in the
Interix subsystem's process table.
If the Win32 process is a console application, then the only file
descriptors that can be inherited are file descriptors 0, 1 and 2,
corresponding to the Win32 standard input, standard output and standard
error. The only types of file descriptors that can be inherited are those
associated with a regular file, a controlling console tty, a controlling
pseudo tty (stdout and stderr only), /dev/null, or a pipe.
If the Win32 process is a graphical user interface application, no file
descriptors are inherited.
If the Windows security token (which corresponds to the POSIX real UID) of
the Win32 process is that of the interactive user, then any windows
created by the process will be visible on the screen. Otherwise, the
windows will be invisible and non-interactive. Win32 processes spawned
from a telnet(1) session, a POSIX service program, or a process whose real
UID was set by a call to exec*_asuser do not have the ability to create
interactive windows.
A POSIX process cannot exec DOS, Win16 or OS/2 image files.
RETURN VALUES
On success, the exec functions don't return. If they fail, they set errno
and return -1.
ERRORS
The exec functions can set errno to any of the following values:
[E2BIG]
The argument list was too long.
[EACCES]
Search permission was denied for a directory in the path or the new
process image file wasn't executable.
[EINVAL]
The device holding the file does not support the operation.
[ENAMETOOLONG]
Some component of path was greater than {NAME_MAX}, or the entire path
name exceeded {PATH_MAX}.
[ENODEV]
When exec'ing a Win32 program, the calls can fail with ENODEV. One of
the following has happened:
a)
File descriptor 0, 1, or 2 refers to an object that is not a file,
pipe, tty, or /dev/null. If one of these file descriptors refers
to a socket, you may also get this error. The usual workaround is
toreplacee file descriptors 0, 1, and 2 with a pipe or /dev/null,
as appropriate.
b)
File descriptors 1 and 2 refer to two different tty devices,
neither of which is a controlling tty of the form /dev/ttynXX.
c)
File descriptor 0 refers to a tty that is not the controlling tty.
This is commonly the case after calling setsid(2). The usual
workaround is to close file descriptor 0, or reopen it as /dev/
null.
[ENOENT]
One or more components of path doesn't exist, or the path or file
argument is an empty string.
[ENOEXEC]
For execl(2), execv(2), execle(2), and execve(2), the new process
image file has the appropriate access permission, but is not in the
proper format; or, more than eight levels of recursion have been
encountered in processing an interpreter file.
[ENOMEM]
Not enough memory to load the new process image.
[ENOSETUID]
An attempt was made to execute a file with the set-user-ID (setuid) or
set-group-ID (setgid) mode bit set, and Interix is not configured to
execute files with these mode bits set. For security purposes, Interix
does not execute these files by default. For more information and and
instructions for enabling execution of files with these mode bits set,
see The superuser account and appropriate privileges in Windows
Services for UNIX Help.
[ENOTDIR]
Some component of the path prefix of path is not a directory.
NOTES
The exec functions will fail if the setuid or setgid bit is set on the
file being executed and if the file's mode bits allow it to be written by
anyone other than the owner.
SEE ALSO
sh(1)
exit(3)
fork(2)
USAGE NOTES
All of these functions are thread safe.
The following functions are async-signal safe: execle, execve. The
following functions are not async-signal safe: exec, execl, execlp, execv,
execvp.