xref: /netbsd-src/lib/libc/string/strerror.3 (revision 7ec84f335ad5fb4672305723762810836fa080e1)

.\" $NetBSD: strerror.3,v 1.24 2020/04/04 21:29:54 dholland Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 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. 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)strerror.3	8.1 (Berkeley) 6/9/93
.Dd April 4, 2020
.Dt STRERROR 3
.Os
.Sh NAME
.Nm perror ,
.Nm strerror ,
.Nm strerror_l ,
.\" .Nm strerror_lr ,
.Nm strerror_r ,
.Nm sys_errlist ,
.Nm sys_nerr
.Nd system error messages
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdio.h
.Ft void
.Fn perror "const char *string"
.In errno.h
.Vt extern const char * const sys_errlist[] ;
.Vt extern const int sys_nerr ;
.In string.h
.Ft "char *"
.Fn strerror "int errnum"
.Ft int
.Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen"
.Ft "char *"
.Fn strerror_l "int errnum" "locale_t loc"
.\".Ft int
.\".Fn strerror_lr "int errnum" "char *strerrbuf" "size_t buflen" "locale_t loc"
.Sh DESCRIPTION
The
.Fn strerror ,
.Fn strerror_l ,
.\".Fn strerror_lr ,
.Fn strerror_r ,
and
.Fn perror
functions look up the language-dependent error message
string corresponding to an error number.
.Pp
The
.Fn strerror
function accepts an error number argument
.Fa errnum
and returns a pointer to the corresponding
message string.
The application should not attempt to modify the
returned string, it may be shared, or read only.
.Pp
The
.Fn strerror_r
function renders the same result into
.Fa strerrbuf
for a maximum of
.Fa buflen
characters (including terminator) and returns 0 upon success.
.Pp
The
.Fn strerror_l
function is like
.Fn strerror
but provides in
.Fa loc
the locale to be used to obtain the language for the message,
rather than using the application's current locale.
.\".Pp
.\"The
.\".Fn strerror_lr
.\"function is to
.\".Fn strerror_l
.\"as
.\".Fn strerror_r
.\"is to
.\".Fn strerror .
.Pp
The
.Fn perror
function finds the error message corresponding to the current
value of the global variable
.Va errno
.Pq Xr intro 2
and writes it, followed by a newline, to the
standard error file descriptor.
If the argument
.Fa string
is
.Pf non- Dv NULL
and does not point to the nul character,
this string is prepended to the message
string and separated from it by
a colon and space
.Pq Dq Li ":\ " ;
otherwise, only the error message string is printed.
Note that in most cases the
.Xr err 3
and
.Xr warn 3
family of functions is preferable to
.Fn perror ;
they are more flexible and also print the program name.
.Pp
If the error number is not recognized, these functions return an error message
string containing
.\" , in the appropriate language,
.Dq Li "Unknown error:\ "
followed by the error number in decimal.
To warn about this,
.Fn strerror
and
.Fn strerror_l
set
.Dv errno
to
.Er EINVAL ,
and
.Fn strerror_r
.\"and
.\".Fn strerror_lr
returns
.Er EINVAL .
In other cases, except where noted below,
.Dv errno
is not altered, so applications should set it to a known value
(usually zero) before calling either
.Fn strerror
or
.Fn strerror_l
if the resulting value in
.Dv errno
is to be tested for this condition.
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
.\" and
.\" .Fn strerror_lr
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 .
In extraordinary cases, it is possible that the internal
buffer used by
.Fn strerror
and
.Fn strerror_l
may be too small for a translated message,
in which case it will be truncated as indicated for
.Fn strerror_r
and
.Dv errno
will be set to
.Er ERANGE .
.Pp
The POSIX locale message strings can be accessed directly using the external
array
.Va sys_errlist .
The external value
.Va sys_nerr
contains a count of the messages in
.Va sys_errlist .
The use of these variables is deprecated;
one of the
.Fn strerror
family of functions should be used instead.
.Sh COMPATIBILITY
Programs that attempt to use the deprecated
.Va sys_errlist
variable often fail to compile because they provide their own,
inconsistent, declaration of it.
Such programs should be updated to use
.Fn strerror .
.Sh ERRORS
These functions may fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The error number was out of range.
.It Bq Er ERANGE
The string buffer supplied was not large enough to hold the complete
error message.
.El
.Sh SEE ALSO
.Xr intro 2 ,
.Xr err 3 ,
.Xr psignal 3 ,
.Xr warn 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 .
The
.Fn strerror_l
function conforms to
.St -p1003.1-2008 .
.Sh HISTORY
The
.Fn perror
function first appeared in
.At v4 .
The
.Fn strerror
function first appeared in
.Bx 4.3 Reno .
The
.Fn strerror_r
function first appeared in
.Nx 4.0 .
The
.Fn strerror_l
function was first released in
.Nx 7.0 .
.\"The
.\".Fn strerror_lr
.\"function first appeared in
.\".Nx 10.0 .
.Sh BUGS
The
.Fn strerror
function may return its result in a static buffer which
will be overwritten by subsequent calls.
For portable use, this must be assumed to be a subsequent
call from the current, or any other, thread in the process.
This implementation limits the issue to calls from the
current thread.
The
.Fn strerror_l
function has a similar restriction, but even in other
implementations, is required to use thread local storage,
so only other calls from the calling thread can overwrite
the result.
Both
.Fn strerror
and
.Fn strerror_l
use the same thread local storage; a call to either will destroy
the result from an earlier call by the same thread of either of them.