execl(3POSIX)

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | PARAMETERS | ERRORS | RETURN VALUES | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO

NAME

exec, execl, execlp, execle, execv, execvp- execute a file

SYNOPSIS

#include <unistd.h>
extern char **environ;

int execl(const char * path, const char * arg0, ..., const char * argN, const char * /*NULL*/);
int execlp(const char * file, const char * arg0, ..., const char * argN, const char * /*NULL*/);
int execle(const char * path, const char * arg0, ..., const char * argN, const char * /*NULL*/, const char * envp[]);
int execv(const char * path, char *const argv[]);
int execvp(const char * file, char *const argv[]);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

The exec family of functions replaces the current process image with a new process image. The functions described in this man page are front-ends for the function execve(2POSIX) . (See the man page for execve(2POSIX) for detailed information about the replacement of the current process.)

PARAMETERS

These functions support the following arguments:

file

Name of the file to be executed. If this parameter does not contain a slash character, the path prefix for the file is obtained by a search of the PATH environment variable.

path

Pathname of the file to be executed.

arg0 , ..., argN

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 filename associated with the file being executed. The list of arguments must be terminated by a NULL pointer.

argv[]

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 filename associated with the file being executed. The array of pointers must be terminated by a NULL pointer.

envp[]

The environment of the executed process. This parameter is an array of pointers to null-terminated strings and must be terminated by a NULL pointer. Functions that do not take this argument take the environment for the new process image from the external variable environ in the current process.

ERRORS

execl() , execle() , execlp() and execvp() may fail and set errno for any of the errors specified for the functions execve(2POSIX) and malloc(3STDC) .

execv() fails and sets errno for any of the errors specified for the function execve(2POSIX) .

RETURN VALUES

If any of the exec functions returns, an error has occurred. The return value is -1 , and the global variable errno is set to indicate the error.

EXTENDED DESCRIPTION

Some of these functions have special semantics.

The functions execlp() and execvp() duplicate the actions of the command interpreter in searching for an executable file if the specified file name does not contain a slash "/" character. The search path is the path specified in the environment by the PATH variable. If this variable is not specified, the default path /bin:/usr/bin: is used. In addition, certain errors are treated specifically.

If an error is ambiguous, these functions act as if they stat the file to determine whether the file exists and has suitable execute permissions. If it does, they return immediately with the global variable errno restored to the value set by execve() . Otherwise, the search is continued. If the search is completed without a successful execve() or without terminating due to an error, these functions return with the global variable errno set to EACCES or ENOENT , depending on whether at least one file with suitable execute permissions was found.

---

Note -

For simplicity, consider all errors except ENOEXEC to be ambiguous, although only the critical error EACCES is really ambiguous.

---

If the header of a file is not recognized (the attempted execve() returns ENOEXEC ), each of these functions executes the shell with the path of the file as its first argument. (If this attempt fails, no further searching is done.)

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
MT-Level	Async-Signal-Safe

SEE ALSO

atrace(2K) , execve(2POSIX) , fork(2POSIX)

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | PARAMETERS | ERRORS | RETURN VALUES | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO