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