source: rtems/doc/posix_users/signal.t @ c4dddee

4.104.114.84.95
Last change on this file since c4dddee was c4dddee, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 19, 1998 at 4:06:46 PM

Major update/merge of POSIX manual.

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