876 lines
38 KiB
ReStructuredText
876 lines
38 KiB
ReStructuredText
=======================
|
|
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 <#Pthread>`__ 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 <NuttXBinfmt.html>`__ and `NXFLAT <NuttXNxFlat.html#binfmt>`__.
|
|
|
|
**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:
|
|
|
|
- :c:func:`task_create`
|
|
- :c:func:`task_delete`
|
|
- :c:func:`task_restart`
|
|
|
|
Non-standard extensions to VxWorks-like interfaces to support POSIX
|
|
`Cancellation
|
|
Points <https://cwiki.apache.org/confluence/display/NUTTX/Cancellation+Points>`__.
|
|
|
|
- :c:func:`task_setcancelstate`
|
|
- :c:func:`task_setcanceltype`
|
|
- :c:func:`task_testcancel`
|
|
|
|
Standard interfaces
|
|
|
|
- :c:func:`exit`
|
|
- :c:func:`getpid`
|
|
|
|
Standard ``vfork`` and ``exec[v|l]`` interfaces:
|
|
|
|
- :c:func:`vfork`
|
|
- :c:func:`exec`
|
|
- :c:func:`execv`
|
|
- :c:func:`execl`
|
|
|
|
Standard ``posix_spawn`` interfaces:
|
|
|
|
- :c:func:`posix_spawn` and :c:func:`posix_spawnp`
|
|
- :c:func:`posix_spawn_file_actions_init`
|
|
- :c:func:`posix_spawn_file_actions_destroy`
|
|
- :c:func:`posix_spawn_file_actions_addclose`
|
|
- :c:func:`posix_spawn_file_actions_adddup2`
|
|
- :c:func:`posix_spawn_file_actions_addopen`
|
|
- :c:func:`posix_spawnattr_init`
|
|
- :c:func:`posix_spawnattr_getflags`
|
|
- :c:func:`posix_spawnattr_getschedparam`
|
|
- :c:func:`posix_spawnattr_getschedpolicy`
|
|
- :c:func:`posix_spawnattr_getsigmask`
|
|
- :c:func:`posix_spawnattr_setflags`
|
|
- :c:func:`posix_spawnattr_setschedparam`
|
|
- :c:func:`posix_spawnattr_setschedpolicy`
|
|
- :c:func:`posix_spawnattr_setsigmask`
|
|
|
|
Non-standard task control interfaces inspired by ``posix_spawn``:
|
|
|
|
- :c:func:`task_spawn`
|
|
- :c:func:`task_spawnattr_getstacksize`
|
|
- :c:func:`task_spawnattr_setstacksize`
|
|
- :c:func:`posix_spawn_file_actions_init`
|
|
|
|
Functions
|
|
---------
|
|
|
|
.. c:function:: 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 :c:func:`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 :c:func:`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.
|
|
|
|
:param name: Name of the new task
|
|
:param priority: Priority of the new task
|
|
:param stack_size: size (in bytes) of the stack needed
|
|
:param entry: Entry point of a new task
|
|
:param 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.
|
|
|
|
:return: 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:
|
|
|
|
.. code-block:: c
|
|
|
|
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 :c:func:`task_create` differs from VxWorks' :c:func:`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).
|
|
|
|
.. c:function:: 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 <https://cwiki.apache.org/confluence/display/NUTTX/Cancellation+Points>`__
|
|
enabled).
|
|
|
|
:param 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()``.
|
|
|
|
:return: ``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()``.
|
|
|
|
.. :c:funcion:: int task_restart(pid_t pid)
|
|
|
|
This function *restarts* a task. The task is first
|
|
terminated and then reinitialized with same ID, priority, original entry
|
|
point, stack size, and parameters it had when it was first started.
|
|
|
|
**NOTES:**
|
|
|
|
#. The normal task exit clean up is not performed. For example, file
|
|
descriptors are not closed; any files opened prior to the restart
|
|
will remain opened after the task is restarted.
|
|
#. Memory allocated by the task before it was restart is not freed. A
|
|
task that is subject to being restart must be designed in such a way
|
|
as to avoid memory leaks.
|
|
#. Initialized data is not reset. All global or static data is left in
|
|
the same state as when the task was terminated. This *feature* may be
|
|
used by restart task to detect that it has been restarted, for
|
|
example.
|
|
|
|
:param pid: The task ID of the task to delete. An ID of zero would
|
|
signify the calling task (However, support for a task to restart
|
|
itself has not been implemented).
|
|
|
|
:return: ``OK``, or ``ERROR`` if the task ID is invalid or the task could not be
|
|
restarted. This function can fail if: (1) A pid of zero or the pid of
|
|
the calling task is provided (functionality not implemented) (2) The
|
|
pid is not associated with any task known to the system.
|
|
|
|
**POSIX Compatibility:** This is a NON-POSIX interface. VxWorks provides
|
|
the following similar interface:
|
|
|
|
.. code-block:: c
|
|
|
|
STATUS taskRestart (int tid);
|
|
|
|
The NuttX :c:func:`task_restart` differs from VxWorks' :c:func:`taskRestart` in the
|
|
following ways:
|
|
|
|
- Restart of the currently running task is not supported by NuttX.
|
|
- The VxWorks description says that the ID, priority, etc. take the
|
|
value that they had when the task was *terminated*.
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param state: New cancellation state. One of PTHREAD_CANCEL_ENABLE or
|
|
PTHREAD_CANCEL_DISABLE.
|
|
:param oldstate: Location to return the previous cancellation state.
|
|
|
|
:return: 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()``.
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param type: New cancellation state. One of ``PTHREAD_CANCEL_DEFERRED``
|
|
or ``PTHREAD_CANCEL_ASYNCHRONOUS``.
|
|
:param oldtype: Location to return the previous cancellation type.
|
|
|
|
:return: 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()``.
|
|
|
|
.. c:function:: void task_testcancel(void)
|
|
|
|
Creates a `Cancellation
|
|
Point <https://cwiki.apache.org/confluence/display/NUTTX/Cancellation+Points>`__
|
|
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()``.
|
|
|
|
.. c:function:: void exit(int code)
|
|
.. c:function:: void _exit(int code)
|
|
|
|
.. #include <sched.h>
|
|
.. #include <nuttx/unistd.h>
|
|
|
|
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()``.
|
|
|
|
:param 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.
|
|
|
|
.. c:function:: pid_t getpid(void)
|
|
|
|
.. #include <unistd.h>
|
|
|
|
Returns the task ID of the calling task.
|
|
The task ID will be invalid if called at the interrupt level.
|
|
|
|
:return: The task ID of the calling task.
|
|
|
|
**POSIX Compatibility:** Compatible with the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: 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.
|
|
|
|
:return: 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.
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param 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.
|
|
:param argv: A pointer to an array of string arguments. The end of the
|
|
array is indicated with a NULL entry.
|
|
:param 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.
|
|
:param nexports: The number of symbols in the ``exports`` table.
|
|
|
|
:return: 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.
|
|
|
|
.. c:function:: 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:
|
|
|
|
#. Call the non-standard ``binfmt`` function ``exec()``, and then
|
|
#. ``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.
|
|
|
|
:param 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,
|
|
:param path: must be the absolute path to the program.
|
|
|
|
:return: 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.
|
|
|
|
.. c:function:: int execl(FAR const char *path, ...)
|
|
|
|
``execl()`` is functionally equivalent to
|
|
`execv() <#execv>`__, differing only in the form of its input
|
|
parameters. See the description of `execv() <#execv>`__ for additional
|
|
information.
|
|
|
|
:param 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,
|
|
:param path: must be the absolute path to the program.
|
|
|
|
:return: 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() <#execv>`__.
|
|
|
|
.. c:function:: 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[])
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param 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.
|
|
|
|
:param 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.
|
|
|
|
:param 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``.
|
|
|
|
:param 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.
|
|
|
|
:param 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.
|
|
|
|
:param 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.
|
|
|
|
:return: 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.
|
|
|
|
.. c:function:: 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>``.
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param file_actions: The address of the ``posix_spawn_file_actions_t``
|
|
to be destroyed.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param file_actions: The address of the ``posix_spawn_file_actions_t``
|
|
object to which the *close* operation will be appended.
|
|
:param fd: The file descriptor to be closed.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param file_actions: The address of the ``posix_spawn_file_actions_t``
|
|
object to which the *dup2* operation will be appended.
|
|
:param fd1: The file descriptor to be be duplicated. The first file
|
|
descriptor to be argument to ``dup2()``.
|
|
:param fd2: The file descriptor to be be created. The second file
|
|
descriptor to be argument to ``dup2()``.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param file_actions: The address of the ``posix_spawn_file_actions_t``
|
|
object to which the *open* operation will be appended.
|
|
:param fd: The file descriptor to be opened.
|
|
:param path: The path to be opened.
|
|
:param oflags: Open flags.
|
|
:param mode: File creation mode/
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param attr: The address of the spawn attributes to be initialized.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be queried.
|
|
:param flags: The location to return the spawn flags
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be queried.
|
|
:param param: The location to return the *spawn-schedparam* value.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be queried.
|
|
:param policy: The location to return the *spawn-schedpolicy* value.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be queried.
|
|
:param sigmask: The location to return the *spawn-sigmask* value.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be used.
|
|
:param flags: The new value of the *spawn-flags* attribute.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be used.
|
|
:param param: The new value of the *spawn-schedparam* attribute.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be used.
|
|
:param policy: The new value of the *spawn-schedpolicy* attribute.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be used.
|
|
:param sigmask: The new value of the *spawn-sigmask* attribute.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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.
|
|
|
|
:param 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.
|
|
|
|
:param name: The name to assign to the child task.
|
|
|
|
:param entry: The child task's entry point (an address in memory).
|
|
|
|
:param 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``.
|
|
|
|
:param 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.
|
|
|
|
:param 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.
|
|
|
|
:param envp: The ``envp[]`` argument is not used by NuttX and may be
|
|
``NULL``.
|
|
|
|
:return: ``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()``.
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be queried.
|
|
:param policy: The location to return the *spawn-stacksize* value.
|
|
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|
|
|
|
.. c:function:: 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``.
|
|
|
|
:param attr: The address spawn attributes to be used.
|
|
:param policy: The new value of the *spawn-stacksize* attribute.
|
|
:return: On success, this function returns 0; on failure it
|
|
will return an error number from ``<errno.h>``
|