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