![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to p4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog|
Return to p4 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog |
1.1 root 1: .\" @(#)p4 6.2 (Berkeley) 5/9/86
2: .\"
3: .NH
4: LOW-LEVEL I/O
5: .PP
6: This section describes the
7: bottom level of I/O on the
8: .UC UNIX
9: system.
10: The lowest level of I/O in
11: .UC UNIX
12: provides no buffering or any other services;
13: it is in fact a direct entry into the operating system.
14: You are entirely on your own,
15: but on the other hand,
16: you have the most control over what happens.
17: And since the calls and usage are quite simple,
18: this isn't as bad as it sounds.
19: .NH 2
20: File Descriptors
21: .PP
22: In the
23: .UC UNIX
24: operating system,
25: all input and output is done
26: by reading or writing files,
27: because all peripheral devices, even the user's terminal,
28: are files in the file system.
29: This means that a single, homogeneous interface
30: handles all communication between a program and peripheral devices.
31: .PP
32: In the most general case,
33: before reading or writing a file,
34: it is necessary to inform the system
35: of your intent to do so,
36: a process called
37: ``opening'' the file.
38: If you are going to write on a file,
39: it may also be necessary to create it.
40: The system checks your right to do so
41: (Does the file exist?
42: Do you have permission to access it?),
43: and if all is well,
44: returns a small positive integer
45: called a
46: .ul
47: file descriptor.
48: Whenever I/O is to be done on the file,
49: the file descriptor is used instead of the name to identify the file.
50: (This is roughly analogous to the use of
51: .UC READ(5,...)
52: and
53: .UC WRITE(6,...)
54: in Fortran.)
55: All
56: information about an open file is maintained by the system;
57: the user program refers to the file
58: only
59: by the file descriptor.
60: .PP
61: The file pointers discussed in section 3
62: are similar in spirit to file descriptors,
63: but file descriptors are more fundamental.
64: A file pointer is a pointer to a structure that contains,
65: among other things, the file descriptor for the file in question.
66: .PP
67: Since input and output involving the user's terminal
68: are so common,
69: special arrangements exist to make this convenient.
70: When the command interpreter (the
71: ``shell'')
72: runs a program,
73: it opens
74: three files, with file descriptors 0, 1, and 2,
75: called the standard input,
76: the standard output, and the standard error output.
77: All of these are normally connected to the terminal,
78: so if a program reads file descriptor 0
79: and writes file descriptors 1 and 2,
80: it can do terminal I/O
81: without worrying about opening the files.
82: .PP
83: If I/O is redirected
84: to and from files with
85: .UL <
86: and
87: .UL > ,
88: as in
89: .P1
90: prog <infile >outfile
91: .P2
92: the shell changes the default assignments for file descriptors
93: 0 and 1
94: from the terminal to the named files.
95: Similar observations hold if the input or output is associated with a pipe.
96: Normally file descriptor 2 remains attached to the terminal,
97: so error messages can go there.
98: In all cases,
99: the file assignments are changed by the shell,
100: not by the program.
101: The program does not need to know where its input
102: comes from nor where its output goes,
103: so long as it uses file 0 for input and 1 and 2 for output.
104: .NH 2
105: Read and Write
106: .PP
107: All input and output is done by
108: two functions called
109: .UL read
110: and
111: .UL write .
112: For both, the first argument is a file descriptor.
113: The second argument is a buffer in your program where the data is to
114: come from or go to.
115: The third argument is the number of bytes to be transferred.
116: The calls are
117: .P1
118: n_read = read(fd, buf, n);
119:
120: n_written = write(fd, buf, n);
121: .P2
122: Each call returns a byte count
123: which is the number of bytes actually transferred.
124: On reading,
125: the number of bytes returned may be less than
126: the number asked for,
127: because fewer than
128: .UL n
129: bytes remained to be read.
130: (When the file is a terminal,
131: .UL read
132: normally reads only up to the next newline,
133: which is generally less than what was requested.)
134: A return value of zero bytes implies end of file,
135: and
136: .UL -1
137: indicates an error of some sort.
138: For writing, the returned value is the number of bytes
139: actually written;
140: it is generally an error if this isn't equal
141: to the number supposed to be written.
142: .PP
143: The number of bytes to be read or written is quite arbitrary.
144: The two most common values are
145: 1,
146: which means one character at a time
147: (``unbuffered''),
148: and
149: 512,
150: which corresponds to a physical blocksize on many peripheral devices.
151: This latter size will be most efficient,
152: but even character at a time I/O
153: is not inordinately expensive.
154: .PP
155: Putting these facts together,
156: we can write a simple program to copy
157: its input to its output.
158: This program will copy anything to anything,
159: since the input and output can be redirected to any file or device.
160: .P1
161: #define BUFSIZE 512 /* best size for PDP-11 UNIX */
162:
163: main() /* copy input to output */
164: {
165: char buf[BUFSIZE];
166: int n;
167:
168: while ((n = read(0, buf, BUFSIZE)) > 0)
169: write(1, buf, n);
170: exit(0);
171: }
172: .P2
173: If the file size is not a multiple of
174: .UL BUFSIZE ,
175: some
176: .UL read
177: will return a smaller number of bytes
178: to be written by
179: .UL write ;
180: the next call to
181: .UL read
182: after that
183: will return zero.
184: .PP
185: It is instructive to see how
186: .UL read
187: and
188: .UL write
189: can be used to construct
190: higher level routines like
191: .UL getchar ,
192: .UL putchar ,
193: etc.
194: For example,
195: here is a version of
196: .UL getchar
197: which does unbuffered input.
198: .P1
199: #define CMASK 0377 /* for making char's > 0 */
200:
201: getchar() /* unbuffered single character input */
202: {
203: char c;
204:
205: return((read(0, &c, 1) > 0) ? c & CMASK : EOF);
206: }
207: .P2
208: .UL c
209: .ul
210: must
211: be declared
212: .UL char ,
213: because
214: .UL read
215: accepts a character pointer.
216: The character being returned must be masked with
217: .UL 0377
218: to ensure that it is positive;
219: otherwise sign extension may make it negative.
220: (The constant
221: .UL 0377
222: is appropriate for the
223: .UC PDP -11
224: but not necessarily for other machines.)
225: .PP
226: The second version of
227: .UL getchar
228: does input in big chunks,
229: and hands out the characters one at a time.
230: .P1
231: #define CMASK 0377 /* for making char's > 0 */
232: #define BUFSIZE 512
233:
234: getchar() /* buffered version */
235: {
236: static char buf[BUFSIZE];
237: static char *bufp = buf;
238: static int n = 0;
239:
240: if (n == 0) { /* buffer is empty */
241: n = read(0, buf, BUFSIZE);
242: bufp = buf;
243: }
244: return((--n >= 0) ? *bufp++ & CMASK : EOF);
245: }
246: .P2
247: .NH 2
248: Open, Creat, Close, Unlink
249: .PP
250: Other than the default
251: standard input, output and error files,
252: you must explicitly open files in order to
253: read or write them.
254: There are two system entry points for this,
255: .UL open
256: and
257: .UL creat
258: [sic].
259: .PP
260: .UL open
261: is rather like the
262: .UL fopen
263: discussed in the previous section,
264: except that instead of returning a file pointer,
265: it returns a file descriptor,
266: which is just an
267: .UL int .
268: .P1
269: int fd;
270:
271: fd = open(name, rwmode);
272: .P2
273: As with
274: .UL fopen ,
275: the
276: .UL name
277: argument
278: is a character string corresponding to the external file name.
279: The access mode argument
280: is different, however:
281: .UL rwmode
282: is 0 for read, 1 for write, and 2 for read and write access.
283: .UL open
284: returns
285: .UL -1
286: if any error occurs;
287: otherwise it returns a valid file descriptor.
288: .PP
289: It is an error to
290: try to
291: .UL open
292: a file that does not exist.
293: The entry point
294: .UL creat
295: is provided to create new files,
296: or to re-write old ones.
297: .P1
298: fd = creat(name, pmode);
299: .P2
300: returns a file descriptor
301: if it was able to create the file
302: called
303: .UL name ,
304: and
305: .UL -1
306: if not.
307: If the file
308: already exists,
309: .UL creat
310: will truncate it to zero length;
311: it is not an error to
312: .UL creat
313: a file that already exists.
314: .PP
315: If the file is brand new,
316: .UL creat
317: creates it with the
318: .ul
319: protection mode
320: specified by
321: the
322: .UL pmode
323: argument.
324: In the
325: .UC UNIX
326: file system,
327: there are nine bits of protection information
328: associated with a file,
329: controlling read, write and execute permission for
330: the owner of the file,
331: for the owner's group,
332: and for all others.
333: Thus a three-digit octal number
334: is most convenient for specifying the permissions.
335: For example,
336: 0755
337: specifies read, write and execute permission for the owner,
338: and read and execute permission for the group and everyone else.
339: .PP
340: To illustrate,
341: here is a simplified version of
342: the
343: .UC UNIX
344: utility
345: .IT cp ,
346: a program which copies one file to another.
347: (The main simplification is that our version
348: copies only one file,
349: and does not permit the second argument
350: to be a directory.)
351: .P1
352: #define NULL 0
353: #define BUFSIZE 512
354: #define PMODE 0644 /* RW for owner, R for group, others */
355:
356: main(argc, argv) /* cp: copy f1 to f2 */
357: int argc;
358: char *argv[];
359: {
360: int f1, f2, n;
361: char buf[BUFSIZE];
362:
363: if (argc != 3)
364: error("Usage: cp from to", NULL);
365: if ((f1 = open(argv[1], 0)) == -1)
366: error("cp: can't open %s", argv[1]);
367: if ((f2 = creat(argv[2], PMODE)) == -1)
368: error("cp: can't create %s", argv[2]);
369:
370: while ((n = read(f1, buf, BUFSIZE)) > 0)
371: if (write(f2, buf, n) != n)
372: error("cp: write error", NULL);
373: exit(0);
374: }
375: .P2
376: .P1
377: error(s1, s2) /* print error message and die */
378: char *s1, *s2;
379: {
380: printf(s1, s2);
381: printf("\en");
382: exit(1);
383: }
384: .P2
385: .PP
386: As we said earlier,
387: there is a limit (typically 15-25)
388: on the number of files which a program
389: may have open simultaneously.
390: Accordingly, any program which intends to process
391: many files must be prepared to re-use
392: file descriptors.
393: The routine
394: .UL close
395: breaks the connection between a file descriptor
396: and an open file,
397: and frees the
398: file descriptor for use with some other file.
399: Termination of a program
400: via
401: .UL exit
402: or return from the main program closes all open files.
403: .PP
404: The function
405: .UL unlink(filename)
406: removes the file
407: .UL filename
408: from the file system.
409: .NH 2
410: Random Access \(em Seek and Lseek
411: .PP
412: File I/O is normally sequential:
413: each
414: .UL read
415: or
416: .UL write
417: takes place at a position in the file
418: right after the previous one.
419: When necessary, however,
420: a file can be read or written in any arbitrary order.
421: The
422: system call
423: .UL lseek
424: provides a way to move around in
425: a file without actually reading
426: or writing:
427: .P1
428: lseek(fd, offset, origin);
429: .P2
430: forces the current position in the file
431: whose descriptor is
432: .UL fd
433: to move to position
434: .UL offset ,
435: which is taken relative to the location
436: specified by
437: .UL origin .
438: Subsequent reading or writing will begin at that position.
439: .UL offset
440: is
441: a
442: .UL long ;
443: .UL fd
444: and
445: .UL origin
446: are
447: .UL int 's.
448: .UL origin
449: can be 0, 1, or 2 to specify that
450: .UL offset
451: is to be
452: measured from
453: the beginning, from the current position, or from the
454: end of the file respectively.
455: For example,
456: to append to a file,
457: seek to the end before writing:
458: .P1
459: lseek(fd, 0L, 2);
460: .P2
461: To get back to the beginning (``rewind''),
462: .P1
463: lseek(fd, 0L, 0);
464: .P2
465: Notice the
466: .UL 0L
467: argument;
468: it could also be written as
469: .UL (long)\ 0 .
470: .PP
471: With
472: .UL lseek ,
473: it is possible to treat files more or less like large arrays,
474: at the price of slower access.
475: For example, the following simple function reads any number of bytes
476: from any arbitrary place in a file.
477: .P1
478: get(fd, pos, buf, n) /* read n bytes from position pos */
479: int fd, n;
480: long pos;
481: char *buf;
482: {
483: lseek(fd, pos, 0); /* get to pos */
484: return(read(fd, buf, n));
485: }
486: .P2
487: .PP
488: In pre-version 7
489: .UC UNIX ,
490: the basic entry point to the I/O system
491: is called
492: .UL seek .
493: .UL seek
494: is identical to
495: .UL lseek ,
496: except that its
497: .UL offset
498: argument is an
499: .UL int
500: rather than a
501: .UL long .
502: Accordingly,
503: since
504: .UC PDP -11
505: integers have only 16 bits,
506: the
507: .UL offset
508: specified
509: for
510: .UL seek
511: is limited to 65,535;
512: for this reason,
513: .UL origin
514: values of 3, 4, 5 cause
515: .UL seek
516: to multiply the given offset by 512
517: (the number of bytes in one physical block)
518: and then interpret
519: .UL origin
520: as if it were 0, 1, or 2 respectively.
521: Thus to get to an arbitrary place in a large file
522: requires two seeks, first one which selects
523: the block, then one which
524: has
525: .UL origin
526: equal to 1 and moves to the desired byte within the block.
527: .NH 2
528: Error Processing
529: .PP
530: The routines discussed in this section,
531: and in fact all the routines which are direct entries into the system
532: can incur errors.
533: Usually they indicate an error by returning a value of \-1.
534: Sometimes it is nice to know what sort of error occurred;
535: for this purpose all these routines, when appropriate,
536: leave an error number in the external cell
537: .UL errno .
538: The meanings of the various error numbers are
539: listed
540: in the introduction to Section II
541: of the
542: .I
543: .UC UNIX
544: Programmer's Manual,
545: .R
546: so your program can, for example, determine if
547: an attempt to open a file failed because it did not exist
548: or because the user lacked permission to read it.
549: Perhaps more commonly,
550: you may want to print out the
551: reason for failure.
552: The routine
553: .UL perror
554: will print a message associated with the value
555: of
556: .UL errno ;
557: more generally,
558: .UL sys\_errno
559: is an array of character strings which can be indexed
560: by
561: .UL errno
562: and printed by your program.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.