int io_read (resmgr_context_t * ctp , io_read_t * msg , RESMGR_OCB_T * ocb )
Classification: I/O
Default handler: iofunc_read_default()
Helper functions: iofunc_read_verify()
Client functions: read(), readdir()
Messages: _IO_READ
Data structure:
struct _io_read { uint16_t type; uint16_t combine_len; int32_t nbytes; uint32_t xtype; }; typedef union { struct _io_read i; } io_read_t;
Description: Responsible for reading data from the resource. The client specifies the number of bytes it's prepared to read in the nbytes input member. You return the data, advance the offset in the OCB, and update the appropriate time fields.
Note that the xtype member may specify a per-read-message override flag. This should be examined. If you don't support any extended override flags, you should return an EINVAL. We'll see the handling of one particularly important (and tricky!) override flag called _IO_XTYPE_OFFSET in the io_read() and io_write() examples below.
Note also that the _IO_READ message arrives not only for regular files, but also for reading the contents of directories. You must ensure that you return an integral number of struct dirent members in the directory case. For more information about returning directory entries, see the example in the "Advanced topics" section under "Returning directory entries."
The helper function iofunc_read_verify() should be called to ascertain that the file was opened in a mode compatible with reading. Also, the iofunc_sync_verify() function should be called to verify if the data needs to be synchronized to the medium. (For a read(), that means that the data returned is guaranteed to be on-media.)
Returns: The number of bytes read, or the status, via the helper macro _IO_SET_READ_NBYTES, and the data itself via message reply.
For an example of returning just data, take a look at "A simple io_read() example" below. For a more complicated example of returning both data and directory entries, look in the "Advanced topics" section under "Returning directory entries."