![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to intro.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to intro.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
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.