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