Content-type: text/html Man page of lvm

lvm

Section: Environments, Tables, and Troff Macros (7)
Index Return to Main Contents
 

NAME

lvm - Logical Volume Manager (LVM) programming interface  

SYNOPSIS

#include <lvm/lvm.h>  

DESCRIPTION

The Logical Volume Manager (LVM) is no longer supported on Digital UNIX systems. Features formerly provided by LVM are now provided by the Logical Storage Manager (LSM). Existing LVM volumes must be migrated to LSM, using an encapsulation process. For information about moving LVM volumes to LSM, see the vollvmencap(8) reference page and the manual Logical Storage Manager.

The Logical Volume Manager (LVM) implements virtual disks, called logical volumes, and uses physical disks, called physical volumes, to store the actual data. The programming interface to the LVM is provided through a number of LVM ioctl commands. These commands perform functions like creating logical and physical volumes, removing logical and physical volumes, and so on.

Note that the physical disks on which LVM creates logical volumes are not protected from access by other programs. For example, it is possible to use newfs to create a file system on a device that is currently part of a logical volume.

Basically, there are four groupings of the LVM ioctl commands: those that deal with volume groups, those that deal with logical volumes, those that deal with physical volumes, and those that perform miscellaneous functions. The following table illustrates these groupings:

Volume Group Activate volume group Create volume group Deactivate volume group Query volume group (retrieve information) Set volume group ID

Logical Volume Change logical volume attributes Create logical volume Delete logical volume from volume group Extend logical volume (adds extents) Query logical volume (retrieve information) Query logical volume physical extent map Move physical extents between logical volumes Reduce logical volume (reduce extents) Resynchronize logical volume

Physical Volume Attach physical volume to volume group Change physical volume attributes Delete physical volume from volume group Install physical volume to volume group Query physical volume (retrieve information) Query map of physical extents on physical volume Query physical volume using physical identifier as the pathname Query multiple physical volumes (retrieve information) Remove a physical volume from the volume group Resynchronize physical volume

Miscellaneous Obtain current raw device I/O options, as set by the LVM_OPTIONSET command Set I/O options for the raw logical volume device Initiates resynchronization for physical extents

The following alphabetic listing of the LVM ioctl commands first gives synopses and descriptions of the LVM ioctl commands, then provides descriptions of the command parameters, and finally provides a list of returned errors.

For detailed information on the LVM, see The Design of the OSF/1 Operating System.

int fd; int flags;

This command brings the specified volume group online. This involves reconciliation of the VGDA's on all attached physical volumes, and recovery of active mirrors. Depending on whether the LVM_ALL_PVS_REQUIRED or LVM_NONMISSING_PVS_REQUIRED flags are set in flags, it may fail if some of the physical volumes in the volume group are missing (LVM_ALL_PVS_REQUIRED flag set). int fd; char *path;

This command attaches the specified physical volume to the specified volume group. This operation is analogous to a mount() command: the named device is opened, and the LVM maintains a reference to it. The LVM_ATTACHPV command reads the LVM record to determine the vg_id and the pvnum. This command fails if the volume is a member of another volume group. int fd; struct lv_statuslv {        ushort_t minor_num;
       ushort_t maxlxs;
       ushort_t lv_flags;
       ushort_t sched_strat;
       ushort_t maxmirrors;
} lv_statuslv;

This command changes the attributes of a logical volume in a specified volume group. It updates the specified logical volume's LVM data structures and logical volume entry in the descriptor area.

You can use this command on a logical volume device. In this case, the minor_num is ignored, and the command applies to that device. int fd; struct lv_changepv {        ushort_t pv_key;
       ushort_t pv_flags;
       ushort_t maxdefects;
} lv_changepv;

This command changes the attributes of a physical volume. You can use LVM_CHANGEPV to change the maximum number of defects (maxdefects) that can be relocated on this physical volume. You can also use this command to disallow or re-allow allocation of extents on the physical volume. Allocation from a physical volume should be disallowed if the physical extents of that physical volume are to be migrated to another physical volume.

Note that if you change maxdefects to a number lower than what has already been relocated on the physical volume, LVM_CHANGEPV will reset maxdefects to the relocated number of defects. int fd; struct lv_statuslv {        ushort_t minor_num;
       ushort_t maxlxs;
       ushort_t lv_flags;
       ushort_t sched_strat;
       ushort_t maxmirrors;
} lv_statuslv;

This command creates a logical volume in a specified volume group. It uses the supplied information to update a previously unused entry in the logical volume list. The index into the list of logical volume entries corresponds to the minor number (minor_num) of the logical volume. LVM_CREATELV does not do extent allocation. The LVM_EXTENDLV ioctl must be used to allocate extents for the new logical volume. int fd; struct lv_createvg {        char *path;
       lv_uniqueID_t vg_id;
       ushort_t pv_flags;
       ushort_t maxlvs;
       ushort_t maxpvs;
       ushort_t maxpxs;
       ulong_t pxsize;
       ulong_t pxspace;
       ushort_t maxdefects;
} lv_createvg; struct lv_uniqueID {        ulong_t id1;
       ulong_t id2;
}; typedef struct lv_uniqueID lv_uniqueID_t;

This command creates a volume group and installs the first physical volume. It initializes the in-memory VGDA for the volume group. int fd;

This command takes a specified volume (fd) group offline. All logical volumes in this volume group must be closed. The argument (0) is ignored. int fd; int minor_num; int fd; int pv_key;

This command deletes a physical volume from a specified volume group (fd). The physical volume must not contain any extents of a logical volume for it to be deleted. If the physical volume contains any extents of a logical volume, an error code is returned. In this case, you must delete logical volumes or relocate the extents that reside on this physical volume. For an empty physical volume, LVM_DELETEPV removes the entries for this physical volume from the LVM data structures and from the descriptor area, and initializes the descriptor area on the physical volume being deleted. int fd; struct lv_lvsize {        ushort_t minor_num;
       ulong_t size;
       lxmap_t *extents;
} lv_lvsize; struct lxmap {        ushort_t lx_num;
       ushort_t pv_key;
       ushort_t px_num;
       ushort_t status;
}; typedef struct lxmap lxmap_t;

This command adds extents to a given logical volume. It allocates physical extents for the specified logical volume at the physical volume and physical extent specified as input via the extent list pointer. It updates the LVM data structures and the descriptor area. int fd; struct lv_installpv {        char *path;
       ulong_t pxspace;
       ushort_t pv_flags;
       ushort_t maxdefects;
} lv_installpv;

This command installs a physical volume into a specified volume group. To do this, LVM_INSTALLPV adds the physical volume specification to the in-memory VGDA for the volume group, and then updates all active physical volumes in the volume group. This command fails if the physical volume is already a member of another volume group. int fd; struct lv_option lv_option; ioctl(fd, LVM_OPTIONSET, &lv_option) int fd; struct lv_option {        ushort_t opt_avoid;
       ushort_t opt_options;
} lv_option;

This command sets the I/O options for the raw logical volume device. The raw device is capable of avoiding specified mirrors on read operations, set through the opt_avoid field. This allows a program to access a specific copy of a mirrored logical volume.

The opt_options field allows the program to temporarily (until the device is closed) specify that all writes are to be verified (LVM_VERIFY) or that defect relocation is not to be performed (LVM_NORELOC) To set these options permanently, or for the block device, see LVM_CHANGELV . The raw I/O options are cleared when the raw device is first opened, and never have an effect on block device operations.

The LVM_OPTIONGET command obtains the current raw device I/O options, as set by the LVM_OPTIONSET command. These functions apply only to open devices, are only valid against the logical volume devices, not the control device. int fd; struct lv_querylv {        ushort_t minor_num;
       ulong_t numpxs;
       ushort_t numlxs;
       ushort_t maxlxs;
       ushort_t lv_flags;
       ushort_t sched_strat;
       ushort_t maxmirrors;
} lv_querylv;

This command obtains information about a particular logical volume from the specified volume group. It verifies that the logical volume is valid and returns the information requested for its volume group to the buffer supplied.

You can use this command on a file descriptor corresponding to a logical volume device. In this case, the command ignores the minor_num field. Structure fields are output fields unless marked otherwise. int fd; struct lv_lvsize {        ushort_t minor_num;
       ulong_t size;
       lxmap_t *extents;
} lv_lvsize; struct lxmap {        ushort_t lx_num;
       ushort_t pv_key;
       ushort_t px_num;
       ushort_t status;
}; typedef struct lxmap lxmap_t;

This command obtains information from the specified volume group about the space and extents allocated to a particular logical volume. It verifies that the logical volume is valid and returns the information requested for its volume group to the buffer supplied. The allocation map must be large enough to accommodate the extent map from the logical volume. This information is available from LVM_QUERYLV.

You can use this command on a file descriptor corresponding to a logical volume device. In this case, the minor_num field is ignored. int fd; struct lv_querypv {        ushort_t pv_key;
       ushort_t pv_flags;
       ushort_t px_count;
       ushort_t px_free;
       ulong_t px_space;
       dev_t pv_rdev;
       ushort_t maxdefects;
       ushort_t bbpool_len;
} lv_querypv;

This command retrieves information about a specified physical volume. It verifies that the physical volume is valid and writes the requested information to the buffer supplied. int fd; struct lv_querypvmap {        ushort_t pv_key;
       ushort_t numpxs;
       pxmap_t *map;
} lv_querypvmap; struct pxmap {        ushort_t lv_minor;
       ushort_t lv_extent;
       ushort_t status;
}; typedef struct pxmap pxmap_t;

This command returns the map of physical extents on the specified physical volume. This mapping indicates the logical volume and logical extent to which each corresponds. A physical extent which is not currently assigned to a logical volume will be indicated by an lv_minor value of 0 (zero). int fd; struct lv_querypvpath {        char *path;
       ushort_t pv_key;
       ushort_t pv_flags;
       ushort_t px_count;
       ushort_t px_free;
       ulong_t px_space;
       dev_t pv_rdev;
       ushort_t maxdefects;
       ushort_t bbpool_len;
} lv_querypvpath;

This command is identical to LVM_QUERYPV, except that it takes a pathname (path) as the physical volume identifier. Also, it returns the pv_key rather than taking it as input. int fd; struct lv_querypvs {        ushort_t numpvs;
       ushort_t *pv_keys;
} lv_querypvs;

This command retrieves the physical volume list from the volume group. It requires the number of volumes in the volume group as input (as obtained from LVM_QUERYVG) and returns the pv_key for each. int fd; struct lv_queryvg {        lv_uniqueID_t vg_id;
       ushort_t maxlvs;
       ushort_t maxpvs;
       ushort_t maxpxs;
       ulong_t pxsize;
       ushort_t freepxs;
       ushort_t cur_lvs;
       ushort_t cur_pvs;
       ushort_t status;
} lv_queryvg;

This command retrieves information about a specified volume group. It verifies that the specified volume group is valid and writes the information requested to the buffer supplied.

int fd; struct lv_realloclv {        ushort_t sourcelv;
       ushort_t destlv;
       ulong_t size;
       lxmap_t *extents;
} lv_realloclv;

This command atomically removes physical extents from one logical volume (fd) and assigns them to another (destlv). The logical extent number of each physical extent is preserved. If the destination logical volume already has space allocated for the indicated logical extents, the new extents will be marked as stale by the reallocation. int fd; struct lv_lvsize {        ushort_t minor_num;
       ulong_t size;
       lxmap_t *extents;
} lv_lvsize; struct lxmap {        ushort_t lx_num;
       ushort_t pv_key;
       ushort_t px_num;
       ushort_t status;
}; typedef struct lxmap lxmap_t;

This command removes extents from a specified logical volume. It deallocates a logical extent for the specified logical volume at the physical volume. The extents to be removed are specified as input via the extent list pointer (*extents). It updates the LVM data structures and the descriptor area.

You can use LVM_REDUCELV on a file descriptor corresponding to a logical volume device. In this case, the minor_num field is ignored. int fd; int pv_key;

This command temporarily removes a physical volume from the volume group by closing the physical volume device. If the volume group is active, the physical volume state is changed to "missing". This command is effectively the inverse of LVM_ATTACHPV. int fd; int minor_num;

This command resynchronizes a logical volume. As a result, every logical extent in the specified logical volume (minor_num), that has a physical extent in the LVM_PXSTALE state, will be updated from a mirror copy. If successful, then the corresponding physical extent's LVM_PXSTALE state is cleared.

You can use this command on a file descriptor corresponding to a logical volume device. In this case, the minor_num argument is ignored. int fd; struct lv_resynclx {        ushort_t minor_num;
       ushort_t lx_num;
} lv_resynclx;

For each physical extent of a logical extent, if the physical extent is in the LVM_PXSTALE state, this command initiates mirror resynchronization for that physical extent. When the command is done, these extents will be in the LVM_ACTIVE state. int fd; int pv_key;

This command resynchronizes a physical volume. For each physical extent on the physical volume that is in the LVM_PXSTALE state, this command resynchronizes the corresponding logical extent. int fd; struct lv_setvgid {        lv_uniqueID_t vg_id;
} lv_setvgid; struct lv_uniqueID {
        ulong_t id1;
       ulong_t id2;
}; typedef struct lv_uniqueID lv_uniqueID_t;

This command sets the volume group ID for the volume group implied by the file descriptor. It fails if the volume group already has a volume group ID and attached physical volumes. It is a necessary precursor to the LVM_ATTACHPV ioctl. If the unique ID passed in is 0 (zero), it is stored. The LVM ioctl commands use the following parameters:

Allocation map for logical volume. Allowed Values: 0 (zero) to 255 Current number of logical volumes in this volume group. Allowed Values: 0 (zero) to LVM_MAXPVS Current number of physical volumes in this volume group. Allowed Values: 0 (zero) to LVM_MAXLXS Current size for logical volume. Pointer to the extent array. flags Allowed Values: Allow logical volume opens. Automatically resynchronize returned volumes. Activate fails if any physical volumes are missing. Activate fails if any physical volumes are missing which were not previously known as missing. Allowed Values: 0 (zero) to LVM_MAXPXS Current number of free extents. Allowed Values: 0 (zero) to MAXLXS Logical extent number on volume. Allowed Values: Logical OR of the following constants: Logical volume entry defined. Logical volume unavailable for use. New bad blocks are not relocated. Read-only logical volume; no writes permitted. Allocate mirrors on different physical volumes. Verify all writes to the logical volume. Do not perform mirror write consistency for this logical volume. Allowed Values: 0 (zero) to LVM_MAXLVS Logical volume minor number. lv_uniqueID The unique ID should be set to a globally unique number. Allowed Values: 0 (zero) to LVM_MAXLXS Logical extent number to perform command on. Pointer to the physical extent map. Allowed Values: 0 (zero) to bbpool_len Maximum number of software-relocated defects. Allowed Values: 0 (zero) to LVM_MAXLVS Maximum number of logical volumes this volume group will contain. Allowed Values: 0 (zero) to LVM_MAXLXS New maximum size for logical volume, count of logical extents. Allowed Values: LVM_MAXCOPIES Maximum number of mirrors allowed for this logical volume. Allowed Values: 0 (zero) to LVM_MAXPVS Maximum number of physical volumes this volume group will contain. Allowed Values: 0 (zero) to LVM_MAXPXS Maximum number of physical extents any physical volumes in this volume group will contain. Allowed Values: 1 to LVM_MAXLVS (or 255) Logical volume minor number. Allowed Values: PATH_MAX chars max NULL terminated physical volume pathname. Allowed Values: 0 (zero) to LVM_MAXLXS Current number of logical extents. Allowed Values: 0 (zero) to LVM_MIRAVOID Mirrors avoided during raw reads. Allowed Values: Logical OR of the following constants: No bad block relocation performed. Verify all writes. Allowed Values: Logical OR of the following constants: No extent allocation allowed from this physical volume. No new defects relocated on this physical volume. No extent allocation allowed from this physical volume. Allowed Values: Logical OR of the following constants: Physical volume is missing from the volume group. Physical volume is not attached to a volume group. Physical volume does not contain a Volume Group Descriptor Area. No extent allocation allowed from this physical volume. No new defects relocated on this physical volume. Allowed Values: Internally defined Physical volume identifier assigned by driver. Allowed Values: 0 (zero) to LVM_MAXPXS Total number of physical extents on this physical volume. Device number (major,minor) currently used to access this physical volume. Not valid if physical volume is not attached. Allowed Values: 0 (zero) to LVM_MAXPXS Physical extent number to add or remove. Allowed Values: 1MB to 256MB Physical extent size for all extents in this volume group (in bytes). Must be a power of 2. Allowed Values: 1MB to 256MB Actual space allocated for each extent (in bytes). This must be the same or larger than pxsize. Allowed Values: 0 (zero) to LVM_MAXPXS Maximum number of physical extents this physical volume will ever contain. Allowed Values: 0 (zero) to LVM_MAXPXS Current number of free physical extents on this physical volume. Allowed Values: 1MB to 256MB Actual space allocated for each extent (in bytes). This must be the same or larger than pxsize. Allowed Values: Write mirror copies sequentially. Write mirror copies in parallel. Allowed Values: 1 to LVM_MAXPXS Number of extents to add or remove. Allowed Values: Any This parameter is ignored. status Allowed Values: LVM_PXSTALE Physical extent is stale. Allowed Values: Logical OR of the following constants: Physical extent is stale (does not contain valid data). Physical extent is on a missing physical volume. Allowed Values: Valid unique ID Valid volume group unique ID. Allowed Values: Logical OR of the following constants: Volume group is activated. Logical volumes are activated.  

RESTRICTIONS

References to mirroring are purely informational, because LVM does not support mirroring.  

ERRORS

On failure, the LVM ioctl commands return the following:

LVM_ACTIVATEVG No valid volume group descriptor areas (VGDA) were found on any physical volume. Could not find a valid volume group status area (VGSA). Quorum was lost while attempting to update the volume group status area. LVM_ALL_PVS_REQUIRED was specified and at least one physical volume was missing. Insufficient kernel memory to complete request. Quorum does not exist. I/O error while reading the bad block directory. There is an invalid physical extent in the VGDA's extent map. LVM_NONMISSING_PVS_REQUIRED was specified and a "nonmissing" physical volume has not been attached.

LVM_ATTACHPV The path parameter does not refer to a valid memory address. The physical volume is a member of another volume group. A component of the path parameter does not exist. A component of the path parameter prefix is not a directory. The path parameter refers to a device that does not exist, or is not configured into the kernel. The path parameter designates a file that is not a block device. A component of the path parameter was not accessible. Too many symbolic links were encountered while looking up the path. The path parameter is too long, or a component exceeds the maximum allowable size. A physical volume with the same physical volume number is already attached to this volume group. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device. The physical volume is not a member of any volume group. The physical volume is not a member of the specified volume group. Insufficient kernel memory to complete request. I/O error while reading the bad block directory or the volume group descriptor area.

LVM_CHANGELV The minor_num parameter is invalid. The maxmirrors parameter was not in the range (0, LVM_MAXCOPIES-1). The lv_flags parameter contains an unrecognized flag. The volume group is not activated. The minor_num parameter refers to a nonexistent logical volume. The sched_strat parameter was not one of LVM_PARALLEL or LVM_SEQUENTIAL. [EBUSY] The maxlxs or maxmirrors parameter is smaller than the current allocation for the logical volume. Must deallocate before changing the logical size. Insufficient kernel memory to complete request. The parameter does not refer to a valid memory address.

LVM_CHANGEPV The pv_flags parameter contains unrecognized flags. The pv_key parameter references a nonexisting physical volume. There are more existing defects than could be supported with the max_defects parameter. The parameter does not refer to a valid memory address. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.

LVM_CREATELV The minor_num parameter is 0 (zero). The minor_num parameter is greater than the maximum number of logical volumes in the volume group. The minor_num parameter refers to an already existing logical volume. Insufficient kernel memory to satisfy the request. The volume group is not activated. The minor_num parameter refers to a nonexistent logical volume. The sched_strat parameter was not one of LVM_PARALLEL or LVM_SEQUENTIAL. The maxlxs or maxmirrors parameter is smaller than the current allocation for the logical volume. Must deallocate before changing the logical size. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.

LVM_CREATEVG Invalid parameter structure; some field within the structure contained an invalid value. Specific checks are made for; 0 (zero) volume group ID, the maxlvs parameter greater than LVM_MAXLVS, the maxpvs parameter greater than MAXPVS, the maxpxs parameter greater than LVM_MAXPXS, 1MB <= pxsize <= 256MB, pxsize <= pxspace, the pxspace parameter is a multiple DEV_BSIZE, the pv_flags parameter is valid. The volume group already exists. Insufficient kernel memory to complete request. Insufficient space on the volume for the volume group reserved area (VGRA). The file specified by the path parameter does not exist. The path parameter does not specify a valid physical volume. Permission denied on open of the path parameter. Unable to read the physical volume. The path parameter designates a file that is not a block device. The physical volume has no driver configured. The parameter does not refer to a valid memory address. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.

LVM_DEACTIVATEVG The minor_num parameter was less than or equal to zero. The volume group is not activated. The minor_num parameter refers to a nonexistent logical volume. The indicated logical volume is open. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.

LVM_DELETEPV Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.

LVM_EXTENDLV The parameter does not refer to a valid memory address. An extent described by the extent array is already in use. The specified logical volume does not exist.

LVM_INSTALLPV The volume group is not active. Unable to allocate memory. The device is not a valid physical volume. Write permission denied on the device. A component of the path parameter was not accessible. Unable to read the physical volume. The path parameter designates a file that is not a block device. The physical volume has no driver configured. The parameter does not refer to a valid memory address. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.

LVM_OPTIONSET/LVM_OPTIONGET The opt_avoid parameter out of range (LVM_OPTIONSET only). The opt_options parameter included invalid bit values (LVM_OPTIONSET only). The parameter does not refer to a valid memory address. Inappropriate ioctl for device; the command was attempted on the control device.

LVM_QUERYLV The minor_num parameter is 0 (zero). The volume group is not activated. The parameter does not refer to a valid memory address.

LVM_QUERYLVMAP The parameter does not refer to a valid memory address.

LVM_QUERYPV The parameter does not refer to a valid memory address. The specified pv_key parameter does not correspond to physical volume attached to this volume group, that is, no such device. Inappropriate ioctl for device; the command was attempted on the control device.

LVM_QUERYPVMAP The parameter does not refer to a valid memory address. The specified pv_key parameter does not correspond to physical volume attached to this volume group, that is, no such device. Inappropriate ioctl for device; the command was attempted on the control device.

LVM_QUERYPATH The parameter does not refer to a valid memory address. A component of the path parameter does not exist. A component of the path parameter prefix is not a directory. The path parameter refers to a device that does not exist, or is not configured into the kernel. The path parameter designates a file that is not a block device. A component of the path parameter was not accessible. Too many symbolic links were encountered while looking up the path. The path parameter is too long, or a component exceeds the maximum allowable size. The specified path parameter does not correspond to physical volume attached to this volume group, that is, no such device. Inappropriate ioctl for device; the command was attempted on a logical volume device.

LVM_QUERYPVS The parameter does not refer to a valid memory address. Inappropriate ioctl for device; the command was attempted on a logical volume device.

LVM_QUERYVG The parameter does not refer to a valid memory address.

LVM_REDUCELV The parameter does not refer to a valid memory address.

LVM_RESYNCLX The parameter does not refer to a valid memory address.

LVM_RESYNCPV Inappropriate ioctl for device; the command was attempted on a logical volume device.

LVM_SETVGID The parameter does not refer to a valid memory address. Inappropriate ioctl for device; the command was attempted on a logical volume device rather than the control device.  

RELATED INFORMATION

Function: ioctl(2) delim off


 

Index

NAME
SYNOPSIS
DESCRIPTION
RESTRICTIONS
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:27 GMT, October 02, 2010