iofunc_devctl()

Handle an _IO_DEVCTL message

Synopsis:

#include <sys/iofunc.h>

int iofunc_devctl( resmgr_context_t *ctp,
                   io_devctl_t *msg,
                   iofunc_ocb_t *ocb,
                   iofunc_attr_t *attr );

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_devctl_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.
attr: A pointer to the iofunc_attr_t structure that describes the characteristics of the device that's associated with your resource manager.

Library:

libc

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

Description:

The iofunc_devctl() helper function implements the semantics for the client's devctl() call, which is received as an _IO_DEVCTL message by the resource manager. This function handles the DCMD_ALL* functionality.

This function handles at least the following device control messages:

DCMD_ALL_GETFLAGS: Implements the functionality of the fcntl() get-flags command.
DCMD_ALL_SETFLAGS: Implements the functionality of the fcntl() set-flags command.
DCMD_ALL_GETMOUNTFLAGS: Returns the mount flag (mount->flags) for a resource that has a mount structure defined, else returns a mount flag of zero.

The supported mount flags (bitmask values) for DCMD_ALL_GETMOUNTFLAGS include:

_MOUNT_READONLY: Read only.
_MOUNT_NOEXEC: Can't exec from filesystem.
_MOUNT_NOSUID: Don't honor setuid bits on filesystem.

If iofunc_devctl() doesn't recognize the command, it returns _RESMGR_DEFAULT, so that your resource manager can process it. If you don't handle the command, the client library's devctl() returns ENOTTY.

io_devctl_t structure

The io_devctl_t structure holds the _IO_DEVCTL message received by the resource manager:

struct _io_devctl {
    uint16_t                    type;
    uint16_t                    combine_len;
    int32_t                     dcmd;
    uint32_t                    nbytes;
    int32_t                     zero;
/*  char                        data[nbytes]; */
};

struct _io_devctl_reply {
    uint32_t                    zero;
    int32_t                     ret_val;
    uint32_t                    nbytes;
    int32_t                     zero2;
/*  char                        data[nbytes]; */
    } ;

typedef union {
    struct _io_devctl           i;
    struct _io_devctl_reply     o;
} io_devctl_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).

The i member is a structure of type _io_devctl that contains the following members:

type: _IO_DEVCTL.
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.
dcmd: The device-control command to execute.
nbytes: The number of bytes of data being passed with the command.

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

The _DEVCTL_DATA() macro gets a pointer to the data that follows the message. Call it like this:

data = _DEVCTL_DATA (msg->i);

The o member of the io_devctl_t message is a structure of type _io_devctl_reply that contains the following members:

ret_val: The value returned by the command.
nbytes: The number of bytes of data being returned.

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

Returns:

EOK: Successful completion.
EINVAL: An attempt to set the flags for a resource that is synchronized, with no mount structure defined, or no synchronized I/O defined.
_RESMGR_DEFAULT: The command isn't one that this function handles. You might want your resource manager to process it; otherwise the call to devctl() will return ENOTTY.

Classification:

QNX Neutrino

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