xref: /dragonfly/lib/libc/string/strerror.3 (revision e65bc1c3) 
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: src/lib/libc/string/strerror.3,v 1.24 2007/01/09 00:28:12 imp Exp $
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 Mt 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