File: demo3.c

package info (click to toggle)
yuma123 2.11-1
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 20,900 kB
  • sloc: ansic: 179,975; cpp: 10,968; python: 5,839; sh: 2,287; makefile: 1,021; xml: 621; exp: 592; perl: 70
file content (738 lines) | stat: -rw-r--r-- 26,309 bytes parent folder | download | duplicates (3)
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
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
/*
 * Copyright (c) 2002, 2003, 2004 by Martin C. Shepherd
 * 
 * All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 * 
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
#include <string.h>
#include <errno.h>
#include <locale.h>
#include <setjmp.h>

#ifdef HAVE_SELECT
#ifdef HAVE_SYS_SELECT_H
#include <sys/select.h>
#endif
#endif

#include <unistd.h>
#include <sys/stat.h>
#include <sys/time.h>    
#include <sys/types.h>
#include <signal.h>

#include "libtecla.h"

/*
 * The SignalActions object provides a way to temporarily install
 * a signal handler to a given set of signals, and later restore all
 * of the signal handlers that this displaced.
 */
typedef struct {
  int nsignal;               /* The number of signals on the host OS */
  sigset_t mask;             /* The set of signals who's signal handlers */
                             /*  are stored in the following actions[] */
                             /*  array. */
  struct sigaction *actions; /* An array of nsignal actions */
} SignalActions;

static SignalActions *new_SignalActions(void);
static SignalActions *del_SignalActions(SignalActions *si);
static int displace_signal_handlers(SignalActions *si, sigset_t *mask,
				    void (*handler)(int));
static int reinstate_signal_handlers(SignalActions *si);

/* Return resources, restore the terminal to a usable state and exit */

static void cleanup_and_exit(GetLine *gl, SignalActions *si, int status);

/* The function which displays the introductory text of the demo */

static void show_demo_introduction(GetLine *gl);

/* A signal-aware version of select() */

static int demo_sigselect(int n, fd_set *readfds, fd_set *writefds,
			  fd_set *exceptfds, struct timeval *timeout,
			  sigset_t *mask, SignalActions *si);

/*
 * The following variables are accessed from signal handlers.  Note
 * that these variables don't need to be either volatile or
 * sig_atomic_t because:
 *
 * 1. Outside of signal handlers we only access them when signal
 *    delivery is blocked, so we know that no signal handlers can
 *    be accessing them at that time.
 *
 * 2. When the signal handlers that set these variables are installed,
 *    the sa_mask member of the sigaction structure is used to ensure
 *    that only one instance of these signal handlers can be running
 *    at a time, so we also know that there can't be simultaneous
 *    accesses to them by multiple signal handlers.
 */
static GetLine *demo_gl;                /* The line editor object */
static sigjmp_buf demo_setjmp_buffer;   /* The sigsetjmp() buffer */
static int demo_setjmp_signo = -1;      /* The signal that was caught */

/* Signal handlers */

static void demo_signal_handler(int signo);
static void demo_setjmp_handler(int signo);

/*
 * Set the amount of time that gl_get_line() should wait for I/O before
 * returning to let the external event loop continue.
 */
#define DEMO_IO_TIMEOUT 100000000 /* ns => 100ms */

/* The timeout handler */

static GL_TIMEOUT_FN(demo_timeout_fn);

/*.......................................................................
 * This program demonstrates the use of gl_get_line() from an external
 * event loop. It takes no arguments.
 */
int main(int argc, char *argv[])
{
  int major,minor,micro;      /* The version number of the library */
  GetLine *gl=NULL;           /* The resource object of gl_get_line() */
  SignalActions *si=NULL;     /* Temporary storage of displaced signal */
                              /*  handlers. */
  sigset_t all_signal_mask;   /* The set of signals known by gl_get_line() */
/*
 * This program requires select().
 */
#if !defined(HAVE_SELECT)
  fprintf(stderr, "The select() system call isn't available - aborting.\n");
  exit(1);
#else
/*
 * Create the line editor, specifying a maximum line length of 500 bytes,
 * and 10000 bytes to allocate to storage of historical input lines.
 */
  gl = demo_gl = new_GetLine(500, 5000);
  if(!gl)
    cleanup_and_exit(gl, si, 1);

/*
 * Allocate an object in which to temporarily record displaced
 * signal handlers.
 */
  si = new_SignalActions();
  if(!si)
    cleanup_and_exit(gl, si, 1);
/*
 * If the user has the LC_CTYPE or LC_ALL environment variables set,
 * enable display of characters corresponding to the specified locale.
 */
  (void) setlocale(LC_CTYPE, "");
/*
 * Lookup and display the version number of the library.
 */
  libtecla_version(&major, &minor, &micro);
  printf(
    "\n Welcome to the server-mode demo program of libtecla version %d.%d.%d\n",
      major, minor, micro);
/*
 * Display some introductory text, left-justifying it within the current
 * width of the terminal and enclosing it in a box of asterixes.
 */
  show_demo_introduction(gl);
/*
 * Load history.
 */
#ifndef WITHOUT_FILE_SYSTEM
  (void) gl_load_history(gl, "~/.demo_history", "#");
#endif
/*
 * In this demo, rather than having gl_get_line() return immediately
 * when it would otherwise have to wait for I/O, we register a timeout
 * callback which causes gl_get_line() to give up waiting after a short
 * interval.
 */
  gl_inactivity_timeout(gl, demo_timeout_fn, NULL, 0, DEMO_IO_TIMEOUT);
/*
 * Install our signal handlers for process termination, suspension and
 * terminal resize signals. Ignore process continuation signals.
 */
  gl_tty_signals(demo_signal_handler, demo_signal_handler, SIG_DFL,
		 demo_signal_handler);
/*
 * Get a list of all of the signals that gl_get_line() currently catches.
 */
  gl_list_signals(gl, &all_signal_mask);
/*
 * Switch gl_get_line() to non-blocking server mode.
 */
  if(gl_io_mode(gl, GL_SERVER_MODE))
    cleanup_and_exit(gl, si, 1);
/*
 * Instruct gl_get_line() to unblock any signals that it catches
 * while waiting for input. Note that in non-blocking server mode,
 * this is only necessary when using gl_inactivity_timeout() to make
 * gl_get_line() block for a non-zero amount of time.
 */
  gl_catch_blocked(gl);
/*
 * Enter the event loop.
 */
  while(1) {
    int nready;        /* The number of file-descriptors that are */
                       /*  ready for I/O */
    fd_set rfds;       /* The set of file descriptors to watch for */
                       /*  readability */
    fd_set wfds;       /* The set of file descriptors to watch for */
                       /*  writability */
/*
 * Construct the sets of file descriptors to be watched by select(),
 * starting from empty sets.
 */
    FD_ZERO(&rfds);
    FD_ZERO(&wfds);
/*
 * To ensure that no signals are received whos handlers might change
 * the requirements for the contents of the above signal sets, block
 * all of the signals that we are handling.
 */
    sigprocmask(SIG_BLOCK, &all_signal_mask, NULL);
/*
 * Depending on which direction of I/O gl_get_line()s is currently
 * waiting for, add the terminal file descriptor to either the set
 * of file descriptors to watch for readability, or those to watch
 * for writability. Note that at the start of a new line, such as
 * after an error, or the return of a completed line, we need to
 * wait for writability, so that a prompt can be written.
 */
    switch(gl_pending_io(gl)) {
    case GLP_READ:
      FD_SET(STDIN_FILENO, &rfds);
      break;
    default:
      FD_SET(STDIN_FILENO, &wfds);
      break;
    };
/*
 * Wait for I/O to become possible on the selected file descriptors.
 * The following is a signal-aware wrapper around the select() system
 * call. This wrapper guarantees that if any of the signals marked in
 * all_signal_mask arrive after the statement above where we blocked
 * these signals, it will detect this and abort with nready=-1 and
 * errno=EINTR. If instead, we just unblocked the above signals just
 * before calling a normal call to select(), there would be a small
 * window of time between those two statements in which a signal could
 * arrive without aborting select(). This would be a problem, since
 * the functions called by our signal handler may change the type
 * of I/O that gl_get_line() wants us to wait for in select().
 */
    nready = demo_sigselect(STDIN_FILENO + 1, &rfds, &wfds, NULL, NULL,
			    &all_signal_mask, si);
/*
 * We can now unblock our signals again.
 */
    sigprocmask(SIG_UNBLOCK, &all_signal_mask, NULL);
/*
 * Did an I/O error occur?
 */
    if(nready < 0 && errno != EINTR)
      cleanup_and_exit(gl, si, 1);
/*
 * If the terminal file descriptor is now ready for I/O, call
 * gl_get_line() to continue editing the current input line.
 */
    if(FD_ISSET(STDIN_FILENO, &rfds) || FD_ISSET(STDIN_FILENO, &wfds)) {
/*
 * Start or continue editing an input line.
 */
      char *line = gl_get_line(gl, "$ ", NULL, 0);
/*
 * Did the user finish entering a new line?
 */
      if(line) {
/*
 * Before writing messages to the terminal, start a new line and
 * switch back to normal terminal I/O.
 */
	gl_normal_io(gl);
/*
 * Display what was entered.
 */
	if(printf("You entered: %s", line) < 0 || fflush(stdout))
	  break;
/*
 * Implement a few simple commands.
 */
	if(strcmp(line, "exit\n")==0)
	  cleanup_and_exit(gl, si, 0);
	else if(strcmp(line, "history\n")==0)
	  gl_show_history(gl, stdout, "%N  %T   %H\n", 0, -1);
	else if(strcmp(line, "size\n")==0) {
	  GlTerminalSize size = gl_terminal_size(gl, 80, 24);
	  printf("Terminal size = %d columns x %d lines.\n", size.ncolumn,
		 size.nline);
	} else if(strcmp(line, "clear\n")==0) {
	  if(gl_erase_terminal(gl))
	    return 1;
	};
/*
 * To resume command-line editing, return the terminal to raw,
 * non-blocking I/O mode.
 */
	gl_raw_io(gl);
/*
 * If gl_get_line() returned NULL because of an error or end-of-file,
 * abort the program.
 */
      } else if(gl_return_status(gl) == GLR_ERROR ||
		gl_return_status(gl) == GLR_EOF) {
	cleanup_and_exit(gl, si, 1);
      };
    };
  };
#endif
  return 0;
}

/*.......................................................................
 * This function is called to return resources to the system and restore
 * the terminal to its original state before exiting the process.
 *
 * Input:
 *  gl        GetLine *   The line editor.
 *  si  SignalActions *   The repository for displaced signal handlers.
 *  status        int     The exit code of the process.
 */
static void cleanup_and_exit(GetLine *gl, SignalActions *si, int status)
{
/*
 * Restore the terminal to its original state before exiting the program.
 */
  gl_normal_io(gl);
/*
 * Save historical command lines.
 */
#ifndef WITHOUT_FILE_SYSTEM
  (void) gl_save_history(gl, "~/.demo_history", "#", -1);
#endif
/*
 * Clean up.
 */
  gl = del_GetLine(gl);
  si = del_SignalActions(si);
/*
 * Exit the process.
 */
  exit(status);
}

/*.......................................................................
 * This is a signal-aware wrapper around the select() system call. It
 * is designed to facilitate reliable signal handling of a given set
 * of signals, without the race conditions that would usually surround
 * the use of select(). See the "RELIABLE SIGNAL HANDLING" section of
 * the gl_get_line(3) man page for further details.
 *
 * Provided that the calling function has blocked the specified set of
 * signals before calling this function, this function guarantees that
 * select() will be aborted by any signal that arrives between the
 * time that the caller blocked the specified signals and this
 * function returns. On return these signals will again be blocked to
 * prevent any signals that arrive after select() returns, from being
 * missed by the caller.
 *
 * Note that this function is written not to be specific to this
 * program, and is thus suitable for use in other programs, whether or
 * not they use gl_get_line().
 *
 * Also note that this function depends on the NSIG preprocessor
 * constant being >= the maximum number of signals available on the
 * host operating system. Under BSD and SysV, this macro is set
 * appropriately in signal.h. On other systems, a reasonably large
 * guess should be substituted. Although nothing terrible will happen
 * if a value that is too small is chosen, signal numbers that exceed
 * the specified value of NSIG will be ignored by this function. A
 * more robust method than depending on nsig would be to use the
 * POSIX sigismember() function to count valid signals, and use this
 * to allocate the array of sigaction structures used to preserve
 * 
 *
 * Input:
 *  n                   int    The number of file descriptors to pay
 *                             attention to at the start of each of the
 *                             following sets of file descriptors.
 *  readfds          fd_set *  The set of file descriptors to check for
 *                             readability, or NULL if not pertinent.
 *  wwritefds        fd_set *  The set of file descriptors to check for
 *                             writability, or NULL if not pertinent.
 *  exceptfds        fd_set *  The set of file descriptors to check for
 *                             the arrival of urgent data, or NULL if
 *                             not pertinent.
 *  timeout  struct timeval *  The maximum time that select() should
 *                             wait, or NULL to wait forever.
 *  mask           sigset_t *  The set of signals to catch.
 *  si       SignalHandlers *  An object in which to preserve temporary
 *                             copies signal handlers.
 * Output:
 *  return              int    > 0  The number of entries in all of the
 *                                  sets of descriptors that are ready
 *                                  for I/O.
 *                               0  Select() timed out.
 *                              -1  Error (see errno).
 */
static int demo_sigselect(int n, fd_set *readfds, fd_set *writefds,
			  fd_set *exceptfds, struct timeval *timeout,
			  sigset_t *mask, SignalActions *si)
{
/*
 * The reason that the the following variables are marked as volatile
 * is to prevent the compiler from placing their values in registers
 * that might not be saved and restored by sigsetjmp().
 */
  volatile sigset_t old_mask;  /* The displaced process signal mask */
  volatile int status;         /* The return value of select() */
/*
 * Make sure that all of the specified signals are blocked. This is
 * redundant if the caller has already blocked signals.
 */
  if(sigprocmask(SIG_BLOCK, mask, (sigset_t *) &old_mask) < 0)
    return -1;
/*
 * Record the fact that no signal has been caught yet.
 */
  demo_setjmp_signo = -1;
/*
 * Now set up the point where our temporary signal handlers will return
 * control if a signal is received.
 */
  if(sigsetjmp(demo_setjmp_buffer, 1) == 0) {
/*
 * Now install the temporary signal handlers that cause the above
 * sigsetjmp() to return non-zero when a signal is detected.
 */
    if(displace_signal_handlers(si, mask, demo_setjmp_handler)) {
      reinstate_signal_handlers(si);
      return 1;
    };
/*
 * Now that we are ready to catch the signals, unblock them.
 */
    sigprocmask(SIG_UNBLOCK, mask, NULL);
/*
 * At last, call select().
 */
    status = select(n, readfds, writefds, exceptfds, timeout);
/*
 * Block the specified signals again.
 */
    sigprocmask(SIG_BLOCK, mask, NULL);
/*
 * Record the fact that no signal was caught.
 */
    demo_setjmp_signo = -1;
  };
/*
 * We can get to this point in one of two ways. Either no signals were
 * caught, and the above block ran to completion (with demo_setjmp_signo=-1),
 * or a signal was caught that caused the above block to be aborted,
 * in which case demo_setjmp_signo will now equal the number of the signal that
 * was caught, and sigsetjmp() will have restored the process signal
 * mask to how it was before it was called (ie. all of the specified
 * signals blocked).
 *
 * First restore the signal handlers to how they were on entry to
 * this function.
 */
  reinstate_signal_handlers(si);
/*
 * Was a signal caught?
 */
  if(demo_setjmp_signo > 0) {
    sigset_t new_mask;
/*
 * Send the signal again, then unblock its delivery, so that the application's
 * signal handler gets invoked.
 */
    raise(demo_setjmp_signo);
    sigemptyset(&new_mask);
    sigaddset(&new_mask, demo_setjmp_signo);
    sigprocmask(SIG_UNBLOCK, &new_mask, NULL);
/*
 * Set the return status to show that a signal was caught.
 */
    errno = EINTR;
    status = -1;
  };
/*
 * Now restore the process signal mask to how it was on entry to this
 * function.
 */
  sigprocmask(SIG_SETMASK, (sigset_t *) &old_mask, NULL);
  return status;
}

/*.......................................................................
 * This is the main signal handler of this demonstration program. If a
 * SIGINT is received by the process, it arranges that the next call
 * to gl_get_line() will abort entry of the current line and start
 * entering a new one. Otherwise it calls the library function which
 * handles terminal resize signals and process suspension and process
 * termination signals. Both of the functions called by this signal
 * handler are designed to be async-signal safe, provided that the
 * rules laid out in the gl_io_mode(3) man page are followed.
 */
static void demo_signal_handler(int signo)
{
  if(signo==SIGINT)
    gl_abandon_line(demo_gl);
  else
    gl_handle_signal(signo, demo_gl, 1);
}

/*.......................................................................
 * The following signal handler is installed while select() is being
 * called from within a block of code protected by sigsetjmp(). It
 * simply records the signal that was caught in setjmp_signo, then
 * causes the sigsetjmp() to return non-zero.
 */
static void demo_setjmp_handler(int signo)
{
  demo_setjmp_signo = signo;
  siglongjmp(demo_setjmp_buffer, 1);
}

/*.......................................................................
 * This optional inactivity timeout function is used in this
 * demonstration to cause gl_get_line() to wait for a small amount of
 * time for I/O, before returning and allowing the event loop to
 * continue. This isn't needed if you want gl_get_line() to return
 * immediately, rather than blocking.
 */
static GL_TIMEOUT_FN(demo_timeout_fn)
{
  return GLTO_CONTINUE;
}

/*.......................................................................
 * Display introductory text to the user, formatted according to the
 * current terminal width and enclosed in a box of asterixes.
 *
 * Input:
 *  gl      GetLine *   The resource object of gl_get_line().
 */
static void show_demo_introduction(GetLine *gl)
{
  int start;     /* The column in which gl_display_text() left the cursor */
  int i;
/*
 * Break the indtroductory text into an array of strings, so as to
 * avoid overflowing any compiler string limits.
 */
  const char *doc[] = {
    "To the user this program appears to act identically to the main ",
    "demo program. However whereas the code underlying the main demo ",
    "program uses gl_get_line() in its default configuration, where each ",
    "call blocks the caller until the user has entered a complete input ",
    "line, demo3 uses gl_get_line() in its non-blocking server mode, ",
    "where it must be called repeatedly from an external ",
    "event loop to incrementally accept entry of the input ",
    "line, as and when terminal I/O becomes possible. The well commented ",
    "source code of demo3, which can be found in demo3.c, thus provides ",
    "a working example of how to use gl_get_line() in a manner that ",
    "doesn't block the caller. Documentation of this mode can be found ",
    "in the gl_io_mode(3) man page.\n"
  };
/*
 * Form the top line of the documentation box by filling the area of
 * the line between a " *" prefix and a "* " suffix with asterixes.
 */
  printf("\n");
  gl_display_text(gl, 0, " *", "* ", '*', 80, 0, "\n");
/*
 * Justify the documentation text within margins of asterixes.
 */
  for(start=0,i=0; i<sizeof(doc)/sizeof(doc[0]) && start >= 0; i++)
    start = gl_display_text(gl, 0, " * ", " * ", ' ', 80, start,doc[i]);
/*
 * Draw the bottom line of the documentation box.
 */
  gl_display_text(gl, 0, " *", "* ", '*', 80, 0, "\n");
  printf("\n");
}


/*.......................................................................
 * This is a constructor function for an object who's role is to allow
 * a signal handler to be assigned to potentially all available signals,
 * while preserving a copy of the original signal handlers, for later
 * restration.
 *
 * Output:
 *  return  SignalActions *  The new object, or NULL on error.
 */
static SignalActions *new_SignalActions(void)
{
  SignalActions *si;  /* The object to be returned */
/*
 * Allocate the container.
 */
  si = malloc(sizeof(SignalActions));
  if(!si) {
    fprintf(stderr, "new_SignalActions: Insufficient memory.\n");
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_SignalActions().
 */
  si->nsignal = 0;
  sigemptyset(&si->mask);
  si->actions = NULL;
/*
 * Count the number of signals that are available of the host
 * platform. Note that si->mask has no members set, and that
 * sigismember() is defined to return -1 if the signal number
 * isn't valid.
 */
  for(si->nsignal=1; sigismember(&si->mask, si->nsignal) == 0; si->nsignal++)
    ;
/*
 * Allocate the array of sigaction structures to use to keep a record
 * of displaced signal handlers.
 */
  si->actions = (struct sigaction *) malloc(sizeof(*si->actions) * si->nsignal);
  if(!si->actions) {
    fprintf(stderr, "Insufficient memory for %d sigaction structures.\n",
	    si->nsignal);
    return del_SignalActions(si);
  };
  return si;
}

/*.......................................................................
 * Delete a SignalActions object.
 *
 * Input:
 *  si     SignalActions *  The object to be deleted.
 * Output:
 *  return SignalActions *  The deleted object (always NULL).
 */
static SignalActions *del_SignalActions(SignalActions *si)
{
  if(si) {
    if(si->actions)
      free(si->actions);
    free(si);
  };
  return NULL;
}

/*.......................................................................
 * Replace the signal handlers of all of the signals in 'mask' with
 * the signal handler 'handler'.
 *
 * Input:
 *  si       SignalActions *     The object in which to record the displaced
 *                               signal handlers.
 *  mask          sigset_t *     The set of signals who's signal handlers
 *                               should be displaced.
 *  handler void (*handler)(int) The new signal handler to assign to each
 *                               of the signals marked in 'mask'.
 * Output:
 *  return             int       0 - OK.
 *                               1 - Error.
 */
static int displace_signal_handlers(SignalActions *si, sigset_t *mask,
				    void (*handler)(int))
{
  int signo;                /* A signal number */
  struct sigaction action;  /* The new signal handler */
/*
 * Mark the fact that so far we haven't displaced any signal handlers.
 */
  sigemptyset(&si->mask);
/*
 * Set up the description of the new signal handler. Note that
 * we make sa_mask=mask. This ensures that only one instance of the
 * signal handler will ever be running at one time.
 */
  action.sa_handler = handler;
  memcpy(&action.sa_mask, mask, sizeof(*mask));
  action.sa_flags = 0;
/*
 * Check each of the available signals to see if it is specified in 'mask'.
 * If so, install the new signal handler, record the displaced one in
 * the corresponding element of si->actions[], and make a record in
 * si->mask that this signal handler has been displaced.
 */
  for(signo=1; signo < si->nsignal; signo++) {
    if(sigismember(mask, signo)) {
      if(sigaction(signo, &action, &si->actions[signo]) < 0) {
	fprintf(stderr, "sigaction error (%s)\n", strerror(errno));
	return 1;
      };
      sigaddset(&si->mask, signo);
    };
  };
  return 0;
}

/*.......................................................................
 * Reinstate any signal handlers displaced by displace_signal_handlers().
 *
 * Input:
 *  sig   SignalActions *  The object containing the displaced signal
 *                         handlers.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
static int reinstate_signal_handlers(SignalActions *si)
{
  int signo;                /* A signal number */
/*
 * Check each of the available signals to see if it is specified in
 * si->mask. If so, reinstate the displaced recorded in the
 * corresponding element of si->actions[], and make a record in
 * si->mask that this signal handler has been reinstated.
 */
  for(signo=1; signo < si->nsignal; signo++) {
    if(sigismember(&si->mask, signo)) {
      if(sigaction(signo, &si->actions[signo], NULL) < 0) {
	fprintf(stderr, "sigaction error (%s)\n", strerror(errno));
	return 1;
      };
      sigdelset(&si->mask, signo);
    };
  };
  return 0;
}