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_ message received by the resource manager:

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

struct _io_devctl_reply {
    uint32_t                    zero;
    int32_t                     ret_val;
    int32_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

See also:

fcntl(), iofunc_attr_t, iofunc_devctl_default(), iofunc_ocb_t, resmgr_context_t

Writing a Resource Manager

Resource Managers chapter of Getting Started with QNX Neutrino