edfb8176f3bdce38844b2c3159c3122c4fc46586
[dragonfly.git] / lib / libc / string / strerror.3
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. 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: head/lib/libc/string/strerror.3 251069 2013-05-28 20:57:40Z emaste $
34 .\"
35 .Dd April 5, 2011
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
59 The
60 .Fn strerror ,
61 .Fn strerror_r
62 and
63 .Fn perror
64 functions look up the error message string corresponding to an
65 error number.
66 .Pp
67 The
68 .Fn strerror
69 function accepts an error number argument
70 .Fa errnum
71 and returns a pointer to the corresponding
72 message string.
73 .Pp
74 The
75 .Fn strerror_r
76 function renders the same result into
77 .Fa strerrbuf
78 for a maximum of
79 .Fa buflen
80 characters and returns 0 upon success.
81 .Pp
82 The
83 .Fn perror
84 function finds the error message corresponding to the current
85 value of the global variable
86 .Va errno
87 .Pq Xr intro 2
88 and writes it, followed by a newline, to the
89 standard error file descriptor.
90 If the argument
91 .Fa string
92 is
93 .Pf non- Dv NULL
94 and does not point to the null character,
95 this string is prepended to the message
96 string and separated from it by
97 a colon and space
98 .Pq Dq Li ":\ " ;
99 otherwise, only the error message string is printed.
100 .Pp
101 If the error number is not recognized, these functions return an error message
102 string containing
103 .Dq Li "Unknown error:\ "
104 followed by the error number in decimal.
105 The
106 .Fn strerror
107 and
108 .Fn strerror_r
109 functions return
110 .Er EINVAL
111 as a warning.
112 Error numbers recognized by this implementation fall in
113 the range 0 <
114 .Fa errnum
115 <
116 .Fa sys_nerr .
117 The number 0 is also recognized, although applications that take advantage of
118 this are likely to use unspecified values of
119 .Va errno .
120 .Pp
121 If insufficient storage is provided in
122 .Fa strerrbuf
123 (as specified in
124 .Fa buflen )
125 to contain the error string,
126 .Fn strerror_r
127 returns
128 .Er ERANGE
129 and
130 .Fa strerrbuf
131 will contain an error message that has been truncated and
132 .Dv NUL
133 terminated to fit the length specified by
134 .Fa buflen .
135 .Pp
136 The message strings can be accessed directly using the external
137 array
138 .Va sys_errlist .
139 The external value
140 .Va sys_nerr
141 contains a count of the messages in
142 .Va sys_errlist .
143 The use of these variables is deprecated;
144 .Fn strerror
145 or
146 .Fn strerror_r
147 should be used instead.
148 .Sh SEE ALSO
149 .Xr intro 2 ,
150 .Xr err 3 ,
151 .Xr psignal 3
152 .Sh STANDARDS
153 The
154 .Fn perror
155 and
156 .Fn strerror
157 functions conform to
158 .St -isoC-99 .
159 The
160 .Fn strerror_r
161 function conforms to
162 .St -p1003.1-2001 .
163 .Sh HISTORY
164 The
165 .Fn strerror
166 and
167 .Fn perror
168 functions first appeared in
169 .Bx 4.4 .
170 The
171 .Fn strerror_r
172 function was implemented in
173 .Fx 4.4
174 by
175 .An Wes Peters Aq wes@FreeBSD.org .
176 .Sh BUGS
177 The
178 .Fn strerror
179 function returns its result in a static buffer which
180 will be overwritten by subsequent calls.
181 .Pp
182 The return type for
183 .Fn strerror
184 is missing a type-qualifier; it should actually be
185 .Vt const char * .
186 .Pp
187 Programs that use the deprecated
188 .Va sys_errlist
189 variable often fail to compile because they declare it
190 inconsistently.