source: rtems/doc/posix_users/signal.t @ 0a535af

4.104.114.84.95
Last change on this file since 0a535af was 0a535af, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 28, 2002 at 7:14:44 PM

2001-06-28 Joel Sherrill <joel@…>

  • preface.texi, procenv.t, process.t, signal.t, stamp-vti, version.texi: Updated as part of starting a sweep on the POSIX User's Guide.
  • Property mode set to 100644
File size: 16.7 KB
Line 
1@c
2@c COPYRIGHT (c) 1988-2002.
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 provides the functionality associated with
14the generation, delivery, and management of process-oriented
15signals.
16
17The directives provided by the signal manager are:
18
19@itemize @bullet
20@item @code{sigaddset} - Add a Signal to a Signal Set
21@item @code{sigdelset} - Delete a Signal from a Signal Set
22@item @code{sigfillset} - Fill a Signal Set
23@item @code{sigismember} - Is Signal a Member of a Signal Set
24@item @code{sigemptyset} - Empty a Signal Set
25@item @code{sigaction} - Examine and Change Signal Action
26@item @code{pthread_kill} - Send a Signal to a Thread
27@item @code{sigprocmask} - Examine and Change Process Blocked Signals
28@item @code{pthread_sigmask} - Examine and Change Thread Blocked Signals
29@item @code{kill} - Send a Signal to a Process
30@item @code{sigpending} - Examine Pending Signals
31@item @code{sigsuspend} - Wait for a Signal
32@item @code{pause} - Suspend Process Execution
33@item @code{sigwait} - Synchronously Accept a Signal
34@item @code{sigwaitinfo} - Synchronously Accept a Signal
35@item @code{sigtimedwait} - Synchronously Accept a Signal with Timeout
36@item @code{sigqueue} - Queue a Signal to a Process
37@item @code{alarm} - Schedule Alarm
38@end itemize
39
40@section Background
41
42@subsection Signals
43
44POSIX signals are an asynchronous event mechanism.  Each process
45and thread has a set of signals associated with it.  Individual
46signals may be enabled (e.g. unmasked) or blocked (e.g. ignored)
47on both a per-thread and process level.  Signals which are
48enabled have a signal handler associated with them.  When the
49signal is generated and conditions are met, then the signal
50handler is invoked in the proper process or thread context
51asynchronous relative to the logical thread of execution.
52
53If a signal has been blocked when it is generated, then it
54is queued and kept pending until the thread or process unblocks
55the signal or explicitly checks for it.
56Traditional, non-real-time POSIX signals do not queue.  Thus
57if a process or thread has blocked a particular signal, then
58multiple occurrences of that signal are recorded as a
59single occurrence of that signal. 
60
61One can check for the set of outstanding signals that have been
62blocked.   Services are provided to check for outstanding process
63or thread directed signals.
64
65@subsection Signal Delivery
66
67Signals which are directed at a thread are delivered to the specified thread.
68
69Signals which are directed at a process are delivered to a thread which
70is selected based on the following algorithm:
71
72@enumerate
73@item If the action for this signal is currently @code{SIG_IGN},
74then the signal is simply ignored.
75
76@item If the currently executing thread has the signal unblocked, then
77the signal is delivered to it.
78
79@item If any threads are currently blocked waiting for this signal
80(@code{sigwait()}), then the signal is delivered to the highest priority
81thread waiting for this signal.
82
83@item If any other threads are willing to accept delivery of the signal, then
84the signal is delivered to the highest priority thread of this set. In the
85event, multiple threads of the same priority are willing to accept this
86signal, then priority is given first to ready threads, then to threads
87blocked on calls which may be interrupted, and finally to threads blocked
88on non-interruptible calls.
89
90@item In the event the signal still can not be delivered, then it is left
91pending. The first thread to unblock the signal (@code{sigprocmask()} or
92@code{pthread_sigprocmask()}) or to wait for this signal
93(@code{sigwait()}) will be the recipient of the signal.
94
95@end enumerate
96
97@section Operations
98
99@subsection Signal Set Management
100
101Each process and each thread within that process has a set of
102individual signals and handlers associated with it.   Services
103are provided to construct signal sets for the purposes of building
104signal sets -- type @code{sigset_t} -- that are used to
105provide arguments to the services that mask, unmask, and
106check on pending signals.
107
108@subsection Blocking Until Signal Generation
109
110A thread may block until receipt of a signal.  The "sigwait"
111and "pause" families of services block until the requested
112signal is received or if using @code{sigtimedwait()} until the specified
113timeout period has elapsed.
114
115@subsection Sending a Signal
116
117This is accomplished
118via one of a number of services that sends a signal to either a
119process or thread.  Signals may be directed at a process by
120the service @code{kill()} or at a thread by the service
121@code{pthread_kill()}
122
123@section Directives
124
125This section details the signal manager's directives.
126A subsection is dedicated to each of this manager's directives
127and describes the calling sequence, related constants, usage,
128and status codes.
129
130@c
131@c
132@c
133@page
134@subsection sigaddset - Add a Signal to a Signal Set
135
136@findex sigaddset
137@cindex  add a signal to a signal set
138
139@subheading CALLING SEQUENCE:
140
141@example
142#include <signal.h>
143
144int sigaddset(
145  sigset_t *set,
146  int       signo
147);
148@end example
149
150@subheading STATUS CODES:
151
152@table @b
153@item EINVAL
154Invalid argument passed.
155
156@end table
157
158@subheading DESCRIPTION:
159
160This function adds the @code{signo} to the specified signal @code{set}.
161
162@subheading NOTES:
163
164NONE
165
166@c
167@c
168@c
169@page
170@subsection sigdelset - Delete a Signal from a Signal Set
171
172@findex sigdelset
173@cindex  delete a signal from a signal set
174
175@subheading CALLING SEQUENCE:
176
177@example
178#include <signal.h>
179
180int sigdelset(
181  sigset_t *set,
182  int       signo
183);
184@end example
185
186@subheading STATUS CODES:
187
188@table @b
189@item EINVAL
190Invalid argument passed.
191
192@end table
193
194@subheading DESCRIPTION:
195
196This function deletes the @code{signo} to the specified signal @code{set}.
197
198@subheading NOTES:
199
200NONE
201
202@c
203@c
204@c
205@page
206@subsection sigfillset - Fill a Signal Set
207
208@findex sigfillset
209@cindex  fill a signal set
210
211@subheading CALLING SEQUENCE:
212
213@example
214#include <signal.h>
215
216int sigfillset(
217  sigset_t *set
218);
219@end example
220
221@subheading STATUS CODES:
222
223@table @b
224
225@item EINVAL
226Invalid argument passed.
227
228@end table
229
230@subheading DESCRIPTION:
231
232This function fills the specified signal @code{set} such that all
233signals are set.
234
235@subheading NOTES:
236
237NONE
238
239@c
240@c
241@c
242@page
243@subsection sigismember - Is Signal a Member of a Signal Set
244
245@findex sigismember
246@cindex  is signal a member of a signal set
247
248@subheading CALLING SEQUENCE:
249
250@example
251#include <signal.h>
252
253int sigismember(
254  const sigset_t *set,
255  int             signo
256);
257@end example
258
259@subheading STATUS CODES:
260
261@table @b
262
263@item EINVAL
264Invalid argument passed.
265
266@end table
267
268@subheading DESCRIPTION:
269
270This function returns returns 1 if @code{signo} is a member of @code{set}
271and 0 otherwise.
272
273@subheading NOTES:
274
275NONE
276
277@c
278@c
279@c
280@page
281@subsection sigemptyset - Empty a Signal Set
282
283@findex sigemptyset
284@cindex  empty a signal set
285
286@subheading CALLING SEQUENCE:
287
288@example
289#include <signal.h>
290
291int sigemptyset(
292  sigset_t *set
293);
294@end example
295
296@subheading STATUS CODES:
297
298@table @b
299
300@item EINVAL
301Invalid argument passed.
302
303@end table
304
305@subheading DESCRIPTION:
306
307This function fills the specified signal @code{set} such that all
308signals are cleared.
309
310@subheading NOTES:
311
312NONE
313
314@c
315@c
316@c
317@page
318@subsection sigaction - Examine and Change Signal Action
319
320@findex sigaction
321@cindex  examine and change signal action
322
323@subheading CALLING SEQUENCE:
324
325@example
326#include <signal.h>
327
328int sigaction(
329  int                     sig,
330  const struct sigaction *act,
331  struct sigaction       *oact
332);
333@end example
334
335@subheading STATUS CODES:
336
337@table @b
338@item EINVAL
339Invalid argument passed.
340
341@item ENOTSUP
342Realtime Signals Extension option not supported.
343
344@end table
345
346@subheading DESCRIPTION:
347
348This function is used to change the action taken by a process on
349receipt of the specfic signal @code{sig}. The new action is
350specified by @code{act} and the previous action is returned
351via @code{oact}.
352
353@subheading NOTES:
354
355The signal number cannot be SIGKILL.
356
357@c
358@c
359@c
360@page
361@subsection pthread_kill - Send a Signal to a Thread
362
363@findex pthread_kill
364@cindex  send a signal to a thread
365
366@subheading CALLING SEQUENCE:
367
368@example
369#include <signal.h>
370
371int pthread_kill(
372  pthread_t thread,
373  int       sig
374);
375@end example
376
377@subheading STATUS CODES:
378
379@table @b
380
381@item ESRCH
382The thread indicated by the parameter thread is invalid.
383
384@item EINVAL
385Invalid argument passed.
386
387@end table
388
389@subheading DESCRIPTION:
390
391This functions sends the specified signal @code{sig} to @code{thread}.
392
393@subheading NOTES:
394
395NONE
396
397@c
398@c
399@c
400@page
401@subsection sigprocmask - Examine and Change Process Blocked Signals
402
403@findex sigprocmask
404@cindex  examine and change process blocked signals
405
406@subheading CALLING SEQUENCE:
407
408@example
409#include <signal.h>
410
411int sigprocmask(
412  int             how,
413  const sigset_t *set,
414  sigset_t       *oset
415);
416@end example
417
418@subheading STATUS CODES:
419
420@table @b
421
422@item EINVAL
423Invalid argument passed.
424
425@end table
426
427@subheading DESCRIPTION:
428
429This function is used to alter the set of currently blocked signals
430on a process wide basis. A blocked signal will not be received by the
431process. The behavior of this function is dependent on the value of
432@code{how} which may be one of the following:
433
434@table @code
435
436@item SIG_BLOCK
437The set of blocked signals is set to the union of @code{set} and
438those signals currently blocked.
439
440@item SIG_UNBLOCK
441The signals specific in @code{set} are removed from the currently
442blocked set.
443
444@item SIG_SETMASK
445The set of currently blocked signals is set to @code{set}.
446
447@end table
448
449If @code{oset} is not @code{NULL}, then the set of blocked signals
450prior to this call is returned in @code{oset}.
451
452@subheading NOTES:
453
454It is not an error to unblock a signal which is not blocked.
455
456@c
457@c
458@c
459@page
460@subsection pthread_sigmask - Examine and Change Thread Blocked Signals
461
462@findex pthread_sigmask
463@cindex  examine and change thread blocked signals
464
465@subheading CALLING SEQUENCE:
466
467@example
468#include <signal.h>
469
470int pthread_sigmask(
471  int             how,
472  const sigset_t *set,
473  sigset_t       *oset
474);
475@end example
476
477@subheading STATUS CODES:
478@table @b
479@item EINVAL
480Invalid argument passed.
481
482@end table
483
484@subheading DESCRIPTION:
485
486This function is used to alter the set of currently blocked signals
487for the calling thread. A blocked signal will not be received by the
488process. The behavior of this function is dependent on the value of
489@code{how} which may be one of the following:
490
491@table @code
492@item SIG_BLOCK
493The set of blocked signals is set to the union of @code{set} and
494those signals currently blocked.
495
496@item SIG_UNBLOCK
497The signals specific in @code{set} are removed from the currently
498blocked set.
499
500@item SIG_SETMASK
501The set of currently blocked signals is set to @code{set}.
502
503@end table
504
505If @code{oset} is not @code{NULL}, then the set of blocked signals
506prior to this call is returned in @code{oset}.
507
508@subheading NOTES:
509
510It is not an error to unblock a signal which is not blocked.
511
512
513@c
514@c
515@c
516@page
517@subsection kill - Send a Signal to a Process
518
519@findex kill
520@cindex  send a signal to a process
521
522@subheading CALLING SEQUENCE:
523
524@example
525#include <sys/types.h>
526#include <signal.h>
527
528int kill(
529  pid_t pid,
530  int   sig
531);
532@end example
533
534@subheading STATUS CODES:
535@table @b
536@item EINVAL
537Invalid argument passed.
538
539@item EPERM
540Process does not have permission to send the signal to any receiving process.
541
542@item ESRCH
543The process indicated by the parameter pid is invalid.
544
545@end table
546
547@subheading DESCRIPTION:
548
549This function sends the signal @code{sig} to the process @code{pid}.
550
551@subheading NOTES:
552
553NONE
554
555@c
556@c
557@c
558@page
559@subsection sigpending - Examine Pending Signals
560
561@findex sigpending
562@cindex  examine pending signals
563
564@subheading CALLING SEQUENCE:
565
566@example
567#include <signal.h>
568
569int sigpending(
570  const sigset_t *set
571);
572@end example
573
574@subheading STATUS CODES:
575
576On error, this routine returns -1 and sets @code{errno} to one of
577the following:
578
579@table @b
580
581@item EFAULT
582Invalid address for set.
583
584@end table
585
586@subheading DESCRIPTION:
587
588This function allows the caller to examine the set of currently pending
589signals. A pending signal is one which has been raised but is currently
590blocked. The set of pending signals is returned in @code{set}.
591
592@subheading NOTES:
593
594NONE
595
596@c
597@c
598@c
599@page
600@subsection sigsuspend - Wait for a Signal
601
602@findex sigsuspend
603@cindex  wait for a signal
604
605@subheading CALLING SEQUENCE:
606
607@example
608#include <signal.h>
609
610int sigsuspend(
611  const sigset_t *sigmask
612);
613@end example
614
615@subheading STATUS CODES:
616
617On error, this routine returns -1 and sets @code{errno} to one of
618the following:
619
620@table @b
621
622@item EINTR
623Signal interrupted this function.
624
625@end table
626
627@subheading DESCRIPTION:
628
629This function temporarily replaces the signal mask for the process
630with that specified by @code{sigmask} and blocks the calling thread
631until the signal is raised.
632
633@subheading NOTES:
634
635NONE
636
637@c
638@c
639@c
640@page
641@subsection pause - Suspend Process Execution
642
643@findex pause
644@cindex  suspend process execution
645
646@subheading CALLING SEQUENCE:
647
648@example
649#include <signal.h>
650
651int pause( void );
652@end example
653
654@subheading STATUS CODES:
655
656On error, this routine returns -1 and sets @code{errno} to one of
657the following:
658
659@table @b
660
661@item EINTR
662Signal interrupted this function.
663
664@end table
665
666@subheading DESCRIPTION:
667
668This function causes the calling thread to be blocked until an
669unblocked signal is received.
670
671@subheading NOTES:
672
673NONE
674
675@c
676@c
677@c
678@page
679@subsection sigwait - Synchronously Accept a Signal
680
681@findex sigwait
682@cindex  synchronously accept a signal
683
684@subheading CALLING SEQUENCE:
685
686@example
687#include <signal.h>
688
689int sigwait(
690  const sigset_t *set,
691  int            *sig
692);
693@end example
694
695@subheading STATUS CODES:
696@table @b
697@item EINVAL
698Invalid argument passed.
699
700@item EINTR
701Signal interrupted this function.
702
703@end table
704
705@subheading DESCRIPTION:
706
707This function selects a pending signal based on the set specified in
708@code{set}, atomically clears it from the set of pending signals, and
709returns the signal number for that signal in @code{sig}.
710
711
712@subheading NOTES:
713
714NONE
715
716@c
717@c
718@c
719@page
720@subsection sigwaitinfo - Synchronously Accept a Signal
721
722@findex sigwaitinfo
723@cindex  synchronously accept a signal
724
725@subheading CALLING SEQUENCE:
726
727@example
728#include <signal.h>
729
730int sigwaitinfo(
731  const sigset_t *set,
732  siginfo_t      *info
733);
734@end example
735
736@subheading STATUS CODES:
737@table @b
738@item EINTR
739Signal interrupted this function.
740
741@end table
742
743@subheading DESCRIPTION:
744
745This function selects a pending signal based on the set specified in
746@code{set}, atomically clears it from the set of pending signals, and
747returns information about that signal in @code{info}.
748
749@subheading NOTES:
750
751NONE
752
753@c
754@c
755@c
756@page
757@subsection sigtimedwait - Synchronously Accept a Signal with Timeout
758
759@findex sigtimedwait
760@cindex  synchronously accept a signal with timeout
761
762@subheading CALLING SEQUENCE:
763
764@example
765#include <signal.h>
766
767int sigtimedwait(
768  const sigset_t        *set,
769  siginfo_t             *info,
770  const struct timespec *timeout
771);
772@end example
773
774@subheading STATUS CODES:
775@table @b
776@item EAGAIN
777Timed out while waiting for the specified signal set.
778
779@item EINVAL
780Nanoseconds field of the timeout argument is invalid.
781
782@item EINTR
783Signal interrupted this function.
784
785@end table
786
787@subheading DESCRIPTION:
788
789This function selects a pending signal based on the set specified in
790@code{set}, atomically clears it from the set of pending signals, and
791returns information about that signal in @code{info}. The calling thread
792will block up to @code{timeout} waiting for the signal to arrive.
793
794@subheading NOTES:
795
796If @code{timeout} is NULL, then the calling thread will wait forever for
797the specified signal set.
798
799@c
800@c
801@c
802@page
803@subsection sigqueue - Queue a Signal to a Process
804
805@findex sigqueue
806@cindex  queue a signal to a process
807
808@subheading CALLING SEQUENCE:
809
810@example
811#include <signal.h>
812
813int sigqueue(
814  pid_t              pid,
815  int                signo,
816  const union sigval value
817);
818@end example
819
820@subheading STATUS CODES:
821
822@table @b
823
824@item EAGAIN
825No resources available to queue the signal. The process has already
826queued SIGQUEUE_MAX signals that are still pending at the receiver
827or the systemwide resource limit has been exceeded.
828
829@item EINVAL
830The value of the signo argument is an invalid or unsupported signal
831number.
832
833@item EPERM
834The process does not have the appropriate privilege to send the signal
835to the receiving process.
836
837@item ESRCH
838The process pid does not exist.
839
840@end table
841
842@subheading DESCRIPTION:
843
844This function sends the signal specified by @code{signo} to the
845process @code{pid}
846
847@subheading NOTES:
848
849NONE
850
851@c
852@c
853@c
854@page
855@subsection alarm - Schedule Alarm
856
857@findex alarm
858@cindex  schedule alarm
859
860@subheading CALLING SEQUENCE:
861
862@example
863#include <signal.h>
864
865unsigned int alarm(
866  unsigned int seconds
867);
868@end example
869
870@subheading STATUS CODES:
871
872This call always succeeds.
873
874@subheading DESCRIPTION:
875
876If there was a previous @code{alarm()} request with time remaining,
877then this routine returns the number of seconds until that outstanding
878alarm would have fired. If no previous @code{alarm()} request was
879outstanding, then zero is returned.
880
881@subheading NOTES:
882
883NONE
Note: See TracBrowser for help on using the repository browser.