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.
- 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:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |