[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

lvm_varyonvg Subroutine

Purpose

Varies a volume group on-line.

Library

Logical Volume Manager Library (liblvm.a)

Syntax

#include <lvm.h>
int lvm_varyonvg (VaryOnVG)
struct varyonvg *VaryOnVG;

Description

Note: You must have root user authority to use this subroutine.

The lvm_varyonvg subroutine varies on the specified volume group. The lvm_varyonvg subroutine contacts the physical volumes in the volume group and recovers the volume group descriptor area if necessary.

The varyonvg structure pointed to by the VaryOnVG parameter is found in the lvm.h file and is defined as follows:

struct varyonvg
        {
          mid_t kmid; 
          char *vgname;
          long vg_major;
          struct unique_id vg_id;
          long noopen_lvs;
          long reserved;
          long auto_resync;
          long misspv_von;
          long missname_von;
          short int override;
          struct {
                   long num_pvs;
                   struct {
                           struct unique_id pv_id;
                            char *pvname;
                          } pv [LVM_MAXPVS];
                 } vvg_in;
          struct {
                   long num_pvs;
                   struct {
                          struct unique_id pv_id;
                           char *pvname;
                          long pv_status;
                        } pv [2 * LVM_MAXPVS];
                 } vvg_out;
          };
Field Description
kmid Specifies the module ID that identifies the entry point of the logical volume device driver module.
vgname Specifies the character special file name, which is either the full path name or a file name that resides in the /dev directory (for example rvg13) of the volume group device. This device is actually a logical volume with a minor number reserved for use by the Logical Volume Manager (LVM).
vg_major Specifies the major number of the volume group to be varied on.
noopen_lvs Contains either a True or False value. If this field is False, the lvm_varyonvg subroutine builds and sends data structures describing all logical volumes in the volume group to the logical volume device driver. This enables those logical volumes to be opened and accessed. If the noopen_lvs flag is True, then queries to the volume group and other system management functions can be performed, but opens to the logical volumes in the volume group are not allowed. Resynchronization and migrate commands cannot be used because they require the presence of the logical volumes.
auto_resync Contains either a True or False value. If this field is False, then resynchronization of physical and logical volumes containing stale partitions will not be performed and should be initiated by the caller at some other time. The LVM subroutines lvm_resyncpv and lvm_resynclv are provided to perform resynchronization of physical and logical volumes, respectively. The recommended value for the auto_resync field is True.
pvname Contains the character special file name, which is either the full path name or a single file name that resides in the /dev directory (for example, rhdisk0) of the physical volume being installed in the new volume group.

The vvg_in structure contains input from the caller to the lvm_varyonvg subroutine which describes the physical volumes in the volume group. The num_pvs field is the number of entries in the pv array of structures. Each entry in the pv array contains the ID (pv_id) and name (pvname) of a physical volume in the volume group. Unless the volume group is already varied on, this array should contain an entry for each physical volume in the volume group.

The vvg_out structure contains output from the lvm_varyonvg subroutine to the user. This subroutine describes the status of the physical volumes in the caller's input list and any additional physical volumes in the volume group, but not included in the input list. The num_pvs field is the number of entries in the pv array of structures. Each entry in the pv array contains the ID (pv_id), the name (pvname), and the status (pv_status) of a physical volume contained in the input list or the volume group.

The pv_status field contains one of the following values for each physical volume in the vvg_out structure if either the volume group is varied on successfully or an LVM_MISSPVNAME or LVM_MISSINGPV error is returned:

LVM_PVACTIVE This physical volume is currently an active member of the volume group.
LVM_PVMISSING This physical volume is currently unavailable and missing from the volume group.
LVM_PVREMOVED This physical volume has been temporarily removed from the volume group by user request or by virtue of its being missing at the time of a forced vary-on.
LVM_INVPVID This physical volume is not a member of the specified volume group.
LVM_NONAME This physical volume is a member of the volume group, but its name was not passed in the input list.
LVM_DUPPVID A physical volume with the same pv_id field value as this physical volume has already appeared earlier in the input list.
LVM_LVMRECNMTCH This physical volume needs to be deleted from the volume group because it has invalid or non matching data in its LVM record. This may mean that the physical volume has been installed into another volume group.
LVM_NAMIDNMTCH The pv_id for this physical volume was passed in the input list, but it does not match the pv_id of the specified physical volume device name.

For physical volumes in the input list that are found to be members of the specified volume group, the pv_status field contains the physical volume state of either LVM_PVACTIVE, LVM_PVMISSING, or LVM_PVREMOVED. If a physical volume with the same pv_id has appeared previously in the input list, the pv_status field contains LVM_DUPPVID. For physical volumes in the list which are not members of the volume group, the pv_status field will be LVM_INVPVID.

In some cases, a physical volume that is a member of the volume group might have a pv_status field value of LVM_LVMRECNMTCH. This means that the LVM record on the physical volume has either invalid or nonmatching data and that the physical volume cannot be brought on line. If this happens, it is most likely because the physical volume has been installed into another volume group without first deleting it from this one. The user should now delete this physical volume from this volume group, since it can no longer be accessed as a member of this volume group.

For physical volumes that are members of the volume group but were not in the input list, the pv_status field value will be LVM_NONAME or LVM_NAMIDNMTCH. In this case the pv_id field contains the ID of the physical volume, and the pvname field contains a null pointer. An error code of LVM_MISSPVNAME is returned to the caller unless the subroutine was called with a value of TRUE for the missname_von field.

The pv_status field for each physical volume in the vvg_out structure contains one of the following values if either the LVM_NOQUORUM or LVM_NOVGDAS error is returned.

LVM_PVNOTFND Either the physical volume device could not be opened or necessary information in the IPL or LVM record could not be read.
LVM_PVNOTINVG The LVM record for this physical volume indicates that it is not a member of the specified volume group.
LVM_PVINVG The LVM record for this physical volume indicates that it is a member of the specified volume group.

It is recommended that the missname_von field contain a value of FALSE for the first call to the lvm_varyonvg subroutine since a value of TRUE means that any physical volume for which a name was not passed in the input list is given a state of LVM_PVMISSING. Users of the volume group cannot have access to that physical volume until a subsequent call is made to the lvm_varyonvg subroutine for that volume group.

If the misspv_von field is TRUE, the volume group is varied on (provided a quorum exists) even if some of the physical volumes in the volume group have a state of LVM_PVMISSING. If the flag is FALSE, the volume group is varied on only if all physical volumes in the volume group that do not have a state of LVM_PVREMOVED are in the active state (LVM_PVACTIVE). The value recommended for this flag is TRUE. For any physical volume with a state of LVM_PVMISSING or LVM_PVREMOVED when the volume group is varied on, access to that physical volume is not available through LVM. If the state of a physical volume is changed from LVM_PVREMOVED to LVM_PVACTIVE through a call to the lvm_changepv subroutine, then that physical volume is available to LVM, provided that it is not missing at the time.

If the override field is TRUE, an attempt is made to vary on the volume group even if access to a quorum (or majority) of volume group descriptor area copies or a quorum of the volume group status area copies cannot be obtained. Provided that there is at least one valid copy of the descriptor area and at least one valid copy of the status area, the vary-on of the volume group will proceed with the latest available copies of the volume group descriptor area and status area.

If the volume group is forcefully varied on by overriding the absence of a quorum, the PV state of all missing physical volumes is changed to LVM_PVREMOVED. When a physical volume's state is changed to LVM_PVREMOVED, any copies of the volume group descriptor area and status area that it contains are removed. The physical volume no longer takes part in quorum checking until it is returned to the volume group. Also, the physical volume cannot become an active member of the volume group until it is returned. See the lvm_changepv subroutine for more information about removing and returning physical volumes.

The recommended value for the override field is FALSE. If the user chooses to override the LVM_NOQUORUM error and artificially force a quorum, LVM does not guarantee the data integrity of the data contained in the chosen copies of the volume group descriptor area and status area. For more information about quorums and quorum checking, see the "Logical Volume Storage Overview" in AIX Version 4.3 System Management Concepts: Operating System and Devices.

If a physical volume's state is LVM_PVMISSING when the volume group is varied on, then access to that physical volume can be made available to the LVM only by again calling the lvm_varyonvg subroutine for that volume group. When the lvm_varyonvg subroutine is called for a volume group that is already varied on, a check is made for any physical volumes in the volume group with a state of LVM_PVMISSING, and an attempt will be made to open those physical volumes. Any previously missing physical volumes that are successfully opened are defined to the logical volume device driver, and access to those physical volumes will again be available through the LVM.

When the lvm_varyonvg subroutine is called for an already varied-on volume group for the purpose of changing previously missing physical volumes back to the active state, the caller does not need to pass an entire list of physical volumes in the vvg_in structure. The caller needs to pass only information for missing physical volumes that the caller is attempting to return to the LVM_PVACTIVE state.

Parameters

VaryOnVG Points to the varyonvg structure.

Return Values

Upon successful completion, the subroutine returns one or more of the following return codes:

LVM_SUCCESS The volume group was successfully varied on.
LVM_CHKVVGOUT The volume group was varied on successfully, but there is information in the vvg_out structure that should be checked.

Error Codes

If the lvm_varyonvg subroutine does not complete successfully, it returns one of the following error codes:

LVM_ALLOCERR A memory allocation error has occurred.
LVM_INVALID_PARAM A field in the varyongvg structure is invalid or the pointer structure is invalid.
LVM_INVCONFIG An error occurred while attempting to configure this volume group into the kernel.
LVM_INV_DEVENT The device entry for a specified device is not valid and cannot be checked to determine if it is raw.
LVM_MAPFOPN The mapped file, which contains a copy of the volume group descriptor area used for making changes to the volume group, could not be opened.
LVM_MAPFRDWR An error occurred while trying to read or write the mapped file.
LVM_MISSINGPV The volume group was not varied on because one of the physical volumes in the volume group has a state of LVM_PVMISSING. This error will be returned only if the misspv_von field has a value of FALSE; otherwise, the volume group is varied on if a quorum is obtained.
LVM_MISSPVNAME The volume group was not varied on because the volume group contains a physical volume ID for which no name was passed. The vvg_out structure contains the pv_id field, a null pointer for the pvname field, and a pv_status field value of LVM_NONAME for any physical volume in the volume group for which a name was not passed in the vvg_in structure. This error is returned only if the missname_von field has a value of FALSE. Otherwise, the volume group is varied on if a quorum is obtained.
LVM_NOQUORUM The volume group could not be varied on because access to a quorum, or majority, of all volume group descriptor areas or access to a quorum of all volume group status areas could not be obtained.
LVM_NOTCHARDEV The device specified is not a raw or character device.
LVM_NOVGDAS The volume group could not be varied on because access to a valid copy of the volume group descriptor area could not be obtained or access to a valid copy of the volume group status area could not be obtained.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The lvm_changepv subroutine, lvm_varyoffvg subroutine.

Logical Volume Storage Overview in AIX Version 4.3 System Management Concepts: Operating System and Devices.

List of Logical Volume Subroutines and Logical Volume Programming Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]