SLAU132V October 2004 – February 2020
The low-level functions are comprised of seven basic I/O functions: open, read, write, close, lseek, rename, and unlink. These low-level routines provide the interface between the high-level functions and the device-level drivers that actually perform the I/O command on the specified device.
The low-level functions are designed to be appropriate for all I/O methods, even those which are not actually disk files. Abstractly, all I/O channels can be treated as files, although some operations (such as lseek) may not be appropriate. See Section 7.2.3 for more details.
The low-level functions are inspired by, but not identical to, the POSIX functions of the same names.
The low-level functions operate on file descriptors. A file descriptor is an integer returned by open, representing an opened file. Multiple file descriptors may be associated with a file; each has its own independent file position indicator.
#include <file.h>
int open (const char *path, unsigned flags, int file_descriptor);
The open function opens the file specified by path and prepares it for I/O.
O_RDONLY (0x0000) /* open for reading */
O_WRONLY (0x0001) /* open for writing */
O_RDWR (0x0002) /* open for read & write */
O_APPEND (0x0008) /* append on each write */
O_CREAT (0x0200) /* open with file create */
O_TRUNC (0x0400) /* open with truncation */
O_BINARY (0x8000) /* open in binary mode */
Low-level I/O routines allow or disallow some operations depending on the flags used when the file was opened. Some flags may not be meaningful for some devices, depending on how the device implements files.
The next available file descriptor is assigned to each new file opened.
The function returns one of the following values:
| non-negative file descriptor | if successful |
| -1 | on failure |
#include <file.h>
int close (int file_descriptor);
The close function closes the file associated with file_descriptor.
The file_descriptor is the number assigned by open to an opened file.
The return value is one of the following:
| 0 | if successful |
| -1 | on failure |
#include <file.h>
int read (intfile_descriptor, char *buffer, unsignedcount);
The read function reads count characters into the buffer from the file associated with file_descriptor.
The function returns one of the following values:
| 0 | if EOF was encountered before any characters were read |
| # | number of characters read (may be less than count) |
| -1 | on failure |
#include <file.h>
int write (intfile_descriptor, const char *buffer, unsignedcount);
The write function writes the number of characters specified by count from the buffer to the file associated with file_descriptor.
The function returns one of the following values:
| # | number of characters written if successful (may be less than count) |
| -1 | on failure |
#include <file.h>
off_t lseek (intfile_descriptor, off_toffset, intorigin);
The lseek function sets the file position indicator for the given file to a location relative to the specified origin. The file position indicator measures the position in characters from the beginning of the file.
SEEK_SET (0x0000) Beginning of file
SEEK_CUR (0x0001) Current value of the file position indicator
SEEK_END (0x0002) End of file
The return value is one of the following:
| # | new value of the file position indicator if successful |
| (off_t)-1 | on failure |
#include <file.h>
int unlink (const char *path);
The unlink function deletes the file specified by path. Depending on the device, a deleted file may still remain until all file descriptors which have been opened for that file have been closed. See Section 7.2.3.
The path is the filename of the file, including path information and optional device prefix. (See Section 7.2.5.)
The function returns one of the following values:
| 0 | if successful |
| -1 | on failure |
#include {<stdio.h> | <file.h>}
int rename (const char *old_name, const char *new_name);
#include {<cstdio> | <file.h>}
int std::rename (const char *old_name, const char *new_name);
The rename function changes the name of a file.
NOTE
The optional device specified in the new name must match the device of the old name. If they do not match, a file copy would be required to perform the rename, and rename is not capable of this action.
The function returns one of the following values:
| 0 | if successful |
| -1 | on failure |
NOTE
Although rename is a low-level function, it is defined by the C standard and can be used by portable applications.