Low-Level Interface Routines

8.3.4 Low-Level Interface Routines

Low-level interface routines are user-defined functions which are called from library functions in order to implement library functions in accordance with the specifications of the user system. They need to be created in any of the following cases.

(1) When using library functions related to standard I/O or memory management

(2) When a library function has to be a reentrant library

Table 8.2 lists the low-level interface routines used by C library functions.

Table 8.2

List of Low-Level Interface Routines

Name *1	Description
open	Opens file.
close	Closes file.
read	Reads from file.
write	Writes to file.
lseek	Sets the read/write position in a file.
sbrk	Allocates area in memory.
errno_addr *2	Acquires errno address.
wait_sem *2	Defines semaphore.
signal_sem *2	Releases semaphore.

Notes 1.

The function names open, close, read, write, lseek, sbrk, error_addr, wait_sem, and signal_sem are reserved for low-level interface routines. They should not be used in user programs.

Notes 2.

These routines are necessary when the reentrant library is used.

Initialization necessary for low-level interface routines must be performed on program startup. This initialization should be performed using the _INIT_LOWLEVEL function in library initial setting processing (_INITLIB).

Below, after explaining the basic approach to low-level I/O, the specifications for each interface routine are described.

(1)	Approach to I/O

In the standard I/O library, files are managed by means of FILE-type data; but in low-level interface routines, positive integers are assigned in a one-to-one correspondence with actual files for management. These integers are called file numbers.

In the open routine, a file number is provided for a specified filename. The open routine must set the following information such that this number can be used for file input and output.

-	The device type of the file (console, printer, disk file, etc.) (In the cases of special devices such as consoles or printers, special filenames must be set by the system and identified in the open routine.)

-	When using file buffering, information such as the buffer position and size

-	In the case of a disk file, the byte offset from the start of the file to the position for reading or writing

Based on the information set using the open routine, all subsequent I/O (read and write routines) and read/write positioning (lseek routine) is performed.

When output buffering is being used, the close routine should be executed to write the contents of the buffer to the actual file, so that the data area set by the open routine can be reused.

(2)	Specifications of Low-Level Interface Routines

In this section, specifications for low-level interface routines are described. For each routine, the interface for calling the routine, its operation, and information for using the routine are described.

The interface for the routines is indicated using the following format. Low-level interface routines should always be given a prototype declaration. Add "extern C" to declare in the C++ program.

(Routine name)

[Description]

-	(A summary of the routine operations is given)

[Return value]

Normal: (The return value on normal termination is explained)

Error: (The return value when an error occurs is given)

[Parameters]

(Name) (Meaning)

(The name of the parameter (The value passed as a parameter)

appearing in the interface)