emulated/bsd_signal.3

   1 .\" Copyright (c) 2002 Apple Computer, Inc.  All rights reserved.
   2 .\"
   3 .\" @APPLE_LICENSE_HEADER_START@
   4 .\"
   5 .\" The contents of this file constitute Original Code as defined in and
   6 .\" are subject to the Apple Public Source License Version 1.1 (the
   7 .\" "License").  You may not use this file except in compliance with the
   8 .\" License.  Please obtain a copy of the License at
   9 .\" http://www.apple.com/publicsource and read it before using this file.
  10 .\"
  11 .\" This Original Code and all software distributed under the License are
  12 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  13 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  14 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  16 .\" License for the specific language governing rights and limitations
  17 .\" under the License.
  18 .\"
  19 .\" @APPLE_LICENSE_HEADER_END@
  20 .\"
  21 .Dd December 20, 2003
  22 .Dt BSD_SIGNAL 3
  23 .Os
  24 .Sh NAME
  25 .Nm bsd_signal
  26 .Nd simplified signal facilities
  27 .Sh SYNOPSIS
  28 .In signal.h
  29 .\" The following is Quite Ugly, but syntactically correct.  Don't try to
  30 .\" fix it.
  31 .Ft void \*(lp*
  32 .Fn bsd_signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
  33 .Pp
  34 or in an equivalent but easier to read typedef'd version:
  35 .Ft typedef "void \*(lp*sig_t\*(rp \*(lpint\*(rp" ;
  36 .Ft sig_t
  37 .Fn bsd_signal "int sig" "sig_t func"
  38 .Sh DESCRIPTION
  39 The
  40 .Fn bsd_signal
  41 function provides a partially compatible interface for programs written
  42 to historical system interfaces (see USAGE below).
  43 .Pp
  44 The function call
  45 .Fn bsd_signal sig func
  46 has the effect as if implemented as:
  47 .Bd -literal -offset indent
  48 void (*bsd_signal(int sig, void (*func)(int)))(int)
  49 {
  50     struct sigaction act, oact;
  51
  52     act.sa_handler = func;
  53     act.sa_flags = SA_RESTART;
  54     sigemptyset(&act.sa_mask);
  55     sigaddset(&act.sa_mask, sig);
  56     if (sigaction(sig, &act, &oact) == -1)
  57         return(SIG_ERR);
  58     return(oact.sa_handler);
  59 }
  60 .Ed
  61 .Pp
  62 The handler function should be declared:
  63 .Pp
  64 .D1 Fn "void func" "int sig"
  65 .Pp
  66 where
  67 .Fa sig
  68 is the signal number.
  69 The behavior is undefined if
  70 .Fn func
  71 is a function that takes more than one argument, or an argument of a
  72 different type.
  73 .Sh RETURN VALUES
  74 Upon successful completion,
  75 .Fn bsd_signal
  76 returns the previous action for
  77 .Fa sig .
  78 Otherwise,
  79 .Er SIG_ERR
  80 is returned and
  81 .Va errno
  82 is set to indicate the error.
  83 .Sh ERRORS
  84 Refer to
  85 .Xr sigaction 2 .
  86 .Sh USAGE
  87 This function is a direct replacement for the
  88 .Bx
  89 .Xr signal(3)
  90 function for simple applications that are installing a single-argument signal
  91 handler function.
  92 If a
  93 .Bx
  94 signal handler function is being installed that expects more than one
  95 argument, the application has to be modified to use
  96 .Xr sigaction 2 .
  97 The
  98 .Fn bsd_signal
  99 function differs from
 100 .Xr signal 3
 101 in that the
 102 .Dv SA_RESTART
 103 flag is set and the
 104 .Dv SA_RESETHAND
 105 will be clear when
 106 .Fn bsd_signal
 107 is used.
 108 The state of these flags is not specified for
 109 .Xr signal 3 .
 110 .Sh SEE ALSO
 111 .Xr sigaction 2 ,
 112 .Xr sigaddset 3 ,
 113 .Xr sigemptyset 3 ,
 114 .Xr signal 3
 115 .Sh STANDARDS
 116 The
 117 .Fn bsd_signal
 118 function conforms to
 119 .St -p1003.1-2001 .