#include <afexec.h>int afexecve(const char * path, KnCap * cactorcap, const AcParam * param, char const * argv, char const * envp);
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.
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.
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.
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.
The number of bytes used by the new c_actor's image argument list and environment list is greater than ARG_MAX bytes.
Search permission is denied for a directory listed in the new c_actor's file path prefix.
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.
path , argv , or envp point to an illegal address.
Inconsistent attribute flags were specified.
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.
An I/O error occurred while reading from the file system.
The length of a component of path exceeds NAME_MAX characters or the length of path exceeds PATH_MAX characters.
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 .
The new c_actor file has the appropriate access permission but is not in the correct format.
A component of the new c_actor path of the file prefix is not a directory.
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.
Too many symbolic links have been encountered during analysis of path .
Error codes generated by read() and open() may also be returned.
See attributes(5) for descriptions of the following attributes:
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|
|Interface Stability||Deprecated: Replaced by posix_spawn(2POSIX)|