Most programs need to do either input (reading data) or output (writing data), or most frequently both, in order to do anything useful. The GNU C library provides such a large selection of input and output functions that the hardest part is often deciding which function is most appropriate!
This chapter introduces concepts and terminology relating to input and output. Other chapters relating to the GNU I/O facilities are:
Before you can read or write the contents of a file, you must establish a connection or communications channel to the file. This process is called opening the file. You can open a file for reading, writing, or both.
The connection to an open file is represented either as a stream or as a file descriptor. You pass this as an argument to the functions that do the actual read or write operations, to tell them which file to operate on. Certain functions expect streams, and others are designed to operate on file descriptors.
When you have finished reading to or writing from the file, you can terminate the connection by closing the file. Once you have closed a stream or file descriptor, you cannot do any more input or output operations on it.
When you want to do input or output to a file, you have a choice of two
basic mechanisms for representing the connection between your program
and the file: file descriptors and streams. File descriptors are
represented as objects of type int, while streams are represented
as FILE * objects.
File descriptors provide a primitive, low-level interface to input and output operations. Both file descriptors and streams can represent a connection to a device (such as a terminal), or a pipe or socket for communicating with another process, as well as a normal file. But, if you want to do control operations that are specific to a particular kind of device, you must use a file descriptor; there are no facilities to use streams in this way. You must also use file descriptors if your program needs to do input or output in special modes, such as nonblocking (or polled) input (see section File Status Flags).
Streams provide a higher-level interface, layered on top of the primitive file descriptor facilities. The stream interface treats all kinds of files pretty much alike--the sole exception being the three styles of buffering that you can choose (see section Stream Buffering).
The main advantage of using the stream interface is that the set of
functions for performing actual input and output operations (as opposed
to control operations) on streams is much richer and more powerful than
the corresponding facilities for file descriptors. The file descriptor
interface provides only simple functions for transferring blocks of
characters, but the stream interface also provides powerful formatted
input and output functions (printf and scanf) as well as
functions for character- and line-oriented input and output.
Since streams are implemented in terms of file descriptors, you can extract the file descriptor from a stream and perform low-level operations directly on the file descriptor. You can also initially open a connection as a file descriptor and then make a stream associated with that file descriptor.
In general, you should stick with using streams rather than file descriptors, unless there is some specific operation you want to do that can only be done on a file descriptor. If you are a beginning programmer and aren't sure what functions to use, we suggest that you concentrate on the formatted input functions (see section Formatted Input) and formatted output functions (see section Formatted Output).
If you are concerned about portability of your programs to systems other than GNU, you should also be aware that file descriptors are not as portable as streams. You can expect any system running ISO C to support streams, but non-GNU systems may not support file descriptors at all, or may only implement a subset of the GNU functions that operate on file descriptors. Most of the file descriptor functions in the GNU library are included in the POSIX.1 standard, however.
One of the attributes of an open file is its file position that keeps track of where in the file the next character is to be read or written. In the GNU system, and all POSIX.1 systems, the file position is simply an integer representing the number of bytes from the beginning of the file.
The file position is normally set to the beginning of the file when it is opened, and each time a character is read or written, the file position is incremented. In other words, access to the file is normally sequential.
Ordinary files permit read or write operations at any position within
the file. Some other kinds of files may also permit this. Files which
do permit this are sometimes referred to as random-access files.
You can change the file position using the fseek function on a
stream (see section File Positioning) or the lseek function on a file
descriptor (see section Input and Output Primitives). If you try to change the file
position on a file that doesn't support random access, you get the
ESPIPE error.
Streams and descriptors that are opened for append access are treated specially for output: output to such files is always appended sequentially to the end of the file, regardless of the file position. However, the file position is still used to control where in the file reading is done.
If you think about it, you'll realize that several programs can read a given file at the same time. In order for each program to be able to read the file at its own pace, each program must have its own file pointer, which is not affected by anything the other programs do.
In fact, each opening of a file creates a separate file position. Thus, if you open a file twice even in the same program, you get two streams or descriptors with independent file positions.
By contrast, if you open a descriptor and then duplicate it to get another descriptor, these two descriptors share the same file position: changing the file position of one descriptor will affect the other.
In order to open a connection to a file, or to perform other operations such as deleting a file, you need some way to refer to the file. Nearly all files have names that are strings--even files which are actually devices such as tape drives or terminals. These strings are called file names. You specify the file name to say which file you want to open or operate on.
This section describes the conventions for file names and how the operating system works with them.
In order to understand the syntax of file names, you need to understand how the file system is organized into a hierarchy of directories.
A directory is a file that contains information to associate other files with names; these associations are called links or directory entries. Sometimes, people speak of "files in a directory", but in reality, a directory only contains pointers to files, not the files themselves.
The name of a file contained in a directory entry is called a file name component. In general, a file name consists of a sequence of one or more such components, separated by the slash character (`/'). A file name which is just one component names a file with respect to its directory. A file name with multiple components names a directory, and then a file in that directory, and so on.
Some other documents, such as the POSIX standard, use the term
pathname for what we call a file name, and either filename
or pathname component for what this manual calls a file name
component. We don't use this terminology because a "path" is
something completely different (a list of directories to search), and we
think that "pathname" used for something else will confuse users. We
always use "file name" and "file name component" (or sometimes just
"component", where the context is obvious) in GNU documentation. Some
macros use the POSIX terminology in their names, such as
PATH_MAX. These macros are defined by the POSIX standard, so we
cannot change their names.
You can find more detailed information about operations on directories in section File System Interface.
A file name consists of file name components separated by slash (`/') characters. On the systems that the GNU C library supports, multiple successive `/' characters are equivalent to a single `/' character.
The process of determining what file a file name refers to is called file name resolution. This is performed by examining the components that make up a file name in left-to-right order, and locating each successive component in the directory named by the previous component. Of course, each of the files that are referenced as directories must actually exist, be directories instead of regular files, and have the appropriate permissions to be accessible by the process; otherwise the file name resolution fails.
If a file name begins with a `/', the first component in the file name is located in the root directory of the process (usually all processes on the system have the same root directory). Such a file name is called an absolute file name.
Otherwise, the first component in the file name is located in the current working directory (see section Working Directory). This kind of file name is called a relative file name.
The file name components `.' ("dot") and `..' ("dot-dot") have special meanings. Every directory has entries for these file name components. The file name component `.' refers to the directory itself, while the file name component `..' refers to its parent directory (the directory that contains the link for the directory in question). As a special case, `..' in the root directory refers to the root directory itself, since it has no parent; thus `/..' is the same as `/'.
Here are some examples of file names:
A file name that names a directory may optionally end in a `/'. You can specify a file name of `/' to refer to the root directory, but the empty string is not a meaningful file name. If you want to refer to the current working directory, use a file name of `.' or `./'.
Unlike some other operating systems, the GNU system doesn't have any built-in support for file types (or extensions) or file versions as part of its file name syntax. Many programs and utilities use conventions for file names--for example, files containing C source code usually have names suffixed with `.c'---but there is nothing in the file system itself that enforces this kind of convention.
Functions that accept file name arguments usually detect these
errno error conditions relating to the file name syntax or
trouble finding the named file. These errors are referred to throughout
this manual as the usual file name errors.
EACCES
ENAMETOOLONG
PATH_MAX, or when an individual file name component
has a length greater than NAME_MAX. See section Limits on File System Capacity.
In the GNU system, there is no imposed limit on overall file name
length, but some file systems may place limits on the length of a
component.
ENOENT
ENOTDIR
ELOOP
The rules for the syntax of file names discussed in section File Names, are the rules normally used by the GNU system and by other POSIX systems. However, other operating systems may use other conventions.
There are two reasons why it can be important for you to be aware of file name portability issues:
The ISO C standard says very little about file name syntax, only that file names are strings. In addition to varying restrictions on the length of file names and what characters can validly appear in a file name, different operating systems use different conventions and syntax for concepts such as structured directories and file types or extensions. Some concepts such as file versions might be supported in some operating systems and not by others.
The POSIX.1 standard allows implementations to put additional restrictions on file name syntax, concerning what characters are permitted in file names and on the length of file name and file name component strings. However, in the GNU system, you do not need to worry about these restrictions; any character except the null character is permitted in a file name string, and there are no limits on the length of file name strings.
Go to the first, previous, next, last section, table of contents.