./_Man_SunOS_4.1.3_html/html2/execve.2v.html

Manual page for EXECVE(2V)

execve - execute a file

SYNOPSIS

int execve(path, argv, envp)
char *path, *argv[], *envp[];

DESCRIPTION

execve() transforms the calling process into a new process. The new process is constructed from an ordinary file, whose name is pointed to by path, called the new process file. This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) and initialized data pages. Additional pages may be specified by the header to be initialized with zero data. See a.out.5

An interpreter file begins with a line of the form `#! interpreter [arg]'. Only the first thirty-two characters of this line are significant. When path refers to an interpreter file, execve() invokes the specified interpreter. If the optional arg is specified, it becomes the first argument to the interpreter, and the pathname to which path points becomes the second argument. Otherwise, the pathname to which path points becomes the first argument. The original arguments are shifted over to become the subsequent arguments. The zeroth argument, normally the pathname to which path points, is left unchanged.

There can be no return from a successful execve() because the calling process image is lost. This is the mechanism whereby different process images become active.

The argument argv is a pointer to a null-terminated array of character pointers to null-terminated character strings. These strings constitute the argument list to be made available to the new process. By convention, at least one argument must be present in this array, and the first element of this array should be the name of the executed program (that is, the last component of path).

The argument envp is also a pointer to a null-terminated array of character pointers to null-terminated strings. These strings pass information to the new process which are not directly arguments to the command (see environ.5v

The number of bytes available for the new process's combined argument and environment lists (including null terminators, pointers and alignment bytes) is {ARG_MAX} (see sysconf.2v On SunOS systems, {ARG_MAX} is currently one megabyte.

Descriptors open in the calling process remain open in the new process, except for those for which the close-on-exec flag is set (see close.2v and fcntl.2v Descriptors which remain open are unaffected by execve().

Signals set to the default action (SIG_DFL) in the calling process image are set to the default action in the new process image. Signals set to be ignored (SIG_IGN) by the calling process image are ignored by the new process image. Signals set to be caught by the calling process image are reset to the default action in the new process image. Signals set to be blocked in the calling process image remain blocked in the new process image, regardless of changes to the signal action. The signal stack is reset to be undefined (see sigvec.2 for more information).

Each process has a real user ID and group ID and an effective user ID and group ID. The real ID identifies the person using the system; the effective ID determines their access privileges. execve() changes the effective user or group ID to the owner or group of the executed file if the file has the ``set-user-ID'' or ``set-group-ID'' modes. The real UID and GID are not affected. The effective user ID and effective group ID of the new process image are saved as the saved set-user-ID and saved set-group-ID respectively, for use by setuid.3v

execve() sets the SEXECED flag for the new process image (see setpgid.2v

The shared memory segments attached to the calling process will not be attached to the new process (see shmop.2

Profiling is disabled for the new process; see profil.2

Upon successful completion, execve() marks for update the st_atime field of the file. execve() also marks st_atime for update if it fails, but is able find the process image file.

If execve() succeeds, the process image file is considered to have been opened (see open.2v The corresponding close (see close.2v is considered to occur after the open, but before process termination or successful completion of a subsequent call to execve().

The new process also inherits the following attributes from the calling process:

attribute                  see
---------------------------------------------------------------------
process ID                 getpid(2)
parent process ID          getpid(2)
process group ID           getpgrp(2V), setpgid(2V)
session membership         setsid(2)
real user ID               getuid(2)
real group ID              getgid(2)
supplementary group IDs    Intro(2)
time left until an alarm   alarm(3C)
supplementary group IDs    getgroups(2)
semadj values              semop(2)
working directory          chdir(2)
root directory             chroot(2)
controlling terminal       termio(4)
trace flag                 ptrace(2), request 0
resource usages            getrusage(2)
interval timers            getitimer(2)
resource limits            getrlimit(2)
file mode mask             umask(2)
process signal mask        sigvec(2), sigprocmask(2V), sigsetmask(2)
pending signals            sigpending(2)
tms_utime, tms_stime,
tms_cutime, tms_cstime     times(3C)

When the executed program begins, it is called as follows:

main(argc, argv, envp)
int argc;
char *argv[], *envp[];

where argc is the number of elements in argv (the ``arg count'', not counting the NULL terminating pointer) and argv points to the array of character pointers to the arguments themselves.

envp is a pointer to an array of strings that constitute the environment of the process. A pointer to this array is also stored in the global variable environ. Each string consists of a name, an ``='', and a null-terminated value. The array of pointers is terminated by a NULL pointer. The shell sh.1 passes an environment entry for each global shell variable defined when the program is called. See environ.5v for some conventionally used names.

Note: Passing values for argc, argv, and envp to main() is optional.

RETURN VALUES

execve() returns to the calling process only on failure. It returns -1 and sets errno to indicate the error.

ERRORS

E2BIG: The total number of bytes in the new process file's argument and environment lists exceeds {ARG_MAX} (see sysconf.2v
EACCES: Search permission is denied for a component of the new process file's path prefix.
: The new process file is not an regular file.
: Execute permission is denied for the new process file.
EFAULT: The new process file is not as long as indicated by the size values in its header.
: path, argv, or envp points to an illegal address.
EIO: An I/O error occurred while reading from the file system.
ENAMETOOLONG: The length of the path argument exceeds {PATH_MAX}.
: A pathname component is longer than {NAME_MAX} (see sysconf.2v while {_POSIX_NO_TRUNC} is in effect (see pathconf.2v
ELOOP: Too many symbolic links were encountered in translating path.
ENOENT: One or more components of the path prefix of the new process file does not exist.
: The new process file does not exist.
ENOEXEC: The new process file has the appropriate access permission, but has an invalid magic number in its header.
ENOMEM: The new process file requires more virtual memory than is allowed by the imposed maximum (getrlimit(2)).
ENOTDIR: A component of the path prefix of the new process file is not a directory.

SYSTEM V ERRORS

In addition to the above, the following may also occur:

ENOENT: path points to a null pathname.

WARNINGS

If a program is setuid() to a non-super-user, but is executed when the real user ID is super-user, then the program has some of the powers of a super-user as well.