iofunc_devctl()

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 _IO_INPUT_PAYLOAD() macro gets a pointer to the data that follows the message. Call it like this:

data = _IO_INPUT_PAYLOAD(msg);

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.

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

data = _IO_OUTPUT_PAYLOAD(msg);

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 OS