xref: /illumos-gate/usr/src/man/man3c/strerror.3c (revision faadcf7e)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2015, Joyent, Inc.
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd April 6, 2024
.Dt STRERROR 3C
.Os
.Sh NAME
.Nm strerror ,
.Nm strerror_r ,
.Nm strerror_l ,
.Nm strerrordesc_np ,
.Nm strerrorname_np
.Nd get error message string
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In string.h
.Ft "char *"
.Fo strerror
.Fa "int errnum"
.Fc
.Ft int
.Fo strerror_r
.Fa "int errnum"
.Fa "char *strerrbuf"
.Fa "size_t buflen"
.Fc
.Ft "char *"
.Fo strerror_l
.Fa "int errnum"
.Fa "locale_t loc"
.Fc
.Ft "const char *"
.Fo strerrordesc_np
.Fa "int errnum"
.Fc
.Ft "const char *"
.Fo strerrorname_np
.Fa "int errnum"
.Fc
.Sh DESCRIPTION
The
.Fn strerror
function maps the error number in
.Fa errnum
to an error message string, and returns a pointer to that string.
It uses the same set of error messages as
.Xr perror 3C .
The returned string should not be overwritten.
The string will be translated based on the current locale.
.Pp
The
.Fn strerror_r
function maps the error number in
.Fa errnum
to an error message string and returns the string in the buffer pointed to by
.Fa strerrbuf
with length
.Fa buflen .
.Pp
The
.Fn strerror_l
function maps the error number in
.Fa \fIerrnum\fR
to an error message string in the locale indicated by
.Fa loc .
The returned string should not be overwritten.
If
.Fa loc
is passed the
.Dv NULL
pointer, then the locale of the calling thread's current locale will be used
instead, like
.Fn strerror .
.Pp
Because the
.Fn strerror
and
.Fn strerror_l
functions, return localized strings in the event of an unknown error, one must
use the value of
.Va errno
to detect an error.
Callers should first set
.Va errno
to
.Sy 0
before the call to either function and then check the value of
.Va errno
after the call.
If the value of
.Va errno
is non-zero then an error has occurred.
.Pp
The
.Fn strerrordesc_np
function behaves the same as
.Fn strerror ,
but will always return the error message string in the C locale and will
not provide a translate message.
Unlike
.Fn strerror ,
unknown error messages will return a
.Dv NULL
pointer.
Clearing
.Va errno
prior to calling
.Fn strerrordesc_np
is still advised, as with
.Fn strerror .
.Pp
The
.Fn strerrorname_np
function translates
.Fa errnum
into the string name of the error constant.
For example:
.Dq Er EIO ,
.Dq Er EINTR ,
etc.
When passed the value of 0, there is no traditional error string.
To match originating implementations, the string
.Dq 0
is returned in that case.
.Sh RETURN VALUES
Upon successful completion,
.Fn strerror
and
.Fn strerror_l
return a pointer to the generated message string.
Otherwise, they set
.Va errno
and returns a pointer to an error message string.
They return the localized string
.Dq Unknown error
if
.Fa errnum
is not a valid error number.
.Pp
Upon successful completion,
.Fn strerror_r
returns
.Sy 0 .
Otherwise it sets
.Va errno
and returns the value of
.Va errno
to indicate the error.
It returns the localized string
.Dq Unknown error
in the buffer pointed to by
.Fa strerrbuf
if
.Fa errnum
is not a valid error number.
.Pp
Upon successful completion, the
.Fn strerrordesc_np
function returns the C locale's generated message string.
Otherwise,
.Dv NULL
is returned and
.Va errno
is set.
Unlike
.Fn strerror ,
this occurs when a string's translation is not known.
.Pp
Upon successful completion, the
.Fn strerrorname_np
function returns the C language constant name of the error.
Otherwise,
.Dv NULL
is returned and
.Va errno
is set.
.Sh ERRORS
These functions may fail if:
.Bl -tag -width Er
.It Er EINVAL
The value of
.Fa errnum
is not a valid error number.
.El
.Pp
The
.Fn strerror_r
function may fail if:
.Bl -tag -width Er
.It Er ERANGE
The
.Fa buflen
argument specifies insufficient storage to contain the generated message string.
.El
.Sh USAGE
Messages returned from these functions
.Po
other than
.Fn strerrordesc_np
and
.Fn strerrorname_np
.Pc
are in the native language specified by the
.Dv LC_MESSAGES
locale category.
See
.Xr setlocale 3C
and
.Xr uselocale 3C .
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Safe
.Sh SEE ALSO
.Xr gettext 3C ,
.Xr perror 3C ,
.Xr setlocale 3C ,
.Xr uselocale 3C ,
.Xr attributes 7 ,
.Xr standards 7