afexecl(2K)

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

NAME

afexec, afexecl, afexecv, afexecle, afexecve, afexeclp, afexecvp- create a new c_actor

SYNOPSIS

#include <afexec.h>

int afexecve(const char * path, KnCap * cactorcap, const AcParam * param, char const * argv, char const * envp);
int afexecl(const char * path, KnCap * cactorcap, const AcParam * param, const char * arg0, ..., const char * argn, char * /*NULL */);
int afexecv(const char * path, KnCap * cactorcap, const AcParam * param, char *const * argv);
int afexecle(const char * path, KnCap * cactorcap, const AcParam * param, const char * arg0, ..., const char * argn, char * /*NULL */, char const * envp);
int afexeclp(const char * file, KnCap * cactorcap, const AcParam * param, const char * arg0, ..., const char * argn, char * /*NULL */);
int afexecvp(const char * file, KnCap * cactorcap, const AcParam * param, 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

afexec() calls create a new c_actor with a single thread (the main thread). This main thread will execute with the priority defined by the am.afexecschedprio tunable. It will have an automatically allocated stack, the size of which is defined by the am.afexec.userstacksize tunable for user actors, and by kern.exec.dflSysStackSize for supervisor actors.

The main thread starts executing the runtime startup routine, usually called _start() , specified as the program entry point in the binary header of the new c_actor file. After initialization of the threadsafe C library, the runtime startup routine calls the C program as follows:

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

where argc is the argument count, argv is an array of character pointers to the arguments themselves, and envp is an array of character pointers to the environment strings. As will be described later, argc is conventionally at least 1 , and the first member of the array points to a string containing the name (or pathname) of the executable file.

cactorcap is the returned capability of the new c_actor, and is a pointer to a KnCap structure (see actorCreate(2K) ).

If param is NULL , default parameters are used, acFlags is set to AFX_ANY_SPACE and all others to un-specified . See acreate(2K) for a description of the AcParam structure.

By convention, afexec routines search for either a fully-linked or a relocatable binary in path . If no such binary exists, afexec() routines search for a file with a .r suffix and then with a .O suffix. If the GZ_FEATURE is set to true , for each step, the afexec() routines also search for a file with an additional .gz (for example: path , path.gz , path.r , path.r.gz ).

path may also refer to a relocatable binary stored in a memory buffer in supervisor space, using the syntax ram:0x <start> :0x <length> : . start is the start address at which the binary is stored. length is the length of the binary. The buffer is not used any more after loading, except if the program uses the dynamic library API. Freeing the buffer after afexec() may have unpredictable results if the program uses the dynamic library API.

Files to be loaded may be fully-linked or relocatable files. They may also include dependencies on dynamic, but not shared, libraries. These libraries are looked for and loaded within the actor address space as part of the afexec() call.

arg0 , ... , argn are pointers to null-terminated character strings. These strings constitute the argument list available to the new c_actor. By convention, at least arg0 must be present and point to a string that is the same as path (or file or the last component of path ).

argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new c_actor. By convention, argv must have at least one member, and it must point to a string that is the same as path (or file or the last component of path ). argv is terminated by a null pointer.

envp is an array of character pointers to null-terminated strings. These strings constitute the environment for the new c_actor. envp is terminated by a null pointer. For afexecl() , afexecv() , afexeclp() and afexecvp() , the C runtime start-off routine places a pointer to the environment of the calling c_actor in the global object:

extern char** environ;

and it is used to pass the environment of the calling c_actor to the new c_actor.

afexeclp() and afexecvp() are called with the same arguments as afexecl() and afexecv() , but duplicate the shell's actions in searching for an executable file in a list of directories. The directory list is obtained from the PATH environment variable, and file must point to an executable file name for the new c_actor.

LIMITATIONS

Incompatible requests (such as afexec() of a supervisor binary with the AFX_USER_SPACE flag set) are not normally detected. Applications can use the AFX_ANY_SPACE (see acreate(2K) ) flag to force the system to deduce the type ( user or supervisor ) of the binary. In this case incompatible requests will be detected and refused.

Correct functioning of a supervisor actor executed in place (using the AFX_EXECUTE_IN_PLACE flag) is not guaranteed. Even if the supervisor actor functions normally, only one supervisor actor can be executed in place at any one time from a given binary file. Attempting to execute more than one supervisor actor in place from the same binary file will be rejected by the system.

Correct functioning of any actor executed in place (using the AFX_EXECUTE_IN_PLACE flag) when in flat memory mode is not guaranteed. Even if the actor functions normally, when in flat memory mode only one actor can be executed in place at any one time from a given binary file. Attempting to execute more than one actor in place in this situation will be rejected by the system.

RETURN VALUES

Upon successful completion, afexec() returns a non-negative integer that is the aid of the new c_actor. Otherwise afexec() returns -1 and sets errno to indicate one of the following error conditions.

ERRORS

E2BIG

The number of bytes used by the new c_actor's image argument list and environment list is greater than ARG_MAX bytes.

EACCES

Search permission is denied for a directory listed in the new c_actor's file path prefix.

EBADSYM

The runtime link-editor cannot find a symbol needed by the new c_actor. Possible reasons are that ChorusOS imake rules have not been used to compile the program, or the link editor has found unexpected dynamic libraries.

EFAULT

path , argv , or envp point to an illegal address.

EINVAL

Inconsistent attribute flags were specified.

EINVAL

The address of the text or data region of the new c_actor is not consistent with the AFX_USER_SPACE or AFX_SUPERVISOR_SPACE attribute flag.

EIO

An I/O error occurred while reading from the file system.

ENAMETOOLONG

The length of a component of path exceeds NAME_MAX characters or the length of path exceeds PATH_MAX characters.

ENOENT

The new c_actor is a dynamic actor and one of its dependencies cannot be found either in the directories listed in the LD_LIBRARY_PATH environment variable, or in its runpath, or in /usr/lib .

ENOEXEC

The new c_actor file has the appropriate access permission but is not in the correct format.

ENOTDIR

A component of the new c_actor path of the file prefix is not a directory.

EPERM

The calling c_actor is not Trusted and is trying either to create a Trusted c_actor or set the new c_actor's credentials.

ELOOP

Too many symbolic links have been encountered during analysis of path .

---

Note -

Error codes generated by read() and open() may also be returned.

---

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Deprecated: Replaced by posix_spawn(2POSIX)

SEE ALSO

aconf(2K) , acreate(2K) , actorCreate(2K) , akill(2K) , aload(2K) , astart(2K) , astat(2K) , await(2K) , dlopen(2K) , fcntl(2POSIX) , intro(2K)

ChorusOS 5.0  Last Revised December 2001

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