1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the American National Standards Committee X3, on Information 6.\" Processing Systems. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the University of 19.\" California, Berkeley and its contributors. 20.\" 4. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" @(#)strerror.3 8.1 (Berkeley) 6/9/93 37.\" $FreeBSD: src/lib/libc/string/strerror.3,v 1.7.2.7 2003/01/17 13:39:50 mike Exp $ 38.\" $DragonFly: src/lib/libc/string/strerror.3,v 1.2 2003/06/17 04:26:46 dillon Exp $ 39.\" 40.Dd December 19, 2002 41.Dt STRERROR 3 42.Os 43.Sh NAME 44.Nm perror , 45.Nm strerror , 46.Nm strerror_r , 47.Nm sys_errlist , 48.Nm sys_nerr 49.Nd system error messages 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.In stdio.h 54.Ft void 55.Fn perror "const char *string" 56.Vt extern const char * const sys_errlist[] ; 57.Vt extern const int sys_nerr ; 58.In string.h 59.Ft "char *" 60.Fn strerror "int errnum" 61.Ft int 62.Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen" 63.Sh DESCRIPTION 64The 65.Fn strerror , 66.Fn strerror_r 67and 68.Fn perror 69functions look up the error message string corresponding to an 70error number. 71.Pp 72The 73.Fn strerror 74function accepts an error number argument 75.Fa errnum 76and returns a pointer to the corresponding 77message string. 78.Pp 79The 80.Fn strerror_r 81function renders the same result into 82.Fa strerrbuf 83for a maximum of 84.Fa buflen 85characters and returns 0 upon success. 86.Pp 87The 88.Fn perror 89function finds the error message corresponding to the current 90value of the global variable 91.Va errno 92.Pq Xr intro 2 93and writes it, followed by a newline, to the 94standard error file descriptor. 95If the argument 96.Fa string 97is 98.Pf non- Dv NULL 99and does not point to the null character, 100this string is prepended to the message 101string and separated from it by 102a colon and space 103.Pq Dq Li ":\ " ; 104otherwise, only the error message string is printed. 105.Pp 106If 107.Fa errnum 108is not a recognized error number, 109.Fn strerror 110returns an error message string containing 111.Dq Li "Unknown error:\ " 112followed by the error number in decimal, while 113.Fn strerror_r 114leaves 115.Fa strerrbuf 116unchanged and returns 117.Er EINVAL . 118Error numbers recognized by this implementation fall in 119the range 0 < 120.Fa errnum 121< 122.Fa sys_nerr . 123.Pp 124If insufficient storage is provided in 125.Fa strerrbuf 126(as specified in 127.Fa buflen ) 128to contain the error string, 129.Fn strerror_r 130returns 131.Er ERANGE 132and 133.Fa strerrbuf 134will contain an error message that has been truncated and 135.Dv NUL 136terminated to fit the length specified by 137.Fa buflen . 138.Pp 139The message strings can be accessed directly using the external 140array 141.Va sys_errlist . 142The external value 143.Va sys_nerr 144contains a count of the messages in 145.Va sys_errlist . 146The use of these variables is deprecated; 147.Fn strerror 148or 149.Fn strerror_r 150should be used instead. 151.Sh SEE ALSO 152.Xr intro 2 , 153.Xr psignal 3 154.Sh STANDARDS 155The 156.Fn perror 157and 158.Fn strerror 159functions conform to 160.St -isoC-99 . 161The 162.Fn strerror_r 163function conforms to 164.St -p1003.1-2001 . 165.Sh HISTORY 166The 167.Fn strerror 168and 169.Fn perror 170functions first appeared in 171.Bx 4.4 . 172The 173.Fn strerror_r 174function was implemented in 175.Fx 4.4 176by 177.An Wes Peters Aq wes@FreeBSD.org . 178.Sh BUGS 179For unknown error numbers, the 180.Fn strerror 181function will return its result in a static buffer which 182may be overwritten by subsequent calls. 183.Pp 184The return type for 185.Fn strerror 186is missing a type-qualifier; it should actually be 187.Vt const char * . 188.Pp 189Programs that use the deprecated 190.Va sys_errlist 191variable often fail to compile because they declare it 192inconsistently. 193