Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" Copyright (c) 1980, 1983, 1986, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
dc71b7ab | 12 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
13 | .\" may be used to endorse or promote products derived from this software |
14 | .\" without specific prior written permission. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" @(#)intro.2 8.5 (Berkeley) 2/27/95 | |
002b43ce | 29 | .\" $FreeBSD: src/lib/libc/sys/intro.2,v 1.48 2007/01/09 00:28:14 imp Exp $ |
984263bc | 30 | .\" |
c907b81a | 31 | .Dd August 8, 2021 |
984263bc MD |
32 | .Dt INTRO 2 |
33 | .Os | |
34 | .Sh NAME | |
35 | .Nm intro | |
36 | .Nd introduction to system calls and error numbers | |
37 | .Sh LIBRARY | |
38 | .Lb libc | |
39 | .Sh SYNOPSIS | |
40 | .In errno.h | |
41 | .Sh DESCRIPTION | |
42 | This section provides an overview of the system calls, | |
43 | their error returns, and other common definitions and concepts. | |
44 | .\".Pp | |
45 | .\".Sy System call restart | |
46 | .\".Pp | |
002b43ce | 47 | .\"(more later...) |
984263bc MD |
48 | .Sh RETURN VALUES |
49 | Nearly all of the system calls provide an error number referenced via | |
834b6336 | 50 | the external identifier |
f60c028d | 51 | .Va errno . |
984263bc | 52 | This identifier is defined in |
44cb301e | 53 | .In errno.h |
984263bc MD |
54 | as |
55 | .Pp | |
834b6336 SS |
56 | .Dl extern __thread int errno; |
57 | .Dl static __inline int * __error(void); | |
984263bc MD |
58 | .Dl #define errno (* __error()) |
59 | .Pp | |
834b6336 SS |
60 | This means there exists a thread-local |
61 | .Va errno | |
62 | variable, though it is shadowed by the inline | |
b564836d | 63 | .Fn __error |
834b6336 SS |
64 | function to allow compilation of source code which |
65 | erroneously itself declares | |
66 | .Va errno | |
67 | as | |
b564836d | 68 | .Vt extern int errno; |
834b6336 SS |
69 | which collides with the thread-local declaration. |
70 | The | |
b564836d | 71 | .Fn __error |
834b6336 | 72 | function returns a pointer the thread specific |
984263bc | 73 | .Va errno |
002b43ce PA |
74 | variable. |
75 | As it is defined | |
b564836d | 76 | .Vt inline , |
834b6336 SS |
77 | it will compile to a no-op, effectively producing |
78 | the same code as if the define wouldn't exist. | |
984263bc MD |
79 | .Pp |
80 | When a system call detects an error, | |
81 | it returns an integer value | |
82 | indicating failure (usually -1) | |
83 | and sets the variable | |
84 | .Va errno | |
85 | accordingly. | |
b564836d SW |
86 | (This allows interpretation of the failure on receiving |
87 | a -1 and to take action accordingly.) | |
984263bc MD |
88 | Successful calls never set |
89 | .Va errno ; | |
90 | once set, it remains until another error occurs. | |
91 | It should only be examined after an error. | |
92 | Note that a number of system calls overload the meanings of these | |
93 | error numbers, and that the meanings must be interpreted according | |
94 | to the type and circumstances of the call. | |
95 | .Pp | |
96 | The following is a complete list of the errors and their | |
97 | names as given in | |
44cb301e | 98 | .In sys/errno.h . |
984263bc MD |
99 | .Bl -hang -width Ds |
100 | .It Er 0 Em "Undefined error: 0" . | |
101 | Not used. | |
102 | .It Er 1 EPERM Em "Operation not permitted" . | |
103 | An attempt was made to perform an operation limited to processes | |
104 | with appropriate privileges or to the owner of a file or other | |
105 | resources. | |
106 | .It Er 2 ENOENT Em "No such file or directory" . | |
107 | A component of a specified pathname did not exist, or the | |
108 | pathname was an empty string. | |
109 | .It Er 3 ESRCH Em "No such process" . | |
110 | No process could be found corresponding to that specified by the given | |
111 | process ID. | |
112 | .It Er 4 EINTR Em "Interrupted system call" . | |
113 | An asynchronous signal (such as | |
114 | .Dv SIGINT | |
115 | or | |
116 | .Dv SIGQUIT ) | |
117 | was caught by the process during the execution of an interruptible | |
118 | function. | |
119 | If the signal handler performs a normal return, the | |
002b43ce | 120 | interrupted system call will seem to have returned the error condition. |
984263bc MD |
121 | .It Er 5 EIO Em "Input/output error" . |
122 | Some physical input or output error occurred. | |
123 | This error will not be reported until a subsequent operation on the same file | |
124 | descriptor and may be lost (over written) by any subsequent errors. | |
125 | .It Er 6 ENXIO Em "Device not configured" . | |
126 | Input or output on a special file referred to a device that did not | |
127 | exist, or | |
128 | made a request beyond the limits of the device. | |
129 | This error may also occur when, for example, | |
130 | a tape drive is not online or no disk pack is | |
131 | loaded on a drive. | |
132 | .It Er 7 E2BIG Em "Argument list too long" . | |
133 | The number of bytes used for the argument and environment | |
134 | list of the new process exceeded the current limit | |
002b43ce | 135 | .Dv ( NCARGS |
984263bc | 136 | in |
44cb301e | 137 | .In sys/param.h ) . |
984263bc MD |
138 | .It Er 8 ENOEXEC Em "Exec format error" . |
139 | A request was made to execute a file | |
140 | that, although it has the appropriate permissions, | |
141 | was not in the format required for an | |
142 | executable file. | |
143 | .It Er 9 EBADF Em "Bad file descriptor" . | |
144 | A file descriptor argument was out of range, referred to no open file, | |
145 | or a read (write) request was made to a file that was only open for | |
146 | writing (reading). | |
984263bc MD |
147 | .It Er 10 ECHILD Em "\&No child processes" . |
148 | A | |
149 | .Xr wait 2 | |
150 | or | |
151 | .Xr waitpid 2 | |
152 | function was executed by a process that had no existing or unwaited-for | |
153 | child processes. | |
154 | .It Er 11 EDEADLK Em "Resource deadlock avoided" . | |
155 | An attempt was made to lock a system resource that | |
156 | would have resulted in a deadlock situation. | |
157 | .It Er 12 ENOMEM Em "Cannot allocate memory" . | |
158 | The new process image required more memory than was allowed by the hardware | |
159 | or by system-imposed memory management constraints. | |
160 | A lack of swap space is normally temporary; however, | |
161 | a lack of core is not. | |
162 | Soft limits may be increased to their corresponding hard limits. | |
163 | .It Er 13 EACCES Em "Permission denied" . | |
164 | An attempt was made to access a file in a way forbidden | |
165 | by its file access permissions. | |
166 | .It Er 14 EFAULT Em "Bad address" . | |
167 | The system detected an invalid address in attempting to | |
168 | use an argument of a call. | |
169 | .It Er 15 ENOTBLK Em "Block device required" . | |
170 | A block device operation was attempted on a non-block device or file. | |
171 | .It Er 16 EBUSY Em "Device busy" . | |
172 | An attempt to use a system resource which was in use at the time | |
173 | in a manner which would have conflicted with the request. | |
174 | .It Er 17 EEXIST Em "File exists" . | |
175 | An existing file was mentioned in an inappropriate context, | |
176 | for instance, as the new link name in a | |
177 | .Xr link 2 | |
002b43ce | 178 | system call. |
984263bc MD |
179 | .It Er 18 EXDEV Em "Cross-device link" . |
180 | A hard link to a file on another file system | |
181 | was attempted. | |
182 | .It Er 19 ENODEV Em "Operation not supported by device" . | |
183 | An attempt was made to apply an inappropriate | |
184 | function to a device, | |
185 | for example, | |
186 | trying to read a write-only device such as a printer. | |
187 | .It Er 20 ENOTDIR Em "Not a directory" . | |
188 | A component of the specified pathname existed, but it was | |
189 | not a directory, when a directory was expected. | |
190 | .It Er 21 EISDIR Em "Is a directory" . | |
191 | An attempt was made to open a directory with write mode specified. | |
192 | .It Er 22 EINVAL Em "Invalid argument" . | |
193 | Some invalid argument was supplied. | |
194 | (For example, | |
195 | specifying an undefined signal to a | |
196 | .Xr signal 3 | |
002b43ce PA |
197 | function |
198 | or a | |
984263bc | 199 | .Xr kill 2 |
002b43ce | 200 | system call). |
984263bc MD |
201 | .It Er 23 ENFILE Em "Too many open files in system" . |
202 | Maximum number of file descriptors allowable on the system | |
203 | has been reached and a requests for an open cannot be satisfied | |
204 | until at least one has been closed. | |
205 | .It Er 24 EMFILE Em "Too many open files" . | |
145d1c2b SW |
206 | (As released, the limit on the number of |
207 | open files per process is 64.) | |
984263bc MD |
208 | The |
209 | .Xr getdtablesize 2 | |
002b43ce | 210 | system call will obtain the current limit. |
984263bc MD |
211 | .It Er 25 ENOTTY Em "Inappropriate ioctl for device" . |
212 | A control function (see | |
213 | .Xr ioctl 2 ) | |
214 | was attempted for a file or | |
215 | special device for which the operation was inappropriate. | |
216 | .It Er 26 ETXTBSY Em "Text file busy" . | |
217 | The new process was a pure procedure (shared text) file | |
218 | which was open for writing by another process, or | |
219 | while the pure procedure file was being executed an | |
220 | .Xr open 2 | |
221 | call requested write access. | |
222 | .It Er 27 EFBIG Em "File too large" . | |
002b43ce | 223 | The size of a file exceeded the maximum. |
984263bc MD |
224 | .It Er 28 ENOSPC Em "No space left on device" . |
225 | A | |
226 | .Xr write 2 | |
227 | to an ordinary file, the creation of a | |
228 | directory or symbolic link, or the creation of a directory | |
229 | entry failed because no more disk blocks were available | |
230 | on the file system, or the allocation of an inode for a newly | |
231 | created file failed because no more inodes were available | |
232 | on the file system. | |
233 | .It Er 29 ESPIPE Em "Illegal seek" . | |
234 | An | |
235 | .Xr lseek 2 | |
002b43ce | 236 | system call was issued on a socket, pipe or |
984263bc MD |
237 | .Tn FIFO . |
238 | .It Er 30 EROFS Em "Read-only file system" . | |
239 | An attempt was made to modify a file or directory | |
240 | on a file system that was read-only at the time. | |
241 | .It Er 31 EMLINK Em "Too many links" . | |
242 | Maximum allowable hard links to a single file has been exceeded (limit | |
243 | of 32767 hard links per file). | |
244 | .It Er 32 EPIPE Em "Broken pipe" . | |
245 | A write on a pipe, socket or | |
246 | .Tn FIFO | |
247 | for which there is no process | |
248 | to read the data. | |
249 | .It Er 33 EDOM Em "Numerical argument out of domain" . | |
250 | A numerical input argument was outside the defined domain of the mathematical | |
251 | function. | |
252 | .It Er 34 ERANGE Em "Result too large" . | |
253 | A numerical result of the function was too large to fit in the | |
254 | available space (perhaps exceeded precision). | |
255 | .It Er 35 EAGAIN Em "Resource temporarily unavailable" . | |
256 | This is a temporary condition and later calls to the | |
257 | same routine may complete normally. | |
258 | .It Er 36 EINPROGRESS Em "Operation now in progress" . | |
259 | An operation that takes a long time to complete (such as | |
260 | a | |
261 | .Xr connect 2 ) | |
262 | was attempted on a non-blocking object (see | |
263 | .Xr fcntl 2 ) . | |
264 | .It Er 37 EALREADY Em "Operation already in progress" . | |
265 | An operation was attempted on a non-blocking object that already | |
266 | had an operation in progress. | |
267 | .It Er 38 ENOTSOCK Em "Socket operation on non-socket" . | |
268 | Self-explanatory. | |
269 | .It Er 39 EDESTADDRREQ Em "Destination address required" . | |
270 | A required address was omitted from an operation on a socket. | |
271 | .It Er 40 EMSGSIZE Em "Message too long" . | |
272 | A message sent on a socket was larger than the internal message buffer | |
273 | or some other network limit. | |
274 | .It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" . | |
275 | A protocol was specified that does not support the semantics of the | |
276 | socket type requested. | |
277 | For example, you cannot use the | |
278 | .Tn ARPA | |
279 | Internet | |
280 | .Tn UDP | |
281 | protocol with type | |
282 | .Dv SOCK_STREAM . | |
283 | .It Er 42 ENOPROTOOPT Em "Protocol not available" . | |
284 | A bad option or level was specified in a | |
285 | .Xr getsockopt 2 | |
286 | or | |
287 | .Xr setsockopt 2 | |
288 | call. | |
289 | .It Er 43 EPROTONOSUPPORT Em "Protocol not supported" . | |
290 | The protocol has not been configured into the | |
291 | system or no implementation for it exists. | |
292 | .It Er 44 ESOCKTNOSUPPORT Em "Socket type not supported" . | |
293 | The support for the socket type has not been configured into the | |
294 | system or no implementation for it exists. | |
295 | .It Er 45 EOPNOTSUPP Em "Operation not supported" . | |
296 | The attempted operation is not supported for the type of object referenced. | |
297 | Usually this occurs when a file descriptor refers to a file or socket | |
298 | that cannot support this operation, | |
299 | for example, trying to | |
300 | .Em accept | |
301 | a connection on a datagram socket. | |
302 | .It Er 46 EPFNOSUPPORT Em "Protocol family not supported" . | |
303 | The protocol family has not been configured into the | |
304 | system or no implementation for it exists. | |
305 | .It Er 47 EAFNOSUPPORT Em "Address family not supported by protocol family" . | |
306 | An address incompatible with the requested protocol was used. | |
002b43ce | 307 | For example, you should not necessarily expect to be able to use |
984263bc MD |
308 | .Tn NS |
309 | addresses with | |
310 | .Tn ARPA | |
311 | Internet protocols. | |
312 | .It Er 48 EADDRINUSE Em "Address already in use" . | |
313 | Only one usage of each address is normally permitted. | |
984263bc MD |
314 | .It Er 49 EADDRNOTAVAIL Em "Cannot assign requested address" . |
315 | Normally results from an attempt to create a socket with an | |
316 | address not on this machine. | |
317 | .It Er 50 ENETDOWN Em "Network is down" . | |
318 | A socket operation encountered a dead network. | |
319 | .It Er 51 ENETUNREACH Em "Network is unreachable" . | |
320 | A socket operation was attempted to an unreachable network. | |
321 | .It Er 52 ENETRESET Em "Network dropped connection on reset" . | |
322 | The host you were connected to crashed and rebooted. | |
323 | .It Er 53 ECONNABORTED Em "Software caused connection abort" . | |
324 | A connection abort was caused internal to your host machine. | |
325 | .It Er 54 ECONNRESET Em "Connection reset by peer" . | |
002b43ce PA |
326 | A connection was forcibly closed by a peer. |
327 | This normally | |
984263bc MD |
328 | results from a loss of the connection on the remote socket |
329 | due to a timeout or a reboot. | |
330 | .It Er 55 ENOBUFS Em "\&No buffer space available" . | |
331 | An operation on a socket or pipe was not performed because | |
332 | the system lacked sufficient buffer space or because a queue was full. | |
333 | .It Er 56 EISCONN Em "Socket is already connected" . | |
334 | A | |
335 | .Xr connect 2 | |
336 | request was made on an already connected socket; or, | |
337 | a | |
338 | .Xr sendto 2 | |
339 | or | |
340 | .Xr sendmsg 2 | |
341 | request on a connected socket specified a destination | |
342 | when already connected. | |
343 | .It Er 57 ENOTCONN Em "Socket is not connected" . | |
344 | An request to send or receive data was disallowed because | |
345 | the socket was not connected and (when sending on a datagram socket) | |
346 | no address was supplied. | |
347 | .It Er 58 ESHUTDOWN Em "Cannot send after socket shutdown" . | |
348 | A request to send data was disallowed because the socket | |
349 | had already been shut down with a previous | |
350 | .Xr shutdown 2 | |
351 | call. | |
352 | .It Er 60 ETIMEDOUT Em "Operation timed out" . | |
353 | A | |
354 | .Xr connect 2 | |
355 | or | |
356 | .Xr send 2 | |
357 | request failed because the connected party did not | |
002b43ce PA |
358 | properly respond after a period of time. |
359 | (The timeout | |
984263bc MD |
360 | period is dependent on the communication protocol.) |
361 | .It Er 61 ECONNREFUSED Em "Connection refused" . | |
362 | No connection could be made because the target machine actively | |
002b43ce PA |
363 | refused it. |
364 | This usually results from trying to connect | |
984263bc MD |
365 | to a service that is inactive on the foreign host. |
366 | .It Er 62 ELOOP Em "Too many levels of symbolic links" . | |
367 | A path name lookup involved more than 32 | |
368 | .Pq Dv MAXSYMLINKS | |
369 | symbolic links. | |
370 | .It Er 63 ENAMETOOLONG Em "File name too long" . | |
002b43ce PA |
371 | A component of a path name exceeded |
372 | .Brq Dv NAME_MAX | |
984263bc | 373 | characters, or an entire |
002b43ce PA |
374 | path name exceeded |
375 | .Brq Dv PATH_MAX | |
984263bc | 376 | characters. |
002b43ce PA |
377 | (See also the description of |
378 | .Dv _PC_NO_TRUNC | |
379 | in | |
380 | .Xr pathconf 2 . ) | |
984263bc MD |
381 | .It Er 64 EHOSTDOWN Em "Host is down" . |
382 | A socket operation failed because the destination host was down. | |
383 | .It Er 65 EHOSTUNREACH Em "No route to host" . | |
384 | A socket operation was attempted to an unreachable host. | |
385 | .It Er 66 ENOTEMPTY Em "Directory not empty" . | |
386 | A directory with entries other than | |
387 | .Ql .\& | |
388 | and | |
389 | .Ql ..\& | |
390 | was supplied to a remove directory or rename call. | |
391 | .It Er 67 EPROCLIM Em "Too many processes" . | |
392 | .It Er 68 EUSERS Em "Too many users" . | |
393 | The quota system ran out of table entries. | |
394 | .It Er 69 EDQUOT Em "Disc quota exceeded" . | |
395 | A | |
396 | .Xr write 2 | |
397 | to an ordinary file, the creation of a | |
398 | directory or symbolic link, or the creation of a directory | |
399 | entry failed because the user's quota of disk blocks was | |
400 | exhausted, or the allocation of an inode for a newly | |
401 | created file failed because the user's quota of inodes | |
402 | was exhausted. | |
403 | .It Er 70 ESTALE Em "Stale NFS file handle" . | |
404 | An attempt was made to access an open file (on an | |
405 | .Tn NFS | |
002b43ce | 406 | file system) |
984263bc MD |
407 | which is now unavailable as referenced by the file descriptor. |
408 | This may indicate the file was deleted on the | |
409 | .Tn NFS | |
410 | server or some | |
411 | other catastrophic event occurred. | |
412 | .It Er 72 EBADRPC Em "RPC struct is bad" . | |
413 | Exchange of | |
414 | .Tn RPC | |
415 | information was unsuccessful. | |
416 | .It Er 73 ERPCMISMATCH Em "RPC version wrong" . | |
417 | The version of | |
418 | .Tn RPC | |
419 | on the remote peer is not compatible with | |
420 | the local version. | |
421 | .It Er 74 EPROGUNAVAIL Em "RPC prog. not avail" . | |
422 | The requested program is not registered on the remote host. | |
423 | .It Er 75 EPROGMISMATCH Em "Program version wrong" . | |
424 | The requested version of the program is not available | |
425 | on the remote host | |
426 | .Pq Tn RPC . | |
427 | .It Er 76 EPROCUNAVAIL Em "Bad procedure for program" . | |
428 | An | |
429 | .Tn RPC | |
002b43ce | 430 | call was attempted for a procedure which does not exist |
984263bc MD |
431 | in the remote program. |
432 | .It Er 77 ENOLCK Em "No locks available" . | |
433 | A system-imposed limit on the number of simultaneous file | |
434 | locks was reached. | |
435 | .It Er 78 ENOSYS Em "Function not implemented" . | |
436 | Attempted a system call that is not available on this | |
437 | system. | |
438 | .It Er 79 EFTYPE Em "Inappropriate file type or format" . | |
439 | The file was the wrong type for the operation, or a data file had | |
440 | the wrong format. | |
441 | .It Er 80 EAUTH Em "Authentication error" . | |
442 | Attempted to use an invalid authentication ticket to mount a | |
443 | .Tn NFS | |
002b43ce | 444 | file system. |
984263bc MD |
445 | .It Er 81 ENEEDAUTH Em "Need authenticator" . |
446 | An authentication ticket must be obtained before the given | |
447 | .Tn NFS | |
002b43ce | 448 | file system may be mounted. |
984263bc MD |
449 | .It Er 82 EIDRM Em "Identifier removed" . |
450 | An IPC identifier was removed while the current process was waiting on it. | |
451 | .It Er 83 ENOMSG Em "No message of desired type" . | |
452 | An IPC message queue does not contain a message of the desired type, or a | |
453 | message catalog does not contain the requested message. | |
454 | .It Er 84 EOVERFLOW Em "Value too large to be stored in data type" . | |
455 | A numerical result of the function was too large to be stored in the caller | |
456 | provided space. | |
457 | .It Er 85 ECANCELED Em "Operation canceled" . | |
458 | The scheduled operation was canceled. | |
459 | .It Er 86 EILSEQ Em "Illegal byte sequence" . | |
460 | While decoding a multibyte character the function came along an | |
461 | invalid or an incomplete sequence of bytes or the given wide | |
462 | character is invalid. | |
002b43ce PA |
463 | .It Er 87 ENOATTR Em "Attribute not found" . |
464 | The specified extended attribute does not exist. | |
465 | .It Er 88 EDOOFUS Em "Programming error" . | |
466 | A function or API is being abused in a way which could only be detected | |
467 | at run-time. | |
a62eeffb | 468 | .It Er 89 EBADMSG Em "Bad message" . |
469 | A corrupted message was detected. | |
470 | .It Er 90 EMULTIHOP Em "Multihop attempted" . | |
471 | This error code is unused, but present for compatibility with other systems. | |
472 | .It Er 91 ENOLINK Em "Link has been severed" . | |
473 | This error code is unused, but present for compatibility with other systems. | |
474 | .It Er 92 EPROTO Em "Protocol error" . | |
475 | A device or socket encountered an unrecoverable protocol error. | |
476 | .It Er 93 ENOMEDIUM Em "No medium found" . | |
477 | This error code is unused, but present for compatibility with other systems. | |
c907b81a SW |
478 | .It Er 94 ENOTRECOVERABLE Em "State not recoverable" . |
479 | The state protected by a robust mutex is not recoverable. | |
480 | .It Er 95 EOWNERDEAD Em "Previous owner died" . | |
481 | The owner of a robust mutex terminated while holding the mutex lock. | |
984263bc MD |
482 | .El |
483 | .Sh DEFINITIONS | |
484 | .Bl -tag -width Ds | |
002b43ce | 485 | .It Process ID . |
984263bc | 486 | Each active process in the system is uniquely identified by a non-negative |
002b43ce PA |
487 | integer called a process ID. |
488 | The range of this ID is from 0 to 99999. | |
489 | .It Parent process ID | |
490 | A new process is created by a currently active process (see | |
984263bc MD |
491 | .Xr fork 2 ) . |
492 | The parent process ID of a process is initially the process ID of its creator. | |
493 | If the creating process exits, | |
494 | the parent process ID of each child is set to the ID of a system process, | |
495 | .Xr init 8 . | |
002b43ce | 496 | .It Process Group |
984263bc | 497 | Each active process is a member of a process group that is identified by |
002b43ce PA |
498 | a non-negative integer called the process group ID. |
499 | This is the process | |
500 | ID of the group leader. | |
501 | This grouping permits the signaling of related | |
984263bc MD |
502 | processes (see |
503 | .Xr termios 4 ) | |
504 | and the job control mechanisms of | |
505 | .Xr csh 1 . | |
506 | .It Session | |
507 | A session is a set of one or more process groups. | |
508 | A session is created by a successful call to | |
509 | .Xr setsid 2 , | |
510 | which causes the caller to become the only member of the only process | |
511 | group in the new session. | |
512 | .It Session leader | |
513 | A process that has created a new session by a successful call to | |
514 | .Xr setsid 2 , | |
515 | is known as a session leader. | |
516 | Only a session leader may acquire a terminal as its controlling terminal (see | |
517 | .Xr termios 4 ) . | |
518 | .It Controlling process | |
519 | A session leader with a controlling terminal is a controlling process. | |
520 | .It Controlling terminal | |
521 | A terminal that is associated with a session is known as the controlling | |
522 | terminal for that session and its members. | |
002b43ce | 523 | .It "Terminal Process Group ID" |
984263bc MD |
524 | A terminal may be acquired by a session leader as its controlling terminal. |
525 | Once a terminal is associated with a session, any of the process groups | |
526 | within the session may be placed into the foreground by setting | |
527 | the terminal process group ID to the ID of the process group. | |
528 | This facility is used | |
529 | to arbitrate between multiple jobs contending for the same terminal; | |
530 | (see | |
531 | .Xr csh 1 | |
532 | and | |
533 | .Xr tty 4 ) . | |
002b43ce | 534 | .It "Orphaned Process Group" |
984263bc MD |
535 | A process group is considered to be |
536 | .Em orphaned | |
537 | if it is not under the control of a job control shell. | |
538 | More precisely, a process group is orphaned | |
539 | when none of its members has a parent process that is in the same session | |
540 | as the group, | |
541 | but is in a different process group. | |
542 | Note that when a process exits, the parent process for its children | |
543 | is changed to be | |
544 | .Xr init 8 , | |
545 | which is in a separate session. | |
546 | Not all members of an orphaned process group are necessarily orphaned | |
547 | processes (those whose creating process has exited). | |
548 | The process group of a session leader is orphaned by definition. | |
549 | .It "Real User ID and Real Group ID" | |
550 | Each user on the system is identified by a positive integer | |
551 | termed the real user ID. | |
552 | .Pp | |
553 | Each user is also a member of one or more groups. | |
554 | One of these groups is distinguished from others and | |
002b43ce PA |
555 | used in implementing accounting facilities. |
556 | The positive | |
984263bc MD |
557 | integer corresponding to this distinguished group is termed |
558 | the real group ID. | |
559 | .Pp | |
560 | All processes have a real user ID and real group ID. | |
561 | These are initialized from the equivalent attributes | |
562 | of the process that created it. | |
563 | .It "Effective User Id, Effective Group Id, and Group Access List" | |
564 | Access to system resources is governed by two values: | |
565 | the effective user ID, and the group access list. | |
566 | The first member of the group access list is also known as the | |
567 | effective group ID. | |
568 | (In POSIX.1, the group access list is known as the set of supplementary | |
569 | group IDs, and it is unspecified whether the effective group ID is | |
570 | a member of the list.) | |
571 | .Pp | |
572 | The effective user ID and effective group ID are initially the | |
002b43ce PA |
573 | process's real user ID and real group ID respectively. |
574 | Either | |
984263bc MD |
575 | may be modified through execution of a set-user-ID or set-group-ID |
576 | file (possibly by one its ancestors) (see | |
577 | .Xr execve 2 ) . | |
578 | By convention, the effective group ID (the first member of the group access | |
579 | list) is duplicated, so that the execution of a set-group-ID program | |
580 | does not result in the loss of the original (real) group ID. | |
581 | .Pp | |
582 | The group access list is a set of group IDs | |
002b43ce PA |
583 | used only in determining resource accessibility. |
584 | Access checks | |
984263bc | 585 | are performed as described below in ``File Access Permissions''. |
002b43ce | 586 | .It "Saved Set User ID and Saved Set Group ID" |
984263bc MD |
587 | When a process executes a new file, the effective user ID is set |
588 | to the owner of the file if the file is set-user-ID, and the effective | |
589 | group ID (first element of the group access list) is set to the group | |
590 | of the file if the file is set-group-ID. | |
591 | The effective user ID of the process is then recorded as the saved set-user-ID, | |
592 | and the effective group ID of the process is recorded as the saved set-group-ID. | |
593 | These values may be used to regain those values as the effective user | |
594 | or group ID after reverting to the real ID (see | |
595 | .Xr setuid 2 ) . | |
596 | (In POSIX.1, the saved set-user-ID and saved set-group-ID are optional, | |
597 | and are used in setuid and setgid, but this does not work as desired | |
598 | for the super-user.) | |
002b43ce | 599 | .It Super-user |
984263bc MD |
600 | A process is recognized as a |
601 | .Em super-user | |
602 | process and is granted special privileges if its effective user ID is 0. | |
002b43ce | 603 | .It Descriptor |
984263bc MD |
604 | An integer assigned by the system when a file is referenced |
605 | by | |
606 | .Xr open 2 | |
607 | or | |
608 | .Xr dup 2 , | |
609 | or when a socket is created by | |
610 | .Xr pipe 2 , | |
611 | .Xr socket 2 | |
612 | or | |
613 | .Xr socketpair 2 , | |
614 | which uniquely identifies an access path to that file or socket from | |
615 | a given process or any of its children. | |
002b43ce PA |
616 | .It File Name |
617 | Names consisting of up to | |
618 | .Brq Dv NAME_MAX | |
984263bc MD |
619 | characters may be used to name |
620 | an ordinary file, special file, or directory. | |
621 | .Pp | |
002b43ce PA |
622 | These characters may be arbitrary eight-bit values, |
623 | excluding | |
624 | .Dv NUL | |
625 | .Tn ( ASCII | |
626 | 0) and the | |
984263bc | 627 | .Ql \&/ |
002b43ce PA |
628 | character (slash, |
629 | .Tn ASCII | |
630 | 47). | |
984263bc MD |
631 | .Pp |
632 | Note that it is generally unwise to use | |
633 | .Ql \&* , | |
634 | .Ql \&? , | |
635 | .Ql \&[ | |
636 | or | |
637 | .Ql \&] | |
638 | as part of | |
639 | file names because of the special meaning attached to these characters | |
640 | by the shell. | |
002b43ce | 641 | .It Path Name |
984263bc | 642 | A path name is a |
002b43ce | 643 | .Dv NUL Ns -terminated |
984263bc MD |
644 | character string starting with an |
645 | optional slash | |
646 | .Ql \&/ , | |
647 | followed by zero or more directory names separated | |
648 | by slashes, optionally followed by a file name. | |
002b43ce PA |
649 | The total length of a path name must be less than |
650 | .Brq Dv PATH_MAX | |
984263bc | 651 | characters. |
002b43ce | 652 | (On some systems, this limit may be infinite.) |
984263bc MD |
653 | .Pp |
654 | If a path name begins with a slash, the path search begins at the | |
655 | .Em root | |
656 | directory. | |
657 | Otherwise, the search begins from the current working directory. | |
002b43ce PA |
658 | A slash by itself names the root directory. |
659 | An empty | |
984263bc | 660 | pathname refers to the current directory. |
002b43ce | 661 | .It Directory |
984263bc MD |
662 | A directory is a special type of file that contains entries |
663 | that are references to other files. | |
002b43ce PA |
664 | Directory entries are called links. |
665 | By convention, a directory | |
984263bc MD |
666 | contains at least two links, |
667 | .Ql .\& | |
668 | and | |
669 | .Ql \&.. , | |
670 | referred to as | |
671 | .Em dot | |
672 | and | |
673 | .Em dot-dot | |
002b43ce PA |
674 | respectively. |
675 | Dot refers to the directory itself and | |
984263bc MD |
676 | dot-dot refers to its parent directory. |
677 | .It "Root Directory and Current Working Directory" | |
678 | Each process has associated with it a concept of a root directory | |
679 | and a current working directory for the purpose of resolving path | |
002b43ce PA |
680 | name searches. |
681 | A process's root directory need not be the root | |
984263bc | 682 | directory of the root file system. |
002b43ce | 683 | .It File Access Permissions |
984263bc MD |
684 | Every file in the file system has a set of access permissions. |
685 | These permissions are used in determining whether a process | |
686 | may perform a requested operation on the file (such as opening | |
002b43ce PA |
687 | a file for writing). |
688 | Access permissions are established at the | |
689 | time a file is created. | |
690 | They may be changed at some later time | |
984263bc MD |
691 | through the |
692 | .Xr chmod 2 | |
693 | call. | |
694 | .Pp | |
695 | File access is broken down according to whether a file may be: read, | |
002b43ce PA |
696 | written, or executed. |
697 | Directory files use the execute | |
984263bc MD |
698 | permission to control if the directory may be searched. |
699 | .Pp | |
700 | File access permissions are interpreted by the system as | |
701 | they apply to three different classes of users: the owner | |
702 | of the file, those users in the file's group, anyone else. | |
703 | Every file has an independent set of access permissions for | |
002b43ce PA |
704 | each of these classes. |
705 | When an access check is made, the system | |
984263bc MD |
706 | decides if permission should be granted by checking the access |
707 | information applicable to the caller. | |
708 | .Pp | |
709 | Read, write, and execute/search permissions on | |
710 | a file are granted to a process if: | |
711 | .Pp | |
712 | The process's effective user ID is that of the super-user. | |
713 | (Note: | |
714 | even the super-user cannot execute a non-executable file.) | |
715 | .Pp | |
716 | The process's effective user ID matches the user ID of the owner | |
717 | of the file and the owner permissions allow the access. | |
718 | .Pp | |
719 | The process's effective user ID does not match the user ID of the | |
720 | owner of the file, and either the process's effective | |
721 | group ID matches the group ID | |
722 | of the file, or the group ID of the file is in | |
723 | the process's group access list, | |
724 | and the group permissions allow the access. | |
725 | .Pp | |
726 | Neither the effective user ID nor effective group ID | |
727 | and group access list of the process | |
728 | match the corresponding user ID and group ID of the file, | |
729 | but the permissions for ``other users'' allow access. | |
730 | .Pp | |
731 | Otherwise, permission is denied. | |
002b43ce | 732 | .It Sockets and Address Families |
984263bc MD |
733 | A socket is an endpoint for communication between processes. |
734 | Each socket has queues for sending and receiving data. | |
735 | .Pp | |
736 | Sockets are typed according to their communications properties. | |
737 | These properties include whether messages sent and received | |
738 | at a socket require the name of the partner, whether communication | |
739 | is reliable, the format used in naming message recipients, etc. | |
740 | .Pp | |
741 | Each instance of the system supports some | |
742 | collection of socket types; consult | |
743 | .Xr socket 2 | |
744 | for more information about the types available and | |
745 | their properties. | |
746 | .Pp | |
747 | Each instance of the system supports some number of sets of | |
002b43ce PA |
748 | communications protocols. |
749 | Each protocol set supports addresses of a certain format. | |
750 | An Address Family is the set of addresses for a specific group of protocols. | |
751 | Each socket has an address | |
984263bc MD |
752 | chosen from the address family in which the socket was created. |
753 | .El | |
754 | .Sh SEE ALSO | |
755 | .Xr intro 3 , | |
3f066efb SW |
756 | .Xr perror 3 , |
757 | .Xr errno 9 |