User's Manual
by
Gregory Nutt
-
Last Updated: January 8, 2013
+Last Updated: January 11, 2013
@@ -193,18 +193,52 @@ paragraphs.Task Control Interfaces. The following task control interfaces are provided by NuttX:
++ Non-standard task control interfaces inspired by VxWorks interfaces: +
+ Standard interfaces +
+ +
+ Standard vfork and exec[v|l] interfaces:
+
+ Standard posix_spawn interfaces:
+
task_delete() will re-direct processing to exit().
--Function Prototype: -
- #include <sched.h> - void exit(int code); - - #include <nuttx/unistd.h> - void _exit(int code); -- -
-Description: This function 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().
-
-Input Parameters: -
code. (ignored)
--Returned Value: None. - -
-Assumptions/Limitations: - -
-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: -
-code parameter is ignored.
-Function Prototype:
@@ -588,6 +576,52 @@ VxWorks provides the following similar interface:
+Function Prototype: +
+ #include <sched.h> + void exit(int code); + + #include <nuttx/unistd.h> + void _exit(int code); ++ +
+Description: This function 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().
+
+Input Parameters: +
code. (ignored)
++Returned Value: None. + +
+Assumptions/Limitations: + +
+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: +
+code parameter is ignored.
+@@ -780,6 +814,595 @@ int execl(FAR const char *path, ...); There are, however, several compatibility issues as detailed in the description of execv().
++ Function Prototype: +
++#include <spawn.h> +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[]); ++
+ Description:
+ The posix_spawn() and posix_spawnp() functions will create a new, child task, constructed from a regular executable file.
+
++ Input 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 or file:
+ 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_BINFMT_EXEPATH 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.
+ Returned Value:
+ posix_spawn() and posix_spawnp() will 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.
+ vfork() and excec[l|v]() had been called.
+ + Assumptions/Limitations: +
+posix_spawn() or posix_spawnp() behavior depending upon the setting of CONFIG_BINFMT_EXEPATH:
+ If CONFIG_BINFMT_EXEPATH is defined, then only posix_spawnp() behavior is supported; otherwise, only posix_spawn() behavior is supported.
+ envp argument is not used and the environ variable is not altered (NuttX does not support the environ variable).
+ POSIX_SPAWN_SETPGROUP above).
+ POSIX_SPAWN_RESETIDS above).
+ 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.
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawn_file_actions_init(FAR posix_spawn_file_actions_t *file_actions); ++
+ Description:
+ 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().
+
+ 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>.
+
+ +
+ Function Prototype: +
++#include <spawn.h> +int posix_spawn_file_actions_destroy(FAR posix_spawn_file_actions_t *file_actions); ++
+ Description:
+ The posix_spawn_file_actions_destroy() function destroys the object referenced by file_actions which was previously intialized 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.
+
+ Input Parameters: +
+file_actions:
+ The address of the posix_spawn_file_actions_t to be destroyed.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ +
+ Function Prototype: +
++#include <spawn.h> +int posix_spawn_file_actions_addclose(FAR posix_spawn_file_actions_t *file_actions, int fd); ++
+ Description:
+ The posix_spawn_file_actions_addclose() function 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.
+
+ Input 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.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawn_file_actions_adddup2(FAR posix_spawn_file_actions_t *file_actions, int fd1, int fd2); ++
+ Description:
+ The posix_spawn_file_actions_adddup2() function 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.
+
+ Input 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().
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.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); ++
+ Description:
+ The posix_spawn_file_actions_addopen() function 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.
+
+ Input 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/
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_init(FAR posix_spawnattr_t *attr); ++
+ Description:
+ 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:
+
+#define posix_spawnattr_destroy(attr) (0) ++
+ For portability, the convention of calling posix_spawnattr_destroyed() when the attributes are not longer needed should still be followed.
+
+ Input Parameters: +
+attr:
+ The address of the spawn attributes to be initialized.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_getflags(FAR const posix_spawnattr_t *attr, FAR short *flags); ++
+ Description:
+ The posix_spawnattr_getflags() function will obtain the value of the spawn-flags attribute from the attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be queried.
+ flags:
+ The location to return the spawn flags
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_getschedparam(FAR const posix_spawnattr_t *attr, FAR struct sched_param *param); ++
+ Description:
+ The posix_spawnattr_getschedparam() function will obtain the value of the spawn-schedparam attribute from the attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be queried.
+ param:
+ The location to return the spawn-schedparam value.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_getschedpolicy(FAR const posix_spawnattr_t *attr, FAR int *policy); ++
+ Description:
+ The posix_spawnattr_getschedpolicy() function will obtain the value of the spawn-schedpolicy attribute from the attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be queried.
+ policy:
+ The location to return the spawn-schedpolicy value.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +#ifndef CONFIG_DISABLE_SIGNALS +int posix_spawnattr_getsigmask(FAR const posix_spawnattr_t *attr, FAR sigset_t *sigmask); +#endif ++
+ Description:
+ The posix_spawnattr_getsigdefault() function will obtain the value of the spawn-sigmask attribute from the attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be queried.
+ sigmask:
+ The location to return the spawn-sigmask value.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_setflags(FAR posix_spawnattr_t *attr, short flags); ++
+ Description:
+ The posix_spawnattr_setflags() function will set the spawn-flags attribute in an initialized attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be used.
+ flags:
+ The new value of the spawn-flags attribute.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_setschedparam(FAR posix_spawnattr_t *attr, FAR const struct sched_param *param); ++
+ Description:
+ The posix_spawnattr_setschedparam() function will set the spawn-schedparam attribute in an initialized attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be used.
+ param:
+ The new value of the spawn-schedparam attribute.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +int posix_spawnattr_setschedpolicy(FAR posix_spawnattr_t *attr, int policy); ++
+ Description:
+ The posix_spawnattr_setschedpolicy() function will set the spawn-schedpolicy attribute in an initialized attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be used.
+ policy:
+ The new value of the spawn-schedpolicy attribute.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
+ Function Prototype: +
++#include <spawn.h> +#ifndef CONFIG_DISABLE_SIGNALS +int posix_spawnattr_setsigmask(FAR posix_spawnattr_t *attr, FAR const sigset_t *sigmask); +#endif ++
+ Description:
+ The posix_spawnattr_setsigmask() function will set the spawn-sigmask attribute in an initialized attributes object referenced by attr.
+
+ Input Parameters: +
+attr:
+ The address spawn attributes to be used.
+ sigmask:
+ The new value of the spawn-sigmask attribute.
+
+ Returned Value:
+ On success, this function returns 0; on failure it will return an error number from <errno.h>
+
|
@@ -8395,13 +9018,30 @@ notify a task when a message is available on a queue.
|
-
|
+
+ |
+
|
-
|