![[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 [Research Unix] / researchv10dc / man / man2|
Return to intro.2 CVS log | Up to [Research Unix] / researchv10dc / man / man2 |
1.1 root 1: .TH INTRO 2
2: .de en
3: .HP
4: \\$1 \fL\\$2\fP \\$3
5: .br
6: ..
7: .SH NAME
8: intro, errno \(mi introduction to system calls and error numbers
9: .SH SYNOPSIS
10: .B #include <errno.h>
11: .SH DESCRIPTION
12: Section 2 describes the entries into the operating system.
13: .SS "File I/O"
14: Files are opened for input or output
15: by
16: .IR open (2)
17: or
18: .IR creat .
19: These calls return a integer called a
20: .IR "file descriptor"
21: which identifies the file
22: to subsequent I/O calls,
23: notably
24: .IR read (2)
25: and
26: .IR write .
27: File descriptors range from 0 to 127 in the current system.
28: The system gets to pick the numbers,
29: but they may be reassigned by
30: .IR dup (2)
31: and
32: .IR dup2 .
33: .PP
34: By agreement among user programs,
35: file descriptor 0 is the standard input,
36: 1 is the standard output,
37: 2 is for error messages,
38: and 3 is the controlling terminal if any.
39: The operating system is unaware of these conventions;
40: it is permissible to close file 0,
41: or even to replace it by a file open only for writing,
42: but many programs will be confused by such chicanery.
43: .PP
44: Files are normally read or written in sequential order.
45: .IR Lseek (2)
46: addresses arbitrary locations.
47: .PP
48: Files have associated status,
49: consisting of ownerships,
50: permission modes,
51: access dates,
52: and so on.
53: The status is retrieved by
54: .IR stat (2);
55: the calls in
56: .IR chmod (2)
57: alter parts of it.
58: .PP
59: New files are made with
60: .I creat
61: (in
62: .IR open (2)).
63: An existing file may be given an additional name
64: by
65: .IR link (2)
66: or
67: .IR symlink ;
68: names are removed by
69: .IR unlink (2).
70: Directories are created and removed by
71: .IR mkdir (2)
72: and
73: .IR rmdir .
74: .PP
75: Device files and communication channels
76: (streams)
77: admit a plethora of special operations,
78: most specific to the device in question;
79: see
80: .IR ioctl (2)
81: and the device writeups in section 4,
82: especially
83: .IR ttyld (4)
84: for terminals
85: and
86: .IR stream (4)
87: for communications.
88: .IR Pipe (2)
89: creates nameless streams,
90: useful for local communication.
91: Several streams may be monitored in parallel by
92: .IR select (2).
93: .SS "Process execution and control"
94: A new process is created
95: when an existing one calls
96: .IR fork (2).
97: The new (child) process starts out with
98: copies of the address space and most other attributes
99: of the old (parent) process.
100: In particular,
101: the child starts out running
102: the same program as the parent;
103: .IR exec (2)
104: will bring in a different one.
105: .PP
106: Each process has an integer process id,
107: unique among all currently active processes;
108: a process group id,
109: used to distribute signals
110: among processes in the same session
111: or window;
112: a userid and groupid,
113: which determine access permissions;
114: and
115: a character-string login name
116: for the current user
117: (not the same as permissions).
118: The calls in
119: .IR getuid (2)
120: retrieve and change these values.
121: .PP
122: Various events cause software traps (signals):
123: program errors like addressing violations,
124: software events like the interrupt key on the terminal,
125: the alarm clock set by
126: .IR alarm (2),
127: calls to
128: .IR kill
129: (in
130: .IR signal (2)).
131: Most signals terminate the process by default;
132: .IR signal (2)
133: will arrange to trap or ignore them instead.
134: .PP
135: A process terminates
136: on receiving a signal
137: or by calling
138: .IR exit (2).
139: A parent process may call
140: .I wait
141: (in
142: .IR exit (2))
143: to wait for some child to terminate.
144: A single byte of status information
145: may be passed from
146: .I exit
147: to
148: .IR wait .
149: .SS "Timekeeping"
150: .IR Time (2)
151: and
152: .I ftime
153: return the time of day
154: and related information.
155: .IR Times (2)
156: returns runtime accounting
157: for this process
158: and its children.
159: .IR Profil
160: arranges to increment various locations
161: in memory whenever the clock ticks;
162: it is useful for execution profiling.
163: .PP
164: .IR Times ,
165: .IR profil ,
166: and a few other calls
167: measure time in clock ticks.
168: The clock frequency is given by the constant
169: .B HZ
170: in
171: .BR <sys/param.h> ;
172: 60 ticks per second
173: in this system.
174: .SH SEE ALSO
175: .IR intro (3),
176: .IR perror (3)
177: .SH DIAGNOSTICS
178: A `Diagnostics' paragraph appears in the page for each system call
179: that has an error return.
180: Unless otherwise stated, the error value is the integer \-1,
181: and the success value is 0.
182: When an error occurs,
183: an error number is assigned to
184: the external variable
185: .IR errno .
186: .I Errno
187: is not cleared on successful calls, so it should be tested only
188: after an error has occurred.
189: .PP
190: There is a table of messages that describe the errors
191: and a routine for printing them;
192: see
193: .IR perror (3).
194: The list below gives
195: the number, the name (as defined in
196: .BR <errno.h> ),
197: and the
198: .I perror
199: message for each error type.
200: The reasons for error returns are explained in general terms;
201: further explanations for less obvious error returns
202: appear in the writeups of individual system calls.
203: .en 0 \h'\w'EIO'u' "Error 0
204: No error has occurred.
205: .en 1 EPERM "Not owner
206: An attempt was made to modify a file in some way forbidden
207: except to its owner or the super-user,
208: or an ordinary user attempted to do something
209: allowed only to the super-user.
210: .en 2 ENOENT "No such file or directory
211: A file name was specified
212: and the file should exist but didn't, or one
213: of the directories in a path name did not exist.
214: .en 3 ESRCH "No such process
215: The process whose number was given to
216: .I kill
217: did not exist, or was already dead.
218: .en 4 EINTR "Interrupted system call
219: A signal
220: which the user has elected to catch
221: occurred during a system call.
222: If execution is resumed
223: after processing the signal,
224: it will appear as if the interrupted system call
225: returned this error condition.
226: .en 5 EIO "I/O error
227: A physical I/O error
228: or timeout occurred,
229: usually in
230: .IR read ,
231: .IR write ,
232: or
233: .IR ioctl .
234: This error may in some cases be returned
235: on a call following the one to which it actually applies.
236: .en 6 ENXIO "No such device or address
237: I/O on a special file referred to a device which does not
238: exist or is off line,
239: or beyond the limits of the device.
240: .en 7 E2BIG "Arg list too long
241: An argument list longer than 16384 bytes
242: was presented to
243: .IR exec .
244: .en 8 ENOEXEC "Exec format error
245: A request was made to execute a file
246: which, although it had the appropriate permissions,
247: did not start with a valid magic number, see
248: .IR a.out (5).
249: .en 9 EBADF "Bad file number
250: A file descriptor referred to no
251: open file,
252: or a
253: .I read
254: (resp.
255: /IR write )
256: a file which was open only for writing (resp. reading).
257: .en 10 ECHILD "No children
258: In
259: .IR wait ,
260: the process had no
261: living or unwaited-for children.
262: .en 11 EAGAIN "No more processes
263: In
264: .IR fork ,
265: the system's process table was full
266: or the user was not allowed to create any more
267: processes.
268: .en 12 ENOMEM "Not enough memory
269: During
270: .I exec
271: or
272: .I brk,
273: a program asked for more memory or swap space
274: than the system was able to supply.
275: .en 13 EACCES "Permission denied
276: An attempt was made to access a file in a way forbidden
277: by the protection system.
278: .en 14 EFAULT "Bad address
279: The system encountered a hardware fault in attempting to
280: access the arguments of a system call.
281: .en 15 EHASF "Directory not empty
282: An attempt was made to remove a nonempty directory.
283: .en 16 EBUSY "In use
284: An attempt was made to mount a device that was already mounted
285: (or crashed or was copied in mounted state),
286: to dismount a device
287: on which there was an active file
288: (open file, current directory, mounted-on file, active text segment),
289: or to remove the current directory of some process.
290: .en 17 EEXIST "File exists
291: An existing file was mentioned in an inappropriate context,
292: e.g.
293: .IR link .
294: .en 18 EXDEV "Cross-device link
295: A link to a file on another device
296: was attempted.
297: .en 19 ENODEV "No such device
298: An attempt was made to apply an inappropriate
299: system call to a device;
300: e.g. read a write-only device.
301: .en 20 ENOTDIR "Not a directory
302: A non-directory was specified where a directory
303: is required,
304: for example in a path name or
305: as an argument to
306: .IR chdir .
307: .en 21 EISDIR "Is a directory
308: An attempt to write on a directory.
309: .en 22 EINVAL "Invalid argument
310: Some invalid argument:
311: dismounting a non-mounted
312: device,
313: mentioning an unknown signal in
314: .IR signal ,
315: reading or writing a file for which
316: .I lseek
317: has generated a negative pointer.
318: Also set by math functions, see
319: .IR intro (3).
320: .en 23 ENFILE "File table overflow
321: The system's table of open files was full,
322: and temporarily no more
323: .I opens
324: could be accepted.
325: .en 24 EMFILE "Too many open files
326: The limit is 128 per process.
327: .en 25 ENOTTY "Illegal ioctl
328: The function code mentioned in
329: .I ioctl
330: does not apply to the file or device.
331: .en 26 ETXTBSY "Text file busy
332: An attempt to execute a pure-procedure
333: program which was open for writing,
334: or to open for writing a pure-procedure
335: program that was being executed.
336: .en 27 EFBIG "File too large
337: The size of a file exceeded the maximum (about
338: .if t 10\u\s-29\s+2\d
339: .if n 1.0E9
340: bytes).
341: .en 28 ENOSPC "No space left on device
342: During a
343: .I write
344: to an ordinary file,
345: there was no free space left on the device.
346: .en 29 ESPIPE "Illegal seek
347: .I Lseek
348: was issued to a stream device.
349: .en 30 EROFS "Read-only file system
350: An attempt to modify a file or directory
351: was made
352: on a device mounted read-only.
353: .en 31 EMLINK "Too many links
354: An attempt to make more than 32767 links to a file.
355: .en 32 EPIPE "Broken pipe
356: .I Write
357: to a stream that has been hung up,
358: usually a pipe with no process to read the data.
359: This condition normally generates a signal;
360: the error is returned if the signal is ignored.
361: .en 33 EDOM "Math argument
362: The argument of a function in the math package (3M)
363: was out of the domain of the function.
364: .en 34 ERANGE "Result too large
365: The value of a function in the math package (3M)
366: was unrepresentable within machine precision.
367: .en 35 ELOOP "Link loop
368: An endless cycle of symbolic links was encountered.
369: .en 36 ECONC "Concurrency violation
370: An
371: .I open
372: or
373: .I creat
374: was in violation of the concurrent access specified
375: for the file.
376: .en 37 EGREG "It's all Greg's fault
377: Something went wrong.
378: .SH BUGS
379: Device and file system drivers
380: may use error codes in
381: unexpected or unconventional ways;
382: it is infeasible to list them all.
383: The writeups in section 4
384: list some such special cases.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.