lvm_createlv Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

lvm_createlv Subroutine

Purpose

Creates an empty logical volume in a specified volume group.

Library

Logical Volume Manager Library (liblvm.a)

Syntax

#include <lvm.h>

int lvm_createlv 
(CreateLV)
struct createlv *CreateLV;

Description

Note: You must have root user authority to use this subroutine.

The lvm_createlv subroutine creates an empty logical volume in an existing volume group with the information supplied. The lvm_extendlv subroutine should be called to allocate partitions once the logical volume is created.

The createlv structure pointed to by the CreateLV parameter is defined in the lvm.h file and contains the following fields:

struct createlv {
  char *lvname;
  struct unique_id vg_id;
  long minor_num;
  long maxsize;
  long mirror_policy;
  long permissions;
  long bb_relocation;
  long write_verify;
  long mirwrt_consist;
}
struct unique_id{
#ifndef_64BIT_    
    unsigned long word1;
    unsigned long word2;
    unsigned long word3;
    unsigned long word4;
#else
    unsigned int word1;
    unsigned int word2;
    unsigned int word3;
    unsigned int word4;
#endif
};

Field	Definition
`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 in order 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 will contain the logical volume.
`minor_num`	Must be in the range from 1 to the `maxlvs` value. The `maxlvs` field is set when a volume group is created and is returned by the lvm_queryvg subroutine.
`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 will be 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.
`permissions`	Indicates read/write or read only permission for the logical volume.
`bb_relocation`	Indicates that bad block relocation is desired.
`write_verify`	Indicates that writes to the logical volume are to be verified as successful.
`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 the page space, that do not use the existing data when the volume group is re-varied on do not need this protection.

All fields in the createlv structure must have a valid value in them, or an error will be returned.

The lvm_createlv subroutine uses the createlv structure to build an information area for the logical volume. If the volume group that is to contain this logical volume is not varied on-line, the LVM_OFFLINE error code is returned.

Possible values for the mirror_policy field are:

LVM_SEQUENTIAL	For this logical volume, use a sequential method of writing the physical copies (if more than one) of a logical partition.
LVM_PARALLEL	For this logical volume, use a parallel method of writing the physical copies (if more than one) of a logical partition.

Possible values for the permissions field are:

LVM_RDONLY	Create the logical volume with read only permission.
LVM_RDWR	Create the logical volume with read/write permission.

Possible values for the bb_relocation field are:

LVM_RELOC	Bad block relocation is desired.
LVM_NORELOC	Bad block relocation is not desired.

Possible values for the write_verify field are:

LVM_VERIFY	Write verification is desired.
LVM_NOVERIFY	Write verification is not desired.

Possible 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.

Parameters

CreateLV

Points to the createlv structure.

Return Values

The lvm_createlv subroutine returns a value of 0 upon successful completion.

Error Codes

If the lvm_createlv subroutine fails, it returns one of the following values:

LVM_ALLOCERR	A memory allocation error has occurred.
LVM_DALVOPN	The descriptor area logical volume could not be opened.
LVM_FORCEOFF	The volume group has been forcefully varied off due to a loss of quorum.
LVM_INVALID_MIN_NUM	A minor number passed into the routine is invalid.
LVM_INVALID_PARAM	A field in the createlv structure is invalid, or the pointer to the createlv structure is invalid.
LVM_INV_DEVENT	The logical volume device entry is invalid and cannot be checked to determine if it is raw.
LVM_LVEXIST	A logical volume already exists with the name passed into the routine.
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	An error occurred while trying to read or write the mapped file.
LVM_NOTCHARDEV	The lvname name given does not represent a raw or character device.
LVM_OFFLINE	A routine that requires a volume group to be online has encountered one that is offline.
LVM_VGFULL	The volume group that the logical volume was requested to be a member of already has the maximum number of logical volumes.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The lvm_extendlv subroutine, lvm_querylv subroutine, lvm_queryvg subroutine, lvm_varyonvg subroutine.

List of Logical Volume Subroutines and Logical Volume Programming Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.