summaryrefslogtreecommitdiffstats
path: root/doc/posix_users/signal.texi
blob: c3200460c4ea7e60e99dd26fefccf7c690e76330 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
@c
@c  COPYRIGHT (c) 1996.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@ifinfo
@node Signal Manager, Signal Manager Introduction, pthread_getschedparam, Top
@end ifinfo
@chapter Signal Manager
@ifinfo
@menu
* Signal Manager Introduction::
* Signal Manager Background::
* Signal Manager Operations::
* Signal Manager Directives::
@end menu
@end ifinfo

@ifinfo
@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager
@end ifinfo
@section Introduction

The signal manager ...

The directives provided by the signal manager are:

@itemize @bullet
@item @code{sigaddset} - 
@item @code{sigdelset} - 
@item @code{sigfillset} - 
@item @code{sigismember} - 
@item @code{sigemptyset} - 
@item @code{sigaction} - 
@item @code{pthread_kill} - 
@item @code{sigprocmask} - 
@item @code{pthread_sigmask} - 
@item @code{kill} - 
@item @code{sigpending} - 
@item @code{sigsuspend} - 
@item @code{pause} - 
@item @code{sigwait} - 
@item @code{sigwaitinfo} - 
@item @code{sigtimedwait} - 
@item @code{sigqueue} - 
@item @code{alarm} - 
@end itemize

@ifinfo
@node Signal Manager Background, Signal Delivery, Signal Manager Introduction, Signal Manager
@end ifinfo
@section Background
@ifinfo
@menu
* Signal Delivery::
@end menu
@end ifinfo


@ifinfo
@node Signal Delivery, Signal Manager Operations, Signal Manager Background, Signal Manager Background
@end ifinfo
@subsection Signal Delivery

Signals directed at a thread are delivered to the specified thread.

Signals directed at a process are delivered to a thread which is selected
based on the following algorithm:

@enumerate
@item If the action for this signal is currently SIG_IGN, then the signal
is simply ignored.

@item If the currently executing thread has the signal unblocked, then
the signal is delivered to it.

@item If any threads are currently blocked waiting for this signal 
(sigwait()), then the signal is delivered to the highest priority 
thread waiting for this signal.

@item If any other threads are willing to accept delivery of the signal, then
the signal is delivered to the highest priority thread of this set.  In the
event, multiple threads of the same priority are willing to accept this
signal, then priority is given first to ready threads, then to threads
blocked on calls which may be interrupted, and finally to threads blocked
on non-interruptible calls.

@item In the event the signal still can not be delivered, then it is left
pending.  The first thread to unblock the signal (sigprocmask() or
pthread_sigprocmask()) or to wait for this signal (sigwait()) will be
the recipient of the signal.

@end enumerate

@ifinfo
@node Signal Manager Operations, Signal Manager Directives, Signal Delivery, Signal Manager
@end ifinfo
@section Operations

@ifinfo
@node Signal Manager Directives, sigaddset, Signal Manager Operations, Signal Manager
@end ifinfo
@section Directives
@ifinfo
@menu
* sigaddset::
* sigdelset::
* sigfillset::
* sigismember::
* sigemptyset::
* sigaction::
* pthread_kill::
* sigprocmask::
* pthread_sigmask::
* kill::
* sigpending::
* sigsuspend::
* pause::
* sigwait::
* sigwaitinfo::
* sigtimedwait::
* sigqueue::
* alarm::
@end menu
@end ifinfo

This section details the signal manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.

@page
@ifinfo
@node sigaddset, sigdelset, Signal Manager Directives, Signal Manager Directives
@end ifinfo
@subsection sigaddset

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigaddset(
  sigset_t   *set,
  int         signo
);
@end example

@subheading STATUS CODES:

@table @b
@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigdelset, sigfillset, sigaddset, Signal Manager Directives
@end ifinfo
@subsection sigdelset

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigdelset(
  sigset_t   *set,
  int         signo
);
@end example

@subheading STATUS CODES:

@table @b
@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigfillset, sigismember, sigdelset, Signal Manager Directives
@end ifinfo
@subsection sigfillset

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigfillset(
  sigset_t   *set
);
@end example

@subheading STATUS CODES:
@table @b
@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigismember, sigemptyset, sigfillset, Signal Manager Directives
@end ifinfo
@subsection sigismember

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigismember(
  const sigset_t   *set,
  int               signo
);
@end example

@subheading STATUS CODES:
@table @b
@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigemptyset, sigaction,  sigismember, Signal Manager Directives
@end ifinfo
@subsection sigemptyset

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigemptyset(
  sigset_t   *set
);
@end example

@subheading STATUS CODES:

@table @b
@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigaction, pthread_kill, sigemptyset, Signal Manager Directives
@end ifinfo
@subsection sigaction

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigaction(
  int                     sig,
  const struct sigaction *act,
  struct sigaction       *oact
);
@end example

@subheading STATUS CODES:

@table @b
@item EINVAL
Invalid argument passed.

@item ENOTSUP
Realtime Signals Extension option not supported.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

The signal number cannot be SIGKILL.
@page
@ifinfo
@node pthread_kill, sigprocmask, sigaction, Signal Manager Directives
@end ifinfo
@subsection pthread_kill

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int pthread_kill(
  pthread_t   thread,
  int         sig
);
@end example

@subheading STATUS CODES:
@table @b
@item ESRCH
The thread indicated by the parameter thread is invalid.

@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigprocmask, pthread_sigmask, pthread_kill, Signal Manager Directives
@end ifinfo
@subsection sigprocmask
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int sigprocmask(
  int               how,
  const sigset_t   *set,
  sigset_t         *oset
);
@end example
 
@subheading STATUS CODES:
@table @b
@item EINVAL
Invalid argument passed.
 
@end table
 
@subheading DESCRIPTION:
 
@subheading NOTES:
 

@page
@ifinfo
@node pthread_sigmask, kill, sigprocmask, Signal Manager Directives
@end ifinfo
@subsection pthread_sigmask

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int pthread_sigmask(
  int               how,
  const sigset_t   *set,
  sigset_t         *oset
);
@end example

@subheading STATUS CODES:
@table @b
@item EINVAL
Invalid argument passed.

@end table

@subheading DESCRIPTION:

@subheading NOTES:


@page
@ifinfo
@node kill, sigpending, pthread_sigmask, Signal Manager Directives
@end ifinfo
@subsection kill

@subheading CALLING SEQUENCE:

@example
#include <sys/types.h>
#include <signal.h>

int kill(
  pid_t pid,
  int   sig
);
@end example

@subheading STATUS CODES:
@table @b
@item EINVAL
Invalid argument passed.

@item EPERM
Process does not have permission to send the signal to any receiving process.

@item ESRCH
The process indicated by the parameter pid is invalid.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

 
@page
@ifinfo
@node sigpending, sigsuspend, kill, Signal Manager Directives
@end ifinfo
@subsection sigpending
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int sigpending(
  const sigset_t  *set
);
@end example
 
@subheading STATUS CODES:

On error, this routine returns -1 and sets errno to one of the following:
 
@table @b
@item EFAULT
Invalid address for set.

@end table

@subheading DESCRIPTION:
 
@subheading NOTES:

@page
@ifinfo
@node sigsuspend, pause, sigpending, Signal Manager Directives
@end ifinfo
@subsection sigsuspend
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int sigsuspend(
  const sigset_t  *sigmask
);
@end example
 
@subheading STATUS CODES:
@table @b
Returns -1 and sets errno.

@item EINTR
Signal interrupted this function.
 
@end table
 
@subheading DESCRIPTION:
 
@subheading NOTES:

@page
@ifinfo
@node pause, sigwait, sigsuspend, Signal Manager Directives
@end ifinfo
@subsection pause
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int pause( void );
@end example
 
@subheading STATUS CODES:
@table @b
Returns -1 and sets errno.
 
@item EINTR
Signal interrupted this function.
 
@end table
 
@subheading DESCRIPTION:
 
@subheading NOTES:
 
@page
@ifinfo
@node sigwait, sigwaitinfo, pause, Signal Manager Directives
@end ifinfo
@subsection sigwait

@subheading CALLING SEQUENCE:

@example
#include <signal.h>

int sigwait(
  const sigset_t  *set,
  int             *sig
);
@end example

@subheading STATUS CODES:
@table @b
@item EINVAL
Invalid argument passed.

@item EINTR
Signal interrupted this function.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@ifinfo
@node sigwaitinfo, sigtimedwait, sigwait, Signal Manager Directives
@end ifinfo
@subsection sigwaitinfo
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int sigwaitinfo(
  const sigset_t  *set,
  siginfo_t       *info
);
@end example
 
@subheading STATUS CODES:
@table @b
@item EINTR
Signal interrupted this function.
 
@end table
 
@subheading DESCRIPTION:
 
@subheading NOTES:

@page
@ifinfo
@node sigtimedwait, sigqueue, sigwaitinfo, Signal Manager Directives
@end ifinfo
@subsection sigtimedwait
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int sigtimedwait(
  const sigset_t         *set,
  siginfo_t              *info,
  const struct timespec  *timeout
);
@end example
 
@subheading STATUS CODES:
@table @b
@item EAGAIN
Timed out while waiting for the specified signal set.
 
@item EINVAL
Nanoseconds field of the timeout argument is invalid.
 
@item EINTR
Signal interrupted this function.
 
@end table
 
@subheading DESCRIPTION:
 
@subheading NOTES:

If timeout is NULL, then the thread will wait forever for the specified 
signal set.

@page
@ifinfo
@node sigqueue, alarm, sigtimedwait, Signal Manager Directives
@end ifinfo
@subsection sigqueue
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
int sigqueue(
  pid_t               pid,
  int                 signo,
  const union sigval  value
);
@end example
 
@subheading STATUS CODES:

@table @b

@item EAGAIN
No resources available to queue the signal.  The process has already
queued SIGQUEUE_MAX signals that are still pending at the receiver
or the systemwide resource limit has been exceeded.
 
@item EINVAL
The value of the signo argument is an invalid or unsupported signal
number.
 
@item EPERM
The process does not have the appropriate privilege to send the signal
to the receiving process.

@item ESRCH
The process pid does not exist.
 
@end table
 
@subheading DESCRIPTION:
 
@subheading NOTES:


@page
@ifinfo
@node alarm, Mutex Manager, sigqueue, Signal Manager Directives
@end ifinfo
@subsection alarm
 
@subheading CALLING SEQUENCE:
 
@example
#include <signal.h>
 
unsigned int alarm(
  unsigned int  seconds
);
@end example
 
@subheading STATUS CODES:

If there was a previous alarm() request with time remaining, then this routine
returns the number of seconds until that outstanding alarm would have fired.
If no previous alarm() request was outstanding, then zero is returned.
 
@subheading DESCRIPTION:
 
@subheading NOTES: