xref: /dragonfly/lib/libc/string/strerror.3 (revision 0db87cb7) 
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
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 .
117The number 0 is also recognized, although applications that take advantage of
118this are likely to use unspecified values of
119.Va errno .
120.Pp
121If insufficient storage is provided in
122.Fa strerrbuf
123(as specified in
124.Fa buflen )
125to contain the error string,
126.Fn strerror_r
127returns
128.Er ERANGE
129and
130.Fa strerrbuf
131will contain an error message that has been truncated and
132.Dv NUL
133terminated to fit the length specified by
134.Fa buflen .
135.Pp
136The message strings can be accessed directly using the external
137array
138.Va sys_errlist .
139The external value
140.Va sys_nerr
141contains a count of the messages in
142.Va sys_errlist .
143The use of these variables is deprecated;
144.Fn strerror
145or
146.Fn strerror_r
147should be used instead.
148.Sh SEE ALSO
149.Xr intro 2 ,
150.Xr err 3 ,
151.Xr psignal 3
152.Sh STANDARDS
153The
154.Fn perror
155and
156.Fn strerror
157functions conform to
158.St -isoC-99 .
159The
160.Fn strerror_r
161function conforms to
162.St -p1003.1-2001 .
163.Sh HISTORY
164The
165.Fn strerror
166and
167.Fn perror
168functions first appeared in
169.Bx 4.4 .
170The
171.Fn strerror_r
172function was implemented in
173.Fx 4.4
174by
175.An Wes Peters Aq Mt wes@FreeBSD.org .
176.Sh BUGS
177The
178.Fn strerror
179function returns its result in a static buffer which
180will be overwritten by subsequent calls.
181.Pp
182The return type for
183.Fn strerror
184is missing a type-qualifier; it should actually be
185.Vt const char * .
186.Pp
187Programs that use the deprecated
188.Va sys_errlist
189variable often fail to compile because they declare it
190inconsistently.
191