Commit | Line | Data |
---|---|---|
aaea5b2e KB |
1 | .\" Copyright (c) 1993, 1980198319861991 |
2 | .\" The Regents of the University of California. All rights reserved. | |
5822f3c2 | 3 | .\" |
931b8415 | 4 | .\" %sccs.include.redist.man% |
5822f3c2 | 5 | .\" |
0dc293bd | 6 | .\" @(#)intro.2 8.2 (Berkeley) %G% |
931b8415 CL |
7 | .\" |
8 | .Dd | |
9 | .Dt INTRO 2 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm intro | |
13 | .Nd introduction to system calls and error numbers | |
14 | .Sh SYNOPSIS | |
a67e2645 | 15 | .Fd #include <sys/errno.h> |
931b8415 | 16 | .Sh DESCRIPTION |
f9238312 MK |
17 | This section provides an overview of the system calls, |
18 | their error returns, and other common definitions and concepts. | |
931b8415 CL |
19 | .\".Pp |
20 | .\".Sy System call restart | |
21 | .\".Pp | |
f9238312 | 22 | .\"<more later...> |
931b8415 CL |
23 | .Sh DIAGNOSTICS |
24 | Nearly all of the system calls provide an error number in the external | |
25 | variable | |
26 | .Va errno , | |
27 | which is defined as: | |
28 | .Pp | |
29 | .Dl extern int errno | |
30 | .Pp | |
31 | When a system call detects an error, | |
32 | it returns an integer value | |
33 | indicating failure (usually -1) | |
34 | and sets the variable | |
35 | .Va errno | |
36 | accordingly. | |
37 | <This allows interpretation of the failure on receiving | |
38 | a -1 and to take action accordingly.> | |
39 | Successful calls never set | |
40 | .Va errno ; | |
41 | once set, it remains until another error occurs. | |
42 | It should only be examined after an error. | |
91409caa MK |
43 | Note that a number of system calls overload the meanings of these |
44 | error numbers, and that the meanings must be interpreted according | |
45 | to the type and circumstances of the call. | |
931b8415 | 46 | .Pp |
5e1f9d48 KM |
47 | The following is a complete list of the errors and their |
48 | names as given in | |
931b8415 CL |
49 | .Aq Pa sys/errno.h . |
50 | .Bl -hang -width Ds | |
51 | .It Er 0 Em "Error 0" . | |
52 | Not used. | |
53 | .It Er 1 EPERM Em "Operation not permitted . | |
54 | An attempt was made to perform an operation limited to processes | |
55 | with appropriate privileges or to the owner of a file or other | |
56 | resources. | |
57 | .It Er 2 ENOENT Em "No such file or directory" . | |
58 | A component of a specified pathname did not exist, or the | |
59 | pathname was an empty string. | |
60 | .It Er 3 ESRCH Em "No such process" . | |
61 | No process could be found corresponding to that specified by the given | |
62 | process ID. | |
63 | .It Er 4 EINTR Em "Interrupted function call" . | |
64 | An asynchronous signal (such as | |
65 | .Dv SIGINT | |
5822f3c2 | 66 | or |
931b8415 CL |
67 | .Dv SIGQUIT ) |
68 | was caught by the process during the execution of an interruptible | |
69 | function. If the signal handler performs a normal return, the | |
a67e2645 | 70 | interrupted function call will seem to have returned the error condition. |
931b8415 CL |
71 | .It Er 5 EIO Em "Input/output error" . |
72 | Some physical input or output error occurred. | |
73 | This error not be reported until a subsequent operation on the same file | |
74 | descriptor and may be lost (over written) by any subsequent errors. | |
75 | .It Er 6 ENXIO Em "\&No such device or address" . | |
76 | Input or output on a special file referred to a device that did not | |
77 | exist, or | |
78 | made a request beyond the limits of the device. | |
79 | This error may also occur when, for example, | |
80 | a tape drive is not online or no disk pack is | |
81 | is loaded on a drive. | |
82 | .It Er 7 E2BIG Em "Arg list too long" . | |
83 | The number of bytes used for the argument and environment | |
84 | list of the new process exceeded the current limit | |
85 | of 20480 bytes | |
86 | .Pf ( Dv NCARGS | |
87 | in | |
88 | .Aq Pa sys/param.h ) . | |
89 | .It Er 8 ENOEXEC Em "Exec format error" . | |
90 | A request was made to execute a file | |
750588ad | 91 | that, although it has the appropriate permissions, |
931b8415 CL |
92 | was not in the format required for an |
93 | executable file. | |
94 | .It Er 9 EBADF Em "Bad file descriptor" . | |
95 | A file descriptor argument was out of range, referred to no open file, | |
96 | or a read (write) request was made to a file that was only open for | |
97 | writing (reading). | |
98 | .It Er 10 ECHILD Em "\&No child processes" . | |
99 | A | |
100 | .Xr wait | |
101 | or | |
102 | .Xr waitpid | |
103 | function was executed by a process that had no existing or unwaited-for | |
104 | child processes. | |
105 | .It Er 11 EDEADLK Em "Resource deadlock avoided" . | |
c8051adb TH |
106 | An attempt was made to lock a system resource that |
107 | would have resulted in a deadlock situation. | |
a67e2645 | 108 | .It Er 12 ENOMEM Em "Cannot allocate memory" . |
931b8415 CL |
109 | The new process image required more memory than was allowed by the hardware |
110 | or by system-imposed memory management constraints. | |
111 | A lack of swap space is normally temporary; however, | |
112 | a lack of core is not. | |
91409caa | 113 | Soft limits may be increased to their corresponding hard limits. |
931b8415 | 114 | .It Er 13 EACCES Em "Permission denied" . |
5822f3c2 | 115 | An attempt was made to access a file in a way forbidden |
931b8415 CL |
116 | by its file access permissions. |
117 | .It Er 14 EFAULT Em "Bad address" . | |
118 | The system detected an invalid address in attempting to | |
119 | use an argument of a call. | |
120 | .It Er 15 ENOTBLK Em "Not a block device" . | |
121 | A block device operation was attempted on a non-block device or file. | |
122 | .It Er 16 EBUSY Em "Resource busy" . | |
123 | An attempt to use a system resource which was in use at the time | |
124 | in a manner which would have conflicted with the request. | |
125 | .It Er 17 EEXIST Em "File exists" . | |
5822f3c2 | 126 | An existing file was mentioned in an inappropriate context, |
931b8415 CL |
127 | for instance, as the new link name in a |
128 | .Xr link | |
129 | function. | |
130 | .It Er 18 EXDEV Em "Improper link" . | |
131 | A hard link to a file on another file system | |
5822f3c2 | 132 | was attempted. |
931b8415 | 133 | .It Er 19 ENODEV Em "Operation not supported by device" . |
5822f3c2 | 134 | An attempt was made to apply an inappropriate |
931b8415 CL |
135 | function to a device, |
136 | for example, | |
137 | trying to read a write-only device such as a printer. | |
138 | .It Er 20 ENOTDIR Em "Not a directory" . | |
139 | A component of the specified pathname existed, but it was | |
140 | not a directory, when a directory was expected. | |
141 | .It Er 21 EISDIR Em "Is a directory" . | |
142 | An attempt was made to open a directory with write mode specified. | |
143 | .It Er 22 EINVAL Em "Invalid argument" . | |
144 | Some invalid argument was supplied. (For example, | |
145 | specifying an undefined signal to a | |
146 | .Xr signal | |
147 | or | |
148 | .Xr kill | |
149 | function). | |
150 | .It Er 23 ENFILE Em "Too many open files in system" . | |
151 | Maximum number of file descriptors allowable on the system | |
152 | has been reached and a requests for an open cannot be satisfied | |
153 | until at least one has been closed. | |
154 | .It Er 24 EMFILE Em "Too many open files" . | |
155 | <As released, the limit on the number of | |
156 | open files per process is 64.> | |
157 | .Xr Getdtablesize 2 | |
91409caa | 158 | will obtain the current limit. |
931b8415 CL |
159 | .It Er 25 ENOTTY Em "Inappropriate ioctl for device" . |
160 | A control function (see | |
161 | .Xr ioctl 2 ) | |
162 | was attempted for a file or | |
163 | special device for which the operation was inappropriate. | |
164 | .It Er 26 ETXTBSY Em "Text file busy" . | |
165 | The new process was a pure procedure (shared text) file | |
166 | which was open for writing by another process, or | |
167 | the pure procedure file was being executed an | |
168 | .Xr open | |
169 | call requested write access. | |
170 | .It Er 27 EFBIG Em "File too large" . | |
5822f3c2 | 171 | The size of a file exceeded the maximum (about |
91409caa MK |
172 | .if t 2\u\s-231\s+2\d |
173 | .if n 2.1E9 | |
5822f3c2 | 174 | bytes). |
931b8415 | 175 | .It Er 28 ENOSPC Em "Device out of space" . |
fd690c8b | 176 | A |
931b8415 | 177 | .Xr write |
fd690c8b KM |
178 | to an ordinary file, the creation of a |
179 | directory or symbolic link, or the creation of a directory | |
180 | entry failed because no more disk blocks are available | |
181 | on the file system, or the allocation of an inode for a newly | |
182 | created file failed because no more inodes are available | |
183 | on the file system. | |
931b8415 | 184 | .It Er 29 ESPIPE Em "Illegal seek" . |
5822f3c2 | 185 | An |
931b8415 CL |
186 | .Xr lseek |
187 | function was issued on a socket, pipe or | |
188 | .Tn FIFO . | |
189 | .It Er 30 EROFS Em "Read-only file system" . | |
190 | An attempt was made to modify a file or directory | |
5822f3c2 | 191 | was made |
931b8415 CL |
192 | on a file system that was read-only at the time. |
193 | .It Er 31 EMLINK Em "Too many links" . | |
194 | Maximum allowable hard links to a single file has been exceeded (limit | |
195 | of 32767 hard links per file). | |
196 | .It Er 32 EPIPE Em "Broken pipe" . | |
197 | A write on a pipe, socket or | |
198 | .Tn FIFO | |
199 | for which there is no process | |
5822f3c2 | 200 | to read the data. |
931b8415 CL |
201 | .It Er 33 EDOM Em "Numerical argument out of domain" . |
202 | A numerical input argument was outside the defined domain of the mathematical | |
203 | function. | |
204 | .It Er 34 ERANGE Em "Numerical result out of range" . | |
205 | A numerical result of the function was to large to fit in the | |
206 | available space (perhaps exceeded precision). | |
207 | .It Er 35 EAGAIN Em "Resource temporarily unavailable" . | |
c8051adb TH |
208 | This is a temporary condition and later calls to the |
209 | same routine may complete normally. | |
931b8415 | 210 | .It Er 36 EINPROGRESS Em "Operation now in progress" . |
750588ad | 211 | An operation that takes a long time to complete (such as |
931b8415 CL |
212 | a |
213 | .Xr connect 2 ) | |
214 | was attempted on a non-blocking object (see | |
215 | .Xr fcntl 2 ) . | |
216 | .It Er 37 EALREADY Em "Operation already in progress" . | |
750588ad | 217 | An operation was attempted on a non-blocking object that already |
5e1f9d48 | 218 | had an operation in progress. |
931b8415 | 219 | .It Er 38 ENOTSOCK Em "Socket operation on non-socket" . |
5e1f9d48 | 220 | Self-explanatory. |
931b8415 | 221 | .It Er 39 EDESTADDRREQ Em "Destination address required" . |
5e1f9d48 | 222 | A required address was omitted from an operation on a socket. |
931b8415 | 223 | .It Er 40 EMSGSIZE Em "Message too long" . |
91409caa MK |
224 | A message sent on a socket was larger than the internal message buffer |
225 | or some other network limit. | |
931b8415 | 226 | .It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" . |
750588ad | 227 | A protocol was specified that does not support the semantics of the |
931b8415 CL |
228 | socket type requested. For example, you cannot use the |
229 | .Tn ARPA | |
230 | Internet | |
231 | .Tn UDP | |
232 | protocol with type | |
233 | .Dv SOCK_STREAM . | |
234 | .It Er 42 ENOPROTOOPT Em "Protocol not available" . | |
91409caa | 235 | A bad option or level was specified in a |
931b8415 | 236 | .Xr getsockopt 2 |
5e1f9d48 | 237 | or |
931b8415 | 238 | .Xr setsockopt 2 |
5e1f9d48 | 239 | call. |
931b8415 | 240 | .It Er 43 EPROTONOSUPPORT Em "Protocol not supported" . |
5e1f9d48 KM |
241 | The protocol has not been configured into the |
242 | system or no implementation for it exists. | |
931b8415 | 243 | .It Er 44 ESOCKTNOSUPPORT Em "Socket type not supported" . |
5e1f9d48 KM |
244 | The support for the socket type has not been configured into the |
245 | system or no implementation for it exists. | |
7caaf118 MK |
246 | .It Er 45 EOPNOTSUPP Em "Operation not supported" . |
247 | The attempted operation is not supported for the type of object referenced. | |
248 | Usually this occurs when a file descriptor refers to a file or socket | |
249 | that cannot support this operation, | |
250 | for example, trying to | |
931b8415 CL |
251 | .Em accept |
252 | a connection on a datagram socket. | |
253 | .It Er 46 EPFNOSUPPORT Em "Protocol family not supported" . | |
5e1f9d48 KM |
254 | The protocol family has not been configured into the |
255 | system or no implementation for it exists. | |
931b8415 | 256 | .It Er 47 EAFNOSUPPORT Em "Address family not supported by protocol family" . |
5e1f9d48 | 257 | An address incompatible with the requested protocol was used. |
931b8415 CL |
258 | For example, you shouldn't necessarily expect to be able to use |
259 | .Tn NS | |
260 | addresses with | |
261 | .Tn ARPA | |
262 | Internet protocols. | |
263 | .It Er 48 EADDRINUSE Em "Address already in use" . | |
5e1f9d48 | 264 | Only one usage of each address is normally permitted. |
931b8415 | 265 | .It Er 49 EADDRNOTAVAIL Em "Cannot assign requested address" . |
5e1f9d48 KM |
266 | Normally results from an attempt to create a socket with an |
267 | address not on this machine. | |
931b8415 | 268 | .It Er 50 ENETDOWN Em "Network is down" . |
5e1f9d48 | 269 | A socket operation encountered a dead network. |
931b8415 | 270 | .It Er 51 ENETUNREACH Em "Network is unreachable" . |
5e1f9d48 | 271 | A socket operation was attempted to an unreachable network. |
931b8415 | 272 | .It Er 52 ENETRESET Em "Network dropped connection on reset" . |
5e1f9d48 | 273 | The host you were connected to crashed and rebooted. |
931b8415 | 274 | .It Er 53 ECONNABORTED Em "Software caused connection abort" . |
5e1f9d48 | 275 | A connection abort was caused internal to your host machine. |
931b8415 | 276 | .It Er 54 ECONNRESET Em "Connection reset by peer" . |
5e1f9d48 | 277 | A connection was forcibly closed by a peer. This normally |
91409caa MK |
278 | results from a loss of the connection on the remote socket |
279 | due to a timeout or a reboot. | |
931b8415 | 280 | .It Er 55 ENOBUFS Em "\&No buffer space available" . |
5e1f9d48 | 281 | An operation on a socket or pipe was not performed because |
91409caa | 282 | the system lacked sufficient buffer space or because a queue was full. |
931b8415 | 283 | .It Er 56 EISCONN Em "Socket is already connected" . |
5e1f9d48 | 284 | A |
931b8415 | 285 | .Xr connect |
5e1f9d48 KM |
286 | request was made on an already connected socket; or, |
287 | a | |
931b8415 | 288 | .Xr sendto |
5e1f9d48 | 289 | or |
931b8415 | 290 | .Xr sendmsg |
5e1f9d48 | 291 | request on a connected socket specified a destination |
91409caa | 292 | when already connected. |
931b8415 | 293 | .It Er 57 ENOTCONN Em "Socket is not connected" . |
5e1f9d48 | 294 | An request to send or receive data was disallowed because |
91409caa MK |
295 | the socket is not connected and (when sending on a datagram socket) |
296 | no address was supplied. | |
931b8415 | 297 | .It Er 58 ESHUTDOWN Em "Cannot send after socket shutdown" . |
5e1f9d48 KM |
298 | A request to send data was disallowed because the socket |
299 | had already been shut down with a previous | |
931b8415 | 300 | .Xr shutdown 2 |
5e1f9d48 | 301 | call. |
0dc293bd | 302 | .It Er 60 ETIMEDOUT Em "Operation timed out" . |
5e1f9d48 | 303 | A |
931b8415 | 304 | .Xr connect |
91409caa | 305 | or |
931b8415 | 306 | .Xr send |
5e1f9d48 KM |
307 | request failed because the connected party did not |
308 | properly respond after a period of time. (The timeout | |
309 | period is dependent on the communication protocol.) | |
931b8415 | 310 | .It Er 61 ECONNREFUSED Em "Connection refused" . |
5e1f9d48 KM |
311 | No connection could be made because the target machine actively |
312 | refused it. This usually results from trying to connect | |
750588ad | 313 | to a service that is inactive on the foreign host. |
931b8415 | 314 | .It Er 62 ELOOP Em "Too many levels of symbolic links" . |
5e1f9d48 | 315 | A path name lookup involved more than 8 symbolic links. |
931b8415 CL |
316 | .It Er 63 ENAMETOOLONG Em "File name too long" . |
317 | A component of a path name exceeded 255 | |
318 | .Pq Dv MAXNAMELEN | |
319 | characters, or an entire | |
320 | path name exceeded 1023 | |
321 | .Pq Dv MAXPATHLEN Ns -1 | |
322 | characters. | |
323 | .It Er 64 EHOSTDOWN Em "Host is down" . | |
8af6b0db | 324 | A socket operation failed because the destination host was down. |
931b8415 | 325 | .It Er 65 EHOSTUNREACH Em "No route to host" . |
8af6b0db | 326 | A socket operation was attempted to an unreachable host. |
931b8415 CL |
327 | .It Er 66 ENOTEMPTY Em "Directory not empty" . |
328 | A directory with entries other than | |
329 | .Ql \&. | |
330 | and | |
331 | .Ql \&.. | |
5e1f9d48 | 332 | was supplied to a remove directory or rename call. |
931b8415 CL |
333 | .It Er 67 EPROCLIM Em "Too many processes" . |
334 | .It Er 68 EUSERS Em "Too many users" . | |
a0f47338 | 335 | The quota system ran out of table entries. |
931b8415 | 336 | .It Er 69 EDQUOT Em "Disc quota exceeded" . |
fd690c8b | 337 | A |
931b8415 | 338 | .Xr write |
fd690c8b KM |
339 | to an ordinary file, the creation of a |
340 | directory or symbolic link, or the creation of a directory | |
341 | entry failed because the user's quota of disk blocks was | |
342 | exhausted, or the allocation of an inode for a newly | |
343 | created file failed because the user's quota of inodes | |
344 | was exhausted. | |
931b8415 CL |
345 | .It Er 70 ESTALE Em "Stale NFS file handle" . |
346 | An attempt was made to access an open file (on an | |
347 | .Tn NFS | |
348 | filesystem) | |
c8051adb | 349 | which is now unavailable as referenced by the file descriptor. |
931b8415 CL |
350 | This may indicate the file was deleted on the |
351 | .Tn NFS | |
352 | server or some | |
a67e2645 | 353 | other catastrophic event occurred. |
931b8415 CL |
354 | .It Er 72 EBADRPC Em "RPC struct is bad" . |
355 | Exchange of | |
356 | .Tn RPC | |
357 | information was unsuccessful. | |
358 | .It Er 73 ERPCMISMATCH Em "RPC version wrong" . | |
359 | The version of | |
360 | .Tn RPC | |
361 | on the remote peer is not compatible with | |
c8051adb | 362 | the local version. |
931b8415 | 363 | .It Er 74 EPROGUNAVAIL Em "RPC prog. not avail" . |
c8051adb | 364 | The requested program is not registered on the remote host. |
931b8415 | 365 | .It Er 75 EPROGMISMATCH Em "Program version wrong" . |
c8051adb | 366 | The requested version of the program is not available |
931b8415 CL |
367 | on the remote host |
368 | .Pq Tn RPC . | |
369 | .It Er 76 EPROCUNAVAIL Em "Bad procedure for program" . | |
370 | An | |
371 | .Tn RPC | |
372 | call was attempted for a procedure which doesn't exist | |
c8051adb | 373 | in the remote program. |
931b8415 | 374 | .It Er 77 ENOLCK Em "No locks available" . |
c8051adb TH |
375 | A system-imposed limit on the number of simultaneous file |
376 | locks was reached. | |
931b8415 | 377 | .It Er 78 ENOSYS Em "Function not implemented" . |
c8051adb TH |
378 | Attempted a system call that is not available on this |
379 | system. | |
931b8415 CL |
380 | .Sh DEFINITIONS |
381 | .Bl -tag -width Ds | |
382 | .It Process ID . | |
383 | Each active process in the system is uniquely identified by a non-negative | |
91409caa | 384 | integer called a process ID. The range of this ID is from 0 to 30000. |
931b8415 | 385 | .It Parent process ID |
9b718484 | 386 | A new process is created by a currently active process; (see |
931b8415 | 387 | .Xr fork 2 ) . |
87af7cb9 KM |
388 | The parent process ID of a process is initially the process ID of its creator. |
389 | If the creating process exits, | |
390 | the parent process ID of each child is set to the ID of a system process, | |
391 | .Xr init . | |
392 | .It Process Group | |
5e1f9d48 | 393 | Each active process is a member of a process group that is identified by |
931b8415 | 394 | a non-negative integer called the process group ID. This is the process |
91409caa | 395 | ID of the group leader. This grouping permits the signaling of related |
5e1f9d48 | 396 | processes (see |
a67e2645 | 397 | .Xr termios 4 ) |
5e1f9d48 | 398 | and the job control mechanisms of |
931b8415 | 399 | .Xr csh 1 . |
a67e2645 KM |
400 | .It Session |
401 | A session is a set of one or more process groups. | |
402 | A session is created by a successful call to | |
403 | .Xr setsid 2 , | |
404 | which causes the caller to become the only member of the only process | |
405 | group in the new session. | |
87af7cb9 KM |
406 | .It Session leader |
407 | A process that has created a new session by a successful call to | |
408 | .Xr setsid 2 , | |
409 | is known as a session leader. | |
a67e2645 KM |
410 | Only a session leader may acquire a terminal as its controlling terminal (see |
411 | .Xr termios 4 ) . | |
87af7cb9 KM |
412 | .It Controlling process |
413 | A session leader with a controlling terminal is a controlling process. | |
414 | .It Controlling terminal | |
415 | A terminal that is associated with a session is known as the controlling | |
416 | terminal for that session and its members. | |
417 | .It "Terminal Process Group ID" | |
a67e2645 KM |
418 | A terminal may be acquired by a session leader as its controlling terminal. |
419 | Once a terminal is associated with a session, any of the process groups | |
420 | within the session may be placed into the foreground by setting | |
421 | the terminal process group ID to the ID of the process group. | |
422 | This facility is used | |
5e1f9d48 | 423 | to arbitrate between multiple jobs contending for the same terminal; |
9b718484 | 424 | (see |
931b8415 | 425 | .Xr csh 1 |
5822f3c2 | 426 | and |
931b8415 | 427 | .Xr tty 4 ) . |
87af7cb9 KM |
428 | .It "Orphaned Process Group" |
429 | A process group is considered to be | |
430 | .Em orphaned | |
431 | if it is not under the control of a job control shell. | |
432 | More precisely, a process group is orphaned | |
433 | when none of its members has a parent process that is in the same session | |
434 | as the group, | |
435 | but is in a different process group. | |
436 | Note that when a process exits, the parent process for its children | |
437 | is changed to be | |
438 | .Xr init , | |
439 | which is in a separate session. | |
440 | Not all members of an orphaned process group are necessarily orphaned | |
441 | processes (those whose creating process has exited). | |
442 | The process group of a session leader is orphaned by definition. | |
bb45189a | 443 | .It "Real User ID and Real Group ID" |
5e1f9d48 KM |
444 | Each user on the system is identified by a positive integer |
445 | termed the real user ID. | |
931b8415 | 446 | .Pp |
5e1f9d48 KM |
447 | Each user is also a member of one or more groups. |
448 | One of these groups is distinguished from others and | |
449 | used in implementing accounting facilities. The positive | |
450 | integer corresponding to this distinguished group is termed | |
451 | the real group ID. | |
931b8415 | 452 | .Pp |
5e1f9d48 KM |
453 | All processes have a real user ID and real group ID. |
454 | These are initialized from the equivalent attributes | |
750588ad | 455 | of the process that created it. |
a67e2645 KM |
456 | .It "Effective User Id, Effective Group Id, and Group Access List" |
457 | Access to system resources is governed by two values: | |
458 | the effective user ID, and the group access list. | |
459 | The first member of the group access list is also known as the | |
460 | effective group ID. | |
461 | (In POSIX.1, the group access list is known as the set of supplementary | |
462 | group IDs, and it is unspecified whether the effective group ID is | |
463 | a member of the list.) | |
931b8415 | 464 | .Pp |
5e1f9d48 KM |
465 | The effective user ID and effective group ID are initially the |
466 | process's real user ID and real group ID respectively. Either | |
467 | may be modified through execution of a set-user-ID or set-group-ID | |
9b718484 | 468 | file (possibly by one its ancestors) (see |
931b8415 | 469 | .Xr execve 2 ) . |
a67e2645 KM |
470 | By convention, the effective group ID (the first member of the group access |
471 | list) is duplicated, so that the execution of a set-group-ID program | |
472 | does not result in the loss of the original (real) group ID. | |
931b8415 | 473 | .Pp |
87af7cb9 | 474 | The group access list is a set of group IDs |
5e1f9d48 KM |
475 | used only in determining resource accessibility. Access checks |
476 | are performed as described below in ``File Access Permissions''. | |
a67e2645 KM |
477 | .It "Saved Set User ID and Saved Set Group ID" |
478 | When a process executes a new file, the effective user ID is set | |
479 | to the owner of the file if the file is set-user-ID, and the effective | |
480 | group ID (first element of the group access list) is set to the group | |
481 | of the file if the file is set-group-ID. | |
482 | The effective user ID of the process is then recorded as the saved set-user-ID, | |
483 | and the effective group ID of the process is recorded as the saved set-group-ID. | |
484 | These values may be used to regain those values as the effective user | |
485 | or group ID after reverting to the real ID (see | |
486 | .Xr setuid 2 ) . | |
487 | (In POSIX.1, the saved set-user-ID and saved set-group-ID are optional, | |
488 | and are used in setuid and setgid, but this does not work as desired | |
489 | for the super-user.) | |
931b8415 | 490 | .It Super-user |
5e1f9d48 | 491 | A process is recognized as a |
931b8415 | 492 | .Em super-user |
5e1f9d48 | 493 | process and is granted special privileges if its effective user ID is 0. |
931b8415 | 494 | .It Special Processes |
87af7cb9 | 495 | The processes with process IDs of 0, 1, and 2 are special. |
5e1f9d48 | 496 | Process 0 is the scheduler. Process 1 is the initialization process |
931b8415 | 497 | .Xr init , |
5e1f9d48 KM |
498 | and is the ancestor of every other process in the system. |
499 | It is used to control the process structure. | |
500 | Process 2 is the paging daemon. | |
931b8415 | 501 | .It Descriptor |
5e1f9d48 KM |
502 | An integer assigned by the system when a file is referenced |
503 | by | |
931b8415 | 504 | .Xr open 2 |
91409caa | 505 | or |
931b8415 | 506 | .Xr dup 2 , |
91409caa | 507 | or when a socket is created by |
931b8415 CL |
508 | .Xr pipe 2 , |
509 | .Xr socket 2 | |
5e1f9d48 | 510 | or |
931b8415 | 511 | .Xr socketpair 2 , |
5e1f9d48 KM |
512 | which uniquely identifies an access path to that file or socket from |
513 | a given process or any of its children. | |
931b8415 CL |
514 | .It File Name |
515 | Names consisting of up to 255 | |
516 | .Pq Dv MAXNAMELEN | |
517 | characters may be used to name | |
5e1f9d48 | 518 | an ordinary file, special file, or directory. |
931b8415 CL |
519 | .Pp |
520 | These characters may be selected from the set of all | |
521 | .Tn ASCII | |
522 | character | |
523 | excluding 0 (NUL) and the | |
524 | .Tn ASCII | |
525 | code for | |
526 | .Ql \&/ | |
527 | (slash). (The parity bit, | |
528 | bit 7, must be 0.) | |
529 | .Pp | |
530 | Note that it is generally unwise to use | |
531 | .Ql \&* , | |
532 | .Ql \&? , | |
533 | .Ql \&[ | |
534 | or | |
535 | .Ql \&] | |
536 | as part of | |
5e1f9d48 KM |
537 | file names because of the special meaning attached to these characters |
538 | by the shell. | |
931b8415 | 539 | .It Path Name |
bb45189a CL |
540 | A path name is a |
541 | .Tn NUL Ns -terminated | |
542 | character string starting with an | |
931b8415 CL |
543 | optional slash |
544 | .Ql \&/ , | |
545 | followed by zero or more directory names separated | |
5e1f9d48 | 546 | by slashes, optionally followed by a file name. |
931b8415 CL |
547 | The total length of a path name must be less than 1024 |
548 | .Pq Dv MAXPATHLEN | |
549 | characters. | |
550 | .Pp | |
5e1f9d48 | 551 | If a path name begins with a slash, the path search begins at the |
931b8415 | 552 | .Em root |
5e1f9d48 KM |
553 | directory. |
554 | Otherwise, the search begins from the current working directory. | |
931b8415 | 555 | A slash by itself names the root directory. An empty |
5e1f9d48 | 556 | pathname refers to the current directory. |
931b8415 | 557 | .It Directory |
750588ad SS |
558 | A directory is a special type of file that contains entries |
559 | that are references to other files. | |
5e1f9d48 | 560 | Directory entries are called links. By convention, a directory |
931b8415 CL |
561 | contains at least two links, |
562 | .Ql \&. | |
5822f3c2 | 563 | and |
931b8415 CL |
564 | .Ql \&.. , |
565 | referred to as | |
566 | .Em dot | |
567 | and | |
568 | .Em dot-dot | |
5e1f9d48 KM |
569 | respectively. Dot refers to the directory itself and |
570 | dot-dot refers to its parent directory. | |
bb45189a | 571 | .It "Root Directory and Current Working Directory" |
5e1f9d48 KM |
572 | Each process has associated with it a concept of a root directory |
573 | and a current working directory for the purpose of resolving path | |
574 | name searches. A process's root directory need not be the root | |
575 | directory of the root file system. | |
931b8415 | 576 | .It File Access Permissions |
5e1f9d48 KM |
577 | Every file in the file system has a set of access permissions. |
578 | These permissions are used in determining whether a process | |
579 | may perform a requested operation on the file (such as opening | |
580 | a file for writing). Access permissions are established at the | |
581 | time a file is created. They may be changed at some later time | |
582 | through the | |
931b8415 | 583 | .Xr chmod 2 |
5e1f9d48 | 584 | call. |
931b8415 | 585 | .Pp |
5e1f9d48 KM |
586 | File access is broken down according to whether a file may be: read, |
587 | written, or executed. Directory files use the execute | |
588 | permission to control if the directory may be searched. | |
931b8415 | 589 | .Pp |
5e1f9d48 KM |
590 | File access permissions are interpreted by the system as |
591 | they apply to three different classes of users: the owner | |
592 | of the file, those users in the file's group, anyone else. | |
593 | Every file has an independent set of access permissions for | |
594 | each of these classes. When an access check is made, the system | |
595 | decides if permission should be granted by checking the access | |
596 | information applicable to the caller. | |
931b8415 | 597 | .Pp |
5e1f9d48 KM |
598 | Read, write, and execute/search permissions on |
599 | a file are granted to a process if: | |
931b8415 CL |
600 | .Pp |
601 | The process's effective user ID is that of the super-user. (Note: | |
602 | even the super-user cannot execute a non-executable file.) | |
603 | .Pp | |
5e1f9d48 KM |
604 | The process's effective user ID matches the user ID of the owner |
605 | of the file and the owner permissions allow the access. | |
931b8415 | 606 | .Pp |
5e1f9d48 KM |
607 | The process's effective user ID does not match the user ID of the |
608 | owner of the file, and either the process's effective | |
609 | group ID matches the group ID | |
610 | of the file, or the group ID of the file is in | |
611 | the process's group access list, | |
612 | and the group permissions allow the access. | |
931b8415 | 613 | .Pp |
5e1f9d48 KM |
614 | Neither the effective user ID nor effective group ID |
615 | and group access list of the process | |
616 | match the corresponding user ID and group ID of the file, | |
617 | but the permissions for ``other users'' allow access. | |
931b8415 | 618 | .Pp |
5e1f9d48 | 619 | Otherwise, permission is denied. |
931b8415 CL |
620 | .It Sockets and Address Families |
621 | .Pp | |
5e1f9d48 KM |
622 | A socket is an endpoint for communication between processes. |
623 | Each socket has queues for sending and receiving data. | |
931b8415 | 624 | .Pp |
5e1f9d48 KM |
625 | Sockets are typed according to their communications properties. |
626 | These properties include whether messages sent and received | |
627 | at a socket require the name of the partner, whether communication | |
628 | is reliable, the format used in naming message recipients, etc. | |
931b8415 | 629 | .Pp |
5e1f9d48 KM |
630 | Each instance of the system supports some |
631 | collection of socket types; consult | |
931b8415 | 632 | .Xr socket 2 |
5e1f9d48 KM |
633 | for more information about the types available and |
634 | their properties. | |
931b8415 | 635 | .Pp |
5e1f9d48 KM |
636 | Each instance of the system supports some number of sets of |
637 | communications protocols. Each protocol set supports addresses | |
638 | of a certain format. An Address Family is the set of addresses | |
639 | for a specific group of protocols. Each socket has an address | |
640 | chosen from the address family in which the socket was created. | |
931b8415 | 641 | .Sh SEE ALSO |
5e1f9d48 | 642 | intro(3), perror(3) |