ChorusOS man pages section 2K: Kernel System Calls

acreate(2K)

NAME

acreate- create an actor or process

SYNOPSIS

#include <afexec.h>

cactorcap

param

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

The acreate call creates an actor or process having the properties specified by param.

PARAMETERS

The param argument points to an AcParam structure which should contain the specification of the new process. An AcParam structure has the following members:

     int         acSite ;         /* new process execution site ID */
     int         acFlags ;        /* process options */
     char*       acStdin ;        /* standard input */
     char*       acStdout ;       /* standard output */
     char*       acStderr ;       /* standard error output */
     char*       acCurdir ;       /* current directory */
     char*       acRootdir ;      /* root directory */
     cx_cred_t*  acCred ;         /* process credentials (ignored) */

Note -

The new process runs on the local site. acSite is ignored.

The acFlags values are constructed using a combination of the following flags.

AFX_USER_SPACE

If AFX_TRUSTED is set, the new process is implemented as a system actor and is a Trusted process (see intro(2K)), otherwise the new process is implemented as a user actor and is not Trusted.

Mutually exclusive with AFX_SUPERVISOR_SPACE.

AFX_SUPERVISOR_SPACE

The new process is implemented as a supervisor actor (see intro(2K)) and is a Trusted process (see intro(2K)).

Mutually exclusive with AFX_USER_SPACE.

AFX_ANY_SPACE

AFX_ANY_SPACE is meaningful only with afexec(2K). It is not applicable with acreate(2K).

The new process 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.

AFX_DEBUGGEE

The new process will be started in debug mode. If AFX_WAIT_ATTACH is also set, the new process will be stopped to wait for a debugger to perform an ATRACE_ATTACH command through the (see atrace(2K)) system call. Otherwise, the calling process is considered as its own debugger.

AFX_EXECUTE_IN_PLACE

The new process 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.

AFX_KDB_SYMBOLS

A description of the new process symbols will be loaded in memory. This symbol description will enable symbolic debugging of the new process using the microkernel debugger. This flag is only meaningful for a supervisor process.

AFX_DEBUGMODE

The new process will be put into DEBUGMODE (see actorCreate(2K)) That means that more information than usual about thread execution will be gathered by the system.

AFX_STOPPED

The new process 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 process.

The acCurdir field allows you to specify the pathname for the current directory of the new process.

The acRootdir field allows you to specify the pathname for the root directory of the new process.

The acCred field allows you to set the credentials of the new process. This field may only be set by a trusted process.

Unlike afexec, acreate does not load the new process or activate it.

After acreate has been created, the new process 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 process has the specified credentials. However, the new process does not have any regions or threads. In addition, the new process is not mature, which means that if the calling process is deleted, the new process 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 process will inherit the corresponding running attributes of the calling process.

File descriptors with the close-on-afexec flag set (see afexec(2K)) will not be inherited by the new process.

LIMITATIONS

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, acreate() returns a non-negative integer that is the pid of the new process. Otherwise acreate() returns -1 and sets errno to indicate one of the following error conditions:

[EPERM]: The calling process is not trusted and is either trying to create a trusted process or to set the new process's credentials.
ENOENT: One or more components of the new process's I/O files' path names do not exist.
ENOTDIR: A component of the new process's I/O files' path prefix is not a directory.
EACCES: Search permission is denied for a directory listed in one of the new process's I/O files' path prefix.
EINVAL: Inconsistent attribute flags were provided.
EINVAL: param was NULL.
ENAMETOOLONG: 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.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Deprecated