File: rtlinux_sigaction.3.html

package info (click to toggle)
rtlinux 3.1pre3-3
links: PTS
area: non-free
in suites: etch, etch-m68k
size: 4,896 kB
ctags: 4,228
sloc: ansic: 26,204; sh: 2,069; makefile: 1,414; perl: 855; tcl: 489; asm: 380; cpp: 42
file content (618 lines) | stat: -rw-r--r-- 10,432 bytes
parent folder | download | duplicates (2)
<HTML
><HEAD
><TITLE
>rtlinux_sigaction, rtlinux_sigprocmask</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"></HEAD
><BODY
CLASS="REFENTRY"
><H1
><A
NAME="AEN1"
>rtlinux_sigaction, rtlinux_sigprocmask</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5"
></A
><H2
>Name</H2
>rtlinux_sigaction, rtlinux_sigprocmask&nbsp;--&nbsp;RTLinux V3 User-Level signal handling functions.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8"
></A
><H2
>Synopsis</H2
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
>	#include &#60;rtlinux_signal.h&#62;

	int <TT
CLASS="FUNCTION"
>rtlinux_sigaction</TT
>(int <TT
CLASS="PARAMETER"
><I
>signum</I
></TT
>, struct rtlinux_sigaction * <TT
CLASS="PARAMETER"
><I
>act</I
></TT
>, struct rtlinux_sigaction * <TT
CLASS="PARAMETER"
><I
>oldact</I
></TT
>);
       
	int <TT
CLASS="FUNCTION"
>rtlinux_sigprocmask</TT
>(int <TT
CLASS="PARAMETER"
><I
>how</I
></TT
>, rtlinux_sigset_t * <TT
CLASS="PARAMETER"
><I
>set</I
></TT
>, rtlinux_sigset_t * <TT
CLASS="PARAMETER"
><I
>oldset</I
></TT
>);</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN18"
></A
><H2
>DESCRIPTION</H2
><P
>This is introduced in  V3 RTLinux.
The <TT
CLASS="FUNCTION"
>rtlinux_sigaction</TT
> function call is used to request
delivery of a real-time event and assign a handler for that event.  Its 
semantics are similar to <TT
CLASS="FUNCTION"
>sigaction(3)</TT
> for ease of 
programming, but it does not affect or interact with normal Linux signals.  The 
handler is called as quickly as hardware allows and does not wait for Linux to 
become ready (enabling interrupts, releasing locks and so on).  Latencies 
between the requested event and handler code being called is on the order of 
a few tens of micro-seconds on modern hardware.  This low-latency behavior 
comes with restrictions listed in the NOTES section.</P
><P
><TT
CLASS="PARAMETER"
><I
>signum</I
></TT
> specifies the signal number.  Signal numbers 0 up to (but 
not including) <TT
CLASS="LITERAL"
>RTLINUX_SIGTIMER0</TT
> are hardware IRQ's.  So, 
signal 3 represents IRQ 3.  Signal numbers <TT
CLASS="LITERAL"
>RTLINUX_SIGTIMER0</TT
> 
and above are timer events.</P
><P
>If <TT
CLASS="PARAMETER"
><I
>act</I
></TT
> is non-NULL, the new action for signal
<TT
CLASS="PARAMETER"
><I
>signum</I
></TT
> is installed from <TT
CLASS="PARAMETER"
><I
>act</I
></TT
>.
Unlike with <TT
CLASS="FUNCTION"
>sigaction</TT
>, <TT
CLASS="PARAMETER"
><I
>oldact</I
></TT
> is
ignored and may be NULL or non-NULL.  The call to
<TT
CLASS="FUNCTION"
>rtlinux_sigaction</TT
> does not change or read
<TT
CLASS="PARAMETER"
><I
>oldact</I
></TT
>.</P
><P
>The <TT
CLASS="PARAMETER"
><I
>rtlinux_sigaction</I
></TT
> structure is defined as

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>	struct rtlinux_sigaction
	{
		void (*sa_handler)(int);
		rtlinux_sigset_t sa_mask;
		int sa_flags;
		hrtime_t sa_period;
	};</PRE
></TD
></TR
></TABLE
>

<TT
CLASS="PARAMETER"
><I
>sa_handler</I
></TT
> specifies the action to be associated with
<TT
CLASS="PARAMETER"
><I
>signum</I
></TT
> and may be <TT
CLASS="LITERAL"
>RTLINUX_SIG_DFL</TT
>
for the default action, <TT
CLASS="LITERAL"
>RTLINUX_SIG_IGN</TT
> to ignore the
signal, or a pointer to a signal handling function.</P
><P
><TT
CLASS="PARAMETER"
><I
>sa_period</I
></TT
> is the period (in nanoseconds) between signals
sent to the process when <TT
CLASS="PARAMETER"
><I
>signum</I
></TT
> is
<TT
CLASS="LITERAL"
>RTLINUX_SIGTIMER0</TT
> or above.  Only one timer signal will
be delivered in <TT
CLASS="PARAMETER"
><I
>sa_period</I
></TT
> nanoseconds when
<TT
CLASS="LITERAL"
>RTLINUX_SA_ONESHOT</TT
> is set in
<TT
CLASS="PARAMETER"
><I
>sa_flags</I
></TT
>.  If <TT
CLASS="LITERAL"
>RTLINUX_SA_ONESHOT</TT
> is
not set then the signal handler is automatically reinstalled each signal
delivery (this is the default behavior).</P
><P
><TT
CLASS="PARAMETER"
><I
>sa_flags</I
></TT
> specifies a set of flags which modify the
behavior of the signal handling process.  It is formed by the bitwise OR of
zero or more of the following:

<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>RTLINUX_SA_ONESHOT</TT
> or
<TT
CLASS="LITERAL"
>RTLINUX_SA_RESETHAND</TT
></DT
><DD
><P
>Restore the signal action to the default state once signal
handler has been called.  (NOTE: <TT
CLASS="LITERAL"
>RTLINUX_SA_ONESHOT</TT
> and
<TT
CLASS="LITERAL"
>RTLINUX_SA_RESETHAND</TT
> have the same value; read
<TT
CLASS="LITERAL"
>RTLINUX_SA_RESETHAND</TT
> as "reset the handler to the default
handler after the specified handler is called".)</P
></DD
><DT
>RTLINUX_SA_PERIODIC</DT
><DD
><P
>Re-install the specified signal handler each signal delivery
(default behavior).</P
></DD
></DL
></DIV
>&#13;</P
><P
>The <TT
CLASS="FUNCTION"
>rtlinux_sigprocmask</TT
> call is used to change the list
of currently blocked RTLinux signals, similar to
<TT
CLASS="FUNCTION"
>sigprocmask</TT
> in libc.  The behavior of the call is
dependant on the value of <TT
CLASS="PARAMETER"
><I
>how</I
></TT
>, as follows.

<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>RTLINUX_SIG_BLOCK</TT
></DT
><DD
><P
>The set of blocked signals is the union of the current set and
the <TT
CLASS="PARAMETER"
><I
>set</I
></TT
> argument.</P
></DD
><DT
><TT
CLASS="LITERAL"
>RTLINUX_SIG_UNBLOCK</TT
></DT
><DD
><P
>The signals in <TT
CLASS="PARAMETER"
><I
>set</I
></TT
> are removed from the
current set of blocked signals.  It is legal to attempt to unblock a signal
which is not blocked.</P
></DD
><DT
><TT
CLASS="LITERAL"
>RTLINUX_SIG_SETMASK</TT
></DT
><DD
><P
>The set of blocked signals is set to the current argument
<TT
CLASS="PARAMETER"
><I
>set</I
></TT
>.</P
></DD
></DL
></DIV
>&#13;</P
><P
>If <TT
CLASS="PARAMETER"
><I
>oldset</I
></TT
> is non-NULL, the previous value of the signal
mask is stored in <TT
CLASS="PARAMETER"
><I
>oldset</I
></TT
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN92"
></A
><H2
>RETURN VALUES</H2
><P
><TT
CLASS="FUNCTION"
>rtlinux_sigaction</TT
> and
<TT
CLASS="FUNCTION"
>rtlinux_sigprocmask</TT
> return 0 on success and -1 on error.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN97"
></A
><H2
>ERRORS</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>EINVAL</DT
><DD
><P
>An invalid signal was specified.</P
></DD
><DT
>EFAULT</DT
><DD
><P
><TT
CLASS="PARAMETER"
><I
>act</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>oldact</I
></TT
>,
<TT
CLASS="PARAMETER"
><I
>set</I
></TT
> or <TT
CLASS="PARAMETER"
><I
>oldset</I
></TT
> point to memory
which is not a valid part of the address space.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN112"
></A
><H2
>NOTES</H2
><P
>This function is only available in Linux user processes. RTLinux threads can not use this function.</P
><P
>It is necessary for the RTLinux modules to be loaded for these calls to
succeed.</P
><P
>During a call to rtlinux_sigaction, <TT
CLASS="FUNCTION"
>mlockall</TT
> is called so
currently swapped-in pages and future pages will be locked in memory until
this process exits or unlocks its pages.  As a result, this call will only
succeed when made from a process running as root.</P
><P
>The handler assigned in the call to <TT
CLASS="FUNCTION"
>rtlinux_sigaction</TT
>
will be scheduled and executed by RTLinux and may be run when Linux is
unable to provide normal services to the executing code.  So, all
calls made in the signal handler must be to statically linked libraries;
code within the program itself cannot execute system calls. To have services perform the needed actions, one should send requests to the non-RTLinux signal handler
part of the program.</P
><P
>Currently, in addition to its own address space, the handler executes with the kernel memory mapped in and accessible (the same as that of
the parent), so programmers must take care to not change kernel data
structures.  This feature allows access to device address space as well.</P
><P
>Since RTLinux signals represent either IRQs or real-time timers, blocking an
RTLinux signal will pend the IRQ or timer to which it corresponds.  Blocking an IRQ
will keep track of how many times that IRQ goes off, then call the installed
handler that many times when the IRQ is unblocked.  When a timer is blocked
and then unblocked, the installed handler will only be called once if the the
timer went off one or more times while blocked.</P
><P
>To manipulate RTLinux signal sets (rtlinux_sigset_t) use the 
<TT
CLASS="FUNCTION"
>rtlinux_sigsetops</TT
>(3).
To see which RTLinux signals are available, see 
<TT
CLASS="FUNCTION"
>rtlinux_signal</TT
>(3).</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN125"
></A
><H2
>EXAMPLES</H2
><P
>See the RTLinux distribution examples/psc directory for further examples.</P
><P
><TT
CLASS="FUNCTION"
>request_irq()</TT
> functionality can be implemented as:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>	struct rtlinux_sigaction sig, oldsig;
	int irq = 4;
	void handler_function(int);

	sig.sa_handler = handler_function;
	sig.sa_flags = RTLINUX_SA_PERIODIC;

	if ( rtlinux_sigaction( irq, &#38; sig, &#38; oldsig ) )
	{
		printf("Couldn't get irq\n");
		perror("rtlinux_sigaction");
		return -1;
	}</PRE
></TD
></TR
></TABLE
></P
><P
><TT
CLASS="FUNCTION"
>free_irq()</TT
> functionality can be implemented with:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>	struct rtlinux_sigaction sig, oldsig;
	int irq = 4;

	sig.sa_handler = RTLINUX_SIG_IGN;
	/* free the irq */
	rtlinux_sigaction( irq, &#38; sig, &#38; oldsig );</PRE
></TD
></TR
></TABLE
>&#13;</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN134"
></A
><H2
>AUTHORS</H2
><P
>Cort Dougan (<A
HREF="mailto:cort@fsmlabs.com"
TARGET="_top"
>cort@fsmlabs.com</A
>)</P
><P
>Nathan Paul Simons (<A
HREF="mailto:npsimons@fsmlabs.com"
TARGET="_top"
>npsimons@fsmlabs.com</A
>)</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN140"
></A
><H2
>SEE ALSO</H2
><A
HREF="../susv2/xsh/sigaction.html"
TARGET="_top"
>UNIX spec sigaction(2)</A
>, <A
HREF="../susv2/xsh/sigprocmask.html"
TARGET="_top"
>UNIX spec sigprocmask(2)</A
>, <A
HREF="rtlinux_sigsetops.3.html"
TARGET="_top"
>rtlinux_sigsetops(3)</A
>, <A
HREF="rtlinux_signal.3.html"
TARGET="_top"
>rtlinux_signal(3)</A
><P
>2001 FSMLabs Inc.</P
><P
>All rights reserved.</P
></DIV
></BODY
></HTML
>