iofunc_devctl_verify()

Perform validation that's common to all handlers for _IO_DEVCTL messages

Synopsis:

#include <sys/iofunc.h>

int iofunc_devctl_verify( const resmgr_context_t *const ctp,
                          const io_devctl_t      *const msg,
                          const iofunc_ocb_t     *const ocb,
                          const unsigned          requested_checks );

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. For more information, see the documentation for iofunc_devctl().

ocb

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

requested_checks

Bits that specify which checks to perform; the flags are defined in iomsg.h and include the following:

_IO_DEVCTL_VERIFY_ACC_IEXEC — requires user-level exec permission. For more information, see the description of iofunc_check_access().
_IO_DEVCTL_VERIFY_ACC_IREAD — requires user-level read permission.
_IO_DEVCTL_VERIFY_ACC_ISGID — the message sender must have group permission to the device.
_IO_DEVCTL_VERIFY_ACC_ISUID — the message sender must be owner of the device.
_IO_DEVCTL_VERIFY_ACC_IWRITE — requires user-level write permission.
_IO_DEVCTL_VERIFY_DIR — Ensure that the direction (read/write) of the IOCTL command matches the open mode flags in the OCB. Commands using __DIOF require read access, __DIOT requires write access, __DIOTF requires read and write access. Commands that use __DION don't require read or write access.
_IO_DEVCTL_VERIFY_LEN — ensure that the size encoded in the IOCTL command matches what's encoded in the message.
_IO_DEVCTL_VERIFY_MSG_LEN — check that the incoming message has enough space to hold the size of the data as indicated in the devctl() encoding.
_IO_DEVCTL_VERIFY_OCB_READ — explicitly check that the OCB was opened with read access.
_IO_DEVCTL_VERIFY_OCB_WRITE — explicitly check that the OCB was opened with write access.
_IO_DEVCTL_VERIFY_PRIV — ensure that the caller has root access.

Library:

libc

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

Description:

The iofunc_devctl_verify() function performs validation that's common to all resource manager devctl() handlers. Generally it's meant to be used to test the security and validity of incoming devctl() messages from a client, or the privileges of the client such as ensuring the client is root, the resource owner, and so on.

Note:

We recommend that you not use this function. Instead, you should write your own code that checks permissions based on each devctl() command that your resource manager supports. For more information, see “Device control I/O function handler” in the “Resource Managers” chapter of Getting Started with QNX Neutrino.
The default handler doesn't call this function.
This function returns on the first error that it finds. The order in which errors are checked is subject to change.

The most common use is ensuring that the client sending the message has actually opened the resource for read and/or write. This is usually done using the _IO_DEVCTL_VERIFY_DIR flag, which reads the direction of the devctl() command and ensures that there are matching ocb->oflags.

Another important flag is _IO_DEVCTL_VERIFY_MSG_LEN, which checks that the incoming message has enough space to hold the size of the data as indicated in the devctl() encoding.

Returns:

EOK on success, or an error code on failure (see the entry for errno). This function doesn't set errno.

Examples:

Check the direction of a command:

if (EOK != (status = iofunc_devctl_verify(ctp, msg, ocb, _IO_DEVCTL_VERIFY_DIR))
{
    return status;
}

Classification:

QNX Neutrino

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