[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
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]
}
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. |
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.
Parameters
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:
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:
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. |
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 ]