source: rtems/doc/new_chapters/signal.t @ 2341410c

4.104.114.84.95
Last change on this file since 2341410c was 2341410c, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 29, 1998 at 12:02:53 AM

Fleshed out considerably. This is almost a passable manual now.

  • Property mode set to 100644
File size: 13.6 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Signal Manager
10
11@section Introduction
12
13The signal manager ...
14
15The directives provided by the signal manager are:
16
17@itemize @bullet
18@item @code{sigaddset} - Add a Signal to a Signal Set
19@item @code{sigdelset} - Delete a Signal from a Signal Set
20@item @code{sigfillset} - Fill a Signal Set
21@item @code{sigismember} - Is Signal a Member of a Signal Set
22@item @code{sigemptyset} - Empty a Signal Set
23@item @code{sigaction} - Examine and Change Signal Action
24@item @code{pthread_kill} - Send a Signal to a Thread
25@item @code{sigprocmask} - Examine and Change Process Blocked Signals
26@item @code{pthread_sigmask} - Examine and Change Thread Blocked Signals
27@item @code{kill} - Send a Signal to a Process
28@item @code{sigpending} - Examine Pending Signals
29@item @code{sigsuspend} - Wait for a Signal
30@item @code{pause} - Suspend Process Execution
31@item @code{sigwait} - Synchronously Accept a Signal
32@item @code{sigwaitinfo} - Synchronously Accept a Signal
33@item @code{sigtimedwait} - Synchronously Accept a Signal with Timeout
34@item @code{sigqueue} - Queue a Signal to a Process
35@item @code{alarm} - Schedule Alarm
36@end itemize
37
38@section Background
39
40@subsection Signal Delivery
41
42Signals directed at a thread are delivered to the specified thread.
43
44Signals directed at a process are delivered to a thread which is selected
45based on the following algorithm:
46
47@enumerate
48@item If the action for this signal is currently @code{SIG_IGN},
49then the signal is simply ignored.
50
51@item If the currently executing thread has the signal unblocked, then
52the signal is delivered to it.
53
54@item If any threads are currently blocked waiting for this signal
55(@code{sigwait()}), then the signal is delivered to the highest priority
56thread waiting for this signal.
57
58@item If any other threads are willing to accept delivery of the signal, then
59the signal is delivered to the highest priority thread of this set.  In the
60event, multiple threads of the same priority are willing to accept this
61signal, then priority is given first to ready threads, then to threads
62blocked on calls which may be interrupted, and finally to threads blocked
63on non-interruptible calls.
64
65@item In the event the signal still can not be delivered, then it is left
66pending.  The first thread to unblock the signal (@code{sigprocmask()} or
67@code{pthread_sigprocmask()}) or to wait for this signal
68(@code{sigwait()}) will be the recipient of the signal.
69
70@end enumerate
71
72@section Operations
73
74There is currently no text in this section.
75
76@section Directives
77
78This section details the signal manager's directives.
79A subsection is dedicated to each of this manager's directives
80and describes the calling sequence, related constants, usage,
81and status codes.
82
83@page
84@subsection sigaddset - Add a Signal to a Signal Set
85
86@subheading CALLING SEQUENCE:
87
88@example
89#include <signal.h>
90
91int sigaddset(
92  sigset_t   *set,
93  int         signo
94);
95@end example
96
97@subheading STATUS CODES:
98
99@table @b
100@item EINVAL
101Invalid argument passed.
102
103@end table
104
105@subheading DESCRIPTION:
106
107This function adds the @code{signo} to the specified signal @code{set}.
108
109@subheading NOTES:
110
111@page
112@subsection sigdelset - Delete a Signal from a Signal Set
113
114@subheading CALLING SEQUENCE:
115
116@example
117#include <signal.h>
118
119int sigdelset(
120  sigset_t   *set,
121  int         signo
122);
123@end example
124
125@subheading STATUS CODES:
126
127@table @b
128@item EINVAL
129Invalid argument passed.
130
131@end table
132
133@subheading DESCRIPTION:
134
135This function deletes the @code{signo} to the specified signal @code{set}.
136
137@subheading NOTES:
138
139NONE
140
141@page
142@subsection sigfillset - Fill a Signal Set
143
144@subheading CALLING SEQUENCE:
145
146@example
147#include <signal.h>
148
149int sigfillset(
150  sigset_t   *set
151);
152@end example
153
154@subheading STATUS CODES:
155
156@table @b
157
158@item EINVAL
159Invalid argument passed.
160
161@end table
162
163@subheading DESCRIPTION:
164
165This function fills the specified signal @code{set} such that all
166signals are set.
167
168@subheading NOTES:
169
170NONE
171
172@page
173@subsection sigismember - Is Signal a Member of a Signal Set
174
175@subheading CALLING SEQUENCE:
176
177@example
178#include <signal.h>
179
180int sigismember(
181  const sigset_t   *set,
182  int               signo
183);
184@end example
185
186@subheading STATUS CODES:
187
188@table @b
189
190@item EINVAL
191Invalid argument passed.
192
193@end table
194
195@subheading DESCRIPTION:
196
197This function returns returns 1 if @code{signo} is a member of @code{set}
198and 0 otherwise.
199
200@subheading NOTES:
201
202NONE
203
204@page
205@subsection sigemptyset - Empty a Signal Set
206
207@subheading CALLING SEQUENCE:
208
209@example
210#include <signal.h>
211
212int sigemptyset(
213  sigset_t   *set
214);
215@end example
216
217@subheading STATUS CODES:
218
219@table @b
220
221@item EINVAL
222Invalid argument passed.
223
224@end table
225
226@subheading DESCRIPTION:
227
228This function fills the specified signal @code{set} such that all
229signals are cleared.
230
231@subheading NOTES:
232
233NONE
234
235@page
236@subsection sigaction - Examine and Change Signal Action
237
238@subheading CALLING SEQUENCE:
239
240@example
241#include <signal.h>
242
243int sigaction(
244  int                     sig,
245  const struct sigaction *act,
246  struct sigaction       *oact
247);
248@end example
249
250@subheading STATUS CODES:
251
252@table @b
253@item EINVAL
254Invalid argument passed.
255
256@item ENOTSUP
257Realtime Signals Extension option not supported.
258
259@end table
260
261@subheading DESCRIPTION:
262
263This function is used to change the action taken by a process on
264receipt of the specfic signal @code{sig}.  The new action is
265specified by @code{act} and the previous action is returned
266via @code{oact}.
267
268@subheading NOTES:
269
270The signal number cannot be SIGKILL.
271
272@page
273@subsection pthread_kill - Send a Signal to a Thread
274
275@subheading CALLING SEQUENCE:
276
277@example
278#include <signal.h>
279
280int pthread_kill(
281  pthread_t   thread,
282  int         sig
283);
284@end example
285
286@subheading STATUS CODES:
287
288@table @b
289
290@item ESRCH
291The thread indicated by the parameter thread is invalid.
292
293@item EINVAL
294Invalid argument passed.
295
296@end table
297
298@subheading DESCRIPTION:
299
300This functions sends the specified signal @code{sig} to @code{thread}.
301
302@subheading NOTES:
303
304NONE
305
306@page
307@subsection sigprocmask - Examine and Change Process Blocked Signals
308 
309@subheading CALLING SEQUENCE:
310 
311@example
312#include <signal.h>
313 
314int sigprocmask(
315  int               how,
316  const sigset_t   *set,
317  sigset_t         *oset
318);
319@end example
320 
321@subheading STATUS CODES:
322
323@table @b
324
325@item EINVAL
326Invalid argument passed.
327 
328@end table
329 
330@subheading DESCRIPTION:
331 
332This function is used to alter the set of currently blocked signals
333on a process wide basis.  A blocked signal will not be received by the
334process.  The behavior of this function is dependent on the value of
335@code{how} which may be one of the following:
336
337@itemize @code
338@item SIG_BLOCK
339The set of blocked signals is set to the union of @code{set} and
340those signals currently blocked.
341
342@item SIG_UNBLOCK
343The signals specific in @code{set} are removed from the currently
344blocked set.
345
346@item SIG_SETMASK
347The set of currently blocked signals is set to @code{set}.
348
349@end itemize
350
351If @code{oset} is not @code{NULL}, then the set of blocked signals
352prior to this call is returned in @code{oset}.
353
354@subheading NOTES:
355
356It is not an error to unblock a signal which is not blocked.
357
358@page
359@subsection pthread_sigmask - Examine and Change Thread Blocked Signals
360
361@subheading CALLING SEQUENCE:
362
363@example
364#include <signal.h>
365
366int pthread_sigmask(
367  int               how,
368  const sigset_t   *set,
369  sigset_t         *oset
370);
371@end example
372
373@subheading STATUS CODES:
374@table @b
375@item EINVAL
376Invalid argument passed.
377
378@end table
379
380@subheading DESCRIPTION:
381
382This function is used to alter the set of currently blocked signals
383for the calling thread.  A blocked signal will not be received by the
384process.  The behavior of this function is dependent on the value of
385@code{how} which may be one of the following:
386
387@table @code
388@item SIG_BLOCK
389The set of blocked signals is set to the union of @code{set} and
390those signals currently blocked.
391
392@item SIG_UNBLOCK
393The signals specific in @code{set} are removed from the currently
394blocked set.
395
396@item SIG_SETMASK
397The set of currently blocked signals is set to @code{set}.
398
399@end table
400
401If @code{oset} is not @code{NULL}, then the set of blocked signals
402prior to this call is returned in @code{oset}.
403
404@subheading NOTES:
405
406It is not an error to unblock a signal which is not blocked.
407
408
409@page
410@subsection kill - Send a Signal to a Process
411
412@subheading CALLING SEQUENCE:
413
414@example
415#include <sys/types.h>
416#include <signal.h>
417
418int kill(
419  pid_t pid,
420  int   sig
421);
422@end example
423
424@subheading STATUS CODES:
425@table @b
426@item EINVAL
427Invalid argument passed.
428
429@item EPERM
430Process does not have permission to send the signal to any receiving process.
431
432@item ESRCH
433The process indicated by the parameter pid is invalid.
434
435@end table
436
437@subheading DESCRIPTION:
438
439This function sends the signal @code{sig} to the process @code{pid}.
440
441@subheading NOTES:
442
443NONE
444 
445@page
446@subsection sigpending - Examine Pending Signals
447 
448@subheading CALLING SEQUENCE:
449 
450@example
451#include <signal.h>
452 
453int sigpending(
454  const sigset_t  *set
455);
456@end example
457 
458@subheading STATUS CODES:
459
460On error, this routine returns -1 and sets errno to one of the following:
461 
462@table @b
463
464@item EFAULT
465Invalid address for set.
466
467@end table
468
469@subheading DESCRIPTION:
470
471This function allows the caller to examine the set of currently pending
472signals.  A pending signal is one which has been raised but is currently
473blocked.  The set of pending signals is returned in @code{set}.
474 
475@subheading NOTES:
476
477NONE
478
479@page
480@subsection sigsuspend - Wait for a Signal
481 
482@subheading CALLING SEQUENCE:
483 
484@example
485#include <signal.h>
486 
487int sigsuspend(
488  const sigset_t  *sigmask
489);
490@end example
491 
492@subheading STATUS CODES:
493
494@table @b
495Returns -1 and sets errno.
496
497@item EINTR
498Signal interrupted this function.
499 
500@end table
501 
502@subheading DESCRIPTION:
503
504This function temporarily replaces the signal mask for the process
505with that specified by @code{sigmask} and blocks the calling thread
506until the signal is raised.
507 
508@subheading NOTES:
509
510NONE
511
512@page
513@subsection pause - Suspend Process Execution
514 
515@subheading CALLING SEQUENCE:
516 
517@example
518#include <signal.h>
519 
520int pause( void );
521@end example
522 
523@subheading STATUS CODES:
524
525@table @b
526Returns -1 and sets errno.
527 
528@item EINTR
529Signal interrupted this function.
530 
531@end table
532 
533@subheading DESCRIPTION:
534
535This function causes the calling thread to be blocked until the signal
536is received.
537 
538@subheading NOTES:
539
540NONE
541 
542@page
543@subsection sigwait - Synchronously Accept a Signal
544
545@subheading CALLING SEQUENCE:
546
547@example
548#include <signal.h>
549
550int sigwait(
551  const sigset_t  *set,
552  int             *sig
553);
554@end example
555
556@subheading STATUS CODES:
557@table @b
558@item EINVAL
559Invalid argument passed.
560
561@item EINTR
562Signal interrupted this function.
563
564@end table
565
566@subheading DESCRIPTION:
567
568This function selects a pending signal based on the set specified in
569@code{set}, atomically clears it from the set of pending signals, and
570returns the signal number for that signal in @code{sig}.
571
572
573@subheading NOTES:
574
575NONE
576
577@page
578@subsection sigwaitinfo - Synchronously Accept a Signal
579 
580@subheading CALLING SEQUENCE:
581 
582@example
583#include <signal.h>
584 
585int sigwaitinfo(
586  const sigset_t  *set,
587  siginfo_t       *info
588);
589@end example
590 
591@subheading STATUS CODES:
592@table @b
593@item EINTR
594Signal interrupted this function.
595 
596@end table
597 
598@subheading DESCRIPTION:
599 
600This function selects a pending signal based on the set specified in
601@code{set}, atomically clears it from the set of pending signals, and
602returns information about that signal in @code{info}.
603
604@subheading NOTES:
605
606NONE
607
608@page
609@subsection sigtimedwait - Synchronously Accept a Signal with Timeout
610 
611@subheading CALLING SEQUENCE:
612 
613@example
614#include <signal.h>
615 
616int sigtimedwait(
617  const sigset_t         *set,
618  siginfo_t              *info,
619  const struct timespec  *timeout
620);
621@end example
622 
623@subheading STATUS CODES:
624@table @b
625@item EAGAIN
626Timed out while waiting for the specified signal set.
627 
628@item EINVAL
629Nanoseconds field of the timeout argument is invalid.
630 
631@item EINTR
632Signal interrupted this function.
633 
634@end table
635 
636@subheading DESCRIPTION:
637 
638This function selects a pending signal based on the set specified in
639@code{set}, atomically clears it from the set of pending signals, and
640returns information about that signal in @code{info}.  The calling thread
641will block up to @code{timeout} waiting for the signal to arrive.
642
643@subheading NOTES:
644
645If @code{timeout} is NULL, then the calling thread will wait forever for
646the specified signal set.
647
648@page
649@subsection sigqueue - Queue a Signal to a Process
650 
651@subheading CALLING SEQUENCE:
652 
653@example
654#include <signal.h>
655 
656int sigqueue(
657  pid_t               pid,
658  int                 signo,
659  const union sigval  value
660);
661@end example
662 
663@subheading STATUS CODES:
664
665@table @b
666
667@item EAGAIN
668No resources available to queue the signal.  The process has already
669queued SIGQUEUE_MAX signals that are still pending at the receiver
670or the systemwide resource limit has been exceeded.
671 
672@item EINVAL
673The value of the signo argument is an invalid or unsupported signal
674number.
675 
676@item EPERM
677The process does not have the appropriate privilege to send the signal
678to the receiving process.
679
680@item ESRCH
681The process pid does not exist.
682 
683@end table
684 
685@subheading DESCRIPTION:
686
687This function sends the signal specified by @code{signo} to the
688process @code{pid}
689 
690@subheading NOTES:
691
692NONE
693
694@page
695@subsection alarm - Schedule Alarm
696 
697@subheading CALLING SEQUENCE:
698 
699@example
700#include <signal.h>
701 
702unsigned int alarm(
703  unsigned int  seconds
704);
705@end example
706 
707@subheading STATUS CODES:
708
709This call always succeeds.
710 
711@subheading DESCRIPTION:
712 
713If there was a previous @code{alarm()} request with time remaining,
714then this routine returns the number of seconds until that outstanding
715alarm would have fired.  If no previous @code{alarm()} request was
716outstanding, then zero is returned.
717
718@subheading NOTES:
719
720NONE
Note: See TracBrowser for help on using the repository browser.