\" $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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.