[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine

Purpose

Executes a file.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

extern 
char **environ;


int execl (
Path,
Argument0 [, Argument1...], 0)
const char *Path, *Argument0, *Argument
1
, ...;


int execle (
Path,
Argument0 [, Argument1...], 0,
        
EnvironmentPointer)
const
char *
Path, *Argument0, *Argum
ent
1
...;
char *const EnvironmentPointer[ ];


int execlp (
File,
Argument0 [, Argument1
, ...], 0)
const char *File, *Argument0, *Argument
1
, ...;


int execv (
Path
ArgumentV)
const char *Path;
char *const ArgumentV];


int execve (
Path
ArgumentV,
        
EnvironmentPointer)
const char *Path;
char
*const 
ArgumentV[ ], *EnvironmentPointer
[ ];


int execvp (
File
ArgumentV)
const char *File;
char *const ArgumentV[ ];


int exect (
Path,
ArgumentV,
EnvironmentPointer)
char *Path, *ArgumentV, *EnvironmentPointer [ ];

Description

The exec subroutine, in all its forms, executes a new program in the calling process. The exec subroutine does not create a new process, but overlays the current program with a new one, which is called the new-process image. The new-process image file can be one of three file types:

The new-process image inherits the following attributes from the calling process image: session membership, supplementary group IDs, process signal mask, and pending signals.

The last of the types mentioned is recognized by a header with the following syntax:

#! Path [String]

The #! is the file magic number, which identifies the file type. The path name of the file to be executed is specified by the Path parameter. The String parameter is an optional character string that contains no tab or space characters. If specified, this string is passed to the new process as an argument in front of the name of the new-process image file. The header must be terminated with a new-line character. When called, the new process passes the Path parameter as ArgumentV[0]. If a String parameter is specified in the new process image file, the exec subroutine sets ArgumentV[0] to the String and Path parameter values concatenated together. The rest of the arguments passed are the same as those passed to the exec subroutine.

The exec subroutine attempts to cancel outstanding asynchronous I/O requests by this process. If the asynchronous I/O requests cannot be canceled, the application is blocked until the requests have completed.

The exec subroutine is similar to the load (load Subroutine) subroutine, except that the exec subroutine does not have an explicit library path parameter. Instead, the exec subroutine uses the LIBPATH environment variable. The LIBPATH variable is ignored when the program that the exec subroutine is run on has more privilege than the calling program, for example, the suid program.

The exect subroutine is included for compatibility with older programs being traced with the ptrace command. The program being executed is forced into hardware single-step mode.

Note: exect is not supported in 64-bit mode.

Parameters


Path Specifies a pointer to the path name of the new-process image file. If Network File System (NFS) is installed on your system, this path can cross into another node. Data is copied into local virtual memory before proceeding.
File Specifies a pointer to the name of the new-process image file. Unless the File parameter is a full path name, the path prefix for the file is obtained by searching the directories named in the PATH environment variable. The initial environment is supplied by the shell.

Note: The execlp subroutine and the execvp subroutine take File parameters, but the rest of the exec subroutines take Path parameters. (For information about the environment, see the environment miscellaneous facility and the sh command.)
Argument0 [, Argument1, ...] Point to null-terminated character strings. The strings constitute the argument list available to the new process. By convention, at least the Argument0 parameter must be present, and it must point to a string that is the same as the Path parameter or its last component.
ArgumentV Specifies an array of pointers to null-terminated character strings. These strings constitute the argument list available to the new process. By convention, the ArgumentV parameter must have at least one element, and it must point to a string that is the same as the Path parameter or its last component. The last element of the ArgumentV parameter is a null pointer.
EnvironmentPointer An array of pointers to null-terminated character strings. These strings constitute the environment for the new process. The last element of the EnvironmentPointer parameter is a null pointer.

When a C program is run, it receives the following parameters:

main (ArgumentCount, ArgumentV, EnvironmentPointer)
int ArgumentCount;
char *ArgumentV[ ], *EnvironmentPointer[ 
];

In this example, the ArgumentCount parameter is the argument count, and the ArgumentV parameter is an array of character pointers to the arguments themselves. By convention, the value of the ArgumentCount parameter is at least 1, and the ArgumentV[0] parameter points to a string containing the name of the new-process image file.

The main routine of a C language program automatically begins with a runtime start-off routine. This routine sets the environ global variable so that it points to the environment array passed to the program in EnvironmentPointer. You can access this global variable by including the following declaration in your program:

extern char **environ;

The execl, execv, execlp, and execvp subroutines use the environ global variable to pass the calling process current environment to the new process.

File descriptors open in the calling process remain open, except for those whose close-on-exec flag is set. For those file descriptors that remain open, the file pointer is unchanged. (For information about file control, see the fcntl.h file.)

The state-of-conversion descriptors and message-catalog descriptors in the new process image are undefined. For the new process, an equivalent of the setlocale subroutine, specifying the LC_ALL value for its category and the "C" value for its locale, is run at startup.

If the new program requires shared libraries, the exec subroutine finds, opens, and loads each of them into the new-process address space. The referenced counts for shared libraries in use by the issuer of the exec are decremented. Shared libraries are searched for in the directories listed in the LIBPATH environment variable. If any of these files is remote, the data is copied into local virtual memory.

The exec subroutines reset all caught signals to the default action. Signals that cause the default action continue to do so after the exec subroutines. Ignored signals remain ignored, the signal mask remains the same, and the signal stack state is reset. (For information about signals, see the sigaction subroutine.)

If the SetUserID mode bit of the new-process image file is set, the exec subroutine sets the effective user ID of the new process to the owner ID of the new-process image file. Similarly, if the SetGroupID mode bit of the new-process image file is set, the effective group ID of the new process is set to the group ID of the new-process image file. The real user ID and real group ID of the new process remain the same as those of the calling process. (For information about the SetID modes, see the chmod subroutine.)

At the end of the exec operation the saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process.

When one or both of the set ID mode bits is set and the file to be executed is a remote file, the file user and group IDs go through outbound translation at the server. Then they are transmitted to the client node where they are translated according to the inbound translation table. These translated IDs become the user and group IDs of the new process.

Note: setuid and setgid bids on shell scripts do not affect user or group IDs of the process finally executed.

Profiling is disabled for the new process.

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

Upon successful completion, the exec subroutines mark for update the st_atime field of the file.

Examples

  1. To run a command and pass it a parameter, enter:

    execlp("ls", "ls", "-al", 0);
    

    The execlp subroutine searches each of the directories listed in the PATH environment variable for the ls command, and then it overlays the current process image with this command. The execlp subroutine is not returned, unless the ls command cannot be executed.

    Note: This example does not run the shell command processor, so operations interpreted by the shell, such as using wildcard characters in file names, are not valid.
  2. To run the shell to interpret a command, enter:

    execl("/usr/bin/sh", "sh", "-c", "ls -l *.c", 
    0);
    

    This runs the sh command with the -c flag, which indicates that the following parameter is the command to be interpreted. This example uses the execl subroutine instead of the execlp subroutine because the full path name /usr/bin/sh is specified, making a path search unnecessary.

    Running a shell command in a child process is generally more useful than simply using the exec subroutine, as shown in this example. The simplest way to do this is to use the system subroutine.

  3. The following is an example of a new-process file that names a program to be run:

    #! /usr/bin/awk -f
    { for (i = NF; i > 0; --i) print $i }
    

    If this file is named reverse, entering the following command on the command line:

    reverse chapter1 chapter2
    

    This command runs the following command:

    /usr/bin/awk -f reverse chapter1 chapter2
    

    Note: The exec subroutines use only the first line of the new-process image file and ignore the rest of it. Also, the awk command interprets the text that follows a # (pound sign) as a comment.

Return Values

Upon successful completion, the exec subroutines do not return because the calling process image is overlaid by the new-process image. If the exec subroutines return to the calling process, the value of -1 is returned and the errno global variable is set to identify the error.

Error Codes

If the exec subroutine is unsuccessful, it returns one or more of the following error codes:

EACCES The new-process image file is not an ordinary file.
EACCES The mode of the new-process image file denies execution permission.
ENOEXEC The exec subroutine is neither an execlp subroutine nor an execvp subroutine. The new-process image file has the appropriate access permission, but the magic number in its header is not valid.
ENOEXEC The new-process image file has a valid magic number in its header, but the header is damaged or is incorrect for the machine on which the file is to be run.
ETXTBSY The new-process image file is a pure procedure (shared text) file that is currently open for writing by some process.
ENOMEM The new process requires more memory than is allowed by the system-imposed maximum, the MAXMEM compiler option.
E2BIG The number of bytes in the new-process argument list is greater than the system-imposed limit. This limit is a system configurable value that can be set by superusers or system group users using SMIT. Refer to Kernel Tunable Parameters for details.
EFAULT The Path, ArgumentV, or EnviromentPointer parameter points outside of the process address space.
EPERM The SetUserID or SetGroupID mode bit is set on the process image file. The translation tables at the server or client do not allow translation of this user or group ID.

If the exec subroutine is unsuccessful because of a condition requiring path name resolution, it returns one or more of the following error codes:

EACCES Search permission is denied on a component of the path prefix. Access could be denied due to a secure mount.
EFAULT The Path parameter points outside of the allocated address space of the process.
EIO An input/output (I/O) error occurred during the operation.
ELOOP Too many symbolic links were encountered in translating the Path parameter.
ENAMETOOLONG A component of a path name exceeded 255 characters and the process has the disallow truncation attribute (see the ulimit subroutine), or an entire path name exceeded 1023 characters.
ENOENT A component of the path prefix does not exist.
ENOENT A symbolic link was named, but the file to which it refers does not exist.
ENOENT The path name is null.
ENOTDIR A component of the path prefix is not a directory.
ESTALE The root or current directory of the process is located in a virtual file system that has been unmounted.

In addition, some errors can occur when using the new-process file after the old process image has been overwritten. These errors include problems in setting up new data and stack registers, problems in mapping a shared library, or problems in reading the new-process file. Because returning to the calling process is not possible, the system sends the SIGKILL signal to the process when one of these errors occurs.

If an error occurred while mapping a shared library, an error message describing the reason for error is written to standard error before the signal SIGKILL is sent to the process. If a shared library cannot be mapped, the subroutine returns one of the following error codes:

ENOENT One or more components of the path name of the shared library file do not exist.
ENOTDIR A component of the path prefix of the shared library file is not a directory.
ENAMETOOLONG A component of a path name prefix of a shared library file exceeded 255 characters, or an entire path name exceeded 1023 characters.
EACCES Search permission is denied for a directory listed in the path prefix of the shared library file.
EACCES The shared library file mode denies execution permission.
ENOEXEC The shared library file has the appropriate access permission, but a magic number in its header is not valid.
ETXTBSY The shared library file is currently open for writing by some other process.
ENOMEM The shared library requires more memory than is allowed by the system-imposed maximum.
ESTALE The process root or current directory is located in a virtual file system that has been unmounted.

If NFS is installed on the system, the exec subroutine can also fail if the following is true:

ETIMEDOUT The connection timed out.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Note: Currently, a Graphics Library program cannot be overlaid with another Graphics Library program. The overlaying program can be a nongraphics program. For additional information, see the /usr/lpp/GL/README file.

Related Information

The alarm (getinterval, incinterval, absinterval, resinc, resabs, alarm, ualarm, getitimer or setitimer Subroutine) or incinterval (getinterval, incinterval, absinterval, resinc, resabs, alarm, ualarm, getitimer or setitimer Subroutine) subroutine, chmod (chmod or fchmod Subroutine) or fchmod (chmod or fchmod Subroutine) subroutine, exit (exit, atexit, or _exit Subroutine) subroutine, fcntl (fcntl, dup, or dup2 Subroutine) subroutine, fork (fork, f_fork, or vfork Subroutine) subroutine, getrusage (getrusage, getrusage64, times, or vtimes Subroutine) or times (getrusage, getrusage64, times, or vtimes Subroutine) subroutine, nice (getpriority, setpriority, or nice Subroutine) subroutine, profil (profil Subroutine) subroutine, ptrace (ptrace, ptracex, ptrace64 Subroutine) subroutine.

The semop subroutine, settimer (gettimer, settimer, restimer, stime, or time Subroutine) subroutine, sigaction, signal, or sigvec subroutine, shmat subroutine, system subroutine, ulimit subroutine, umask subroutine.

The awk command, ksh command, sh command.

The environment file.

The XCOFF object (a.out) file format.

The varargs macros.

Asynchronous I/O Overview in AIX 5L Version 5.1 Kernel Extensions and Device Support Programming Concepts.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]