1 .\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are
7 .\" Redistributions of source code and documentation must retain the above
8 .\" copyright notice, this list of conditions and the following
11 .\" Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
18 .\" This product includes software developed or owned by Caldera
19 .\" International, Inc. Neither the name of Caldera International, Inc.
20 .\" nor the names of other contributors may be used to endorse or promote
21 .\" products derived from this software without specific prior written
24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
25 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28 .\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 .\" @(#)p4 8.1 (Berkeley) 6/8/93
44 This section describes the
45 bottom level of I/O on the
48 The lowest level of I/O in
50 provides no buffering or any other services;
51 it is in fact a direct entry into the operating system.
52 You are entirely on your own,
53 but on the other hand,
54 you have the most control over what happens.
55 And since the calls and usage are quite simple,
56 this isn't as bad as it sounds.
63 all input and output is done
64 by reading or writing files,
65 because all peripheral devices, even the user's terminal,
66 are files in the file system.
67 This means that a single, homogeneous interface
68 handles all communication between a program and peripheral devices.
70 In the most general case,
71 before reading or writing a file,
72 it is necessary to inform the system
73 of your intent to do so,
76 If you are going to write on a file,
77 it may also be necessary to create it.
78 The system checks your right to do so
80 Do you have permission to access it?),
82 returns a small positive integer
86 Whenever I/O is to be done on the file,
87 the file descriptor is used instead of the name to identify the file.
88 (This is roughly analogous to the use of
94 information about an open file is maintained by the system;
95 the user program refers to the file
97 by the file descriptor.
99 The file pointers discussed in section 3
100 are similar in spirit to file descriptors,
101 but file descriptors are more fundamental.
102 A file pointer is a pointer to a structure that contains,
103 among other things, the file descriptor for the file in question.
105 Since input and output involving the user's terminal
107 special arrangements exist to make this convenient.
108 When the command interpreter (the
112 three files, with file descriptors 0, 1, and 2,
113 called the standard input,
114 the standard output, and the standard error output.
115 All of these are normally connected to the terminal,
116 so if a program reads file descriptor 0
117 and writes file descriptors 1 and 2,
118 it can do terminal I/O
119 without worrying about opening the files.
122 to and from files with
128 prog <infile >outfile
130 the shell changes the default assignments for file descriptors
132 from the terminal to the named files.
133 Similar observations hold if the input or output is associated with a pipe.
134 Normally file descriptor 2 remains attached to the terminal,
135 so error messages can go there.
137 the file assignments are changed by the shell,
139 The program does not need to know where its input
140 comes from nor where its output goes,
141 so long as it uses file 0 for input and 1 and 2 for output.
145 All input and output is done by
150 For both, the first argument is a file descriptor.
151 The second argument is a buffer in your program where the data is to
153 The third argument is the number of bytes to be transferred.
156 n_read = read(fd, buf, n);
158 n_written = write(fd, buf, n);
160 Each call returns a byte count
161 which is the number of bytes actually transferred.
163 the number of bytes returned may be less than
164 the number asked for,
167 bytes remained to be read.
168 (When the file is a terminal,
170 normally reads only up to the next newline,
171 which is generally less than what was requested.)
172 A return value of zero bytes implies end of file,
175 indicates an error of some sort.
176 For writing, the returned value is the number of bytes
178 it is generally an error if this isn't equal
179 to the number supposed to be written.
181 The number of bytes to be read or written is quite arbitrary.
182 The two most common values are
184 which means one character at a time
188 which corresponds to a physical blocksize on many peripheral devices.
189 This latter size will be most efficient,
190 but even character at a time I/O
191 is not inordinately expensive.
193 Putting these facts together,
194 we can write a simple program to copy
195 its input to its output.
196 This program will copy anything to anything,
197 since the input and output can be redirected to any file or device.
199 #define BUFSIZE 512 /* best size for PDP-11 UNIX */
201 main() /* copy input to output */
206 while ((n = read(0, buf, BUFSIZE)) > 0)
211 If the file size is not a multiple of
215 will return a smaller number of bytes
223 It is instructive to see how
227 can be used to construct
228 higher level routines like
235 which does unbuffered input.
237 #define CMASK 0377 /* for making char's > 0 */
239 getchar() /* unbuffered single character input */
243 return((read(0, &c, 1) > 0) ? c & CMASK : EOF);
253 accepts a character pointer.
254 The character being returned must be masked with
256 to ensure that it is positive;
257 otherwise sign extension may make it negative.
260 is appropriate for the
262 but not necessarily for other machines.)
264 The second version of
266 does input in big chunks,
267 and hands out the characters one at a time.
269 #define CMASK 0377 /* for making char's > 0 */
272 getchar() /* buffered version */
274 static char buf[BUFSIZE];
275 static char *bufp = buf;
278 if (n == 0) { /* buffer is empty */
279 n = read(0, buf, BUFSIZE);
282 return((--n >= 0) ? *bufp++ & CMASK : EOF);
286 Open, Creat, Close, Unlink
288 Other than the default
289 standard input, output and error files,
290 you must explicitly open files in order to
292 There are two system entry points for this,
301 discussed in the previous section,
302 except that instead of returning a file pointer,
303 it returns a file descriptor,
309 fd = open(name, rwmode);
316 is a character string corresponding to the external file name.
317 The access mode argument
318 is different, however:
320 is 0 for read, 1 for write, and 2 for read and write access.
325 otherwise it returns a valid file descriptor.
330 a file that does not exist.
333 is provided to create new files,
334 or to re-write old ones.
336 fd = creat(name, pmode);
338 returns a file descriptor
339 if it was able to create the file
348 will truncate it to zero length;
349 it is not an error to
351 a file that already exists.
353 If the file is brand new,
365 there are nine bits of protection information
366 associated with a file,
367 controlling read, write and execute permission for
368 the owner of the file,
369 for the owner's group,
371 Thus a three-digit octal number
372 is most convenient for specifying the permissions.
375 specifies read, write and execute permission for the owner,
376 and read and execute permission for the group and everyone else.
379 here is a simplified version of
384 a program which copies one file to another.
385 (The main simplification is that our version
386 copies only one file,
387 and does not permit the second argument
392 #define PMODE 0644 /* RW for owner, R for group, others */
394 main(argc, argv) /* cp: copy f1 to f2 */
402 error("Usage: cp from to", NULL);
403 if ((f1 = open(argv[1], 0)) == -1)
404 error("cp: can't open %s", argv[1]);
405 if ((f2 = creat(argv[2], PMODE)) == -1)
406 error("cp: can't create %s", argv[2]);
408 while ((n = read(f1, buf, BUFSIZE)) > 0)
409 if (write(f2, buf, n) != n)
410 error("cp: write error", NULL);
415 error(s1, s2) /* print error message and die */
425 there is a limit (typically 15-25)
426 on the number of files which a program
427 may have open simultaneously.
428 Accordingly, any program which intends to process
429 many files must be prepared to re-use
433 breaks the connection between a file descriptor
436 file descriptor for use with some other file.
437 Termination of a program
440 or return from the main program closes all open files.
446 from the file system.
448 Random Access \(em Seek and Lseek
450 File I/O is normally sequential:
455 takes place at a position in the file
456 right after the previous one.
457 When necessary, however,
458 a file can be read or written in any arbitrary order.
462 provides a way to move around in
463 a file without actually reading
466 lseek(fd, offset, origin);
468 forces the current position in the file
473 which is taken relative to the location
476 Subsequent reading or writing will begin at that position.
487 can be 0, 1, or 2 to specify that
491 the beginning, from the current position, or from the
492 end of the file respectively.
495 seek to the end before writing:
499 To get back to the beginning (``rewind''),
506 it could also be written as
511 it is possible to treat files more or less like large arrays,
512 at the price of slower access.
513 For example, the following simple function reads any number of bytes
514 from any arbitrary place in a file.
516 get(fd, pos, buf, n) /* read n bytes from position pos */
521 lseek(fd, pos, 0); /* get to pos */
522 return(read(fd, buf, n));
528 the basic entry point to the I/O system
543 integers have only 16 bits,
549 is limited to 65,535;
552 values of 3, 4, 5 cause
554 to multiply the given offset by 512
555 (the number of bytes in one physical block)
558 as if it were 0, 1, or 2 respectively.
559 Thus to get to an arbitrary place in a large file
560 requires two seeks, first one which selects
561 the block, then one which
564 equal to 1 and moves to the desired byte within the block.
568 The routines discussed in this section,
569 and in fact all the routines which are direct entries into the system
571 Usually they indicate an error by returning a value of \-1.
572 Sometimes it is nice to know what sort of error occurred;
573 for this purpose all these routines, when appropriate,
574 leave an error number in the external cell
576 The meanings of the various error numbers are
578 in the introduction to Section II
584 so your program can, for example, determine if
585 an attempt to open a file failed because it did not exist
586 or because the user lacked permission to read it.
587 Perhaps more commonly,
588 you may want to print out the
592 will print a message associated with the value
597 is an array of character strings which can be indexed
600 and printed by your program.