Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / io.texi
1 @node Input/Output Overview
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{Input/Output 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 Input/Output}, 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 * Input/Output Concepts::               Some basic information and terminology.
43 * File Names::                          How to refer to a file.
44 @end menu
45
46 @node Input/Output Concepts
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::
70 @end menu
71
72 @node Streams and File Descriptors
73 @subsection Streams and File Descriptors
74
75 When you want to do input or output to a file, you have a choice of two
76 basic mechanisms for representing the connection between your program
77 and the file: file descriptors and streams.  File descriptors are
78 represented as objects of type @code{int}, while streams are represented
79 as @code{FILE *} objects.
80
81 File descriptors provide a primitive, low-level interface to input and
82 output operations.  Both file descriptors and streams can represent a
83 connection to a device (such as a terminal), or a pipe or socket for
84 communicating with another process, as well as a normal file.  But, if
85 you want to do control operations that are specific to a particular kind
86 of device, you must use a file descriptor; there are no facilities to
87 use streams in this way.  You must also use file descriptors if your
88 program needs to do input or output in special modes, such as
89 nonblocking (or polled) input (@pxref{File Status Flags}).
90
91 Streams provide a higher-level interface, layered on top of the
92 primitive file descriptor facilities.  The stream interface treats all
93 kinds of files pretty much alike---the sole exception being the three
94 styles of buffering that you can choose (@pxref{Stream Buffering}).
95
96 The main advantage of using the stream interface is that the set of
97 functions for performing actual input and output operations (as opposed
98 to control operations) on streams is much richer and more powerful than
99 the corresponding facilities for file descriptors.  The file descriptor
100 interface provides only simple functions for transferring blocks of
101 characters, but the stream interface also provides powerful formatted
102 input and output functions (@code{printf} and @code{scanf}) as well as
103 functions for character- and line-oriented input and output.
104
105 Since streams are implemented in terms of file descriptors, you can
106 extract the file descriptor from a stream and perform low-level
107 operations directly on the file descriptor.  You can also initially open
108 a connection as a file descriptor and then make a stream associated with
109 that file descriptor.
110
111 In general, you should stick with using streams rather than file
112 descriptors, unless there is some specific operation you want to do that
113 can only be done on a file descriptor.  If you are a beginning
114 programmer and aren't sure what functions to use, we suggest that you
115 concentrate on the formatted input functions (@pxref{Formatted Input})
116 and formatted output functions (@pxref{Formatted Output}).
117
118 If you are concerned about portability of your programs to systems other
119 than GNU, you should also be aware that file descriptors are not as
120 portable as streams.  You can expect any system running ANSI C to
121 support streams, but non-GNU systems may not support file descriptors at
122 all, or may only implement a subset of the GNU functions that operate on
123 file descriptors.  Most of the file descriptor functions in the GNU
124 library are included in the POSIX.1 standard, however.
125
126 @node File Position
127 @subsection File Position 
128
129 One of the attributes of an open file is its @dfn{file position}
130 that keeps track of where in the file the next character is to be read
131 or written.  In the GNU system, the file position is simply an integer
132 representing the number of bytes from the beginning of the file.
133
134 The file position is normally set to the beginning of the file when it
135 is opened, and each time a character is read or written, the file
136 position is incremented.  In other words, access to the file is normally
137 @dfn{sequential}.
138 @cindex file position
139 @cindex sequential-access files
140
141 Ordinary files permit read or write operations at any position within
142 the file.  Some other kinds of files may also permit this.  Files which
143 do permit this are sometimes referred to as @dfn{random-access} files.
144 You can change the file position using the @code{fseek} function on a
145 stream (@pxref{File Positioning}) or the @code{lseek} function on a file
146 descriptor (@pxref{I/O Primitives}).  If you try to change the file
147 position on a file that doesn't support random access, you get an error.
148 @cindex random-access files
149
150 Streams and descriptors that are opened for @dfn{append access} are
151 treated specially for output: output to such files is @emph{always}
152 appended sequentially to the @emph{end} of the file, regardless of the
153 file position.  But, the file position is still used to control where in
154 the file reading is done.
155 @cindex append-access files
156
157 If you'll think about it, you'll realize that several programs can read
158 a given file at the same time.  In order for each program to be able to
159 read the file at its own pace, each program must have its own file
160 pointer, which is not affected by anything the other programs do.
161
162 In fact, each opening of  a file creates a separate file position.  
163 Thus, if you open a file twice even in the same program, you get two
164 streams or descriptors with independent file positions.
165
166 By contrast, if you open a descriptor and then duplicate it to get 
167 another descriptor, these two descriptors share the same file position:
168 changing the file position of one descriptor will affect the other.
169
170 @node File Names
171 @section File Names
172
173 In order to open a connection to a file, or to perform other operations
174 such as deleting a file, you need some way to refer to the file.  Nearly
175 all files have names that are strings---even files which are actually
176 devices such as tape drives or terminals.  These strings are called
177 @dfn{file names}.  You specify the file name to say which file you want
178 to open or operate on.
179
180 This section describes the conventions for file names and how the
181 operating system works with them.
182 @cindex file name
183
184 @menu
185 * Directories::                 Directories contain entries for files.
186 * File Name Resolution::        A file name specifies how to look up a file.
187 * File Name Errors::            Error conditions relating to file names.
188 * Portability of File Names::
189 @end menu
190
191
192 @node Directories
193 @subsection Directories
194
195 In order to understand the syntax of file names, you need to understand
196 how the file system is organized into a hierarchy of directories.
197
198 @cindex directory
199 @cindex link
200 @cindex directory entry
201 A @dfn{directory} is a file that contains information to associate other
202 files with names; these associations are called @dfn{links} or
203 @dfn{directory entries}.  Sometimes, people speak of ``files in a
204 directory'', but in reality, a directory only contains pointers to
205 files, not the files themselves.
206
207 @cindex file name component
208 The name of a file contained in a directory entry is called a @dfn{file
209 name component}.  In general, a file name consists of a sequence of one
210 or more such components, seperated by the slash character (@samp{/}).  A
211 file name whih is just one component names a file with respect to its
212 directory.  A file name with multiple components names a directory, and
213 then a file in that directory, and so on.
214
215 Some other documents, such as the POSIX standard, use the term
216 @dfn{pathname} for what we call a file name, and either
217 @dfn{filename} or @dfn{pathname component} for what this manual calls a
218 file name component.  We don't use this terminology because a ``path''
219 is something completely different (a list of directories to search), and
220 we think that ``pathname'' used for something else will confuse users.
221 We always use ``file name'' and ``file name component'' (or sometimes
222 just ``component'', where the context is obvious) in GNU documentation.
223
224 You can find more detailed information about operations on directories
225 in @ref{File System Interface}.
226
227 @node File Name Resolution
228 @subsection File Name Resolution
229
230 A file name consists of file name components separated by slash
231 (@samp{/}) characters.  Multiple successive @samp{/} characters are
232 equivalent to a single @samp{/} character.
233
234 @cindex file name resolution
235 The process of determining what file a file name refers to is called
236 @dfn{file name resolution}.  This is performed by examining the
237 components that make up a file name in left-to-right order, and locating
238 each successive component in the directory named by the previous
239 component.  Of course, each of the files that are referenced as
240 directories must actually exist, be directories instead of regular
241 files, and have the appropriate permissions to be accessible by the
242 process; otherwise the file name resolution fails.
243
244 @cindex root directory
245 @cindex absolute file name
246 If a file name begins with a @samp{/}, the first component in the file
247 name is located in the @dfn{root directory} of the process.  Such a file
248 name is called an @dfn{absolute file name}.
249
250 @cindex relative file name
251 Otherwise, the first component in the file name is located in the
252 current working directory (@pxref{Working Directory}).  This kind of
253 file name is called a @dfn{relative file name}.
254
255 @cindex parent directory
256 The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
257 have special meanings.  Every directory has entries for these file name
258 components.  The file name component @file{.} refers to the directory
259 itself, while the file name component @file{..} refers to its
260 @dfn{parent directory} (the directory that contains the link for the
261 directory in question).
262
263 Here are some examples of file names:
264
265 @table @file
266 @item /a
267 The file named @file{a}, in the root directory.
268
269 @item /a/b
270 The file named @file{b}, in the directory named @file{a} in the root directory.
271
272 @item a
273 The file named @file{a}, in the current working directory.
274
275 @item /a/./b
276 This is the same as @file{/a/b}.  
277
278 @item ./a
279 The file named @file{a}, in the current working directory.
280
281 @item ../a
282 The file named @file{a}, in the parent directory of the current working
283 directory.
284 @end table
285
286 A file name that names a directory may optionally end in a @samp{/}.  You
287 can specify a file name of @file{/} to refer to the root directory, but
288 you can't have an empty file name.  If you want to refer to the current
289 working directory, use a file name of @file{.} or @file{./}.
290
291 Unlike some other operating systems, the GNU system doesn't have any
292 built-in support for file types (or extensions) or file versions as part
293 of its file name syntax.  Many programs and utilities use conventions
294 for file names --- for example, files containing C source code usually
295 have names suffixed with @samp{.c} --- but there is nothing in the file
296 system itself that enforces this kind of convention.
297
298 @node File Name Errors
299 @subsection File Name Errors
300
301 @cindex file name syntax errors
302 @cindex usual file name syntax errors
303
304 Functions that accept file name arguments usually detect these
305 @code{errno} error conditions relating to file name syntax.  These
306 errors are referred to throughout this manual as the @dfn{usual file
307 name syntax errors}.
308
309 @table @code
310 @item EACCES
311 The process does not have search permission for a directory component 
312 of the file name.
313
314 @item ENAMETOOLONG
315 This error is used when either the the total length of a file name is
316 greater than @code{PATH_MAX}, or when an individual file name component
317 has a length greater than @code{NAME_MAX}.  @xref{File System Parameters}.
318 @c ??? Do we really have these limits?
319
320 @item ENOENT
321 This error is reported when a file referenced as a directory component
322 in the file name doesn't exist.  It also is used when an empty file name
323 string is supplied.
324
325 @item ENOTDIR
326 A file that is referenced as a directory component in the file name
327 exists, but it isn't a directory.
328 @end table
329
330
331 @node Portability of File Names
332 @subsection Portability of File Names
333
334 The rules for the syntax of file names discussed in @ref{File Names},
335 are the rules normally used by the GNU system and by other POSIX
336 systems.  However, other operating systems may use other conventions.
337
338 There are two reasons why it can be important for you to be aware of
339 file name portability issues:
340
341 @itemize @bullet
342 @item 
343 If your program makes assumptions about file name syntax, or contains
344 embedded literal file name strings, it is more difficult to get it to
345 run under other operating systems that use different syntax conventions.
346
347 @item
348 Even if you are not concerned about running your program on machines
349 that run other operating systems, it may still be possible to access
350 files that use different naming conventions.  For example, you may be
351 able to access file systems on another computer running a different
352 operating system over a network, or read and write disks in formats used
353 by other operating systems.
354 @end itemize
355
356 The ANSI C standard says very little about file name syntax, only that
357 file names are strings.  In addition to varying restrictions on the
358 length of file names and what characters can validly appear in a file
359 name, different operating systems use different conventions and syntax
360 for concepts such as structured directories and file types or
361 extensions.  Some concepts such as file versions might be supported in
362 some operating systems and not by others.
363
364 The POSIX.1 standard allows implementations to put additional
365 restrictions on file name syntax, concerning what characters are
366 permitted in file names and on the length of file name and file name
367 component strings.  However, in the GNU system, you do not need to worry
368 about these restrictions; any character except the null character is
369 permitted in a file name string, and there are no limits on the length
370 of file name strings.
371
372