INTRO(2) INTRO(2)
NAME
intro, errno - introduction to system calls and error
numbers
SYNOPSIS
#include <errno.h>
DESCRIPTION
Section 2 describes the entries into the operating system.
File I/O
Files are opened for input or output by open(2) or creat.
These calls return a integer called a file descriptor which
identifies the file to subsequent I/O calls, notably read(2)
and write. File descriptors range from 0 to 127 in the cur-
rent system. The system gets to pick the numbers, but they
may be reassigned by dup(2) and dup2.
By agreement among user programs, file descriptor 0 is the
standard input, 1 is the standard output, 2 is for error
messages, and 3 is the controlling terminal if any. The
operating system is unaware of these conventions; it is per-
missible to close file 0, or even to replace it by a file
open only for writing, but many programs will be confused by
such chicanery.
Files are normally read or written in sequential order.
Lseek(2) addresses arbitrary locations.
Files have associated status, consisting of ownerships, per-
mission modes, access dates, and so on. The status is
retrieved by stat(2); the calls in chmod(2) alter parts of
it.
New files are made with creat (in open(2)). An existing file
may be given an additional name by link(2) or symlink; names
are removed by unlink(2). Directories are created and
removed by mkdir(2) and rmdir.
Device files and communication channels (streams) admit a
plethora of special operations, most specific to the device
in question; see ioctl(2) and the device writeups in section
4, especially ttyld(4) for terminals and stream(4) for com-
munications. Pipe(2) creates nameless streams, useful for
local communication. Several streams may be monitored in
parallel by select(2).
Process execution and control
A new process is created when an existing one calls fork(2).
The new (child) process starts out with copies of the
INTRO(2) INTRO(2)
address space and most other attributes of the old (parent)
process. In particular, the child starts out running the
same program as the parent; exec(2) will bring in a differ-
ent one.
Each process has an integer process id, unique among all
currently active processes; a process group id, used to dis-
tribute signals among processes in the same session or win-
dow; a userid and groupid, which determine access permis-
sions; and a character-string login name for the current
user (not the same as permissions). The calls in getuid(2)
retrieve and change these values.
Various events cause software traps (signals): program
errors like addressing violations, software events like the
interrupt key on the terminal, the alarm clock set by
alarm(2), calls to kill (in signal(2)). Most signals termi-
nate the process by default; signal(2) will arrange to trap
or ignore them instead.
A process terminates on receiving a signal or by calling
exit(2). A parent process may call wait (in exit(2)) to wait
for some child to terminate. A single byte of status infor-
mation may be passed from exit to wait.
Timekeeping
Time(2) and ftime return the time of day and related infor-
mation. Times(2) returns runtime accounting for this pro-
cess and its children. Profil arranges to increment various
locations in memory whenever the clock ticks; it is useful
for execution profiling.
Times, profil, and a few other calls measure time in clock
ticks. The clock frequency is given by the constant HZ in
<sys/param.h>; 60 ticks per second in this system.
SEE ALSO
intro(3), perror(3)
DIAGNOSTICS
A `Diagnostics' paragraph appears in the page for each sys-
tem call that has an error return. Unless otherwise stated,
the error value is the integer -1, and the success value is
0. When an error occurs, an error number is assigned to the
external variable errno. Errno is not cleared on successful
calls, so it should be tested only after an error has
occurred.
There is a table of messages that describe the errors and a
routine for printing them; see perror(3). The list below
gives the number, the name (as defined in <errno.h>), and
the perror message for each error type. The reasons for
INTRO(2) INTRO(2)
error returns are explained in general terms; further expla-
nations for less obvious error returns appear in the write-
ups of individual system calls.
0 Error 0
No error has occurred.
1 EPERM Not owner
An attempt was made to modify a file in some way for-
bidden except to its owner or the super-user, or an
ordinary user attempted to do something allowed only to
the super-user.
2 ENOENT No such file or directory
A file name was specified and the file should exist but
didn't, or one of the directories in a path name did
not exist.
3 ESRCH No such process
The process whose number was given to kill did not
exist, or was already dead.
4 EINTR Interrupted system call
A signal which the user has elected to catch occurred
during a system call. If execution is resumed after
processing the signal, it will appear as if the inter-
rupted system call returned this error condition.
5 EIO I/O error
A physical I/O error or timeout occurred, usually in
read, write, or ioctl. This error may in some cases be
returned on a call following the one to which it actu-
ally applies.
6 ENXIO No such device or address
I/O on a special file referred to a device which does
not exist or is off line, or beyond the limits of the
device.
7 E2BIG Arg list too long
An argument list longer than 16384 bytes was presented
to exec.
8 ENOEXEC Exec format error
A request was made to execute a file which, although it
had the appropriate permissions, did not start with a
valid magic number, see a.out(5).
9 EBADF Bad file number
A file descriptor referred to no open file, or a read
(resp. /IR write ) a file which was open only for
writing (resp. reading).
INTRO(2) INTRO(2)
10 ECHILD No children
In wait, the process had no living or unwaited-for
children.
11 EAGAIN No more processes
In fork, the system's process table was full or the
user was not allowed to create any more processes.
12 ENOMEM Not enough memory
During exec or brk, a program asked for more memory or
swap space than the system was able to supply.
13 EACCES Permission denied
An attempt was made to access a file in a way forbidden
by the protection system.
14 EFAULT Bad address
The system encountered a hardware fault in attempting
to access the arguments of a system call.
15 EHASF Directory not empty
An attempt was made to remove a nonempty directory.
16 EBUSY In use
An attempt was made to mount a device that was already
mounted (or crashed or was copied in mounted state), to
dismount a device on which there was an active file
(open file, current directory, mounted-on file, active
text segment), or to remove the current directory of
some process.
17 EEXIST File exists
An existing file was mentioned in an inappropriate con-
text, e.g. link.
18 EXDEV Cross-device link
A link to a file on another device was attempted.
19 ENODEV No such device
An attempt was made to apply an inappropriate system
call to a device; e.g. read a write-only device.
20 ENOTDIR Not a directory
A non-directory was specified where a directory is
required, for example in a path name or as an argument
to chdir.
21 EISDIR Is a directory
An attempt to write on a directory.
22 EINVAL Invalid argument
Some invalid argument: dismounting a non-mounted
INTRO(2) INTRO(2)
device, mentioning an unknown signal in signal, reading
or writing a file for which lseek has generated a nega-
tive pointer. Also set by math functions, see
intro(3).
23 ENFILE File table overflow
The system's table of open files was full, and tem-
porarily no more opens could be accepted.
24 EMFILE Too many open files
The limit is 128 per process.
25 ENOTTY Illegal ioctl
The function code mentioned in ioctl does not apply to
the file or device.
26 ETXTBSY Text file busy
An attempt to execute a pure-procedure program which
was open for writing, or to open for writing a pure-
procedure program that was being executed.
27 EFBIG File too large
The size of a file exceeded the maximum (about 1.0E9
bytes).
28 ENOSPC No space left on device
During a write to an ordinary file, there was no free
space left on the device.
29 ESPIPE Illegal seek
Lseek was issued to a stream device.
30 EROFS Read-only file system
An attempt to modify a file or directory was made on a
device mounted read-only.
31 EMLINK Too many links
An attempt to make more than 32767 links to a file.
32 EPIPE Broken pipe
Write to a stream that has been hung up, usually a pipe
with no process to read the data. This condition nor-
mally generates a signal; the error is returned if the
signal is ignored.
33 EDOM Math argument
The argument of a function in the math package (3M) was
out of the domain of the function.
34 ERANGE Result too large
The value of a function in the math package (3M) was
unrepresentable within machine precision.
INTRO(2) INTRO(2)
35 ELOOP Link loop
An endless cycle of symbolic links was encountered.
36 ECONC Concurrency violation
An open or creat was in violation of the concurrent
access specified for the file.
37 EGREG It's all Greg's fault
Something went wrong.
BUGS
Device and file system drivers may use error codes in unex-
pected or unconventional ways; it is infeasible to list them
all. The writeups in section 4 list some such special
cases.