1.\" Copyright (c) 1980, 1983, 1986, 1991, 1993 2.\" The Regents of the University of California. 3.\" All rights reserved. The Berkeley software License Agreement 4.\" specifies the terms and conditions for redistribution. 5.\" 6.\" @(#)intro.2 8.5 (Berkeley) 2/27/95 7.\" 8.\" Adapted to MINIX 3 9.\" 10.Dd July 14, 2010 11.Dt INTRO 2 12.Os 13.Sh NAME 14.Nm intro , 15.Nm errno 16.Nd introduction to system calls and error numbers 17.Sh SYNOPSIS 18.In errno.h 19.Sh DESCRIPTION 20This section provides an overview of the system calls, 21their error returns, and other common definitions and concepts. 22.Sh DIAGNOSTICS 23Nearly all of the system calls provide an error number in the external 24variable 25.Va errno . 26.Pp 27When a system call detects an error, 28it returns an integer value 29indicating failure (usually \-1) 30and sets the variable 31.Va errno 32accordingly. 33(This allows interpretation of the failure on receiving 34a \-1 and to take action accordingly.) 35Successful calls never set 36.Va errno ; 37once set, it remains until another error occurs. 38It should only be examined after an error has been reported, because 39otherwise a leftover value from some previous error may be found 40instead. 41.Po 42Many library functions that are not system calls also set 43.Va errno 44on return, in the same fashion. 45In these cases a nonzero value may be left in 46.Va errno 47even upon successful return if some internal action failed. 48.Pc 49.Pp 50The manual page for each system call will list some of the common 51errno codes that system call can return, but that should not be 52considered an exhaustive list, i.e. 53a properly written program should be able to gracefully recover from 54any error that a system call might return. 55Documenting all the error codes that a system call can return in 56a more specification-like manner would take more resources than 57this project has available. 58.Pp 59Note also that a number of system calls overload the meanings of these 60error numbers, and that in these cases the meanings must be 61interpreted according to the type and circumstances of the call. 62.Pp 63The following is a list of the errors and their 64names as given in 65.In errno.h . 66.Bl -hang -width Ds 67.It Er 0 OK Em "Error 0" . 68Not used. (The symbol "OK" is only used inside the kernel source.) 69.It 1 EPERM Em "Operation not permitted" . 70An attempt was made to perform an operation limited to processes 71with appropriate privileges or to the owner of a file or other 72resources. 73.It Er 2 ENOENT Em "No such file or directory" . 74A component of a specified pathname did not exist, or the 75pathname was an empty string. 76.It Er 3 ESRCH Em "No such process" . 77No process could be found corresponding to that specified by the given 78process ID. 79It Er 4 EINTR Em "Interrupted function call" . 80An asynchronous signal (such as 81.Dv SIGINT 82or 83.Dv SIGQUIT ) 84was caught by the process during the execution of an interruptible 85function. 86If the signal handler performs a normal return, the 87interrupted function call will seem to have returned the error condition. 88.It Er 5 EIO Em "Input/output error" . 89Some physical input or output error occurred. 90This error will not be reported until a subsequent operation on the same file 91descriptor and may be lost (over written) by any subsequent errors. 92.It Er 6 ENXIO Em "Device not configured" . 93Input or output on a special file referred to a device that did not 94exist, or 95made a request beyond the limits of the device. 96This error may also occur when, for example, 97a tape drive is not online or no disk pack is 98loaded on a drive. 99.It Er 7 E2BIG Em "Arg list too long" . 100The number of bytes used for the argument and environment 101list of the new process exceeded the current limit of 102262144 bytes 103.Pf ( Dv ARG_MAX 104in 105.In limits.h ) . 106.It Er 8 ENOEXEC Em "Exec format error" . 107A request was made to execute a file 108that, although it has the appropriate permissions, 109was not in the format required for an 110executable file. 111.It Er 9 EBADF Em "Bad file descriptor" . 112A file descriptor argument was out of range, referred to no open file, 113or a 114.Xr read 2 115(or 116.Xr write 2 ) 117request was made to a file that was 118only open for writing (or reading). 119.It Er 10 ECHILD Em "\&No child processes" . 120A 121.Xr wait 2 122or 123.Xr waitpid 2 124function was executed by a process that had no existing or unwaited-for 125child processes. 126.It Er 11 EAGAIN Em "Resource temporarily unavailable" . 127This is a temporary condition and later calls to the 128same routine may complete normally. 129.It Er 12 ENOMEM Em "Cannot allocate memory" . 130The new process image required more memory than was allowed by the hardware 131or by system-imposed memory management constraints. 132Soft limits may be increased to their corresponding hard limits. 133.It Er 13 EACCES Em "Permission denied" . 134An attempt was made to access a file in a way forbidden 135by its file access permissions. 136.It Er 14 EFAULT Em "Bad address" . 137The system detected an invalid address in attempting to 138use an argument of a call. 139The reliable detection of this error cannot be guaranteed and when not detected 140may result in the generation of a signal, indicating an address violation, 141which is sent to the process. 142.It Er 15 ENOTBLK Em "Block device required" . 143A block device operation was attempted on a non-block device or file. 144.It Er 16 EBUSY Em "Resource busy" . 145An attempt to use a system resource which was in use at the time 146in a manner which would have conflicted with the request. 147.It Er 17 EEXIST Em "File exists" . 148An existing file was mentioned in an inappropriate context, 149for instance, as the new link name in a 150.Xr link 2 151function. 152.It Er 18 EXDEV Em "Improper link" . 153A hard link to a file on another file system 154was attempted. 155.It Er 19 ENODEV Em "Operation not supported by device" . 156An attempt was made to apply an inappropriate 157function to a device, 158for example, 159trying 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 requests for an open cannot be satisfied 175until at least one has been closed. 176.It Er 24 EMFILE Em "Too many open files" . 177\*[Lt]As released, the limit on the number of 178open files per process is 64.\*[Gt] 179The 180.Xr getrlimit 2 181call with the 182.Ar RLIMIT_NOFILE 183resource will obtain the current limit. 184.It Er 25 ENOTTY Em "Inappropriate ioctl for device" . 185A control function (see 186.Xr ioctl 2 ) 187was attempted for a file or 188special device for which the operation was inappropriate. 189.en 26 ETXTBSY "Text file busy 190Attempt to execute a program that is open for writing. Obsolete under MINIX 3. 191.It Er 27 EFBIG Em "File too large" . 192The size of a file exceeded the maximum. 193(The system-wide maximum file size is 1942147483648 (2GB) bytes. 195Each file system may impose a lower limit for files contained within it). 196.It Er 28 ENOSPC Em "Device out of space" . 197A 198.Xr write 2 199to an ordinary file, the creation of a 200directory or symbolic link, or the creation of a directory 201entry failed because no more disk blocks were available 202on the file system, or the allocation of an inode for a newly 203created file failed because no more inodes were available 204on the file system. 205.It Er 29 ESPIPE Em "Illegal seek" . 206An 207.Xr lseek 2 208function was issued on a socket, pipe or 209.Tn FIFO . 210.It Er 30 EROFS Em "Read-only file system" . 211An attempt was made to modify a file or directory 212was made 213on a file system that was read-only at the time. 214.It Er 31 EMLINK Em "Too many links" . 215The number of hard links to a single file has exceeded the maximum. 216(The system-wide maximum number of hard links is 32767. 217Each file system may impose a lower limit for files contained within it). 218.It Er 32 EPIPE Em "Broken pipe" . 219A write on a pipe, socket or 220.Tn FIFO 221for which there is no process 222to read the data. 223.It Er 33 EDOM Em "Numerical argument out of domain" . 224A numerical input argument was outside the defined domain of the mathematical 225function. 226.It Er 34 ERANGE Em "Result too large or too small" . 227The result of the function is too large or too small to be represented 228in the available space. 229.It Er 35 EDEADLK Em "Resource deadlock avoided" . 230An attempt was made to lock a system resource that 231would have resulted in a deadlock situation. 232.It Er 36 ENAMETOOLONG Em "File name too long" . 233A component of a path name exceeded 234.Pq Dv NAME_MAX 235characters, or an entire 236path name exceeded 255 237.Pq Dv PATH_MAX 238characters. 239.It Er 37 ENOLCK Em "No locks available" . 240A system-imposed limit on the number of simultaneous file 241locks was reached. 242.It Er 38 ENOSYS Em "Function not implemented" . 243Attempted a system call that is not available on this 244system. 245.It Er 39 ENOTEMPTY Em "Directory not empty" . 246A directory with entries other than 247.Ql \&. 248and 249.Ql \&.. 250was supplied to a remove directory or rename call. 251.It Er 40 ELOOP Em "Too many levels of symbolic links" . 252A path name lookup involved more than 16 253.Pq Dv SYMLOOP_MAX 254symbolic links. 255.It Er 41 ERESTART Em "Service restarted" . 256.It Er 43 ERESTART Em "Identifier removed" . 257An IPC identifier was removed while the current process was waiting on it. 258.It Er 44 EILSEQ Em "Illegal byte sequence" . 259A wide character/multibyte character encoding error occurred. 260.It Er 45 EFTYPE Em "Inappropriate file type or format" . 261Attempted a file operation on a file of a type for which it was invalid. 262.It Er 46 EOVERFLOW Em "Value too large to be stored in data type" . 263A numerical result of the function was too large to be stored in the 264caller-provided space. 265.It Er 50 EPACKSIZE Em "Invalid packet size" . 266.It Er 51 ENOBUFS Em "\&No buffer space available" . 267An operation on a socket or pipe was not performed because 268the system lacked sufficient buffer space or because a queue was full. 269.It Er 53 EBADMODE Em "Bad mode in ioctl" . 270.It Er 54 EWOULDBLOCK Em "Would block" . 271.It Er 55 ENETUNREACH Em "Network is unreachable" . 272A socket operation was attempted to an unreachable network. 273.It Er 56 EHOSTUNREACH Em "No route to host" . 274A socket operation was attempted to an unreachable host. 275.It Er 57 EISCONN Em "Socket is already connected" . 276A 277.Xr connect 2 278request was made on an already connected socket; or, 279a 280.Xr sendto 2 281or 282.Xr sendmsg 2 283request on a connected socket specified a destination 284when already connected. 285.It Er 58 EADDRINUSE Em "Address already in use" . 286Only one usage of each address is normally permitted. 287.It Er 59 ECONNREFUSED Em "Connection refused" . 288No connection could be made because the target machine actively 289refused it. 290This usually results from trying to connect 291to a service that is inactive on the foreign host. 292.It Er 60 ECONNRESET Em "Connection reset by peer" . 293A connection was forcibly closed by a peer. 294This normally results from a loss of the connection on the remote 295socket due to a timeout or a reboot. 296.It Er 61 ETIMEDOUT Em "Operation timed out" . 297A 298.Xr connect 2 299or 300.Xr send 2 301request failed because the connected party did not 302properly respond after a period of time. 303(The timeout period is dependent on the communication protocol). 304.It Er 62 EURG Em "Urgent data present" . 305.It Er 63 ENOURG Em "No urgent data present" . 306.It Er 64 ENOTCONN Em "Socket is not connected" . 307An request to send or receive data was disallowed because 308the socket was not connected and (when sending on a datagram socket) 309no address was supplied. 310.It Er 65 ESHUTDOWN Em "Cannot send after socket shutdown" . 311A request to send data was disallowed because the socket 312had already been shut down with a previous 313.Xr shutdown 2 314call. 315.It Er 66 ENOCONN Em "No such connection" . 316.It Er 67 EAFNOSUPPORT Em "Address family not supported by protocol family" . 317An address incompatible with the requested protocol was used. 318For example, you shouldn't necessarily expect to be able to use 319.Tn NS 320addresses with 321.Tn ARPA 322Internet protocols. 323.It Er 68 EPROTONOSUPPORT Em "Protocol not supported" . 324The protocol has not been configured into the 325system or no implementation for it exists. 326.It Er 69 EPROTOTYPE Em "Protocol wrong type for socket" . 327A protocol was specified that does not support the semantics of the 328socket type requested. 329For example, you cannot use the 330.Tn ARPA 331Internet 332.Tn UDP 333protocol with type 334.Dv SOCK_STREAM . 335.It Er 70 EINPROGRESS Em "Operation now in progress" . 336An operation that takes a long time to complete (such as 337a 338.Xr connect 2 ) 339was attempted on a non-blocking object (see 340.Xr fcntl 2 ) . 341.It Er 71 EADDRNOTAVAIL Em "Cannot assign requested address" . 342Normally results from an attempt to create a socket with an 343address not on this machine. 344.It Er 72 EALREADY Em "Operation already in progress" . 345An operation was attempted on a non-blocking object that already 346had an operation in progress. 347.It Er 73 EMSGSIZE Em "Message too long" . 348A message sent on a socket was larger than the internal message buffer 349or some other network limit. 350.It Er 74 ENOTSOCK Em "Socket operation on non-socket" . 351Self-explanatory. 352.It Er 75 ENOPROTOOPT Em "Protocol option not available" . 353A bad option or level was specified in a 354.Xr getsockopt 2 355or 356.Xr setsockopt 2 357call. 358.It Er 76 EOPNOTSUPP Em "Operation not supported" (has alias ENOTSUP) . 359The attempted operation is not supported for the type of object referenced. 360Usually this occurs when a file descriptor refers to a file or socket 361that cannot support this operation, 362for example, trying to 363.Em accept 364a connection on a datagram socket. 365.It Er 77 ENETDOWN Em "Network is down" . 366A socket operation encountered a dead network. 367.It Er 78 EPFNOSUPPORT Em "Protocol family not supported" . 368A socket operation specified an unsupported protocol family. 369.It Er 79 EDESTADDRREQ Em "Destination address required" . 370A required address was omitted from an operation on a socket. 371.It Er 80 EHOSTDOWN Em "Host is down" . 372The destination host has been determined to be down or disconnected. 373.El 374.Sh DEFINITIONS 375.Bl -tag -width Ds 376.It Process ID 377Each active process in the system is uniquely identified by a positive 378integer called a process ID. The range of this ID is from 1 to 29999. 379.It Parent process ID 380A new process is created by a currently active process; (see 381.Xr fork 2 ) . 382The parent process ID of a process is initially the process ID of its creator. 383If the creating process exits, 384the parent process ID of each child is set to the ID of 385.Em init , 386.Xr init 8 . 387.It Process Group 388Each active process is a member of a process group that is identified by 389a positive integer called the process group ID. 390This is the process ID of the group leader. 391This grouping permits the signaling of related processes (see 392.Xr termios 4 ). 393.It Session 394A session is a set of one or more process groups. 395A session is created by a successful call to 396.Xr setsid 2 , 397which causes the caller to become the only member of the only process 398group in the new session. 399.It Session leader 400A process that has created a new session by a successful call to 401.Xr setsid 2 , 402is known as a session leader. 403Only a session leader may acquire a terminal as its controlling terminal (see 404.Xr termios 4 ) . 405.It Controlling process 406A session leader with a controlling terminal is a controlling process. 407.It Controlling terminal 408A terminal that is associated with a session is known as the controlling 409terminal for that session and its members. 410.It "Real User ID and Real Group ID" 411Each user on the system is identified by a positive integer 412termed the real user ID. 413.Pp 414Each user is also a member of one or more groups. 415One of these groups is distinguished from others and 416used in implementing accounting facilities. 417The positive integer corresponding to this distinguished group is 418termed the real group ID. 419.Pp 420All processes have a real user ID and real group ID. 421These are initialized from the equivalent attributes 422of the process that created it. 423.It "Effective User Id, Effective Group Id, and Group Access List" 424Access to system resources is governed by two values: 425the effective user ID and the group access list. 426(In POSIX.1, the group access list is known as the set of supplementary 427group IDs, and it is unspecified whether the effective group ID is 428a member of the list.) 429.Pp 430The effective user ID and effective group ID are initially the 431process's real user ID and real group ID respectively. Either 432may be modified through execution of a set-user-ID or set-group-ID 433file (possibly by one its ancestors) (see 434.BR execve (2)). 435.Pp 436The group access list is an additional set of group ID's 437used only in determining resource accessibility. 438Access checks are performed as described below in 439.Qq File Access Permissions . 440It Super-user 441A process is recognized as a 442.Em super-user 443process and is granted special privileges if its effective user ID is 0. 444.It Descriptor 445An integer assigned by the system when a file is referenced 446by 447.Xr open 2 448or 449.Xr dup 2 , 450or when a socket is created by 451.Xr pipe 2 , 452.Xr socket 2 , 453or 454.Xr socketpair 2 , 455which uniquely identifies an access path to that file or socket from 456a given process or any of its children. 457.It File Name 458Names consisting of up to 60 459.Pq Dv NAME_MAX 460characters may be used to name 461an ordinary file, special file, or directory. 462.Pp 463These characters may be selected from the set of all 464.Tn ASCII 465character 466excluding 0 (NUL) and the 467.Tn ASCII 468code for 469.Ql \&/ 470(slash). 471(The parity bit, bit 7, must be 0). 472.Pp 473Note that it is generally unwise to use 474.Ql \&* , 475.Ql \&? , 476.Ql \&[ 477or 478.Ql \&] 479as part of 480file names because of the special meaning attached to these characters 481by the shell. 482.It Pathname 483A path name is a 484.Tn NUL Ns -terminated 485character string starting with an 486optional slash 487.Ql \&/ , 488followed by zero or more directory names separated 489by slashes, optionally followed by a file name. 490The total length of a path name must be less than 255 491.Pq Dv PATH_MAX 492characters. 493.Pp 494If a path name begins with a slash, the path search begins at the 495.Em root 496directory. 497Otherwise, the search begins from the current working directory. 498A slash by itself names the root directory. 499An empty string is not a valid pathname. 500.It Directory 501A directory is a special type of file that contains entries 502that are references to other files. 503Directory entries are called links. 504By convention, a directory contains at least two links, 505.Ql \&. 506and 507.Ql \&.. , 508referred to as 509.Em dot 510and 511.Em dot-dot 512respectively. 513Dot refers to the directory itself and dot-dot refers to its parent directory. 514.It "Root Directory and Current Working Directory" 515Each process has associated with it a concept of a root directory 516and a current working directory for the purpose of resolving path 517name searches. 518A process's root directory need not be the root 519directory of the root file system. 520.It File Access Permissions 521Every file in the file system has a set of access permissions. 522These permissions are used in determining whether a process 523may perform a requested operation on the file (such as opening 524a file for writing). 525Access permissions are established at the time a file is created. 526They may be changed at some later time through the 527.Xr chmod 2 528call. 529.Pp 530File access is broken down according to whether a file may be: read, 531written, or executed. 532Directory files use the execute permission to control if the 533directory may be searched. 534.Pp 535File access permissions are interpreted by the system as 536they apply to three different classes of users: the owner 537of the file, those users in the file's group, anyone else. 538Every file has an independent set of access permissions for 539each of these classes. 540When an access check is made, the system decides if permission should be 541granted by checking the access information applicable to the caller. 542.Pp 543Read, write, and execute/search permissions on 544a file are granted to a process if: 545.Pp 546The process's effective user ID is that of the super-user. 547(Note: even the super-user cannot execute a non-executable file). 548.Pp 549The process's effective user ID matches the user ID of the owner 550of the file and the owner permissions allow the access. 551.Pp 552The process's effective user ID does not match the user ID of the 553owner of the file, and either the process's effective 554group ID matches the group ID 555of the file, or the group ID of the file is in 556the process's group access list, 557and the group permissions allow the access. 558.Pp 559Neither the effective user ID nor effective group ID 560and group access list of the process 561match the corresponding user ID and group ID of the file, 562but the permissions for ``other users'' allow access. 563.Pp 564Otherwise, permission is denied. 565.It Sockets and Address Families 566A socket is an endpoint for communication between processes. 567Each socket has queues for sending and receiving data. 568.Pp 569Sockets are typed according to their communications properties. 570These properties include whether messages sent and received 571at a socket require the name of the partner, whether communication 572is reliable, the format used in naming message recipients, etc. 573.Pp 574Each instance of the system supports some 575collection of socket types; consult 576.Xr socket 2 577for more information about the types available and 578their properties. 579.Pp 580Each instance of the system supports some number of sets of 581communications protocols. 582Each protocol set supports addresses of a certain format. 583An Address Family is the set of addresses for a specific group of protocols. 584Each socket has an address 585chosen from the address family in which the socket was created. 586.El 587.Sh SEE ALSO 588.Xr intro 3 , 589.Xr perror 3 590 591 592