rtlinux_sigprocmask.3

rtlinux-3.1源代码

.\" This -*- nroff -*- file has been generated from
.\" DocBook SGML with docbook-to-man on Debian GNU/Linux.
...\"
...\"	transcript compatibility for postscript use.
...\"
...\"	synopsis:  .P! <file.ps>
...\"
.de P!
\\&.
.fl			\" force out current output buffer
\\!%PB
\\!/showpage{}def
...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
.fl			\" prolog
.sy cat \\$1\" bring in postscript file
...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
.sp \\$2u	\" move below the image
..
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
'\" t 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n  
.TH "rtlinux_sigaction, rtlinux_sigprocmask" "3" 
.SH "NAME" 
rtlinux_sigaction, rtlinux_sigprocmask \(em RTLinux V3 User-Level signal handling functions. 
.SH "SYNOPSIS" 
.PP 
.nf 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
#include <rtlinux_signal.h> 
 
int \fBrtlinux_sigaction\fP(int \fBsignum\fR, struct rtlinux_sigaction * \fBact\fR, struct rtlinux_sigaction * \fBoldact\fR); 
 
int \fBrtlinux_sigprocmask\fP(int \fBhow\fR, rtlinux_sigset_t * \fBset\fR, rtlinux_sigset_t * \fBoldset\fR); 
.fi 
.SH "DESCRIPTION" 
.PP 
This is introduced in  V3 RTLinux. 
The \fBrtlinux_sigaction\fP function call is used to request 
delivery of a real-time event and assign a handler for that event.  Its  
semantics are similar to \fBsigaction(3)\fP 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. 
.PP 
\fBsignum\fR specifies the signal number.  Signal numbers 0 up to (but  
not including) \fBRTLINUX_SIGTIMER0\fP are hardware IRQ's.  So,  
signal 3 represents IRQ 3.  Signal numbers \fBRTLINUX_SIGTIMER0\fP  
and above are timer events. 
.PP 
If \fBact\fR is non-NULL, the new action for signal 
\fBsignum\fR is installed from \fBact\fR. 
Unlike with \fBsigaction\fP, \fBoldact\fR is 
ignored and may be NULL or non-NULL.  The call to 
\fBrtlinux_sigaction\fP does not change or read 
\fBoldact\fR. 
.PP 
The \fBrtlinux_sigaction\fR structure is defined as 
 
.PP 
.nf 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
\f(CW	struct rtlinux_sigaction 
{ 
void (*sa_handler)(int); 
rtlinux_sigset_t sa_mask; 
int sa_flags; 
hrtime_t sa_period; 
};\fR 
.fi 
.PP 
 
\fBsa_handler\fR specifies the action to be associated with 
\fBsignum\fR and may be \fBRTLINUX_SIG_DFL\fP for the default action, \fBRTLINUX_SIG_IGN\fP to ignore the 
signal, or a pointer to a signal handling function. 
.PP 
\fBsa_period\fR is the period (in nanoseconds) between signals 
sent to the process when \fBsignum\fR is 
\fBRTLINUX_SIGTIMER0\fP or above.  Only one timer signal will 
be delivered in \fBsa_period\fR nanoseconds when 
\fBRTLINUX_SA_ONESHOT\fP is set in 
\fBsa_flags\fR.  If \fBRTLINUX_SA_ONESHOT\fP is 
not set then the signal handler is automatically reinstalled each signal 
delivery (this is the default behavior). 
.PP 
\fBsa_flags\fR 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: 
 
.IP "\fBRTLINUX_SA_ONESHOT\fP or 
\fBRTLINUX_SA_RESETHAND\fP" 10 
Restore the signal action to the default state once signal 
handler has been called.  (NOTE: \fBRTLINUX_SA_ONESHOT\fP and 
\fBRTLINUX_SA_RESETHAND\fP have the same value; read 
\fBRTLINUX_SA_RESETHAND\fP as "reset the handler to the default 
handler after the specified handler is called".) 
.IP "RTLINUX_SA_PERIODIC" 10 
Re-install the specified signal handler each signal delivery 
(default behavior). 
.PP 
The \fBrtlinux_sigprocmask\fP call is used to change the list 
of currently blocked RTLinux signals, similar to 
\fBsigprocmask\fP in libc.  The behavior of the call is 
dependant on the value of \fBhow\fR, as follows. 
 
.IP "\fBRTLINUX_SIG_BLOCK\fP" 10 
The set of blocked signals is the union of the current set and 
the \fBset\fR argument. 
.IP "\fBRTLINUX_SIG_UNBLOCK\fP" 10 
The signals in \fBset\fR are removed from the 
current set of blocked signals.  It is legal to attempt to unblock a signal 
which is not blocked. 
.IP "\fBRTLINUX_SIG_SETMASK\fP" 10 
The set of blocked signals is set to the current argument 
\fBset\fR. 
.PP 
If \fBoldset\fR is non-NULL, the previous value of the signal 
mask is stored in \fBoldset\fR. 
.SH "RETURN VALUES" 
.PP 
\fBrtlinux_sigaction\fP and 
\fBrtlinux_sigprocmask\fP return 0 on success and -1 on error. 
.SH "ERRORS" 
.IP "EINVAL" 10 
An invalid signal was specified. 
.IP "EFAULT" 10 
\fBact\fR, \fBoldact\fR, 
\fBset\fR or \fBoldset\fR point to memory 
which is not a valid part of the address space. 
.SH "NOTES" 
.PP 
It is necessary for the RTLinux modules to be loaded for these calls to 
succeed. 
.PP 
During a call to rtlinux_sigaction, \fBmlockall\fP 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. 
.PP 
The handler assigned in the call to \fBrtlinux_sigaction\fP 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. 
.PP 
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. 
.PP 
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. 
.PP 
To manipulate RTLinux signal sets (rtlinux_sigset_t) use the  
\fBrtlinux_sigsetops\fP(3). 
To see which RTLinux signals are available, see  
\fBrtlinux_signal\fP(3). 
.SH "EXAMPLES" 
.PP 
See the RTLinux distribution examples/psc directory for further examples. 
.PP 
\fBrequest_irq()\fP functionality can be implemented as: 
 
.PP 
.nf 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
\f(CW	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, & sig, & oldsig ) ) 
{ 
printf("Couldn't get irq\n"); 
perror("rtlinux_sigaction"); 
return -1; 
}\fR 
.fi 
.PP 
.PP 
\fBfree_irq()\fP functionality can be implemented with: 
 
.PP 
.nf 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
\f(CW	struct rtlinux_sigaction sig, oldsig; 
int irq = 4; 
 
sig.sa_handler = RTLINUX_SIG_IGN; 
/* free the irq */ 
rtlinux_sigaction( irq, & sig, & oldsig );\fR 
.fi 
.PP 
.SH "AUTHORS" 
.PP 
Cort Dougan (\[e-mail] (link to URL mailto:[e-mail]) \fR) 
.PP 
Nathan Paul Simons (\[e-mail] (link to URL mailto:[e-mail]) \fR) 
.SH "NOTES" 
.PP 
This function is only available in Linux user processes. RTLinux threads can not use this function. 
.SH "SEE ALSO" 
\fIUNIX spec sigaction(2) (link to URL ../susv2/xsh/sigaction.html) \fR,  \fIUNIX spec sigprocmask(2) (link to URL ../susv2/xsh/sigprocmask.html) \fR, \fIrtlinux_sigsetops(3) (link to URL rtlinux_sigsetops.3.html) \fR, \fIrtlinux_signal(3) (link to URL rtlinux_signal.3.html) \fR 
.PP 
\(co2001 FSMLabs Inc. 
.PP 
All rights reserved. 
...\" created by instant / docbook-to-man, Thu 26 Jul 2001, 11:20