CONFIG_SIG_SIGWORK: The signal number that will be used to wake-up
the worker thread. Default: 4
+
+ CONFIG_SCHED_WAITPID: Enables the waitpid() API
+ CONFIG_SCHED_ATEXIT: Enables the atexit() API
+ CONFIG_SCHED_ATEXIT_MAX: By default if CONFIG_SCHED_ATEXIT is selected, only a single atexit() function is supported.
+ That number can be increased by defined this setting to the number that you require.
+ CONFIG_SCHED_ONEXIT: Enables the on_exit() API
+ CONFIG_SCHED_ONEXIT_MAX: By default if CONFIG_SCHED_ONEXIT is selected, only a single on_exit() function is supported.
+ That number can be increased by defined this setting to the number that you require.
+ diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html index 9d3af1c270d..457347727ce 100644 --- a/Documentation/NuttxUserGuide.html +++ b/Documentation/NuttxUserGuide.html @@ -13,7 +13,7 @@
User's Manual
by
Gregory Nutt
-
Last Updated: March 23, 2012
+Last Updated: August 1, 2012
@@ -54,7 +54,7 @@
- 2.3 Task Switching Interfaces+2.3 Task Control Interfaces |
Scheduler locking interfaces
+Task synchronization interfaces
++Function Prototype: +
+ #include <sys/wait.h> + ipid_t waitpid(pid_t pid, int *stat_loc, int options); ++ +
+ Description: +
++ The following discussion is a general description of the+waitpid() interface. + However, as of this writing, the implementation ofwaitpid()is fragmentary (but usable). + It simply supports waiting for any task to complete execution. + NuttX does not support any concept of parent/child processes or of process groups nor signals related to child processes (SIGCHLD). + Nor does NuttX retain the status of exited tasks so ifwaitpid()is called after a task has exited, then no status will be available. + The options argument is currently ignored. +
+ The waitpid() functions will obtain status information pertaining to one of the caller's child processes.
+ The waitpid() function will suspend execution of the calling thread until status information for one of the terminated child processes of the calling process is available, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.
+ If more than one thread is suspended in waitpid() awaiting termination of the same process, exactly one thread will return the process status at the time of the target process termination.
+ If status information is available prior to the call to waitpid(), return will be immediate.
+
+ NOTE:
+ Because waitpid() is not fully POSIX compliant, it must be specifically enabled by setting CONFIG_SCHED_WAITPID in the NuttX configuration file.
+
+ Input Parameters: +
+pid. The task ID of the thread to waid forstat_loc. The location to return the exit statusoptions. ignored
+ The pid argument specifies a set of child processes for which status is requested.
+ The waitpid() function will only return the status of a child process from this set:
+
pid is equal to (pid_t)-1), status is requested for any child process.
+ In this respect, waitpid() is then equivalent to wait().
+ pid is greater than 0, it specifies the process ID of a single child process for which status is requested.
+ pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process.
+ pid is less than (pid_t)-1), status is requested for any child process whose process group ID is equal to the absolute value of pid.
+
+ The options argument is constructed from the bitwise-inclusive OR of zero or more of the following flags,
+ defined in the <sys/wait.h> header:
+
WCONTINUED.
+ The waitpid() function will report the status of any continued child process specified by pid whose status has not been reported since it continued from a job control stop.
+ WNOHANG.
+ The waitpid() function will not suspend execution of the calling thread if status is not immediately available for one of the child processes specified by pid.
+ WUNTRACED.
+ The status of any child processes specified by pid that are stopped, and whose status has not yet been reported since they stopped, will also be reported to the requesting process.
+
+ If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to SIG_IGN, and the process has no unwaited-for children that were transformed into zombie processes, the calling thread will block until all of the children of the process containing the calling thread terminate, and waitpid() will fail and set errno to ECHILD.
+
+ If waitpid() returns because the status of a child process is available, these functions will return a value equal to the process ID of the child process.
+ In this case, if the value of the argument stat_loc is not a null pointer, information will be stored in the location pointed to by stat_loc.
+ The value stored at the location pointed to by stat_loc will be 0 if and only if the status returned is from a terminated child process that terminated by one of the following means:
+
main().
+ _exit() or exit() with a status argument of 0.
+
+ Regardless of its value, this information may be interpreted using the following macros, which are defined in <sys/wait.h> and evaluate to integral expressions; the stat_val argument is the integer value pointed to by stat_loc.
+
WIFEXITED(stat_val).
+ Evaluates to a non-zero value if status was returned for a child process that terminated normally.
+ WEXITSTATUS(stat_val).
+ If the value of WIFEXITED(stat_val) is non-zero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to _exit() or exit(), or the value the child process returned from main().
+ WIFSIGNALED(stat_val).
+ Evaluates to a non-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught (see >signal.h<).
+ WTERMSIG(stat_val).
+ If the value of WIFSIGNALED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.
+ WIFSTOPPED(stat_val).
+ Evaluates to a non-zero value if status was returned for a child process that is currently stopped.
+ WSTOPSIG(stat_val).
+ If the value of WIFSTOPPED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop.
+ WIFCONTINUED(stat_val).
+ Evaluates to a non-zero value if status was returned for a child process that has continued from a job control stop.
+ + Returned Values: +
+
+ If waitpid() returns because the status of a child process is available, it will return a value equal to the process ID of the child process for which status is reported.
+
+ If waitpid() returns due to the delivery of a signal to the calling process, -1 will be returned and errno set to EINTR.
+
+ If waitpid() was invoked with WNOHANG set in options, it has at least one child process specified by pid for which status is not available, and status is not available for any process specified by pid, 0 is returned.
+
+ Otherwise, (pid_t)-1errno set to indicate the error:
+
ECHILD.
+ The process specified by pid does not exist or is not a child of the calling process, or the process group specified by pid does not exist or does not have any member process that is a child of the calling process.
+ EINTR.
+ The function was interrupted by a signal.
+ The value of the location pointed to by stat_loc is undefined.
+ EINVAL.
+ The options argument is not valid.
+ + Assumptions/Limitations: +
+ POSIX Compatibility: + Comparable to the POSIX interface of the same name, but the implementation is incomplete (as detailed above). +
+ ++Function Prototype: +
+ #include <stdlib.h> + int atexit(void (*func)(void)); ++
+ Description:
+ Registers a function to be called at program exit.
+ The atexit() function registers the given function to be called at normal process termination, whether via exit() or via return from the program's main().
+
+ NOTE: CONFIG_SCHED_ATEXIT must be defined to enable this function.
+
+ Input Parameters: +
+
+ Returned Values:
+ On success, atexit() returns OK (0).
+ On error, ERROR (-1) is returned, and errno is set to indicate the cause of the failure.
+
+ Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the ISO C interface of the same name. + Limitiations in the current implementation: +
+atexit function can be registered unless CONFIG_SCHED_ATEXIT_MAX defines a larger number.atexit() functions are not inherited when a new task is created.+Function Prototype: +
+ #include <stdlib.h> + int on_exit(CODE void (*func)(int, FAR void *), FAR void *arg) ++
+ Description:
+ Registers a function to be called at program exit.
+ The on_exit() function registers the given function to be called at normal process termination, whether via exit() or via return from the program's main().
+ The function is passed the status argument given to the last call to exit() and the arg argument from on_exit().
+
+ NOTE: CONFIG_SCHED_ONEXIT must be defined to enable this function
+
+ Input Parameters: +
+on_exit() function when the task exits.
+ Returned Values:
+ On success, on_exit() returns OK (0).
+ On error, ERROR (-1) is returned, and errno is set to indicate the cause of the failure.
+
+ Assumptions/Limitations: +
+ POSIX Compatibility:
+ This function comes from SunOS 4, but is also present in libc4, libc5 and glibc.
+ It no longer occurs in Solaris (SunOS 5).
+ Avoid this function, and use the standard atexit() instead.
+
on_exit function can be registered unless CONFIG_SCHED_ONEXIT_MAX defines a larger number.on_exit() functions are not inherited when a new task is created.| @@ -7833,6 +8087,7 @@ notify a task when a message is available on a queue. | ||
|
|
+ |
+ |