alParamBuild(2K)

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | LIMITATIONS | BUGS | RETURN VALUE | ATTRIBUTES | SEE ALSO

NAME

aload, alParamBuild, alParamUnpack, agetalparam- Manage the loading of an actor

SYNOPSIS

#include <afexec.h>

int aload(const KnCap * cactorcap, const char * path, const AlParam * ldParam, KnPc entry);
void alParamBuild(void * buffer, unsigned int bufferSize, const char *const * argv, const char *const * envp);
int alParamUnpack(const Alparam * alParamp, int * argcp, char *** argvp);
unsigned int alParamSize(const Alparam * alParamp);
int agetalparam(const AlParam ** argp);

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 aload() call initializes the text and data regions of the target actor identified by cactorcap . This call also initializes the environment and arguments of the target actor.

The target actor is loaded from an executable object file whose pathname is specified by path . This file consists of a binary header, a text segment, and the initialized part of the data segment. The file may be in any of the supported executable file formats.

The param argument points to an AlParam data structure, which is a packed representation of the environment, and arguments which will be copied to a region of the target actor address space. The address of this region can subsequently be obtained by the target actor using the agetalparam() call. This region is freed when the target actor starts executing after the args and env have been installed in the actor address space (heap or stack).

An AlParam structure can be built using alParamBuild() .

If path is a NULL pointer, no executable file is loaded.

If ldParam is a NULL pointer, the packed arguments and environment currently installed in the actor are not affected.

If entry is not a NULL pointer, it must point to a valid location large enough to store a KnPc object. In that case, the entry-point as determined by the loader is returned into the location pointed to by entry .

The aload() call can be used on any actor as many times as necessary. It is up to the caller to ensure that the address ranges to be used in the target actor are actually free, and that the target actor is in a state where it is safe to modify its address space.

The alParamBuild() command builds an AlParam structure from the argv and envp arrays provided, and stores the result in the buffer buffer . The buffer field must point to an area of memory large enough to hold the arguments and environment described by argv and envp .

The alParamUnpack() command retrieves the arguments and environment from the data structure pointed to by alParamp , copies them to the newly-allocated memory, builds the environment string pointer arrays and builds the argument's string pointers array whose addresses are stored in the areas pointed to by argvp . The number of arguments is returned into the location pointed to by argcp .

Do not build an AlParam data structure containing more than ARG_MAX bytes of data. The only limit is the amount of memory available when unpacking the structure, and the amount of memory available in the system to store a copy of it in the restart parameters of a new actor.

The alparamsize field shows the total size used of the AlParam object referred to by alParamp . The size returned takes into account the AlParam object and the strings that follow.

The agetalparam() call returns, at the location pointed to by argp , the address where the packed arguments and environment are stored in the calling actor's address space.

Note that agetalparam() and alParamUnpack() are not normally used by the application; they are used by the C library startup code to build the arguments and environment in the traditional UNIX representation. The packed arguments and environment themselves are not affected, nor used by, the getenv() and setenv() library routines. If permitted by the configuration of the microkernel, the region containing the packed arguments and environment will be read-only.

LIMITATIONS

It should be noted that aload() is usually the first event that allocates regions to an actor created using acreate() .

BUGS

When installing the new packed arguments and environment, aload() does not free the packed arguments and environment region resulting from a previous call to aload() .

RETURN VALUE

Upon successful completion, aload() returns 0 . Otherwise aload() returns -1 and sets errno to indicate one of the following error conditions:

ENOENT

One or more components of the new actor's pathname do not exist.

ENOTDIR

A component of the new actor's pathname prefix is not a directory.

EACCES

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

ENOEXEC

The new actor file has the appropriate access permission but is not in the proper format.

EFAULT

The new actor file is not as long as indicated by the size values in its header.

EFAULT

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

EINVAL

The address of the text or data region of the new actor is not consistent with the new actor privilege (SUPERVISOR, USER, SYSTEM).

ENAMETOOLONG

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

ELOOP

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

EIO

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

ESRCH

The actor referred to by the given capability does not exist.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Deprecated

SEE ALSO

acreate(2K) , afexec(2K) , akill(2K) , astart(2K) , hrfexec(2RESTART)

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | LIMITATIONS | BUGS | RETURN VALUE | ATTRIBUTES | SEE ALSO