Performs a direct read from an open file object that was opened by in Direct I/O mode.
#include <zPublics.h>
STATUS zDIORead(
Key_t key,
QUAD unitOffset,
NINT unitsToRead,
ADDR callBackContext,
void (*dioReadCallBack)(
ADDR reserved,
ADDR callBackContext,
NINT retStatus),
void *retBuffer);
(IN) Specifies the file object to be read using Direct I/O (as returned by zOpen or zCreate with the zRR_DIO_MODE set in the requested rights field).
(IN) Specifies a starting location in the file object where the read operation will begin. A unit is 512 bytes in length. For example, unit 0 starts at logical offset 0, unit 1 starts at logical offset 512, etc.
(IN) Specifies the number of 512-byte units to read from the file.
(IN) Specifies a user-provided cookie that is provided back to the user when the call back function is called. This value can be anything you want, if it fits in an ADDR type.
(IN) Points to a callback function:
NULL performs a synchronous read and waits until the read operation completes before it returns.
non-NULL performs an asynchronous read, calls the specified function, and returns when the read is queued.
IMPORTANT:Because the callback function can be called from fast work-to-do routines and can be called from any processor, the callback function must be SMP enabled and non-blocking.
Is used internally to optimize performance and should be ignored.
(IN) Specifies the context for the callback function.
(OUT) Specifies the return code of the callback function.
(OUT) Points to a buffer that contains the data that was read. You must allocate memory for the buffer, and it must be large enough to handle the requested number of units of data (each unit is 512 bytes).
|
zOK |
The operation completed successfully. |
|
non-0 |
An error occurred (see Section 4.1, Return Values for a description). |
|
zERR_FILE_NOT_IN_DIO_MODE |
The file is not in direct file mode. |
A direct read is one that does not go through an internal file system cache buffer. Instead, the data is read directly from the media into the provided buffer. In order to do a direct read, the file object must be opened by calling zOpen or zCreate with the requested rights set to zRR_DIO_MODE.
zDIORead reads the specified number of 512-byte units, starting at the specified logical unitNumber in the file identified by the key. If all units are not read, it fails.
zDIORead works with physical storage media of any sector size. However, it works optimally if the read operation begins on a sector boundary and if the read length is an integral number of sectors; otherwise, the file system must do some internal manipulation to read on non-sector boundaries. For example, if the media is made up of 512-byte sectors, all reads are optimal. However, if the media is made up of 1024 byte sectors, zDIORead works optimally by always reading an even number of units and by starting the reads on an even-numbered unit.
zDIORead bypasses the cache.