]>
Commit | Line | Data |
---|---|---|
5f4b7a26 | 1 | /* |
0d23926e | 2 | * Copyright (C) 2008,2009,2010 Red Hat, Inc. All rights reserved. |
5f4b7a26 TW |
3 | * |
4 | * This file is part of LVM2. | |
5 | * | |
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. | |
9 | * | |
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 | |
13 | */ | |
9e813cc9 AK |
14 | #ifndef _LIB_LVM2APP_H |
15 | #define _LIB_LVM2APP_H | |
5f4b7a26 | 16 | |
2d696f9e | 17 | #include <libdevmapper.h> |
5f4b7a26 TW |
18 | |
19 | #include <stdint.h> | |
20 | ||
c9c7d25c MB |
21 | #ifdef __cplusplus |
22 | extern "C" { | |
23 | #endif | |
d4b31197 | 24 | |
88e3ced7 DW |
25 | /******************************** WARNING *********************************** |
26 | * | |
d4b31197 DW |
27 | * NOTE: This API is under development and subject to change at any time. |
28 | * | |
29 | * Please send feedback to lvm-devel@redhat.com | |
88e3ced7 DW |
30 | * |
31 | *********************************** WARNING ********************************/ | |
32 | ||
33 | /*************************** Design Overview ********************************/ | |
34 | ||
1df7ef9a DW |
35 | /** |
36 | * \mainpage LVM library API | |
37 | * | |
88e3ced7 | 38 | * The API is designed around the following basic LVM objects: |
3fe35b32 | 39 | * 1) Physical Volume (pv_t) 2) Volume Group (vg_t) 3) Logical Volume (lv_t). |
88e3ced7 DW |
40 | * |
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. | |
46 | * | |
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 | |
3fe35b32 DW |
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. | |
88e3ced7 DW |
52 | * |
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. | |
9ac1af71 DW |
56 | * |
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. | |
d4b31197 | 67 | */ |
d4b31197 | 68 | |
f7bc94ac DW |
69 | /** |
70 | * Retrieve the library version. | |
71 | * | |
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)". | |
79 | * | |
80 | * \return A string describing the library version. | |
81 | */ | |
82 | const char *lvm_library_get_version(void); | |
d4b31197 | 83 | |
5ed93950 DW |
84 | /******************************** structures ********************************/ |
85 | ||
42a871b3 DW |
86 | /** |
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. | |
93 | */ | |
5ed93950 | 94 | struct lvm; |
39d6ccdf | 95 | struct physical_volume; |
5ed93950 | 96 | struct volume_group; |
39d6ccdf | 97 | struct logical_volume; |
ecc51116 | 98 | struct lv_segment; |
b2b27cd7 | 99 | struct pv_segment; |
39d6ccdf | 100 | |
5ed93950 | 101 | /** |
3fe35b32 | 102 | * \class lvm_t |
5ed93950 | 103 | * |
42a871b3 DW |
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 | |
8e3da446 | 107 | * lvm_errno()) and error message (see lvm_errmsg()) that any function may |
42a871b3 | 108 | * generate. |
5ed93950 DW |
109 | */ |
110 | typedef struct lvm *lvm_t; | |
111 | ||
5ed93950 | 112 | /** |
3fe35b32 | 113 | * \class vg_t |
5ed93950 | 114 | * |
3fe35b32 DW |
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. | |
5ed93950 | 120 | */ |
7510963f | 121 | typedef struct volume_group *vg_t; |
5ed93950 DW |
122 | |
123 | /** | |
3fe35b32 | 124 | * \class lv_t |
5ed93950 | 125 | * |
3fe35b32 DW |
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(). | |
5ed93950 | 129 | */ |
5d370b1b | 130 | typedef struct logical_volume *lv_t; |
357ed599 | 131 | |
5ed93950 | 132 | /** |
3fe35b32 | 133 | * \class pv_t |
5ed93950 | 134 | * |
3fe35b32 DW |
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(). | |
5ed93950 | 138 | */ |
e0e7fb84 | 139 | typedef struct physical_volume *pv_t; |
357ed599 | 140 | |
ecc51116 PR |
141 | /** |
142 | * \class lvseg_t | |
143 | * | |
144 | * This lv segment object is bound to a lv_t. | |
145 | */ | |
146 | typedef struct lv_segment *lvseg_t; | |
147 | ||
b2b27cd7 PR |
148 | /** |
149 | * \class pvseg_t | |
150 | * | |
151 | * This pv segment object is bound to a pv_t. | |
152 | */ | |
153 | typedef struct pv_segment *pvseg_t; | |
154 | ||
5ed93950 | 155 | /** |
42a871b3 | 156 | * Logical Volume object list. |
5ed93950 | 157 | * |
3c1febe0 | 158 | * Lists of these structures are returned by lvm_vg_list_lvs(). |
5ed93950 | 159 | */ |
42a871b3 | 160 | typedef struct lvm_lv_list { |
5ed93950 | 161 | struct dm_list list; |
5d370b1b | 162 | lv_t lv; |
42a871b3 | 163 | } lv_list_t; |
5ed93950 | 164 | |
ecc51116 PR |
165 | /** |
166 | * Logical Volume Segment object list. | |
167 | * | |
168 | * Lists of these structures are returned by lvm_lv_list_lvsegs(). | |
169 | */ | |
170 | typedef struct lvm_lvseg_list { | |
171 | struct dm_list list; | |
172 | lvseg_t lvseg; | |
173 | } lvseg_list_t; | |
174 | ||
5ed93950 | 175 | /** |
42a871b3 | 176 | * Physical volume object list. |
5ed93950 | 177 | * |
3fe35b32 | 178 | * Lists of these structures are returned by lvm_vg_list_pvs(). |
5ed93950 | 179 | */ |
42a871b3 | 180 | typedef struct lvm_pv_list { |
357ed599 | 181 | struct dm_list list; |
e0e7fb84 | 182 | pv_t pv; |
42a871b3 | 183 | } pv_list_t; |
357ed599 | 184 | |
b2b27cd7 PR |
185 | /** |
186 | * Physical Volume Segment object list. | |
187 | * | |
188 | * Lists of these structures are returned by lvm_pv_list_pvsegs(). | |
189 | */ | |
190 | typedef struct lvm_pvseg_list { | |
191 | struct dm_list list; | |
192 | pvseg_t pvseg; | |
193 | } pvseg_list_t; | |
194 | ||
5ed93950 DW |
195 | /** |
196 | * String list. | |
197 | * | |
198 | * This string list contains read-only strings. | |
3fe35b32 DW |
199 | * Lists of these structures are returned by functions such as |
200 | * lvm_list_vg_names() and lvm_list_vg_uuids(). | |
5ed93950 | 201 | */ |
a8ab5867 | 202 | typedef struct lvm_str_list { |
122ccd0d DW |
203 | struct dm_list list; |
204 | const char *str; | |
a8ab5867 | 205 | } lvm_str_list_t; |
122ccd0d | 206 | |
3c1febe0 DW |
207 | /** |
208 | * Property Value | |
209 | * | |
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(). | |
213 | * | |
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) | |
218 | */ | |
219 | typedef struct lvm_property_value { | |
220 | uint32_t is_settable:1; | |
221 | uint32_t is_string:1; | |
222 | uint32_t is_integer:1; | |
223 | uint32_t is_valid:1; | |
224 | uint32_t padding:28; | |
225 | union { | |
226 | const char *string; | |
227 | uint64_t integer; | |
228 | } value; | |
229 | } lvm_property_value_t; | |
230 | ||
5ed93950 | 231 | /*************************** generic lvm handling ***************************/ |
5f4b7a26 TW |
232 | /** |
233 | * Create a LVM handle. | |
234 | * | |
3fe35b32 DW |
235 | * \memberof lvm_t |
236 | * | |
8e3da446 | 237 | * Once all LVM operations have been completed, use lvm_quit() to release |
930a1434 DW |
238 | * the handle and any associated resources. |
239 | * | |
f4edfec7 DW |
240 | * \param system_dir |
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. | |
244 | * | |
245 | * \return | |
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 | |
8e3da446 | 248 | * with the lvm_error() function. |
f4edfec7 | 249 | */ |
9c2e73fd | 250 | lvm_t lvm_init(const char *system_dir); |
5f4b7a26 TW |
251 | |
252 | /** | |
3fe35b32 DW |
253 | * Destroy a LVM handle allocated with lvm_init(). |
254 | * | |
255 | * \memberof lvm_t | |
5f4b7a26 | 256 | * |
42a871b3 DW |
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. | |
261 | * | |
5f4b7a26 | 262 | * \param libh |
3fe35b32 | 263 | * Handle obtained from lvm_init(). |
5f4b7a26 | 264 | */ |
9c2e73fd | 265 | void lvm_quit(lvm_t libh); |
5f4b7a26 TW |
266 | |
267 | /** | |
268 | * Reload the original configuration from the system directory. | |
269 | * | |
3fe35b32 DW |
270 | * \memberof lvm_t |
271 | * | |
42a871b3 DW |
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 | |
274 | * the application. | |
93e025dc | 275 | * |
5f4b7a26 | 276 | * \param libh |
3fe35b32 | 277 | * Handle obtained from lvm_init(). |
f4edfec7 DW |
278 | * |
279 | * \return | |
280 | * 0 (success) or -1 (failure). | |
5f4b7a26 | 281 | */ |
f6b1eaf7 | 282 | int lvm_config_reload(lvm_t libh); |
5f4b7a26 | 283 | |
dce56c97 DW |
284 | /** |
285 | * Override the LVM configuration with a configuration string. | |
286 | * | |
3fe35b32 DW |
287 | * \memberof lvm_t |
288 | * | |
42a871b3 | 289 | * This function is equivalent to the --config option on lvm commands. |
dce56c97 | 290 | * Once this API has been used to over-ride the configuration, |
3fe35b32 | 291 | * use lvm_config_reload() to apply the new settings. |
42a871b3 | 292 | * |
dce56c97 | 293 | * \param libh |
3fe35b32 | 294 | * Handle obtained from lvm_init(). |
f4edfec7 | 295 | * |
42a871b3 | 296 | * \param config_string |
f4edfec7 DW |
297 | * LVM configuration string to apply. See the lvm.conf file man page |
298 | * for the format of the config string. | |
299 | * | |
300 | * \return | |
301 | * 0 (success) or -1 (failure). | |
dce56c97 DW |
302 | */ |
303 | int lvm_config_override(lvm_t libh, const char *config_string); | |
304 | ||
7a35a9f5 | 305 | /** |
93e025dc | 306 | * Return stored error no describing last LVM API error. |
7a35a9f5 | 307 | * |
3fe35b32 DW |
308 | * \memberof lvm_t |
309 | * | |
42a871b3 DW |
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 | |
316 | * returns a value. | |
7a35a9f5 | 317 | * |
93e025dc | 318 | * \param libh |
3fe35b32 | 319 | * Handle obtained from lvm_init(). |
7a35a9f5 | 320 | * |
f4edfec7 DW |
321 | * \return |
322 | * An errno value describing the last LVM error. | |
93e025dc DW |
323 | */ |
324 | int lvm_errno(lvm_t libh); | |
325 | ||
326 | /** | |
327 | * Return stored error message describing last LVM error. | |
328 | * | |
3fe35b32 DW |
329 | * \memberof lvm_t |
330 | * | |
8e3da446 | 331 | * This function may be used in conjunction with lvm_errno() to obtain more |
42a871b3 DW |
332 | * specific error information for a function that is known to have failed. |
333 | * | |
93e025dc | 334 | * \param libh |
3fe35b32 | 335 | * Handle obtained from lvm_init(). |
7a35a9f5 | 336 | * |
f4edfec7 DW |
337 | * \return |
338 | * An error string describing the last LVM error. | |
7a35a9f5 | 339 | */ |
93e025dc | 340 | const char *lvm_errmsg(lvm_t libh); |
7a35a9f5 | 341 | |
8bcb9683 | 342 | /** |
93e025dc | 343 | * Scan all devices on the system for VGs and LVM metadata. |
8bcb9683 | 344 | * |
3fe35b32 DW |
345 | * \memberof lvm_t |
346 | * | |
f4edfec7 DW |
347 | * \return |
348 | * 0 (success) or -1 (failure). | |
8bcb9683 | 349 | */ |
2572832e | 350 | int lvm_scan(lvm_t libh); |
93e025dc | 351 | |
a0b1b187 | 352 | /** |
93e025dc | 353 | * Return the list of volume group names. |
a0b1b187 | 354 | * |
3fe35b32 DW |
355 | * \memberof lvm_t |
356 | * | |
0589e19f | 357 | * The memory allocated for the list is tied to the lvm_t handle and will be |
8e3da446 | 358 | * released when lvm_quit() is called. |
0589e19f | 359 | * |
42a871b3 | 360 | * NOTE: This function normally does not scan devices in the system for LVM |
8e3da446 | 361 | * metadata. To scan the system, use lvm_scan(). |
93e025dc DW |
362 | * |
363 | * To process the list, use the dm_list iterator functions. For example: | |
7510963f | 364 | * vg_t vg; |
93e025dc DW |
365 | * struct dm_list *vgnames; |
366 | * struct lvm_str_list *strl; | |
367 | * | |
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 | |
373 | * lvm_vg_close(vg); | |
374 | * } | |
375 | * | |
376 | * | |
f4edfec7 DW |
377 | * \return |
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. | |
93e025dc DW |
383 | */ |
384 | struct dm_list *lvm_list_vg_names(lvm_t libh); | |
385 | ||
386 | /** | |
387 | * Return the list of volume group uuids. | |
388 | * | |
3fe35b32 DW |
389 | * \memberof lvm_t |
390 | * | |
0589e19f | 391 | * The memory allocated for the list is tied to the lvm_t handle and will be |
8e3da446 | 392 | * released when lvm_quit() is called. |
0589e19f | 393 | * |
42a871b3 | 394 | * NOTE: This function normally does not scan devices in the system for LVM |
8e3da446 | 395 | * metadata. To scan the system, use lvm_scan(). |
a0b1b187 DW |
396 | * |
397 | * \param libh | |
3fe35b32 | 398 | * Handle obtained from lvm_init(). |
a0b1b187 | 399 | * |
f4edfec7 DW |
400 | * \return |
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. | |
a0b1b187 | 406 | */ |
93e025dc | 407 | struct dm_list *lvm_list_vg_uuids(lvm_t libh); |
a0b1b187 | 408 | |
0d23926e DW |
409 | /** |
410 | * Return the volume group name given a PV UUID | |
411 | * | |
412 | * \memberof lvm_t | |
413 | * | |
414 | * The memory allocated for the name is tied to the lvm_t handle and will be | |
8e3da446 | 415 | * released when lvm_quit() is called. |
0d23926e DW |
416 | * |
417 | * NOTE: This function may scan devices in the system for LVM metadata. | |
418 | * | |
419 | * \param libh | |
420 | * Handle obtained from lvm_init(). | |
421 | * | |
422 | * \return | |
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. | |
425 | */ | |
426 | const char *lvm_vgname_from_pvid(lvm_t libh, const char *pvid); | |
427 | ||
428 | /** | |
429 | * Return the volume group name given a device name | |
430 | * | |
431 | * \memberof lvm_t | |
432 | * | |
433 | * The memory allocated for the name is tied to the lvm_t handle and will be | |
8e3da446 | 434 | * released when lvm_quit() is called. |
0d23926e DW |
435 | * |
436 | * NOTE: This function may scan devices in the system for LVM metadata. | |
437 | * | |
438 | * \param libh | |
439 | * Handle obtained from lvm_init(). | |
440 | * | |
441 | * \return | |
442 | * The volume group name for the given device name. | |
443 | * NULL is returned if the device is not an LVM device. | |
444 | * | |
445 | */ | |
446 | const char *lvm_vgname_from_device(lvm_t libh, const char *device); | |
447 | ||
a0b1b187 | 448 | /** |
93e025dc DW |
449 | * Open an existing VG. |
450 | * | |
451 | * Open a VG for reading or writing. | |
a0b1b187 | 452 | * |
3fe35b32 DW |
453 | * \memberof lvm_t |
454 | * | |
a0b1b187 | 455 | * \param libh |
3fe35b32 | 456 | * Handle obtained from lvm_init(). |
f4edfec7 | 457 | * |
93e025dc | 458 | * \param vgname |
f4edfec7 DW |
459 | * Name of the VG to open. |
460 | * | |
93e025dc | 461 | * \param mode |
f4edfec7 DW |
462 | * Open mode - either "r" (read) or "w" (read/write). |
463 | * Any other character results in an error with EINVAL set. | |
464 | * | |
93e025dc | 465 | * \param flags |
f4edfec7 DW |
466 | * Open flags - currently ignored. |
467 | * | |
93e025dc | 468 | * \return non-NULL VG handle (success) or NULL (failure). |
a0b1b187 | 469 | */ |
7510963f | 470 | vg_t lvm_vg_open(lvm_t libh, const char *vgname, const char *mode, |
93e025dc | 471 | uint32_t flags); |
a0b1b187 | 472 | |
930a1434 DW |
473 | /** |
474 | * Create a VG with default parameters. | |
475 | * | |
3fe35b32 DW |
476 | * \memberof lvm_t |
477 | * | |
42a871b3 | 478 | * This function creates a Volume Group object in memory. |
930a1434 | 479 | * Upon success, other APIs may be used to set non-default parameters. |
3fe35b32 | 480 | * For example, to set a non-default extent size, use lvm_vg_set_extent_size(). |
930a1434 | 481 | * Next, to add physical storage devices to the volume group, use |
3fe35b32 | 482 | * lvm_vg_extend() for each device. |
930a1434 | 483 | * Once all parameters are set appropriately and all devices are added to the |
3fe35b32 | 484 | * VG, use lvm_vg_write() to commit the new VG to disk, and lvm_vg_close() to |
930a1434 DW |
485 | * release the VG handle. |
486 | * | |
487 | * \param libh | |
3fe35b32 | 488 | * Handle obtained from lvm_init(). |
f4edfec7 | 489 | * |
93e025dc | 490 | * \param vg_name |
f4edfec7 DW |
491 | * Name of the VG to open. |
492 | * | |
493 | * \return | |
494 | * non-NULL vg handle (success) or NULL (failure) | |
930a1434 | 495 | */ |
7510963f | 496 | vg_t lvm_vg_create(lvm_t libh, const char *vg_name); |
930a1434 | 497 | |
3fe35b32 DW |
498 | /*************************** volume group handling **************************/ |
499 | ||
500 | /** | |
501 | * Return a list of LV handles for a given VG handle. | |
502 | * | |
503 | * \memberof vg_t | |
504 | * | |
505 | * \param vg | |
8e3da446 | 506 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
3fe35b32 DW |
507 | * |
508 | * \return | |
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. | |
511 | */ | |
512 | struct dm_list *lvm_vg_list_lvs(vg_t vg); | |
513 | ||
514 | /** | |
515 | * Return a list of PV handles for a given VG handle. | |
516 | * | |
517 | * \memberof vg_t | |
518 | * | |
519 | * \param vg | |
8e3da446 | 520 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
3fe35b32 DW |
521 | * |
522 | * \return | |
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. | |
525 | */ | |
526 | struct dm_list *lvm_vg_list_pvs(vg_t vg); | |
527 | ||
528 | /** | |
93e025dc DW |
529 | * Write a VG to disk. |
530 | * | |
3fe35b32 DW |
531 | * \memberof vg_t |
532 | * | |
42a871b3 DW |
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 | |
3fe35b32 | 535 | * with lvm_vg_close(). |
93e025dc DW |
536 | * |
537 | * \param vg | |
8e3da446 | 538 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
539 | * |
540 | * \return | |
541 | * 0 (success) or -1 (failure). | |
93e025dc | 542 | */ |
7510963f | 543 | int lvm_vg_write(vg_t vg); |
93e025dc DW |
544 | |
545 | /** | |
546 | * Remove a VG from the system. | |
547 | * | |
3fe35b32 DW |
548 | * \memberof vg_t |
549 | * | |
a5609e30 | 550 | * This function removes a Volume Group object in memory, and requires |
3fe35b32 | 551 | * calling lvm_vg_write() to commit the removal to disk. |
93e025dc DW |
552 | * |
553 | * \param vg | |
8e3da446 | 554 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
555 | * |
556 | * \return | |
557 | * 0 (success) or -1 (failure). | |
93e025dc | 558 | */ |
7510963f | 559 | int lvm_vg_remove(vg_t vg); |
93e025dc DW |
560 | |
561 | /** | |
3fe35b32 DW |
562 | * Close a VG opened with lvm_vg_create or lvm_vg_open(). |
563 | * | |
564 | * \memberof vg_t | |
93e025dc | 565 | * |
42a871b3 DW |
566 | * This function releases a VG handle and any resources associated with the |
567 | * handle. | |
93e025dc DW |
568 | * |
569 | * \param vg | |
8e3da446 | 570 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
571 | * |
572 | * \return | |
573 | * 0 (success) or -1 (failure). | |
93e025dc | 574 | */ |
7510963f | 575 | int lvm_vg_close(vg_t vg); |
93e025dc | 576 | |
930a1434 DW |
577 | /** |
578 | * Extend a VG by adding a device. | |
579 | * | |
3fe35b32 DW |
580 | * \memberof vg_t |
581 | * | |
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 | |
930a1434 | 584 | * to disk. Upon failure, retry the operation or release the VG handle with |
3fe35b32 | 585 | * lvm_vg_close(). |
bae6bc62 DW |
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 | |
8e3da446 | 589 | * before calling lvm_vg_extend(). |
930a1434 DW |
590 | * |
591 | * \param vg | |
8e3da446 | 592 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 | 593 | * |
930a1434 | 594 | * \param device |
f4edfec7 DW |
595 | * Absolute pathname of device to add to VG. |
596 | * | |
597 | * \return | |
598 | * 0 (success) or -1 (failure). | |
930a1434 | 599 | */ |
7510963f | 600 | int lvm_vg_extend(vg_t vg, const char *device); |
dfe213f8 DW |
601 | |
602 | /** | |
603 | * Reduce a VG by removing an unused device. | |
604 | * | |
3fe35b32 DW |
605 | * \memberof vg_t |
606 | * | |
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 | |
dfe213f8 | 609 | * to disk. Upon failure, retry the operation or release the VG handle with |
3fe35b32 | 610 | * lvm_vg_close(). |
dfe213f8 DW |
611 | * |
612 | * \param vg | |
8e3da446 | 613 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
dfe213f8 DW |
614 | * |
615 | * \param device | |
f4edfec7 | 616 | * Name of device to remove from VG. |
dfe213f8 | 617 | * |
f4edfec7 DW |
618 | * \return |
619 | * 0 (success) or -1 (failure). | |
dfe213f8 | 620 | */ |
7510963f | 621 | int lvm_vg_reduce(vg_t vg, const char *device); |
930a1434 | 622 | |
a8ab5867 | 623 | /** |
3fe35b32 DW |
624 | * Add a tag to a VG. |
625 | * | |
626 | * \memberof vg_t | |
a8ab5867 | 627 | * |
3fe35b32 DW |
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 | |
a8ab5867 | 630 | * new VG to disk. Upon failure, retry the operation or release the VG handle |
3fe35b32 | 631 | * with lvm_vg_close(). |
a8ab5867 DW |
632 | * |
633 | * \param vg | |
8e3da446 | 634 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
a8ab5867 DW |
635 | * |
636 | * \param tag | |
3fe35b32 | 637 | * Tag to add to the VG. |
a8ab5867 DW |
638 | * |
639 | * \return | |
640 | * 0 (success) or -1 (failure). | |
641 | */ | |
642 | int lvm_vg_add_tag(vg_t vg, const char *tag); | |
3fe35b32 DW |
643 | |
644 | /** | |
645 | * Remove a tag from a VG. | |
646 | * | |
647 | * \memberof vg_t | |
648 | * | |
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(). | |
653 | * | |
654 | * \param vg | |
8e3da446 | 655 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
3fe35b32 DW |
656 | * |
657 | * \param tag | |
658 | * Tag to remove from VG. | |
659 | * | |
660 | * \return | |
661 | * 0 (success) or -1 (failure). | |
662 | */ | |
a8ab5867 DW |
663 | int lvm_vg_remove_tag(vg_t vg, const char *tag); |
664 | ||
930a1434 DW |
665 | /** |
666 | * Set the extent size of a VG. | |
667 | * | |
3fe35b32 DW |
668 | * \memberof vg_t |
669 | * | |
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 | |
930a1434 | 672 | * the new VG to disk. Upon failure, retry the operation or release the VG |
3fe35b32 | 673 | * handle with lvm_vg_close(). |
930a1434 DW |
674 | * |
675 | * \param vg | |
8e3da446 | 676 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 | 677 | * |
930a1434 | 678 | * \param new_size |
f4edfec7 DW |
679 | * New extent size in bytes. |
680 | * | |
681 | * \return | |
682 | * 0 (success) or -1 (failure). | |
930a1434 | 683 | */ |
7510963f | 684 | int lvm_vg_set_extent_size(vg_t vg, uint32_t new_size); |
930a1434 | 685 | |
fca43425 DW |
686 | /** |
687 | * Get whether or not a volume group is clustered. | |
688 | * | |
3fe35b32 DW |
689 | * \memberof vg_t |
690 | * | |
fca43425 | 691 | * \param vg |
8e3da446 | 692 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
fca43425 DW |
693 | * |
694 | * \return | |
695 | * 1 if the VG is clustered, 0 if not | |
696 | */ | |
697 | uint64_t lvm_vg_is_clustered(vg_t vg); | |
698 | ||
699 | /** | |
700 | * Get whether or not a volume group is exported. | |
701 | * | |
3fe35b32 DW |
702 | * \memberof vg_t |
703 | * | |
fca43425 | 704 | * \param vg |
8e3da446 | 705 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
fca43425 DW |
706 | * |
707 | * \return | |
708 | * 1 if the VG is exported, 0 if not | |
709 | */ | |
710 | uint64_t lvm_vg_is_exported(vg_t vg); | |
711 | ||
712 | /** | |
713 | * Get whether or not a volume group is a partial volume group. | |
714 | * | |
3fe35b32 DW |
715 | * \memberof vg_t |
716 | * | |
fca43425 DW |
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 | |
719 | * group. | |
720 | * | |
721 | * \param vg | |
8e3da446 | 722 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
fca43425 DW |
723 | * |
724 | * \return | |
725 | * 1 if the VG is PVs, 0 if not | |
726 | */ | |
727 | uint64_t lvm_vg_is_partial(vg_t vg); | |
728 | ||
9ac1af71 DW |
729 | /** |
730 | * Get the current metadata sequence number of a volume group. | |
731 | * | |
3fe35b32 DW |
732 | * \memberof vg_t |
733 | * | |
9ac1af71 DW |
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. | |
737 | * | |
738 | * \param vg | |
8e3da446 | 739 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
9ac1af71 DW |
740 | * |
741 | * \return | |
742 | * Metadata sequence number. | |
743 | */ | |
7510963f | 744 | uint64_t lvm_vg_get_seqno(const vg_t vg); |
9ac1af71 | 745 | |
930a1434 | 746 | /** |
298ec21e | 747 | * Get the current uuid of a volume group. |
930a1434 | 748 | * |
3fe35b32 DW |
749 | * \memberof vg_t |
750 | * | |
298ec21e DW |
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. | |
930a1434 DW |
753 | * |
754 | * \param vg | |
8e3da446 | 755 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
756 | * |
757 | * \return | |
758 | * Copy of the uuid string. | |
930a1434 | 759 | */ |
298ec21e | 760 | const char *lvm_vg_get_uuid(const vg_t vg); |
930a1434 DW |
761 | |
762 | /** | |
298ec21e | 763 | * Get the current name of a volume group. |
930a1434 | 764 | * |
3fe35b32 DW |
765 | * \memberof vg_t |
766 | * | |
298ec21e DW |
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. | |
930a1434 DW |
769 | * |
770 | * \param vg | |
8e3da446 | 771 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
772 | * |
773 | * \return | |
774 | * Copy of the name. | |
930a1434 | 775 | */ |
298ec21e | 776 | const char *lvm_vg_get_name(const vg_t vg); |
930a1434 | 777 | |
f032ed74 | 778 | /** |
93e025dc | 779 | * Get the current size in bytes of a volume group. |
f032ed74 | 780 | * |
3fe35b32 DW |
781 | * \memberof vg_t |
782 | * | |
93e025dc | 783 | * \param vg |
8e3da446 | 784 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
785 | * |
786 | * \return | |
787 | * Size in bytes. | |
f032ed74 | 788 | */ |
7510963f | 789 | uint64_t lvm_vg_get_size(const vg_t vg); |
f032ed74 | 790 | |
83f25cd1 | 791 | /** |
93e025dc DW |
792 | * Get the current unallocated space in bytes of a volume group. |
793 | * | |
3fe35b32 DW |
794 | * \memberof vg_t |
795 | * | |
93e025dc | 796 | * \param vg |
8e3da446 | 797 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
798 | * |
799 | * \return | |
800 | * Free size in bytes. | |
83f25cd1 | 801 | */ |
7510963f | 802 | uint64_t lvm_vg_get_free_size(const vg_t vg); |
93e025dc DW |
803 | |
804 | /** | |
805 | * Get the current extent size in bytes of a volume group. | |
806 | * | |
3fe35b32 DW |
807 | * \memberof vg_t |
808 | * | |
93e025dc | 809 | * \param vg |
8e3da446 | 810 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
811 | * |
812 | * \return | |
813 | * Extent size in bytes. | |
93e025dc | 814 | */ |
7510963f | 815 | uint64_t lvm_vg_get_extent_size(const vg_t vg); |
93e025dc DW |
816 | |
817 | /** | |
818 | * Get the current number of total extents of a volume group. | |
819 | * | |
3fe35b32 DW |
820 | * \memberof vg_t |
821 | * | |
93e025dc | 822 | * \param vg |
8e3da446 | 823 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
824 | * |
825 | * \return | |
826 | * Extent count. | |
93e025dc | 827 | */ |
7510963f | 828 | uint64_t lvm_vg_get_extent_count(const vg_t vg); |
93e025dc DW |
829 | |
830 | /** | |
831 | * Get the current number of free extents of a volume group. | |
832 | * | |
3fe35b32 DW |
833 | * \memberof vg_t |
834 | * | |
93e025dc | 835 | * \param vg |
8e3da446 | 836 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
837 | * |
838 | * \return | |
839 | * Free extent count. | |
93e025dc | 840 | */ |
7510963f | 841 | uint64_t lvm_vg_get_free_extent_count(const vg_t vg); |
93e025dc DW |
842 | |
843 | /** | |
844 | * Get the current number of physical volumes of a volume group. | |
845 | * | |
3fe35b32 DW |
846 | * \memberof vg_t |
847 | * | |
93e025dc | 848 | * \param vg |
8e3da446 | 849 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 DW |
850 | * |
851 | * \return | |
852 | * Physical volume count. | |
93e025dc | 853 | */ |
7510963f | 854 | uint64_t lvm_vg_get_pv_count(const vg_t vg); |
93e025dc | 855 | |
8c794666 DW |
856 | /** |
857 | * Get the maximum number of physical volumes allowed in a volume group. | |
858 | * | |
3fe35b32 DW |
859 | * \memberof vg_t |
860 | * | |
8c794666 | 861 | * \param vg |
8e3da446 | 862 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
8c794666 DW |
863 | * |
864 | * \return | |
865 | * Maximum number of physical volumes allowed in a volume group. | |
866 | */ | |
867 | uint64_t lvm_vg_get_max_pv(const vg_t vg); | |
868 | ||
869 | /** | |
870 | * Get the maximum number of logical volumes allowed in a volume group. | |
871 | * | |
3fe35b32 DW |
872 | * \memberof vg_t |
873 | * | |
8c794666 | 874 | * \param vg |
8e3da446 | 875 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
8c794666 DW |
876 | * |
877 | * \return | |
878 | * Maximum number of logical volumes allowed in a volume group. | |
879 | */ | |
880 | uint64_t lvm_vg_get_max_lv(const vg_t vg); | |
881 | ||
a8ab5867 DW |
882 | /** |
883 | * Return the list of volume group tags. | |
884 | * | |
3fe35b32 DW |
885 | * \memberof vg_t |
886 | * | |
a8ab5867 | 887 | * The memory allocated for the list is tied to the vg_t handle and will be |
298ec21e | 888 | * released when lvm_vg_close() is called. |
a8ab5867 DW |
889 | * |
890 | * To process the list, use the dm_list iterator functions. For example: | |
891 | * vg_t vg; | |
892 | * struct dm_list *tags; | |
893 | * struct lvm_str_list *strl; | |
894 | * | |
895 | * tags = lvm_vg_get_tags(vg); | |
896 | * dm_list_iterate_items(strl, tags) { | |
897 | * tag = strl->str; | |
898 | * // do something with tag | |
899 | * } | |
900 | * | |
901 | * | |
902 | * \return | |
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. | |
908 | */ | |
909 | struct dm_list *lvm_vg_get_tags(const vg_t vg); | |
910 | ||
3c1febe0 DW |
911 | /** |
912 | * Get the value of a VG property | |
913 | * | |
914 | * \memberof vg_t | |
915 | * | |
916 | * \param vg | |
917 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). | |
918 | * | |
919 | * \param name | |
920 | * Name of property to query. See vgs man page for full list of properties | |
921 | * that may be queried. | |
922 | * | |
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. | |
925 | * | |
926 | * Example: | |
927 | * lvm_property_value v; | |
928 | * char *prop_name = "vg_mda_count"; | |
929 | * | |
930 | * v = lvm_vg_get_property(vg, prop_name); | |
931 | * if (!v.is_valid) { | |
932 | * printf("Invalid property name or unable to query" | |
933 | * "'%s', errno = %d.\n", prop_name, lvm_errno(libh)); | |
934 | * return; | |
935 | * } | |
936 | * if (v.is_string) | |
937 | * printf(", value = %s\n", v.value.string); | |
938 | * if (v.is_integer) | |
939 | * printf(", value = %"PRIu64"\n", v.value.integer); | |
940 | * | |
941 | * | |
942 | * \return | |
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. | |
947 | */ | |
948 | struct lvm_property_value lvm_vg_get_property(const vg_t vg, const char *name); | |
949 | ||
eeaf3ba7 PR |
950 | /** |
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. | |
954 | * | |
955 | * \memberof vg_t | |
956 | * | |
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. | |
959 | * | |
960 | * Example (integer): | |
961 | * lvm_property_value copies; | |
962 | * | |
963 | * if (lvm_vg_get_property(vg, "vg_mda_copies", &copies) < 0) { | |
964 | * // Error - unable to query property | |
965 | * } | |
966 | * if (!copies.is_settable) { | |
967 | * // Error - property not settable | |
968 | * } | |
969 | * copies.value.integer = 2; | |
970 | * if (lvm_vg_set_property(vg, "vg_mda_copies", &copies) < 0) { | |
971 | * // handle error | |
972 | * } | |
973 | * | |
974 | * \return | |
975 | * 0 (success) or -1 (failure). | |
976 | */ | |
977 | int lvm_vg_set_property(const vg_t vg, const char *name, | |
978 | struct lvm_property_value *value); | |
979 | ||
93e025dc | 980 | /************************** logical volume handling *************************/ |
83f25cd1 | 981 | |
93e025dc DW |
982 | /** |
983 | * Create a linear logical volume. | |
42a871b3 | 984 | * This function commits the change to disk and does _not_ require calling |
3fe35b32 | 985 | * lvm_vg_write(). |
88e3ced7 DW |
986 | * NOTE: The commit behavior of this function is subject to change |
987 | * as the API is developed. | |
930a1434 DW |
988 | * |
989 | * \param vg | |
8e3da446 | 990 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). |
f4edfec7 | 991 | * |
93e025dc | 992 | * \param name |
f4edfec7 DW |
993 | * Name of logical volume to create. |
994 | * | |
93e025dc | 995 | * \param size |
f4edfec7 DW |
996 | * Size of logical volume in extents. |
997 | * | |
998 | * \return | |
999 | * non-NULL handle to an LV object created, or NULL if creation fails. | |
930a1434 | 1000 | * |
930a1434 | 1001 | */ |
5d370b1b | 1002 | lv_t lvm_vg_create_lv_linear(vg_t vg, const char *name, uint64_t size); |
39d6ccdf | 1003 | |
ecc51116 PR |
1004 | /** |
1005 | * Return a list of lvseg handles for a given LV handle. | |
1006 | * | |
1007 | * \memberof lv_t | |
1008 | * | |
1009 | * \param lv | |
1010 | * Logical volume handle. | |
1011 | * | |
1012 | * \return | |
1013 | * A list of lvm_lvseg_list structures containing lvseg handles for this lv. | |
1014 | */ | |
1015 | struct dm_list *lvm_lv_list_lvsegs(lv_t lv); | |
1016 | ||
14b0c96b PR |
1017 | /** |
1018 | * Lookup an LV handle in a VG by the LV name. | |
1019 | * | |
1020 | * \memberof lv_t | |
1021 | * | |
1022 | * \param vg | |
1023 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). | |
1024 | * | |
1025 | * \param name | |
1026 | * Name of LV to lookup. | |
1027 | * | |
1028 | * \return | |
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. | |
1031 | */ | |
1032 | lv_t lvm_lv_from_name(vg_t vg, const char *name); | |
1033 | ||
5219fe3c PR |
1034 | /** |
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. | |
1038 | * | |
1039 | * \memberof lv_t | |
1040 | * | |
1041 | * \param vg | |
1042 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). | |
1043 | * | |
1044 | * \param uuid | |
1045 | * UUID of LV to lookup. | |
1046 | * | |
1047 | * \return | |
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. | |
1050 | */ | |
1051 | lv_t lvm_lv_from_uuid(vg_t vg, const char *uuid); | |
1052 | ||
63b186b6 DW |
1053 | /** |
1054 | * Activate a logical volume. | |
1055 | * | |
3fe35b32 DW |
1056 | * \memberof lv_t |
1057 | * | |
42a871b3 | 1058 | * This function is the equivalent of the lvm command "lvchange -ay". |
63b186b6 | 1059 | * |
42a871b3 | 1060 | * NOTE: This function cannot currently handle LVs with an in-progress pvmove or |
63b186b6 DW |
1061 | * lvconvert. |
1062 | * | |
1063 | * \param lv | |
f4edfec7 DW |
1064 | * Logical volume handle. |
1065 | * | |
1066 | * \return | |
1067 | * 0 (success) or -1 (failure). | |
63b186b6 | 1068 | */ |
5d370b1b | 1069 | int lvm_lv_activate(lv_t lv); |
63b186b6 DW |
1070 | |
1071 | /** | |
1072 | * Deactivate a logical volume. | |
1073 | * | |
3fe35b32 DW |
1074 | * \memberof lv_t |
1075 | * | |
42a871b3 | 1076 | * This function is the equivalent of the lvm command "lvchange -an". |
63b186b6 DW |
1077 | * |
1078 | * \param lv | |
f4edfec7 DW |
1079 | * Logical volume handle. |
1080 | * | |
1081 | * \return | |
1082 | * 0 (success) or -1 (failure). | |
63b186b6 | 1083 | */ |
5d370b1b | 1084 | int lvm_lv_deactivate(lv_t lv); |
63b186b6 | 1085 | |
729f472c | 1086 | /** |
93e025dc | 1087 | * Remove a logical volume from a volume group. |
729f472c | 1088 | * |
3fe35b32 DW |
1089 | * \memberof lv_t |
1090 | * | |
93e025dc | 1091 | * This function commits the change to disk and does _not_ require calling |
3fe35b32 | 1092 | * lvm_vg_write(). |
88e3ced7 DW |
1093 | * NOTE: The commit behavior of this function is subject to change |
1094 | * as the API is developed. | |
93e025dc | 1095 | * Currently only removing linear LVs are possible. |
729f472c | 1096 | * |
93e025dc | 1097 | * \param lv |
f4edfec7 DW |
1098 | * Logical volume handle. |
1099 | * | |
1100 | * \return | |
1101 | * 0 (success) or -1 (failure). | |
93e025dc | 1102 | */ |
5d370b1b | 1103 | int lvm_vg_remove_lv(lv_t lv); |
93e025dc DW |
1104 | |
1105 | /** | |
1106 | * Get the current name of a logical volume. | |
729f472c | 1107 | * |
3fe35b32 DW |
1108 | * \memberof lv_t |
1109 | * | |
da42be4d DW |
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. | |
729f472c | 1112 | * |
93e025dc | 1113 | * \param lv |
f4edfec7 DW |
1114 | * Logical volume handle. |
1115 | * | |
1116 | * \return | |
1117 | * Copy of the uuid string. | |
93e025dc | 1118 | */ |
298ec21e | 1119 | const char *lvm_lv_get_uuid(const lv_t lv); |
93e025dc DW |
1120 | |
1121 | /** | |
1122 | * Get the current uuid of a logical volume. | |
729f472c | 1123 | * |
3fe35b32 DW |
1124 | * \memberof lv_t |
1125 | * | |
8e3da446 | 1126 | * The memory allocated for the name is tied to the vg_t handle and will be |
da42be4d | 1127 | * released when lvm_vg_close() is called. |
93e025dc DW |
1128 | * |
1129 | * \param lv | |
f4edfec7 DW |
1130 | * Logical volume handle. |
1131 | * | |
1132 | * \return | |
1133 | * Copy of the name. | |
93e025dc | 1134 | */ |
298ec21e | 1135 | const char *lvm_lv_get_name(const lv_t lv); |
93e025dc DW |
1136 | |
1137 | /** | |
1138 | * Get the current size in bytes of a logical volume. | |
1139 | * | |
3fe35b32 DW |
1140 | * \memberof lv_t |
1141 | * | |
93e025dc | 1142 | * \param lv |
f4edfec7 DW |
1143 | * Logical volume handle. |
1144 | * | |
1145 | * \return | |
1146 | * Size in bytes. | |
93e025dc | 1147 | */ |
5d370b1b | 1148 | uint64_t lvm_lv_get_size(const lv_t lv); |
93e025dc | 1149 | |
dd68ee88 DW |
1150 | /** |
1151 | * Get the value of a LV property | |
1152 | * | |
1153 | * \memberof lv_t | |
1154 | * | |
1155 | * \param lv | |
1156 | * Logical volume handle. | |
1157 | * | |
1158 | * \param name | |
1159 | * Name of property to query. See lvs man page for full list of properties | |
1160 | * that may be queried. | |
1161 | * | |
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. | |
1164 | * | |
1165 | * Example: | |
1166 | * lvm_property_value v; | |
1167 | * char *prop_name = "seg_count"; | |
1168 | * | |
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)); | |
1173 | * return; | |
1174 | * } | |
1175 | * if (v.is_string) | |
1176 | * printf(", value = %s\n", v.value.string); | |
1177 | * if (v.is_integer) | |
1178 | * printf(", value = %"PRIu64"\n", v.value.integer); | |
1179 | * | |
1180 | * \return | |
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. | |
1185 | */ | |
1186 | struct lvm_property_value lvm_lv_get_property(const lv_t lv, const char *name); | |
1187 | ||
5de70620 PR |
1188 | /** |
1189 | * Get the value of a LV segment property | |
1190 | * | |
1191 | * \memberof lv_t | |
1192 | * | |
1193 | * \param lvseg | |
1194 | * Logical volume segment handle. | |
1195 | * | |
1196 | * \param name | |
1197 | * Name of property to query. See lvs man page for full list of properties | |
1198 | * that may be queried. | |
1199 | * | |
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. | |
1202 | * | |
1203 | * Example: | |
1204 | * lvm_property_value v; | |
1205 | * char *prop_name = "seg_start_pe"; | |
1206 | * | |
1207 | * v = lvm_lvseg_get_property(lvseg, prop_name); | |
1208 | * if (lvm_errno(libh) || !v.is_valid) { | |
1209 | * // handle error | |
1210 | * printf("Invalid property name or unable to query" | |
1211 | * "'%s'.\n", prop_name); | |
1212 | * return; | |
1213 | * } | |
1214 | * if (v.is_string) | |
1215 | * printf(", value = %s\n", v.value.string); | |
1216 | * else | |
1217 | * printf(", value = %"PRIu64"\n", v.value.integer); | |
1218 | * | |
1219 | * \return | |
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. | |
1223 | */ | |
1224 | struct lvm_property_value lvm_lvseg_get_property(const lvseg_t lvseg, | |
1225 | const char *name); | |
1226 | ||
2642ef55 DW |
1227 | /** |
1228 | * Get the current activation state of a logical volume. | |
1229 | * | |
3fe35b32 DW |
1230 | * \memberof lv_t |
1231 | * | |
2642ef55 | 1232 | * \param lv |
f4edfec7 DW |
1233 | * Logical volume handle. |
1234 | * | |
1235 | * \return | |
1236 | * 1 if the LV is active in the kernel, 0 if not | |
2642ef55 | 1237 | */ |
5d370b1b | 1238 | uint64_t lvm_lv_is_active(const lv_t lv); |
2642ef55 DW |
1239 | |
1240 | /** | |
1241 | * Get the current suspended state of a logical volume. | |
1242 | * | |
3fe35b32 DW |
1243 | * \memberof lv_t |
1244 | * | |
2642ef55 | 1245 | * \param lv |
f4edfec7 DW |
1246 | * Logical volume handle. |
1247 | * | |
1248 | * \return | |
1249 | * 1 if the LV is suspended in the kernel, 0 if not | |
2642ef55 | 1250 | */ |
5d370b1b | 1251 | uint64_t lvm_lv_is_suspended(const lv_t lv); |
2642ef55 | 1252 | |
a6ca9ac0 | 1253 | /** |
3fe35b32 | 1254 | * Add a tag to an LV. |
a6ca9ac0 | 1255 | * |
3fe35b32 DW |
1256 | * \memberof lv_t |
1257 | * | |
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 | |
a6ca9ac0 | 1260 | * new VG to disk. Upon failure, retry the operation or release the VG handle |
3fe35b32 | 1261 | * with lvm_vg_close(). |
a6ca9ac0 DW |
1262 | * |
1263 | * \param lv | |
1264 | * Logical volume handle. | |
1265 | * | |
1266 | * \param tag | |
3fe35b32 | 1267 | * Tag to add to an LV. |
a6ca9ac0 DW |
1268 | * |
1269 | * \return | |
1270 | * 0 (success) or -1 (failure). | |
1271 | */ | |
1272 | int lvm_lv_add_tag(lv_t lv, const char *tag); | |
3fe35b32 DW |
1273 | |
1274 | /** | |
1275 | * Remove a tag from an LV. | |
1276 | * | |
1277 | * \memberof lv_t | |
1278 | * | |
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(). | |
1283 | * | |
1284 | * \param lv | |
1285 | * Logical volume handle. | |
1286 | * | |
1287 | * \param tag | |
1288 | * Tag to remove from LV. | |
1289 | * | |
1290 | * \return | |
1291 | * 0 (success) or -1 (failure). | |
1292 | */ | |
a6ca9ac0 DW |
1293 | int lvm_lv_remove_tag(lv_t lv, const char *tag); |
1294 | ||
1295 | /** | |
1296 | * Return the list of logical volume tags. | |
1297 | * | |
3fe35b32 DW |
1298 | * \memberof lv_t |
1299 | * | |
a6ca9ac0 | 1300 | * The memory allocated for the list is tied to the vg_t handle and will be |
298ec21e | 1301 | * released when lvm_vg_close() is called. |
a6ca9ac0 DW |
1302 | * |
1303 | * To process the list, use the dm_list iterator functions. For example: | |
1304 | * lv_t lv; | |
1305 | * struct dm_list *tags; | |
1306 | * struct lvm_str_list *strl; | |
1307 | * | |
1308 | * tags = lvm_lv_get_tags(lv); | |
1309 | * dm_list_iterate_items(strl, tags) { | |
1310 | * tag = strl->str; | |
1311 | * // do something with tag | |
1312 | * } | |
1313 | * | |
1314 | * | |
1315 | * \return | |
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. | |
1321 | */ | |
1322 | struct dm_list *lvm_lv_get_tags(const lv_t lv); | |
1323 | ||
1324 | ||
ee7e183f DW |
1325 | /** |
1326 | * Resize logical volume to new_size bytes. | |
1327 | * | |
3fe35b32 DW |
1328 | * \memberof lv_t |
1329 | * | |
88e3ced7 DW |
1330 | * NOTE: This function is currently not implemented. |
1331 | * | |
ee7e183f | 1332 | * \param lv |
f4edfec7 DW |
1333 | * Logical volume handle. |
1334 | * | |
ee7e183f | 1335 | * \param new_size |
f4edfec7 DW |
1336 | * New size in bytes. |
1337 | * | |
1338 | * \return | |
1339 | * 0 (success) or -1 (failure). | |
ee7e183f DW |
1340 | * |
1341 | */ | |
5d370b1b | 1342 | int lvm_lv_resize(const lv_t lv, uint64_t new_size); |
ee7e183f | 1343 | |
93e025dc DW |
1344 | /************************** physical volume handling ************************/ |
1345 | ||
1346 | /** | |
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. | |
729f472c | 1350 | */ |
729f472c | 1351 | |
6c6c8214 | 1352 | /** |
3fe35b32 | 1353 | * Get the current uuid of a physical volume. |
6c6c8214 | 1354 | * |
3fe35b32 | 1355 | * \memberof pv_t |
122ccd0d | 1356 | * |
298ec21e DW |
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. | |
122ccd0d | 1359 | * |
93e025dc | 1360 | * \param pv |
f4edfec7 DW |
1361 | * Physical volume handle. |
1362 | * | |
1363 | * \return | |
1364 | * Copy of the uuid string. | |
93e025dc | 1365 | */ |
298ec21e | 1366 | const char *lvm_pv_get_uuid(const pv_t pv); |
93e025dc DW |
1367 | |
1368 | /** | |
3fe35b32 DW |
1369 | * Get the current name of a physical volume. |
1370 | * | |
1371 | * \memberof pv_t | |
122ccd0d | 1372 | * |
8e3da446 | 1373 | * The memory allocated for the name is tied to the vg_t handle and will be |
298ec21e | 1374 | * released when lvm_vg_close() is called. |
122ccd0d | 1375 | * |
93e025dc | 1376 | * \param pv |
f4edfec7 DW |
1377 | * Physical volume handle. |
1378 | * | |
1379 | * \return | |
1380 | * Copy of the name. | |
122ccd0d | 1381 | */ |
298ec21e | 1382 | const char *lvm_pv_get_name(const pv_t pv); |
122ccd0d | 1383 | |
fe63e644 | 1384 | /** |
93e025dc | 1385 | * Get the current number of metadata areas in the physical volume. |
fe63e644 | 1386 | * |
3fe35b32 DW |
1387 | * \memberof pv_t |
1388 | * | |
93e025dc | 1389 | * \param pv |
f4edfec7 DW |
1390 | * Physical volume handle. |
1391 | * | |
1392 | * \return | |
1393 | * Number of metadata areas in the PV. | |
fe63e644 | 1394 | */ |
e0e7fb84 | 1395 | uint64_t lvm_pv_get_mda_count(const pv_t pv); |
122ccd0d | 1396 | |
629efc6a DW |
1397 | /** |
1398 | * Get the current size in bytes of a device underlying a | |
1399 | * physical volume. | |
1400 | * | |
3fe35b32 DW |
1401 | * \memberof pv_t |
1402 | * | |
629efc6a DW |
1403 | * \param pv |
1404 | * Physical volume handle. | |
1405 | * | |
1406 | * \return | |
1407 | * Size in bytes. | |
1408 | */ | |
1409 | uint64_t lvm_pv_get_dev_size(const pv_t pv); | |
1410 | ||
1411 | /** | |
1412 | * Get the current size in bytes of a physical volume. | |
1413 | * | |
3fe35b32 DW |
1414 | * \memberof pv_t |
1415 | * | |
629efc6a DW |
1416 | * \param pv |
1417 | * Physical volume handle. | |
1418 | * | |
1419 | * \return | |
1420 | * Size in bytes. | |
1421 | */ | |
1422 | uint64_t lvm_pv_get_size(const pv_t pv); | |
1423 | ||
1424 | /** | |
1425 | * Get the current unallocated space in bytes of a physical volume. | |
1426 | * | |
3fe35b32 DW |
1427 | * \memberof pv_t |
1428 | * | |
629efc6a DW |
1429 | * \param pv |
1430 | * Physical volume handle. | |
1431 | * | |
1432 | * \return | |
1433 | * Free size in bytes. | |
1434 | */ | |
1435 | uint64_t lvm_pv_get_free(const pv_t pv); | |
1436 | ||
4e92d7c9 DW |
1437 | /** |
1438 | * Get the value of a PV property | |
1439 | * | |
1440 | * \memberof pv_t | |
1441 | * | |
1442 | * \param pv | |
1443 | * Physical volume handle. | |
1444 | * | |
1445 | * \param name | |
1446 | * Name of property to query. See pvs man page for full list of properties | |
1447 | * that may be queried. | |
1448 | * | |
8961b1d5 PR |
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(). | |
4e92d7c9 DW |
1453 | * |
1454 | * Example: | |
1455 | * lvm_property_value value; | |
1456 | * char *prop_name = "pv_mda_count"; | |
1457 | * | |
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)); | |
1462 | * return; | |
1463 | * } | |
1464 | * if (v.is_string) | |
1465 | * printf(", value = %s\n", v.value.string); | |
1466 | * if (v.is_integer) | |
1467 | * printf(", value = %"PRIu64"\n", v.value.integer); | |
1468 | * | |
1469 | * \return | |
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. | |
1474 | */ | |
1475 | struct lvm_property_value lvm_pv_get_property(const pv_t pv, const char *name); | |
1476 | ||
55429cde PR |
1477 | /** |
1478 | * Get the value of a PV segment property | |
1479 | * | |
1480 | * \memberof pv_t | |
1481 | * | |
1482 | * \param pvseg | |
1483 | * Physical volume segment handle. | |
1484 | * | |
1485 | * \param name | |
1486 | * Name of property to query. See pvs man page for full list of properties | |
1487 | * that may be queried. | |
1488 | * | |
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. | |
1491 | * | |
1492 | * Example: | |
1493 | * lvm_property_value v; | |
1494 | * char *prop_name = "pvseg_start"; | |
1495 | * | |
1496 | * v = lvm_pvseg_get_property(pvseg, prop_name); | |
1497 | * if (lvm_errno(libh) || !v.is_valid) { | |
1498 | * // handle error | |
1499 | * printf("Invalid property name or unable to query" | |
1500 | * "'%s'.\n", prop_name); | |
1501 | * return; | |
1502 | * } | |
1503 | * if (v.is_string) | |
1504 | * printf(", value = %s\n", v.value.string); | |
1505 | * else | |
1506 | * printf(", value = %"PRIu64"\n", v.value.integer); | |
1507 | * | |
1508 | * \return | |
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. | |
1512 | */ | |
1513 | struct lvm_property_value lvm_pvseg_get_property(const pvseg_t pvseg, | |
1514 | const char *name); | |
1515 | ||
b2b27cd7 PR |
1516 | /** |
1517 | * Return a list of pvseg handles for a given PV handle. | |
1518 | * | |
1519 | * \memberof pv_t | |
1520 | * | |
1521 | * \param pv | |
1522 | * Physical volume handle. | |
1523 | * | |
1524 | * \return | |
1525 | * A list of lvm_pvseg_list structures containing pvseg handles for this pv. | |
1526 | */ | |
1527 | struct dm_list *lvm_pv_list_pvsegs(pv_t pv); | |
1528 | ||
14b0c96b PR |
1529 | /** |
1530 | * Lookup an PV handle in a VG by the PV name. | |
1531 | * | |
1532 | * \memberof pv_t | |
1533 | * | |
1534 | * \param vg | |
1535 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). | |
1536 | * | |
1537 | * \param name | |
1538 | * Name of PV to lookup. | |
1539 | * | |
1540 | * \return | |
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. | |
1543 | */ | |
1544 | pv_t lvm_pv_from_name(vg_t vg, const char *name); | |
1545 | ||
5219fe3c PR |
1546 | /** |
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. | |
1550 | * | |
1551 | * \memberof pv_t | |
1552 | * | |
1553 | * \param vg | |
1554 | * VG handle obtained from lvm_vg_create() or lvm_vg_open(). | |
1555 | * | |
1556 | * \param uuid | |
1557 | * UUID of PV to lookup. | |
1558 | * | |
1559 | * \return | |
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. | |
1562 | */ | |
1563 | pv_t lvm_pv_from_uuid(vg_t vg, const char *uuid); | |
1564 | ||
ee7e183f DW |
1565 | /** |
1566 | * Resize physical volume to new_size bytes. | |
1567 | * | |
3fe35b32 DW |
1568 | * \memberof pv_t |
1569 | * | |
88e3ced7 DW |
1570 | * NOTE: This function is currently not implemented. |
1571 | * | |
ee7e183f | 1572 | * \param pv |
f4edfec7 DW |
1573 | * Physical volume handle. |
1574 | * | |
ee7e183f | 1575 | * \param new_size |
f4edfec7 | 1576 | * New size in bytes. |
ee7e183f | 1577 | * |
f4edfec7 DW |
1578 | * \return |
1579 | * 0 (success) or -1 (failure). | |
ee7e183f | 1580 | */ |
e0e7fb84 | 1581 | int lvm_pv_resize(const pv_t pv, uint64_t new_size); |
ee7e183f | 1582 | |
8961b1d5 PR |
1583 | #ifndef _LVM_PERCENT_H |
1584 | ||
1585 | /** | |
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. | |
1589 | */ | |
1590 | typedef enum { | |
1591 | PERCENT_0 = 0, | |
1592 | PERCENT_1 = 1000000, | |
1593 | PERCENT_100 = 100 * PERCENT_1, | |
23e34c72 MS |
1594 | PERCENT_INVALID = -1, |
1595 | PERCENT_MERGE_FAILED = -2 | |
8961b1d5 PR |
1596 | } percent_range_t; |
1597 | ||
1598 | typedef int32_t percent_t; | |
1599 | ||
1600 | #endif | |
1601 | ||
1602 | /** | |
1603 | * Convert a (fixed-point) value obtained from the percent-denominated | |
1604 | * *_get_property functions into a floating-point value. | |
1605 | */ | |
1606 | float lvm_percent_to_float(percent_t v); | |
1607 | ||
c9c7d25c MB |
1608 | #ifdef __cplusplus |
1609 | } | |
1610 | #endif | |
9e813cc9 | 1611 | #endif /* _LIB_LVM2APP_H */ |