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 strsignal_r ,
  38 .Nm sys_siglist ,
  39 .Nm sys_signame
  40 .Nd system signal messages
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In signal.h
  45 .Ft void
  46 .Fn psignal "unsigned sig" "const char *s"
  47 .Vt extern const char * const sys_siglist[] ;
  48 .Vt extern const char * const sys_signame[] ;
  49 .In string.h
  50 .Ft "char *"
  51 .Fn strsignal "int sig"
  52 .Ft "int"
  53 .Fo strsignal_r
  54 .Fa "int sig"
  55 .Fa "char *strsignalbuf"
  56 .Fa "size_t buflen"
  57 .Fc
  58 .Sh DESCRIPTION
  59 The
  60 .Fn psignal ,
  61 .Fn strsignal ,
  62 and
  63 .Fn strsignal_r
  64 functions locate the descriptive message
  65 string for a signal number.
  66 .Pp
  67 The
  68 .Fn strsignal
  69 function accepts a signal number argument
  70 .Fa sig
  71 and returns a pointer to the corresponding message string.
  72 .Pp
  73 The
  74 .Fn strsignal_r
  75 function renders the same result into
  76 .Fa strsignalbuf
  77 for a maximum of
  78 .Fa buflen
  79 characters and returns 0 upon success.
  80 .Pp
  81 The
  82 .Fn psignal
  83 function accepts a signal number argument
  84 .Fa sig
  85 and writes it to the standard error.
  86 If the argument
  87 .Fa s
  88 is
  89 .Pf non- Dv NULL
  90 and does not point to the null character,
  91 .Fa s
  92 is written to the standard error file descriptor
  93 prior to the message string,
  94 immediately followed by a colon and a space.
  95 If the signal number is not recognized
  96 .Pq Xr sigaction 2 ,
  97 the string
  98 .Dq "Unknown signal
  99 is produced.
 100 .Pp
 101 The message strings can be accessed directly
 102 through the external array
 103 .Va sys_siglist ,
 104 indexed by recognized signal numbers.
 105 The external array
 106 .Va sys_signame
 107 is used similarly and
 108 contains short, lower-case abbreviations for signals
 109 which are useful for recognizing signal names
 110 in user input.
 111 The defined variable
 112 .Dv NSIG
 113 contains a count of the strings in
 114 .Va sys_siglist
 115 and
 116 .Va sys_signame .
 117 .Sh RETURN VALUES
 118 .Fn strsignal
 119 a pointer to the desired message or a NULL value indicating an error.  This
 120 string is not to be freed by the caller.  Beginning with Mac OSX 10.7, this
 121 string is unique to each thread.
 122 .Pp
 123 .Fn strsignal_r
 124 0 if the message string is successfully copied in its entirety to
 125 .Fa strsignalbuf .
 126 .Pp
 127 .Sh ERRORS
 128 .Fn strsignal
 129 will fail and no additional memory will be allocated if
 130 one of the following are true:
 131 .Bl -tag -width Er
 132 .It Bq Er ENOMEM
 133 There was insufficient memory to allocate storage space for the return value in the running thread.
 134 .El
 135 .Pp
 136 .Fn strsignal_r
 137 will return an error (but not fail) if one or more condition is met:
 138 .Bl -tag -width Er
 139 .It Bq Er ERANGE
 140 .Fa buflen
 141 is not long enough to fit the length of the message.
 142 .Fa strsignalbuf
 143 will contain the message string that has been truncated and
 144 NUL terminated to fit the length specified by
 145 .Fa buflen .
 146 .El
 147 .Bl -tag -width Er
 148 .It Bq Er EINVAL
 149 .Fa sig
 150 <= 0 or >= NSIG.
 151 .El
 152 .Sh SEE ALSO
 153 .Xr sigaction 2 ,
 154 .Xr perror 3 ,
 155 .Xr strerror 3
 156 .Sh HISTORY
 157 The
 158 .Fn psignal
 159 function appeared in
 160 .Bx 4.2 .