plexrec(4)

plexrec - structure defining a plex record

Synopsis

#include <sys/types.h>
#include <sys/vol.h>

#define Name_LEN       14
#define COMMENT_LEN    40
#define UTIL_NUM       3
#define UTIL_LEN       14
#define Name_SZ        (Name_LEN + 1)
#define COMMENT_SZ     (COMMENT_LEN + 1)
#define UTIL_SZ        (UTIL_LEN + 1)

struct volseqno { ulong_t seqno_lo, seqno_hi; };
typedef struct volseqno volseqno_t;
typedef struct volseqno volrid_t;

struct plexrec {
        struct pl_tmp  pl_tmp;       /* non-persistent fields */
        struct pl_perm pl_perm;      /* persistent fields */
};

Fields for the pl_perm structure:

	char        pl_name[Name_SZ];           /*record name */
	char        pl_comment[COMMENT_SZ];     /*comment field */
	char        pl_putil[UTIL_NUM][UTIL_SZ] /*persistent util fields */
	char        pl_v_name[Name_SZ];         /*volume name */
	char        pl_state[STATE_SZ];         /*utility state of plex */
	enum plex_layout pl_layout;             /*layout of subdisks */
	ulong_t     pl_pflag;                   /*persistent plex flags */
	long        pl_sd_num;                  /*number of associated sds */
	volseqno_t  pl_update_tid;              /* trans id of last update */
	voff_t      pl_st_width;                /* stripe width if PL_STRIPE */
	char        pl_log_sd[Name_SZ];         /* name of log subdisk */
	volrid_t    pl_rid;                     /* unique identifier */
	volrid_t    pl_vol_rid;                 /* record ID for volume */
	volseqno_t  pl_detach_tid;              /* trans id of kernel detach */
	volrid_t    pl_log_sd_rid;              /* record ID of log subdisk */

Fields for the pl_tmp structure:

char pl_tutil[UTIL_NUM][UTIL_SZ] /* non-persistent util fields */ long pl_lock; /* 1 if record locked */ long pl_compact; /* 1 if plex has no holes */ ulong_t pl_tflag; /* non-persistent plex flags */ enum plex_kstate pl_kstate; /* relation to volume */ minor_t pl_minor; /* minor number of plex dev */ long pl_lasterr; /* last plex error or 0 */ voff_t pl_len; /* byte length of plex */ voff_t pl_contig_len; /* contiguous len from start */ dev_t pl_dev; /* plex device number */

Description

A plexrec structure is the structure used to communicate plex record information between the volume configuration daemon, vold, and programs using the Volume Manager library to query for configurations and to make configuration changes.

The two structures contained in the plexrec structure differentiate elements of the plex record that are persistent and that are non-persistent. The division of fields between pl_tmp and pl_perm structures is somewhat historical, however the pl_perm structure contains information that is stored persistently (i.e., fields that are recovered unchanged after a system reboot), or is directly derivable from persistent plex record information. The pl_tmp field, on the other hand, contains fields that can be modified without the changes being stored persistently.

The uses of the various plex fields are defined as follows:

pl_name

The plex name. This field cannot be changed directly, although it can be changed by calling vxvm_rename.

v_rid

This is a 64-bit record ID assigned to the plex record, which is unique within the disk group for the duration of existence for the disk group. This does not change as a result of a vxvm_rename, even if the record name changes.

pl_comment

A null-terminated comment string associated with the record. The contents are arbitrary except that they cannot contain a new line.

pl_putil

An array of three null-terminated strings that can be used as scratch pads by utilities. These fields are preserved across reboots. By convention, the first field is reserved for usage types; the second field for higher-level applications, such as the VERITAS Visual Administrator; and the third field for local site administrators.

pl_v_name

The name of the associated volume. This field is empty if the plex is not associated. This is a read- only field.

pl_state

A null-terminated state field that is reserved specifically for use by usage types.

pl_layout

The method that is used to map blocks in the plex address space onto blocks in associated subdisks. Possible plex layouts are as follows:

PL_CONCAT: Subdisks are simply mapped into the plex address space based on their association offset; i.e., the subdisks are (more-or-less) concatenated.
PL_STRIPE: Alternating sets of blocks in the associated subdisks are mapped to blocks in the plex address space. The alternation between subdisks occurs at intervals defined by pl_st_width. This is known as striping.; The plex layout cannot be changed when the plex is associated.

pl_pflag

Flags associated with the plex that are preserved across reboots. The persistent flags are:

PL_PFLAG_NOERROR: If set, this plex will not participate in volume error policies.
PL_PFLAG_STALE: If set, a disk replacement or a temporary disk failure caused the plex contents to become out-of-date, requiring recovery of the plex from any other available source (hopefully another plex). This flag remains set until cleared by plex_change.
PL_PFLAG_KDETACH: If set, then the kernel detached the plex as a result of an I/O failure. This flag remains set until cleared by plex_change.

pl_sd_num

The number of subdisks associated with the plex.

v_update_tid

The transaction ID of the last update to this record. This field is assigned when changes to a disk group are committed.

pl_st_width

The length of a single subdisk stripe, for use when the value for pl_layout is PL_STRIPE. This value is in sectors.

pl_log_sd

The name of a subdisk that was associated with the subdisk using the the sd_as_log function. This subdisk is used as a region for logging changes in the volume contents. See the V_PFLAG_LOGTYPE mask in volrec(4) for more information. If no log subdisk is associated with the plex, then this field is empty. This is a read-only field.

pl_vol_rid

The record ID of the associated volume, or zero if the plex is not associated with a volume. This is a read-only field.

pl_detach_tid

The committed configuration transaction ID in effect at the time of a plex detach. This is a read- only field.

lp_log_sd_rid

The record ID of the associated log subdisk, or zero if the plex does not have an associated log subdisk. This is a read-only field.

pl_tutil

An array of three null-terminated strings that can be used as scratch pads by utilities. These fields are cleared on reboot. By convention, the first field is reserved for usage types; the second field for higher-level applications, such as the VERITAS Visual Administrator; and the third field for local site administrators.

pl_lock

A boolean value that is 1 if the plex is locked in the caller's current transaction, and 0 otherwise. This is a read-only field.

pl_compact

A boolean value that is 1 if the plex is compact, and 0 otherwise. A plex is compact if there are no gaps between subdisks associated with the plex, and if the first associated subdisk has an association offset of 0. A plex with no associated subdisks is compact.

pl_tflag

A bitmask of flags that is cleared after a reboot. Flags defined in this field are:

VK_OPEN: The plex device that corresponds to the plex record is open. This flag is maintained by the kernel.
PL_TFLAG_READ: If this flag is set, then read operations may be directed to the plex.
PL_TFLAG_WRITE: If this flag is set, then write operations may be directed to the plex. It is invalid for both the read and write flags to be cleared.
PL_TFLAG_VOLATILE: At least one of the subdisks associated with the plex has its SD_PFLAG_VOLATILE flag set.
PL_TFLAG_LOG: This flag can be set by a utility to indicate that a log subdisk associated with the plex should be considered enabled. This flag is ignored if its use is inappropriate, such as when the plex is not enabled or does not have an associated log subdisk.
PL_TFLAG_COMPLETE: A usage-type utility can set this flag to indicate that this plex is considered to be complete. This flag is used by some volume exception policies. See volrec(4) for more information. This flag is normally set if a usage-type utility considers that the plex contains a complete image of the volume contents. Existence of log subdisks may or may not be taken into account.
PL_TFLAG_VOLATILE: This flag is set by the kernel or vold to indicate that one of the subdisks associated with the plex has the SD_TFLAG_VOLATILE flag set. This is a read-only flag and attempts to set it are ignored.
PL_TFLAG_REMOVED: This flag is set if one of the subdisks associated with the plex is defined on a disk that is in the removed state.
PL_TFLAG_NODAREC: This flag is set if one of the subdisks associated with the plex is defined on a disk that is in the NODAREC state.

pl_kstate

The accessibility of the plex. This can have one of the following values:

PL_ENABLED: Reads of the associated volume may be satisfied by the plex, and writes to the volume will be copied to the plex, within the bounds of the read and write flags in pl_tflag. Any volume ioctl can also be directed toward the plex, and the associated plex device can be used.
PL_DETACHED: Only volume ioctls that specifically name this plex will be directed to the plex, and the associated plex device can be used. However, regular volume I/O will not be directed to the plex.
PL_DISABLED: The plex cannot be used for any operations.

This field can be PL_ENABLED only if the plex is associated. Also, if the associated volume is disabled, then the plex is also effectively disabled. This is set to PL_DISABLED after a reboot.

pl_minor

The minor number of the associated plex device. This is assigned when a plex is associated and is set to NODEV for dissociated plexes. This is a read-only field.

pl_lasterr

A sequence number for the last I/O error to be encountered on the plex. This is a read-only field.

pl_len

The length of the plex. This is a read-only field that is calculated automatically by adding together the subdisk length and association offset of the associated subdisk with the highest association offset. The length is zero if the plex has no associated subdisks. This value is in sectors.

pl_contig_len

The offset from the beginning of the plex to the first block that does not have a backing subdisk. For plexes that have the pl_compact field set to zero, this will be less than the plex length; otherwise, it will equal the plex length. This field can be compared to the length of the associated volume to determine whether the plex is sparse relative to the volume. This value is in sectors.

pl_dev

The device number of the plex device node, which is a character device.

References

vxintro(1M), sdrec(4), volmake(4)