]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) |
1130df60 | 2 | .\" and Copyright (C) 2005, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
3 | .\" |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" | |
24 | .\" References consulted: | |
25 | .\" Linux libc source code | |
26 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
27 | .\" 386BSD man pages | |
28 | .\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith <faith@cs.unc.edu> | |
29 | .\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer <aeb@cwi.nl> | |
30 | .\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer <aeb@cwi.nl> | |
31 | .\" Modified Mon Oct 15 21:16:25 2001 by John Levon <moz@compsoc.man.ac.uk> | |
32 | .\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer <aeb@cwi.nl> | |
33 | .\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer <aeb@cwi.nl> | |
ed07f09a MK |
34 | .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description |
35 | .\" Addition of extra material on portability and standards. | |
fea681da | 36 | .\" |
6e84dfa1 | 37 | .TH STRERROR 3 2005-12-13 "" "Linux Programmer's Manual" |
fea681da | 38 | .SH NAME |
6e84dfa1 | 39 | strerror, strerror_r \- return string describing error number |
fea681da MK |
40 | .SH SYNOPSIS |
41 | .nf | |
42 | .B #include <string.h> | |
43 | .sp | |
44 | .BI "char *strerror(int " errnum ); | |
b99cf1e0 | 45 | .sp |
6e84dfa1 MK |
46 | .BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen ); |
47 | /* GNU-specific strerror_r() */ | |
48 | .sp | |
49 | .B #define _XOPEN_SOURCE 600 | |
b99cf1e0 MK |
50 | .B #include <string.h> |
51 | .sp | |
6e84dfa1 MK |
52 | .BI "int strerror_r(int " errnum ", char *" buf ", size_t " buflen ); |
53 | /* XSI-compliant strerror_r() */ | |
fea681da MK |
54 | .fi |
55 | .SH DESCRIPTION | |
63aa9df0 | 56 | The \fBstrerror\fP() function returns a string describing the error |
fea681da MK |
57 | code passed in the argument \fIerrnum\fP, possibly using the LC_MESSAGES |
58 | part of the current locale to select the appropriate language. | |
59 | This string must not be modified by the application, but may be | |
63aa9df0 | 60 | modified by a subsequent call to \fBperror\fP() or \fBstrerror\fP(). |
fea681da MK |
61 | No library function will modify this string. |
62 | ||
63aa9df0 | 63 | The \fBstrerror_r\fP() function is similar to \fBstrerror\fP(), but is |
6e84dfa1 MK |
64 | thread safe. |
65 | This function is available in two versions: | |
66 | an XSI-compliant version specified in SUSv3, | |
67 | and a GNU-specific version (available since glibc 2.0). | |
68 | If _XOPEN_SOURCE is defined with the value 600, | |
69 | then the XSI-compliant version is provided, | |
70 | otherwise the GNU-specific version is provided. | |
71 | ||
72 | The XSI-compliant | |
73 | .BR strerror_r () | |
74 | is preferred for portable applications. | |
75 | It returns the error string in the user-supplied buffer | |
fea681da MK |
76 | .I buf |
77 | of length | |
6e84dfa1 MK |
78 | .IR buflen . |
79 | ||
80 | The GNU-specific | |
81 | .BR strerror_r () | |
82 | returns a pointer to a string containing the error message. | |
83 | This may be either a pointer to a string that the function stores in | |
84 | .IR buf , | |
85 | or a pointer to some (immutable) static string | |
86 | (in which case | |
87 | .I buf | |
88 | is unused). | |
89 | If the function stores a string in | |
90 | .IR buf , | |
91 | then at most | |
92 | .I buflen | |
93 | bytes are stored (the string may be truncated if | |
94 | .I buflen | |
95 | is too small) and the string always includes a terminating null byte. | |
fea681da MK |
96 | |
97 | .SH "RETURN VALUE" | |
ed07f09a | 98 | The \fBstrerror\fP() and \fBstrerror_r\fP() functions return |
6e84dfa1 MK |
99 | the appropriate error description string, |
100 | or an "Unknown error nnn" message if the error number is unknown. | |
6e84dfa1 MK |
101 | |
102 | The XSI-compliant \fBstrerror_r\fP() function returns 0 on success; | |
103 | on error, \-1 is returned and | |
104 | .I errno | |
105 | is set to indicate the error. | |
fea681da MK |
106 | |
107 | .SH ERRORS | |
108 | .TP | |
109 | .B EINVAL | |
110 | The value of | |
111 | .I errnum | |
112 | is not a valid error number. | |
113 | .TP | |
114 | .B ERANGE | |
115 | Insufficient storage was supplied to contain the error description string. | |
116 | ||
117 | .SH "CONFORMING TO" | |
6e84dfa1 MK |
118 | POSIX.1 |
119 | ||
120 | The GNU-specific | |
63aa9df0 | 121 | .BR strerror_r () |
6e84dfa1 MK |
122 | function is a non-standard extension. |
123 | ||
124 | POSIX.1 permits | |
125 | .BR strerror () | |
126 | to set | |
127 | .I errno | |
128 | if the call encounters an error, but does not specify what | |
129 | value should be returned as the function result in the event of an error. | |
130 | On some systems, | |
131 | .\" e.g., Solaris 8, HP-UX 11 | |
132 | .BR strerror () | |
133 | returns NULL if the error number is unknown. | |
134 | On other systems, | |
135 | .\" e.g., FreeBSD 5.4, Tru64 5.1B | |
136 | .BR strerror () | |
137 | returns a string something like "Error nnn occurred" and sets | |
138 | .I errno | |
139 | to | |
140 | .B EINVAL | |
141 | if the error number is unknown. | |
142 | ||
fea681da | 143 | .SH "SEE ALSO" |
d7871cf9 | 144 | .BR err (3), |
fea681da | 145 | .BR errno (3), |
37b6aec3 | 146 | .BR error (3), |
fea681da MK |
147 | .BR perror (3), |
148 | .BR strsignal (3) |