Write I/O function handler

Prototype:

int (*write) ( resmgr_context_t *ctp,
               io_write_t *msg,
               RESMGR_OCB_T *ocb ) 

Classification:

I/O

Default handler:

iofunc_write_default()

Helper functions:

iofunc_write_verify()

Client functions:

write(), fwrite(), etc.

Messages:

_IO_WRITE, _IO_WRITE64

Data structure:

struct _io_write {
    uint16_t            type;
    uint16_t            combine_len;
    uint32_t            nbytes;
    uint32_t            xtype;
    uint32_t            zero;
    /* unsigned char    data[nbytes]; */
};

struct _io_write64 {
    uint16_t            type;
    uint16_t            combine_len;
    uint32_t            nbytes;
    uint32_t            xtype;
    uint32_t            nbytes_hi;
    /* unsigned char    data[nbytes]; */
};

typedef union {
    struct _io_write    i;
    struct _io_write    i64;
    /*  nbytes is returned with MsgReply  */
} io_write_t;

Description:

This message handler is responsible for getting data that the client wrote to the resource manager. It gets passed the number of bytes the client is attempting to write in the nbytes member; the data implicitly follows the input data structure (unless the xtype override is _IO_XTYPE_OFFSET; see “A simple write I/O function handler example” below!) The implementation will need to re-read the data portion of the message from the client, using resmgr_msgreadv() or the equivalent. The return status is the number of bytes actually written or an errno.

Note the following:

• To make sure the handler supports writes that are greater than 4 GB (whether the form is _IO_WRITE or _IO_WRITE64), use the _IO_WRITE_GET_NBYTES() macro (defined in <sys/iofunc.h>).
• You should use the helper function iofunc_write_verify() to ascertain that the file was opened in a mode compatible with writing. You should also call the iofunc_sync_verify() function to verify if the data needs to be synchronized to the medium.

Returns:

The status via the helper macro _IO_SET_WRITE_NBYTES().

For an example, take a look at “A simple write I/O function handler example” below.

Referenced by:

resmgr_io_funcs_t I/O table

Permission checking:

The default implementation iofunc_write_default() calls iofunc_write_verify() and then silently discards all data written. Because it is possible to open a file without read or write permissions, you must validate that the OCB was opened for write in each call. By default, this validation is done using iofunc_write_verify(). In addition, the resource manager should validate the extended type (xtype).