Read I/O function handler

Prototype:

int (*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, _IO_READ64

Data structure:

struct _io_read {
    uint16_t            type;
    uint16_t            combine_len;
    uint32_t            nbytes;
    uint32_t            xtype;
    uint32_t            zero;
};

struct _io_read64 {
    uint16_t            type;
    uint16_t            combine_len;
    uint32_t            nbytes;
    uint32_t            xtype;
    uint32_t            nbytes_hi;
};

typedef union {
    struct _io_read     i;
    struct _io_read     i64;
    /* unsigned char    data[nbytes];    */
    /* nbytes is returned with MsgReply  */
} 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 the following:

You should call the helper function iofunc_read_verify() to ascertain that the file was opened in a mode compatible with reading. You should also call the iofunc_sync_verify() function 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 read I/O function handler example” below. For a more complicated example of returning both data and directory entries, look in the “Advanced topics” section under Returning directory entries.

Referenced by:

resmgr_io_funcs_t I/O table

Permission checking:

The default implementation iofunc_read_default() calls iofunc_read_verify() and then doesn't return any data. Because it is possible to open a file without read or write permissions, you must validate that the OCB was opened for read in each call. The iofunc_read_verify() function does this by default. In addition, the resource manager should validate the extended type (xtype; see “If you aren't expecting extended types (xtype)” in Writing a Resource Manager).