Return to intro.2 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2

Annotation of 43BSDTahoe/man/man2/intro.2, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.