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_PRIV — ensure that the caller has root access.
  • _IO_DEVCTL_VERIFY_LEN — ensure that the size encoded in the IOCTL command matches what's encoded in the message.
  • _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_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_ACC_ISUID — the message sender must be owner of the device.
  • _IO_DEVCTL_VERIFY_ACC_ISGID — the message sender must have group permission to the device.
  • _IO_DEVCTL_VERIFY_ACC_IREAD — requires user-level read permission
  • _IO_DEVCTL_VERIFY_ACC_IWRITE — requires user-level write permission
  • _IO_DEVCTL_VERIFY_ACC_IEXEC — requires user-level exec permission. For more information, see the description of iofunc_check_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:
  • 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 a POSIX 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