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