exec()

NAME

execl(), execle(), execlp(), execv(), execve(), execvp() - execute a file

SYNOPSIS

#include <unistd.h>
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

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:

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]

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.

All POSIX signals sent to the Win32 process are ignored.

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)