<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>change log for rtems (2011-01-10)</title>
</head>
<body text='#000000' bgcolor='#ffffff'>
<a name='cs1'></a>
<table border='0' cellspacing='0' cellpadding='5' width='100%' bgcolor='#eeeeee'>
<tr><td colspan='3' bgcolor='#dddddd'>
<font color='#bb2222'><strong>joel</strong></font>
</td></tr>
<tr><td colspan='3' bgcolor='#dddddd'><pre>2011-01-10 Danila Bespalov <danila DOT bespalov AT gmail DOT com>
* posix_users/posix_users.texi, posix_users/signal.t: Review and
improve as part of Google Code-In 2010.
</pre></td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/doc/ChangeLog.diff?r1=text&tr1=1.294&r2=text&tr2=1.295&diff_format=h">M</a></td><td width='1%'>1.295</td><td width='100%'>doc/ChangeLog</td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/doc/posix_users/posix_users.texi.diff?r1=text&tr1=1.18&r2=text&tr2=1.19&diff_format=h">M</a></td><td width='1%'>1.19</td><td width='100%'>doc/posix_users/posix_users.texi</td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/doc/posix_users/signal.t.diff?r1=text&tr1=1.7&r2=text&tr2=1.8&diff_format=h">M</a></td><td width='1%'>1.8</td><td width='100%'>doc/posix_users/signal.t</td></tr>
</table>
<pre>
<font color='#006600'>diff -u rtems/doc/ChangeLog:1.294 rtems/doc/ChangeLog:1.295
--- rtems/doc/ChangeLog:1.294 Sun Jan 2 10:12:02 2011
+++ rtems/doc/ChangeLog Mon Jan 10 10:14:07 2011
</font><font color='#997700'>@@ -1,3 +1,8 @@
</font><font color='#000088'>+2011-01-10 Danila Bespalov <danila DOT bespalov AT gmail DOT com>
+
+ * posix_users/posix_users.texi, posix_users/signal.t: Review and
+ improve as part of Google Code-In 2010.
+
</font> 2011-01-02 Danila Bespalov <danila DOT bespalov AT gmail DOT com>
* started/buildc.t, started/buildrt.t, started/nt.t, started/require.t,
<font color='#006600'>diff -u rtems/doc/posix_users/posix_users.texi:1.18 rtems/doc/posix_users/posix_users.texi:1.19
--- rtems/doc/posix_users/posix_users.texi:1.18 Thu Jun 21 13:53:00 2007
+++ rtems/doc/posix_users/posix_users.texi Mon Jan 10 10:14:07 2011
</font><font color='#997700'>@@ -16,7 +16,7 @@
</font> @c
@c
<font color='#880000'>-@c Master file for the C User's Guide
</font><font color='#000088'>+@c Master file for the POSIX API User's Guide
</font> @c
@c Joel's Questions
<font color='#997700'>@@ -43,7 +43,7 @@
</font> @c in the infrastructure Florist support should be simple to add.
@set is-C
@clear is-Ada
<font color='#880000'>-@set LANGUAGE C<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+@set LANGUAGE C
</font> @set STRUCTURE structure
@set ROUTINE function
@set OR |
<font color='#997700'>@@ -63,7 +63,7 @@
</font> @c @shorttitlepage RTEMS POSIX API User's Guide
@setchapternewpage odd
<font color='#880000'>-@settitle RTEMS POSIX API User's Guide<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+@settitle RTEMS POSIX API User's Guide
</font> @titlepage
@finalout
<font color='#997700'>@@ -139,8 +139,8 @@
</font> @end menu
@end ifinfo
<font color='#880000'>-@c<span style="background-color: #FF0000"> </span>
-@c<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+@c
+@c
</font> @c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
@c
<font color='#006600'>diff -u rtems/doc/posix_users/signal.t:1.7 rtems/doc/posix_users/signal.t:1.8
--- rtems/doc/posix_users/signal.t:1.7 Fri Jan 9 17:39:14 2004
+++ rtems/doc/posix_users/signal.t Mon Jan 10 10:14:07 2011
</font><font color='#997700'>@@ -56,8 +56,9 @@
</font> the signal or explicitly checks for it.
Traditional, non-real-time POSIX signals do not queue. Thus
if a process or thread has blocked a particular signal, then
<font color='#880000'>-multiple occurrences of that signal are recorded as a<span style="background-color: #FF0000"> </span>
-single occurrence of that signal.<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+multiple occurrences of that signal are recorded as a
+single occurrence of that signal.
+@c TODO: SIGRTMIN and SIGRTMAX ?
</font>
One can check for the set of outstanding signals that have been
blocked. Services are provided to check for outstanding process
<font color='#997700'>@@ -102,22 +103,22 @@
</font> Each process and each thread within that process has a set of
individual signals and handlers associated with it. Services
are provided to construct signal sets for the purposes of building
<font color='#880000'>-signal sets -- type @code{sigset_t} -- that are used to<span style="background-color: #FF0000"> </span>
-provide arguments to the services that mask, unmask, and<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+signal sets -- type @code{sigset_t} -- that are used to
+provide arguments to the services that mask, unmask, and
</font> check on pending signals.
@subsection Blocking Until Signal Generation
A thread may block until receipt of a signal. The "sigwait"
<font color='#880000'>-and "pause" families of services block until the requested
-signal is received or if using @code{sigtimedwait()} until the specified<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+and "pause" families of functions block until the requested
+signal is received or if using @code{sigtimedwait()} until the specified
</font> timeout period has elapsed.
@subsection Sending a Signal
This is accomplished
<font color='#880000'>-via one of a number of services that sends a signal to either a<span style="background-color: #FF0000"> </span>
-process or thread. Signals may be directed at a process by<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+via one of a number of services that sends a signal to either a
+process or thread. Signals may be directed at a process by
</font> the service @code{kill()} or at a thread by the service
@code{pthread_kill()}
<font color='#997700'>@@ -150,6 +151,9 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -158,11 +162,12 @@
</font>
@subheading DESCRIPTION:
<font color='#880000'>-This function adds the @code{signo} to the specified signal @code{set}.
</font><font color='#000088'>+This function adds the signal @code{signo} to the specified signal @code{set}.
</font>
@subheading NOTES:
<font color='#880000'>-NONE
</font><font color='#000088'>+The set must be initialized using either @code{sigemptyset} or @code{sigfillset}
+before using this function.
</font>
@c
@c
<font color='#997700'>@@ -186,6 +191,9 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -194,11 +202,13 @@
</font>
@subheading DESCRIPTION:
<font color='#880000'>-This function deletes the @code{signo} to the specified signal @code{set}.
</font><font color='#000088'>+This function deletes the signal specified by @code{signo} from the specified
+signal @code{set}.
</font>
@subheading NOTES:
<font color='#880000'>-NONE
</font><font color='#000088'>+The set must be initialized using either @code{sigemptyset} or @code{sigfillset}
+before using this function.
</font>
@c
@c
<font color='#997700'>@@ -221,8 +231,10 @@
</font>
@subheading STATUS CODES:
<font color='#880000'>-@table @b
</font><font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
</font>
<font color='#000088'>+@table @b
</font> @item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -233,10 +245,6 @@
</font> This function fills the specified signal @code{set} such that all
signals are set.
<font color='#880000'>-@subheading NOTES:
-
-NONE
-
</font> @c
@c
@c
<font color='#997700'>@@ -259,6 +267,10 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns either 1 or 0 if completed successfully, otherwise it
+returns -1 and sets @code{errno} to indicate the error. @code{errno} may be set
+to:
+
</font> @table @b
@item EINVAL
<font color='#997700'>@@ -273,7 +285,8 @@
</font>
@subheading NOTES:
<font color='#880000'>-NONE
</font><font color='#000088'>+The set must be initialized using either @code{sigemptyset} or @code{sigfillset}
+before using this function.
</font>
@c
@c
<font color='#997700'>@@ -296,8 +309,10 @@
</font>
@subheading STATUS CODES:
<font color='#880000'>-@table @b
</font><font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
</font>
<font color='#000088'>+@table @b
</font> @item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -305,12 +320,7 @@
</font>
@subheading DESCRIPTION:
<font color='#880000'>-This function fills the specified signal @code{set} such that all
-signals are cleared.
-
-@subheading NOTES:
-
-NONE
</font><font color='#000088'>+This function initializes an empty signal set pointed to by @code{set}.
</font>
@c
@c
<font color='#997700'>@@ -335,6 +345,9 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -346,10 +359,71 @@
</font>
@subheading DESCRIPTION:
<font color='#880000'>-This function is used to change the action taken by a process on
-receipt of the specfic signal @code{sig}. The new action is
-specified by @code{act} and the previous action is returned
-via @code{oact}.
</font><font color='#000088'>+If the argument act is not a null pointer, it points to a structure specifying
+the action to be associated with the specified signal. If the argument oact is
+not a null pointer, the action previously associated with the signal is stored
+in the location pointed to by the argument oact. If the argument act is a null
+pointer, signal handling is unchanged; thus, the call can be used to enquire
+about the current handling of a given signal.
+
+The structure @code{sigaction} has the following members:
+
+@table @code
+
+@item void(*)(int) sa_handler
+Pointer to a signal-catching function or one of the macros SIG_IGN or SIG_DFL.
+
+@item sigset_t sa_mask
+Additional set of signals to be blocked during execution of signal-catching function.
+
+@item int sa_flags
+Special flags to affect behavior of signal.
+
+@item void(*)(int, siginfo_t*, void*) sa_sigaction
+Alternative pointer to a signal-catching function.
+
+@end table
+
+@code{sa_handler} and @code{sa_sigaction} should never be used at the same time as their storage may overlap.
+
+If the @code{SA_SIGINFO} flag (see below) is set in @code{sa_flags}, the
+@code{sa_sigaction} field specifies a signal-catching function, otherwise
+@code{sa_handler} specifies the action to be associated with the signal, which
+may be a signal-catching function or one of the macros @code{SIG_IGN} or
+@code{SIG_DFN}.
+
+The following flags can be set in the @code{sa_flags} field:
+
+@table @code
+
+@c I found no evidence that other flags are used in the source code.
+@c I did a fulltext search in cpukit/posix/, maybe I looked in the wrong place?
+@item SA_SIGINFO
+If not set, the signal-catching function should be declared as @code{void
+func(int signo)} and the address of the function should be set in
+@code{sa_handler}. If set, the signal-catching function should be declared as
+@code{void func(int signo, siginfo_t* info, void* context)} and the address of
+the function should be set in @code{sa_sigaction}.
+
+@end table
+
+The prototype of the @code{siginfo_t} structure is the following:
+@example
+typedef struct
+@{
+ int si_signo; /* Signal number */
+ int si_code; /* Cause of the signal */
+ pid_t si_pid; /* Sending process ID */
+ uid_t si_uid; /* Real user ID of sending process */
+ void* si_addr; /* Address of faulting instruction */
+ int si_status; /* Exit value or signal */
+ union sigval
+ @{
+ int sival_int; /* Integer signal value */
+ void* sival_ptr; /* Pointer signal value */
+ @} si_value; /* Signal value */
+@}
+@end example
</font>
@subheading NOTES:
<font color='#997700'>@@ -377,6 +451,9 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item ESRCH
<font color='#997700'>@@ -389,11 +466,11 @@
</font>
@subheading DESCRIPTION:
<font color='#880000'>-This functions sends the specified signal @code{sig} to @code{thread}.
</font><font color='#000088'>+This functions sends the specified signal @code{sig} to a thread referenced
+to by @code{thread}.
</font>
<font color='#880000'>-@subheading NOTES:
</font><font color='#000088'>+If the signal code is @code{0}, arguments are validated and no signal is sent.
</font>
<font color='#880000'>-NONE
</font>
@c
@c
<font color='#997700'>@@ -418,6 +495,9 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item EINVAL
<font color='#997700'>@@ -447,13 +527,17 @@
</font>
@end table
<font color='#880000'>-If @code{oset} is not @code{NULL}, then the set of blocked signals
-prior to this call is returned in @code{oset}.
</font><font color='#000088'>+If @code{oset} is not @code{NULL}, then the set of blocked signals prior to
+this call is returned in @code{oset}. If @code{set} is @b{NULL}, no change is
+done, allowing to examine the set of currently blocked signals.
</font>
@subheading NOTES:
It is not an error to unblock a signal which is not blocked.
<font color='#000088'>+In the current implementation of RTEMS POSIX API sigprocmask() is technically
+mapped to pthread_sigmask().
+
</font> @c
@c
@c
<font color='#997700'>@@ -476,7 +560,12 @@
</font> @end example
@subheading STATUS CODES:
<font color='#000088'>+
+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
<font color='#000088'>+
</font> @item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -503,8 +592,9 @@
</font>
@end table
<font color='#880000'>-If @code{oset} is not @code{NULL}, then the set of blocked signals
-prior to this call is returned in @code{oset}.
</font><font color='#000088'>+If @code{oset} is not @code{NULL}, then the set of blocked signals prior to
+this call is returned in @code{oset}. If @code{set} is @b{NULL}, no change is
+done, allowing to examine the set of currently blocked signals.
</font>
@subheading NOTES:
<font color='#997700'>@@ -533,6 +623,10 @@
</font> @end example
@subheading STATUS CODES:
<font color='#000088'>+
+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -551,7 +645,8 @@
</font>
@subheading NOTES:
<font color='#880000'>-NONE
</font><font color='#000088'>+Since RTEMS is a single-process system, a signal can only be sent to the calling
+process (i.e. the current node).
</font>
@c
@c
<font color='#997700'>@@ -574,8 +669,8 @@
</font>
@subheading STATUS CODES:
<font color='#880000'>-On error, this routine returns -1 and sets @code{errno} to one of
-the following:
</font><font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
</font>
@table @b
<font color='#997700'>@@ -590,10 +685,6 @@
</font> signals. A pending signal is one which has been raised but is currently
blocked. The set of pending signals is returned in @code{set}.
<font color='#880000'>-@subheading NOTES:
-
-NONE
-
</font> @c
@c
@c
<font color='#997700'>@@ -615,8 +706,8 @@
</font>
@subheading STATUS CODES:
<font color='#880000'>-On error, this routine returns -1 and sets @code{errno} to one of
-the following:
</font><font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
</font>
@table @b
<font color='#997700'>@@ -629,11 +720,7 @@
</font>
This function temporarily replaces the signal mask for the process
with that specified by @code{sigmask} and blocks the calling thread
<font color='#880000'>-until the signal is raised.
-
-@subheading NOTES:
-
-NONE
</font><font color='#000088'>+until a signal is raised.
</font>
@c
@c
<font color='#997700'>@@ -654,8 +741,8 @@
</font>
@subheading STATUS CODES:
<font color='#880000'>-On error, this routine returns -1 and sets @code{errno} to one of
-the following:
</font><font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
</font>
@table @b
<font color='#997700'>@@ -669,10 +756,6 @@
</font> This function causes the calling thread to be blocked until an
unblocked signal is received.
<font color='#880000'>-@subheading NOTES:
-
-NONE
-
</font> @c
@c
@c
<font color='#997700'>@@ -694,7 +777,12 @@
</font> @end example
@subheading STATUS CODES:
<font color='#000088'>+
+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
<font color='#000088'>+
</font> @item EINVAL
Invalid argument passed.
<font color='#997700'>@@ -709,11 +797,6 @@
</font> @code{set}, atomically clears it from the set of pending signals, and
returns the signal number for that signal in @code{sig}.
<font color='#880000'>-
-@subheading NOTES:
-
-NONE
-
</font> @c
@c
@c
<font color='#997700'>@@ -735,7 +818,12 @@
</font> @end example
@subheading STATUS CODES:
<font color='#000088'>+
+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
<font color='#000088'>+
</font> @item EINTR
Signal interrupted this function.
<font color='#997700'>@@ -747,9 +835,23 @@
</font> @code{set}, atomically clears it from the set of pending signals, and
returns information about that signal in @code{info}.
<font color='#880000'>-@subheading NOTES:
-
-NONE
</font><font color='#000088'>+The prototype of the @code{siginfo_t} structure is the following:
+@example
+typedef struct
+@{
+ int si_signo; /* Signal number */
+ int si_code; /* Cause of the signal */
+ pid_t si_pid; /* Sending process ID */
+ uid_t si_uid; /* Real user ID of sending process */
+ void* si_addr; /* Address of faulting instruction */
+ int si_status; /* Exit value or signal */
+ union sigval
+ @{
+ int sival_int; /* Integer signal value */
+ void* sival_ptr; /* Pointer signal value */
+ @} si_value; /* Signal value */
+@}
+@end example
</font>
@c
@c
<font color='#997700'>@@ -773,7 +875,12 @@
</font> @end example
@subheading STATUS CODES:
<font color='#000088'>+
+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
<font color='#000088'>+
</font> @item EAGAIN
Timed out while waiting for the specified signal set.
<font color='#997700'>@@ -792,6 +899,15 @@
</font> returns information about that signal in @code{info}. The calling thread
will block up to @code{timeout} waiting for the signal to arrive.
<font color='#000088'>+The @code{timespec} structure is defined as follows:
+@example
+struct timespec
+@{
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+@}
+@end example
+
</font> @subheading NOTES:
If @code{timeout} is NULL, then the calling thread will wait forever for
<font color='#997700'>@@ -820,6 +936,9 @@
</font>
@subheading STATUS CODES:
<font color='#000088'>+The function returns 0 on success, otherwise it returns -1 and sets
+@code{errno} to indicate the error. @code{errno} may be set to:
+
</font> @table @b
@item EAGAIN
<font color='#997700'>@@ -845,9 +964,19 @@
</font> This function sends the signal specified by @code{signo} to the
process @code{pid}
<font color='#000088'>+The @code{sigval} union is specified as:
+@example
+union sigval
+@{
+ int sival_int; /* Integer signal value */
+ void* sival_ptr; /* Pointer signal value */
+@}
+@end example
+
</font> @subheading NOTES:
<font color='#880000'>-NONE
</font><font color='#000088'>+Since RTEMS is a single-process system, a signal can only be sent to the calling
+process (i.e. the current node).
</font>
@c
@c
<font color='#997700'>@@ -886,7 +1015,7 @@
</font> @subheading NOTES:
Alarm requests do not queue. If @code{alarm} is called while
<font color='#880000'>-a previous request is outstanding, the call will result in<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+a previous request is outstanding, the call will result in
</font> rescheduling the time at which the @code{SIGALRM} signal
will be generated.
<font color='#997700'>@@ -936,7 +1065,7 @@
</font> @subheading NOTES:
Alarm requests do not queue. If @code{alarm} is called while
<font color='#880000'>-a previous request is outstanding, the call will result in<span style="background-color: #FF0000"> </span>
</font><font color='#000088'>+a previous request is outstanding, the call will result in
</font> rescheduling the time at which the @code{SIGALRM} signal
will be generated.
</pre>
<p> </p>
<p>--<br />
<small>Generated by <a href="http://www.codewiz.org/projects/index.html#loginfo">Deluxe Loginfo</a> 2.122 by Bernardo Innocenti <bernie@develer.com></small></p>
</body>
</html>