<util/spawn.h>¶
Starting programs: load a ZXF or ELF32 image into a new space and run it.
#include <util/spawn.h>
Constants¶
| Name | Value | Description |
|---|---|---|
SPAWN_PRIO_INHERIT |
(-1) |
SpawnAttr value meaning "keep what the new task inherits from the caller". |
Structures¶
SpawnAttr¶
Scheduling settings for a new program.
| Field | Type | Description |
|---|---|---|
prio |
int32_t |
Base priority, or SPAWN_PRIO_INHERIT. |
max_prio |
int32_t |
Maximum priority, or SPAWN_PRIO_INHERIT. |
Functions¶
SpawnProcess¶
Err SpawnProcess(const void *image, size_t size, const char *name, const char *argbuf, size_t argbuf_len, uint32_t argc, Spid *out_pid, Handle *out_task);
Starts a program from an image in memory.
Detects ZXF or ELF32 by its magic, creates a space and a task, maps the load segments, lays out argv on a fresh stack, gives the new space the name-service port in its handle slot 0, and starts the task with r0 = argc and r1 = argv.
| Parameter | Direction | Description |
|---|---|---|
image |
in | Image bytes, 4-byte aligned. |
size |
in | Image size in bytes. |
name |
in | Name for the new space; truncated to 31 characters. |
argbuf |
in | argv strings back to back, each NUL-terminated ("a\0b\0"), or NULL. |
argbuf_len |
in | Length of argbuf including the NULs, or 0. |
argc |
in | Number of strings in argbuf, or 0. |
out_pid |
out | Receives the new space's handle; may be NULL. |
out_task |
out | Receives the new task's handle; may be NULL. |
Returns: ZUZU_OK, or an error code.
| Error | Condition |
|---|---|
ERR_MALFORMED |
The image is neither a valid ZXF nor a valid ARM ELF32 executable. |
ERR_OVERFLOW |
The image has more than 8 load segments. |
ERR_BADARG |
argc and argbuf disagree, or argv needs more than 16 KiB. |
ERR_NOMEM |
Out of memory. |
SpawnProcessAttr¶
Err SpawnProcessAttr(const void *image, size_t size, const char *name, const char *argbuf, size_t argbuf_len, uint32_t argc, const SpawnAttr *attr, Spid *out_pid, Handle *out_task);
SpawnProcess() with scheduling settings.
prio must not exceed max_prio, and neither may exceed the caller's own maximum priority.
| Parameter | Direction | Description |
|---|---|---|
image |
in | Image bytes, 4-byte aligned. |
size |
in | Image size in bytes. |
name |
in | Name for the new space. |
argbuf |
in | argv strings back to back, or NULL. |
argbuf_len |
in | Length of argbuf, or 0. |
argc |
in | Number of strings in argbuf, or 0. |
attr |
in | Scheduling settings, or NULL to inherit both. |
out_pid |
out | Receives the new space's handle; may be NULL. |
out_task |
out | Receives the new task's handle; may be NULL. |
Returns: As SpawnProcess(); also ERR_BADARG if prio is above max_prio, or ERR_NOPERM if either is above the caller's maximum.
SpawnProcessObj¶
Err SpawnProcessObj(Handle image_obj, size_t size, const char *name, const char *argbuf, size_t argbuf_len, uint32_t argc, Spid *out_pid, Handle *out_task);
SpawnProcess() from an image held in a memory object, e.g.
read there by FsdReadObj().
Read-only segments whose file offset is page-aligned are mapped straight from the object, without copying; the rest is copied. The caller keeps image_obj and may close it afterwards: the new program's mappings hold their own references.
| Parameter | Direction | Description |
|---|---|---|
image_obj |
in | Memory object holding the image. |
size |
in | Image size in bytes. |
name |
in | Name for the new space. |
argbuf |
in | argv strings back to back, or NULL. |
argbuf_len |
in | Length of argbuf, or 0. |
argc |
in | Number of strings in argbuf, or 0. |
out_pid |
out | Receives the new space's handle; may be NULL. |
out_task |
out | Receives the new task's handle; may be NULL. |
Returns: As SpawnProcess(), or the error from mapping image_obj.
SpawnProcessObjAttr¶
Err SpawnProcessObjAttr(Handle image_obj, size_t size, const char *name, const char *argbuf, size_t argbuf_len, uint32_t argc, const SpawnAttr *attr, Spid *out_pid, Handle *out_task);
SpawnProcessObj() with scheduling settings; see SpawnProcessAttr().
| Parameter | Direction | Description |
|---|---|---|
image_obj |
in | Memory object holding the image. |
size |
in | Image size in bytes. |
name |
in | Name for the new space. |
argbuf |
in | argv strings back to back, or NULL. |
argbuf_len |
in | Length of argbuf, or 0. |
argc |
in | Number of strings in argbuf, or 0. |
attr |
in | Scheduling settings, or NULL to inherit both. |
out_pid |
out | Receives the new space's handle; may be NULL. |
out_task |
out | Receives the new task's handle; may be NULL. |
Returns: As SpawnProcessAttr().