Libc-763.13.tar.gz

[apple/libc.git] / string / strerror.3

diff --git a/string/strerror.3 b/string/strerror.3
index c82aebf57317889556f6c54c99e9c649ccdc9159..f6f7510d64bf0abe539d22eafb1ff8f956c9baa7 100644 (file)
--- a/string/strerror.3
+++ b/string/strerror.3
@@ -13,10 +13,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.
@@ -34,14 +30,15 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)strerror.3 8.1 (Berkeley) 6/9/93
-.\" $FreeBSD: src/lib/libc/string/strerror.3,v 1.12 2001/10/01 16:09:00 ru Exp $
+.\" $FreeBSD: src/lib/libc/string/strerror.3,v 1.24 2007/01/09 00:28:12 imp Exp $
 .\"
-.Dd June 9, 1993
+.Dd October 12, 2004
 .Dt STRERROR 3
 .Os
 .Sh NAME
 .Nm perror ,
 .Nm strerror ,
+.Nm strerror_r ,
 .Nm sys_errlist ,
 .Nm sys_nerr
 .Nd system error messages
@@ -50,15 +47,26 @@
 .Sh SYNOPSIS
 .In stdio.h
 .Ft void
-.Fn perror "const char *string"
+.Fo perror
+.Fa "const char *s"
+.Fc
 .Vt extern const char * const sys_errlist[] ;
 .Vt extern const int sys_nerr ;
 .In string.h
-.Ft char *
-.Fn strerror "int errnum"
+.Ft "char *"
+.Fo strerror
+.Fa "int errnum"
+.Fc
+.Ft int
+.Fo strerror_r
+.Fa "int errnum"
+.Fa "char *strerrbuf"
+.Fa "size_t buflen"
+.Fc
 .Sh DESCRIPTION
 The
-.Fn strerror
+.Fn strerror ,
+.Fn strerror_r ,
 and
 .Fn perror
 functions look up the error message string corresponding to an
@@ -68,11 +76,18 @@ The
 .Fn strerror
 function accepts an error number argument
 .Fa errnum
-and
-returns a pointer to the corresponding
+and returns a pointer to the corresponding
 message string.
 .Pp
 The
+.Fn strerror_r
+function renders the same result into
+.Fa strerrbuf
+for a maximum of
+.Fa buflen
+characters and returns 0 upon success.
+.Pp
+The
 .Fn perror
 function finds the error message corresponding to the current
 value of the global variable
@@ -81,22 +96,47 @@ value of the global variable
 and writes it, followed by a newline, to the
 standard error file descriptor.
 If the argument
-.Fa string
+.Fa s
 is
 .Pf non- Dv NULL
 and does not point to the null character,
 this string is prepended to the message
 string and separated from it by
 a colon and space
-.Pq Ql \&:\ \& ;
+.Pq Dq Li ":\ " ;
 otherwise, only the error message string is printed.
 .Pp
-If
-.Fa errnum
-is not a recognized error number,
-the error message string will contain
+If the error number is not recognized, these functions return an error message
+string containing
 .Dq Li "Unknown error:\ "
 followed by the error number in decimal.
+The
+.Fn strerror
+and
+.Fn strerror_r
+functions return
+.Er EINVAL
+as a warning.
+Error numbers recognized by this implementation fall in
+the range 0 <=
+.Fa errnum
+<
+.Fa sys_nerr .
+.Pp
+If insufficient storage is provided in
+.Fa strerrbuf
+(as specified in
+.Fa buflen )
+to contain the error string,
+.Fn strerror_r
+returns
+.Er ERANGE
+and
+.Fa strerrbuf
+will contain an error message that has been truncated and
+.Dv NUL
+terminated to fit the length specified by
+.Fa buflen .
 .Pp
 The message strings can be accessed directly using the external
 array
@@ -107,10 +147,23 @@ contains a count of the messages in
 .Va sys_errlist .
 The use of these variables is deprecated;
 .Fn strerror
+or
+.Fn strerror_r
 should be used instead.
 .Sh SEE ALSO
 .Xr intro 2 ,
 .Xr psignal 3
+.Sh STANDARDS
+The
+.Fn perror
+and
+.Fn strerror
+functions conform to
+.St -isoC-99 .
+The
+.Fn strerror_r
+function conforms to
+.St -p1003.1-2001 .
 .Sh HISTORY
 The
 .Fn strerror
@@ -118,12 +171,23 @@ and
 .Fn perror
 functions first appeared in
 .Bx 4.4 .
+The
+.Fn strerror_r
+function was implemented in
+.Fx 4.4
+by
+.An Wes Peters Aq wes@FreeBSD.org .
 .Sh BUGS
 For unknown error numbers, the
 .Fn strerror
 function will return its result in a static buffer which
 may be overwritten by subsequent calls.
 .Pp
+The return type for
+.Fn strerror
+is missing a type-qualifier; it should actually be
+.Vt const char * .
+.Pp
 Programs that use the deprecated
 .Va sys_errlist
 variable often fail to compile because they declare it