]>
sourceware.org Git - lvm2.git/blob - liblvm/lvm2app.h
2 * Copyright (C) 2008,2009,2010 Red Hat, Inc. All rights reserved.
4 * This file is part of LVM2.
6 * This copyrighted material is made available to anyone wishing to use,
7 * modify, copy, or redistribute it subject to the terms and conditions
8 * of the GNU Lesser General Public License v.2.1.
10 * You should have received a copy of the GNU Lesser General Public License
11 * along with this program; if not, write to the Free Software Foundation,
12 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
14 #ifndef _LIB_LVM2APP_H
15 #define _LIB_LVM2APP_H
17 #include <libdevmapper.h>
25 /******************************** WARNING ***********************************
27 * NOTE: This API is under development and subject to change at any time.
29 * Please send feedback to lvm-devel@redhat.com
31 *********************************** WARNING ********************************/
33 /*************************** Design Overview ********************************/
36 * \mainpage LVM library API
38 * The API is designed around the following basic LVM objects:
39 * 1) Physical Volume (pv_t) 2) Volume Group (vg_t) 3) Logical Volume (lv_t).
41 * The library provides functions to list the objects in a system,
42 * get and set object properties (such as names, UUIDs, and sizes), as well
43 * as create/remove objects and perform more complex operations and
44 * transformations. Each object instance is represented by a handle, and
45 * handles are passed to and from the functions to perform the operations.
47 * A central object in the library is the Volume Group, represented by the
48 * VG handle, vg_t. Performing an operation on a PV or LV object first
49 * requires obtaining a VG handle. Once the vg_t has been obtained, it can
50 * be used to enumerate the pv_t and lv_t objects within that vg_t. Attributes
51 * of these objects can then be queried or changed.
53 * A volume group handle may be obtained with read or write permission.
54 * Any attempt to change a property of a pv_t, vg_t, or lv_t without
55 * obtaining write permission on the vg_t will fail with EPERM.
57 * An application first opening a VG read-only, then later wanting to change
58 * a property of an object must first close the VG and re-open with write
59 * permission. Currently liblvm provides no mechanism to determine whether
60 * the VG has changed on-disk in between these operations - this is the
61 * application's responsiblity. One way the application can ensure the VG
62 * has not changed is to save the "vg_seqno" field after opening the VG with
63 * READ permission. If the application later needs to modify the VG, it can
64 * close the VG and re-open with WRITE permission. It should then check
65 * whether the original "vg_seqno" obtained with READ permission matches
66 * the new one obtained with WRITE permission.
70 * Retrieve the library version.
72 * The library version is the same format as the full LVM version.
73 * The format is as follows:
74 * LVM_MAJOR.LVM_MINOR.LVM_PATCHLEVEL(LVM_LIBAPI)[-LVM_RELEASE]
75 * An application wishing to determine compatibility with a particular version
76 * of the library should check at least the LVM_MAJOR, LVM_MINOR, and
77 * LVM_LIBAPI numbers. For example, assume the full LVM version is
78 * 2.02.50(1)-1. The application should verify the "2.02" and the "(1)".
80 * \return A string describing the library version.
82 const char *lvm_library_get_version(void);
84 /******************************** structures ********************************/
87 * Opaque structures - do not use directly. Internal structures may change
88 * without notice between releases, whereas this API will be changed much less
89 * frequently. Backwards compatibility will normally be preserved in future
90 * releases. On any occasion when the developers do decide to break backwards
91 * compatibility in any significant way, the LVM_LIBAPI number (included in
92 * the library's soname) will be incremented.
95 struct physical_volume
;
97 struct logical_volume
;
104 * This is the base handle that is needed to open and create objects such as
105 * volume groups and logical volumes. In addition, this handle provides a
106 * context for error handling information, saving any error number (see
107 * lvm_errno()) and error message (see lvm_errmsg()) that any function may
110 typedef struct lvm
*lvm_t
;
115 * The volume group object is a central object in the library, and can be
116 * either a read-only object or a read-write object depending on the function
117 * used to obtain the object handle. For example, lvm_vg_create() always
118 * returns a read/write handle, while lvm_vg_open() has a "mode" argument
119 * to define the read/write mode of the handle.
121 typedef struct volume_group
*vg_t
;
126 * This logical volume object is bound to a vg_t and has the same
127 * read/write mode as the vg_t. Changes will be written to disk
128 * when the vg_t gets committed to disk by calling lvm_vg_write().
130 typedef struct logical_volume
*lv_t
;
135 * This physical volume object is bound to a vg_t and has the same
136 * read/write mode as the vg_t. Changes will be written to disk
137 * when the vg_t gets committed to disk by calling lvm_vg_write().
139 typedef struct physical_volume
*pv_t
;
144 * This lv segment object is bound to a lv_t.
146 typedef struct lv_segment
*lvseg_t
;
151 * This pv segment object is bound to a pv_t.
153 typedef struct pv_segment
*pvseg_t
;
156 * Logical Volume object list.
158 * Lists of these structures are returned by lvm_vg_list_lvs().
160 typedef struct lvm_lv_list
{
166 * Logical Volume Segment object list.
168 * Lists of these structures are returned by lvm_lv_list_lvsegs().
170 typedef struct lvm_lvseg_list
{
176 * Physical volume object list.
178 * Lists of these structures are returned by lvm_vg_list_pvs().
180 typedef struct lvm_pv_list
{
186 * Physical Volume Segment object list.
188 * Lists of these structures are returned by lvm_pv_list_pvsegs().
190 typedef struct lvm_pvseg_list
{
198 * This string list contains read-only strings.
199 * Lists of these structures are returned by functions such as
200 * lvm_list_vg_names() and lvm_list_vg_uuids().
202 typedef struct lvm_str_list
{
210 * This structure defines a single LVM property value for an LVM object.
211 * The structures are returned by functions such as
212 * lvm_vg_get_property().
214 * is_settable: indicates whether a 'set' function exists for this property
215 * is_string: indicates whether this property is a string (1) or not (0)
216 * is_integer: indicates whether this property is an integer (1) or not (0)
217 * is_valid: indicates whether 'value' is valid (1) or not (0)
219 typedef struct lvm_property_value
{
220 uint32_t is_settable
:1;
221 uint32_t is_string
:1;
222 uint32_t is_integer
:1;
229 } lvm_property_value_t
;
231 /*************************** generic lvm handling ***************************/
233 * Create a LVM handle.
237 * Once all LVM operations have been completed, use lvm_quit() to release
238 * the handle and any associated resources.
241 * Set an alternative LVM system directory. Use NULL to use the
242 * default value. If the environment variable LVM_SYSTEM_DIR is set,
243 * it will override any system_dir setting.
246 * A valid LVM handle is returned or NULL if there has been a
247 * memory allocation problem. You have to check if an error occured
248 * with the lvm_error() function.
250 lvm_t
lvm_init(const char *system_dir
);
253 * Destroy a LVM handle allocated with lvm_init().
257 * This function should be used after all LVM operations are complete or after
258 * an unrecoverable error. Destroying the LVM handle frees the memory and
259 * other resources associated with the handle. Once destroyed, the handle
260 * cannot be used subsequently.
263 * Handle obtained from lvm_init().
265 void lvm_quit(lvm_t libh
);
268 * Reload the original configuration from the system directory.
272 * This function should be used when any LVM configuration changes in the LVM
273 * system_dir or by another lvm_config* function, and the change is needed by
277 * Handle obtained from lvm_init().
280 * 0 (success) or -1 (failure).
282 int lvm_config_reload(lvm_t libh
);
285 * Override the LVM configuration with a configuration string.
289 * This function is equivalent to the --config option on lvm commands.
290 * Once this API has been used to over-ride the configuration,
291 * use lvm_config_reload() to apply the new settings.
294 * Handle obtained from lvm_init().
296 * \param config_string
297 * LVM configuration string to apply. See the lvm.conf file man page
298 * for the format of the config string.
301 * 0 (success) or -1 (failure).
303 int lvm_config_override(lvm_t libh
, const char *config_string
);
306 * Return stored error no describing last LVM API error.
310 * Users of liblvm should use lvm_errno to determine the details of a any
311 * failure of the last call. A basic success or fail is always returned by
312 * every function, either by returning a 0 or -1, or a non-NULL / NULL.
313 * If a function has failed, lvm_errno may be used to get a more specific
314 * error code describing the failure. In this way, lvm_errno may be used
315 * after every function call, even after a 'get' function call that simply
319 * Handle obtained from lvm_init().
322 * An errno value describing the last LVM error.
324 int lvm_errno(lvm_t libh
);
327 * Return stored error message describing last LVM error.
331 * This function may be used in conjunction with lvm_errno() to obtain more
332 * specific error information for a function that is known to have failed.
335 * Handle obtained from lvm_init().
338 * An error string describing the last LVM error.
340 const char *lvm_errmsg(lvm_t libh
);
343 * Scan all devices on the system for VGs and LVM metadata.
348 * 0 (success) or -1 (failure).
350 int lvm_scan(lvm_t libh
);
353 * Return the list of volume group names.
357 * The memory allocated for the list is tied to the lvm_t handle and will be
358 * released when lvm_quit() is called.
360 * NOTE: This function normally does not scan devices in the system for LVM
361 * metadata. To scan the system, use lvm_scan().
363 * To process the list, use the dm_list iterator functions. For example:
365 * struct dm_list *vgnames;
366 * struct lvm_str_list *strl;
368 * vgnames = lvm_list_vg_names(libh);
369 * dm_list_iterate_items(strl, vgnames) {
370 * vgname = strl->str;
371 * vg = lvm_vg_open(libh, vgname, "r");
372 * // do something with vg
378 * A list with entries of type struct lvm_str_list, containing the
379 * VG name strings of the Volume Groups known to the system.
380 * NULL is returned if unable to allocate memory.
381 * An empty list (verify with dm_list_empty) is returned if no VGs
382 * exist on the system.
384 struct dm_list
*lvm_list_vg_names(lvm_t libh
);
387 * Return the list of volume group uuids.
391 * The memory allocated for the list is tied to the lvm_t handle and will be
392 * released when lvm_quit() is called.
394 * NOTE: This function normally does not scan devices in the system for LVM
395 * metadata. To scan the system, use lvm_scan().
398 * Handle obtained from lvm_init().
401 * A list with entries of type struct lvm_str_list, containing the
402 * VG UUID strings of the Volume Groups known to the system.
403 * NULL is returned if unable to allocate memory.
404 * An empty list (verify with dm_list_empty) is returned if no VGs
405 * exist on the system.
407 struct dm_list
*lvm_list_vg_uuids(lvm_t libh
);
410 * Return the volume group name given a PV UUID
414 * The memory allocated for the name is tied to the lvm_t handle and will be
415 * released when lvm_quit() is called.
417 * NOTE: This function may scan devices in the system for LVM metadata.
420 * Handle obtained from lvm_init().
423 * The volume group name for the given PV UUID.
424 * NULL is returned if the PV UUID is not associated with a volume group.
426 const char *lvm_vgname_from_pvid(lvm_t libh
, const char *pvid
);
429 * Return the volume group name given a device name
433 * The memory allocated for the name is tied to the lvm_t handle and will be
434 * released when lvm_quit() is called.
436 * NOTE: This function may scan devices in the system for LVM metadata.
439 * Handle obtained from lvm_init().
442 * The volume group name for the given device name.
443 * NULL is returned if the device is not an LVM device.
446 const char *lvm_vgname_from_device(lvm_t libh
, const char *device
);
449 * Open an existing VG.
451 * Open a VG for reading or writing.
456 * Handle obtained from lvm_init().
459 * Name of the VG to open.
462 * Open mode - either "r" (read) or "w" (read/write).
463 * Any other character results in an error with EINVAL set.
466 * Open flags - currently ignored.
468 * \return non-NULL VG handle (success) or NULL (failure).
470 vg_t
lvm_vg_open(lvm_t libh
, const char *vgname
, const char *mode
,
474 * Create a VG with default parameters.
478 * This function creates a Volume Group object in memory.
479 * Upon success, other APIs may be used to set non-default parameters.
480 * For example, to set a non-default extent size, use lvm_vg_set_extent_size().
481 * Next, to add physical storage devices to the volume group, use
482 * lvm_vg_extend() for each device.
483 * Once all parameters are set appropriately and all devices are added to the
484 * VG, use lvm_vg_write() to commit the new VG to disk, and lvm_vg_close() to
485 * release the VG handle.
488 * Handle obtained from lvm_init().
491 * Name of the VG to open.
494 * non-NULL vg handle (success) or NULL (failure)
496 vg_t
lvm_vg_create(lvm_t libh
, const char *vg_name
);
498 /*************************** volume group handling **************************/
501 * Return a list of LV handles for a given VG handle.
506 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
509 * A list of lvm_lv_list structures containing lv handles for this vg.
510 * If no LVs exist on the given VG, NULL is returned.
512 struct dm_list
*lvm_vg_list_lvs(vg_t vg
);
515 * Return a list of PV handles for a given VG handle.
520 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
523 * A list of lvm_pv_list structures containing pv handles for this vg.
524 * If no PVs exist on the given VG, NULL is returned.
526 struct dm_list
*lvm_vg_list_pvs(vg_t vg
);
529 * Write a VG to disk.
533 * This function commits the Volume Group object referenced by the VG handle
534 * to disk. Upon failure, retry the operation and/or release the VG handle
535 * with lvm_vg_close().
538 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
541 * 0 (success) or -1 (failure).
543 int lvm_vg_write(vg_t vg
);
546 * Remove a VG from the system.
550 * This function removes a Volume Group object in memory, and requires
551 * calling lvm_vg_write() to commit the removal to disk.
554 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
557 * 0 (success) or -1 (failure).
559 int lvm_vg_remove(vg_t vg
);
562 * Close a VG opened with lvm_vg_create or lvm_vg_open().
566 * This function releases a VG handle and any resources associated with the
570 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
573 * 0 (success) or -1 (failure).
575 int lvm_vg_close(vg_t vg
);
578 * Extend a VG by adding a device.
582 * This function requires calling lvm_vg_write() to commit the change to disk.
583 * After successfully adding a device, use lvm_vg_write() to commit the new VG
584 * to disk. Upon failure, retry the operation or release the VG handle with
586 * If the device is not initialized for LVM use, it will be initialized
587 * before adding to the VG. Although some internal checks are done,
588 * the caller should be sure the device is not in use by other subsystems
589 * before calling lvm_vg_extend().
592 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
595 * Absolute pathname of device to add to VG.
598 * 0 (success) or -1 (failure).
600 int lvm_vg_extend(vg_t vg
, const char *device
);
603 * Reduce a VG by removing an unused device.
607 * This function requires calling lvm_vg_write() to commit the change to disk.
608 * After successfully removing a device, use lvm_vg_write() to commit the new VG
609 * to disk. Upon failure, retry the operation or release the VG handle with
613 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
616 * Name of device to remove from VG.
619 * 0 (success) or -1 (failure).
621 int lvm_vg_reduce(vg_t vg
, const char *device
);
628 * This function requires calling lvm_vg_write() to commit the change to disk.
629 * After successfully adding a tag, use lvm_vg_write() to commit the
630 * new VG to disk. Upon failure, retry the operation or release the VG handle
631 * with lvm_vg_close().
634 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
637 * Tag to add to the VG.
640 * 0 (success) or -1 (failure).
642 int lvm_vg_add_tag(vg_t vg
, const char *tag
);
645 * Remove a tag from a VG.
649 * This function requires calling lvm_vg_write() to commit the change to disk.
650 * After successfully removing a tag, use lvm_vg_write() to commit the
651 * new VG to disk. Upon failure, retry the operation or release the VG handle
652 * with lvm_vg_close().
655 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
658 * Tag to remove from VG.
661 * 0 (success) or -1 (failure).
663 int lvm_vg_remove_tag(vg_t vg
, const char *tag
);
666 * Set the extent size of a VG.
670 * This function requires calling lvm_vg_write() to commit the change to disk.
671 * After successfully setting a new extent size, use lvm_vg_write() to commit
672 * the new VG to disk. Upon failure, retry the operation or release the VG
673 * handle with lvm_vg_close().
676 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
679 * New extent size in bytes.
682 * 0 (success) or -1 (failure).
684 int lvm_vg_set_extent_size(vg_t vg
, uint32_t new_size
);
687 * Get whether or not a volume group is clustered.
692 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
695 * 1 if the VG is clustered, 0 if not
697 uint64_t lvm_vg_is_clustered(vg_t vg
);
700 * Get whether or not a volume group is exported.
705 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
708 * 1 if the VG is exported, 0 if not
710 uint64_t lvm_vg_is_exported(vg_t vg
);
713 * Get whether or not a volume group is a partial volume group.
717 * When one or more physical volumes belonging to the volume group
718 * are missing from the system the volume group is a partial volume
722 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
725 * 1 if the VG is PVs, 0 if not
727 uint64_t lvm_vg_is_partial(vg_t vg
);
730 * Get the current metadata sequence number of a volume group.
734 * The metadata sequence number is incrented for each metadata change.
735 * Applications may use the sequence number to determine if any LVM objects
736 * have changed from a prior query.
739 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
742 * Metadata sequence number.
744 uint64_t lvm_vg_get_seqno(const vg_t vg
);
747 * Get the current uuid of a volume group.
751 * The memory allocated for the uuid is tied to the vg_t handle and will be
752 * released when lvm_vg_close() is called.
755 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
758 * Copy of the uuid string.
760 const char *lvm_vg_get_uuid(const vg_t vg
);
763 * Get the current name of a volume group.
767 * The memory allocated for the name is tied to the vg_t handle and will be
768 * released when lvm_vg_close() is called.
771 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
776 const char *lvm_vg_get_name(const vg_t vg
);
779 * Get the current size in bytes of a volume group.
784 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
789 uint64_t lvm_vg_get_size(const vg_t vg
);
792 * Get the current unallocated space in bytes of a volume group.
797 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
800 * Free size in bytes.
802 uint64_t lvm_vg_get_free_size(const vg_t vg
);
805 * Get the current extent size in bytes of a volume group.
810 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
813 * Extent size in bytes.
815 uint64_t lvm_vg_get_extent_size(const vg_t vg
);
818 * Get the current number of total extents of a volume group.
823 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
828 uint64_t lvm_vg_get_extent_count(const vg_t vg
);
831 * Get the current number of free extents of a volume group.
836 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
841 uint64_t lvm_vg_get_free_extent_count(const vg_t vg
);
844 * Get the current number of physical volumes of a volume group.
849 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
852 * Physical volume count.
854 uint64_t lvm_vg_get_pv_count(const vg_t vg
);
857 * Get the maximum number of physical volumes allowed in a volume group.
862 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
865 * Maximum number of physical volumes allowed in a volume group.
867 uint64_t lvm_vg_get_max_pv(const vg_t vg
);
870 * Get the maximum number of logical volumes allowed in a volume group.
875 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
878 * Maximum number of logical volumes allowed in a volume group.
880 uint64_t lvm_vg_get_max_lv(const vg_t vg
);
883 * Return the list of volume group tags.
887 * The memory allocated for the list is tied to the vg_t handle and will be
888 * released when lvm_vg_close() is called.
890 * To process the list, use the dm_list iterator functions. For example:
892 * struct dm_list *tags;
893 * struct lvm_str_list *strl;
895 * tags = lvm_vg_get_tags(vg);
896 * dm_list_iterate_items(strl, tags) {
898 * // do something with tag
903 * A list with entries of type struct lvm_str_list, containing the
904 * tag strings attached to volume group.
905 * If no tags are attached to the given VG, an empty list is returned
906 * (check with dm_list_empty()).
907 * If there is a problem obtaining the list of tags, NULL is returned.
909 struct dm_list
*lvm_vg_get_tags(const vg_t vg
);
912 * Get the value of a VG property
917 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
920 * Name of property to query. See vgs man page for full list of properties
921 * that may be queried.
923 * The memory allocated for a string property value is tied to the vg_t
924 * handle and will be released when lvm_vg_close() is called.
927 * lvm_property_value v;
928 * char *prop_name = "vg_mda_count";
930 * v = lvm_vg_get_property(vg, prop_name);
932 * printf("Invalid property name or unable to query"
933 * "'%s', errno = %d.\n", prop_name, lvm_errno(libh));
937 * printf(", value = %s\n", v.value.string);
939 * printf(", value = %"PRIu64"\n", v.value.integer);
943 * lvm_property_value structure that will contain the current
944 * value of the property. Caller should check 'is_valid' flag before using
945 * the value. If 'is_valid' is not set, caller should check lvm_errno()
946 * for specific error.
948 struct lvm_property_value
lvm_vg_get_property(const vg_t vg
, const char *name
);
951 * Set the value of a VG property. Note that the property must be
952 * a 'settable' property, as evidenced by the 'is_settable' flag
953 * when querying the property.
957 * The memory allocated for a string property value is tied to the vg_t
958 * handle and will be released when lvm_vg_close() is called.
961 * lvm_property_value copies;
963 * if (lvm_vg_get_property(vg, "vg_mda_copies", &copies) < 0) {
964 * // Error - unable to query property
966 * if (!copies.is_settable) {
967 * // Error - property not settable
969 * copies.value.integer = 2;
970 * if (lvm_vg_set_property(vg, "vg_mda_copies", &copies) < 0) {
975 * 0 (success) or -1 (failure).
977 int lvm_vg_set_property(const vg_t vg
, const char *name
,
978 struct lvm_property_value
*value
);
980 /************************** logical volume handling *************************/
983 * Create a linear logical volume.
984 * This function commits the change to disk and does _not_ require calling
986 * NOTE: The commit behavior of this function is subject to change
987 * as the API is developed.
990 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
993 * Name of logical volume to create.
996 * Size of logical volume in extents.
999 * non-NULL handle to an LV object created, or NULL if creation fails.
1002 lv_t
lvm_vg_create_lv_linear(vg_t vg
, const char *name
, uint64_t size
);
1005 * Return a list of lvseg handles for a given LV handle.
1010 * Logical volume handle.
1013 * A list of lvm_lvseg_list structures containing lvseg handles for this lv.
1015 struct dm_list
*lvm_lv_list_lvsegs(lv_t lv
);
1018 * Lookup an LV handle in a VG by the LV name.
1023 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
1026 * Name of LV to lookup.
1029 * non-NULL handle to the LV 'name' attached to the VG.
1030 * NULL is returned if the LV name is not associated with the VG handle.
1032 lv_t
lvm_lv_from_name(vg_t vg
, const char *name
);
1035 * Lookup an LV handle in a VG by the LV uuid.
1036 * The form of the uuid may be either the formatted, human-readable form,
1037 * or the non-formatted form.
1042 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
1045 * UUID of LV to lookup.
1048 * non-NULL handle to the LV with 'uuid' attached to the VG.
1049 * NULL is returned if the LV uuid is not associated with the VG handle.
1051 lv_t
lvm_lv_from_uuid(vg_t vg
, const char *uuid
);
1054 * Activate a logical volume.
1058 * This function is the equivalent of the lvm command "lvchange -ay".
1060 * NOTE: This function cannot currently handle LVs with an in-progress pvmove or
1064 * Logical volume handle.
1067 * 0 (success) or -1 (failure).
1069 int lvm_lv_activate(lv_t lv
);
1072 * Deactivate a logical volume.
1076 * This function is the equivalent of the lvm command "lvchange -an".
1079 * Logical volume handle.
1082 * 0 (success) or -1 (failure).
1084 int lvm_lv_deactivate(lv_t lv
);
1087 * Remove a logical volume from a volume group.
1091 * This function commits the change to disk and does _not_ require calling
1093 * NOTE: The commit behavior of this function is subject to change
1094 * as the API is developed.
1095 * Currently only removing linear LVs are possible.
1098 * Logical volume handle.
1101 * 0 (success) or -1 (failure).
1103 int lvm_vg_remove_lv(lv_t lv
);
1106 * Get the current name of a logical volume.
1110 * The memory allocated for the uuid is tied to the vg_t handle and will be
1111 * released when lvm_vg_close() is called.
1114 * Logical volume handle.
1117 * Copy of the uuid string.
1119 const char *lvm_lv_get_uuid(const lv_t lv
);
1122 * Get the current uuid of a logical volume.
1126 * The memory allocated for the name is tied to the vg_t handle and will be
1127 * released when lvm_vg_close() is called.
1130 * Logical volume handle.
1135 const char *lvm_lv_get_name(const lv_t lv
);
1138 * Get the current size in bytes of a logical volume.
1143 * Logical volume handle.
1148 uint64_t lvm_lv_get_size(const lv_t lv
);
1151 * Get the value of a LV property
1156 * Logical volume handle.
1159 * Name of property to query. See lvs man page for full list of properties
1160 * that may be queried.
1162 * The memory allocated for a string property value is tied to the vg_t
1163 * handle and will be released when lvm_vg_close() is called.
1166 * lvm_property_value v;
1167 * char *prop_name = "seg_count";
1169 * v = lvm_lv_get_property(lv, prop_name);
1170 * if (!v.is_valid) {
1171 * printf("Invalid property name or unable to query"
1172 * "'%s', errno = %d.\n", prop_name, lvm_errno(libh));
1176 * printf(", value = %s\n", v.value.string);
1178 * printf(", value = %"PRIu64"\n", v.value.integer);
1181 * lvm_property_value structure that will contain the current
1182 * value of the property. Caller should check 'is_valid' flag before using
1183 * the value. If 'is_valid' is not set, caller should check lvm_errno()
1184 * for specific error.
1186 struct lvm_property_value
lvm_lv_get_property(const lv_t lv
, const char *name
);
1189 * Get the value of a LV segment property
1194 * Logical volume segment handle.
1197 * Name of property to query. See lvs man page for full list of properties
1198 * that may be queried.
1200 * The memory allocated for a string property value is tied to the vg_t
1201 * handle and will be released when lvm_vg_close() is called.
1204 * lvm_property_value v;
1205 * char *prop_name = "seg_start_pe";
1207 * v = lvm_lvseg_get_property(lvseg, prop_name);
1208 * if (lvm_errno(libh) || !v.is_valid) {
1210 * printf("Invalid property name or unable to query"
1211 * "'%s'.\n", prop_name);
1215 * printf(", value = %s\n", v.value.string);
1217 * printf(", value = %"PRIu64"\n", v.value.integer);
1220 * lvm_property_value structure that will contain the current
1221 * value of the property. Caller should check lvm_errno() as well
1222 * as 'is_valid' flag before using the value.
1224 struct lvm_property_value
lvm_lvseg_get_property(const lvseg_t lvseg
,
1228 * Get the current activation state of a logical volume.
1233 * Logical volume handle.
1236 * 1 if the LV is active in the kernel, 0 if not
1238 uint64_t lvm_lv_is_active(const lv_t lv
);
1241 * Get the current suspended state of a logical volume.
1246 * Logical volume handle.
1249 * 1 if the LV is suspended in the kernel, 0 if not
1251 uint64_t lvm_lv_is_suspended(const lv_t lv
);
1254 * Add a tag to an LV.
1258 * This function requires calling lvm_vg_write() to commit the change to disk.
1259 * After successfully adding a tag, use lvm_vg_write() to commit the
1260 * new VG to disk. Upon failure, retry the operation or release the VG handle
1261 * with lvm_vg_close().
1264 * Logical volume handle.
1267 * Tag to add to an LV.
1270 * 0 (success) or -1 (failure).
1272 int lvm_lv_add_tag(lv_t lv
, const char *tag
);
1275 * Remove a tag from an LV.
1279 * This function requires calling lvm_vg_write() to commit the change to disk.
1280 * After successfully removing a tag, use lvm_vg_write() to commit the
1281 * new VG to disk. Upon failure, retry the operation or release the VG handle
1282 * with lvm_vg_close().
1285 * Logical volume handle.
1288 * Tag to remove from LV.
1291 * 0 (success) or -1 (failure).
1293 int lvm_lv_remove_tag(lv_t lv
, const char *tag
);
1296 * Return the list of logical volume tags.
1300 * The memory allocated for the list is tied to the vg_t handle and will be
1301 * released when lvm_vg_close() is called.
1303 * To process the list, use the dm_list iterator functions. For example:
1305 * struct dm_list *tags;
1306 * struct lvm_str_list *strl;
1308 * tags = lvm_lv_get_tags(lv);
1309 * dm_list_iterate_items(strl, tags) {
1311 * // do something with tag
1316 * A list with entries of type struct lvm_str_list, containing the
1317 * tag strings attached to volume group.
1318 * If no tags are attached to the LV, an empty list is returned
1319 * (check with dm_list_empty()).
1320 * If there is a problem obtaining the list of tags, NULL is returned.
1322 struct dm_list
*lvm_lv_get_tags(const lv_t lv
);
1326 * Resize logical volume to new_size bytes.
1330 * NOTE: This function is currently not implemented.
1333 * Logical volume handle.
1336 * New size in bytes.
1339 * 0 (success) or -1 (failure).
1342 int lvm_lv_resize(const lv_t lv
, uint64_t new_size
);
1344 /************************** physical volume handling ************************/
1347 * Physical volume handling should not be needed anymore. Only physical volumes
1348 * bound to a vg contain useful information. Therefore the creation,
1349 * modification and the removal of orphan physical volumes is not suported.
1353 * Get the current uuid of a physical volume.
1357 * The memory allocated for the uuid is tied to the vg_t handle and will be
1358 * released when lvm_vg_close() is called.
1361 * Physical volume handle.
1364 * Copy of the uuid string.
1366 const char *lvm_pv_get_uuid(const pv_t pv
);
1369 * Get the current name of a physical volume.
1373 * The memory allocated for the name is tied to the vg_t handle and will be
1374 * released when lvm_vg_close() is called.
1377 * Physical volume handle.
1382 const char *lvm_pv_get_name(const pv_t pv
);
1385 * Get the current number of metadata areas in the physical volume.
1390 * Physical volume handle.
1393 * Number of metadata areas in the PV.
1395 uint64_t lvm_pv_get_mda_count(const pv_t pv
);
1398 * Get the current size in bytes of a device underlying a
1404 * Physical volume handle.
1409 uint64_t lvm_pv_get_dev_size(const pv_t pv
);
1412 * Get the current size in bytes of a physical volume.
1417 * Physical volume handle.
1422 uint64_t lvm_pv_get_size(const pv_t pv
);
1425 * Get the current unallocated space in bytes of a physical volume.
1430 * Physical volume handle.
1433 * Free size in bytes.
1435 uint64_t lvm_pv_get_free(const pv_t pv
);
1438 * Get the value of a PV property
1443 * Physical volume handle.
1446 * Name of property to query. See pvs man page for full list of properties
1447 * that may be queried.
1449 * The memory allocated for a string property value is tied to the vg_t handle
1450 * and will be released when lvm_vg_close() is called. For "percent" values
1451 * (those obtained for copy_percent and snap_percent properties), please see
1452 * percent_range_t and lvm_percent_to_float().
1455 * lvm_property_value value;
1456 * char *prop_name = "pv_mda_count";
1458 * v = lvm_pv_get_property(pv, prop_name);
1459 * if (!v.is_valid) {
1460 * printf("Invalid property name or unable to query"
1461 * "'%s', errno = %d.\n", prop_name, lvm_errno(libh));
1465 * printf(", value = %s\n", v.value.string);
1467 * printf(", value = %"PRIu64"\n", v.value.integer);
1470 * lvm_property_value structure that will contain the current
1471 * value of the property. Caller should check 'is_valid' flag before using
1472 * the value. If 'is_valid' is not set, caller should check lvm_errno()
1473 * for specific error.
1475 struct lvm_property_value
lvm_pv_get_property(const pv_t pv
, const char *name
);
1478 * Get the value of a PV segment property
1483 * Physical volume segment handle.
1486 * Name of property to query. See pvs man page for full list of properties
1487 * that may be queried.
1489 * The memory allocated for a string property value is tied to the vg_t
1490 * handle and will be released when lvm_vg_close() is called.
1493 * lvm_property_value v;
1494 * char *prop_name = "pvseg_start";
1496 * v = lvm_pvseg_get_property(pvseg, prop_name);
1497 * if (lvm_errno(libh) || !v.is_valid) {
1499 * printf("Invalid property name or unable to query"
1500 * "'%s'.\n", prop_name);
1504 * printf(", value = %s\n", v.value.string);
1506 * printf(", value = %"PRIu64"\n", v.value.integer);
1509 * lvm_property_value structure that will contain the current
1510 * value of the property. Caller should check lvm_errno() as well
1511 * as 'is_valid' flag before using the value.
1513 struct lvm_property_value
lvm_pvseg_get_property(const pvseg_t pvseg
,
1517 * Return a list of pvseg handles for a given PV handle.
1522 * Physical volume handle.
1525 * A list of lvm_pvseg_list structures containing pvseg handles for this pv.
1527 struct dm_list
*lvm_pv_list_pvsegs(pv_t pv
);
1530 * Lookup an PV handle in a VG by the PV name.
1535 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
1538 * Name of PV to lookup.
1541 * non-NULL handle to the PV 'name' attached to the VG.
1542 * NULL is returned if the PV name is not associated with the VG handle.
1544 pv_t
lvm_pv_from_name(vg_t vg
, const char *name
);
1547 * Lookup an PV handle in a VG by the PV uuid.
1548 * The form of the uuid may be either the formatted, human-readable form,
1549 * or the non-formatted form.
1554 * VG handle obtained from lvm_vg_create() or lvm_vg_open().
1557 * UUID of PV to lookup.
1560 * non-NULL handle to the PV with 'uuid' attached to the VG.
1561 * NULL is returned if the PV uuid is not associated with the VG handle.
1563 pv_t
lvm_pv_from_uuid(vg_t vg
, const char *uuid
);
1566 * Resize physical volume to new_size bytes.
1570 * NOTE: This function is currently not implemented.
1573 * Physical volume handle.
1576 * New size in bytes.
1579 * 0 (success) or -1 (failure).
1581 int lvm_pv_resize(const pv_t pv
, uint64_t new_size
);
1583 #ifndef _LVM_PERCENT_H
1586 * This type defines a couple of special percent values. The PERCENT_0 and
1587 * PERCENT_100 constants designate *exact* percentages: values are never
1588 * rounded to either of these two.
1592 PERCENT_1
= 1000000,
1593 PERCENT_100
= 100 * PERCENT_1
,
1594 PERCENT_INVALID
= -1,
1595 PERCENT_MERGE_FAILED
= -2
1598 typedef int32_t percent_t
;
1603 * Convert a (fixed-point) value obtained from the percent-denominated
1604 * *_get_property functions into a floating-point value.
1606 float lvm_percent_to_float(percent_t v
);
1611 #endif /* _LIB_LVM2APP_H */
This page took 0.103033 seconds and 5 git commands to generate.