1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright 1989 AT&T 44.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 45.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. 46.\" Copyright 2015, Joyent, Inc. 47.\" Copyright 2024 Oxide Computer Company 48.\" 49.Dd April 6, 2024 50.Dt STRERROR 3C 51.Os 52.Sh NAME 53.Nm strerror , 54.Nm strerror_r , 55.Nm strerror_l , 56.Nm strerrordesc_np , 57.Nm strerrorname_np 58.Nd get error message string 59.Sh LIBRARY 60.Lb libc 61.Sh SYNOPSIS 62.In string.h 63.Ft "char *" 64.Fo strerror 65.Fa "int errnum" 66.Fc 67.Ft int 68.Fo strerror_r 69.Fa "int errnum" 70.Fa "char *strerrbuf" 71.Fa "size_t buflen" 72.Fc 73.Ft "char *" 74.Fo strerror_l 75.Fa "int errnum" 76.Fa "locale_t loc" 77.Fc 78.Ft "const char *" 79.Fo strerrordesc_np 80.Fa "int errnum" 81.Fc 82.Ft "const char *" 83.Fo strerrorname_np 84.Fa "int errnum" 85.Fc 86.Sh DESCRIPTION 87The 88.Fn strerror 89function maps the error number in 90.Fa errnum 91to an error message string, and returns a pointer to that string. 92It uses the same set of error messages as 93.Xr perror 3C . 94The returned string should not be overwritten. 95The string will be translated based on the current locale. 96.Pp 97The 98.Fn strerror_r 99function maps the error number in 100.Fa errnum 101to an error message string and returns the string in the buffer pointed to by 102.Fa strerrbuf 103with length 104.Fa buflen . 105.Pp 106The 107.Fn strerror_l 108function maps the error number in 109.Fa \fIerrnum\fR 110to an error message string in the locale indicated by 111.Fa loc . 112The returned string should not be overwritten. 113If 114.Fa loc 115is passed the 116.Dv NULL 117pointer, then the locale of the calling thread's current locale will be used 118instead, like 119.Fn strerror . 120.Pp 121Because the 122.Fn strerror 123and 124.Fn strerror_l 125functions, return localized strings in the event of an unknown error, one must 126use the value of 127.Va errno 128to detect an error. 129Callers should first set 130.Va errno 131to 132.Sy 0 133before the call to either function and then check the value of 134.Va errno 135after the call. 136If the value of 137.Va errno 138is non-zero then an error has occurred. 139.Pp 140The 141.Fn strerrordesc_np 142function behaves the same as 143.Fn strerror , 144but will always return the error message string in the C locale and will 145not provide a translate message. 146Unlike 147.Fn strerror , 148unknown error messages will return a 149.Dv NULL 150pointer. 151Clearing 152.Va errno 153prior to calling 154.Fn strerrordesc_np 155is still advised, as with 156.Fn strerror . 157.Pp 158The 159.Fn strerrorname_np 160function translates 161.Fa errnum 162into the string name of the error constant. 163For example: 164.Dq Er EIO , 165.Dq Er EINTR , 166etc. 167When passed the value of 0, there is no traditional error string. 168To match originating implementations, the string 169.Dq 0 170is returned in that case. 171.Sh RETURN VALUES 172Upon successful completion, 173.Fn strerror 174and 175.Fn strerror_l 176return a pointer to the generated message string. 177Otherwise, they set 178.Va errno 179and returns a pointer to an error message string. 180They return the localized string 181.Dq Unknown error 182if 183.Fa errnum 184is not a valid error number. 185.Pp 186Upon successful completion, 187.Fn strerror_r 188returns 189.Sy 0 . 190Otherwise it sets 191.Va errno 192and returns the value of 193.Va errno 194to indicate the error. 195It returns the localized string 196.Dq Unknown error 197in the buffer pointed to by 198.Fa strerrbuf 199if 200.Fa errnum 201is not a valid error number. 202.Pp 203Upon successful completion, the 204.Fn strerrordesc_np 205function returns the C locale's generated message string. 206Otherwise, 207.Dv NULL 208is returned and 209.Va errno 210is set. 211Unlike 212.Fn strerror , 213this occurs when a string's translation is not known. 214.Pp 215Upon successful completion, the 216.Fn strerrorname_np 217function returns the C language constant name of the error. 218Otherwise, 219.Dv NULL 220is returned and 221.Va errno 222is set. 223.Sh ERRORS 224These functions may fail if: 225.Bl -tag -width Er 226.It Er EINVAL 227The value of 228.Fa errnum 229is not a valid error number. 230.El 231.Pp 232The 233.Fn strerror_r 234function may fail if: 235.Bl -tag -width Er 236.It Er ERANGE 237The 238.Fa buflen 239argument specifies insufficient storage to contain the generated message string. 240.El 241.Sh USAGE 242Messages returned from these functions 243.Po 244other than 245.Fn strerrordesc_np 246and 247.Fn strerrorname_np 248.Pc 249are in the native language specified by the 250.Dv LC_MESSAGES 251locale category. 252See 253.Xr setlocale 3C 254and 255.Xr uselocale 3C . 256.Sh INTERFACE STABILITY 257.Sy Committed 258.Sh MT-LEVEL 259.Sy Safe 260.Sh SEE ALSO 261.Xr gettext 3C , 262.Xr perror 3C , 263.Xr setlocale 3C , 264.Xr uselocale 3C , 265.Xr attributes 7 , 266.Xr standards 7 267