Commit | Line | Data |
---|---|---|
5822f3c2 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
b5984ffe | 5 | .\" @(#)intro.2 6.2 (Berkeley) %G% |
5822f3c2 | 6 | .\" |
8af6b0db | 7 | .TH INTRO 2 "" |
5822f3c2 KM |
8 | .UC 4 |
9 | .de en | |
10 | .HP | |
11 | \\$1 \\$2 \\$3 | |
12 | .br | |
13 | .. | |
14 | .SH NAME | |
5e1f9d48 | 15 | intro \- introduction to system calls and error numbers |
5822f3c2 KM |
16 | .SH SYNOPSIS |
17 | .B #include <errno.h> | |
18 | .SH DESCRIPTION | |
5e1f9d48 KM |
19 | This section describes all of the system calls. Most |
20 | of these calls have one or more error returns. | |
21 | An error condition is indicated by an otherwise impossible return | |
22 | value. This is almost always \-1; the individual descriptions | |
23 | specify the details. | |
5822f3c2 | 24 | .PP |
5e1f9d48 KM |
25 | As with normal arguments, all return codes and values from |
26 | functions are of type integer unless otherwise noted. | |
27 | An error number is also made available in the external | |
28 | variable \fIerrno\fP, which is not cleared | |
29 | on successful calls. | |
30 | Thus \fIerrno\fP should be tested only after an error has occurred. | |
5822f3c2 | 31 | .PP |
5e1f9d48 KM |
32 | The following is a complete list of the errors and their |
33 | names as given in | |
34 | .RI < errno.h >. | |
5822f3c2 KM |
35 | .en 0 \h'\w'EIO'u' "Error 0 |
36 | Unused. | |
37 | .en 1 EPERM "Not owner | |
38 | Typically this error indicates | |
39 | an attempt to modify a file in some way forbidden | |
40 | except to its owner or super-user. | |
41 | It is also returned for attempts | |
42 | by ordinary users to do things | |
43 | allowed only to the super-user. | |
44 | .en 2 ENOENT "No such file or directory | |
45 | This error occurs when a file name is specified | |
46 | and the file should exist but doesn't, or when one | |
47 | of the directories in a path name does not exist. | |
48 | .en 3 ESRCH "No such process | |
49 | The process whose number was given to | |
5e1f9d48 | 50 | .I kill |
5822f3c2 KM |
51 | and |
52 | .I ptrace | |
53 | does not exist, or is already dead. | |
54 | .en 4 EINTR "Interrupted system call | |
55 | An asynchronous signal (such as interrupt or quit), | |
56 | which the user has elected to catch, | |
57 | occurred during a system call. | |
58 | If execution is resumed | |
59 | after processing the signal, | |
60 | it will appear as if the interrupted system call | |
61 | returned this error condition. | |
62 | .en 5 EIO "I/O error | |
63 | Some physical I/O error occurred during a | |
64 | .I read | |
65 | or | |
66 | .IR write . | |
67 | This error may in some cases occur | |
68 | on a call following the one to which it actually applies. | |
69 | .en 6 ENXIO "No such device or address | |
70 | I/O on a special file refers to a subdevice which does not | |
71 | exist, | |
72 | or beyond the limits of the device. | |
5e1f9d48 KM |
73 | It may also occur when, for example, an illegal tape drive |
74 | unit number is selected | |
75 | or a disk pack is not loaded on a drive. | |
5822f3c2 KM |
76 | .en 7 E2BIG "Arg list too long |
77 | An argument list longer than 10240 bytes | |
78 | is presented to | |
5e1f9d48 | 79 | .IR execve . |
5822f3c2 KM |
80 | .en 8 ENOEXEC "Exec format error |
81 | A request is made to execute a file | |
82 | which, although it has the appropriate permissions, | |
83 | does not start with a valid magic number, see | |
84 | .IR a.out (5). | |
85 | .en 9 EBADF "Bad file number | |
86 | Either a file descriptor refers to no | |
87 | open file, | |
88 | or a read (resp. write) request is made to | |
89 | a file which is open only for writing (resp. reading). | |
90 | .en 10 ECHILD "No children | |
91 | .I Wait | |
92 | and the process has no | |
93 | living or unwaited-for children. | |
94 | .en 11 EAGAIN "No more processes | |
95 | In a | |
96 | .I fork, | |
97 | the system's process table is full | |
98 | or the user is not allowed to create any more | |
99 | processes. | |
100 | .en 12 ENOMEM "Not enough core | |
101 | During an | |
5e1f9d48 | 102 | .I execve |
5822f3c2 KM |
103 | or |
104 | .I break, | |
5e1f9d48 KM |
105 | a program asks for more core or swap space than the system is |
106 | able to supply. | |
107 | A lack of swap space is normally a temporary condition, however | |
108 | a lack of core | |
109 | is not a temporary condition; the maximum size | |
110 | of the text, data, and stack segments is a system parameter. | |
5822f3c2 KM |
111 | .en 13 EACCES "Permission denied |
112 | An attempt was made to access a file in a way forbidden | |
113 | by the protection system. | |
114 | .en 14 EFAULT "Bad address | |
115 | The system encountered a hardware fault in attempting to | |
116 | access the arguments of a system call. | |
117 | .en 15 ENOTBLK "Block device required | |
118 | A plain file was mentioned where a block device was required, | |
119 | e.g. in | |
120 | .IR mount . | |
b5984ffe | 121 | .en 16 EBUSY "Device busy |
5822f3c2 KM |
122 | An attempt to mount a device that was already mounted or |
123 | an attempt was made to dismount a device | |
124 | on which there is an active file | |
125 | directory. | |
126 | (open file, current directory, mounted-on file, active text segment). | |
b5984ffe | 127 | A request was made to an exclusive access device that was already in use. |
5822f3c2 KM |
128 | .en 17 EEXIST "File exists |
129 | An existing file was mentioned in an inappropriate context, | |
130 | e.g. | |
131 | .IR link . | |
132 | .en 18 EXDEV "Cross-device link | |
5e1f9d48 | 133 | A hard link to a file on another device |
5822f3c2 KM |
134 | was attempted. |
135 | .en 19 ENODEV "No such device | |
136 | An attempt was made to apply an inappropriate | |
137 | system call to a device; | |
138 | e.g. read a write-only device. | |
139 | .en 20 ENOTDIR "Not a directory | |
140 | A non-directory was specified where a directory | |
141 | is required, | |
142 | for example in a path name or | |
143 | as an argument to | |
144 | .IR chdir . | |
145 | .en 21 EISDIR "Is a directory | |
146 | An attempt to write on a directory. | |
147 | .en 22 EINVAL "Invalid argument | |
148 | Some invalid argument: | |
149 | dismounting a non-mounted | |
150 | device, | |
151 | mentioning an unknown signal in | |
152 | .I signal, | |
153 | reading or writing a file for which | |
154 | .I seek | |
155 | has generated a negative pointer. | |
156 | Also set by math functions, see | |
157 | .IR intro (3). | |
158 | .en 23 ENFILE "File table overflow | |
159 | The system's table of open files is full, | |
160 | and temporarily no more | |
161 | .I opens | |
162 | can be accepted. | |
163 | .en 24 EMFILE "Too many open files | |
164 | Customary configuration limit is 20 per process. | |
165 | .en 25 ENOTTY "Not a typewriter | |
5e1f9d48 KM |
166 | The file mentioned in an |
167 | .I ioctl | |
5822f3c2 | 168 | is not a terminal or one of the other |
8af6b0db | 169 | devices to which this call applies. |
5822f3c2 KM |
170 | .en 26 ETXTBSY "Text file busy |
171 | An attempt to execute a pure-procedure | |
8af6b0db | 172 | program which is currently open for writing. |
5822f3c2 KM |
173 | Also an attempt to open for writing a pure-procedure |
174 | program that is being executed. | |
175 | .en 27 EFBIG "File too large | |
176 | The size of a file exceeded the maximum (about | |
177 | .if t 10\u\s-29\s+2\d | |
178 | .if n 1.0E9 | |
179 | bytes). | |
180 | .en 28 ENOSPC "No space left on device | |
181 | During a | |
182 | .I write | |
183 | to an ordinary file, | |
184 | there is no free space left on the device. | |
185 | .en 29 ESPIPE "Illegal seek | |
186 | An | |
187 | .I lseek | |
188 | was issued to a pipe. | |
5e1f9d48 | 189 | This error may also be issued for |
5822f3c2 KM |
190 | other non-seekable devices. |
191 | .en 30 EROFS "Read-only file system | |
192 | An attempt to modify a file or directory | |
193 | was made | |
194 | on a device mounted read-only. | |
195 | .en 31 EMLINK "Too many links | |
5e1f9d48 | 196 | An attempt to make more than 32767 hard links to a file. |
5822f3c2 | 197 | .en 32 EPIPE "Broken pipe |
5e1f9d48 | 198 | A write on a pipe or socket for which there is no process |
5822f3c2 KM |
199 | to read the data. |
200 | This condition normally generates a signal; | |
201 | the error is returned if the signal is ignored. | |
202 | .en 33 EDOM "Math argument | |
203 | The argument of a function in the math package (3M) | |
204 | is out of the domain of the function. | |
205 | .en 34 ERANGE "Result too large | |
206 | The value of a function in the math package (3M) | |
207 | is unrepresentable within machine precision. | |
5e1f9d48 KM |
208 | .en 35 EWOULDBLOCK "Operation would block" |
209 | An operation which would cause a process to block was attempted | |
210 | on a object in non-blocking mode (see \fIioctl\fP (2)). | |
211 | .en 36 EINPROGRESS "Operation now in progress" | |
212 | An operation which takes a long time to complete (such as | |
213 | a \fIconnect\fP (2)) was attempted on a non-blocking object (see | |
214 | \fIioctl\fP (2)). | |
215 | .en 37 EALREADY "Operation already in progress" | |
216 | An operation was attempted on a non-blocking object which already | |
217 | had an operation in progress. | |
218 | .en 38 ENOTSOCK "Socket operation on non-socket" | |
219 | Self-explanatory. | |
220 | .en 39 EDESTADDRREQ "Destination address required" | |
221 | A required address was omitted from an operation on a socket. | |
222 | .en 40 EMSGSIZE "Message too long" | |
223 | A message sent on a socket was larger than the internal message buffer. | |
224 | .en 41 EPROTOTYPE "Protocol wrong type for socket" | |
225 | A protocol was specified which does not support the semantics of the | |
226 | socket type requested. For example you cannot use the ARPA Internet | |
227 | UDP protocol with type SOCK_STREAM. | |
228 | .en 42 ENOPROTOOPT "Bad protocol option" | |
229 | A bad option was specified in a | |
230 | .IR getsockopt (2) | |
231 | or | |
232 | .IR setsockopt (2) | |
233 | call. | |
234 | .en 43 EPROTONOSUPPORT "Protocol not supported" | |
235 | The protocol has not been configured into the | |
236 | system or no implementation for it exists. | |
237 | .en 44 ESOCKTNOSUPPORT "Socket type not supported" | |
238 | The support for the socket type has not been configured into the | |
239 | system or no implementation for it exists. | |
240 | .en 45 EOPNOTSUPP "Operation not supported on socket" | |
241 | For example, trying to \fIaccept\fP a connection on a datagram socket. | |
242 | .en 46 EPFNOSUPPORT "Protocol family not supported" | |
243 | The protocol family has not been configured into the | |
244 | system or no implementation for it exists. | |
245 | .en 47 EAFNOSUPPORT "Address family not supported by protocol family" | |
246 | An address incompatible with the requested protocol was used. | |
247 | For example, you shouldn't necessarily expect to be able to use PUP | |
248 | Internet addresses with ARPA Internet protocols. | |
249 | .en 48 EADDRINUSE "Address already in use" | |
250 | Only one usage of each address is normally permitted. | |
251 | .en 49 EADDRNOTAVAIL "Can't assign requested address" | |
252 | Normally results from an attempt to create a socket with an | |
253 | address not on this machine. | |
254 | .en 50 ENETDOWN "Network is down" | |
255 | A socket operation encountered a dead network. | |
256 | .en 51 ENETUNREACH "Network is unreachable" | |
257 | A socket operation was attempted to an unreachable network. | |
258 | .en 52 ENETRESET "Network dropped connection on reset" | |
259 | The host you were connected to crashed and rebooted. | |
260 | .en 53 ECONNABORTED "Software caused connection abort" | |
261 | A connection abort was caused internal to your host machine. | |
262 | .en 54 ECONNRESET "Connection reset by peer" | |
263 | A connection was forcibly closed by a peer. This normally | |
264 | results from the peer executing a \fIshutdown\fP (2) call. | |
265 | .en 55 ENOBUFS "No buffer space available" | |
266 | An operation on a socket or pipe was not performed because | |
267 | the system lacked sufficient buffer space. | |
268 | .en 56 EISCONN "Socket is already connected" | |
269 | A | |
270 | .I connect | |
271 | request was made on an already connected socket; or, | |
272 | a | |
273 | .I sendto | |
274 | or | |
275 | .I sendmsg | |
276 | request on a connected socket specified a destination | |
277 | other than the connected party. | |
278 | .en 57 ENOTCONN "Socket is not connected" | |
279 | An request to send or receive data was disallowed because | |
280 | the socket is not connected. | |
281 | .en 58 ESHUTDOWN "Can't send after socket shutdown" | |
282 | A request to send data was disallowed because the socket | |
283 | had already been shut down with a previous | |
284 | .IR shutdown (2) | |
285 | call. | |
286 | .en 59 \fIunused\fP | |
287 | .en 60 ETIMEDOUT "Connection timed out" | |
288 | A | |
289 | .I connect | |
290 | request failed because the connected party did not | |
291 | properly respond after a period of time. (The timeout | |
292 | period is dependent on the communication protocol.) | |
293 | .en 61 ECONNREFUSED "Connection refused" | |
294 | No connection could be made because the target machine actively | |
295 | refused it. This usually results from trying to connect | |
296 | to a service which is inactive on the foreign host. | |
297 | .en 62 ELOOP "Too many levels of symbolic links" | |
298 | A path name lookup involved more than 8 symbolic links. | |
299 | .en 63 ENAMETOOLONG "File name too long" | |
300 | A component of a path name exceeded 255 characters, or an entire | |
301 | path name exceeded 1023 characters. | |
8af6b0db KM |
302 | .en 64 EHOSTDOWN "Host is down" |
303 | A socket operation failed because the destination host was down. | |
304 | .en 65 EHOSTUNREACH "Host is unreachable" | |
305 | A socket operation was attempted to an unreachable host. | |
306 | .en 66 ENOTEMPTY "Directory not empty" | |
5e1f9d48 KM |
307 | A directory with entries other than \*(lq.\*(rq and \*(lq..\*(rq |
308 | was supplied to a remove directory or rename call. | |
8af6b0db KM |
309 | ...en 67 EPROCLIM "Too many processes" |
310 | ...en 68 EUSERS "Too many users" | |
311 | .en 69 EDQUOT "Disc quota exceeded" | |
312 | A file creation or write operation failed because the hard limit | |
313 | for that resource had been reached. | |
5e1f9d48 KM |
314 | .SH DEFINITIONS |
315 | .TP 5 | |
316 | Process ID | |
317 | .br | |
318 | Each active process in the system is uniquely identified by a positive | |
319 | integer called a process ID. The range of this ID is from 0 to {PROC_MAX}. | |
320 | .TP 5 | |
321 | Parent process ID | |
322 | .br | |
323 | A new process is created by a currently active process; see | |
324 | .IR fork (2). | |
325 | The parent process ID of a process is the process ID of its creator. | |
326 | .TP 5 | |
327 | Process Group ID | |
328 | .br | |
329 | Each active process is a member of a process group that is identified by | |
330 | a positive integer called the process group ID. This is the process | |
331 | ID of the group leader. This grouping permits the signalling of related | |
332 | processes (see | |
333 | .IR killpg (2)) | |
334 | and the job control mechanisms of | |
335 | .IR csh (1). | |
336 | .TP 5 | |
337 | Tty Group ID | |
338 | .br | |
339 | Each active process can be a member of a terminal group that is identified | |
340 | by a positive integer called the tty group ID. This grouping is used | |
341 | to arbitrate between multiple jobs contending for the same terminal; | |
342 | see | |
343 | .IR csh (1), | |
5822f3c2 | 344 | and |
5e1f9d48 KM |
345 | .IR tty (4). |
346 | .TP 5 | |
347 | Real User ID and Real Group ID | |
348 | .br | |
349 | Each user on the system is identified by a positive integer | |
350 | termed the real user ID. | |
5822f3c2 | 351 | .IP |
5e1f9d48 KM |
352 | Each user is also a member of one or more groups. |
353 | One of these groups is distinguished from others and | |
354 | used in implementing accounting facilities. The positive | |
355 | integer corresponding to this distinguished group is termed | |
356 | the real group ID. | |
357 | .IP | |
358 | All processes have a real user ID and real group ID. | |
359 | These are initialized from the equivalent attributes | |
360 | of the process which created it. | |
361 | .TP 5 | |
362 | Effective User Id, Effective Group Id, and Access Groups | |
363 | .br | |
364 | Access to system resources is governed by three values: | |
365 | the effective user ID, the effective group ID, and the | |
366 | group access list. | |
367 | .IP | |
368 | The effective user ID and effective group ID are initially the | |
369 | process's real user ID and real group ID respectively. Either | |
370 | may be modified through execution of a set-user-ID or set-group-ID | |
371 | file (possibly by one its ancestors); see | |
372 | .IR execve (2). | |
373 | .IP | |
374 | The group access list is an additional set of group ID's | |
375 | used only in determining resource accessibility. Access checks | |
376 | are performed as described below in ``File Access Permissions''. | |
377 | .TP 5 | |
378 | Super-user | |
379 | .br | |
380 | A process is recognized as a | |
381 | .I super-user | |
382 | process and is granted special privileges if its effective user ID is 0. | |
383 | .TP 5 | |
384 | Special Processes | |
385 | .br | |
386 | The processes with a process ID's of 0, 1, and 2 are special. | |
387 | Process 0 is the scheduler. Process 1 is the initialization process | |
388 | .IR init , | |
389 | and is the ancestor of every other process in the system. | |
390 | It is used to control the process structure. | |
391 | Process 2 is the paging daemon. | |
392 | .TP 5 | |
393 | Descriptor | |
394 | .br | |
395 | An integer assigned by the system when a file is referenced | |
396 | by | |
397 | .IR open (2), | |
398 | .IR dup (2), | |
399 | or | |
400 | .IR pipe (2) | |
401 | or a socket is referenced by | |
402 | .IR socket (2) | |
403 | or | |
404 | .IR socketpair (2) | |
405 | which uniquely identifies an access path to that file or socket from | |
406 | a given process or any of its children. | |
407 | .TP 5 | |
408 | File Name | |
409 | .br | |
410 | Names consisting of up to {FILENAME_MAX} characters may be used to name | |
411 | an ordinary file, special file, or directory. | |
412 | .IP | |
413 | These characters may be selected from the set of all ASCII character | |
414 | excluding 0 (null) and the ASCII code for / (slash). (The parity bit, | |
415 | bit 8, must be 0.) | |
416 | .IP | |
417 | Note that it is generally unwise to use *, ?, [ or ] as part of | |
418 | file names because of the special meaning attached to these characters | |
419 | by the shell. | |
420 | .TP 5 | |
421 | Path Name | |
422 | .br | |
423 | A path name is a null-terminated character string starting with an | |
424 | optional slash (/), followed by zero or more directory names separated | |
425 | by slashes, optionally followed by a file name. | |
426 | The total length of a path name must be less than {PATHNAME_MAX} characters. | |
427 | .IP | |
428 | If a path name begins with a slash, the path search begins at the | |
429 | .I root | |
430 | directory. | |
431 | Otherwise, the search begins from the current working directory. | |
432 | A slash by itself names the root directory. A null | |
433 | pathname refers to the current directory. | |
434 | .TP 5 | |
435 | Directory | |
436 | .br | |
437 | A directory is a special type of file which contains entries | |
438 | which are references to other files. | |
439 | Directory entries are called links. By convention, a directory | |
440 | contains at least two links, . and .., referred to as | |
441 | .I dot | |
5822f3c2 | 442 | and |
5e1f9d48 KM |
443 | .I dot-dot |
444 | respectively. Dot refers to the directory itself and | |
445 | dot-dot refers to its parent directory. | |
446 | .TP 5 | |
447 | Root Directory and Current Working Directory | |
448 | .br | |
449 | Each process has associated with it a concept of a root directory | |
450 | and a current working directory for the purpose of resolving path | |
451 | name searches. A process's root directory need not be the root | |
452 | directory of the root file system. | |
453 | .TP 5 | |
454 | File Access Permissions | |
455 | .br | |
456 | Every file in the file system has a set of access permissions. | |
457 | These permissions are used in determining whether a process | |
458 | may perform a requested operation on the file (such as opening | |
459 | a file for writing). Access permissions are established at the | |
460 | time a file is created. They may be changed at some later time | |
461 | through the | |
462 | .IR chmod (2) | |
463 | call. | |
464 | .IP | |
465 | File access is broken down according to whether a file may be: read, | |
466 | written, or executed. Directory files use the execute | |
467 | permission to control if the directory may be searched. | |
468 | .IP | |
469 | File access permissions are interpreted by the system as | |
470 | they apply to three different classes of users: the owner | |
471 | of the file, those users in the file's group, anyone else. | |
472 | Every file has an independent set of access permissions for | |
473 | each of these classes. When an access check is made, the system | |
474 | decides if permission should be granted by checking the access | |
475 | information applicable to the caller. | |
476 | .IP | |
477 | Read, write, and execute/search permissions on | |
478 | a file are granted to a process if: | |
479 | .IP | |
480 | The process's effective user ID is that of the super-user. | |
481 | .IP | |
482 | The process's effective user ID matches the user ID of the owner | |
483 | of the file and the owner permissions allow the access. | |
484 | .IP | |
485 | The process's effective user ID does not match the user ID of the | |
486 | owner of the file, and either the process's effective | |
487 | group ID matches the group ID | |
488 | of the file, or the group ID of the file is in | |
489 | the process's group access list, | |
490 | and the group permissions allow the access. | |
491 | .IP | |
492 | Neither the effective user ID nor effective group ID | |
493 | and group access list of the process | |
494 | match the corresponding user ID and group ID of the file, | |
495 | but the permissions for ``other users'' allow access. | |
496 | .IP | |
497 | Otherwise, permission is denied. | |
498 | .TP 5 | |
499 | Sockets and Address Families | |
500 | .IP | |
501 | A socket is an endpoint for communication between processes. | |
502 | Each socket has queues for sending and receiving data. | |
503 | .IP | |
504 | Sockets are typed according to their communications properties. | |
505 | These properties include whether messages sent and received | |
506 | at a socket require the name of the partner, whether communication | |
507 | is reliable, the format used in naming message recipients, etc. | |
508 | .IP | |
509 | Each instance of the system supports some | |
510 | collection of socket types; consult | |
511 | .IR socket (2) | |
512 | for more information about the types available and | |
513 | their properties. | |
514 | .IP | |
515 | Each instance of the system supports some number of sets of | |
516 | communications protocols. Each protocol set supports addresses | |
517 | of a certain format. An Address Family is the set of addresses | |
518 | for a specific group of protocols. Each socket has an address | |
519 | chosen from the address family in which the socket was created. | |
520 | .SH SEE ALSO | |
521 | intro(3), perror(3) |