Task Control Interfaces

Tasks. NuttX is a flat address OS. As such it does not support processes in the way that, say, Linux does. NuttX only supports simple threads running within the same address space. However, the programming model makes a distinction between tasks and pthreads:

  • tasks are threads which have a degree of independence

  • pthreads share some resources.

File Descriptors and Streams. This applies, in particular, in the area of opened file descriptors and streams. When a task is started using the interfaces in this section, it will be created with at most three open files.

If CONFIG_DEV_CONSOLE is defined, the first three file descriptors (corresponding to stdin, stdout, stderr) will be duplicated for the new task. Since these file descriptors are duplicated, the child task can free close them or manipulate them in any way without effecting the parent task. File-related operations (open, close, etc.) within a task will have no effect on other tasks. Since the three file descriptors are duplicated, it is also possible to perform some level of redirection.

pthreads, on the other hand, will always share file descriptors with the parent thread. In this case, file operations will have effect only all pthreads the were started from the same parent thread.

Executing Programs within a File System. NuttX also provides internal interfaces for the execution of separately built programs that reside in a file system. These internal interfaces are, however, non-standard and are documented with the NuttX binary loader and NXFLAT documentation.

Task Control Interfaces. The following task control interfaces are provided by NuttX:

Note

Maybe this can be converted into a table, or could otherwise be replaced by the index if these are sectioned in this way.

Non-standard task control interfaces inspired by VxWorks interfaces:

Non-standard extensions to VxWorks-like interfaces to support POSIX Cancellation Points.

Standard interfaces

Standard vfork and exec[v|l] interfaces:

Standard posix_spawn interfaces:

Non-standard task control interfaces inspired by posix_spawn:

Functions

int task_create(char *name, int priority, int stack_size, main_t entry, char *const argv[])

This function creates and activates a new task with a specified priority and returns its system-assigned ID.

The entry address entry is the address of the “main” function of the task. This function will be called once the C environment has been set up. The specified function will be called with four arguments. Should the specified routine return, a call to exit() will automatically be made.

Note that an arbitrary number of arguments may be passed to the spawned functions.

The arguments are copied (via strdup) so that the life of the passed strings is not dependent on the life of the caller to task_create().

The newly created task does not inherit scheduler characteristics from the parent task: The new task is started at the default system priority and with the SCHED_FIFO scheduling policy. These characteristics may be modified after the new task has been started.

The newly created task does inherit the first three file descriptors (corresponding to stdin, stdout, and stderr) and redirection of standard I/O is supported.

Parameters:

  • name – Name of the new task

  • priority – Priority of the new task

  • stack_size – size (in bytes) of the stack needed

  • entry – Entry point of a new task

  • argv – A pointer to an array of input parameters. The array should be terminated with a NULL argv[] value. If no parameters are required, argv may be NULL.

Returns:

the non-zero task ID of the new task or ERROR if memory is insufficient or the task cannot be created (`errno <#ErrnoAccess>`__ is not set).

Defined in: sched.h

POSIX Compatibility: This is a NON-POSIX interface. VxWorks provides the following similar interface:

int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt,
              int arg1, int arg2, int arg3, int arg4, int arg5,
              int arg6, int arg7, int arg8, int arg9, int arg10);

The NuttX task_create() differs from VxWorks’ taskSpawn() in the following ways:

  • Interface name

  • Various differences in types of arguments

  • There is no options argument.

  • A variable number of parameters can be passed to a task (VxWorks supports ten).

int task_delete(pid_t pid)

This function causes a specified task to cease to exist. Its stack and TCB will be deallocated. This function is the companion to task_create(). This is the version of the function exposed to the user; it is simply a wrapper around the internal, nxtask_terminate() function.

The logic in this function only deletes non-running tasks. If the pid parameter refers to the currently running task, then processing is redirected to exit(). This can only happen if a task calls task_delete() in order to delete itself.

This function obeys the semantics of pthread cancellation: task deletion is deferred if cancellation is disabled or if deferred cancellation is supported (with Cancellation Points enabled).

Parameters:

  • pid – The task ID of the task to delete. An ID of zero signifies the calling task. Any attempt by the calling task will be automatically re-directed to exit().

Returns:

OK, or ERROR if the task cannot be deleted. The `errno <#ErrnoAccess>`__ is set to indicate the nature of the failure. This function can fail, for example, if the provided pid does not correspond to a currently executing task.

Assumptions/Limitations:

task_delete() must be used with caution: If the task holds resources (for example, allocated memory or semaphores needed by other tasks), then task_delete() can strand those resources.

POSIX Compatibility: This is a NON-POSIX interface. VxWorks provides the following similar interface:

The NuttX task_delete() differs from VxWorks’ taskDelete() in the following ways:

  • No support is provided for calling the tasks deletion routines (because the VxWorks taskDeleteHookAdd() is not supported). However, if atexit() or on_exit support is enabled, those will be called when the task deleted.

  • Deletion of self is supported, but only because task_delete() will re-direct processing to exit().

int task_setcancelstate(int state, int *oldstate)

This function atomically sets both the calling task’s cancellability state to the indicated state and returns the previous cancellability state at the location referenced by oldstate. Legal values for state are TASK_CANCEL_ENABLE and TASK_CANCEL_DISABLE.

Any pending thread cancellation may occur at the time that the cancellation state is set to TASK_CANCEL_ENABLE.

The cancellability state and type of any newly created tasks are TASK_CANCEL_ENABLE and TASK_CANCEL_DEFERRED respectively.

Parameters:

  • state – New cancellation state. One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

  • oldstate – Location to return the previous cancellation state.

Returns:

Zero (OK) on success; ERROR is returned on any failure with the errno value set appropriately:

  • ESRCH. No thread could be found corresponding to that specified by the given thread ID.

POSIX Compatibility: This is a non-standard interface. It extends the functionality of pthread_setcancelstate() to tasks and supports use of task_delete().

int task_setcanceltype(int type, FAR int *oldtype);

This function atomically both sets the calling task’s cancellability type to the indicated type and returns the previous cancellability type at the location referenced by oldtype. Legal values for type are TASK_CANCEL_DEFERRED and TASK_CANCEL_ASYNCHRONOUS.

The cancellability state and type of any newly created tasks are TASK_CANCEL_ENABLE and TASK_CANCEL_DEFERRED respectively.

Parameters:

  • type – New cancellation state. One of PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.

  • oldtype – Location to return the previous cancellation type.

Returns:

Zero (OK) on success; ERROR is returned on any failure with the errno value set appropriately:

  • ESRCH. No thread could be found corresponding to that specified by the given thread ID.

POSIX Compatibility: This is a non-standard interface. It extends the functionality of pthread_setcanceltype() to tasks and supports use of task_delete().

void task_testcancel(void)

Creates a Cancellation Point in the calling task. The task_testcancel() function has no effect if cancellability is disabled.

POSIX Compatibility: This is a non-standard interface. It extends the functionality of pthread_testcancel() to tasks and supports use of task_delete().

void exit(int code)
void _exit(int code)

Causes the calling task to cease to exist – its stack and TCB will be deallocated. exit differs from _exit in that it flushes streams, closes file descriptors and will execute any function registered with atexit() or on_exit().

Parameters:

  • code – (ignored)

POSIX Compatibility: This is equivalent to the ANSI interface:

void exit(int code);

And the UNIX interface:

void _exit(int code);

The NuttX exit() differs from ANSI exit() in the following ways:

  • The code parameter is ignored.

pid_t getpid(void)
pid_t vfork(void)

The vfork() function has the same effect as fork(), except that the behavior is undefined if the process created by vfork() either modifies any data other than a variable of type pid_t used to store the return value from vfork(), or returns from the function in which vfork() was called, or calls any other function before successfully calling _exit() or one of the exec family of functions.

NOTE: vfork() is not an independent NuttX feature, but is implemented in architecture-specific logic (using only helper functions from the NuttX core logic). As a result, vfork() may not be available on all architectures.

Returns:

Upon successful completion, vfork() returns 0 to the child process and returns the process ID of the child process to the parent process. Otherwise, -1 is returned to the parent, no child process is created, and errno is set to indicate the error.

POSIX Compatibility: Compatible with the BSD/Linux interface of the same name. POSIX marks this interface as Obsolete.

int exec(FAR const char *filename, FAR char *const *argv, FAR const struct symtab_s *exports, int nexports)

This non-standard, NuttX function is similar to execv() and posix_spawn() but differs in the following ways;

  • Unlike execv() and posix_spawn() this function accepts symbol table information as input parameters. This means that the symbol table used to link the application prior to execution is provided by the caller, not by the system.

  • Unlike execv(), this function always returns.

This non-standard interface is included as a official NuttX API only because it is needed in certain build modes: exec() is probably the only want to load programs in the PROTECTED mode. Other file execution APIs rely on a symbol table provided by the OS. In the PROTECTED build mode, the OS cannot provide any meaningful symbolic information for execution of code in the user-space blob so that is the exec() function is really needed in that build case

The interface is available in the FLAT build mode although it is not really necessary in that case. It is currently used by some example code under the apps/ that that generate their own symbol tables for linking test programs. So although it is not necessary, it can still be useful.

The interface would be completely useless and will not be supported in the KERNEL build mode where the contrary is true: An application process cannot provide any meaning symbolic information for use in linking a different process.

NOTE: This function is flawed and useless without CONFIG_SCHED_ONEXIT and CONFIG_SCHED_HAVE_PARENT because without those features there is then no mechanism to unload the module once it exits.

Parameters:

  • filename – The path to the program to be executed. If CONFIG_LIB_ENVPATH is defined in the configuration, then this may be a relative path from the current working directory. Otherwise, path must be the absolute path to the program.

  • argv – A pointer to an array of string arguments. The end of the array is indicated with a NULL entry.

  • exports – The address of the start of the caller-provided symbol table. This symbol table contains the addresses of symbols exported by the caller and made available for linking the module into the system.

  • nexports – The number of symbols in the exports table.

Returns:

Zero (OK) is returned on success; On any failure, exec() will return -1 (ERROR) and will set the errno value appropriately.

POSIX Compatibility: This is a non-standard interface unique to NuttX. Motivation for inclusion of this non-standard interface in certain build modes is discussed above.

int execv(FAR const char *path, FAR char *const argv[])

The standard exec family of functions will replace the current process image with a new process image. The new image will be constructed from a regular, executable file called the new process image file. There will be no return from a successful exec, because the calling process image is overlaid by the new process image.

Simplified execl() and execv() functions are provided by NuttX for compatibility. NuttX is a tiny embedded RTOS that does not support processes and hence the concept of overlaying a tasks process image with a new process image does not make any sense. In NuttX, these functions are wrapper functions that:

  1. Call the non-standard binfmt function exec(), and then

  2. exit(0).

Note the inefficiency when execv() or execl() is called in the normal, two-step process: (1) first call vfork() to create a new thread, then (2) call execv() or execl() to replace the new thread with a program from the file system. Since the new thread will be terminated by the execv() or execl() call, it really served no purpose other than to support POSIX compatibility.

The non-standard binfmt function exec() needs to have (1) a symbol table that provides the list of symbols exported by the base code, and (2) the number of symbols in that table. This information is currently provided to exec() from execv() or execl() via NuttX configuration settings:

  • CONFIG_LIBC_EXECFUNCS: Enable execv() and execl() support

  • CONFIG_EXECFUNCS_SYMTAB_ARRAY: Name of the symbol table used by execv() or execl().

  • CONFIG_EXECFUNCS_NSYMBOLS_VAR: Name of the int variable holding the number of symbols in the symbol table

As a result of the above, the current implementations of execl() and execv() suffer from some incompatibilities that may or may not be addressed in a future version of NuttX. Other than just being an inefficient use of MCU resource, the most serious of these is that the exec’ed task will not have the same task ID as the vfork’ed function. So the parent function cannot know the ID of the exec’ed task.

Parameters:

  • path – The path to the program to be executed. If CONFIG_LIB_ENVPATH is defined in the configuration, then this may be a relative path from the current working directory. Otherwise,

  • path – must be the absolute path to the program.

Returns:

This function does not return on success. On failure, it will return -1 (ERROR) and will set the errno value appropriately.

POSIX Compatibility: Similar with the POSIX interface of the same name. There are, however, several compatibility issues as detailed in the description above.

int execl(FAR const char *path, ...)

execl() is functionally equivalent to execv(), differing only in the form of its input parameters. See the description of execv() for additional information.

Parameters:

  • path – The path to the program to be executed. If CONFIG_LIB_ENVPATH is defined in the configuration, then this may be a relative path from the current working directory. Otherwise,

  • path – must be the absolute path to the program.

Returns:

This function does not return on success. On failure, it will return -1 (ERROR) and will set the errno value appropriately.

POSIX Compatibility: Similar with the POSIX interface of the same name. There are, however, several compatibility issues as detailed in the description of execv().

int posix_spawn(FAR pid_t *pid, FAR const char *path, FAR const posix_spawn_file_actions_t *file_actions, FAR const posix_spawnattr_t *attr, FAR char *const argv[], FAR char *const envp[])
int posix_spawnp(FAR pid_t *pid, FAR const char *file, FAR const posix_spawn_file_actions_t *file_actions, FAR const posix_spawnattr_t *attr, FAR char *const argv[], FAR char *const envp[]);

The posix_spawn() and posix_spawnp() functions will create a new, child task, constructed from a regular executable file.

Parameters:

  • pid – Upon successful completion, posix_spawn() and posix_spawnp() will return the task ID of the child task to the parent task, in the variable pointed to by a non-NULL pid argument. If the pid argument is a null pointer, the process ID of the child is not returned to the caller.

  • path –

    The path argument to posix_spawn() is the absolute path that identifies the file to execute. The file argument to posix_spawnp() may also be a relative path and will be used to construct a pathname that identifies the file to execute. In the case of a relative path, the path prefix for the file will be obtained by a search of the directories passed as the environment variable PATH.

    NOTE: NuttX provides only one implementation: If CONFIG_LIB_ENVPATH is defined, then only posix_spawnp() behavior is supported; otherwise, only posix_spawn behavior is supported.

  • file_actions – If file_actions is a null pointer, then file descriptors open in the calling process will remain open in the child process (unless CONFIG_FDCLONE_STDIO is defined). If file_actions is not NULL, then the file descriptors open in the child process will be those open in the calling process as modified by the spawn file actions object pointed to by file_actions.

  • attr –

    If the value of the attr parameter is NULL, the all default values for the POSIX spawn attributes will be used. Otherwise, the attributes will be set according to the spawn flags. The posix_spawnattr_t spawn attributes object type is defined in spawn.h. It will contains these attributes, not all of which are supported by NuttX:

    • POSIX_SPAWN_SETPGROUP: Setting of the new task’s process group is not supported. NuttX does not support process groups.

    • POSIX_SPAWN_SETSCHEDPARAM: Set new tasks priority to the sched_param value.

    • POSIX_SPAWN_SETSCHEDULER: Set the new task’s scheduler policy to the sched_policy value.

    • POSIX_SPAWN_RESETIDS Resetting of the effective user ID of the child process is not supported. NuttX does not support effective user IDs.

    • POSIX_SPAWN_SETSIGMASK: Set the new task’s signal mask.

    • POSIX_SPAWN_SETSIGDEF: Resetting signal default actions is not supported. NuttX does not support default signal actions.

  • argv – argv[] is the argument list for the new task. argv[] is an array of pointers to null-terminated strings. The list is terminated with a null pointer.

  • envp – The envp[] argument is not used by NuttX and may be NULL. In standard implementations, envp[] is an array of character pointers to null-terminated strings that provide the environment for the new process image. The environment array is terminated by a null pointer. In NuttX, the envp[] argument is ignored and the new task will inherit the environment of the parent task unconditionally.

Returns:

Zero on success. Otherwise, an error number will be returned as the function return value to indicate the error:

  • EINVAL: The value specified by file_actions or attr is invalid.

  • Any errors that might have been return if vfork() and exec[l|v]() had been called.

Assumptions/Limitations:

  • NuttX provides only posix_spawn() or posix_spawnp() behavior depending upon the setting of CONFIG_LIB_ENVPATH: If CONFIG_LIB_ENVPATH is defined, then only posix_spawnp() behavior is supported; otherwise, only posix_spawn() behavior is supported.

  • The envp argument is not used and the environ variable is not altered (NuttX does not support the environ variable).

  • Process groups are not supported (See POSIX_SPAWN_SETPGROUP above).

  • Effective user IDs are not supported (See POSIX_SPAWN_RESETIDS above).

  • Signal default actions cannot be modified in the newly task executed because NuttX does not support default signal actions (See POSIX_SPAWN_SETSIGDEF).

POSIX Compatibility: The value of the argv[0] received by the child task is assigned by NuttX. For the caller of posix_spawn(), the provided argv[0] will correspond to argv[1] received by the new task.

int posix_spawn_file_actions_init(FAR posix_spawn_file_actions_t *file_actions)

Initializes the object referenced by file_actions to an empty set of file actions for subsequent use in a call to posix_spawn() or posix_spawnp().

Input Parameters:

  • file_actions: The address of the posix_spawn_file_actions_t to be initialized.

Returned Value: On success, this function returns 0; on failure it will return an error number from <errno.h>.

int posix_spawn_file_actions_destroy(FAR posix_spawn_file_actions_t *file_actions)

Destroys the object referenced by file_actions which was previously initialized by posix_spawn_file_actions_init(), returning any resources obtained at the time of initialization to the system for subsequent reuse. A posix_spawn_file_actions_t may be reinitialized after having been destroyed, but must not be reused after destruction, unless it has been reinitialized.

Parameters:

  • file_actions – The address of the posix_spawn_file_actions_t to be destroyed.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawn_file_actions_addclose(FAR posix_spawn_file_actions_t *file_actions, int fd)

Adds a close operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). The descriptor referred to by fd is closed as if close() had been called on it prior to the new child process starting execution.

Parameters:

  • file_actions – The address of the posix_spawn_file_actions_t object to which the close operation will be appended.

  • fd – The file descriptor to be closed.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawn_file_actions_adddup2(FAR posix_spawn_file_actions_t *file_actions, int fd1, int fd2)

Adds a dup2 operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). The descriptor referred to by fd2 is created as if dup2() had been called on fd1 prior to the new child process starting execution.

Parameters:

  • file_actions – The address of the posix_spawn_file_actions_t object to which the dup2 operation will be appended.

  • fd1 – The file descriptor to be be duplicated. The first file descriptor to be argument to dup2().

  • fd2 – The file descriptor to be be created. The second file descriptor to be argument to dup2().

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawn_file_actions_addopen(FAR posix_spawn_file_actions_t *file_actions, int fd, FAR const char *path, int oflags, mode_t mode);

Adds an open operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). The descriptor referred to by fd is opened using the path, oflag, and mode arguments as if open() had been called on it prior to the new child process starting execution. The string path is copied by the posix_spawn_file_actions_addopen() function during this process, so storage need not be persistent in the caller.

Parameters:

  • file_actions – The address of the posix_spawn_file_actions_t object to which the open operation will be appended.

  • fd – The file descriptor to be opened.

  • path – The path to be opened.

  • oflags – Open flags.

  • mode – File creation mode/

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_init(FAR posix_spawnattr_t *attr)

The posix_spawnattr_init() function initializes the object referenced by attr, to an empty set of spawn attributes for subsequent use in a call to posix_spawn() or posix_spawnp().

Then the spawn attributes are no longer needed, they should be destroyed by calling posix_spawnattr_destroyed(). In NuttX, however, posix_spawnattr_destroyed() is just stub:

For portability, the convention of calling posix_spawnattr_destroyed() when the attributes are not longer needed should still be followed.

Parameters:

  • attr – The address of the spawn attributes to be initialized.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_getflags(FAR const posix_spawnattr_t *attr, FAR short *flags)

The posix_spawnattr_getflags() function will obtain the value of the spawn-flags attribute from the attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be queried.

  • flags – The location to return the spawn flags

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_getschedparam(FAR const posix_spawnattr_t *attr, FAR struct sched_param *param)

The posix_spawnattr_getschedparam() function will obtain the value of the spawn-schedparam attribute from the attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be queried.

  • param – The location to return the spawn-schedparam value.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_getschedpolicy(FAR const posix_spawnattr_t *attr, FAR int *policy)

The posix_spawnattr_getschedpolicy() function will obtain the value of the spawn-schedpolicy attribute from the attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be queried.

  • policy – The location to return the spawn-schedpolicy value.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_getsigmask(FAR const posix_spawnattr_t *attr, FAR sigset_t *sigmask)

posix_spawnattr_getsigdefault() function will obtain the value of the spawn-sigmask attribute from the attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be queried.

  • sigmask – The location to return the spawn-sigmask value.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_setflags(FAR posix_spawnattr_t *attr, short flags)

The posix_spawnattr_setflags() function will set the spawn-flags attribute in an initialized attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be used.

  • flags – The new value of the spawn-flags attribute.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_setschedparam(FAR posix_spawnattr_t *attr, FAR const struct sched_param *param)

The posix_spawnattr_setschedparam() function will set the spawn-schedparam attribute in an initialized attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be used.

  • param – The new value of the spawn-schedparam attribute.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_setschedpolicy(FAR posix_spawnattr_t *attr, int policy)

The posix_spawnattr_setschedpolicy() function will set the spawn-schedpolicy attribute in an initialized attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be used.

  • policy – The new value of the spawn-schedpolicy attribute.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int posix_spawnattr_setsigmask(FAR posix_spawnattr_t *attr, FAR const sigset_t *sigmask)

The posix_spawnattr_setsigmask() function will set the spawn-sigmask attribute in an initialized attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be used.

  • sigmask – The new value of the spawn-sigmask attribute.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int task_spawn(FAR pid_t *pid, FAR const char *name, main_t entry, FAR const posix_spawn_file_actions_t *file_actions, FAR const posix_spawnattr_t *attr, FAR char *const argv[], FAR char *const envp[])

The task_spawn() function will create a new, child task, where the entry point to the task is an address in memory.

Parameters:

  • pid – Upon successful completion, task_spawn() will return the task ID of the child task to the parent task, in the variable pointed to by a non-NULL pid argument. If the pid argument is a null pointer, the process ID of the child is not returned to the caller.

  • name – The name to assign to the child task.

  • entry – The child task’s entry point (an address in memory).

  • file_actions – If file_actions is a null pointer, then file descriptors open in the calling process will remain open in the child process (unless CONFIG_FDCLONE_STDIO is defined). If file_actions is not NULL, then the file descriptors open in the child process will be those open in the calling process as modified by the spawn file actions object pointed to by file_actions.

  • attr –

    If the value of the attr parameter is NULL, the all default values for the POSIX spawn attributes will be used. Otherwise, the attributes will be set according to the spawn flags. The posix_spawnattr_t spawn attributes object type is defined in spawn.h. It will contains these attributes, not all of which are supported by NuttX:

    • POSIX_SPAWN_SETPGROUP: Setting of the new task’s process group is not supported. NuttX does not support process groups.

    • POSIX_SPAWN_SETSCHEDPARAM: Set new tasks priority to the sched_param value.

    • POSIX_SPAWN_SETSCHEDULER: Set the new task’s scheduler policy to the sched_policy value.

    • POSIX_SPAWN_RESETIDS Resetting of the effective user ID of the child process is not supported. NuttX does not support effective user IDs.

    • POSIX_SPAWN_SETSIGMASK: Set the new task’s signal mask.

    • POSIX_SPAWN_SETSIGDEF: Resetting signal default actions is not supported. NuttX does not support default signal actions.

    And the non-standard:

    • TASK_SPAWN_SETSTACKSIZE: Set the stack size for the new task.

  • argv – argv[] is the argument list for the new task. argv[] is an array of pointers to null-terminated strings. The list is terminated with a null pointer.

  • envp – The envp[] argument is not used by NuttX and may be NULL.

Returns:

task_spawn() will return zero on success. Otherwise, an error number will be returned as the function return value to indicate the error:

POSIX Compatibility: This is a non-standard interface inspired by posix_spawn().

int task_spawnattr_getstacksize(FAR const posix_spawnattr_t *attr, FAR size_t *stacksize)

The task_spawnattr_getstacksize() function will obtain the value of the spawn-stacksize attribute from the attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be queried.

  • policy – The location to return the spawn-stacksize value.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>

int task_spawnattr_setstacksize(FAR posix_spawnattr_t *attr, size_t stacksize)

The task_spawnattr_setstacksize() function will set the spawn-stacksize attribute in an initialized attributes object referenced by attr.

Parameters:

  • attr – The address spawn attributes to be used.

  • policy – The new value of the spawn-stacksize attribute.

Returns:

On success, this function returns 0; on failure it will return an error number from <errno.h>