gen/FreeBSD/psignal.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)psignal.3   8.2 (Berkeley) 2/27/95
  29 .\" $FreeBSD: src/lib/libc/gen/psignal.3,v 1.17 2007/01/09 00:27:54 imp Exp $
  30 .\"
  31 .Dd February 27, 1995
  32 .Dt PSIGNAL 3
  33 .Os
  34 .Sh NAME
  35 .Nm psignal ,
  36 .Nm strsignal ,
  37 .Nm sys_siglist ,
  38 .Nm sys_signame
  39 .Nd system signal messages
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In signal.h
  44 .Ft void
  45 .Fn psignal "unsigned sig" "const char *s"
  46 .Vt extern const char * const sys_siglist[] ;
  47 .Vt extern const char * const sys_signame[] ;
  48 .In string.h
  49 .Ft "char *"
  50 .Fn strsignal "int sig"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn psignal
  54 and
  55 .Fn strsignal
  56 functions locate the descriptive message
  57 string for a signal number.
  58 .Pp
  59 The
  60 .Fn strsignal
  61 function accepts a signal number argument
  62 .Fa sig
  63 and returns a pointer to the corresponding message string.
  64 .Pp
  65 The
  66 .Fn psignal
  67 function accepts a signal number argument
  68 .Fa sig
  69 and writes it to the standard error.
  70 If the argument
  71 .Fa s
  72 is
  73 .Pf non- Dv NULL
  74 and does not point to the null character,
  75 .Fa s
  76 is written to the standard error file descriptor
  77 prior to the message string,
  78 immediately followed by a colon and a space.
  79 If the signal number is not recognized
  80 .Pq Xr sigaction 2 ,
  81 the string
  82 .Dq "Unknown signal
  83 is produced.
  84 .Pp
  85 The message strings can be accessed directly
  86 through the external array
  87 .Va sys_siglist ,
  88 indexed by recognized signal numbers.
  89 The external array
  90 .Va sys_signame
  91 is used similarly and
  92 contains short, lower-case abbreviations for signals
  93 which are useful for recognizing signal names
  94 in user input.
  95 The defined variable
  96 .Dv NSIG
  97 contains a count of the strings in
  98 .Va sys_siglist
  99 and
 100 .Va sys_signame .
 101 .Sh RETURN VALUES
 102 .Fn strsignal
 103 a pointer to the desired message or a NULL value indicating an error.  This
 104 string is not to be freed by the caller.  Beginning with Mac OSX 10.7, this
 105 string is unique to each thread.
 106 .Sh ERRORS
 107 .Fn strsignal
 108 will fail and no additional memory will be allocated if
 109 one of the following are true:
 110 .Bl -tag -width Er
 111 .It Bq Er ENOMEM
 112 There was insufficient memory to allocate storage space for the return value in the running thread.
 113 .El
 114 .Sh SEE ALSO
 115 .Xr sigaction 2 ,
 116 .Xr perror 3 ,
 117 .Xr strerror 3
 118 .Sh HISTORY
 119 The
 120 .Fn psignal
 121 function appeared in
 122 .Bx 4.2 .