source: rtems/doc/posix_users/signal.t @ 0660b4f8

4.104.114.84.95
Last change on this file since 0660b4f8 was 0660b4f8, checked in by Joel Sherrill <joel.sherrill@…>, on 11/16/99 at 19:50:56

Changed copyright date to 1999.

  • Property mode set to 100644
File size: 14.5 KB
Line 
1@c
2@c COPYRIGHT (c) 1988-1999.
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@c
84@c
85@c
86@page
87@subsection sigaddset - Add a Signal to a Signal Set
88
89@findex sigaddset
90@cindex  add a signal to a signal set
91
92@subheading CALLING SEQUENCE:
93
94@example
95#include <signal.h>
96
97int sigaddset(
98sigset_t *set,
99int signo
100);
101@end example
102
103@subheading STATUS CODES:
104
105@table @b
106@item EINVAL
107Invalid argument passed.
108
109@end table
110
111@subheading DESCRIPTION:
112
113This function adds the @code{signo} to the specified signal @code{set}.
114
115@subheading NOTES:
116
117NONE
118
119@c
120@c
121@c
122@page
123@subsection sigdelset - Delete a Signal from a Signal Set
124
125@findex sigdelset
126@cindex  delete a signal from a signal set
127
128@subheading CALLING SEQUENCE:
129
130@example
131#include <signal.h>
132
133int sigdelset(
134sigset_t *set,
135int signo
136);
137@end example
138
139@subheading STATUS CODES:
140
141@table @b
142@item EINVAL
143Invalid argument passed.
144
145@end table
146
147@subheading DESCRIPTION:
148
149This function deletes the @code{signo} to the specified signal @code{set}.
150
151@subheading NOTES:
152
153NONE
154
155@c
156@c
157@c
158@page
159@subsection sigfillset - Fill a Signal Set
160
161@findex sigfillset
162@cindex  fill a signal set
163
164@subheading CALLING SEQUENCE:
165
166@example
167#include <signal.h>
168
169int sigfillset(
170sigset_t *set
171);
172@end example
173
174@subheading STATUS CODES:
175
176@table @b
177
178@item EINVAL
179Invalid argument passed.
180
181@end table
182
183@subheading DESCRIPTION:
184
185This function fills the specified signal @code{set} such that all
186signals are set.
187
188@subheading NOTES:
189
190NONE
191
192@c
193@c
194@c
195@page
196@subsection sigismember - Is Signal a Member of a Signal Set
197
198@findex sigismember
199@cindex  is signal a member of a signal set
200
201@subheading CALLING SEQUENCE:
202
203@example
204#include <signal.h>
205
206int sigismember(
207const sigset_t *set,
208int signo
209);
210@end example
211
212@subheading STATUS CODES:
213
214@table @b
215
216@item EINVAL
217Invalid argument passed.
218
219@end table
220
221@subheading DESCRIPTION:
222
223This function returns returns 1 if @code{signo} is a member of @code{set}
224and 0 otherwise.
225
226@subheading NOTES:
227
228NONE
229
230@c
231@c
232@c
233@page
234@subsection sigemptyset - Empty a Signal Set
235
236@findex sigemptyset
237@cindex  empty a signal set
238
239@subheading CALLING SEQUENCE:
240
241@example
242#include <signal.h>
243
244int sigemptyset(
245sigset_t *set
246);
247@end example
248
249@subheading STATUS CODES:
250
251@table @b
252
253@item EINVAL
254Invalid argument passed.
255
256@end table
257
258@subheading DESCRIPTION:
259
260This function fills the specified signal @code{set} such that all
261signals are cleared.
262
263@subheading NOTES:
264
265NONE
266
267@c
268@c
269@c
270@page
271@subsection sigaction - Examine and Change Signal Action
272
273@findex sigaction
274@cindex  examine and change signal action
275
276@subheading CALLING SEQUENCE:
277
278@example
279#include <signal.h>
280
281int sigaction(
282int sig,
283const struct sigaction *act,
284struct sigaction *oact
285);
286@end example
287
288@subheading STATUS CODES:
289
290@table @b
291@item EINVAL
292Invalid argument passed.
293
294@item ENOTSUP
295Realtime Signals Extension option not supported.
296
297@end table
298
299@subheading DESCRIPTION:
300
301This function is used to change the action taken by a process on
302receipt of the specfic signal @code{sig}. The new action is
303specified by @code{act} and the previous action is returned
304via @code{oact}.
305
306@subheading NOTES:
307
308The signal number cannot be SIGKILL.
309
310@c
311@c
312@c
313@page
314@subsection pthread_kill - Send a Signal to a Thread
315
316@findex pthread_kill
317@cindex  send a signal to a thread
318
319@subheading CALLING SEQUENCE:
320
321@example
322#include <signal.h>
323
324int pthread_kill(
325pthread_t thread,
326int sig
327);
328@end example
329
330@subheading STATUS CODES:
331
332@table @b
333
334@item ESRCH
335The thread indicated by the parameter thread is invalid.
336
337@item EINVAL
338Invalid argument passed.
339
340@end table
341
342@subheading DESCRIPTION:
343
344This functions sends the specified signal @code{sig} to @code{thread}.
345
346@subheading NOTES:
347
348NONE
349
350@c
351@c
352@c
353@page
354@subsection sigprocmask - Examine and Change Process Blocked Signals
355
356@findex sigprocmask
357@cindex  examine and change process blocked signals
358
359@subheading CALLING SEQUENCE:
360
361@example
362#include <signal.h>
363
364int sigprocmask(
365int how,
366const sigset_t *set,
367sigset_t *oset
368);
369@end example
370
371@subheading STATUS CODES:
372
373@table @b
374
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
383on a process wide basis. 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
389@item SIG_BLOCK
390The set of blocked signals is set to the union of @code{set} and
391those signals currently blocked.
392
393@item SIG_UNBLOCK
394The signals specific in @code{set} are removed from the currently
395blocked set.
396
397@item SIG_SETMASK
398The set of currently blocked signals is set to @code{set}.
399
400@end table
401
402If @code{oset} is not @code{NULL}, then the set of blocked signals
403prior to this call is returned in @code{oset}.
404
405@subheading NOTES:
406
407It is not an error to unblock a signal which is not blocked.
408
409@c
410@c
411@c
412@page
413@subsection pthread_sigmask - Examine and Change Thread Blocked Signals
414
415@findex pthread_sigmask
416@cindex  examine and change thread blocked signals
417
418@subheading CALLING SEQUENCE:
419
420@example
421#include <signal.h>
422
423int pthread_sigmask(
424int how,
425const sigset_t *set,
426sigset_t *oset
427);
428@end example
429
430@subheading STATUS CODES:
431@table @b
432@item EINVAL
433Invalid argument passed.
434
435@end table
436
437@subheading DESCRIPTION:
438
439This function is used to alter the set of currently blocked signals
440for the calling thread. A blocked signal will not be received by the
441process. The behavior of this function is dependent on the value of
442@code{how} which may be one of the following:
443
444@table @code
445@item SIG_BLOCK
446The set of blocked signals is set to the union of @code{set} and
447those signals currently blocked.
448
449@item SIG_UNBLOCK
450The signals specific in @code{set} are removed from the currently
451blocked set.
452
453@item SIG_SETMASK
454The set of currently blocked signals is set to @code{set}.
455
456@end table
457
458If @code{oset} is not @code{NULL}, then the set of blocked signals
459prior to this call is returned in @code{oset}.
460
461@subheading NOTES:
462
463It is not an error to unblock a signal which is not blocked.
464
465
466@c
467@c
468@c
469@page
470@subsection kill - Send a Signal to a Process
471
472@findex kill
473@cindex  send a signal to a process
474
475@subheading CALLING SEQUENCE:
476
477@example
478#include <sys/types.h>
479#include <signal.h>
480
481int kill(
482pid_t pid,
483int sig
484);
485@end example
486
487@subheading STATUS CODES:
488@table @b
489@item EINVAL
490Invalid argument passed.
491
492@item EPERM
493Process does not have permission to send the signal to any receiving process.
494
495@item ESRCH
496The process indicated by the parameter pid is invalid.
497
498@end table
499
500@subheading DESCRIPTION:
501
502This function sends the signal @code{sig} to the process @code{pid}.
503
504@subheading NOTES:
505
506NONE
507
508@c
509@c
510@c
511@page
512@subsection sigpending - Examine Pending Signals
513
514@findex sigpending
515@cindex  examine pending signals
516
517@subheading CALLING SEQUENCE:
518
519@example
520#include <signal.h>
521
522int sigpending(
523const sigset_t *set
524);
525@end example
526
527@subheading STATUS CODES:
528
529On error, this routine returns -1 and sets @code{errno} to one of
530the following:
531
532@table @b
533
534@item EFAULT
535Invalid address for set.
536
537@end table
538
539@subheading DESCRIPTION:
540
541This function allows the caller to examine the set of currently pending
542signals. A pending signal is one which has been raised but is currently
543blocked. The set of pending signals is returned in @code{set}.
544
545@subheading NOTES:
546
547NONE
548
549@c
550@c
551@c
552@page
553@subsection sigsuspend - Wait for a Signal
554
555@findex sigsuspend
556@cindex  wait for a signal
557
558@subheading CALLING SEQUENCE:
559
560@example
561#include <signal.h>
562
563int sigsuspend(
564const sigset_t *sigmask
565);
566@end example
567
568@subheading STATUS CODES:
569
570On error, this routine returns -1 and sets @code{errno} to one of
571the following:
572
573@table @b
574
575@item EINTR
576Signal interrupted this function.
577
578@end table
579
580@subheading DESCRIPTION:
581
582This function temporarily replaces the signal mask for the process
583with that specified by @code{sigmask} and blocks the calling thread
584until the signal is raised.
585
586@subheading NOTES:
587
588NONE
589
590@c
591@c
592@c
593@page
594@subsection pause - Suspend Process Execution
595
596@findex pause
597@cindex  suspend process execution
598
599@subheading CALLING SEQUENCE:
600
601@example
602#include <signal.h>
603
604int pause( void );
605@end example
606
607@subheading STATUS CODES:
608
609On error, this routine returns -1 and sets @code{errno} to one of
610the following:
611
612@table @b
613
614@item EINTR
615Signal interrupted this function.
616
617@end table
618
619@subheading DESCRIPTION:
620
621This function causes the calling thread to be blocked until the signal
622is received.
623
624@subheading NOTES:
625
626NONE
627
628@c
629@c
630@c
631@page
632@subsection sigwait - Synchronously Accept a Signal
633
634@findex sigwait
635@cindex  synchronously accept a signal
636
637@subheading CALLING SEQUENCE:
638
639@example
640#include <signal.h>
641
642int sigwait(
643const sigset_t *set,
644int *sig
645);
646@end example
647
648@subheading STATUS CODES:
649@table @b
650@item EINVAL
651Invalid argument passed.
652
653@item EINTR
654Signal interrupted this function.
655
656@end table
657
658@subheading DESCRIPTION:
659
660This function selects a pending signal based on the set specified in
661@code{set}, atomically clears it from the set of pending signals, and
662returns the signal number for that signal in @code{sig}.
663
664
665@subheading NOTES:
666
667NONE
668
669@c
670@c
671@c
672@page
673@subsection sigwaitinfo - Synchronously Accept a Signal
674
675@findex sigwaitinfo
676@cindex  synchronously accept a signal
677
678@subheading CALLING SEQUENCE:
679
680@example
681#include <signal.h>
682
683int sigwaitinfo(
684const sigset_t *set,
685siginfo_t *info
686);
687@end example
688
689@subheading STATUS CODES:
690@table @b
691@item EINTR
692Signal interrupted this function.
693
694@end table
695
696@subheading DESCRIPTION:
697
698This function selects a pending signal based on the set specified in
699@code{set}, atomically clears it from the set of pending signals, and
700returns information about that signal in @code{info}.
701
702@subheading NOTES:
703
704NONE
705
706@c
707@c
708@c
709@page
710@subsection sigtimedwait - Synchronously Accept a Signal with Timeout
711
712@findex sigtimedwait
713@cindex  synchronously accept a signal with timeout
714
715@subheading CALLING SEQUENCE:
716
717@example
718#include <signal.h>
719
720int sigtimedwait(
721const sigset_t *set,
722siginfo_t *info,
723const struct timespec *timeout
724);
725@end example
726
727@subheading STATUS CODES:
728@table @b
729@item EAGAIN
730Timed out while waiting for the specified signal set.
731
732@item EINVAL
733Nanoseconds field of the timeout argument is invalid.
734
735@item EINTR
736Signal interrupted this function.
737
738@end table
739
740@subheading DESCRIPTION:
741
742This function selects a pending signal based on the set specified in
743@code{set}, atomically clears it from the set of pending signals, and
744returns information about that signal in @code{info}. The calling thread
745will block up to @code{timeout} waiting for the signal to arrive.
746
747@subheading NOTES:
748
749If @code{timeout} is NULL, then the calling thread will wait forever for
750the specified signal set.
751
752@c
753@c
754@c
755@page
756@subsection sigqueue - Queue a Signal to a Process
757
758@findex sigqueue
759@cindex  queue a signal to a process
760
761@subheading CALLING SEQUENCE:
762
763@example
764#include <signal.h>
765
766int sigqueue(
767pid_t pid,
768int signo,
769const union sigval value
770);
771@end example
772
773@subheading STATUS CODES:
774
775@table @b
776
777@item EAGAIN
778No resources available to queue the signal. The process has already
779queued SIGQUEUE_MAX signals that are still pending at the receiver
780or the systemwide resource limit has been exceeded.
781
782@item EINVAL
783The value of the signo argument is an invalid or unsupported signal
784number.
785
786@item EPERM
787The process does not have the appropriate privilege to send the signal
788to the receiving process.
789
790@item ESRCH
791The process pid does not exist.
792
793@end table
794
795@subheading DESCRIPTION:
796
797This function sends the signal specified by @code{signo} to the
798process @code{pid}
799
800@subheading NOTES:
801
802NONE
803
804@c
805@c
806@c
807@page
808@subsection alarm - Schedule Alarm
809
810@findex alarm
811@cindex  schedule alarm
812
813@subheading CALLING SEQUENCE:
814
815@example
816#include <signal.h>
817
818unsigned int alarm(
819unsigned int seconds
820);
821@end example
822
823@subheading STATUS CODES:
824
825This call always succeeds.
826
827@subheading DESCRIPTION:
828
829If there was a previous @code{alarm()} request with time remaining,
830then this routine returns the number of seconds until that outstanding
831alarm would have fired. If no previous @code{alarm()} request was
832outstanding, then zero is returned.
833
834@subheading NOTES:
835
836NONE
Note: See TracBrowser for help on using the repository browser.