]>
Commit | Line | Data |
---|---|---|
99a20616 | 1 | @node Error Reporting, Memory, Introduction, Top |
28f540f4 | 2 | @chapter Error Reporting |
7a68c94a | 3 | @c %MENU% How library functions report errors |
28f540f4 RM |
4 | @cindex error reporting |
5 | @cindex reporting errors | |
6 | @cindex error codes | |
7 | @cindex status codes | |
8 | ||
1f77f049 | 9 | Many functions in @theglibc{} detect and report error conditions, |
28f540f4 RM |
10 | and sometimes your programs need to check for these error conditions. |
11 | For example, when you open an input file, you should verify that the | |
12 | file was actually opened correctly, and print an error message or take | |
13 | other appropriate action if the call to the library function failed. | |
14 | ||
15 | This chapter describes how the error reporting facility works. Your | |
16 | program should include the header file @file{errno.h} to use this | |
17 | facility. | |
18 | @pindex errno.h | |
19 | ||
20 | @menu | |
21 | * Checking for Errors:: How errors are reported by library functions. | |
b8fe19fa | 22 | * Error Codes:: Error code macros; all of these expand |
28f540f4 RM |
23 | into integer constant values. |
24 | * Error Messages:: Mapping error codes onto error messages. | |
25 | @end menu | |
26 | ||
27 | @node Checking for Errors, Error Codes, , Error Reporting | |
28 | @section Checking for Errors | |
29 | ||
30 | Most library functions return a special value to indicate that they have | |
31 | failed. The special value is typically @code{-1}, a null pointer, or a | |
32 | constant such as @code{EOF} that is defined for that purpose. But this | |
33 | return value tells you only that an error has occurred. To find out | |
34 | what kind of error it was, you need to look at the error code stored in the | |
35 | variable @code{errno}. This variable is declared in the header file | |
36 | @file{errno.h}. | |
37 | @pindex errno.h | |
38 | ||
28f540f4 | 39 | @deftypevr {Variable} {volatile int} errno |
d08a7e4c | 40 | @standards{ISO, errno.h} |
28f540f4 RM |
41 | The variable @code{errno} contains the system error number. You can |
42 | change the value of @code{errno}. | |
43 | ||
44 | Since @code{errno} is declared @code{volatile}, it might be changed | |
45 | asynchronously by a signal handler; see @ref{Defining Handlers}. | |
46 | However, a properly written signal handler saves and restores the value | |
47 | of @code{errno}, so you generally do not need to worry about this | |
48 | possibility except when writing signal handlers. | |
49 | ||
54e4efc2 AJ |
50 | The initial value of @code{errno} at program startup is zero. In many |
51 | cases, when a library function encounters an error, it will set | |
52 | @code{errno} to a non-zero value to indicate what specific error | |
53 | condition occurred. The documentation for each function lists the | |
54 | error conditions that are possible for that function. Not all library | |
55 | functions use this mechanism; some return an error code directly, | |
56 | instead. | |
28f540f4 | 57 | |
54e4efc2 AJ |
58 | @strong{Warning:} Many library functions may set @code{errno} to some |
59 | meaningless non-zero value even if they did not encounter any errors, | |
60 | and even if they return error codes directly. Therefore, it is | |
61 | usually incorrect to check @emph{whether} an error occurred by | |
62 | inspecting the value of @code{errno}. The proper way to check for | |
63 | error is documented for each function. | |
28f540f4 | 64 | |
f65fd747 | 65 | @strong{Portability Note:} @w{ISO C} specifies @code{errno} as a |
28f540f4 RM |
66 | ``modifiable lvalue'' rather than as a variable, permitting it to be |
67 | implemented as a macro. For example, its expansion might involve a | |
a7a93d50 JM |
68 | function call, like @w{@code{*__errno_location ()}}. In fact, that is |
69 | what it is | |
70 | on @gnulinuxhurdsystems{}. @Theglibc{}, on each system, does | |
28f540f4 RM |
71 | whatever is right for the particular system. |
72 | ||
73 | There are a few library functions, like @code{sqrt} and @code{atan}, | |
74 | that return a perfectly legitimate value in case of an error, but also | |
75 | set @code{errno}. For these functions, if you want to check to see | |
76 | whether an error occurred, the recommended method is to set @code{errno} | |
77 | to zero before calling the function, and then check its value afterward. | |
78 | @end deftypevr | |
79 | ||
80 | @pindex errno.h | |
81 | All the error codes have symbolic names; they are macros defined in | |
82 | @file{errno.h}. The names start with @samp{E} and an upper-case | |
83 | letter or digit; you should consider names of this form to be | |
84 | reserved names. @xref{Reserved Names}. | |
85 | ||
86 | The error code values are all positive integers and are all distinct, | |
87 | with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same. | |
88 | Since the values are distinct, you can use them as labels in a | |
89 | @code{switch} statement; just don't use both @code{EWOULDBLOCK} and | |
90 | @code{EAGAIN}. Your program should not make any other assumptions about | |
91 | the specific values of these symbolic constants. | |
92 | ||
93 | The value of @code{errno} doesn't necessarily have to correspond to any | |
94 | of these macros, since some library functions might return other error | |
95 | codes of their own for other situations. The only values that are | |
96 | guaranteed to be meaningful for a particular library function are the | |
97 | ones that this manual lists for that function. | |
98 | ||
a7a93d50 | 99 | Except on @gnuhurdsystems{}, almost any system call can return @code{EFAULT} if |
28f540f4 RM |
100 | it is given an invalid pointer as an argument. Since this could only |
101 | happen as a result of a bug in your program, and since it will not | |
a7a93d50 | 102 | happen on @gnuhurdsystems{}, we have saved space by not mentioning |
28f540f4 RM |
103 | @code{EFAULT} in the descriptions of individual functions. |
104 | ||
105 | In some Unix systems, many system calls can also return @code{EFAULT} if | |
106 | given as an argument a pointer into the stack, and the kernel for some | |
107 | obscure reason fails in its attempt to extend the stack. If this ever | |
108 | happens, you should probably try using statically or dynamically | |
109 | allocated memory instead of stack memory on that system. | |
110 | ||
111 | @node Error Codes, Error Messages, Checking for Errors, Error Reporting | |
112 | @section Error Codes | |
113 | ||
114 | @pindex errno.h | |
115 | The error code macros are defined in the header file @file{errno.h}. | |
116 | All of them expand into integer constant values. Some of these error | |
a7a93d50 | 117 | codes can't occur on @gnusystems{}, but they can occur using @theglibc{} |
1f77f049 | 118 | on other systems. |
28f540f4 | 119 | |
28f540f4 | 120 | @deftypevr Macro int EPERM |
d08a7e4c | 121 | @standards{POSIX.1, errno.h} |
a429d2ff | 122 | @errno{EPERM, 1, Operation not permitted} |
3e6def23 | 123 | Only the owner of the file (or other resource) |
28f540f4 RM |
124 | or processes with special privileges can perform the operation. |
125 | @end deftypevr | |
126 | ||
28f540f4 | 127 | @deftypevr Macro int ENOENT |
d08a7e4c | 128 | @standards{POSIX.1, errno.h} |
a429d2ff | 129 | @errno{ENOENT, 2, No such file or directory} |
3e6def23 | 130 | This is a ``file doesn't exist'' error |
28f540f4 RM |
131 | for ordinary files that are referenced in contexts where they are |
132 | expected to already exist. | |
133 | @end deftypevr | |
134 | ||
28f540f4 | 135 | @deftypevr Macro int ESRCH |
d08a7e4c | 136 | @standards{POSIX.1, errno.h} |
a429d2ff | 137 | @errno{ESRCH, 3, No such process} |
28f540f4 RM |
138 | No process matches the specified process ID. |
139 | @end deftypevr | |
140 | ||
28f540f4 | 141 | @deftypevr Macro int EINTR |
d08a7e4c | 142 | @standards{POSIX.1, errno.h} |
a429d2ff | 143 | @errno{EINTR, 4, Interrupted system call} |
3e6def23 | 144 | An asynchronous signal occurred and prevented |
28f540f4 RM |
145 | completion of the call. When this happens, you should try the call |
146 | again. | |
147 | ||
148 | You can choose to have functions resume after a signal that is handled, | |
149 | rather than failing with @code{EINTR}; see @ref{Interrupted | |
150 | Primitives}. | |
151 | @end deftypevr | |
152 | ||
28f540f4 | 153 | @deftypevr Macro int EIO |
d08a7e4c | 154 | @standards{POSIX.1, errno.h} |
a429d2ff | 155 | @errno{EIO, 5, Input/output error} |
3e6def23 | 156 | Usually used for physical read or write errors. |
28f540f4 RM |
157 | @end deftypevr |
158 | ||
28f540f4 | 159 | @deftypevr Macro int ENXIO |
d08a7e4c | 160 | @standards{POSIX.1, errno.h} |
a429d2ff | 161 | @errno{ENXIO, 6, No such device or address} |
3e6def23 | 162 | The system tried to use the device |
28f540f4 RM |
163 | represented by a file you specified, and it couldn't find the device. |
164 | This can mean that the device file was installed incorrectly, or that | |
165 | the physical device is missing or not correctly attached to the | |
166 | computer. | |
167 | @end deftypevr | |
168 | ||
28f540f4 | 169 | @deftypevr Macro int E2BIG |
d08a7e4c | 170 | @standards{POSIX.1, errno.h} |
a429d2ff | 171 | @errno{E2BIG, 7, Argument list too long} |
3e6def23 | 172 | Used when the arguments passed to a new program |
28f540f4 | 173 | being executed with one of the @code{exec} functions (@pxref{Executing a |
a7a93d50 JM |
174 | File}) occupy too much memory space. This condition never arises on |
175 | @gnuhurdsystems{}. | |
28f540f4 RM |
176 | @end deftypevr |
177 | ||
28f540f4 | 178 | @deftypevr Macro int ENOEXEC |
d08a7e4c | 179 | @standards{POSIX.1, errno.h} |
a429d2ff | 180 | @errno{ENOEXEC, 8, Exec format error} |
28f540f4 RM |
181 | Invalid executable file format. This condition is detected by the |
182 | @code{exec} functions; see @ref{Executing a File}. | |
183 | @end deftypevr | |
184 | ||
28f540f4 | 185 | @deftypevr Macro int EBADF |
d08a7e4c | 186 | @standards{POSIX.1, errno.h} |
a429d2ff | 187 | @errno{EBADF, 9, Bad file descriptor} |
3e6def23 | 188 | For example, I/O on a descriptor that has been |
28f540f4 RM |
189 | closed or reading from a descriptor open only for writing (or vice |
190 | versa). | |
191 | @end deftypevr | |
192 | ||
28f540f4 | 193 | @deftypevr Macro int ECHILD |
d08a7e4c | 194 | @standards{POSIX.1, errno.h} |
a429d2ff | 195 | @errno{ECHILD, 10, No child processes} |
3e6def23 | 196 | This error happens on operations that are |
28f540f4 RM |
197 | supposed to manipulate child processes, when there aren't any processes |
198 | to manipulate. | |
199 | @end deftypevr | |
200 | ||
28f540f4 | 201 | @deftypevr Macro int EDEADLK |
d08a7e4c | 202 | @standards{POSIX.1, errno.h} |
a429d2ff | 203 | @errno{EDEADLK, 11, Resource deadlock avoided} |
3e6def23 | 204 | Allocating a system resource would have resulted in a |
28f540f4 RM |
205 | deadlock situation. The system does not guarantee that it will notice |
206 | all such situations. This error means you got lucky and the system | |
207 | noticed; it might just hang. @xref{File Locks}, for an example. | |
208 | @end deftypevr | |
209 | ||
28f540f4 | 210 | @deftypevr Macro int ENOMEM |
d08a7e4c | 211 | @standards{POSIX.1, errno.h} |
a429d2ff | 212 | @errno{ENOMEM, 12, Cannot allocate memory} |
3e6def23 | 213 | The system cannot allocate more virtual memory |
28f540f4 RM |
214 | because its capacity is full. |
215 | @end deftypevr | |
216 | ||
28f540f4 | 217 | @deftypevr Macro int EACCES |
d08a7e4c | 218 | @standards{POSIX.1, errno.h} |
a429d2ff | 219 | @errno{EACCES, 13, Permission denied} |
3e6def23 | 220 | The file permissions do not allow the attempted operation. |
28f540f4 RM |
221 | @end deftypevr |
222 | ||
28f540f4 | 223 | @deftypevr Macro int EFAULT |
d08a7e4c | 224 | @standards{POSIX.1, errno.h} |
a429d2ff | 225 | @errno{EFAULT, 14, Bad address} |
3e6def23 | 226 | An invalid pointer was detected. |
a7a93d50 | 227 | On @gnuhurdsystems{}, this error never happens; you get a signal instead. |
28f540f4 RM |
228 | @end deftypevr |
229 | ||
28f540f4 | 230 | @deftypevr Macro int ENOTBLK |
d08a7e4c | 231 | @standards{BSD, errno.h} |
a429d2ff | 232 | @errno{ENOTBLK, 15, Block device required} |
28f540f4 RM |
233 | A file that isn't a block special file was given in a situation that |
234 | requires one. For example, trying to mount an ordinary file as a file | |
235 | system in Unix gives this error. | |
236 | @end deftypevr | |
237 | ||
28f540f4 | 238 | @deftypevr Macro int EBUSY |
d08a7e4c | 239 | @standards{POSIX.1, errno.h} |
a429d2ff | 240 | @errno{EBUSY, 16, Device or resource busy} |
3e6def23 | 241 | A system resource that can't be shared is already in use. |
28f540f4 RM |
242 | For example, if you try to delete a file that is the root of a currently |
243 | mounted filesystem, you get this error. | |
244 | @end deftypevr | |
245 | ||
28f540f4 | 246 | @deftypevr Macro int EEXIST |
d08a7e4c | 247 | @standards{POSIX.1, errno.h} |
a429d2ff | 248 | @errno{EEXIST, 17, File exists} |
3e6def23 | 249 | An existing file was specified in a context where it only |
28f540f4 RM |
250 | makes sense to specify a new file. |
251 | @end deftypevr | |
252 | ||
28f540f4 | 253 | @deftypevr Macro int EXDEV |
d08a7e4c | 254 | @standards{POSIX.1, errno.h} |
a429d2ff | 255 | @errno{EXDEV, 18, Invalid cross-device link} |
28f540f4 RM |
256 | An attempt to make an improper link across file systems was detected. |
257 | This happens not only when you use @code{link} (@pxref{Hard Links}) but | |
258 | also when you rename a file with @code{rename} (@pxref{Renaming Files}). | |
259 | @end deftypevr | |
260 | ||
28f540f4 | 261 | @deftypevr Macro int ENODEV |
d08a7e4c | 262 | @standards{POSIX.1, errno.h} |
a429d2ff | 263 | @errno{ENODEV, 19, No such device} |
28f540f4 RM |
264 | The wrong type of device was given to a function that expects a |
265 | particular sort of device. | |
266 | @end deftypevr | |
267 | ||
28f540f4 | 268 | @deftypevr Macro int ENOTDIR |
d08a7e4c | 269 | @standards{POSIX.1, errno.h} |
a429d2ff | 270 | @errno{ENOTDIR, 20, Not a directory} |
28f540f4 RM |
271 | A file that isn't a directory was specified when a directory is required. |
272 | @end deftypevr | |
273 | ||
28f540f4 | 274 | @deftypevr Macro int EISDIR |
d08a7e4c | 275 | @standards{POSIX.1, errno.h} |
a429d2ff | 276 | @errno{EISDIR, 21, Is a directory} |
3e6def23 | 277 | You cannot open a directory for writing, |
28f540f4 RM |
278 | or create or remove hard links to it. |
279 | @end deftypevr | |
280 | ||
28f540f4 | 281 | @deftypevr Macro int EINVAL |
d08a7e4c | 282 | @standards{POSIX.1, errno.h} |
a429d2ff | 283 | @errno{EINVAL, 22, Invalid argument} |
3e6def23 | 284 | This is used to indicate various kinds of problems |
28f540f4 RM |
285 | with passing the wrong argument to a library function. |
286 | @end deftypevr | |
287 | ||
28f540f4 | 288 | @deftypevr Macro int EMFILE |
d08a7e4c | 289 | @standards{POSIX.1, errno.h} |
a429d2ff | 290 | @errno{EMFILE, 24, Too many open files} |
28f540f4 RM |
291 | The current process has too many files open and can't open any more. |
292 | Duplicate descriptors do count toward this limit. | |
293 | ||
294 | In BSD and GNU, the number of open files is controlled by a resource | |
295 | limit that can usually be increased. If you get this error, you might | |
296 | want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited; | |
297 | @pxref{Limits on Resources}. | |
298 | @end deftypevr | |
299 | ||
28f540f4 | 300 | @deftypevr Macro int ENFILE |
d08a7e4c | 301 | @standards{POSIX.1, errno.h} |
a429d2ff | 302 | @errno{ENFILE, 23, Too many open files in system} |
28f540f4 RM |
303 | There are too many distinct file openings in the entire system. Note |
304 | that any number of linked channels count as just one file opening; see | |
a7a93d50 | 305 | @ref{Linked Channels}. This error never occurs on @gnuhurdsystems{}. |
28f540f4 RM |
306 | @end deftypevr |
307 | ||
28f540f4 | 308 | @deftypevr Macro int ENOTTY |
d08a7e4c | 309 | @standards{POSIX.1, errno.h} |
a429d2ff | 310 | @errno{ENOTTY, 25, Inappropriate ioctl for device} |
28f540f4 RM |
311 | Inappropriate I/O control operation, such as trying to set terminal |
312 | modes on an ordinary file. | |
313 | @end deftypevr | |
314 | ||
28f540f4 | 315 | @deftypevr Macro int ETXTBSY |
d08a7e4c | 316 | @standards{BSD, errno.h} |
a429d2ff | 317 | @errno{ETXTBSY, 26, Text file busy} |
28f540f4 RM |
318 | An attempt to execute a file that is currently open for writing, or |
319 | write to a file that is currently being executed. Often using a | |
320 | debugger to run a program is considered having it open for writing and | |
321 | will cause this error. (The name stands for ``text file busy''.) This | |
a7a93d50 | 322 | is not an error on @gnuhurdsystems{}; the text is copied as necessary. |
28f540f4 RM |
323 | @end deftypevr |
324 | ||
28f540f4 | 325 | @deftypevr Macro int EFBIG |
d08a7e4c | 326 | @standards{POSIX.1, errno.h} |
a429d2ff | 327 | @errno{EFBIG, 27, File too large} |
3e6def23 | 328 | The size of a file would be larger than allowed by the system. |
28f540f4 RM |
329 | @end deftypevr |
330 | ||
28f540f4 | 331 | @deftypevr Macro int ENOSPC |
d08a7e4c | 332 | @standards{POSIX.1, errno.h} |
a429d2ff | 333 | @errno{ENOSPC, 28, No space left on device} |
3e6def23 | 334 | Write operation on a file failed because the |
28f540f4 RM |
335 | disk is full. |
336 | @end deftypevr | |
337 | ||
28f540f4 | 338 | @deftypevr Macro int ESPIPE |
d08a7e4c | 339 | @standards{POSIX.1, errno.h} |
a429d2ff | 340 | @errno{ESPIPE, 29, Illegal seek} |
28f540f4 RM |
341 | Invalid seek operation (such as on a pipe). |
342 | @end deftypevr | |
343 | ||
28f540f4 | 344 | @deftypevr Macro int EROFS |
d08a7e4c | 345 | @standards{POSIX.1, errno.h} |
a429d2ff | 346 | @errno{EROFS, 30, Read-only file system} |
28f540f4 RM |
347 | An attempt was made to modify something on a read-only file system. |
348 | @end deftypevr | |
349 | ||
28f540f4 | 350 | @deftypevr Macro int EMLINK |
d08a7e4c | 351 | @standards{POSIX.1, errno.h} |
a429d2ff | 352 | @errno{EMLINK, 31, Too many links} |
3e6def23 | 353 | The link count of a single file would become too large. |
28f540f4 RM |
354 | @code{rename} can cause this error if the file being renamed already has |
355 | as many links as it can take (@pxref{Renaming Files}). | |
356 | @end deftypevr | |
357 | ||
28f540f4 | 358 | @deftypevr Macro int EPIPE |
d08a7e4c | 359 | @standards{POSIX.1, errno.h} |
a429d2ff | 360 | @errno{EPIPE, 32, Broken pipe} |
3e6def23 | 361 | There is no process reading from the other end of a pipe. |
28f540f4 RM |
362 | Every library function that returns this error code also generates a |
363 | @code{SIGPIPE} signal; this signal terminates the program if not handled | |
364 | or blocked. Thus, your program will never actually see @code{EPIPE} | |
365 | unless it has handled or blocked @code{SIGPIPE}. | |
366 | @end deftypevr | |
367 | ||
28f540f4 | 368 | @deftypevr Macro int EDOM |
d08a7e4c | 369 | @standards{ISO, errno.h} |
a429d2ff | 370 | @errno{EDOM, 33, Numerical argument out of domain} |
3e6def23 | 371 | Used by mathematical functions when an argument value does |
28f540f4 RM |
372 | not fall into the domain over which the function is defined. |
373 | @end deftypevr | |
374 | ||
28f540f4 | 375 | @deftypevr Macro int ERANGE |
d08a7e4c | 376 | @standards{ISO, errno.h} |
a429d2ff | 377 | @errno{ERANGE, 34, Numerical result out of range} |
3e6def23 | 378 | Used by mathematical functions when the result value is |
28f540f4 RM |
379 | not representable because of overflow or underflow. |
380 | @end deftypevr | |
381 | ||
28f540f4 | 382 | @deftypevr Macro int EAGAIN |
d08a7e4c | 383 | @standards{POSIX.1, errno.h} |
a429d2ff | 384 | @errno{EAGAIN, 35, Resource temporarily unavailable} |
3e6def23 | 385 | The call might work if you try again |
28f540f4 | 386 | later. The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN}; |
1f77f049 | 387 | they are always the same in @theglibc{}. |
28f540f4 RM |
388 | |
389 | This error can happen in a few different situations: | |
390 | ||
391 | @itemize @bullet | |
392 | @item | |
393 | An operation that would block was attempted on an object that has | |
394 | non-blocking mode selected. Trying the same operation again will block | |
395 | until some external condition makes it possible to read, write, or | |
396 | connect (whatever the operation). You can use @code{select} to find out | |
397 | when the operation will be possible; @pxref{Waiting for I/O}. | |
398 | ||
55c14926 | 399 | @strong{Portability Note:} In many older Unix systems, this condition |
28f540f4 RM |
400 | was indicated by @code{EWOULDBLOCK}, which was a distinct error code |
401 | different from @code{EAGAIN}. To make your program portable, you should | |
402 | check for both codes and treat them the same. | |
403 | ||
404 | @item | |
405 | A temporary resource shortage made an operation impossible. @code{fork} | |
406 | can return this error. It indicates that the shortage is expected to | |
407 | pass, so your program can try the call again later and it may succeed. | |
408 | It is probably a good idea to delay for a few seconds before trying it | |
409 | again, to allow time for other processes to release scarce resources. | |
410 | Such shortages are usually fairly serious and affect the whole system, | |
411 | so usually an interactive program should report the error to the user | |
412 | and return to its command loop. | |
413 | @end itemize | |
414 | @end deftypevr | |
415 | ||
28f540f4 | 416 | @deftypevr Macro int EWOULDBLOCK |
d08a7e4c | 417 | @standards{BSD, errno.h} |
a429d2ff | 418 | @errno{EWOULDBLOCK, EAGAIN, Operation would block} |
1f77f049 | 419 | In @theglibc{}, this is another name for @code{EAGAIN} (above). |
28f540f4 RM |
420 | The values are always the same, on every operating system. |
421 | ||
422 | C libraries in many older Unix systems have @code{EWOULDBLOCK} as a | |
423 | separate error code. | |
424 | @end deftypevr | |
425 | ||
28f540f4 | 426 | @deftypevr Macro int EINPROGRESS |
d08a7e4c | 427 | @standards{BSD, errno.h} |
a429d2ff | 428 | @errno{EINPROGRESS, 36, Operation now in progress} |
28f540f4 RM |
429 | An operation that cannot complete immediately was initiated on an object |
430 | that has non-blocking mode selected. Some functions that must always | |
431 | block (such as @code{connect}; @pxref{Connecting}) never return | |
432 | @code{EAGAIN}. Instead, they return @code{EINPROGRESS} to indicate that | |
433 | the operation has begun and will take some time. Attempts to manipulate | |
434 | the object before the call completes return @code{EALREADY}. You can | |
435 | use the @code{select} function to find out when the pending operation | |
436 | has completed; @pxref{Waiting for I/O}. | |
437 | @end deftypevr | |
438 | ||
28f540f4 | 439 | @deftypevr Macro int EALREADY |
d08a7e4c | 440 | @standards{BSD, errno.h} |
a429d2ff | 441 | @errno{EALREADY, 37, Operation already in progress} |
28f540f4 RM |
442 | An operation is already in progress on an object that has non-blocking |
443 | mode selected. | |
444 | @end deftypevr | |
445 | ||
28f540f4 | 446 | @deftypevr Macro int ENOTSOCK |
d08a7e4c | 447 | @standards{BSD, errno.h} |
a429d2ff | 448 | @errno{ENOTSOCK, 38, Socket operation on non-socket} |
28f540f4 RM |
449 | A file that isn't a socket was specified when a socket is required. |
450 | @end deftypevr | |
451 | ||
28f540f4 | 452 | @deftypevr Macro int EMSGSIZE |
d08a7e4c | 453 | @standards{BSD, errno.h} |
a429d2ff | 454 | @errno{EMSGSIZE, 40, Message too long} |
28f540f4 | 455 | The size of a message sent on a socket was larger than the supported |
b8fe19fa | 456 | maximum size. |
28f540f4 RM |
457 | @end deftypevr |
458 | ||
28f540f4 | 459 | @deftypevr Macro int EPROTOTYPE |
d08a7e4c | 460 | @standards{BSD, errno.h} |
a429d2ff | 461 | @errno{EPROTOTYPE, 41, Protocol wrong type for socket} |
28f540f4 RM |
462 | The socket type does not support the requested communications protocol. |
463 | @end deftypevr | |
464 | ||
28f540f4 | 465 | @deftypevr Macro int ENOPROTOOPT |
d08a7e4c | 466 | @standards{BSD, errno.h} |
a429d2ff | 467 | @errno{ENOPROTOOPT, 42, Protocol not available} |
28f540f4 RM |
468 | You specified a socket option that doesn't make sense for the |
469 | particular protocol being used by the socket. @xref{Socket Options}. | |
470 | @end deftypevr | |
471 | ||
28f540f4 | 472 | @deftypevr Macro int EPROTONOSUPPORT |
d08a7e4c | 473 | @standards{BSD, errno.h} |
a429d2ff | 474 | @errno{EPROTONOSUPPORT, 43, Protocol not supported} |
28f540f4 | 475 | The socket domain does not support the requested communications protocol |
7ba4fcfc | 476 | (perhaps because the requested protocol is completely invalid). |
28f540f4 RM |
477 | @xref{Creating a Socket}. |
478 | @end deftypevr | |
479 | ||
28f540f4 | 480 | @deftypevr Macro int ESOCKTNOSUPPORT |
d08a7e4c | 481 | @standards{BSD, errno.h} |
a429d2ff | 482 | @errno{ESOCKTNOSUPPORT, 44, Socket type not supported} |
28f540f4 RM |
483 | The socket type is not supported. |
484 | @end deftypevr | |
485 | ||
28f540f4 | 486 | @deftypevr Macro int EOPNOTSUPP |
d08a7e4c | 487 | @standards{BSD, errno.h} |
a429d2ff | 488 | @errno{EOPNOTSUPP, 45, Operation not supported} |
28f540f4 RM |
489 | The operation you requested is not supported. Some socket functions |
490 | don't make sense for all types of sockets, and others may not be | |
a7a93d50 | 491 | implemented for all communications protocols. On @gnuhurdsystems{}, this |
28f540f4 RM |
492 | error can happen for many calls when the object does not support the |
493 | particular operation; it is a generic indication that the server knows | |
494 | nothing to do for that call. | |
495 | @end deftypevr | |
496 | ||
28f540f4 | 497 | @deftypevr Macro int EPFNOSUPPORT |
d08a7e4c | 498 | @standards{BSD, errno.h} |
a429d2ff | 499 | @errno{EPFNOSUPPORT, 46, Protocol family not supported} |
28f540f4 RM |
500 | The socket communications protocol family you requested is not supported. |
501 | @end deftypevr | |
502 | ||
28f540f4 | 503 | @deftypevr Macro int EAFNOSUPPORT |
d08a7e4c | 504 | @standards{BSD, errno.h} |
a429d2ff | 505 | @errno{EAFNOSUPPORT, 47, Address family not supported by protocol} |
28f540f4 RM |
506 | The address family specified for a socket is not supported; it is |
507 | inconsistent with the protocol being used on the socket. @xref{Sockets}. | |
508 | @end deftypevr | |
509 | ||
28f540f4 | 510 | @deftypevr Macro int EADDRINUSE |
d08a7e4c | 511 | @standards{BSD, errno.h} |
a429d2ff | 512 | @errno{EADDRINUSE, 48, Address already in use} |
28f540f4 RM |
513 | The requested socket address is already in use. @xref{Socket Addresses}. |
514 | @end deftypevr | |
515 | ||
28f540f4 | 516 | @deftypevr Macro int EADDRNOTAVAIL |
d08a7e4c | 517 | @standards{BSD, errno.h} |
a429d2ff | 518 | @errno{EADDRNOTAVAIL, 49, Cannot assign requested address} |
28f540f4 RM |
519 | The requested socket address is not available; for example, you tried |
520 | to give a socket a name that doesn't match the local host name. | |
521 | @xref{Socket Addresses}. | |
522 | @end deftypevr | |
523 | ||
28f540f4 | 524 | @deftypevr Macro int ENETDOWN |
d08a7e4c | 525 | @standards{BSD, errno.h} |
a429d2ff | 526 | @errno{ENETDOWN, 50, Network is down} |
28f540f4 RM |
527 | A socket operation failed because the network was down. |
528 | @end deftypevr | |
529 | ||
28f540f4 | 530 | @deftypevr Macro int ENETUNREACH |
d08a7e4c | 531 | @standards{BSD, errno.h} |
a429d2ff | 532 | @errno{ENETUNREACH, 51, Network is unreachable} |
28f540f4 RM |
533 | A socket operation failed because the subnet containing the remote host |
534 | was unreachable. | |
535 | @end deftypevr | |
536 | ||
28f540f4 | 537 | @deftypevr Macro int ENETRESET |
d08a7e4c | 538 | @standards{BSD, errno.h} |
a429d2ff | 539 | @errno{ENETRESET, 52, Network dropped connection on reset} |
28f540f4 RM |
540 | A network connection was reset because the remote host crashed. |
541 | @end deftypevr | |
542 | ||
28f540f4 | 543 | @deftypevr Macro int ECONNABORTED |
d08a7e4c | 544 | @standards{BSD, errno.h} |
a429d2ff | 545 | @errno{ECONNABORTED, 53, Software caused connection abort} |
28f540f4 RM |
546 | A network connection was aborted locally. |
547 | @end deftypevr | |
548 | ||
28f540f4 | 549 | @deftypevr Macro int ECONNRESET |
d08a7e4c | 550 | @standards{BSD, errno.h} |
a429d2ff | 551 | @errno{ECONNRESET, 54, Connection reset by peer} |
28f540f4 RM |
552 | A network connection was closed for reasons outside the control of the |
553 | local host, such as by the remote machine rebooting or an unrecoverable | |
554 | protocol violation. | |
555 | @end deftypevr | |
556 | ||
28f540f4 | 557 | @deftypevr Macro int ENOBUFS |
d08a7e4c | 558 | @standards{BSD, errno.h} |
a429d2ff | 559 | @errno{ENOBUFS, 55, No buffer space available} |
28f540f4 RM |
560 | The kernel's buffers for I/O operations are all in use. In GNU, this |
561 | error is always synonymous with @code{ENOMEM}; you may get one or the | |
562 | other from network operations. | |
563 | @end deftypevr | |
564 | ||
28f540f4 | 565 | @deftypevr Macro int EISCONN |
d08a7e4c | 566 | @standards{BSD, errno.h} |
a429d2ff | 567 | @errno{EISCONN, 56, Transport endpoint is already connected} |
28f540f4 RM |
568 | You tried to connect a socket that is already connected. |
569 | @xref{Connecting}. | |
570 | @end deftypevr | |
571 | ||
28f540f4 | 572 | @deftypevr Macro int ENOTCONN |
d08a7e4c | 573 | @standards{BSD, errno.h} |
a429d2ff | 574 | @errno{ENOTCONN, 57, Transport endpoint is not connected} |
28f540f4 RM |
575 | The socket is not connected to anything. You get this error when you |
576 | try to transmit data over a socket, without first specifying a | |
577 | destination for the data. For a connectionless socket (for datagram | |
578 | protocols, such as UDP), you get @code{EDESTADDRREQ} instead. | |
579 | @end deftypevr | |
580 | ||
28f540f4 | 581 | @deftypevr Macro int EDESTADDRREQ |
d08a7e4c | 582 | @standards{BSD, errno.h} |
a429d2ff | 583 | @errno{EDESTADDRREQ, 39, Destination address required} |
28f540f4 RM |
584 | No default destination address was set for the socket. You get this |
585 | error when you try to transmit data over a connectionless socket, | |
586 | without first specifying a destination for the data with @code{connect}. | |
587 | @end deftypevr | |
588 | ||
28f540f4 | 589 | @deftypevr Macro int ESHUTDOWN |
d08a7e4c | 590 | @standards{BSD, errno.h} |
a429d2ff | 591 | @errno{ESHUTDOWN, 58, Cannot send after transport endpoint shutdown} |
28f540f4 RM |
592 | The socket has already been shut down. |
593 | @end deftypevr | |
594 | ||
28f540f4 | 595 | @deftypevr Macro int ETOOMANYREFS |
d08a7e4c | 596 | @standards{BSD, errno.h} |
a429d2ff | 597 | @errno{ETOOMANYREFS, 59, Too many references: cannot splice} |
28f540f4 RM |
598 | @end deftypevr |
599 | ||
28f540f4 | 600 | @deftypevr Macro int ETIMEDOUT |
d08a7e4c | 601 | @standards{BSD, errno.h} |
a429d2ff | 602 | @errno{ETIMEDOUT, 60, Connection timed out} |
28f540f4 RM |
603 | A socket operation with a specified timeout received no response during |
604 | the timeout period. | |
605 | @end deftypevr | |
606 | ||
28f540f4 | 607 | @deftypevr Macro int ECONNREFUSED |
d08a7e4c | 608 | @standards{BSD, errno.h} |
a429d2ff | 609 | @errno{ECONNREFUSED, 61, Connection refused} |
28f540f4 RM |
610 | A remote host refused to allow the network connection (typically because |
611 | it is not running the requested service). | |
612 | @end deftypevr | |
613 | ||
28f540f4 | 614 | @deftypevr Macro int ELOOP |
d08a7e4c | 615 | @standards{BSD, errno.h} |
a429d2ff | 616 | @errno{ELOOP, 62, Too many levels of symbolic links} |
28f540f4 RM |
617 | Too many levels of symbolic links were encountered in looking up a file name. |
618 | This often indicates a cycle of symbolic links. | |
619 | @end deftypevr | |
620 | ||
28f540f4 | 621 | @deftypevr Macro int ENAMETOOLONG |
d08a7e4c | 622 | @standards{POSIX.1, errno.h} |
a429d2ff | 623 | @errno{ENAMETOOLONG, 63, File name too long} |
28f540f4 RM |
624 | Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for |
625 | Files}) or host name too long (in @code{gethostname} or | |
626 | @code{sethostname}; @pxref{Host Identification}). | |
627 | @end deftypevr | |
628 | ||
28f540f4 | 629 | @deftypevr Macro int EHOSTDOWN |
d08a7e4c | 630 | @standards{BSD, errno.h} |
a429d2ff | 631 | @errno{EHOSTDOWN, 64, Host is down} |
28f540f4 RM |
632 | The remote host for a requested network connection is down. |
633 | @end deftypevr | |
634 | ||
28f540f4 | 635 | @deftypevr Macro int EHOSTUNREACH |
d08a7e4c | 636 | @standards{BSD, errno.h} |
a429d2ff | 637 | @errno{EHOSTUNREACH, 65, No route to host} |
28f540f4 RM |
638 | The remote host for a requested network connection is not reachable. |
639 | @end deftypevr | |
640 | ||
28f540f4 | 641 | @deftypevr Macro int ENOTEMPTY |
d08a7e4c | 642 | @standards{POSIX.1, errno.h} |
a429d2ff | 643 | @errno{ENOTEMPTY, 66, Directory not empty} |
28f540f4 RM |
644 | Directory not empty, where an empty directory was expected. Typically, |
645 | this error occurs when you are trying to delete a directory. | |
646 | @end deftypevr | |
647 | ||
28f540f4 | 648 | @deftypevr Macro int EPROCLIM |
d08a7e4c | 649 | @standards{BSD, errno.h} |
a429d2ff | 650 | @errno{EPROCLIM, 67, Too many processes} |
28f540f4 RM |
651 | This means that the per-user limit on new process would be exceeded by |
652 | an attempted @code{fork}. @xref{Limits on Resources}, for details on | |
653 | the @code{RLIMIT_NPROC} limit. | |
654 | @end deftypevr | |
655 | ||
28f540f4 | 656 | @deftypevr Macro int EUSERS |
d08a7e4c | 657 | @standards{BSD, errno.h} |
a429d2ff | 658 | @errno{EUSERS, 68, Too many users} |
28f540f4 RM |
659 | The file quota system is confused because there are too many users. |
660 | @c This can probably happen in a GNU system when using NFS. | |
661 | @end deftypevr | |
662 | ||
28f540f4 | 663 | @deftypevr Macro int EDQUOT |
d08a7e4c | 664 | @standards{BSD, errno.h} |
a429d2ff | 665 | @errno{EDQUOT, 69, Disk quota exceeded} |
28f540f4 RM |
666 | The user's disk quota was exceeded. |
667 | @end deftypevr | |
668 | ||
28f540f4 | 669 | @deftypevr Macro int ESTALE |
d08a7e4c | 670 | @standards{BSD, errno.h} |
a429d2ff | 671 | @errno{ESTALE, 70, Stale file handle} |
3e6def23 | 672 | This indicates an internal confusion in the |
96945714 JL |
673 | file system which is due to file system rearrangements on the server host |
674 | for NFS file systems or corruption in other file systems. | |
675 | Repairing this condition usually requires unmounting, possibly repairing | |
676 | and remounting the file system. | |
28f540f4 RM |
677 | @end deftypevr |
678 | ||
28f540f4 | 679 | @deftypevr Macro int EREMOTE |
d08a7e4c | 680 | @standards{BSD, errno.h} |
a429d2ff | 681 | @errno{EREMOTE, 71, Object is remote} |
28f540f4 RM |
682 | An attempt was made to NFS-mount a remote file system with a file name that |
683 | already specifies an NFS-mounted file. | |
684 | (This is an error on some operating systems, but we expect it to work | |
a7a93d50 | 685 | properly on @gnuhurdsystems{}, making this error code impossible.) |
28f540f4 RM |
686 | @end deftypevr |
687 | ||
28f540f4 | 688 | @deftypevr Macro int EBADRPC |
d08a7e4c | 689 | @standards{BSD, errno.h} |
a429d2ff | 690 | @errno{EBADRPC, 72, RPC struct is bad} |
28f540f4 RM |
691 | @end deftypevr |
692 | ||
28f540f4 | 693 | @deftypevr Macro int ERPCMISMATCH |
d08a7e4c | 694 | @standards{BSD, errno.h} |
a429d2ff | 695 | @errno{ERPCMISMATCH, 73, RPC version wrong} |
28f540f4 RM |
696 | @end deftypevr |
697 | ||
28f540f4 | 698 | @deftypevr Macro int EPROGUNAVAIL |
d08a7e4c | 699 | @standards{BSD, errno.h} |
a429d2ff | 700 | @errno{EPROGUNAVAIL, 74, RPC program not available} |
28f540f4 RM |
701 | @end deftypevr |
702 | ||
28f540f4 | 703 | @deftypevr Macro int EPROGMISMATCH |
d08a7e4c | 704 | @standards{BSD, errno.h} |
a429d2ff | 705 | @errno{EPROGMISMATCH, 75, RPC program version wrong} |
28f540f4 RM |
706 | @end deftypevr |
707 | ||
28f540f4 | 708 | @deftypevr Macro int EPROCUNAVAIL |
d08a7e4c | 709 | @standards{BSD, errno.h} |
a429d2ff | 710 | @errno{EPROCUNAVAIL, 76, RPC bad procedure for program} |
28f540f4 RM |
711 | @end deftypevr |
712 | ||
28f540f4 | 713 | @deftypevr Macro int ENOLCK |
d08a7e4c | 714 | @standards{POSIX.1, errno.h} |
a429d2ff | 715 | @errno{ENOLCK, 77, No locks available} |
3e6def23 | 716 | This is used by the file locking facilities; see |
a7a93d50 | 717 | @ref{File Locks}. This error is never generated by @gnuhurdsystems{}, but |
28f540f4 RM |
718 | it can result from an operation to an NFS server running another |
719 | operating system. | |
720 | @end deftypevr | |
721 | ||
28f540f4 | 722 | @deftypevr Macro int EFTYPE |
d08a7e4c | 723 | @standards{BSD, errno.h} |
a429d2ff | 724 | @errno{EFTYPE, 79, Inappropriate file type or format} |
3e6def23 | 725 | The file was the wrong type for the |
28f540f4 RM |
726 | operation, or a data file had the wrong format. |
727 | ||
728 | On some systems @code{chmod} returns this error if you try to set the | |
729 | sticky bit on a non-directory file; @pxref{Setting Permissions}. | |
730 | @end deftypevr | |
731 | ||
28f540f4 | 732 | @deftypevr Macro int EAUTH |
d08a7e4c | 733 | @standards{BSD, errno.h} |
a429d2ff | 734 | @errno{EAUTH, 80, Authentication error} |
28f540f4 RM |
735 | @end deftypevr |
736 | ||
28f540f4 | 737 | @deftypevr Macro int ENEEDAUTH |
d08a7e4c | 738 | @standards{BSD, errno.h} |
a429d2ff | 739 | @errno{ENEEDAUTH, 81, Need authenticator} |
28f540f4 RM |
740 | @end deftypevr |
741 | ||
28f540f4 | 742 | @deftypevr Macro int ENOSYS |
d08a7e4c | 743 | @standards{POSIX.1, errno.h} |
a429d2ff | 744 | @errno{ENOSYS, 78, Function not implemented} |
3e6def23 | 745 | This indicates that the function called is |
75d0cab2 RM |
746 | not implemented at all, either in the C library itself or in the |
747 | operating system. When you get this error, you can be sure that this | |
748 | particular function will always fail with @code{ENOSYS} unless you | |
749 | install a new version of the C library or the operating system. | |
750 | @end deftypevr | |
751 | ||
45a8e057 ST |
752 | @deftypevr Macro int ELIBEXEC |
753 | @standards{GNU, errno.h} | |
754 | @errno{ELIBEXEC, 83, Cannot exec a shared library directly} | |
755 | @end deftypevr | |
756 | ||
75d0cab2 | 757 | @deftypevr Macro int ENOTSUP |
d08a7e4c | 758 | @standards{POSIX.1, errno.h} |
a429d2ff | 759 | @errno{ENOTSUP, 118, Not supported} |
3e6def23 | 760 | A function returns this error when certain parameter |
75d0cab2 RM |
761 | values are valid, but the functionality they request is not available. |
762 | This can mean that the function does not implement a particular command | |
763 | or option value or flag bit at all. For functions that operate on some | |
764 | object given in a parameter, such as a file descriptor or a port, it | |
765 | might instead mean that only @emph{that specific object} (file | |
766 | descriptor, port, etc.) is unable to support the other parameters given; | |
767 | different file descriptors might support different ranges of parameter | |
768 | values. | |
769 | ||
770 | If the entire function is not available at all in the implementation, | |
771 | it returns @code{ENOSYS} instead. | |
28f540f4 RM |
772 | @end deftypevr |
773 | ||
b8fe19fa | 774 | @deftypevr Macro int EILSEQ |
d08a7e4c | 775 | @standards{ISO, errno.h} |
a429d2ff | 776 | @errno{EILSEQ, 106, Invalid or incomplete multibyte or wide character} |
b8fe19fa RM |
777 | While decoding a multibyte character the function came along an invalid |
778 | or an incomplete sequence of bytes or the given wide character is invalid. | |
779 | @end deftypevr | |
780 | ||
28f540f4 | 781 | @deftypevr Macro int EBACKGROUND |
d08a7e4c | 782 | @standards{GNU, errno.h} |
a429d2ff | 783 | @errno{EBACKGROUND, 100, Inappropriate operation for background process} |
a7a93d50 | 784 | On @gnuhurdsystems{}, servers supporting the @code{term} protocol return |
28f540f4 RM |
785 | this error for certain operations when the caller is not in the |
786 | foreground process group of the terminal. Users do not usually see this | |
787 | error because functions such as @code{read} and @code{write} translate | |
788 | it into a @code{SIGTTIN} or @code{SIGTTOU} signal. @xref{Job Control}, | |
789 | for information on process groups and these signals. | |
790 | @end deftypevr | |
791 | ||
28f540f4 | 792 | @deftypevr Macro int EDIED |
d08a7e4c | 793 | @standards{GNU, errno.h} |
a429d2ff | 794 | @errno{EDIED, 101, Translator died} |
a7a93d50 | 795 | On @gnuhurdsystems{}, opening a file returns this error when the file is |
28f540f4 RM |
796 | translated by a program and the translator program dies while starting |
797 | up, before it has connected to the file. | |
798 | @end deftypevr | |
799 | ||
28f540f4 | 800 | @deftypevr Macro int ED |
d08a7e4c | 801 | @standards{GNU, errno.h} |
a429d2ff | 802 | @errno{ED, 102, ?} |
28f540f4 | 803 | The experienced user will know what is wrong. |
a78b0f18 RM |
804 | @c This error code is a joke. Its perror text is part of the joke. |
805 | @c Don't change it. | |
28f540f4 RM |
806 | @end deftypevr |
807 | ||
28f540f4 | 808 | @deftypevr Macro int EGREGIOUS |
d08a7e4c | 809 | @standards{GNU, errno.h} |
a429d2ff | 810 | @errno{EGREGIOUS, 103, You really blew it this time} |
28f540f4 RM |
811 | You did @strong{what}? |
812 | @end deftypevr | |
813 | ||
28f540f4 | 814 | @deftypevr Macro int EIEIO |
d08a7e4c | 815 | @standards{GNU, errno.h} |
a429d2ff | 816 | @errno{EIEIO, 104, Computer bought the farm} |
28f540f4 | 817 | Go home and have a glass of warm, dairy-fresh milk. |
a67377e7 ST |
818 | @c Okay. Since you are dying to know, I'll tell you. |
819 | @c This is a joke, obviously. There is a children's song which begins, | |
820 | @c "Old McDonald had a farm, e-i-e-i-o." Every time I see the (real) | |
821 | @c errno macro EIO, I think about that song. Probably most of my | |
822 | @c compatriots who program on Unix do, too. One of them must have stayed | |
823 | @c up a little too late one night and decided to add it to Hurd or Glibc. | |
824 | @c Whoever did it should be castigated, but it made me laugh. | |
825 | @c --jtobey@channel1.com | |
826 | @c | |
827 | @c "bought the farm" means "died". -jtobey | |
828 | @c | |
829 | @c Translators, please do not translate this litteraly, translate it into | |
830 | @c an idiomatic funny way of saying that the computer died. | |
28f540f4 RM |
831 | @end deftypevr |
832 | ||
28f540f4 | 833 | @deftypevr Macro int EGRATUITOUS |
d08a7e4c | 834 | @standards{GNU, errno.h} |
a429d2ff | 835 | @errno{EGRATUITOUS, 105, Gratuitous error} |
28f540f4 RM |
836 | This error code has no purpose. |
837 | @end deftypevr | |
838 | ||
ebe3b3eb | 839 | @deftypevr Macro int EBADMSG |
d08a7e4c | 840 | @standards{XOPEN, errno.h} |
a429d2ff | 841 | @errno{EBADMSG, 107, Bad message} |
ebe3b3eb | 842 | @end deftypevr |
b25ae9c6 | 843 | |
ebe3b3eb | 844 | @deftypevr Macro int EIDRM |
d08a7e4c | 845 | @standards{XOPEN, errno.h} |
a429d2ff | 846 | @errno{EIDRM, 108, Identifier removed} |
ebe3b3eb TBB |
847 | @end deftypevr |
848 | ||
ebe3b3eb | 849 | @deftypevr Macro int EMULTIHOP |
d08a7e4c | 850 | @standards{XOPEN, errno.h} |
a429d2ff | 851 | @errno{EMULTIHOP, 109, Multihop attempted} |
ebe3b3eb TBB |
852 | @end deftypevr |
853 | ||
ebe3b3eb | 854 | @deftypevr Macro int ENODATA |
d08a7e4c | 855 | @standards{XOPEN, errno.h} |
a429d2ff | 856 | @errno{ENODATA, 110, No data available} |
b25ae9c6 RM |
857 | @end deftypevr |
858 | ||
ebe3b3eb | 859 | @deftypevr Macro int ENOLINK |
d08a7e4c | 860 | @standards{XOPEN, errno.h} |
a429d2ff | 861 | @errno{ENOLINK, 111, Link has been severed} |
ebe3b3eb TBB |
862 | @end deftypevr |
863 | ||
b25ae9c6 | 864 | @deftypevr Macro int ENOMSG |
d08a7e4c | 865 | @standards{XOPEN, errno.h} |
a429d2ff | 866 | @errno{ENOMSG, 112, No message of desired type} |
b25ae9c6 RM |
867 | @end deftypevr |
868 | ||
ebe3b3eb | 869 | @deftypevr Macro int ENOSR |
d08a7e4c | 870 | @standards{XOPEN, errno.h} |
a429d2ff | 871 | @errno{ENOSR, 113, Out of streams resources} |
ebe3b3eb TBB |
872 | @end deftypevr |
873 | ||
ebe3b3eb | 874 | @deftypevr Macro int ENOSTR |
d08a7e4c | 875 | @standards{XOPEN, errno.h} |
a429d2ff | 876 | @errno{ENOSTR, 114, Device not a stream} |
ebe3b3eb TBB |
877 | @end deftypevr |
878 | ||
ebe3b3eb | 879 | @deftypevr Macro int EOVERFLOW |
d08a7e4c | 880 | @standards{XOPEN, errno.h} |
a429d2ff | 881 | @errno{EOVERFLOW, 115, Value too large for defined data type} |
ebe3b3eb TBB |
882 | @end deftypevr |
883 | ||
ebe3b3eb | 884 | @deftypevr Macro int EPROTO |
d08a7e4c | 885 | @standards{XOPEN, errno.h} |
a429d2ff | 886 | @errno{EPROTO, 116, Protocol error} |
ebe3b3eb TBB |
887 | @end deftypevr |
888 | ||
ebe3b3eb | 889 | @deftypevr Macro int ETIME |
d08a7e4c | 890 | @standards{XOPEN, errno.h} |
a429d2ff | 891 | @errno{ETIME, 117, Timer expired} |
ebe3b3eb TBB |
892 | @end deftypevr |
893 | ||
b88ac073 | 894 | @deftypevr Macro int ECANCELED |
d08a7e4c | 895 | @standards{POSIX.1, errno.h} |
a429d2ff | 896 | @errno{ECANCELED, 119, Operation canceled} |
3e6def23 | 897 | An asynchronous operation was canceled before it |
b88ac073 RM |
898 | completed. @xref{Asynchronous I/O}. When you call @code{aio_cancel}, |
899 | the normal result is for the operations affected to complete with this | |
900 | error; @pxref{Cancel AIO Operations}. | |
901 | @end deftypevr | |
902 | ||
fb4cc8a0 AA |
903 | @deftypevr Macro int EOWNERDEAD |
904 | @standards{GNU, errno.h} | |
905 | @errno{EOWNERDEAD, 120, Owner died} | |
906 | @end deftypevr | |
907 | ||
908 | @deftypevr Macro int ENOTRECOVERABLE | |
909 | @standards{GNU, errno.h} | |
910 | @errno{ENOTRECOVERABLE, 121, State not recoverable} | |
911 | @end deftypevr | |
912 | ||
ebe3b3eb TBB |
913 | |
914 | @emph{The following error codes are defined by the Linux/i386 kernel. | |
915 | They are not yet documented.} | |
916 | ||
ebe3b3eb | 917 | @deftypevr Macro int ERESTART |
d08a7e4c | 918 | @standards{Linux???, errno.h} |
a429d2ff | 919 | @errno{ERESTART, ???/85, Interrupted system call should be restarted} |
b25ae9c6 RM |
920 | @end deftypevr |
921 | ||
b25ae9c6 | 922 | @deftypevr Macro int ECHRNG |
d08a7e4c | 923 | @standards{Linux???, errno.h} |
a429d2ff | 924 | @errno{ECHRNG, ???/44, Channel number out of range} |
b25ae9c6 RM |
925 | @end deftypevr |
926 | ||
b25ae9c6 | 927 | @deftypevr Macro int EL2NSYNC |
d08a7e4c | 928 | @standards{Obsolete, errno.h} |
a429d2ff | 929 | @errno{EL2NSYNC, ???/45, Level 2 not synchronized} |
b25ae9c6 RM |
930 | @end deftypevr |
931 | ||
b25ae9c6 | 932 | @deftypevr Macro int EL3HLT |
d08a7e4c | 933 | @standards{Obsolete, errno.h} |
a429d2ff | 934 | @errno{EL3HLT, ???/46, Level 3 halted} |
b25ae9c6 RM |
935 | @end deftypevr |
936 | ||
b25ae9c6 | 937 | @deftypevr Macro int EL3RST |
d08a7e4c | 938 | @standards{Obsolete, errno.h} |
a429d2ff | 939 | @errno{EL3RST, ???/47, Level 3 reset} |
b25ae9c6 RM |
940 | @end deftypevr |
941 | ||
b25ae9c6 | 942 | @deftypevr Macro int ELNRNG |
d08a7e4c | 943 | @standards{Linux???, errno.h} |
a429d2ff | 944 | @errno{ELNRNG, ???/48, Link number out of range} |
b25ae9c6 RM |
945 | @end deftypevr |
946 | ||
b25ae9c6 | 947 | @deftypevr Macro int EUNATCH |
d08a7e4c | 948 | @standards{Linux???, errno.h} |
a429d2ff | 949 | @errno{EUNATCH, ???/49, Protocol driver not attached} |
b25ae9c6 RM |
950 | @end deftypevr |
951 | ||
b25ae9c6 | 952 | @deftypevr Macro int ENOCSI |
d08a7e4c | 953 | @standards{Linux???, errno.h} |
a429d2ff | 954 | @errno{ENOCSI, ???/50, No CSI structure available} |
b25ae9c6 RM |
955 | @end deftypevr |
956 | ||
b25ae9c6 | 957 | @deftypevr Macro int EL2HLT |
d08a7e4c | 958 | @standards{Obsolete, errno.h} |
a429d2ff | 959 | @errno{EL2HLT, ???/51, Level 2 halted} |
b25ae9c6 RM |
960 | @end deftypevr |
961 | ||
b25ae9c6 | 962 | @deftypevr Macro int EBADE |
d08a7e4c | 963 | @standards{Linux???, errno.h} |
a429d2ff | 964 | @errno{EBADE, ???/52, Invalid exchange} |
b25ae9c6 RM |
965 | @end deftypevr |
966 | ||
b25ae9c6 | 967 | @deftypevr Macro int EBADR |
d08a7e4c | 968 | @standards{Linux???, errno.h} |
a429d2ff | 969 | @errno{EBADR, ???/53, Invalid request descriptor} |
b25ae9c6 RM |
970 | @end deftypevr |
971 | ||
b25ae9c6 | 972 | @deftypevr Macro int EXFULL |
d08a7e4c | 973 | @standards{Linux???, errno.h} |
a429d2ff | 974 | @errno{EXFULL, ???/54, Exchange full} |
b25ae9c6 RM |
975 | @end deftypevr |
976 | ||
b25ae9c6 | 977 | @deftypevr Macro int ENOANO |
d08a7e4c | 978 | @standards{Linux???, errno.h} |
a429d2ff | 979 | @errno{ENOANO, ???/55, No anode} |
b25ae9c6 RM |
980 | @end deftypevr |
981 | ||
b25ae9c6 | 982 | @deftypevr Macro int EBADRQC |
d08a7e4c | 983 | @standards{Linux???, errno.h} |
a429d2ff | 984 | @errno{EBADRQC, ???/56, Invalid request code} |
b25ae9c6 RM |
985 | @end deftypevr |
986 | ||
b25ae9c6 | 987 | @deftypevr Macro int EBADSLT |
d08a7e4c | 988 | @standards{Linux???, errno.h} |
a429d2ff | 989 | @errno{EBADSLT, ???/57, Invalid slot} |
b25ae9c6 RM |
990 | @end deftypevr |
991 | ||
b25ae9c6 | 992 | @deftypevr Macro int EDEADLOCK |
d08a7e4c | 993 | @standards{Linux???, errno.h} |
a429d2ff | 994 | @errno{EDEADLOCK, ???/58, File locking deadlock error} |
b25ae9c6 RM |
995 | @end deftypevr |
996 | ||
b25ae9c6 | 997 | @deftypevr Macro int EBFONT |
d08a7e4c | 998 | @standards{Linux???, errno.h} |
a429d2ff | 999 | @errno{EBFONT, ???/59, Bad font file format} |
b25ae9c6 RM |
1000 | @end deftypevr |
1001 | ||
b25ae9c6 | 1002 | @deftypevr Macro int ENONET |
d08a7e4c | 1003 | @standards{Linux???, errno.h} |
a429d2ff | 1004 | @errno{ENONET, ???/64, Machine is not on the network} |
b25ae9c6 RM |
1005 | @end deftypevr |
1006 | ||
b25ae9c6 | 1007 | @deftypevr Macro int ENOPKG |
d08a7e4c | 1008 | @standards{Linux???, errno.h} |
a429d2ff | 1009 | @errno{ENOPKG, ???/65, Package not installed} |
b25ae9c6 RM |
1010 | @end deftypevr |
1011 | ||
b25ae9c6 | 1012 | @deftypevr Macro int EADV |
d08a7e4c | 1013 | @standards{Linux???, errno.h} |
a429d2ff | 1014 | @errno{EADV, ???/68, Advertise error} |
b25ae9c6 RM |
1015 | @end deftypevr |
1016 | ||
b25ae9c6 | 1017 | @deftypevr Macro int ESRMNT |
d08a7e4c | 1018 | @standards{Linux???, errno.h} |
a429d2ff | 1019 | @errno{ESRMNT, ???/69, Srmount error} |
b25ae9c6 RM |
1020 | @end deftypevr |
1021 | ||
b25ae9c6 | 1022 | @deftypevr Macro int ECOMM |
d08a7e4c | 1023 | @standards{Linux???, errno.h} |
a429d2ff | 1024 | @errno{ECOMM, ???/70, Communication error on send} |
b25ae9c6 RM |
1025 | @end deftypevr |
1026 | ||
b25ae9c6 | 1027 | @deftypevr Macro int EDOTDOT |
d08a7e4c | 1028 | @standards{Linux???, errno.h} |
a429d2ff | 1029 | @errno{EDOTDOT, ???/73, RFS specific error} |
b25ae9c6 RM |
1030 | @end deftypevr |
1031 | ||
b25ae9c6 | 1032 | @deftypevr Macro int ENOTUNIQ |
d08a7e4c | 1033 | @standards{Linux???, errno.h} |
a429d2ff | 1034 | @errno{ENOTUNIQ, ???/76, Name not unique on network} |
b25ae9c6 RM |
1035 | @end deftypevr |
1036 | ||
b25ae9c6 | 1037 | @deftypevr Macro int EBADFD |
d08a7e4c | 1038 | @standards{Linux???, errno.h} |
a429d2ff | 1039 | @errno{EBADFD, ???/77, File descriptor in bad state} |
b25ae9c6 RM |
1040 | @end deftypevr |
1041 | ||
b25ae9c6 | 1042 | @deftypevr Macro int EREMCHG |
d08a7e4c | 1043 | @standards{Linux???, errno.h} |
a429d2ff | 1044 | @errno{EREMCHG, ???/78, Remote address changed} |
b25ae9c6 RM |
1045 | @end deftypevr |
1046 | ||
b25ae9c6 | 1047 | @deftypevr Macro int ELIBACC |
d08a7e4c | 1048 | @standards{Linux???, errno.h} |
a429d2ff | 1049 | @errno{ELIBACC, ???/79, Can not access a needed shared library} |
b25ae9c6 RM |
1050 | @end deftypevr |
1051 | ||
b25ae9c6 | 1052 | @deftypevr Macro int ELIBBAD |
d08a7e4c | 1053 | @standards{Linux???, errno.h} |
a429d2ff | 1054 | @errno{ELIBBAD, ???/80, Accessing a corrupted shared library} |
b25ae9c6 RM |
1055 | @end deftypevr |
1056 | ||
b25ae9c6 | 1057 | @deftypevr Macro int ELIBSCN |
d08a7e4c | 1058 | @standards{Linux???, errno.h} |
a429d2ff | 1059 | @errno{ELIBSCN, ???/81, .lib section in a.out corrupted} |
b25ae9c6 RM |
1060 | @end deftypevr |
1061 | ||
b25ae9c6 | 1062 | @deftypevr Macro int ELIBMAX |
d08a7e4c | 1063 | @standards{Linux???, errno.h} |
a429d2ff | 1064 | @errno{ELIBMAX, ???/82, Attempting to link in too many shared libraries} |
b25ae9c6 RM |
1065 | @end deftypevr |
1066 | ||
b25ae9c6 | 1067 | @deftypevr Macro int ESTRPIPE |
d08a7e4c | 1068 | @standards{Linux???, errno.h} |
a429d2ff | 1069 | @errno{ESTRPIPE, ???/86, Streams pipe error} |
b25ae9c6 RM |
1070 | @end deftypevr |
1071 | ||
b25ae9c6 | 1072 | @deftypevr Macro int EUCLEAN |
d08a7e4c | 1073 | @standards{Linux???, errno.h} |
a429d2ff | 1074 | @errno{EUCLEAN, ???/117, Structure needs cleaning} |
b25ae9c6 RM |
1075 | @end deftypevr |
1076 | ||
b25ae9c6 | 1077 | @deftypevr Macro int ENOTNAM |
d08a7e4c | 1078 | @standards{Linux???, errno.h} |
a429d2ff | 1079 | @errno{ENOTNAM, ???/118, Not a XENIX named type file} |
b25ae9c6 RM |
1080 | @end deftypevr |
1081 | ||
b25ae9c6 | 1082 | @deftypevr Macro int ENAVAIL |
d08a7e4c | 1083 | @standards{Linux???, errno.h} |
a429d2ff | 1084 | @errno{ENAVAIL, ???/119, No XENIX semaphores available} |
b25ae9c6 RM |
1085 | @end deftypevr |
1086 | ||
b25ae9c6 | 1087 | @deftypevr Macro int EISNAM |
d08a7e4c | 1088 | @standards{Linux???, errno.h} |
a429d2ff | 1089 | @errno{EISNAM, ???/120, Is a named type file} |
b25ae9c6 RM |
1090 | @end deftypevr |
1091 | ||
b25ae9c6 | 1092 | @deftypevr Macro int EREMOTEIO |
d08a7e4c | 1093 | @standards{Linux???, errno.h} |
a429d2ff | 1094 | @errno{EREMOTEIO, ???/121, Remote I/O error} |
b25ae9c6 | 1095 | @end deftypevr |
28f540f4 | 1096 | |
22d57dd3 | 1097 | @deftypevr Macro int ENOMEDIUM |
d08a7e4c | 1098 | @standards{Linux???, errno.h} |
a429d2ff | 1099 | @errno{ENOMEDIUM, ???/???, No medium found} |
22d57dd3 UD |
1100 | @end deftypevr |
1101 | ||
22d57dd3 | 1102 | @deftypevr Macro int EMEDIUMTYPE |
d08a7e4c | 1103 | @standards{Linux???, errno.h} |
a429d2ff | 1104 | @errno{EMEDIUMTYPE, ???/???, Wrong medium type} |
22d57dd3 | 1105 | @end deftypevr |
d4d138a4 | 1106 | |
d4d138a4 | 1107 | @deftypevr Macro int ENOKEY |
d08a7e4c | 1108 | @standards{Linux, errno.h} |
a429d2ff | 1109 | @errno{ENOKEY, ???/???, Required key not available} |
d4d138a4 UD |
1110 | @end deftypevr |
1111 | ||
d4d138a4 | 1112 | @deftypevr Macro int EKEYEXPIRED |
d08a7e4c | 1113 | @standards{Linux, errno.h} |
a429d2ff | 1114 | @errno{EKEYEXPIRED, ???/???, Key has expired} |
d4d138a4 UD |
1115 | @end deftypevr |
1116 | ||
d4d138a4 | 1117 | @deftypevr Macro int EKEYREVOKED |
d08a7e4c | 1118 | @standards{Linux, errno.h} |
a429d2ff | 1119 | @errno{EKEYREVOKED, ???/???, Key has been revoked} |
d4d138a4 UD |
1120 | @end deftypevr |
1121 | ||
d4d138a4 | 1122 | @deftypevr Macro int EKEYREJECTED |
d08a7e4c | 1123 | @standards{Linux, errno.h} |
a429d2ff | 1124 | @errno{EKEYREJECTED, ???/???, Key was rejected by service} |
d4d138a4 UD |
1125 | @end deftypevr |
1126 | ||
0079dd23 | 1127 | @deftypevr Macro int ERFKILL |
d08a7e4c | 1128 | @standards{Linux, errno.h} |
a429d2ff | 1129 | @errno{ERFKILL, ???/???, Operation not possible due to RF-kill} |
0079dd23 | 1130 | @end deftypevr |
22d57dd3 | 1131 | |
7638c0fd | 1132 | @deftypevr Macro int EHWPOISON |
d08a7e4c | 1133 | @standards{Linux, errno.h} |
a429d2ff | 1134 | @errno{EHWPOISON, ???/???, Memory page has hardware error} |
7638c0fd AS |
1135 | @end deftypevr |
1136 | ||
28f540f4 RM |
1137 | @node Error Messages, , Error Codes, Error Reporting |
1138 | @section Error Messages | |
1139 | ||
1140 | The library has functions and variables designed to make it easy for | |
1141 | your program to report informative error messages in the customary | |
1142 | format about the failure of a library call. The functions | |
1143 | @code{strerror} and @code{perror} give you the standard error message | |
1144 | for a given error code; the variable | |
1145 | @w{@code{program_invocation_short_name}} gives you convenient access to the | |
1146 | name of the program that encountered the error. | |
1147 | ||
28f540f4 | 1148 | @deftypefun {char *} strerror (int @var{errnum}) |
d08a7e4c | 1149 | @standards{ISO, string.h} |
c3299c08 AO |
1150 | @safety{@prelim{}@mtunsafe{@mtasurace{:strerror}}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} |
1151 | @c Calls strerror_r with a static buffer allocated with malloc on the | |
1152 | @c first use. | |
28f540f4 RM |
1153 | The @code{strerror} function maps the error code (@pxref{Checking for |
1154 | Errors}) specified by the @var{errnum} argument to a descriptive error | |
1155 | message string. The return value is a pointer to this string. | |
1156 | ||
1157 | The value @var{errnum} normally comes from the variable @code{errno}. | |
1158 | ||
1159 | You should not modify the string returned by @code{strerror}. Also, if | |
1160 | you make subsequent calls to @code{strerror}, the string might be | |
1161 | overwritten. (But it's guaranteed that no library function ever calls | |
1162 | @code{strerror} behind your back.) | |
1163 | ||
1164 | The function @code{strerror} is declared in @file{string.h}. | |
1165 | @end deftypefun | |
1166 | ||
22d57dd3 | 1167 | @deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n}) |
d08a7e4c | 1168 | @standards{GNU, string.h} |
c3299c08 | 1169 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuintl{}}@acunsafe{}} |
22d57dd3 UD |
1170 | The @code{strerror_r} function works like @code{strerror} but instead of |
1171 | returning the error message in a statically allocated buffer shared by | |
da2d1bc5 | 1172 | all threads in the process, it returns a private copy for the |
cf822e3c | 1173 | thread. This might be either some permanent global data or a message |
da2d1bc5 UD |
1174 | string in the user supplied buffer starting at @var{buf} with the |
1175 | length of @var{n} bytes. | |
22d57dd3 UD |
1176 | |
1177 | At most @var{n} characters are written (including the NUL byte) so it is | |
b56e416f | 1178 | up to the user to select a buffer large enough. |
22d57dd3 UD |
1179 | |
1180 | This function should always be used in multi-threaded programs since | |
1181 | there is no way to guarantee the string returned by @code{strerror} | |
1182 | really belongs to the last call of the current thread. | |
1183 | ||
b56e416f | 1184 | The function @code{strerror_r} is a GNU extension and it is declared in |
22d57dd3 UD |
1185 | @file{string.h}. |
1186 | @end deftypefun | |
1187 | ||
28f540f4 | 1188 | @deftypefun void perror (const char *@var{message}) |
d08a7e4c | 1189 | @standards{ISO, stdio.h} |
c3299c08 AO |
1190 | @safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} |
1191 | @c Besides strerror_r's and some of fprintf's issues, if stderr is not | |
1192 | @c oriented yet, create a new stream with a dup of stderr's fd and write | |
1193 | @c to that instead of stderr, to avoid orienting it. | |
28f540f4 | 1194 | This function prints an error message to the stream @code{stderr}; |
a2635361 UD |
1195 | see @ref{Standard Streams}. The orientation of @code{stderr} is not |
1196 | changed. | |
28f540f4 RM |
1197 | |
1198 | If you call @code{perror} with a @var{message} that is either a null | |
b8fe19fa | 1199 | pointer or an empty string, @code{perror} just prints the error message |
28f540f4 RM |
1200 | corresponding to @code{errno}, adding a trailing newline. |
1201 | ||
1202 | If you supply a non-null @var{message} argument, then @code{perror} | |
b8fe19fa | 1203 | prefixes its output with this string. It adds a colon and a space |
28f540f4 RM |
1204 | character to separate the @var{message} from the error string corresponding |
1205 | to @code{errno}. | |
1206 | ||
1207 | The function @code{perror} is declared in @file{stdio.h}. | |
1208 | @end deftypefun | |
1209 | ||
c318905e | 1210 | @deftypefun {const char *} strerrorname_np (int @var{errnum}) |
325081b9 | 1211 | @standards{GNU, string.h} |
e9422236 | 1212 | @safety{@mtsafe{}@assafe{}@acsafe{}} |
325081b9 AZ |
1213 | This function returns the name describing the error @var{errnum} or |
1214 | @code{NULL} if there is no known constant with this value (e.g "EINVAL" | |
1215 | for @code{EINVAL}). | |
1216 | ||
1217 | @pindex string.h | |
1218 | This function is a GNU extension, declared in the header file @file{string.h}. | |
1219 | @end deftypefun | |
1220 | ||
c318905e | 1221 | @deftypefun {const char *} strerrordesc_np (int @var{errnum}) |
325081b9 | 1222 | @standards{GNU, string.h} |
e9422236 | 1223 | @safety{@mtsafe{}@assafe{}@acsafe{}} |
325081b9 AZ |
1224 | This function returns the message describing the error @var{errnum} or |
1225 | @code{NULL} if there is no known constant with this value (e.g "Invalid | |
1226 | argument" for @code{EINVAL}). Different than @code{strerror} the returned | |
1227 | description is not translated. | |
1228 | ||
1229 | @pindex string.h | |
1230 | This function is a GNU extension, declared in the header file @file{string.h}. | |
1231 | @end deftypefun | |
1232 | ||
28f540f4 | 1233 | @code{strerror} and @code{perror} produce the exact same message for any |
a7a93d50 JM |
1234 | given error code; the precise text varies from system to system. With |
1235 | @theglibc{}, the messages are fairly short; there are no multi-line | |
28f540f4 RM |
1236 | messages or embedded newlines. Each error message begins with a capital |
1237 | letter and does not include any terminating punctuation. | |
1238 | ||
28f540f4 RM |
1239 | @cindex program name |
1240 | @cindex name of running program | |
1241 | Many programs that don't read input from the terminal are designed to | |
1242 | exit if any system call fails. By convention, the error message from | |
1243 | such a program should start with the program's name, sans directories. | |
1244 | You can find that name in the variable | |
1245 | @code{program_invocation_short_name}; the full file name is stored the | |
bc938d3d | 1246 | variable @code{program_invocation_name}. |
28f540f4 | 1247 | |
b8fe19fa | 1248 | @deftypevar {char *} program_invocation_name |
d08a7e4c | 1249 | @standards{GNU, errno.h} |
28f540f4 RM |
1250 | This variable's value is the name that was used to invoke the program |
1251 | running in the current process. It is the same as @code{argv[0]}. Note | |
1252 | that this is not necessarily a useful file name; often it contains no | |
1253 | directory names. @xref{Program Arguments}. | |
7e7af349 RJ |
1254 | |
1255 | This variable is a GNU extension and is declared in @file{errno.h}. | |
28f540f4 RM |
1256 | @end deftypevar |
1257 | ||
b8fe19fa | 1258 | @deftypevar {char *} program_invocation_short_name |
d08a7e4c | 1259 | @standards{GNU, errno.h} |
28f540f4 RM |
1260 | This variable's value is the name that was used to invoke the program |
1261 | running in the current process, with directory names removed. (That is | |
1262 | to say, it is the same as @code{program_invocation_name} minus | |
1263 | everything up to the last slash, if any.) | |
7e7af349 RJ |
1264 | |
1265 | This variable is a GNU extension and is declared in @file{errno.h}. | |
28f540f4 RM |
1266 | @end deftypevar |
1267 | ||
1268 | The library initialization code sets up both of these variables before | |
1269 | calling @code{main}. | |
1270 | ||
7e7af349 RJ |
1271 | @strong{Portability Note:} If you want your program to work with |
1272 | non-GNU libraries, you must save the value of @code{argv[0]} in | |
1273 | @code{main}, and then strip off the directory names yourself. We | |
1274 | added these extensions to make it possible to write self-contained | |
1275 | error-reporting subroutines that require no explicit cooperation from | |
1276 | @code{main}. | |
28f540f4 RM |
1277 | |
1278 | Here is an example showing how to handle failure to open a file | |
1279 | correctly. The function @code{open_sesame} tries to open the named file | |
1280 | for reading and returns a stream if successful. The @code{fopen} | |
1281 | library function returns a null pointer if it couldn't open the file for | |
1282 | some reason. In that situation, @code{open_sesame} constructs an | |
1283 | appropriate error message using the @code{strerror} function, and | |
1284 | terminates the program. If we were going to make some other library | |
1285 | calls before passing the error code to @code{strerror}, we'd have to | |
1286 | save it in a local variable instead, because those other library | |
1287 | functions might overwrite @code{errno} in the meantime. | |
1288 | ||
1289 | @smallexample | |
7e7af349 RJ |
1290 | #define _GNU_SOURCE |
1291 | ||
28f540f4 RM |
1292 | #include <errno.h> |
1293 | #include <stdio.h> | |
1294 | #include <stdlib.h> | |
1295 | #include <string.h> | |
1296 | ||
1297 | FILE * | |
1298 | open_sesame (char *name) | |
b8fe19fa | 1299 | @{ |
28f540f4 RM |
1300 | FILE *stream; |
1301 | ||
b8fe19fa | 1302 | errno = 0; |
28f540f4 RM |
1303 | stream = fopen (name, "r"); |
1304 | if (stream == NULL) | |
1305 | @{ | |
1306 | fprintf (stderr, "%s: Couldn't open file %s; %s\n", | |
1307 | program_invocation_short_name, name, strerror (errno)); | |
1308 | exit (EXIT_FAILURE); | |
1309 | @} | |
1310 | else | |
1311 | return stream; | |
1312 | @} | |
1313 | @end smallexample | |
a2635361 UD |
1314 | |
1315 | Using @code{perror} has the advantage that the function is portable and | |
1316 | available on all systems implementing @w{ISO C}. But often the text | |
1317 | @code{perror} generates is not what is wanted and there is no way to | |
1318 | extend or change what @code{perror} does. The GNU coding standard, for | |
1319 | instance, requires error messages to be preceded by the program name and | |
bbf70ae9 | 1320 | programs which read some input files should provide information |
a2635361 UD |
1321 | about the input file name and the line number in case an error is |
1322 | encountered while reading the file. For these occasions there are two | |
1323 | functions available which are widely used throughout the GNU project. | |
1324 | These functions are declared in @file{error.h}. | |
1325 | ||
a2635361 | 1326 | @deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{}) |
d08a7e4c | 1327 | @standards{GNU, error.h} |
c3299c08 AO |
1328 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acsafe{}} |
1329 | @c Cancellation is disabled throughout the execution. It flushes stdout | |
1330 | @c and then holds a lock on stderr while printing the program name and | |
1331 | @c then running error_tail. The non-wide case just runs vfprintf; the | |
1332 | @c wide case converts the message to an alloca/malloc-allocated buffer | |
1333 | @c with mbsrtowcs, then prints it with vfwprintf. Afterwards, | |
1334 | @c print_errno_message calls strerror_r and fxprintf. | |
a2635361 UD |
1335 | The @code{error} function can be used to report general problems during |
1336 | program execution. The @var{format} argument is a format string just | |
1337 | like those given to the @code{printf} family of functions. The | |
1338 | arguments required for the format can follow the @var{format} parameter. | |
1339 | Just like @code{perror}, @code{error} also can report an error code in | |
1340 | textual form. But unlike @code{perror} the error value is explicitly | |
11bf311e | 1341 | passed to the function in the @var{errnum} parameter. This eliminates |
a2635361 UD |
1342 | the problem mentioned above that the error reporting function must be |
1343 | called immediately after the function causing the error since otherwise | |
1344 | @code{errno} might have a different value. | |
1345 | ||
b56e416f | 1346 | @code{error} prints first the program name. If the application |
a2635361 UD |
1347 | defined a global variable @code{error_print_progname} and points it to a |
1348 | function this function will be called to print the program name. | |
1349 | Otherwise the string from the global variable @code{program_name} is | |
1350 | used. The program name is followed by a colon and a space which in turn | |
1351 | is followed by the output produced by the format string. If the | |
1352 | @var{errnum} parameter is non-zero the format string output is followed | |
1353 | by a colon and a space, followed by the error message for the error code | |
1354 | @var{errnum}. In any case is the output terminated with a newline. | |
1355 | ||
1356 | The output is directed to the @code{stderr} stream. If the | |
1357 | @code{stderr} wasn't oriented before the call it will be narrow-oriented | |
1358 | afterwards. | |
1359 | ||
1360 | The function will return unless the @var{status} parameter has a | |
1361 | non-zero value. In this case the function will call @code{exit} with | |
1362 | the @var{status} value for its parameter and therefore never return. If | |
b56e416f | 1363 | @code{error} returns, the global variable @code{error_message_count} is |
a2635361 UD |
1364 | incremented by one to keep track of the number of errors reported. |
1365 | @end deftypefun | |
1366 | ||
a2635361 | 1367 | @deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{}) |
d08a7e4c | 1368 | @standards{GNU, error.h} |
c3299c08 AO |
1369 | @safety{@prelim{}@mtunsafe{@mtasurace{:error_at_line/error_one_per_line} @mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acunsafe{@acucorrupt{/error_one_per_line}}} |
1370 | @c The error_one_per_line variable is accessed (without any form of | |
1371 | @c synchronization, but since it's an int used once, it should be safe | |
1372 | @c enough) and, if this mode is enabled, static variables used to hold | |
1373 | @c the last printed file name and line number are accessed and modified | |
1374 | @c without synchronization; the update is not atomic and it occurs | |
1375 | @c before disabling cancellation, so it can be interrupted after only | |
1376 | @c one of the two variables is modified. After that, it's very much | |
1377 | @c like error. | |
a2635361 UD |
1378 | |
1379 | The @code{error_at_line} function is very similar to the @code{error} | |
b56e416f | 1380 | function. The only differences are the additional parameters @var{fname} |
a2635361 UD |
1381 | and @var{lineno}. The handling of the other parameters is identical to |
1382 | that of @code{error} except that between the program name and the string | |
1383 | generated by the format string additional text is inserted. | |
1384 | ||
1385 | Directly following the program name a colon, followed by the file name | |
b56e416f | 1386 | pointed to by @var{fname}, another colon, and the value of @var{lineno} is |
a2635361 UD |
1387 | printed. |
1388 | ||
1389 | This additional output of course is meant to be used to locate an error | |
1390 | in an input file (like a programming language source code file etc). | |
1391 | ||
1392 | If the global variable @code{error_one_per_line} is set to a non-zero | |
1393 | value @code{error_at_line} will avoid printing consecutive messages for | |
11bf311e | 1394 | the same file and line. Repetition which are not directly following |
a2635361 UD |
1395 | each other are not caught. |
1396 | ||
b56e416f | 1397 | Just like @code{error} this function only returns if @var{status} is |
a2635361 | 1398 | zero. Otherwise @code{exit} is called with the non-zero value. If |
b56e416f | 1399 | @code{error} returns, the global variable @code{error_message_count} is |
a2635361 UD |
1400 | incremented by one to keep track of the number of errors reported. |
1401 | @end deftypefun | |
1402 | ||
b56e416f | 1403 | As mentioned above, the @code{error} and @code{error_at_line} functions |
a2635361 UD |
1404 | can be customized by defining a variable named |
1405 | @code{error_print_progname}. | |
1406 | ||
8ded91fb | 1407 | @deftypevar {void (*error_print_progname)} (void) |
d08a7e4c | 1408 | @standards{GNU, error.h} |
a2635361 UD |
1409 | If the @code{error_print_progname} variable is defined to a non-zero |
1410 | value the function pointed to is called by @code{error} or | |
1411 | @code{error_at_line}. It is expected to print the program name or do | |
1412 | something similarly useful. | |
1413 | ||
b56e416f | 1414 | The function is expected to print to the @code{stderr} stream and |
a2635361 UD |
1415 | must be able to handle whatever orientation the stream has. |
1416 | ||
1417 | The variable is global and shared by all threads. | |
1418 | @end deftypevar | |
1419 | ||
a2635361 | 1420 | @deftypevar {unsigned int} error_message_count |
d08a7e4c | 1421 | @standards{GNU, error.h} |
a2635361 UD |
1422 | The @code{error_message_count} variable is incremented whenever one of |
1423 | the functions @code{error} or @code{error_at_line} returns. The | |
1424 | variable is global and shared by all threads. | |
1425 | @end deftypevar | |
1426 | ||
a2635361 | 1427 | @deftypevar int error_one_per_line |
d08a7e4c | 1428 | @standards{GNU, error.h} |
a2635361 UD |
1429 | The @code{error_one_per_line} variable influences only |
1430 | @code{error_at_line}. Normally the @code{error_at_line} function | |
1431 | creates output for every invocation. If @code{error_one_per_line} is | |
1432 | set to a non-zero value @code{error_at_line} keeps track of the last | |
b56e416f | 1433 | file name and line number for which an error was reported and avoids |
a2635361 UD |
1434 | directly following messages for the same file and line. This variable |
1435 | is global and shared by all threads. | |
1436 | @end deftypevar | |
1437 | ||
1438 | @noindent | |
1439 | A program which read some input file and reports errors in it could look | |
1440 | like this: | |
1441 | ||
1442 | @smallexample | |
1443 | @{ | |
1444 | char *line = NULL; | |
1445 | size_t len = 0; | |
1446 | unsigned int lineno = 0; | |
1447 | ||
1448 | error_message_count = 0; | |
1449 | while (! feof_unlocked (fp)) | |
1450 | @{ | |
1451 | ssize_t n = getline (&line, &len, fp); | |
1452 | if (n <= 0) | |
1453 | /* @r{End of file or error.} */ | |
1454 | break; | |
1455 | ++lineno; | |
1456 | ||
1457 | /* @r{Process the line.} */ | |
1458 | @dots{} | |
1459 | ||
1460 | if (@r{Detect error in line}) | |
1461 | error_at_line (0, errval, filename, lineno, | |
1462 | "some error text %s", some_variable); | |
1463 | @} | |
1464 | ||
1465 | if (error_message_count != 0) | |
1466 | error (EXIT_FAILURE, 0, "%u errors found", error_message_count); | |
1467 | @} | |
1468 | @end smallexample | |
1469 | ||
1470 | @code{error} and @code{error_at_line} are clearly the functions of | |
1471 | choice and enable the programmer to write applications which follow the | |
1f77f049 | 1472 | GNU coding standard. @Theglibc{} additionally contains functions which |
a2635361 UD |
1473 | are used in BSD for the same purpose. These functions are declared in |
1474 | @file{err.h}. It is generally advised to not use these functions. They | |
1475 | are included only for compatibility. | |
1476 | ||
a2635361 | 1477 | @deftypefun void warn (const char *@var{format}, @dots{}) |
d08a7e4c | 1478 | @standards{BSD, err.h} |
c3299c08 AO |
1479 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1480 | @c Just calls vwarn with the va_list. | |
a2635361 UD |
1481 | The @code{warn} function is roughly equivalent to a call like |
1482 | @smallexample | |
1483 | error (0, errno, format, @r{the parameters}) | |
1484 | @end smallexample | |
1485 | @noindent | |
1486 | except that the global variables @code{error} respects and modifies | |
1487 | are not used. | |
1488 | @end deftypefun | |
1489 | ||
cc6e48bc | 1490 | @deftypefun void vwarn (const char *@var{format}, va_list @var{ap}) |
d08a7e4c | 1491 | @standards{BSD, err.h} |
c3299c08 AO |
1492 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1493 | @c While holding stderr's recursive lock, it prints the programname, the | |
1494 | @c given message, and the error string with fw?printf's %m. When the | |
1495 | @c stream is wide, convert_and_print converts the format string to an | |
1496 | @c alloca/malloc-created buffer using mbsrtowcs and then calls fwprintf. | |
a2635361 UD |
1497 | The @code{vwarn} function is just like @code{warn} except that the |
1498 | parameters for the handling of the format string @var{format} are passed | |
9dcc8f11 | 1499 | in as a value of type @code{va_list}. |
a2635361 UD |
1500 | @end deftypefun |
1501 | ||
a2635361 | 1502 | @deftypefun void warnx (const char *@var{format}, @dots{}) |
d08a7e4c | 1503 | @standards{BSD, err.h} |
c3299c08 AO |
1504 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1505 | @c Same as warn, but without the strerror translation issues. | |
a2635361 UD |
1506 | The @code{warnx} function is roughly equivalent to a call like |
1507 | @smallexample | |
1508 | error (0, 0, format, @r{the parameters}) | |
1509 | @end smallexample | |
1510 | @noindent | |
1511 | except that the global variables @code{error} respects and modifies | |
1512 | are not used. The difference to @code{warn} is that no error number | |
1513 | string is printed. | |
1514 | @end deftypefun | |
1515 | ||
cc6e48bc | 1516 | @deftypefun void vwarnx (const char *@var{format}, va_list @var{ap}) |
d08a7e4c | 1517 | @standards{BSD, err.h} |
c3299c08 AO |
1518 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1519 | @c Same as vwarn, but without the strerror translation issues. | |
a2635361 UD |
1520 | The @code{vwarnx} function is just like @code{warnx} except that the |
1521 | parameters for the handling of the format string @var{format} are passed | |
9dcc8f11 | 1522 | in as a value of type @code{va_list}. |
a2635361 UD |
1523 | @end deftypefun |
1524 | ||
a2635361 | 1525 | @deftypefun void err (int @var{status}, const char *@var{format}, @dots{}) |
d08a7e4c | 1526 | @standards{BSD, err.h} |
c3299c08 AO |
1527 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1528 | @c Same as warn followed by exit. | |
a2635361 UD |
1529 | The @code{err} function is roughly equivalent to a call like |
1530 | @smallexample | |
1531 | error (status, errno, format, @r{the parameters}) | |
1532 | @end smallexample | |
1533 | @noindent | |
1534 | except that the global variables @code{error} respects and modifies | |
1535 | are not used and that the program is exited even if @var{status} is zero. | |
1536 | @end deftypefun | |
1537 | ||
cc6e48bc | 1538 | @deftypefun void verr (int @var{status}, const char *@var{format}, va_list @var{ap}) |
d08a7e4c | 1539 | @standards{BSD, err.h} |
c3299c08 AO |
1540 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1541 | @c Same as vwarn followed by exit. | |
a2635361 UD |
1542 | The @code{verr} function is just like @code{err} except that the |
1543 | parameters for the handling of the format string @var{format} are passed | |
9dcc8f11 | 1544 | in as a value of type @code{va_list}. |
a2635361 UD |
1545 | @end deftypefun |
1546 | ||
a2635361 | 1547 | @deftypefun void errx (int @var{status}, const char *@var{format}, @dots{}) |
d08a7e4c | 1548 | @standards{BSD, err.h} |
c3299c08 AO |
1549 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1550 | @c Same as warnx followed by exit. | |
a2635361 UD |
1551 | The @code{errx} function is roughly equivalent to a call like |
1552 | @smallexample | |
1553 | error (status, 0, format, @r{the parameters}) | |
1554 | @end smallexample | |
1555 | @noindent | |
1556 | except that the global variables @code{error} respects and modifies | |
1557 | are not used and that the program is exited even if @var{status} | |
1558 | is zero. The difference to @code{err} is that no error number | |
1559 | string is printed. | |
1560 | @end deftypefun | |
1561 | ||
cc6e48bc | 1562 | @deftypefun void verrx (int @var{status}, const char *@var{format}, va_list @var{ap}) |
d08a7e4c | 1563 | @standards{BSD, err.h} |
c3299c08 AO |
1564 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} |
1565 | @c Same as vwarnx followed by exit. | |
a2635361 UD |
1566 | The @code{verrx} function is just like @code{errx} except that the |
1567 | parameters for the handling of the format string @var{format} are passed | |
9dcc8f11 | 1568 | in as a value of type @code{va_list}. |
a2635361 | 1569 | @end deftypefun |