Initial revision
[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 as a stream or file
56 descriptor.  You pass this as an argument to the functions that do the
57 actual read or write operations, to tell them which file to operate on.
58
59 When you have finished reading to or writing from the file, you can
60 terminate the connection by @dfn{closing} the file.  Once you have
61 closed a stream or file descriptor, you cannot do any more input or
62 output operations on it.
63
64 @menu
65 * Streams and File Descriptors::        The GNU Library provides two ways
66                                          to access the contents of files.
67 * File Position Indicator::
68 @end menu
69
70 @node Streams and File Descriptors
71 @subsection Streams and File Descriptors
72
73 When you want to do input or output to a file, you have a choice of two
74 basic mechanisms for representing the connection between your program
75 and the file: file descriptors and streams.  File descriptors are
76 represented as objects of type @code{int}, while streams are represented
77 as @code{FILE *} objects.
78
79 File descriptors provide a primitive, low-level interface to input and
80 output operations.  Both file descriptors and streams can represent a
81 connection to a device (such as a terminal), or a pipe or socket for
82 communicating with another process, as well as a normal file.  But, if
83 you want to do control operations that are specific to one of these
84 particular kinds of connections, you must deal with it as a file
85 descriptor rather than as a stream.  You must also use file descriptors
86 if your program needs to do input or output in special modes, such as
87 nonblocking (or polled) input.
88
89 Streams provide a higher-level interface, layered on top of the
90 primitive file descriptor facilities.  The stream interface treats all
91 kinds of connections in the same way.
92
93 The main advantage of using the stream interface is that the set of
94 functions for performing actual input and output operations (as opposed
95 to control operations) on streams is much richer and more powerful than
96 the corresponding facilities for file descriptors.  The file descriptor
97 interface provides only simple functions for transferring blocks of
98 characters, but the stream interface also provides powerful
99 formatted input and output functions as well as functions for character-
100 and line-oriented input and output.
101
102 Since streams are implemented in terms of file descriptors, you can
103 extract the file descriptor from a stream and perform low-level
104 operations directly on the file descriptor.  You can also initially open
105 a connection as a file descriptor and then make a stream associated with
106 that file descriptor.
107
108 In general, you should stick with using streams rather than file
109 descriptors, unless there is some specific operation you want to do that
110 can only be done on a file descriptor.  If you are a beginning
111 programmer and aren't sure what functions to use, we suggest that you
112 concentrate on the formatted input and output functions
113 (@pxref{Formatted Input} and @pxref{Formatted Output}, respectively).
114
115 If you are concerned about portability of your programs to systems other
116 than GNU, you should also be aware that file descriptors are not as
117 portable as streams.  You can expect any system running ANSI C to
118 support streams, but non-GNU systems may not support file descriptors at
119 all, or may only implement a subset of the GNU functions that operate on
120 file descriptors.  Most of the file descriptor functions in the GNU
121 library are included in the POSIX.1 standard, however.
122
123 @node File Position Indicator
124 @subsection File Position Indicator
125
126 One of the attributes of an open file is its @dfn{file position indicator}
127 that keeps track of where in the file the next character is to be read
128 or written.  In the GNU system, the file position is simply an integer
129 representing the number of bytes from the beginning of the file.
130
131 The file position is normally set to the beginning of the file when it
132 is opened, and each time a character is read or written, the file
133 position is incremented.  In other words, access to the file is normally
134 @dfn{sequential}.
135 @cindex file position indicator
136 @cindex sequential-access files
137
138 Some kinds of files permit read or write operations at any position
139 within the file; these files are sometimes referred to as
140 @dfn{random-access} files.  You can change the file position indicator
141 using the @code{fseek} function on a stream (@pxref{File Positioning})
142 or the @code{lseek} function on a file descriptor (@pxref{Input and
143 Output Primitives}).
144 @cindex random-access files
145
146 Typically, streams and file descriptors that correspond to real files on
147 a disk and not to interactive devices or pipes to another process can be
148 positioned, but there's no guarantee that @emph{any} file can be
149 positioned.  If you try to perform a file positioning function on a file
150 that doesn't support such operations, it reports failure.
151
152 Files that are opened for @dfn{append access} are treated a little
153 differently.  Output to such files is @emph{always} appended
154 sequentially to the @emph{end} of the file, regardless of the file
155 position.  But, the file position indicator is still used to control
156 where reading occurs in the file.
157 @cindex append-access files
158
159
160 @node File Names
161 @section File Names
162
163 In order to open a connection to a file, or to perform other operations
164 such as deleting a file, you need some way to refer to the file.  Files
165 --- even files that are really entire devices instead of components of a
166 device such as a disk --- can be referred to by names that are strings.
167 These strings are called @dfn{file names}.
168 @cindex file name
169
170 @menu
171 * Directories::                 Directories contain entries for files.
172 * File Name Resolution::        A file name specifies how to look up a file.
173 * Restrictions on File Names::  
174 * File Name Errors::            Error conditions relating to file names.
175 * Portability of File Names::
176 @end menu
177
178
179 @node Directories
180 @subsection Directories
181
182 In order to understand the syntax of file names, you need to understand
183 a little bit about what directories are and how the file system is
184 organized.
185
186 @cindex directory
187 @cindex link
188 @cindex directory entry
189 A @dfn{directory} is a file that contains information to associate other
190 files with names; these associations are called @dfn{links} or
191 @dfn{directory entries}.  Sometimes, people speak of ``files in a
192 directory'', but in reality, a directory only contains pointers to
193 files, not the files themselves.
194
195 @cindex file name component
196 The name of a file contained in a directory entry is called a @dfn{file
197 name component}.  This is distinct from a file name; a file name
198 component names the file relative to a directory it is linked to, while
199 a file name also indicates which directory contains the file.
200
201 Some other documents, such as the POSIX standard, use the term
202 @dfn{pathname} for what this manual calls a file name, and either
203 @dfn{filename} or @dfn{pathname component} for what this manual calls a
204 file name component.  The two sets of terminology can be confusing, but
205 we always use ``file name'' and ``file name component'' (or sometimes
206 just ``component'', where the context is obvious) in this manual.
207
208 You can find more detailed information about operations on directories
209 in @ref{File System Interface}.
210
211
212 @node File Name Resolution
213 @subsection File Name Resolution
214
215 A file name string consists of file name components separated by slash
216 (@samp{/}) characters.  (Multiple successive @samp{/} characters are
217 treated like a single @samp{/} character.)
218
219 @cindex file name resolution
220 The process of determining what file a file name refers to is called
221 @dfn{file name resolution}.  This is performed by examining the
222 components that make up a file name in left-to-right order, and locating
223 each successive component in the directory named by the previous
224 component.  Of course, each of the files that are referenced as
225 directories must actually exist, be directories instead of regular
226 files, and have the appropriate permissions to be accessible by the
227 process; otherwise the file name resolution fails.
228
229 @cindex root directory
230 @cindex absolute file name
231 If a file name begins with a @samp{/}, the first component in the file
232 name is located in the @dfn{root directory} of the process.  Such a file
233 name is called an @dfn{absolute file name}.
234
235 @cindex relative file name
236 Otherwise, the first component in the file name is located in the
237 current working directory (@pxref{Working Directory}).  This kind of
238 file name is called a @dfn{relative file name}.
239
240 @cindex parent directory
241 The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
242 have special meanings.  Every directory has entries for these file name
243 components.  The file name component @file{.} refers to the directory
244 itself, while the file name component @file{..} refers to its
245 @dfn{parent directory} (the directory that contains the link for the
246 directory in question).
247
248 Here are some examples of file names:
249
250 @table @file
251 @item /a
252 The file named @file{a}, in the root directory.
253
254 @item /a/b
255 The file named @file{b}, in the directory named @file{a} in the root directory.
256
257 @item a
258 The file named @file{a}, in the current working directory.
259
260 @item /a/./b
261 This is the same as @file{/a/b}.  
262
263 @item ./a
264 The file named @file{a}, in the current working directory.
265
266 @item ../a
267 The file named @file{a}, in the parent directory of the current working
268 directory.
269 @end table
270
271 A file name that names a directory may optionally end in a @samp{/}.  You
272 can specify a file name of @file{/} to refer to the root directory, but
273 you can't have an empty file name.  If you want to refer to the current
274 working directory, use a file name of @file{.} or @file{./}.
275
276
277 @node Restrictions on File Names
278 @subsection Restrictions on File Names
279
280 Individual file name components of a file name string may not be longer
281 than @code{NAME_MAX} characters.  The GNU system always flags names that
282 are too long as an error condition, but other implementations might just
283 quietly truncate the name instead.
284
285 In addition, the total size of a file name string (including its
286 terminating null character) can be at most @code{PATH_MAX} characters.
287 @xref{File System Parameters}.
288
289 Upper- and lower-case characters are considered distinct in file names.
290 Portable file name components can contain only the letters @samp{a}
291 through @samp{z} and @samp{A} through @samp{Z}; the digits @samp{0}
292 through @samp{9}; and the characters @samp{.} (period), @samp{_}
293 (underscore), and @samp{-} (hyphen).  A hyphen can't be used as the
294 first character of a portable file name component.
295
296 For example, the following file name components are all portable:
297
298 @example
299 "foo.text"
300 "version.13.notes"
301 "README-FIRST"
302 @end example
303
304 @noindent
305 but these file name components are not:
306
307 @example
308 "-delete-me"
309 "vmshost::[LUSER]LOGIN.COM"
310 @end example
311
312 Of course, most POSIX implementations are much less restrictive than
313 this about what characters can appear in file name components, but
314 different implementations might support different extensions.
315
316 @strong{Incomplete:}  What should I say about the GNU system in this
317 respect?
318
319 Unlike some other operating systems, the GNU system doesn't have any
320 built-in support for file types (or extensions) or file versions as part
321 of its file name syntax.  Many programs and utilities use conventions
322 for file names --- for example, files containing C source code usually
323 have names suffixed with @samp{.c} --- but there is nothing in the file
324 system itself that enforces this kind of convention.
325
326
327 @node File Name Errors
328 @subsection File Name Errors
329
330 @cindex file name syntax errors
331 @cindex usual file name syntax errors
332
333 Functions that accept file name arguments usually detect these
334 @code{errno} error conditions relating to file name syntax.  These
335 errors are referred to throughout this manual as the @dfn{usual file
336 name syntax errors}.
337
338 @table @code
339 @item EACCES
340 The process does not have search permission for a directory component 
341 of the file name.
342
343 @item ENAMETOOLONG
344 This error is used when either the the total length of a file name is
345 greater than @code{PATH_MAX}, or when an individual file name component
346 has a length greater than @code{NAME_MAX}.  @xref{File System Parameters}.
347
348 @item ENOENT
349 This error is reported when a file referenced as a directory component
350 in the file name doesn't exist.  It also is used when an empty file name
351 string is supplied.
352
353 @item ENOTDIR
354 A file that is referenced as a directory component in the file name
355 exists, but the file isn't a directory.
356 @end table
357
358
359 @node Portability of File Names
360 @subsection Portability of File Names
361
362 The rules for the syntax of file names discussed in @ref{File Names},
363 are the rules normally used by the GNU system and by other operating
364 systems that are compatible with the POSIX.1 standard.  However, other
365 operating systems may use other conventions.
366
367 There are two reasons why it can be important for you to be aware of
368 file name portability issues:
369
370 @itemize @bullet
371 @item 
372 If your program makes assumptions about file name syntax, or contains
373 embedded literal file name strings, it is more difficult to get it to
374 run under other operating systems that use different syntax conventions.
375
376 @item
377 Even if you are not concerned about running your program on machines
378 that run other operating systems, it may still be possible to access
379 files that use different naming conventions.  For example, you may be
380 able to access file systems on another computer running a different
381 operating system over a network, or read and write disks in formats used
382 by other operating systems.
383 @end itemize
384
385 The ANSI C standard says very little about file name syntax, only that
386 file names are strings.  In addition to the obvious restrictions on the
387 length of file names and what characters can validly appear in a file
388 name, different operating systems use different conventions and syntax
389 for concepts such as structured directories and file types or
390 extensions.  Some concepts such as file versions might be supported in
391 some operating systems and not by others.
392