Miscellaneous edits.
[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.  However, 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 @dfn{filename}
221 or @dfn{pathname component} for what this manual calls a file name
222 component.  We don't use this terminology because a ``path'' is
223 something completely different (a list of directories to search), and we
224 think that ``pathname'' used for something else will confuse users.  We
225 always use ``file name'' and ``file name component'' (or sometimes just
226 ``component'', where the context is obvious) in GNU documentation.  Some
227 macros use the POSIX terminology in their names, such as
228 @code{PATH_MAX}.  These macros are defined by the POSIX standard, so we
229 cannot change their names.
230
231 You can find more detailed information about operations on directories
232 in @ref{File System Interface}.
233
234 @node File Name Resolution, File Name Errors, Directories, File Names
235 @subsection File Name Resolution
236
237 A file name consists of file name components separated by slash
238 (@samp{/}) characters.  On the systems that the GNU C library supports,
239 multiple successive @samp{/} characters are equivalent to a single
240 @samp{/} character.
241
242 @cindex file name resolution
243 The process of determining what file a file name refers to is called
244 @dfn{file name resolution}.  This is performed by examining the
245 components that make up a file name in left-to-right order, and locating
246 each successive component in the directory named by the previous
247 component.  Of course, each of the files that are referenced as
248 directories must actually exist, be directories instead of regular
249 files, and have the appropriate permissions to be accessible by the
250 process; otherwise the file name resolution fails.
251
252 @cindex root directory
253 @cindex absolute file name
254 If a file name begins with a @samp{/}, the first component in the file
255 name is located in the @dfn{root directory} of the process (usually all
256 processes on the system have the same root directory).  Such a file name
257 is called an @dfn{absolute file name}.
258 @c !!! xref here to chroot, if we ever document chroot. -rm
259
260 @cindex relative file name
261 Otherwise, the first component in the file name is located in the
262 current working directory (@pxref{Working Directory}).  This kind of
263 file name is called a @dfn{relative file name}.
264
265 @cindex parent directory
266 The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
267 have special meanings.  Every directory has entries for these file name
268 components.  The file name component @file{.} refers to the directory
269 itself, while the file name component @file{..} refers to its
270 @dfn{parent directory} (the directory that contains the link for the
271 directory in question).  As a special case, @file{..} in the root
272 directory refers to the root directory itself, since it has no parent;
273 thus @file{/..} is the same as @file{/}.
274
275 Here are some examples of file names:
276
277 @table @file
278 @item /a
279 The file named @file{a}, in the root directory.
280
281 @item /a/b
282 The file named @file{b}, in the directory named @file{a} in the root directory.
283
284 @item a
285 The file named @file{a}, in the current working directory.
286
287 @item /a/./b
288 This is the same as @file{/a/b}.  
289
290 @item ./a
291 The file named @file{a}, in the current working directory.
292
293 @item ../a
294 The file named @file{a}, in the parent directory of the current working
295 directory.
296 @end table
297
298 @c An empty string may ``work'', but I think it's confusing to 
299 @c try to describe it.  It's not a useful thing for users to use--rms.
300 A file name that names a directory may optionally end in a @samp{/}.
301 You can specify a file name of @file{/} to refer to the root directory,
302 but the empty string is not a meaningful file name.  If you want to
303 refer to the current working directory, use a file name of @file{.} or
304 @file{./}.
305
306 Unlike some other operating systems, the GNU system doesn't have any
307 built-in support for file types (or extensions) or file versions as part
308 of its file name syntax.  Many programs and utilities use conventions
309 for file names---for example, files containing C source code usually
310 have names suffixed with @samp{.c}---but there is nothing in the file
311 system itself that enforces this kind of convention.
312
313 @node File Name Errors, File Name Portability, File Name Resolution, File Names
314 @subsection File Name Errors
315
316 @cindex file name errors
317 @cindex usual file name errors
318
319 Functions that accept file name arguments usually detect these
320 @code{errno} error conditions relating to the file name syntax or
321 trouble finding the named file.  These errors are referred to throughout
322 this manual as the @dfn{usual file name errors}.
323
324 @table @code
325 @item EACCES
326 The process does not have search permission for a directory component 
327 of the file name.
328
329 @item ENAMETOOLONG
330 This error is used when either the the total length of a file name is
331 greater than @code{PATH_MAX}, or when an individual file name component
332 has a length greater than @code{NAME_MAX}.  @xref{Limits for Files}.
333
334 In the GNU system, there is no imposed limit on overall file name
335 length, but some file systems may place limits on the length of a
336 component.
337
338 @item ENOENT
339 This error is reported when a file referenced as a directory component
340 in the file name doesn't exist, or when a component is a symbolic link
341 whose target file does not exist.  @xref{Symbolic Links}.
342
343 @item ENOTDIR
344 A file that is referenced as a directory component in the file name
345 exists, but it isn't a directory.
346
347 @item ELOOP
348 Too many symbolic links were resolved while trying to look up the file
349 name.  The system has an arbitrary limit on the number of symbolic links
350 that may be resolved in looking up a single file name, as a primitive
351 way to detect loops.  @xref{Symbolic Links}.
352 @end table
353
354
355 @node File Name Portability,  , File Name Errors, File Names
356 @subsection Portability of File Names
357
358 The rules for the syntax of file names discussed in @ref{File Names},
359 are the rules normally used by the GNU system and by other POSIX
360 systems.  However, other operating systems may use other conventions.
361
362 There are two reasons why it can be important for you to be aware of
363 file name portability issues:
364
365 @itemize @bullet
366 @item 
367 If your program makes assumptions about file name syntax, or contains
368 embedded literal file name strings, it is more difficult to get it to
369 run under other operating systems that use different syntax conventions.
370
371 @item
372 Even if you are not concerned about running your program on machines
373 that run other operating systems, it may still be possible to access
374 files that use different naming conventions.  For example, you may be
375 able to access file systems on another computer running a different
376 operating system over a network, or read and write disks in formats used
377 by other operating systems.
378 @end itemize
379
380 The ANSI C standard says very little about file name syntax, only that
381 file names are strings.  In addition to varying restrictions on the
382 length of file names and what characters can validly appear in a file
383 name, different operating systems use different conventions and syntax
384 for concepts such as structured directories and file types or
385 extensions.  Some concepts such as file versions might be supported in
386 some operating systems and not by others.
387
388 The POSIX.1 standard allows implementations to put additional
389 restrictions on file name syntax, concerning what characters are
390 permitted in file names and on the length of file name and file name
391 component strings.  However, in the GNU system, you do not need to worry
392 about these restrictions; any character except the null character is
393 permitted in a file name string, and there are no limits on the length
394 of file name strings.
395
396