[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
lvm_queryvg Subroutine
Purpose
Queries a volume group and returns pertinent information.
Library
Logical Volume Manager Library (liblvm.a)
Syntax
#include <lvm.h>
int lvm_queryvg ( VG_ID, QueryVG, PVName)
struct unique_id *VG_ID;
struct queryvg **QueryVG;
char *PVName;
Description
Note
The lvm_queryvg 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_queryvg
subroutine.
The lvm_queryvg subroutine returns
information on the volume group specified by the VG_ID parameter.
The queryvg structure , found
in the lvm.h file, contains the following fields:
struct queryvg {
long maxlvs;
long ppsize;
long freespace;
long num_lvs;
long num_pvs;
long total_vgdas;
struct lv_array *lvs;
struct pv_array *pvs;
}
struct pv_array {
struct unique_id pv_id;
long pvnum_vgdas;
char state;
char res[3];
}
struct lv_array {
struct lv_id lv_id;
char lvname[LVM_NAMESIZ];
char state;
char res[3];
}
Field |
Description |
maxlvs |
Specifies the maximum number of logical volumes allowed in the volume
group. |
ppsize |
Specifies the size of all physical partitions in the volume group.
The size in bytes of each physical partitions is 2 to the power of the ppsize field. |
freespace |
Contains the number of free physical partitions in this volume group. |
num_lvs |
Indicates the number of logical volumes. |
num_pvs |
Indicates the number of physical volumes. |
total_vgdas |
Specifies the total number of volume group descriptor areas for the
entire volume group. |
lvs |
Points to an array of unique IDs, names, and states of the logical
volumes in the volume group. |
pvs |
Points to an array of unique IDs, states, and the number of volume
group descriptor areas for each of the physical volumes in the volume group. |
The PVName parameter enables
the user to query from a 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. The data returned is not guaranteed to
be 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). The name must represent a raw
device. If a raw or character device is not specified for the PVName parameter, the Logical Volume Manager will add an r to the file name in order to have a raw device name. If there is no
raw device entry for this name, the LVM returns the LVM_NOTCHARDEV error code. This field must be a null-terminated string of from 1 to LVM_NAMESIZ bytes, including the null byte. If a PVName is specified, the LVM will return the VG_ID to the user through the VG_ID pointer passed
in. If the user wishes to query from the LVM 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 will be returned.
Note
As long as the PVName parameter is
not null, the LVM will attempt a query from a physical volume and not its in-memory copy of data.
In addition to the PVName
parameter, the caller passes the unique ID of the volume group to be queried
(VG_ID) and the address of a pointer to a queryvg structure. The LVM will separately allocate enough space for
the queryvg structure, as well as the lv_array and pv_array structures, and return the
address of the completed structure in the QueryVG
parameter passed in by the user. The user is responsible for freeing the space
by freeing the lv and pv pointers and then freeing the QueryVG pointer.
Parameters
VG_ID |
Points to a unique_id structure that specifies
the volume group to be queried. |
QueryVG |
Specifies the address of a pointer to the queryvg structure. |
PVName |
Specifies the name of the physical volume that contains the descriptor
area to query and must be the name of a raw device. |
Return Values
The lvm_queryvgn subroutine
returns a value of 0 upon successful completion.
Error Codes
If the lvm_queryvg subroutine
fails it returns one of the following error codes:
LVM_ALLOCERR |
The subroutine cannot allocate enough space for a complete buffer. |
LVM_FORCEOFF |
The volume group has been forcefully varied off due to a loss of
quorum. |
LVM_INVALID_PARAM |
An invalid parameter was passed into the routine. |
LVM_OFFLINE |
The volume group is offline and should be online. |
If the query originates from the varied-on volume
group's current volume group descriptor area, one of the following error codes
may be returned:
LVM_DALVOPN |
The volume group reserved logical volume could not be opened. |
LVM_INV_DEVENT |
The device entry for the physical volume specified by the PVName parameter is invalid and cannot be checked to determine if it
is raw. |
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 |
Either the mapped file could not be read, or it could not be written. |
LVM_NOTCHARDEV |
A device is not a raw or character device. |
If a physical volume name has been passed, requesting
that the query originate from a specific physical volume, one of the following
error codes may be returned:
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 this physical volume. |
LVM_NOTVGMEM |
The physical volume 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 this physical volume. |
Related Information
List of Logical Volume Subroutines and Logical Volume Programming Overview
in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]