plexrec - structure defining a plex record

#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_layoutpl_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*/
enumi     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*/

A plexrec structure communicates plex record information between the volume configuration daemon, vold, and programs using the Veritas Volume Manager (VxVM) 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 (that is, 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:

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_comment	A null-terminated comment string associated with the record. The contents are arbitrary except that they cannot contain a new line.
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_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_detach_tid
	The committed configuration transaction ID in effect at the time of a plex detach. This is a read-only field.
pl_dev	The device number of the plex device node, which is a character device.
pl_kstate	The accessibility of the plex. This can have one of the following values: 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. 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_lasterr	A sequence number for the last I/O error to be encountered on the plex. This is a read-only field.
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; that is, 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_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_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_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_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_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_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. See dm(3X). PL_TFLAG_READ   If this flag is set, then read operations may be directed to the plex. 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. See dm(3X). PL_TFLAG_VOLATILE   At least one of the subdisks associated with the plex has its SD_PFLAG_VOLATILE flag set. 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_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. VK_OPEN   The plex device that corresponds to the plex record is open. This flag is maintained by the kernel.
	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_name	The plex name. This field cannot be changed directly, although it can be changed by calling vxvm_rename.
pl_pflag	Flags associated with the plex that are preserved across reboots. The persistent flags are: 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_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_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 Storage Administrator; and the third field for local site administrators.
pl_sd_num	The number of subdisks associated with the plex.
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_state	A null-terminated state field that is reserved specifically for use by usage types.
pl_tflag	A bitmask of flags that is cleared after a reboot. Flags defined in this field are:
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 Storage 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_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.
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.
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. See vol_commit(3X).

vxintro(1M), vxintro(3X), sd_as_log(3X), dm(3X), da(3X), dg(3X), vxmake(4), sdrec(4)