Libc-1439.100.3.tar.gz

[apple/libc.git] / gen / FreeBSD / psignal.3

diff --git a/gen/FreeBSD/psignal.3 b/gen/FreeBSD/psignal.3
index 02013a453eea21fe6b24a6fa00791983eb9e673c..ca8d52df079d9c4b991501cc167134c4d22b4398 100644 (file)
--- a/gen/FreeBSD/psignal.3
+++ b/gen/FreeBSD/psignal.3
@@ -9,10 +9,6 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.
 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
@@ -30,7 +26,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)psignal.3  8.2 (Berkeley) 2/27/95
-.\" $FreeBSD: src/lib/libc/gen/psignal.3,v 1.16 2002/12/30 21:18:02 schweikh Exp $
+.\" $FreeBSD: src/lib/libc/gen/psignal.3,v 1.17 2007/01/09 00:27:54 imp Exp $
 .\"
 .Dd February 27, 1995
 .Dt PSIGNAL 3
@@ -38,6 +34,7 @@
 .Sh NAME
 .Nm psignal ,
 .Nm strsignal ,
+.Nm strsignal_r ,
 .Nm sys_siglist ,
 .Nm sys_signame
 .Nd system signal messages
@@ -52,11 +49,18 @@
 .In string.h
 .Ft "char *"
 .Fn strsignal "int sig"
+.Ft "int"
+.Fo strsignal_r
+.Fa "int sig"
+.Fa "char *strsignalbuf"
+.Fa "size_t buflen"
+.Fc
 .Sh DESCRIPTION
 The
-.Fn psignal
+.Fn psignal ,
+.Fn strsignal ,
 and
-.Fn strsignal
+.Fn strsignal_r
 functions locate the descriptive message
 string for a signal number.
 .Pp
@@ -67,6 +71,14 @@ function accepts a signal number argument
 and returns a pointer to the corresponding message string.
 .Pp
 The
+.Fn strsignal_r
+function renders the same result into
+.Fa strsignalbuf
+for a maximum of
+.Fa buflen
+characters and returns 0 upon success.
+.Pp
+The
 .Fn psignal
 function accepts a signal number argument
 .Fa sig
@@ -102,6 +114,41 @@ contains a count of the strings in
 .Va sys_siglist
 and
 .Va sys_signame .
+.Sh RETURN VALUES
+.Fn strsignal
+a pointer to the desired message or a NULL value indicating an error.  This
+string is not to be freed by the caller.  Beginning with Mac OSX 10.7, this
+string is unique to each thread.
+.Pp
+.Fn strsignal_r
+0 if the message string is successfully copied in its entirety to
+.Fa strsignalbuf .
+.Pp
+.Sh ERRORS
+.Fn strsignal
+will fail and no additional memory will be allocated if
+one of the following are true:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+There was insufficient memory to allocate storage space for the return value in the running thread.
+.El
+.Pp
+.Fn strsignal_r
+will return an error (but not fail) if one or more condition is met:
+.Bl -tag -width Er
+.It Bq Er ERANGE
+.Fa buflen
+is not long enough to fit the length of the message.
+.Fa strsignalbuf 
+will contain the message string that has been truncated and
+NUL terminated to fit the length specified by
+.Fa buflen .
+.El
+.Bl -tag -width Er
+.It Bq Er EINVAL
+.Fa sig
+<= 0 or >= NSIG.
+.El
 .Sh SEE ALSO
 .Xr sigaction 2 ,
 .Xr perror 3 ,