sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
4cb193d530
nuttx/Documentation/reference/user/01_task_control.rst
Brennan Ashton 4cb193d530 Docs: Update links to old website and wiki 
Signed-off-by: Brennan Ashton <bashton@brennanashton.com>
2020-08-30 19:16:30 -03:00

888 lines
39 KiB
ReStructuredText
Raw Blame History

=======================
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>``
.. c:function:: int posix_spawn_file_actions_init(FAR posix_spawn_file_actions_t *file_actions);
The ``posix_spawn_file_actions_init()`` function
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()``.
:param file_actions: The address of the ``posix_spawn_file_actions_t``
to be initialized.
:return: On success, this function returns 0; on failure it
will return an error number from ``<errno.h>``.
Reference in New Issue View Git Blame Copy Permalink