NAME | SYNOPSIS | FEATURES | DESCRIPTION | LIMITATIONS | RETURN VALUES | ATTRIBUTES | SEE ALSO
#include <am/afexec.h>int acreate(KnCap *cactorcap, const AcParam *param);
ACTOR_EXTENDED_MNGT
The acreate call creates a c_actor according to the arguments specified by param.
The param argument points to an AcParam structure which should contain the specification of the new c_actor. An AcParam structure has the following members:
int acSite ; /* new c_actor execution site ID */ int acFlags ; /* c_actor options */ char* acStdin ; /* standard input */ char* acStout ; /* standard output */ char* acStderr ; /* standard error output */ char* acCurdir ; /* current directory */ char* acRootdir ; /* root directory */ cx_cred_t* acCred ; /* c_actor credentials (This member is ignored.) */
The new c_actor runs on the local site. acSite is ignored.
The acFlags values are constructed by using a combination of the following flags. Note that either AFX_USER_SPACE or AFX_SUPERVISER_SPACE, but not both, can be used.
If AFX_TRUSTED is set, the new c_actor is implemented as a system actor (see intro(2K)) and is a Trusted c_actor (see intro(2K)), otherwise the new c_actor is implemented as a user actor and is not Trusted.
The new c_actor is implemented as a supervisor actor (see intro(2K)) and is a Trusted c_actor (see intro(2K)).
AFX_ANY_SPACE is meaningful only with afexec; it is not applicable with acreate.
The new c_actor privilege (user or supervisor) will be deduced from binary at load time. This flag takes precedence over the two previous ones. If the AFX_NON_TRUSTED flag is set, the privilege deduced from binary will be the user privilege.
The new c_actor will be started in debug mode. If AFX_WAIT_ATTACH is also set, the new c_actor will be stopped to wait for a debugger to perform an ATRACE_ATTACH command through the (see atrace(2K)) system call; otherwise, the calling c_actor is considered as its own debugger.
The new c_actor will be executed in place, meaning the code will not be copied, but instead executed where found. Data will be copied. This requires the actor to be fully linked.
A description of the new c_actor symbols will be loaded in memory. This symbol description will enable symbolic debugging of the new c_actor using the kernel debugger. This flag is only meaningful for a supervisor c_actor.
The new c_actor will be put into the DEBUGMODE mode (see actorCreate(2K)) That means that more information than usual about thread execution will be gathered by the system. Not to be confused with AFX_DEBUGEE.
The new c_actor will be put into the STOPPED state. Not to be confused with AFX_WAIT_ATTACH, as no ATRACE_ATTACH command is expected.
The acStdin, acStdout, and acStderr fields specify the path name for the standard input, the standard output and the standard error output files for the new c_actor.
The acCurdir field allows you to specify the pathname for the current directory of the new c_actor.
The acRootdir field allows you to specify the pathname for the root directory of the new c_actor.
The acCred field allows you to set the credentials of the new c_actor. This field may only be set by a trusted c_actor.
Unlike afexec, acreate does not load the new c_actor or activate it.
After acreate has been created, the new c_actor exists, a corresponding actor has been created according to the acFlags specified, the standard I/O files and directories specified are open, and the new c_actor has the specified credentials. However, the new c_actor does not have any regions or threads. In addition, the new c_actor is not mature, which means that if the calling c_actor is deleted, the new c_actor will be deleted.
If one of the pointer-type members of *param is NULL, the corresponding parameter is considered un-specified. If a parameter is un-specified, the new c_actor will inherit the corresponding running attributes of the calling c_actor.
File descriptors with the close-on-afexec flag set (see afexec(2K)) will not be inherited by the new c_actor.
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, acreate returns a non-negative integer that is the aid of the new c_actor. Otherwise acreate returns -1 and sets errno to indicate one of the following error conditions:
The calling c_actor is not trusted and is either trying to create a trusted c_actor or to set the new c_actor's credentials.
One or more components of the new c_actor's I/O files' path names do not exist.
A component of the new c_actor's I/O files' path prefix is not a directory.
Search permission is denied for a directory listed in one of the new c_actor's I/O files' path prefix.
Inconsistent attribute flags were provided.
parame was NULL.
The length of a component of one of the I/O file's path exceeds NAME_MAX characters, or the length of the complete pathname exceeds PATH_MAX characters.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | LIMITATIONS | RETURN VALUES | ATTRIBUTES | SEE ALSO