usr/src/man/man3c/signal.3c

   1 '\" te
   2 .\" Copyright (c) 2007 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\"  Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH SIGNAL 3C "Sep 6, 2007"
   8 .SH NAME
   9 signal, sigset, sighold, sigrelse, sigignore, sigpause \- simplified signal
  10 management for application processes
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <signal.h>
  15
  16 \fBvoid\fR \fB\fR(\fB*signal(int\fR \fIsig\fR, \fBvoid (*\fR\fIdisp\fR)(int)))(int);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid (*\fR\fBsigset\fR(\fBint\fR \fIsig\fR, \fBvoid (*\fR\fIdisp\fR)(int)))(int);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBsighold\fR(\fBint\fR \fIsig\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBsigrelse\fR(\fBint\fR \fIsig\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBsigignore\fR(\fBint\fR \fIsig\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBsigpause\fR(\fBint\fR \fIsig\fR);
  42 .fi
  43
  44 .SH DESCRIPTION
  45 .sp
  46 .LP
  47 These functions provide simplified signal management for application processes.
  48 See \fBsignal.h\fR(3HEAD) for an explanation of general signal concepts.
  49 .sp
  50 .LP
  51 The \fBsignal()\fR and \fBsigset()\fR functions modify signal dispositions. The
  52 \fIsig\fR argument specifies the signal, which may be any signal except
  53 \fBSIGKILL\fR and  \fBSIGSTOP.\fR The \fIdisp\fR argument specifies the
  54 signal's disposition, which may be \fBSIG_DFL,\fR \fBSIG_IGN,\fR or the address
  55 of a signal handler. If \fBsignal()\fR is used, \fIdisp\fR is the address of a
  56 signal handler, and \fIsig\fR is not  \fBSIGILL,\fR \fBSIGTRAP\fR, or
  57 \fBSIGPWR\fR, the system first sets the signal's disposition to  \fBSIG_DFL\fR
  58 before executing the signal handler. If \fBsigset()\fR is used and \fIdisp\fR
  59 is the address of a signal handler, the system adds \fIsig\fR to the calling
  60 process's signal  mask before executing the signal handler; when the signal
  61 handler returns, the system restores the calling process's signal mask to its
  62 state prior to the delivery of the signal. In addition, if \fBsigset()\fR is
  63 used and \fIdisp\fR is equal to  \fBSIG_HOLD\fR, \fIsig\fR is added to the
  64 calling process's signal mask and the signal's disposition remains unchanged.
  65 .sp
  66 .LP
  67 The \fBsighold()\fR function adds \fIsig\fR to the calling process's signal
  68 mask.
  69 .sp
  70 .LP
  71 The \fBsigrelse()\fR function removes \fIsig\fR from the calling process's
  72 signal mask.
  73 .sp
  74 .LP
  75 The \fBsigignore()\fR function sets the disposition of \fIsig\fR to
  76 \fBSIG_IGN.\fR
  77 .sp
  78 .LP
  79 The \fBsigpause()\fR function removes \fIsig\fR from the calling process's
  80 signal mask  and suspends the calling process until a signal is received.
  81 .SH RETURN VALUES
  82 .sp
  83 .LP
  84 Upon successful completion, \fBsignal()\fR returns the signal's previous
  85 disposition. Otherwise, it returns  \fBSIG_ERR\fR and sets \fBerrno\fR to
  86 indicate the error.
  87 .sp
  88 .LP
  89 Upon successful completion, \fBsigset()\fR returns \fBSIG_HOLD\fR if the signal
  90 had been blocked or the signal's previous disposition if it had not been
  91 blocked. Otherwise, it returns  \fBSIG_ERR\fR and sets \fBerrno\fR to indicate
  92 the error.
  93 .sp
  94 .LP
  95 Upon successful completion, \fBsighold()\fR, \fBsigrelse()\fR,
  96 \fBsigignore()\fR, and \fBsigpause()\fR, return  \fB0\fR. Otherwise, they
  97 return  \fB\(mi1\fR and set  \fBerrno\fR to indicate the error.
  98 .SH ERRORS
  99 .sp
 100 .LP
 101 These functions fail if:
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBEINTR\fR\fR
 106 .ad
 107 .RS 10n
 108 A signal was caught during the execution \fBsigpause()\fR.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBEINVAL\fR\fR
 115 .ad
 116 .RS 10n
 117 The value of the \fIsig\fR argument is not a valid signal or is equal to
 118 \fBSIGKILL\fR or  \fBSIGSTOP\fR.
 119 .RE
 120
 121 .SH USAGE
 122 .sp
 123 .LP
 124 The \fBsighold()\fR function used in conjunction with \fBsigrelse()\fR or
 125 \fBsigpause()\fR may be used to establish critical regions of code that require
 126 the delivery of a signal to be temporarily deferred.
 127 .sp
 128 .LP
 129 If \fBsignal()\fR or \fBsigset()\fR is used to set  \fBSIGCHLD\fR's disposition
 130 to a signal handler, \fBSIGCHLD\fR will not be sent when the calling process's
 131 children are stopped or continued.
 132 .sp
 133 .LP
 134 If any of the above functions are used to set \fBSIGCHLD\fR's disposition to
 135 \fBSIG_IGN,\fR the calling process's child processes will not create zombie
 136 processes when they terminate (see \fBexit\fR(2)). If the calling process
 137 subsequently waits for its children, it blocks until all of its children
 138 terminate; it then returns \fB\(mi1\fR with \fBerrno\fR set to \fBECHILD\fR
 139 (see \fBwait\fR(3C) and \fBwaitid\fR(2)).
 140 .sp
 141 .LP
 142 The system guarantees that if more than one instance of the same signal is
 143 generated to a process, at least one signal will be received.  It does not
 144 guarantee the reception of every generated signal.
 145 .SH ATTRIBUTES
 146 .sp
 147 .LP
 148 See \fBattributes\fR(5) for descriptions of the following attributes:
 149 .sp
 150
 151 .sp
 152 .TS
 153 box;
 154 c | c
 155 l | l .
 156 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 157 _
 158 Interface Stability     Standard
 159 _
 160 MT-Level        MT-Safe
 161 .TE
 162
 163 .SH SEE ALSO
 164 .sp
 165 .LP
 166 \fBexit\fR(2), \fBkill\fR(2), \fBpause\fR(2), \fBsigaction\fR(2),
 167 \fBsigsend\fR(2), \fBwaitid\fR(2), \fBsignal.h\fR(3HEAD), \fBwait\fR(3C),
 168 \fBattributes\fR(5), \fBstandards\fR(5)