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

   1 '\" te
   2 .\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH STR2SIG 3C "Oct 7, 1999"
   7 .SH NAME
   8 str2sig, sig2str \- translation between signal name and signal number
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <signal.h>
  13
  14 \fBint\fR \fBstr2sig\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fI*signum\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBint\fR \fBsig2str\fR(\fBint\fR \fIsignum\fR, \fBchar *\fR\fIstr\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBstr2sig()\fR function translates the signal name \fIstr\fR to a signal
  26 number, and stores that result in the location referenced by \fIsignum\fR. The
  27 name in \fIstr\fR can be either the symbol for that signal, without the "SIG"
  28 prefix, or a decimal number.  All the signal symbols defined in
  29 <\fBsys/signal.h\fR> are recognized.  This means that both "CLD" and "CHLD" are
  30 recognized and return the same signal number, as do both "POLL" and "IO".  For
  31 access to the signals in the range \fBSIGRTMIN\fR to \fBSIGRTMAX\fR, the first
  32 four signals match the strings "RTMIN", "RTMIN+1", "RTMIN+2", and "RTMIN+3" and
  33 the last four match the strings "RTMAX-3", "RTMAX-2", "RTMAX-1", and "RTMAX".
  34 .sp
  35 .LP
  36 The \fBsig2str()\fR function translates the signal number \fIsignum\fR to the
  37 symbol for that signal, without the "SIG" prefix, and stores that symbol at the
  38 location specified by \fIstr\fR. The storage referenced by \fIstr\fR should be
  39 large enough to hold the symbol and a terminating null byte. The symbol
  40 \fBSIG2STR_MAX\fR defined by \fB<signal.h>\fR gives the maximum size in bytes
  41 required.
  42 .SH RETURN VALUES
  43 .sp
  44 .LP
  45 The \fBstr2sig()\fR function returns \fB0\fR if it recognizes the signal name
  46 specified in \fIstr\fR; otherwise, it returns \fB\(mi1\fR\&.
  47 .sp
  48 .LP
  49 The \fBsig2str()\fR function returns \fB0\fR if the value \fIsignum\fR
  50 corresponds to a valid signal number; otherwise, it returns \fB\(mi1\fR\&.
  51 .SH EXAMPLES
  52 .LP
  53 \fBExample 1 \fRA sample program using the \fBstr2sig()\fR function.
  54 .sp
  55 .in +2
  56 .nf
  57 int i;
  58 char buf[SIG2STR_MAX];     /*storage for symbol */
  59
  60 str2sig("KILL",&i);        /*stores 9 in i */
  61 str2sig("9", &i);          /* stores 9 in i */
  62 sig2str(SIGKILL,buf);      /* stores "KILL" in buf */
  63 sig2str(9,buf);            /* stores "KILL" in buf */
  64 .fi
  65 .in -2
  66 .sp
  67
  68 .SH SEE ALSO
  69 .sp
  70 .LP
  71 \fBkill\fR(1), \fBstrsignal\fR(3C)