vdmdummy(7) DG/UX R4.11 vdmdummy(7)
NAME
vdmdummy - Virtual Disk Manager Dummy Subdriver
DESCRIPTION
The Dummy Subdriver is used to create empty instances that are used
as place holders for the DG_VDM_INSERT_INSTANCE and
DG_VDM_EXTRACT_INSTANCE commands.
Dummy instances never have any children, cannot be opened, cannot
have I/O done to them, and will return errors for the majority of
other commands (like DG_VDM_LINK_CHILD_INSTANCE, or DSKIOCGET). They
usually have no name. They can be created, deleted, used in insert
and extract commands, and that's all.
Pictorially, a dummy instance looks like this:
+-------------------+
| dummy instance |
+-------------------+
USABILITY
Dummy instances are always usable. Since they have no children and
cannot be opened, nothing can be done with them, however.
CLUSTER DISKS
Dummy instances are not permitted on cluster disks because the
DG_VDM_INSERT_INSTANCE and DG_VDM_EXTRACT_INSTANCE commands are
currently not supported on cluster disks.
PROGRAMMING INTERFACE
The ioctl(2) system call is used for all communication with the Dummy
Subdriver. Use the open(2) system call to open a channel to the
/dev/vdm node, and issue all ioctl(2) commands through that channel.
See vdm(7) for more details on the programming interface.
The <sys/ioctl.h> include file is required for communicating with the
Dummy Subdriver. The <errno.h>, <sys/dg_sysctl.h>, <sys/types.h>,
<stdio.h>, and <unistd.h> include files will be helpful.
SUBDRIVER-SPECIFIC COMMANDS
The Dummy Subdriver has no subdriver-specific commands.
COMMON DISK COMMANDS
Since the Dummy Subdriver cannot do any I/O, it does not support
either the DSKIOCGET or the DSKIOCUSAGE command.
SUBDRIVER-SPECIFIC DEFINES
DG_VDMDUMMY_SUBDRIVER_ID
The unique ID that identifies the Dummy Subdriver.
DG_VDMDUMMY_IOCTL_PACKET_VERSION_0
The version zero stamp used in all Dummy Subdriver ioctl(2) packets.
The stamp indicates which version of the Dummy Subdriver interface is
being used and allows the Dummy Subdriver to support previous
versions without requiring that applications be recompiled.
STRUCTURES
The Dummy Subdriver has no subdriver-specific structures.
EXAMPLES
The following code fragments are illustrate the use of the packets
and commands described in this man page. The fragments are not
complete and are not intended to be compilable or executable. In
particular, initialization code, instance locating code, and error
handling are left out for brevity.
Common includes and variables
#include <errno.h>
#include <sys/dg_sysctl.h>
#include <sys/ioctl.h>
#include <sys/types.h>
#include <stdio.h>
#include <unistd.h>
int status; /* status from system call */
int vdm_channel; /* channel to /dev/vdm node */
Create a dummy instance
dev_t dummy_instance;
struct dg_vdm_create_instance_packet create_pkt;
create_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
create_pkt.subdriver_id = DG_VDMDUMMY_SUBDRIVER_ID;
create_pkt.persistent = 1;
create_pkt.enable_disk_updates = 1;
create_pkt.instance_name [0] = '\0';;
create_pkt.subdriver_attributes_packet_ptr = NULL;
status = ioctl (vdm_channel,
DG_VDM_CREATE_INSTANCE,
&create_pkt);
dummy_instance = create_pkt.device_number;
printf ("Dummy instance device number = 0x%08x\n", dummy_instance);
Insert an instance
dev_t aggr_instance;
dev_t dummy_instance;
dev_t insert_instance;
dev_t piece_instance;
dev_t pieces [1];
struct dg_vdm_create_instance_packet create_pkt;
struct dg_vdm_insert_instance_packet insert_pkt;
struct dg_vdmaggr_create_packet aggr_create_pkt;
/* Create a dummy instance. */
create_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
create_pkt.subdriver_id = DG_VDMDUMMY_SUBDRIVER_ID;
create_pkt.persistent = 1;
create_pkt.enable_disk_updates = 1;
create_pkt.instance_name [0] = '\0';
create_pkt.subdriver_attributes_packet_ptr = NULL;
status = ioctl (vdm_channel,
DG_VDM_CREATE_INSTANCE,
&create_pkt);
dummy_instance = create_pkt.device_number;
/* Insert an aggregation. */
insert_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
insert_pkt.instance_to_change = insert_instance;
insert_pkt.dummy_instance = dummy_instance;
insert_pkt.subdriver_id = DG_VDMAGGR_SUBDRIVER_ID;
insert_pkt.attributes_packet_ptr = &aggr_create_pkt;
aggr_create_pkt.version = DG_VDMAGGR_IOCTL_PACKET_VERSION_0;
aggr_create_pkt.stripe_size = 0;
aggr_create_pkt.number_of_pieces = 1;
aggr_create_pkt.piece_array_ptr = pieces;
pieces [0] = dummy_instance;
status = ioctl (vdm_channel,
DG_VDM_INSERT_INSTANCE,
&insert_pkt);
aggr_instance = insert_instance;
piece_instance = dummy_instance;
Extract an instance
dev_t aggr_instance;
dev_t child_instance;
dev_t dummy_instance;
dev_t extract_instance;
struct dg_vdm_create_instance_packet create_pkt;
struct dg_vdm_delete_instance_packet delete_pkt;
struct dg_vdm_extract_instance_packet extract_pkt;
/* Create a dummy instance. */
create_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
create_pkt.subdriver_id = DG_VDMDUMMY_SUBDRIVER_ID;
create_pkt.persistent = 1;
create_pkt.enable_disk_updates = 1;
create_pkt.instance_name [0] = '\0';
create_pkt.subdriver_attributes_packet_ptr = NULL;
status = ioctl (vdm_channel,
DG_VDM_CREATE_INSTANCE,
&create_pkt);
dummy_instance = create_pkt.device_number;
/* Extract the aggregation. */
extract_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
extract_pkt.parent_device_number = extract_instance;
extract_pkt.new_parent_device_number = dummy_instance;
status = ioctl (vdm_channel,
DG_VDM_EXTRACT_INSTANCE,
&extract_pkt);
aggr_instance = dummy_instance;
dummy_instance = child_instance;
/* Delete the leftover instance and the child dummy instance. */
delete_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
delete_pkt.device_number = aggr_instance;
status = ioctl (vdm_channel,
DG_VDM_DELETE_INSTANCE,
&delete_pkt);
delete_pkt.device_number = dummy_instance;
status = ioctl (vdm_channel,
DG_VDM_DELETE_INSTANCE,
&delete_pkt);
Get the children of a dummy instance
dev_t dummy_instance;
struct dg_vdm_get_child_instance_packet get_child_pkt;
get_child_pkt.version = DG_VDM_IOCTL_PACKET_VERSION_0;
get_child_pkt.key = 0;
get_child_pkt.parent_device_number = dummy_instance;
get_child_pkt.parent_subdriver_id = DG_VDMDUMMY_SUBDRIVER_ID;
get_child_pkt.available = 0;
get_child_pkt.child_instance_array_ptr = NULL;
status = ioctl (vdm_channel,
DG_VDM_GET_CHILD_INSTANCE,
&get_child_pkt);
printf ("Number of children = %d\n",
get_child_pkt.number_of_children);
FILES
/dev/dsk
Directory for the block special device nodes for virtual
disks. These are the buffered access device nodes.
/dev/rdsk
Directory for the character special device nodes for virtual
disks. These are the unbuffered (or raw) access device nodes.
/dev/vdm
Device node for issuing all ioctl(2) commands.
/usr/include/sys/ioctl.h
ioctl(2) definitions.
ACCESS CONTROL
Access control for the standard VDM framework commands is controlled
by the VDM itself. See the vdm(7) man page for a listing of these
controls.
The Dummy Subdriver has no commands of its own, so there is no
subdriver-specific access control done.
On a generic DG/UX system, appropriate privilege is granted by having
an effective UID of 0 (root). See the appropriate_privilege(5) man
page for more information.
On a system with DG/UX information security, appropriate privilege is
granted by having one or more specific capabilities enabled in the
effective capability set of the user. See the cap_defaults(5) man
page for the default capabilities for these commands.
RETURN VALUE
The return value from the ioctl(2) system call used to issue the
command will be one of the following:
0 The command was successful.
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
There are descriptive extended error message strings available for
most of the error codes. They can be retrieved with the
dg_ext_errno(2), extended_strerror(3C), and extended_perror(3C)
routines.
Errno may be set to one of the DG/UX standard error codes. See
/usr/include/sys/errno.h for a listing of those error codes.
Errno may be set to one of the standard error codes provided by the
VDM framework. See vdm(7) for a listing of those error codes.
The Dummy Subdriver has no specific error codes of its own.
SEE ALSO
ioctl(2), dsk(7), rdsk(7), vdm(7).
Licensed material--property of copyright holder(s)