lvm_querylv Subroutine

Purpose

Queries a logical volume and returns all pertinent information.

Library

Logical Volume Manager Library (liblvm.a)

Syntax

#include <lvm.h>

int lvm_querylv ( LV_ID, QueryLV, PVName) struct lv_id *LV_ID; struct querylv **QueryLV; char *PVName;

Description

Note: The lvm_querylv subroutine uses the sysconfig system call, which requires root user authority, to query and update kernel data structures describing a volume group. You must have root user authority to use the lvm_querylv subroutine.

The lvm_querylv subroutine returns information for the logical volume specified by the LV_ID parameter.

The querylv structure, found in the lvm.h file, is defined as follows:

struct querylv {
      char lvname[LVM_NAMESIZ];  
      struct unique_id vg_id;  
      long maxsize;
      long mirror_policy;
      long lv_state;
      long currentsize;
      long ppsize;
      long permissions;
      long bb_relocation;
      long write_verify;
      long mirwrt_consist;
      long open_close;
      struct pp *mirrors[LVM_NUMCOPIES];
      unsigned int     stripe_exp;
      unsigned int     striping_width;
}
struct pp { 
      struct unique_id pv_id;  
      long lp_num;
      long pp_num;
      long ppstate;
 }

Field	Description
lvname	Specifies the special file name of the logical volume and can be either the full path name or a single file name that must reside in the /dev directory (for example, rhd1). All name fields must be null-terminated strings of from 1 to LVM_NAMESIZ bytes, including the null byte. If a raw or character device is not specified for the lvname field, the Logical Volume Manager (LVM) will add an r to the file name to have a raw device name. If there is no raw device entry for this name, the LVM will return the LVM_NOTCHARDEV error code.
vg_id	Specifies the unique ID of the volume group that contains the logical volume.
maxsize	Indicates the maximum size in logical partitions for the logical volume and must be in the range of 1 to LVM_MAXLPS.
mirror_policy	Specifies how the physical copies are written. The mirror_policy field should be either LVM_SEQUENTIAL or LVM_PARALLEL to indicate how the physical copies of a logical partition are to be written when there is more than one copy.
lv_state	Specifies the current state of the logical volume and can have any of the following bit-specific values ORed together: LVM_LVDEFINED The logical volume is defined. LVM_LVSTALE The logical volume contains stale partitions.
currentsize	Indicates the current size in logical partitions of the logical volume. The size, in bytes, of every physical partition is 2 to the power of the ppsize field.
ppsize	Specifies the size of the physical partitions of all physical volumes in the volume group.
permissions	Specifies the permission assigned to the logical volume and can be one of the following values: LVM_RDONLY Access to this logical volume is read only. LVM_RDWR Access to this logical volume is read/write.
bb_relocation	Specifies if bad block relocation is desired and is one of the following values: LVM_NORELOC Bad blocks will not be relocated. LVM_RELOC Bad blocks will be relocated.
write_verify	Specifies if write verification for the logical volume is desired and returns one of the following values: LVM_NOVERIFY Write verification is not performed for this logical volume. LVM_VERIFY Write verification is performed on all writes to the logical volume.
mirwrt_consist	Indicates whether mirror-write consistency recovery will be performed for this logical volume. The LVM always ensures data consistency among mirrored copies of a logical volume during normal I/O processing. For every write to a logical volume, the LVM generates a write request for every mirror copy. A problem arises if the system crashes in the middle of processing a mirrored write (before all copies are written). If mirror write consistency recovery is requested for a logical volume, the LVM keeps additional information to allow recovery of these inconsistent mirrors. Mirror write consistency recovery should be performed for most mirrored logical volumes. Logical volumes, such as page space, that do not use the existing data when the volume group is re-varied on do not need this protection. Values for the mirwrt_consist field are: LVM_CONSIST Mirror-write consistency recovery will be done for this logical volume. LVM_NOCONSIST Mirror-write consistency recovery will not be done for this logical volume.
open_close	Specifies if the logical volume is opened or closed. Values for this field are: LVM_QLV_NOTOPEN The logical volume is closed. LVM_QLVOPEN The logical volume is opened by one or more processes.
mirrors	Specifies an array of pointers to partition map lists (physical volume id, logical partition number, physical partition number, and physical partition state for each copy of the logical partitions for the logical volume). The ppstate field can be LVM_PPFREE, LVM_PPALLOC, or LVM_PPSTALE. If a logical partition does not contain any copies, its pv_id, lp_num, and pp_num fields will contain zeros.
stripe_exp	Specifies the log base 2 of the logical volume strip size (the strip size multiplied by the number of disks in an array equals the stripe size). For example, 2^20 is 1048576 (that is, 1 MB). Therefore, if the strip size is 1 MB, the stripe_exp field is 20. If the logical volume is not striped, the stripe_exp field is 0.
stripe_width	Specifies the number of disks that form the striped logical volume. If the logical volume is not striped, the striping_width field is 0.

The PVName parameter enables the user to query from a volume group descriptor area on a specific physical volume instead of from the Logical Volume Manager's (LVM) most recent, in-memory copy of the descriptor area. This method should only be used if the volume group is varied off.

Note: The data returned is not guaranteed to be the most recent or correct, and it can reflect a back-level descriptor area.

The PVName parameter should specify either the full path name of the physical volume that contains the descriptor area to query, or a single file name that must reside in the /dev directory (for example, rhdisk1). This parameter must be a null-terminated string between 1 and LVM_NAMESIZ bytes, including the null byte, and must represent a raw device entry. If a raw or character device is not specified for the PVName parameter, the LVM adds an r to the file name to have a raw device name. If there is no raw device entry for this name, the LVM returns the LVM_NOTCHARDEV error code.

If a PVName parameter is specified, only the minor_num field of the LV_ID parameter need be supplied. The LVM fills in the vg_id field and returns it to the user. If the user wishes to query from the LVM's in-memory copy, the PVName parameter should be set to null. When using this method of query, the volume group must be varied on, or an error is returned.

Note: As long as the PVName parameter is not null, the LVM will attempt a query from a physical volume and not from its in-memory copy of data.

In addition to the PVName parameter, the caller passes the ID of the logical volume to be queried (LV_ID parameter) and the address of a pointer to the querylv structure, specified by the QueryLV parameter. The LVM separately allocates the space needed for the querylv structure and the struct pp arrays, and returns the querylv structure's address in the pointer variable passed in by the user. The user is responsible for freeing the space by first freeing the struct pp pointers in the mirrors array and then freeing the querylv structure.

Attention: To prevent corruption when there are many pp arrays, the caller of lvm_querylv must set QueryLV->mirrors k != NULL.

Parameters

Item	Description
LV_ID	Points to an lv_id structure that specifies the logical volume to query.
QueryLV	Contains the address of a pointer to the querylv structure.
PVName	Names the physical volume from which to use the volume group descriptor for the query. This parameter can also be null.

Return Values

If the lvm_querylv subroutine is successful, it returns a value of 0.

Error Codes

If the lvm_querylv subroutine does not complete successfully, it returns one of the following values:

Item	Description
LVM_ALLOCERR	The subroutine could not allocate enough space for the complete buffer.
LVM_INVALID_MIN_NUM	The minor number of the logical volume is not valid.
LVM_INVALID_PARAM	A parameter passed into the routine is not valid.
LVM_INV_DEVENT	The device entry for the physical volume specified by the Pvname parameter is not valid and cannot be checked to determine if it is raw.
LVM_NOTCHARDEV	The physical volume name given does not represent a raw or character device.
LVM_OFFLINE	The volume group containing the logical volume to query was offline. If the query originates from the varied-on volume group's current volume group descriptor area, one of the following error codes is returned:
LVM_DALVOPN	The volume group reserved logical volume could not be opened.
LVM_MAPFBSY	The volume group is currently locked because system management on the volume group is being done by another process.
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	The mapped file could not be read or written.

If a physical volume name has been passed, requesting that the query originate from a specific physical volume, one of the following error codes is returned:

Item	Description
LVM_BADBBDIR	The bad-block directory could not be read or written.
LVM_LVMRECERR	The LVM record, which contains information about the volume group descriptor area, could not be read.
LVM_NOPVVGDA	There are no volume group descriptor areas on the physical volume specified.
LVM_NOTVGMEM	The physical volume specified is not a member of a volume group.
LVM_PVDAREAD	An error occurred while trying to read the volume group descriptor area from the specified physical volume.
LVM_PVOPNERR	The physical volume device could not be opened.
LVM_VGDA_BB	A bad block was found in the volume group descriptor area located on the physical volume that was specified for the query. Therefore, a query cannot be done from the specified physical volume.