"GNU Library" => "GNU library", as per RMS.
[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 * File Name Errors::            Error conditions relating to file names.
174 * Portability of File Names::
175 @end menu
176
177
178 @node Directories
179 @subsection Directories
180
181 In order to understand the syntax of file names, you need to understand
182 a little bit about what directories are and how the file system is
183 organized.
184
185 @cindex directory
186 @cindex link
187 @cindex directory entry
188 A @dfn{directory} is a file that contains information to associate other
189 files with names; these associations are called @dfn{links} or
190 @dfn{directory entries}.  Sometimes, people speak of ``files in a
191 directory'', but in reality, a directory only contains pointers to
192 files, not the files themselves.
193
194 @cindex file name component
195 The name of a file contained in a directory entry is called a @dfn{file
196 name component}.  This is distinct from a file name; a file name
197 component names the file relative to a directory it is linked to, while
198 a file name also indicates which directory contains the file.
199
200 Some other documents, such as the POSIX standard, use the term
201 @dfn{pathname} for what this manual calls a file name, and either
202 @dfn{filename} or @dfn{pathname component} for what this manual calls a
203 file name component.  The two sets of terminology can be confusing, but
204 we always use ``file name'' and ``file name component'' (or sometimes
205 just ``component'', where the context is obvious) in this manual.
206
207 You can find more detailed information about operations on directories
208 in @ref{File System Interface}.
209
210
211 @node File Name Resolution
212 @subsection File Name Resolution
213
214 A file name string consists of file name components separated by slash
215 (@samp{/}) characters.  (Multiple successive @samp{/} characters are
216 treated like a single @samp{/} character.)
217
218 @cindex file name resolution
219 The process of determining what file a file name refers to is called
220 @dfn{file name resolution}.  This is performed by examining the
221 components that make up a file name in left-to-right order, and locating
222 each successive component in the directory named by the previous
223 component.  Of course, each of the files that are referenced as
224 directories must actually exist, be directories instead of regular
225 files, and have the appropriate permissions to be accessible by the
226 process; otherwise the file name resolution fails.
227
228 @cindex root directory
229 @cindex absolute file name
230 If a file name begins with a @samp{/}, the first component in the file
231 name is located in the @dfn{root directory} of the process.  Such a file
232 name is called an @dfn{absolute file name}.
233
234 @cindex relative file name
235 Otherwise, the first component in the file name is located in the
236 current working directory (@pxref{Working Directory}).  This kind of
237 file name is called a @dfn{relative file name}.
238
239 @cindex parent directory
240 The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
241 have special meanings.  Every directory has entries for these file name
242 components.  The file name component @file{.} refers to the directory
243 itself, while the file name component @file{..} refers to its
244 @dfn{parent directory} (the directory that contains the link for the
245 directory in question).
246
247 Here are some examples of file names:
248
249 @table @file
250 @item /a
251 The file named @file{a}, in the root directory.
252
253 @item /a/b
254 The file named @file{b}, in the directory named @file{a} in the root directory.
255
256 @item a
257 The file named @file{a}, in the current working directory.
258
259 @item /a/./b
260 This is the same as @file{/a/b}.  
261
262 @item ./a
263 The file named @file{a}, in the current working directory.
264
265 @item ../a
266 The file named @file{a}, in the parent directory of the current working
267 directory.
268 @end table
269
270 A file name that names a directory may optionally end in a @samp{/}.  You
271 can specify a file name of @file{/} to refer to the root directory, but
272 you can't have an empty file name.  If you want to refer to the current
273 working directory, use a file name of @file{.} or @file{./}.
274
275 Unlike some other operating systems, the GNU system doesn't have any
276 built-in support for file types (or extensions) or file versions as part
277 of its file name syntax.  Many programs and utilities use conventions
278 for file names --- for example, files containing C source code usually
279 have names suffixed with @samp{.c} --- but there is nothing in the file
280 system itself that enforces this kind of convention.
281
282 @node File Name Errors
283 @subsection File Name Errors
284
285 @cindex file name syntax errors
286 @cindex usual file name syntax errors
287
288 Functions that accept file name arguments usually detect these
289 @code{errno} error conditions relating to file name syntax.  These
290 errors are referred to throughout this manual as the @dfn{usual file
291 name syntax errors}.
292
293 @table @code
294 @item EACCES
295 The process does not have search permission for a directory component 
296 of the file name.
297
298 @item ENAMETOOLONG
299 This error is used when either the the total length of a file name is
300 greater than @code{PATH_MAX}, or when an individual file name component
301 has a length greater than @code{NAME_MAX}.  @xref{File System Parameters}.
302
303 @item ENOENT
304 This error is reported when a file referenced as a directory component
305 in the file name doesn't exist.  It also is used when an empty file name
306 string is supplied.
307
308 @item ENOTDIR
309 A file that is referenced as a directory component in the file name
310 exists, but the file isn't a directory.
311 @end table
312
313
314 @node Portability of File Names
315 @subsection Portability of File Names
316
317 The rules for the syntax of file names discussed in @ref{File Names},
318 are the rules normally used by the GNU system and by other POSIX
319 systems.  However, other operating systems may use other conventions.
320
321 There are two reasons why it can be important for you to be aware of
322 file name portability issues:
323
324 @itemize @bullet
325 @item 
326 If your program makes assumptions about file name syntax, or contains
327 embedded literal file name strings, it is more difficult to get it to
328 run under other operating systems that use different syntax conventions.
329
330 @item
331 Even if you are not concerned about running your program on machines
332 that run other operating systems, it may still be possible to access
333 files that use different naming conventions.  For example, you may be
334 able to access file systems on another computer running a different
335 operating system over a network, or read and write disks in formats used
336 by other operating systems.
337 @end itemize
338
339 The ANSI C standard says very little about file name syntax, only that
340 file names are strings.  In addition to the obvious restrictions on the
341 length of file names and what characters can validly appear in a file
342 name, different operating systems use different conventions and syntax
343 for concepts such as structured directories and file types or
344 extensions.  Some concepts such as file versions might be supported in
345 some operating systems and not by others.
346
347 The POSIX.1 standard allows implementations to put additional
348 restrictions on file name syntax, concerning what characters are
349 permitted in file names and on the length of file name and file name
350 component strings.  However, in the GNU system, you do not need to
351 worry about these restrictions; any character is permitted in a file
352 name string, and there are no limits on the length of file name strings.
353
354