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