iofunc_write_verify()

Verify a client's write access to a resource

Synopsis:

#include <sys/iofunc.h>

int iofunc_write_verify( resmgr_context_t* ctp,
                         io_write_t* msg,
                         iofunc_ocb_t* ocb,
                         int* nonblock );

Arguments:

ctp

A pointer to a resmgr_context_t structure that the resource-manager library uses to pass context information between functions.

msg

A pointer to the io_write_t structure that contains the message that the resource manager received; see below.

ocb

A pointer to the iofunc_ocb_t structure for the Open Control Block that was created when the client opened the resource.

nonblock

NULL, or a pointer to a location where the function can store a value that indicates whether or not the device is nonblocking:

O_NONBLOCK — the client doesn't want to be blocked.
Zero — the client wants to be blocked.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The iofunc_write_verify() function checks that the client that sent the _IO_WRITE or _IO_WRITE64 message actually has write access to the resource, and, optionally (if nonblock isn't NULL), sets nonblock to O_NONBLOCK or 0.

The write permission check is done against ocb->ioflag.

Note that the io_write_t message has an override flag called msg->i.xtype. This flag allows the client to override the default blocking behavior for the resource on a per-request basis. This override flag is checked, and returned in the optional nonblock.

In the write callout for your resource manager, you'll need to indicate how many bytes were written. You can do this with the macro:

_IO_SET_WRITE_NBYTES( resmgr_context_t *ctp,
                      int nbytes )

io_write_t structure

The io_write_t structure holds the _IO_WRITE or _IO_WRITE64 message received by the resource manager:

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;

The I/O message structures are unions of an input message (coming to the resource manager) and an output or reply message (going back to the client). In this case, there's only an input message, i or i64, that contains the following members:

type

_IO_WRITE or _IO_WRITE64. The client library uses the _IO_WRITE64 form only when the length is greater than 4 GB.

combine_len

If the message is a combine message, _IO_COMBINE_FLAG is set in this member. For more information, see Combine Messages chapter of Writing a Resource Manager.

nbytes

The number of bytes that the client wants to write. For an _IO_WRITE64 message, the high 32 bits of the length are in nbytes_hi.

xtype

Extended type information. This information includes a type and optionally some flags. To isolate the type from the flags, AND the xtype member with _IO_XTYPE_MASK:

if ((msg->i.xtype & _IO_XTYPE_MASK) == ...)

The relevant types include the following:

_IO_XTYPE_NONE
_IO_XTYPE_OFFSET

The xtype member doesn't include any useful flags.

For more information, see “Handling other read/write details” in the Handling Read and Write Messages chapter of Writing a Resource Manager.

nbytes_hi

(_IO_WRITE64 only) The high 32 bits of the length.

Note: You can use the _IO_WRITE_GET_NBYTES() macro (defined in <sys/iofunc.h>) to determine the number of bytes. You pass it a pointer to the message:

num_bytes = _IO_WRITE_GET_NBYTES(msg);

The commented-out declaration for data indicates that nbytes bytes of data immediately follow the _io_write structure.

Returns:

EOK: The client has write access to this resource.
EBADF: The client doesn't have write access to this resource.
EBADMSG: The length of the message is invalid.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes