volevent(7) — Special Files
NAME
volevent − Log of Logical Storage Manager events
DESCRIPTION
The volevent device implements a circular buffer containing the most recent events that occurred to the Logical Storage Manager. There are three classes of events that can be traced; volume reconfiguration events, volume I/O errors, and volume I/O activity. The tracing of errors and I/O activity can be enabled or disabled on a per-volume basis. The tracing of reconfiguration events can only be set for the entire system. By default, the tracing is enabled for reconfiguration and error events on all volumes. When a new volume is added to the configuration, it automatically inherits the tracing events that have been enabled for all volumes through the common system-wide trace mask.
IOCTLS
The ioctl commands supported by the volevent device are discussed later in this section. The format for calling each ioctl command is
#include <sys/types.h>
#include <sys/vol.h>
#include <sys/voltrace.h> struct tag arg; int ioctl (int fd, int cmd, struct tag arg);
The value of cmd is the ioctl command code, and arg is usually a pointer to a structure containing the arguments that need to be passed to the kernel.
The return value for all these ioctls is 0 if the command was successful, and −1 if it was rejected. If the return value is −1, then errno is set to indicate the cause of the error.
The following ioctl commands are supported:
GET_VOLINFO
This command accepts a pointer to a volinfo structure as an argument. It fills in the volinfo structure with the corresponding values from the kernel. The members of the volinfo structure are:
long version; /∗ 0x00 kernel version number ∗/
long voldinfo_sz; /∗ 0x04 size of voldinfo area ∗/
major_t volbmajor; /∗ 0x08 volume blk dev major number ∗/
major_t volcmajor; /∗ 0x0c volume char dev major number ∗/
major_t plexmajor; /∗ 0x10 plex device major number ∗/
long maxvol; /∗ 0x14 max # of volumes supported ∗/
long maxplex; /∗ 0x18 max # of associated plexes ∗/
long plexnum; /∗ 0x1c max plexes per volume ∗/
long sdnum; /∗ 0x20 max subdisks per plex ∗/
long max_ioctl; /∗ 0x24 max size of ioctl data ∗/
long max_specio; /∗ 0x28 max size of ioctl I/O op ∗/
long max_io; /∗ 0x2c max size of I/O operation ∗/
long max_ilocksleep; /∗ 0x30 max sleeps on ilock ∗/
long dflt_iodelay; /∗ 0x34 default I/O delay for utils ∗/
long max_freebuf; /∗ 0x38 max number of volbufs to keep ∗/
long max_freevcb; /∗ 0x3c max number of volcbs to keep ∗/
long max_parallelio; /∗ 0x40 max # voldios allowed ∗/
GET_DAEMON
This ioctl returns the pid of the process with the volconfig device open, or 0 if the volconfig device is closed. The value of arg is undefined and should be NULL.
VOL_TRACE_SET
This command accepts a pointer to a vol_tr structure as an argument. The vol_tr structure contains a list of volume names and the trace mask to set for each volume name. If the volume name is a null string, then the action is applied to the system default mask. The vt_action associated with each volume name determines the action to be taken. An action value of VT_SET causes the volume trace mask to be set to the vt_mask specified, and the volume is controlled by its own trace mask. An action value of VT_CLR causes the volume trace mask to be cleared, and the volume is controlled by the default trace mask for all volumes.
The vol_tr structure is defined in the voltrace.h file.
VOL_TRACE_GET
This ioctl accepts an argument to a vol_tr structure as an argument and fills in the vt_mask values associated with each volume in the name list. If a vt_name is the null string, then the system default mask is placed in the vt_mask field.
VOL_EVENT_NUM
This ioctl returns the number of the most recent event in the volevent buffer. It needs no argument, so the arg pointer is undefined and should be a NULL pointer.
VOL_GET_EVENT
This ioctl accepts a pointer to a vol_eb structure as an argument, and copies up to nvolev volevent structures into volev. The return value indicates the number of events copied. Events are read starting at evnum and proceeding until the most recent event has been read. If evnum is less than the lowest numbered event in the buffer, the ioctl returns immediately with the lowest numbered event. If evnum is greater than the largest numbered event in the buffer, then the calling process sleeps. When a new event is put in the buffer, then the process wakes up and returns up to nvolev new events.
The members of the vol_eb structure are:
struct volevent ∗volev; /∗ ptr to array of events ∗/
int nvolev; /∗ count of elements in volev ∗/
int evnum; /∗ event number to start reading from ∗/
ERRORS
The errors returned by the volevent device are:
EAGAINA needed kernel resource was unavailable.
EFAULTA pointer passed to the kernel was invalid, causing a bad memory reference.
ENOENTA volume named in a VOL_TRACE_SET or VOL_TRACE_GET ioctl does not exist in the configuration.
EINVALInvalid data was passed to the kernel. In a VOL_TRACE_SET ioctl, invalid bits are being set. In VOL_TRACE_SET or VOL_TRACE_GET an invalid number of objects was specified. In VOL_GET_EVENT an invalid number of events or a negative event number was requested.
EINTRIn VOL_TRACE_GET, an interrupt was received while waiting for an event.
FILES
/dev/volevent