lvm2/liblvm/lvm.h

/*
 * Copyright (C) 2008,2009 Red Hat, Inc. All rights reserved.
 *
 * This file is part of LVM2.
 *
 * This copyrighted material is made available to anyone wishing to use,
 * modify, copy, or redistribute it subject to the terms and conditions
 * of the GNU Lesser General Public License v.2.1.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef _LIB_LVM_H
#define _LIB_LVM_H

#include "lvm-version.h"
#include "libdevmapper.h"

#include <stdint.h>


/******************************** WARNING ********************************/
/*
 * NOTE: This API is under development and subject to change at any time.
 *
 * Please send feedback to lvm-devel@redhat.com
 */
/******************************** WARNING ********************************/


/******************************** structures ********************************/

/**
 * Opaque structures - do not use directly.  Internal structures may change
 * without notice between releases, whereas this API will be changed much less
 * frequently.  Backwards compatibility will normally be preserved in future
 * releases.  On any occasion when the developers do decide to break backwards
 * compatibility in any significant way, the LVM_LIBAPI number (included in
 * the library's soname) will be incremented.
 */
struct lvm;
struct physical_volume;
struct volume_group;
struct logical_volume;

/**
 * lvm handle.
 *
 * This is the base handle that is needed to open and create objects such as
 * volume groups and logical volumes.  In addition, this handle provides a
 * context for error handling information, saving any error number (see
 * lvm_errno) and error message (see lvm_errmsg) that any function may
 * generate.
 */
typedef struct lvm *lvm_t;

/**
 * Volume group object.
 *
 * This object can be either a read-only object or a read-write object
 * depending on the mode it was returned by a function. Create functions
 * return a read-write object, but open functions have the argument mode to
 * define if the object can be modified or not.
 */
typedef struct volume_group vg_t;

/**
 * Logical Volume object.
 *
 * This object is bound to a volume group and has the same mode of the volume
 * group.  Changes will be written to disk when the volume group gets
 * committed to disk.
 */
typedef struct logical_volume lv_t;

/**
 * Physical volume object.
 *
 * This object is bound to a volume group and has the same mode of the volume
 * group.  Changes will be written to disk when the volume group gets
 * committed to disk.
 */
typedef struct physical_volume pv_t;

/**
 * Logical Volume object list.
 *
 * Lists of these structures are returned by lvm_vg_list_pvs.
 */
typedef struct lvm_lv_list {
	struct dm_list list;
	lv_t *lv;
} lv_list_t;

/**
 * Physical volume object list.
 *
 * Lists of these structures are returned by lvm_vg_list_pvs.
 */
typedef struct lvm_pv_list {
	struct dm_list list;
	pv_t *pv;
} pv_list_t;

/**
 * String list.
 *
 * This string list contains read-only strings.
 * Lists of these structures are returned by lvm_list_vg_names and
 * lvm_list_vg_uuids.
 */
struct lvm_str_list {
	struct dm_list list;
	const char *str;
};

/*************************** generic lvm handling ***************************/
/**
 * Create a LVM handle.
 *
 * Once all LVM operations have been completed, use lvm_quit to release
 * the handle and any associated resources.
 *
 * \param   system_dir
 *          Set an alternative LVM system directory. Use NULL to use the
 *          default value. If the environment variable LVM_SYSTEM_DIR is set,
 *          it will override any system_dir setting.
 * \return  A valid LVM handle is returned or NULL if there has been a
 *          memory allocation problem. You have to check if an error occured
 *          with the lvm_error function.
 */
// FIXME: Sort out this alignment.  "Set an" directly below "system_dir"
// looks awful.  Indent differently?  More blank lines?
lvm_t lvm_init(const char *system_dir);
// FIXME Find a better name.  lvm_init.

/**
 * Destroy a LVM handle allocated with lvm_init.
 *
 * This function should be used after all LVM operations are complete or after
 * an unrecoverable error.  Destroying the LVM handle frees the memory and
 * other resources associated with the handle.  Once destroyed, the handle
 * cannot be used subsequently.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 */
void lvm_quit(lvm_t libh);

/**
 * Reload the original configuration from the system directory.
 *
 * This function should be used when any LVM configuration changes in the LVM
 * system_dir or by another lvm_config* function, and the change is needed by
 * the application.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 * \return  0 (success) or -1 (failure).
 */
int lvm_config_reload(lvm_t libh);

/**
 * Override the LVM configuration with a configuration string.
 *
 * This function is equivalent to the --config option on lvm commands.
 * FIXME: submit a patch to document the --config option
 * Once this API has been used to over-ride the configuration,
 * you should use lvm_config_reload to apply the new settings.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 * \param   config_string
 *          LVM configuration string to apply.  See the lvm.conf file man page
 *          for the format of the config string.
 * \return  0 (success) or -1 (failure).
 */
int lvm_config_override(lvm_t libh, const char *config_string);

/**
 * Return stored error no describing last LVM API error.
 *
 * Users of liblvm should use lvm_errno to determine the details of a any
 * failure of the last call.  A basic success or fail is always returned by
 * every function, either by returning a 0 or -1, or a non-NULL / NULL.
 * If a function has failed, lvm_errno may be used to get a more specific
 * error code describing the failure.  In this way, lvm_errno may be used
 * after every function call, even after a 'get' function call that simply
 * returns a value.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 *
 * \return  An errno value describing the last LVM error.
 */
int lvm_errno(lvm_t libh);

/**
 * Return stored error message describing last LVM error.
 *
 * This function may be used in conjunction with lvm_errno to obtain more
 * specific error information for a function that is known to have failed.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 *
 * \return  An error string describing the last LVM error.
 */
const char *lvm_errmsg(lvm_t libh);

/**
 * Scan all devices on the system for VGs and LVM metadata.
 * FIXME: Elaborate on when to use, side-effects, .cache file, etc
 *
 * \return  0 (success) or -1 (failure).
 */
int lvm_scan(lvm_t libh);

/*************************** volume group handling **************************/

/**
 * Return the list of volume group names.
 *
 * The memory allocated for the list is tied to the lvm_t handle and will be
 * released when lvm_quit is called.
 *
 * NOTE: This function normally does not scan devices in the system for LVM
 * metadata.  To scan the system, use lvm_scan.
 * NOTE: This function currently returns hidden VG names.  These names always
 * begin with a "#" and should be filtered out and not used.
 *
 * To process the list, use the dm_list iterator functions.  For example:
 *      vg_t *vg;
 *      struct dm_list *vgnames;
 *      struct lvm_str_list *strl;
 *
 *      vgnames = lvm_list_vg_names(libh);
 *	dm_list_iterate_items(strl, vgnames) {
 *		vgname = strl->str;
 *              vg = lvm_vg_open(libh, vgname, "r");
 *              // do something with vg
 *              lvm_vg_close(vg);
 *      }
 *
 *
 * \return  A list with entries of type struct lvm_str_list, containing the
 *          VG name strings of the Volume Groups known to the system.
 *          NULL is returned if unable to allocate memory.
 *          An empty list (verify with dm_list_empty) is returned if no VGs
 *          exist on the system.
 */
struct dm_list *lvm_list_vg_names(lvm_t libh);

/**
 * Return the list of volume group uuids.
 *
 * The memory allocated for the list is tied to the lvm_t handle and will be
 * released when lvm_quit is called.
 *
 * NOTE: This function normally does not scan devices in the system for LVM
 * metadata.  To scan the system, use lvm_scan.
 * NOTE: This function currently returns hidden VG names.  These names always
 * begin with a "#" and should be filtered out and not used.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 *
 * \return  A list with entries of type struct lvm_str_list, containing the
 *          VG UUID strings of the Volume Groups known to the system.
 *          NULL is returned if unable to allocate memory.
 *          An empty list (verify with dm_list_empty) is returned if no VGs
 *          exist on the system.
 */
struct dm_list *lvm_list_vg_uuids(lvm_t libh);

/**
 * Open an existing VG.
 *
 * Open a VG for reading or writing.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 * \param   vgname
 *          Name of the VG to open.
 * \param   mode
 *          Open mode - either "r" (read) or "w" (read/write).
 *          Any other character results in an error with EINVAL set.
 * \param   flags
 *          Open flags - currently ignored.
 * \return  non-NULL VG handle (success) or NULL (failure).
 */
vg_t *lvm_vg_open(lvm_t libh, const char *vgname, const char *mode,
		  uint32_t flags);

/**
 * Create a VG with default parameters.
 *
 * This function creates a Volume Group object in memory.
 * Upon success, other APIs may be used to set non-default parameters.
 * For example, to set a non-default extent size, use lvm_vg_set_extent_size.
 * Next, to add physical storage devices to the volume group, use
 * lvm_vg_extend for each device.
 * Once all parameters are set appropriately and all devices are added to the
 * VG, use lvm_vg_write to commit the new VG to disk, and lvm_vg_close to
 * release the VG handle.
 *
 * \param   libh
 *          Handle obtained from lvm_init.
 * \param   vg_name
 *          Name of the VG to open.
 * \return  non-NULL vg handle (success) or NULL (failure)
 */
vg_t *lvm_vg_create(lvm_t libh, const char *vg_name);

 /**
 * Write a VG to disk.
 *
 * This function commits the Volume Group object referenced by the VG handle
 * to disk. Upon failure, retry the operation and/or release the VG handle
 * with lvm_vg_close.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_write(vg_t *vg);

/**
 * Remove a VG from the system.
 *
 * This function commits the change to disk and does not require calling
 * lvm_vg_write.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_remove(vg_t *vg);

/**
 * Close a VG opened with lvm_vg_create or lvm_vg_open.
 *
 * This function releases a VG handle and any resources associated with the
 * handle.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_close(vg_t *vg);

/**
 * Extend a VG by adding a device.
 *
 * This function requires calling lvm_vg_write to commit the change to disk.
 * After successfully adding a device, use lvm_vg_write to commit the new VG
 * to disk.  Upon failure, retry the operation or release the VG handle with
 * lvm_vg_close.
 * If the device is not initialized for LVM use, it will be initialized
 * before adding to the VG.  Although some internal checks are done,
 * the caller should be sure the device is not in use by other subsystems
 * before calling lvm_vg_extend.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \param   device
 *          Absolute pathname of device to add to VG.
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_extend(vg_t *vg, const char *device);

/**
 * Reduce a VG by removing an unused device.
 *
 * This function requires calling lvm_vg_write to commit the change to disk.
 * After successfully removing a device, use lvm_vg_write to commit the new VG
 * to disk.  Upon failure, retry the operation or release the VG handle with
 * lvm_vg_close.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 *
 * \param   device
 *          Name of device to remove from VG.
 *
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_reduce(vg_t *vg, const char *device);

/**
 * Set the extent size of a VG.
 *
 * This function requires calling lvm_vg_write to commit the change to disk.
 * After successfully setting a new extent size, use lvm_vg_write to commit
 * the new VG to disk.  Upon failure, retry the operation or release the VG
 * handle with lvm_vg_close.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \param   new_size
 *          New extent size in bytes.
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_set_extent_size(vg_t *vg, uint32_t new_size);

/**
 * Get the current name of a volume group.
 *
 * Memory is allocated using dm_malloc() and caller must free the memory
 * using dm_free().
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Copy of the uuid string.
 */
char *lvm_vg_get_uuid(const vg_t *vg);

/**
 * Get the current uuid of a volume group.
 *
 * Memory is allocated using dm_malloc() and caller must free the memory
 * using dm_free().
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Copy of the name.
 */
char *lvm_vg_get_name(const vg_t *vg);

/**
 * Get the current size in bytes of a volume group.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Size in bytes.
 */
uint64_t lvm_vg_get_size(const vg_t *vg);

/**
 * Get the current unallocated space in bytes of a volume group.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Free size in bytes.
 */
uint64_t lvm_vg_get_free_size(const vg_t *vg);

/**
 * Get the current extent size in bytes of a volume group.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Extent size in bytes.
 */
uint64_t lvm_vg_get_extent_size(const vg_t *vg);

/**
 * Get the current number of total extents of a volume group.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Extent count.
 */
uint64_t lvm_vg_get_extent_count(const vg_t *vg);

/**
 * Get the current number of free extents of a volume group.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Free extent count.
 */
uint64_t lvm_vg_get_free_extent_count(const vg_t *vg);

/**
 * Get the current number of physical volumes of a volume group.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  Physical volume count.
 */
uint64_t lvm_vg_get_pv_count(const vg_t *vg);

/************************** logical volume handling *************************/

/**
 * Return a list of LV handles for a given VG handle.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  A list of lv_list_t structures containing lv handles for this vg.
 *          If no LVs exist on the given VG, NULL is returned.
 */
struct dm_list *lvm_vg_list_lvs(vg_t *vg);

/**
 * Create a linear logical volume.
 * This function commits the change to disk and does _not_ require calling
 * lvm_vg_write.
 * FIXME: This function should probably not commit to disk but require calling
 * lvm_vg_write.  However, this appears to be non-trivial change until
 * lv_create_single is refactored by segtype.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \param   name
 *          Name of logical volume to create.
 * \param   size
 *          Size of logical volume in extents.
 * \return  LV object
 *
 */
lv_t *lvm_vg_create_lv_linear(vg_t *vg, const char *name, uint64_t size);

/**
 * Activate a logical volume.
 *
 * This function is the equivalent of the lvm command "lvchange -ay".
 *
 * NOTE: This function cannot currently handle LVs with an in-progress pvmove or
 * lvconvert.
 *
 * \param   lv
 *          Logical volume handle.
 * \return  0 (success) or -1 (failure).
 */
int lvm_lv_activate(lv_t *lv);

/**
 * Deactivate a logical volume.
 *
 * This function is the equivalent of the lvm command "lvchange -an".
 *
 * \param   lv
 *          Logical volume handle.
 * \return  0 (success) or -1 (failure).
 */
int lvm_lv_deactivate(lv_t *lv);

/**
 * Remove a logical volume from a volume group.
 *
 * This function commits the change to disk and does _not_ require calling
 * lvm_vg_write.
 * Currently only removing linear LVs are possible.
 *
 * FIXME: This function should probably not commit to disk but require calling
 * lvm_vg_write.
 *
 * \param   lv
 *          Logical volume handle.
 * \return  0 (success) or -1 (failure).
 */
int lvm_vg_remove_lv(lv_t *lv);

/**
 * Get the current name of a logical volume.
 *
 * Memory is allocated using dm_malloc() and caller must free the memory
 * using dm_free().
 *
 * \param   lv
 *          Logical volume handle.
 * \return  Copy of the uuid string.
 */
char *lvm_lv_get_uuid(const lv_t *lv);

/**
 * Get the current uuid of a logical volume.
 *
 * Memory is allocated using dm_malloc() and caller must free the memory
 * using dm_free().
 *
 * \param   lv
 *          Logical volume handle.
 * \return  Copy of the name.
 */
char *lvm_lv_get_name(const lv_t *lv);

/**
 * Get the current size in bytes of a logical volume.
 *
 * \param   lv
 *          Logical volume handle.
 * \return  Size in bytes.
 */
uint64_t lvm_lv_get_size(const lv_t *lv);

/**
 * Get the current activation state of a logical volume.
 *
 * \param   lv
 *          Logical volume handle.
 * \return  1 if the LV is active in the kernel, 0 if not
 */
uint64_t lvm_lv_is_active(const lv_t *lv);

/**
 * Get the current suspended state of a logical volume.
 *
 * \param   lv
 *          Logical volume handle.
 * \return  1 if the LV is suspended in the kernel, 0 if not
 */
uint64_t lvm_lv_is_suspended(const lv_t *lv);

/**
 * Resize logical volume to new_size bytes.
 *
 * \param   lv
 *          Logical volume handle.
 * \param   new_size
 *          New size in bytes.
 * \return  0 (success) or -1 (failure).
 *
 */
int lvm_lv_resize(const lv_t *lv, uint64_t new_size);

/************************** physical volume handling ************************/

/**
 * Physical volume handling should not be needed anymore. Only physical volumes
 * bound to a vg contain useful information. Therefore the creation,
 * modification and the removal of orphan physical volumes is not suported.
 */

/**
 * Return a list of PV handles for a given VG handle.
 *
 * \param   vg
 *          VG handle obtained from lvm_vg_create or lvm_vg_open.
 * \return  A list of pv_list_t structures containing pv handles for this vg.
 *          If no PVs exist on the given VG, NULL is returned.
 */
struct dm_list *lvm_vg_list_pvs(vg_t *vg);

/**
 * Get the current uuid of a logical volume.
 *
 * Memory is allocated using dm_malloc() and caller must free the memory
 * using dm_free().
 *
 * \param   pv
 *          Physical volume handle.
 * \return  Copy of the uuid string.
 */
char *lvm_pv_get_uuid(const pv_t *pv);

/**
 * Get the current name of a logical volume.
 *
 * Memory is allocated using dm_malloc() and caller must free the memory
 * using dm_free().
 *
 * \param   pv
 *          Physical volume handle.
 * \return  Copy of the name.
 */
char *lvm_pv_get_name(const pv_t *pv);

/**
 * Get the current number of metadata areas in the physical volume.
 *
 * \param   pv
 *          Physical volume handle.
 * \return  metadata area count.
 */
uint64_t lvm_pv_get_mda_count(const pv_t *pv);

/**
 * Resize physical volume to new_size bytes.
 *
 * \param   pv
 *          Physical volume handle.
 * \param   new_size
 *          New size in bytes.
 * \return  0 (success) or -1 (failure).
 *
 */
int lvm_pv_resize(const pv_t *pv, uint64_t new_size);

#endif /* _LIB_LVM_H */