Changed all @example to @smallexample; misc changes for formatting.
[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}, covering 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}
132 that keeps track of where in the file the next character is to be read
133 or written.  In the GNU system, the file position is simply an integer
134 representing the number of bytes from the beginning of the file.
135
136 The file position is normally set to the beginning of the file when it
137 is opened, and each time a character is read or written, the file
138 position is incremented.  In other words, access to the file is normally
139 @dfn{sequential}.
140 @cindex file position
141 @cindex sequential-access files
142
143 Ordinary files permit read or write operations at any position within
144 the file.  Some other kinds of files may also permit this.  Files which
145 do permit this are sometimes referred to as @dfn{random-access} files.
146 You can change the file position using the @code{fseek} function on a
147 stream (@pxref{File Positioning}) or the @code{lseek} function on a file
148 descriptor (@pxref{I/O Primitives}).  If you try to change the file
149 position on a file that doesn't support random access, you get an error.
150 @cindex random-access files
151
152 Streams and descriptors that are opened for @dfn{append access} are
153 treated specially for output: output to such files is @emph{always}
154 appended sequentially to the @emph{end} of the file, regardless of the
155 file position.  But, the file position is still used to control where in
156 the file reading is done.
157 @cindex append-access files
158
159 If you think about it, you'll realize that several programs can read a
160 given file at the same time.  In order for each program to be able to
161 read the file at its own pace, each program must have its own file
162 pointer, which is not affected by anything the other programs do.
163
164 In fact, each opening of a file creates a separate file position.  
165 Thus, if you open a file twice even in the same program, you get two
166 streams or descriptors with independent file positions.
167
168 By contrast, if you open a descriptor and then duplicate it to get 
169 another descriptor, these two descriptors share the same file position:
170 changing the file position of one descriptor will affect the other.
171
172 @node File Names,  , I/O Concepts, I/O Overview
173 @section File Names
174
175 In order to open a connection to a file, or to perform other operations
176 such as deleting a file, you need some way to refer to the file.  Nearly
177 all files have names that are strings---even files which are actually
178 devices such as tape drives or terminals.  These strings are called
179 @dfn{file names}.  You specify the file name to say which file you want
180 to open or operate on.
181
182 This section describes the conventions for file names and how the
183 operating system works with them.
184 @cindex file name
185
186 @menu
187 * Directories::                 Directories contain entries for files.
188 * File Name Resolution::        A file name specifies how to look up a file.
189 * File Name Errors::            Error conditions relating to file names.
190 * File Name Portability::       File name portability and syntax issues.
191 @end menu
192
193
194 @node Directories, File Name Resolution,  , File Names
195 @subsection Directories
196
197 In order to understand the syntax of file names, you need to understand
198 how the file system is organized into a hierarchy of directories.
199
200 @cindex directory
201 @cindex link
202 @cindex directory entry
203 A @dfn{directory} is a file that contains information to associate other
204 files with names; these associations are called @dfn{links} or
205 @dfn{directory entries}.  Sometimes, people speak of ``files in a
206 directory'', but in reality, a directory only contains pointers to
207 files, not the files themselves.
208
209 @cindex file name component
210 The name of a file contained in a directory entry is called a @dfn{file
211 name component}.  In general, a file name consists of a sequence of one
212 or more such components, separated by the slash character (@samp{/}).  A
213 file name which is just one component names a file with respect to its
214 directory.  A file name with multiple components names a directory, and
215 then a file in that directory, and so on.
216
217 Some other documents, such as the POSIX standard, use the term
218 @dfn{pathname} for what we call a file name, and either
219 @dfn{filename} or @dfn{pathname component} for what this manual calls a
220 file name component.  We don't use this terminology because a ``path''
221 is something completely different (a list of directories to search), and
222 we think that ``pathname'' used for something else will confuse users.
223 We always use ``file name'' and ``file name component'' (or sometimes
224 just ``component'', where the context is obvious) in GNU documentation.
225
226 You can find more detailed information about operations on directories
227 in @ref{File System Interface}.
228
229 @node File Name Resolution, File Name Errors, Directories, File Names
230 @subsection File Name Resolution
231
232 A file name consists of file name components separated by slash
233 (@samp{/}) characters.  On the systems that the GNU C library supports,
234 multiple successive @samp{/} characters are equivalent to a single
235 @samp{/} character.
236
237 @cindex file name resolution
238 The process of determining what file a file name refers to is called
239 @dfn{file name resolution}.  This is performed by examining the
240 components that make up a file name in left-to-right order, and locating
241 each successive component in the directory named by the previous
242 component.  Of course, each of the files that are referenced as
243 directories must actually exist, be directories instead of regular
244 files, and have the appropriate permissions to be accessible by the
245 process; otherwise the file name resolution fails.
246
247 @cindex root directory
248 @cindex absolute file name
249 If a file name begins with a @samp{/}, the first component in the file
250 name is located in the @dfn{root directory} of the process.  Such a file
251 name is called an @dfn{absolute file name}.
252 @c !!! xref here to chroot, if we ever document chroot. -rm
253 @c ??? I don't like the idea of encouraging smoking--rms.
254 @c !!! What the hell is that bad pun supposed to mean?  I don't get it.  -rm
255
256 @cindex relative file name
257 Otherwise, the first component in the file name is located in the
258 current working directory (@pxref{Working Directory}).  This kind of
259 file name is called a @dfn{relative file name}.
260
261 @cindex parent directory
262 The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
263 have special meanings.  Every directory has entries for these file name
264 components.  The file name component @file{.} refers to the directory
265 itself, while the file name component @file{..} refers to its
266 @dfn{parent directory} (the directory that contains the link for the
267 directory in question).
268
269 Here are some examples of file names:
270
271 @table @file
272 @item /a
273 The file named @file{a}, in the root directory.
274
275 @item /a/b
276 The file named @file{b}, in the directory named @file{a} in the root directory.
277
278 @item a
279 The file named @file{a}, in the current working directory.
280
281 @item /a/./b
282 This is the same as @file{/a/b}.  
283
284 @item ./a
285 The file named @file{a}, in the current working directory.
286
287 @item ../a
288 The file named @file{a}, in the parent directory of the current working
289 directory.
290 @end table
291
292 @c An empty string may ``work'', but I think it's confusing to 
293 @c try to describe it.  It's not a useful thing for users to use--rms.
294 A file name that names a directory may optionally end in a @samp{/}.
295 You can specify a file name of @file{/} to refer to the root directory,
296 but the empty string is not a meaningful file name.  If you want to
297 refer to the current working directory, use a file name of @file{.} or
298 @file{./}.
299
300 Unlike some other operating systems, the GNU system doesn't have any
301 built-in support for file types (or extensions) or file versions as part
302 of its file name syntax.  Many programs and utilities use conventions
303 for file names---for example, files containing C source code usually
304 have names suffixed with @samp{.c}---but there is nothing in the file
305 system itself that enforces this kind of convention.
306
307 @node File Name Errors, File Name Portability, File Name Resolution, File Names
308 @subsection File Name Errors
309
310 @cindex file name syntax errors
311 @cindex usual file name syntax errors
312
313 Functions that accept file name arguments usually detect these
314 @code{errno} error conditions relating to file name syntax.  These
315 errors are referred to throughout this manual as the @dfn{usual file
316 name syntax errors}.
317
318 @table @code
319 @item EACCES
320 The process does not have search permission for a directory component 
321 of the file name.
322
323 @item ENAMETOOLONG
324 This error is used when either the the total length of a file name is
325 greater than @code{PATH_MAX}, or when an individual file name component
326 has a length greater than @code{NAME_MAX}.  @xref{Limits for Files}.
327
328 In the GNU system, there is no imposed limit on overall file name
329 length, but some file systems may place limits on the length of a
330 component.
331
332 @item ENOENT
333 This error is reported when a file referenced as a directory component
334 in the file name doesn't exist.
335
336 @item ENOTDIR
337 A file that is referenced as a directory component in the file name
338 exists, but it isn't a directory.
339 @end table
340
341
342 @node File Name Portability,  , File Name Errors, File Names
343 @subsection Portability of File Names
344
345 The rules for the syntax of file names discussed in @ref{File Names},
346 are the rules normally used by the GNU system and by other POSIX
347 systems.  However, other operating systems may use other conventions.
348
349 There are two reasons why it can be important for you to be aware of
350 file name portability issues:
351
352 @itemize @bullet
353 @item 
354 If your program makes assumptions about file name syntax, or contains
355 embedded literal file name strings, it is more difficult to get it to
356 run under other operating systems that use different syntax conventions.
357
358 @item
359 Even if you are not concerned about running your program on machines
360 that run other operating systems, it may still be possible to access
361 files that use different naming conventions.  For example, you may be
362 able to access file systems on another computer running a different
363 operating system over a network, or read and write disks in formats used
364 by other operating systems.
365 @end itemize
366
367 The ANSI C standard says very little about file name syntax, only that
368 file names are strings.  In addition to varying restrictions on the
369 length of file names and what characters can validly appear in a file
370 name, different operating systems use different conventions and syntax
371 for concepts such as structured directories and file types or
372 extensions.  Some concepts such as file versions might be supported in
373 some operating systems and not by others.
374
375 The POSIX.1 standard allows implementations to put additional
376 restrictions on file name syntax, concerning what characters are
377 permitted in file names and on the length of file name and file name
378 component strings.  However, in the GNU system, you do not need to worry
379 about these restrictions; any character except the null character is
380 permitted in a file name string, and there are no limits on the length
381 of file name strings.
382
383