Low-Level Routines

Low-level input and output calls do not buffer or format data. Declarations for the low-level functions are given in the include files IO.H, FCNTL.H, SYS\TYPES.H, and SYS\STAT.H. Unlike the stream functions, low-level functions do not require the include file STDIO.H. However, some common constants are defined in STDIO.H; for example, the end-of-file indicator (EOF) may be useful. If your program requires these constants, you must include STDIO.H.

Routine Use

_close Closes a file
_commit Flushes a file to disk
_creat Creates a file
_dup Creates a second handle for a file
_dup2 Reassigns a handle to a file
_eof Tests for end-of-file
_lseek Repositions file pointer to a given location
_open Opens a file
_read Reads data from a file
_sopen Opens a file for file sharing
_tell Gets current file-pointer position
_umask Sets default file-permission mask
_write Writes data to a file

Opening a File

You must open a file before performing I/O functions on it. The _open function opens a file; it can also create the file when opening it. With DOS versions 3.0 and later, you can use _sopen to open a file with file-sharing attributes. The _creat function can create and open a file.

The file can be opened for reading, writing, or both, and opened in either text or binary mode (see “Text and Binary Modes”). The include file FCNTL.H must be included when opening a file, as it contains definitions for flags used in _open. In some cases, the files SYS\TYPES.H and SYS\STAT.H must also be included; for more information, see the reference description for the _open function.

These functions return a file handle, which is normally assigned to an integer variable. You use the variable to refer to the opened file.

Reading and Writing Data

Use the _read and _write routines to read and write to files. These operations begin at the current position in the file. The current position is updated each time a read or write operation occurs.

The _lseek function allows you to place the file pointer anywhere in the file. The next operation occurs at the position you specified. The _tell function indicates the current position of the file pointer. The _eof routine tests for the end of the file.

Low-level I/O routines set the errno variable when an error occurs. Chapter 3, “Global Variables and Standard Types,” describes errno.

Character-oriented devices, such as the console, do not have file pointers. The _lseek and _tell routines have undefined results if used on a handle associated with a device.

Closing Files

The _close function closes an open file. Open files are automatically closed when a program terminates. However, it is a good practice to close a file when your program is finished with it, as there is a limit to the number of files that can be open at one time.

Using Predefined Handles

When a program begins execution, five files are automatically opened: standard input, standard output, standard error, standard auxiliary, and standard print.

Low-level routines can access these files using the following predefined handles:

Stream Handle

stdin 0
stdout 1
stderr 2
stdaux (DOS only) 3
stdprn (DOS only) 4

You can use these file handles without previously opening the files. The files are opened and the handles are assigned when the program starts.

The _dup and _dup2 functions allow you to assign multiple handles for the same file. These functions are typically used to associate the predefined file handles with different files.

With DOS and Windows, you can redirect the standard input and standard output at the operating-system command level. See your operating-system user's manual for a complete discussion of redirection.