*** UNIX MANUAL PAGE BROWSER ***

lvm(7) Miscellaneous Information Manual lvm(7) 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 Log- ical 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 logi- cal 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 func- tions 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 possi- ble 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 miscella- neous functions. The following table illustrates these groupings: Volume Group Activate volume group Create volume group Deactivate vol- ume 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 ex- tents) Query logical volume (retrieve information) Query logical volume physical extent map Move physical extents between logical volumes Re- duce 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 infor- mation) Query map of physical extents on physical volume Query physical volume using physical identifier as the pathname Query multiple physi- cal 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 de- scriptions 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 Oper- ating 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 re- covery of active mirrors. Depending on whether the LVM_ALL_PVS_RE- QUIRED 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 com- mand to disallow or re-allow allocation of extents on the physical vol- ume. 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 al- ready been relocated on the physical volume, LVM_CHANGEPV will reset maxdefects to the relocated number of defects. int fd; struct lv_sta- tuslv { 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 en- tries corresponds to the minor number (minor_num) of the logical vol- ume. 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 ig- nored. 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 ex- tents 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 re- moves 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 vol- ume 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 physi- cal 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 opera- tions, set through the opt_avoid field. This allows a program to ac- cess a specific copy of a mirrored logical volume. The opt_options field allows the program to temporarily (until the de- vice 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 mi- nor_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 logi- cal 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 sta- tus; }; 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 logi- cal 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 phys- ical volume. This mapping indicates the logical volume and logical extent to which each corresponds. A physical extent which is not cur- rently 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 path- name (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 ob- tained 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 infor- mation 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 vol- ume (fd) and assigns them to another (destlv). The logical extent num- ber 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 sta- tus; }; typedef struct lxmap lxmap_t; This command removes extents from a specified logical volume. It deal- locates a logical extent for the specified logical volume at the physi- cal 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 logi- cal 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 com- mand is effectively the inverse of LVM_ATTACHPV. int fd; int mi- nor_num; This command resynchronizes a logical volume. As a result, every logi- cal 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 logi- cal 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 resynchroniza- tion 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 ex- tent on the physical volume that is in the LVM_PXSTALE state, this com- mand 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 Val- ues: 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 vol- umes. 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 num- ber of free extents. Allowed Values: 0 (zero) to MAXLXS Logical extent number on volume. Allowed Values: Logical OR of the following con- stants: 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_MAX- COPIES Maximum number of mirrors allowed for this logical volume. Al- lowed 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 termi- nated physical volume pathname. Allowed Values: 0 (zero) to LVM_MAXLXS Current number of logical extents. Allowed Values: 0 (zero) to LVM_MI- RAVOID 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 ex- tent allocation allowed from this physical volume. No new defects re- located on this physical volume. No extent allocation allowed from this physical volume. Allowed Values: Logical OR of the following con- stants: 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 num- ber of physical extents on this physical volume. Device number (ma- jor,minor) currently used to access this physical volume. Not valid if physical volume is not attached. Allowed Values: 0 (zero) to LVM_MAX- PXS 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. Al- lowed 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 Num- ber 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 miss- ing physical volume. Allowed Values: Valid unique ID Valid volume group unique ID. Allowed Values: Logical OR of the following con- stants: 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 ad- dress. 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 at- tached to this volume group. Inappropriate ioctl for device; the com- mand 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. Insuf- ficient 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 para- meter was not in the range (0, LVM_MAXCOPIES-1). The lv_flags parame- ter 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 pa- rameter 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 pa- rameter. The parameter does not refer to a valid memory address. In- appropriate 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 para- meter is greater than the maximum number of logical volumes in the vol- ume group. The minor_num parameter refers to an already existing logi- cal 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 deal- locate before changing the logical size. Inappropriate ioctl for de- vice; the command was attempted on a logical volume device rather than the control device. LVM_CREATEVG Invalid parameter structure; some field within the struc- ture 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 com- plete 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 vol- ume. 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 pa- rameter 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 speci- fied logical volume does not exist. LVM_INSTALLPV The volume group is not active. Unable to allocate mem- ory. The device is not a valid physical volume. Write permission de- nied on the device. A component of the path parameter was not accessi- ble. Unable to read the physical volume. The path parameter desig- nates a file that is not a block device. The physical volume has no driver configured. The parameter does not refer to a valid memory ad- dress. 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 at- tempted 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 at- tached 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 lvm(7)