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