Many changes after first published edition and comments from mib; still not finished.
[kopensolaris-gnu/glibc.git] / manual / io.texi
1 @node I/O Overview, I/O on Streams, Pattern Matching, Top
2 @chapter Input/Output Overview
3
4 Most programs need to do either input (reading data) or output (writing
5 data), or most frequently both, in order to do anything useful.  The GNU
6 C library provides such a large selection of input and output functions
7 that the hardest part is often deciding which function is most
8 appropriate!
9
10 This chapter introduces concepts and terminology relating to input
11 and output.  Other chapters relating to the GNU I/O facilities are:
12
13 @itemize @bullet
14 @item
15 @ref{I/O on Streams}, which covers the high-level functions
16 that operate on streams, including formatted input and output.
17
18 @item
19 @ref{Low-Level I/O}, which covers the basic I/O and control
20 functions on file descriptors.
21
22 @item
23 @ref{File System Interface}, which covers functions for operating on
24 directories and for manipulating file attributes such as access modes
25 and ownership.
26
27 @item
28 @ref{Pipes and FIFOs}, which includes information on the basic interprocess
29 communication facilities.
30
31 @item
32 @ref{Sockets}, which covers a more complicated interprocess communication
33 facility with support for networking.
34
35 @item
36 @ref{Low-Level Terminal Interface}, which covers functions for changing
37 how input and output to terminal or other serial devices are processed.
38 @end itemize
39
40
41 @menu
42 * I/O Concepts::       Some basic information and terminology.
43 * File Names::         How to refer to a file.
44 @end menu
45
46 @node I/O Concepts, File Names,  , I/O Overview
47 @section Input/Output Concepts
48
49 Before you can read or write the contents of a file, you must establish
50 a connection or communications channel to the file.  This process is
51 called @dfn{opening} the file.  You can open a file for reading, writing,
52 or both.
53 @cindex opening a file
54
55 The connection to an open file is represented either as a stream or as a
56 file descriptor.  You pass this as an argument to the functions that do
57 the actual read or write operations, to tell them which file to operate
58 on.  Certain functions expect streams, and others are designed to
59 operate on file descriptors.
60
61 When you have finished reading to or writing from the file, you can
62 terminate the connection by @dfn{closing} the file.  Once you have
63 closed a stream or file descriptor, you cannot do any more input or
64 output operations on it.
65
66 @menu
67 * Streams and File Descriptors::    The GNU Library provides two ways
68                                      to access the contents of files.
69 * File Position::                   The number of bytes from the
70                                      beginning of the file.
71 @end menu
72
73 @node Streams and File Descriptors, File Position,  , I/O Concepts
74 @subsection Streams and File Descriptors
75
76 When you want to do input or output to a file, you have a choice of two
77 basic mechanisms for representing the connection between your program
78 and the file: file descriptors and streams.  File descriptors are
79 represented as objects of type @code{int}, while streams are represented
80 as @code{FILE *} objects.
81
82 File descriptors provide a primitive, low-level interface to input and
83 output operations.  Both file descriptors and streams can represent a
84 connection to a device (such as a terminal), or a pipe or socket for
85 communicating with another process, as well as a normal file.  But, if
86 you want to do control operations that are specific to a particular kind
87 of device, you must use a file descriptor; there are no facilities to
88 use streams in this way.  You must also use file descriptors if your
89 program needs to do input or output in special modes, such as
90 nonblocking (or polled) input (@pxref{File Status Flags}).
91
92 Streams provide a higher-level interface, layered on top of the
93 primitive file descriptor facilities.  The stream interface treats all
94 kinds of files pretty much alike---the sole exception being the three
95 styles of buffering that you can choose (@pxref{Stream Buffering}).
96
97 The main advantage of using the stream interface is that the set of
98 functions for performing actual input and output operations (as opposed
99 to control operations) on streams is much richer and more powerful than
100 the corresponding facilities for file descriptors.  The file descriptor
101 interface provides only simple functions for transferring blocks of
102 characters, but the stream interface also provides powerful formatted
103 input and output functions (@code{printf} and @code{scanf}) as well as
104 functions for character- and line-oriented input and output.
105 @c !!! glibc has dprintf, which lets you do printf on an fd.
106
107 Since streams are implemented in terms of file descriptors, you can
108 extract the file descriptor from a stream and perform low-level
109 operations directly on the file descriptor.  You can also initially open
110 a connection as a file descriptor and then make a stream associated with
111 that file descriptor.
112
113 In general, you should stick with using streams rather than file
114 descriptors, unless there is some specific operation you want to do that
115 can only be done on a file descriptor.  If you are a beginning
116 programmer and aren't sure what functions to use, we suggest that you
117 concentrate on the formatted input functions (@pxref{Formatted Input})
118 and formatted output functions (@pxref{Formatted Output}).
119
120 If you are concerned about portability of your programs to systems other
121 than GNU, you should also be aware that file descriptors are not as
122 portable as streams.  You can expect any system running ANSI C to
123 support streams, but non-GNU systems may not support file descriptors at
124 all, or may only implement a subset of the GNU functions that operate on
125 file descriptors.  Most of the file descriptor functions in the GNU
126 library are included in the POSIX.1 standard, however.
127
128 @node File Position,  , Streams and File Descriptors, I/O Concepts
129 @subsection File Position 
130
131 One of the attributes of an open file is its @dfn{file position} that
132 keeps track of where in the file the next character is to be read or
133 written.  In the GNU system, and all POSIX.1 systems, the file position
134 is simply an integer representing the number of bytes from the beginning
135 of the file.
136
137 The file position is normally set to the beginning of the file when it
138 is opened, and each time a character is read or written, the file
139 position is incremented.  In other words, access to the file is normally
140 @dfn{sequential}.
141 @cindex file position
142 @cindex sequential-access files
143
144 Ordinary files permit read or write operations at any position within
145 the file.  Some other kinds of files may also permit this.  Files which
146 do permit this are sometimes referred to as @dfn{random-access} files.
147 You can change the file position using the @code{fseek} function on a
148 stream (@pxref{File Positioning}) or the @code{lseek} function on a file
149 descriptor (@pxref{I/O Primitives}).  If you try to change the file
150 position on a file that doesn't support random access, you get the
151 @code{ESPIPE} error.
152 @cindex random-access files
153
154 Streams and descriptors that are opened for @dfn{append access} are
155 treated specially for output: output to such files is @emph{always}
156 appended sequentially to the @emph{end} of the file, regardless of the
157 file position.  But, the file position is still used to control where in
158 the file reading is done.
159 @cindex append-access files
160
161 If you think about it, you'll realize that several programs can read a
162 given file at the same time.  In order for each program to be able to
163 read the file at its own pace, each program must have its own file
164 pointer, which is not affected by anything the other programs do.
165
166 In fact, each opening of a file creates a separate file position.  
167 Thus, if you open a file twice even in the same program, you get two
168 streams or descriptors with independent file positions.
169
170 By contrast, if you open a descriptor and then duplicate it to get 
171 another descriptor, these two descriptors share the same file position:
172 changing the file position of one descriptor will affect the other.
173
174 @node File Names,  , I/O Concepts, I/O Overview
175 @section File Names
176
177 In order to open a connection to a file, or to perform other operations
178 such as deleting a file, you need some way to refer to the file.  Nearly
179 all files have names that are strings---even files which are actually
180 devices such as tape drives or terminals.  These strings are called
181 @dfn{file names}.  You specify the file name to say which file you want
182 to open or operate on.
183
184 This section describes the conventions for file names and how the
185 operating system works with them.
186 @cindex file name
187
188 @menu
189 * Directories::                 Directories contain entries for files.
190 * File Name Resolution::        A file name specifies how to look up a file.
191 * File Name Errors::            Error conditions relating to file names.
192 * File Name Portability::       File name portability and syntax issues.
193 @end menu
194
195
196 @node Directories, File Name Resolution,  , File Names
197 @subsection Directories
198
199 In order to understand the syntax of file names, you need to understand
200 how the file system is organized into a hierarchy of directories.
201
202 @cindex directory
203 @cindex link
204 @cindex directory entry
205 A @dfn{directory} is a file that contains information to associate other
206 files with names; these associations are called @dfn{links} or
207 @dfn{directory entries}.  Sometimes, people speak of ``files in a
208 directory'', but in reality, a directory only contains pointers to
209 files, not the files themselves.
210
211 @cindex file name component
212 The name of a file contained in a directory entry is called a @dfn{file
213 name component}.  In general, a file name consists of a sequence of one
214 or more such components, separated by the slash character (@samp{/}).  A
215 file name which is just one component names a file with respect to its
216 directory.  A file name with multiple components names a directory, and
217 then a file in that directory, and so on.
218
219 Some other documents, such as the POSIX standard, use the term
220 @dfn{pathname} for what we call a file name, and either
221 @dfn{filename} or @dfn{pathname component} for what this manual calls a
222 file name component.  We don't use this terminology because a ``path''
223 is something completely different (a list of directories to search), and
224 we think that ``pathname'' used for something else will confuse users.
225 We always use ``file name'' and ``file name component'' (or sometimes
226 just ``component'', where the context is obvious) in GNU documentation.
227
228 You can find more detailed information about operations on directories
229 in @ref{File System Interface}.
230
231 @node File Name Resolution, File Name Errors, Directories, File Names
232 @subsection File Name Resolution
233
234 A file name consists of file name components separated by slash
235 (@samp{/}) characters.  On the systems that the GNU C library supports,
236 multiple successive @samp{/} characters are equivalent to a single
237 @samp{/} character.
238
239 @cindex file name resolution
240 The process of determining what file a file name refers to is called
241 @dfn{file name resolution}.  This is performed by examining the
242 components that make up a file name in left-to-right order, and locating
243 each successive component in the directory named by the previous
244 component.  Of course, each of the files that are referenced as
245 directories must actually exist, be directories instead of regular
246 files, and have the appropriate permissions to be accessible by the
247 process; otherwise the file name resolution fails.
248
249 @cindex root directory
250 @cindex absolute file name
251 If a file name begins with a @samp{/}, the first component in the file
252 name is located in the @dfn{root directory} of the process (usually all
253 processes on the system have the same root directory).  Such a file name
254 is called an @dfn{absolute file name}.
255 @c !!! xref here to chroot, if we ever document chroot. -rm
256 @c ??? I don't like the idea of encouraging smoking--rms.
257 @c !!! What the hell is that bad pun supposed to mean?  I don't get it.  -rm
258
259 @cindex relative file name
260 Otherwise, the first component in the file name is located in the
261 current working directory (@pxref{Working Directory}).  This kind of
262 file name is called a @dfn{relative file name}.
263
264 @cindex parent directory
265 The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
266 have special meanings.  Every directory has entries for these file name
267 components.  The file name component @file{.} refers to the directory
268 itself, while the file name component @file{..} refers to its
269 @dfn{parent directory} (the directory that contains the link for the
270 directory in question).  As a special case, @file{..} in the root
271 directory refers to the root directory itself, since it has no parent;
272 thus @file{/..} is the same as @file{/}.
273
274 Here are some examples of file names:
275
276 @table @file
277 @item /a
278 The file named @file{a}, in the root directory.
279
280 @item /a/b
281 The file named @file{b}, in the directory named @file{a} in the root directory.
282
283 @item a
284 The file named @file{a}, in the current working directory.
285
286 @item /a/./b
287 This is the same as @file{/a/b}.  
288
289 @item ./a
290 The file named @file{a}, in the current working directory.
291
292 @item ../a
293 The file named @file{a}, in the parent directory of the current working
294 directory.
295 @end table
296
297 @c An empty string may ``work'', but I think it's confusing to 
298 @c try to describe it.  It's not a useful thing for users to use--rms.
299 A file name that names a directory may optionally end in a @samp{/}.
300 You can specify a file name of @file{/} to refer to the root directory,
301 but the empty string is not a meaningful file name.  If you want to
302 refer to the current working directory, use a file name of @file{.} or
303 @file{./}.
304
305 Unlike some other operating systems, the GNU system doesn't have any
306 built-in support for file types (or extensions) or file versions as part
307 of its file name syntax.  Many programs and utilities use conventions
308 for file names---for example, files containing C source code usually
309 have names suffixed with @samp{.c}---but there is nothing in the file
310 system itself that enforces this kind of convention.
311
312 @node File Name Errors, File Name Portability, File Name Resolution, File Names
313 @subsection File Name Errors
314
315 @cindex file name syntax errors
316 @cindex usual file name syntax errors
317
318 Functions that accept file name arguments usually detect these
319 @code{errno} error conditions relating to file name syntax.  These
320 errors are referred to throughout this manual as the @dfn{usual file
321 name syntax errors}.
322
323 @table @code
324 @item EACCES
325 The process does not have search permission for a directory component 
326 of the file name.
327
328 @item ENAMETOOLONG
329 This error is used when either the the total length of a file name is
330 greater than @code{PATH_MAX}, or when an individual file name component
331 has a length greater than @code{NAME_MAX}.  @xref{Limits for Files}.
332
333 In the GNU system, there is no imposed limit on overall file name
334 length, but some file systems may place limits on the length of a
335 component.
336
337 @item ENOENT
338 This error is reported when a file referenced as a directory component
339 in the file name doesn't exist, or when a component is a symbolic link
340 whose target file does not exist.  @xref{Symbolic Links}.
341
342 @item ENOTDIR
343 A file that is referenced as a directory component in the file name
344 exists, but it isn't a directory.
345
346 @item ELOOP
347 Too many symbolic links were resolved while trying to look up the file
348 name.  The system has an arbitrary limit on the number of symbolic links
349 that may be resolved in looking up a single file name, as a primitive
350 way to detect loops.  @xref{Symbolic Links}.
351 @end table
352
353
354 @node File Name Portability,  , File Name Errors, File Names
355 @subsection Portability of File Names
356
357 The rules for the syntax of file names discussed in @ref{File Names},
358 are the rules normally used by the GNU system and by other POSIX
359 systems.  However, other operating systems may use other conventions.
360
361 There are two reasons why it can be important for you to be aware of
362 file name portability issues:
363
364 @itemize @bullet
365 @item 
366 If your program makes assumptions about file name syntax, or contains
367 embedded literal file name strings, it is more difficult to get it to
368 run under other operating systems that use different syntax conventions.
369
370 @item
371 Even if you are not concerned about running your program on machines
372 that run other operating systems, it may still be possible to access
373 files that use different naming conventions.  For example, you may be
374 able to access file systems on another computer running a different
375 operating system over a network, or read and write disks in formats used
376 by other operating systems.
377 @end itemize
378
379 The ANSI C standard says very little about file name syntax, only that
380 file names are strings.  In addition to varying restrictions on the
381 length of file names and what characters can validly appear in a file
382 name, different operating systems use different conventions and syntax
383 for concepts such as structured directories and file types or
384 extensions.  Some concepts such as file versions might be supported in
385 some operating systems and not by others.
386
387 The POSIX.1 standard allows implementations to put additional
388 restrictions on file name syntax, concerning what characters are
389 permitted in file names and on the length of file name and file name
390 component strings.  However, in the GNU system, you do not need to worry
391 about these restrictions; any character except the null character is
392 permitted in a file name string, and there are no limits on the length
393 of file name strings.
394
395