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 POSIX 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.

Any other device control messages return 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.

ENOTTY

An unsupported device control message was decoded.

Classification:

QNX Neutrino

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