|
|
1.1 ! root 1: .\" Copyright (c) 1980,1983,1986 Regents of the University of California. ! 2: .\" All rights reserved. The Berkeley software License Agreement ! 3: .\" specifies the terms and conditions for redistribution. ! 4: .\" ! 5: .\" @(#)intro.2 6.10 (Berkeley) 6/30/90 ! 6: .\" ! 7: .TH INTRO 2 "June 30, 1990" ! 8: .UC 4 ! 9: .de en ! 10: .HP ! 11: \\$1 \\$2 \\$3 ! 12: .br ! 13: .. ! 14: .SH NAME ! 15: intro \- introduction to system calls and error numbers ! 16: .SH SYNOPSIS ! 17: .B #include <sys/errno.h> ! 18: .SH DESCRIPTION ! 19: This section provides an overview of the system calls, ! 20: their error returns, and other common definitions and concepts. ! 21: .\".LP ! 22: .\".B "System call restart" ! 23: .\".PP ! 24: .\"<more later...> ! 25: .SH DIAGNOSTICS ! 26: Most of these calls have one or more error returns. ! 27: An error condition is indicated by an otherwise impossible return ! 28: value. This is almost always \-1; the individual descriptions ! 29: specify the details. ! 30: Note that a number of system calls overload the meanings of these ! 31: error numbers, and that the meanings must be interpreted according ! 32: to the type and circumstances of the call. ! 33: .PP ! 34: As with normal arguments, all return codes and values from ! 35: functions are of type integer unless otherwise noted. ! 36: An error number is also made available in the external ! 37: variable \fIerrno\fP, which is not cleared ! 38: on successful calls. ! 39: Thus \fIerrno\fP should be tested only after an error has occurred. ! 40: .PP ! 41: The following is a complete list of the errors and their ! 42: names as given in ! 43: .RI < sys/errno.h >. ! 44: .en 0 \h'\w'EIO'u' "Error 0 ! 45: Unused. ! 46: .en 1 EPERM "Operation not permitted ! 47: Typically this error indicates ! 48: an attempt to modify a file in some way forbidden ! 49: except to its owner or super-user. ! 50: It is also returned for attempts ! 51: by ordinary users to do things ! 52: allowed only to the super-user. ! 53: .en 2 ENOENT "No such file or directory ! 54: This error occurs when a file name is specified ! 55: and the file should exist but doesn't, or when one ! 56: of the directories in a path name does not exist. ! 57: .en 3 ESRCH "No such process ! 58: The process or process group whose number was given ! 59: does not exist, or any such process is already dead. ! 60: .en 4 EINTR "Interrupted system call ! 61: An asynchronous signal (such as interrupt or quit) ! 62: that the user has elected to catch ! 63: occurred during a system call. ! 64: If execution is resumed ! 65: after processing the signal ! 66: and the system call is not restarted, ! 67: it will appear as if the interrupted system call ! 68: returned this error condition. ! 69: .en 5 EIO "Input/output error ! 70: Some physical I/O error occurred during a ! 71: .I read ! 72: or ! 73: .IR write . ! 74: This error may in some cases occur ! 75: on a call following the one to which it actually applies. ! 76: .en 6 ENXIO "Device not configured ! 77: I/O on a special file refers to a subdevice that does not ! 78: exist, ! 79: or beyond the limits of the device. ! 80: It may also occur when, for example, an illegal tape drive ! 81: unit number is selected ! 82: or a disk pack is not loaded on a drive. ! 83: .en 7 E2BIG "Argument list too long ! 84: An argument list longer than 20480 bytes (or the current limit, NCARGS in ! 85: .IR <sys/param.h> ) ! 86: is presented to ! 87: .IR execve . ! 88: .en 8 ENOEXEC "Exec format error ! 89: A request is made to execute a file ! 90: that, although it has the appropriate permissions, ! 91: does not start with a valid magic number, (see ! 92: .IR a.out (5)). ! 93: .en 9 EBADF "Bad file descriptor ! 94: Either a file descriptor refers to no ! 95: open file, ! 96: or a read (resp. write) request is made to ! 97: a file that is open only for writing (resp. reading). ! 98: .en 10 ECHILD "No child processes ! 99: .I Wait ! 100: and the process has no ! 101: living or unwaited-for children. ! 102: .en 11 EDEADLK "Resource deadlock avoided ! 103: An attempt was made to lock a system resource that ! 104: would have resulted in a deadlock situation. ! 105: .en 12 ENOMEM "Cannnot allocate memory ! 106: During an ! 107: .I execve ! 108: or ! 109: .I break, ! 110: a program asks for more core or swap space than the system is ! 111: able to supply, ! 112: or a process size limit would be exceeded. ! 113: A lack of swap space is normally a temporary condition; however, ! 114: a lack of core ! 115: is not a temporary condition; the maximum size ! 116: of the text, data, and stack segments is a system parameter. ! 117: Soft limits may be increased to their corresponding hard limits. ! 118: .en 13 EACCES "Permission denied ! 119: An attempt was made to access a file in a way forbidden ! 120: by the protection system. ! 121: .en 14 EFAULT "Bad address ! 122: The system encountered a hardware fault in attempting to ! 123: access the arguments of a system call. ! 124: .en 15 ENOTBLK "Block device required ! 125: A plain file was mentioned where a block device was required, ! 126: e.g., in ! 127: .IR mount . ! 128: .en 16 EBUSY "Device busy ! 129: An attempt to mount a device that was already mounted or ! 130: an attempt was made to dismount a device ! 131: on which there is an active file ! 132: (open file, current directory, mounted-on file, or active text segment). ! 133: A request was made to an exclusive access device that was already in use. ! 134: .en 17 EEXIST "File exists ! 135: An existing file was mentioned in an inappropriate context, ! 136: e.g., ! 137: .IR link . ! 138: .en 18 EXDEV "Cross-device link ! 139: A hard link to a file on another device ! 140: was attempted. ! 141: .en 19 ENODEV "Operation not supported by device ! 142: An attempt was made to apply an inappropriate ! 143: system call to a device, ! 144: e.g., to read a write-only device, ! 145: or the device is not configured by the system. ! 146: .en 20 ENOTDIR "Not a directory ! 147: A non-directory was specified where a directory ! 148: is required, ! 149: for example, in a path name or ! 150: as an argument to ! 151: .IR chdir . ! 152: .en 21 EISDIR "Is a directory ! 153: An attempt to write on a directory. ! 154: .en 22 EINVAL "Invalid argument ! 155: Some invalid argument: ! 156: dismounting a non-mounted ! 157: device, ! 158: mentioning an unknown signal in ! 159: .I signal, ! 160: or some other argument inappropriate for the call. ! 161: Also set by math functions, (see ! 162: .IR math (3)). ! 163: .en 23 ENFILE "Too many open files in system ! 164: The system's table of open files is full, ! 165: and temporarily no more ! 166: .I opens ! 167: can be accepted. ! 168: .en 24 EMFILE "Too many open files ! 169: As released, the limit on the number of ! 170: open files per process is 64. ! 171: .IR Getdtablesize (2) ! 172: will obtain the current limit. ! 173: Customary configuration limit on most other UNIX systems ! 174: is 20 per process. ! 175: .en 25 ENOTTY "Inappropriate ioctl for device ! 176: The file mentioned in an ! 177: .I ioctl ! 178: is not a terminal or one of the ! 179: devices to which this call applies. ! 180: .en 26 ETXTBSY "Text file busy ! 181: An attempt to execute a pure-procedure ! 182: program that is currently open for writing. ! 183: Also an attempt to open for writing a pure-procedure ! 184: program that is being executed. ! 185: .en 27 EFBIG "File too large ! 186: The size of a file exceeded the maximum (about ! 187: .if t 2\u\s-231\s+2\d ! 188: .if n 2.1E9 ! 189: bytes). ! 190: .en 28 ENOSPC "No space left on device ! 191: A ! 192: .I write ! 193: to an ordinary file, the creation of a ! 194: directory or symbolic link, or the creation of a directory ! 195: entry failed because no more disk blocks are available ! 196: on the file system, or the allocation of an inode for a newly ! 197: created file failed because no more inodes are available ! 198: on the file system. ! 199: .en 29 ESPIPE "Illegal seek ! 200: An ! 201: .I lseek ! 202: was issued to a socket or pipe. ! 203: This error may also be issued for ! 204: other non-seekable devices. ! 205: .en 30 EROFS "Read-only file system ! 206: An attempt to modify a file or directory ! 207: was made ! 208: on a device mounted read-only. ! 209: .en 31 EMLINK "Too many links ! 210: An attempt to make more than 32767 hard links to a file. ! 211: .en 32 EPIPE "Broken pipe ! 212: A write on a pipe or socket for which there is no process ! 213: to read the data. ! 214: This condition normally generates a signal; ! 215: the error is returned if the signal is caught or ignored. ! 216: .en 33 EDOM "Numerical argument out of domain ! 217: The argument of a function in the math package (3M) ! 218: is out of the domain of the function. ! 219: .en 34 ERANGE "Numerical result out of range ! 220: The value of a function in the math package (3M) ! 221: is unrepresentable within machine precision. ! 222: .en 35 EAGAIN "Resource temporarily unavailable ! 223: This is a temporary condition and later calls to the ! 224: same routine may complete normally. ! 225: .en 36 EINPROGRESS "Operation now in progress" ! 226: An operation that takes a long time to complete (such as ! 227: a \fIconnect\fP(2)) was attempted on a non-blocking object (see ! 228: \fIfcntl\fP(2)). ! 229: .en 37 EALREADY "Operation already in progress" ! 230: An operation was attempted on a non-blocking object that already ! 231: had an operation in progress. ! 232: .en 38 ENOTSOCK "Socket operation on non-socket" ! 233: Self-explanatory. ! 234: .en 39 EDESTADDRREQ "Destination address required" ! 235: A required address was omitted from an operation on a socket. ! 236: .en 40 EMSGSIZE "Message too long" ! 237: A message sent on a socket was larger than the internal message buffer ! 238: or some other network limit. ! 239: .en 41 EPROTOTYPE "Protocol wrong type for socket" ! 240: A protocol was specified that does not support the semantics of the ! 241: socket type requested. For example, you cannot use the ARPA Internet ! 242: UDP protocol with type SOCK_STREAM. ! 243: .en 42 ENOPROTOOPT "Protocol not available ! 244: A bad option or level was specified in a ! 245: .IR getsockopt (2) ! 246: or ! 247: .IR setsockopt (2) ! 248: call. ! 249: .en 43 EPROTONOSUPPORT "Protocol not supported" ! 250: The protocol has not been configured into the ! 251: system or no implementation for it exists. ! 252: .en 44 ESOCKTNOSUPPORT "Socket type not supported" ! 253: The support for the socket type has not been configured into the ! 254: system or no implementation for it exists. ! 255: .en 45 EOPNOTSUPP "Operation not supported on socket" ! 256: For example, trying to \fIaccept\fP a connection on a datagram socket. ! 257: .en 46 EPFNOSUPPORT "Protocol family not supported" ! 258: The protocol family has not been configured into the ! 259: system or no implementation for it exists. ! 260: .en 47 EAFNOSUPPORT "Address family not supported by protocol family" ! 261: An address incompatible with the requested protocol was used. ! 262: For example, you shouldn't necessarily expect to be able to use NS ! 263: addresses with ARPA Internet protocols. ! 264: .en 48 EADDRINUSE "Address already in use" ! 265: Only one usage of each address is normally permitted. ! 266: .en 49 EADDRNOTAVAIL "Can't assign requested address" ! 267: Normally results from an attempt to create a socket with an ! 268: address not on this machine. ! 269: .en 50 ENETDOWN "Network is down" ! 270: A socket operation encountered a dead network. ! 271: .en 51 ENETUNREACH "Network is unreachable" ! 272: A socket operation was attempted to an unreachable network. ! 273: .en 52 ENETRESET "Network dropped connection on reset" ! 274: The host you were connected to crashed and rebooted. ! 275: .en 53 ECONNABORTED "Software caused connection abort" ! 276: A connection abort was caused internal to your host machine. ! 277: .en 54 ECONNRESET "Connection reset by peer" ! 278: A connection was forcibly closed by a peer. This normally ! 279: results from a loss of the connection on the remote socket ! 280: due to a timeout or a reboot. ! 281: .en 55 ENOBUFS "No buffer space available" ! 282: An operation on a socket or pipe was not performed because ! 283: the system lacked sufficient buffer space or because a queue was full. ! 284: .en 56 EISCONN "Socket is already connected" ! 285: A ! 286: .I connect ! 287: request was made on an already connected socket; or, ! 288: a ! 289: .I sendto ! 290: or ! 291: .I sendmsg ! 292: request on a connected socket specified a destination ! 293: when already connected. ! 294: .en 57 ENOTCONN "Socket is not connected" ! 295: An request to send or receive data was disallowed because ! 296: the socket is not connected and (when sending on a datagram socket) ! 297: no address was supplied. ! 298: .en 58 ESHUTDOWN "Can't send after socket shutdown" ! 299: A request to send data was disallowed because the socket ! 300: had already been shut down with a previous ! 301: .IR shutdown (2) ! 302: call. ! 303: .en 60 ETIMEDOUT "Connection timed out" ! 304: A ! 305: .I connect ! 306: or ! 307: .I send ! 308: request failed because the connected party did not ! 309: properly respond after a period of time. (The timeout ! 310: period is dependent on the communication protocol.) ! 311: .en 61 ECONNREFUSED "Connection refused" ! 312: No connection could be made because the target machine actively ! 313: refused it. This usually results from trying to connect ! 314: to a service that is inactive on the foreign host. ! 315: .en 62 ELOOP "Too many levels of symbolic links" ! 316: A path name lookup involved more than 8 symbolic links. ! 317: .en 63 ENAMETOOLONG "File name too long" ! 318: A component of a path name exceeded 255 (MAXNAMELEN) characters, or an entire ! 319: path name exceeded 1023 (MAXPATHLEN-1) characters. ! 320: .en 64 EHOSTDOWN "Host is down" ! 321: A socket operation failed because the destination host was down. ! 322: .en 65 EHOSTUNREACH "No route to host" ! 323: A socket operation was attempted to an unreachable host. ! 324: .en 66 ENOTEMPTY "Directory not empty" ! 325: A directory with entries other than \*(lq.\*(rq and \*(lq..\*(rq ! 326: was supplied to a remove directory or rename call. ! 327: .en 67 EPROCLIM "Too many processes" ! 328: .en 68 EUSERS "Too many users" ! 329: The quota system ran out of table entries. ! 330: .en 69 EDQUOT "Disc quota exceeded" ! 331: A ! 332: .I write ! 333: to an ordinary file, the creation of a ! 334: directory or symbolic link, or the creation of a directory ! 335: entry failed because the user's quota of disk blocks was ! 336: exhausted, or the allocation of an inode for a newly ! 337: created file failed because the user's quota of inodes ! 338: was exhausted. ! 339: .en 70 ESTALE "Stale NFS file handle" ! 340: An attempt was made to access an open file (on an NFS filesystem) ! 341: which is now unavailable as referenced by the file descriptor. ! 342: This may indicate the file was deleted on the NFS server and some ! 343: other catastrophic event occured. ! 344: .en 72 EBADRPC "RPC struct is bad" ! 345: Exchange of RPC information was unsuccessful. ! 346: .en 73 ERPCMISMATCH "RPC version wrong" ! 347: The version of RPC on the remote peer is not compatible with ! 348: the local version. ! 349: .en 74 EPROGUNAVAIL "RPC prog. not avail" ! 350: The requested program is not registered on the remote host. ! 351: .en 75 EPROGMISMATCH "Program version wrong" ! 352: The requested version of the program is not available ! 353: on the remote host (RPC). ! 354: .en 76 EPROCUNAVAIL "Bad procedure for program" ! 355: An RPC call was attempted for a procedure which doesn't exist ! 356: in the remote program. ! 357: .en 77 ENOLCK "No locks available" ! 358: A system-imposed limit on the number of simultaneous file ! 359: locks was reached. ! 360: .en 78 ENOSYS "Function not implemented" ! 361: Attempted a system call that is not available on this ! 362: system. ! 363: .SH DEFINITIONS ! 364: .TP 5 ! 365: Process ID ! 366: .br ! 367: Each active process in the system is uniquely identified by a positive ! 368: integer called a process ID. The range of this ID is from 0 to 30000. ! 369: .TP 5 ! 370: Parent process ID ! 371: .br ! 372: A new process is created by a currently active process; (see ! 373: .IR fork (2)). ! 374: The parent process ID of a process is the process ID of its creator. ! 375: .TP 5 ! 376: Process Group ID ! 377: .br ! 378: Each active process is a member of a process group that is identified by ! 379: a positive integer called the process group ID. This is the process ! 380: ID of the group leader. This grouping permits the signaling of related ! 381: processes (see ! 382: .IR killpg (2)) ! 383: and the job control mechanisms of ! 384: .IR csh (1). ! 385: .TP 5 ! 386: Tty Group ID ! 387: .br ! 388: Each active process can be a member of a terminal group that is identified ! 389: by a positive integer called the tty group ID. This grouping is used ! 390: to arbitrate between multiple jobs contending for the same terminal; ! 391: (see ! 392: .IR csh (1) ! 393: and ! 394: .IR tty (4)). ! 395: .TP 5 ! 396: Real User ID and Real Group ID ! 397: .br ! 398: Each user on the system is identified by a positive integer ! 399: termed the real user ID. ! 400: .IP ! 401: Each user is also a member of one or more groups. ! 402: One of these groups is distinguished from others and ! 403: used in implementing accounting facilities. The positive ! 404: integer corresponding to this distinguished group is termed ! 405: the real group ID. ! 406: .IP ! 407: All processes have a real user ID and real group ID. ! 408: These are initialized from the equivalent attributes ! 409: of the process that created it. ! 410: .TP 5 ! 411: Effective User Id, Effective Group Id, and Access Groups ! 412: .br ! 413: Access to system resources is governed by three values: ! 414: the effective user ID, the effective group ID, and the ! 415: group access list. ! 416: .IP ! 417: The effective user ID and effective group ID are initially the ! 418: process's real user ID and real group ID respectively. Either ! 419: may be modified through execution of a set-user-ID or set-group-ID ! 420: file (possibly by one its ancestors) (see ! 421: .IR execve (2)). ! 422: .IP ! 423: The group access list is an additional set of group ID's ! 424: used only in determining resource accessibility. Access checks ! 425: are performed as described below in ``File Access Permissions''. ! 426: .TP 5 ! 427: Super-user ! 428: .br ! 429: A process is recognized as a ! 430: .I super-user ! 431: process and is granted special privileges if its effective user ID is 0. ! 432: .TP 5 ! 433: Special Processes ! 434: .br ! 435: The processes with a process ID's of 0, 1, and 2 are special. ! 436: Process 0 is the scheduler. Process 1 is the initialization process ! 437: .IR init , ! 438: and is the ancestor of every other process in the system. ! 439: It is used to control the process structure. ! 440: Process 2 is the paging daemon. ! 441: .TP 5 ! 442: Descriptor ! 443: .br ! 444: An integer assigned by the system when a file is referenced ! 445: by ! 446: .IR open (2) ! 447: or ! 448: .IR dup (2), ! 449: or when a socket is created by ! 450: .IR pipe (2), ! 451: .IR socket (2) ! 452: or ! 453: .IR socketpair (2), ! 454: which uniquely identifies an access path to that file or socket from ! 455: a given process or any of its children. ! 456: .TP 5 ! 457: File Name ! 458: .br ! 459: Names consisting of up to 255 (MAXNAMELEN) characters may be used to name ! 460: an ordinary file, special file, or directory. ! 461: .IP ! 462: These characters may be selected from the set of all ASCII character ! 463: excluding 0 (null) and the ASCII code for / (slash). (The parity bit, ! 464: bit 8, must be 0.) ! 465: .IP ! 466: Note that it is generally unwise to use *, ?, [ or ] as part of ! 467: file names because of the special meaning attached to these characters ! 468: by the shell. ! 469: .TP 5 ! 470: Path Name ! 471: .br ! 472: A path name is a null-terminated character string starting with an ! 473: optional slash (/), followed by zero or more directory names separated ! 474: by slashes, optionally followed by a file name. ! 475: The total length of a path name must be less than 1024 (MAXPATHLEN) characters. ! 476: .IP ! 477: If a path name begins with a slash, the path search begins at the ! 478: .I root ! 479: directory. ! 480: Otherwise, the search begins from the current working directory. ! 481: A slash by itself names the root directory. A null ! 482: pathname refers to the current directory. ! 483: .TP 5 ! 484: Directory ! 485: .br ! 486: A directory is a special type of file that contains entries ! 487: that are references to other files. ! 488: Directory entries are called links. By convention, a directory ! 489: contains at least two links, . and .., referred to as ! 490: .I dot ! 491: and ! 492: .I dot-dot ! 493: respectively. Dot refers to the directory itself and ! 494: dot-dot refers to its parent directory. ! 495: .TP 5 ! 496: Root Directory and Current Working Directory ! 497: .br ! 498: Each process has associated with it a concept of a root directory ! 499: and a current working directory for the purpose of resolving path ! 500: name searches. A process's root directory need not be the root ! 501: directory of the root file system. ! 502: .TP 5 ! 503: File Access Permissions ! 504: .br ! 505: Every file in the file system has a set of access permissions. ! 506: These permissions are used in determining whether a process ! 507: may perform a requested operation on the file (such as opening ! 508: a file for writing). Access permissions are established at the ! 509: time a file is created. They may be changed at some later time ! 510: through the ! 511: .IR chmod (2) ! 512: call. ! 513: .IP ! 514: File access is broken down according to whether a file may be: read, ! 515: written, or executed. Directory files use the execute ! 516: permission to control if the directory may be searched. ! 517: .IP ! 518: File access permissions are interpreted by the system as ! 519: they apply to three different classes of users: the owner ! 520: of the file, those users in the file's group, anyone else. ! 521: Every file has an independent set of access permissions for ! 522: each of these classes. When an access check is made, the system ! 523: decides if permission should be granted by checking the access ! 524: information applicable to the caller. ! 525: .IP ! 526: Read, write, and execute/search permissions on ! 527: a file are granted to a process if: ! 528: .IP ! 529: The process's effective user ID is that of the super-user. ! 530: .IP ! 531: The process's effective user ID matches the user ID of the owner ! 532: of the file and the owner permissions allow the access. ! 533: .IP ! 534: The process's effective user ID does not match the user ID of the ! 535: owner of the file, and either the process's effective ! 536: group ID matches the group ID ! 537: of the file, or the group ID of the file is in ! 538: the process's group access list, ! 539: and the group permissions allow the access. ! 540: .IP ! 541: Neither the effective user ID nor effective group ID ! 542: and group access list of the process ! 543: match the corresponding user ID and group ID of the file, ! 544: but the permissions for ``other users'' allow access. ! 545: .IP ! 546: Otherwise, permission is denied. ! 547: .TP 5 ! 548: Sockets and Address Families ! 549: .IP ! 550: A socket is an endpoint for communication between processes. ! 551: Each socket has queues for sending and receiving data. ! 552: .IP ! 553: Sockets are typed according to their communications properties. ! 554: These properties include whether messages sent and received ! 555: at a socket require the name of the partner, whether communication ! 556: is reliable, the format used in naming message recipients, etc. ! 557: .IP ! 558: Each instance of the system supports some ! 559: collection of socket types; consult ! 560: .IR socket (2) ! 561: for more information about the types available and ! 562: their properties. ! 563: .IP ! 564: Each instance of the system supports some number of sets of ! 565: communications protocols. Each protocol set supports addresses ! 566: of a certain format. An Address Family is the set of addresses ! 567: for a specific group of protocols. Each socket has an address ! 568: chosen from the address family in which the socket was created. ! 569: .SH SEE ALSO ! 570: intro(3), perror(3)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.