ACHTUNG: AS OF 20110523, THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI: http://whiki.wanderinghorse.net/wikis/whio/?page=whio_dev

whio_dev API

whio_dev is a C struct (declared in <wh/whio/whio_dev.h>) which defines an interface for basic random-access i/o operations. It essentially defines the same functionality as are available for standard FILE handles.

whio_dev specifies only an interface, and instances of concrete implementations are created via various factory functions (declared in <wh/whio/whio_devs.h>). Probably its most useful feature is that all i/o devices are destroyed using the same interface - only their construction is type-specific. This simplifies clean-up in client code, e.g. compared to having to know whether a give FILE handle must be closed with fclose(3) or pclose(3).

Implementations are provided for the following types of i/o devices:

• Local files, either by filename, FILE handle, or file descriptor. There are various methods for opening them, depending on what interface you prefer to use (e.g. using open(2)-style arguments or fopen(3)-style). For files there are two different implementations - one uses the low-level read(2)/write(2) interfaces and one uses the higher-level FILE abstraction.
• A dynamically-allocated memory buffer which grows as the device grows.
• A bounded, user-supplied memory range, either in read-write or read-only modes.
• The "subdevice" class acts as a proxy for a client-defined range of bytes within another (parent) device. Subdevices are used to fence access to a certain range of bytes within the parent (a subdevice won't let the user write past its logical end), and subdevices can be nested within other subdevices.
• The whio_epfs bits support "embedded" files which the client interacts with via the whio_dev interface. (It also uses whio_dev as the back-end storage, which means that one EPFS can be embedded in another.)

In principal, it is normally simple to create whio_dev implementations for any type of device which provides facilities for random access. In doing so, any generic i/o algorithms, or code which uses the whio_dev interface for its i/o, can use such client-supplied whio_dev implementations. For example, whio_epfs and whio_udb can use any compliant client-written device for their underlying storage.

See also...

• whio_stream, an interface for sequential-only device access.
• whio_epfs, an embedded filesystem based on the whio_dev API.
• whio_udb, a whio_dev-base hashtable.
• whio_ht, another whio_dev-base hashtable.
• whio_vlbm, a storage-based "memory allocator."