[lvm-devel] LVM2/liblvm lvm.h
wysochanski at sourceware.org
wysochanski at sourceware.org
Tue Jul 28 00:36:59 UTC 2009
CVSROOT: /cvs/lvm2
Module name: LVM2
Changes by: wysochanski at sourceware.org 2009-07-28 00:36:59
Modified files:
liblvm : lvm.h
Log message:
Update lvm.h to address feeback.
This addresses a a large amount of Alasdair's review. Subsequent patches
will address remaining issues.
Addressed:
// FIXME Mention that's also required on error.
// FIXME Be consistent in terminology. It's called "system_dir" then last sentence says "system directory setting". Is it referring to "system_dir" there or something else?
// FIXME Mention it frees all resources and cannot be used subsequently?
// FIXME What does "any system configuration" mean?
// FIXME Expand on that explanation a bit, now that we know what the other fns look like.
// FIXME Not sure about that - it needs to scan sometimes. "will not" or "might not" ?
// FIXME: That's a FIXME in the code!!!
// FIXME What does "copied" mean in this context???
// FIXME Say what struct the returned struct dm_list is a list of...
// FIXME "This API" ? This function creates an object in memory?
// FIXME This function commits the Volume Group object referenced by the VG handle to disk?
// FIXME Where is "Name" defined? Absolute pathname?
Outstanding:
// FIXME Version function first? No structs or handles needed for that.
// FIXME Sort out this alignment. "Set an" directly below "system_dir" looks awful. Indent differently? More blank lines?
// FIXME Check how doxygen processes this. E.g. "return: LVM handle. You must use lvm_error() to check there were no errors and confirm that the handle is valid for passing to other functions."
// FIXME Find a better name. lvm_init.
// FIXME Consider renaming according to the new name for lvm_create.
// FIXME Please can we use dm_malloc throughout?
Patches:
http://sourceware.org/cgi-bin/cvsweb.cgi/LVM2/liblvm/lvm.h.diff?cvsroot=lvm2&r1=1.33&r2=1.34
--- LVM2/liblvm/lvm.h 2009/07/27 21:13:54 1.33
+++ LVM2/liblvm/lvm.h 2009/07/28 00:36:58 1.34
@@ -31,7 +31,14 @@
/******************************** structures ********************************/
-/* Internal object structures - do not use directly */
+/**
+ * Opaque structures - do not use directly. Internal structures may change
+ * without notice between releases, whereas this API will be changed much less
+ * frequently. Backwards compatibility will normally be preserved in future
+ * releases. On any occasion when the developers do decide to break backwards
+ * compatibility in any significant way, the LVM_LIBAPI number (included in
+ * the library's soname) will be incremented.
+ */
struct lvm;
struct physical_volume;
struct volume_group;
@@ -40,23 +47,15 @@
/**
* lvm handle.
*
- * This is the base handle that is needed to open and create objects. Also
- * error handling is bound to this handle.
+ * This is the base handle that is needed to open and create objects such as
+ * volume groups and logical volumes. In addition, this handle provides a
+ * context for error handling information, saving any error number (see
+ * lvm_errno) and error message (see lvm_errmsg) that any function may
+ * generate.
*/
typedef struct lvm *lvm_t;
/**
- * Physical volume object.
- *
- * This object can be either a read-only object or a read-write object and
- * depends on the mode of the volume group. This object can not be
- * written to disk independently, and changes will be written to disk
- * when the volume group gets committed to disk. The open mode is the
- * same as the volume group object it was created from.
- */
-typedef struct physical_volume pv_t;
-
-/**
* Volume group object.
*
* This object can be either a read-only object or a read-write object
@@ -69,51 +68,47 @@
/**
* Logical Volume object.
*
- * This object can be either a read-only object or a read-write object
- * depending on the mode of the volume group. This object can not be
- * written to disk independently, it is bound to a volume group and changes
- * will be written to disk when the volume group gets committed to disk. The
- * open mode is the same as the volume group object is was created from.
+ * This object is bound to a volume group and has the same mode of the volume
+ * group. Changes will be written to disk when the volume group gets
+ * committed to disk.
*/
typedef struct logical_volume lv_t;
/**
- * Physical volume object list.
+ * Physical volume object.
*
- * The properties of physical volume objects also applies to the list of
- * physical volumes.
+ * This object is bound to a volume group and has the same mode of the volume
+ * group. Changes will be written to disk when the volume group gets
+ * committed to disk.
*/
-typedef struct lvm_pv_list {
- struct dm_list list;
- pv_t *pv;
-} pv_list_t;
+typedef struct physical_volume pv_t;
/**
- * Volume group object list.
+ * Logical Volume object list.
*
- * The properties of volume group objects also applies to the list of
- * volume groups.
+ * Lists of these structures are returned by lvm_vg_list_pvs.
*/
-typedef struct lvm_vg_list {
+typedef struct lvm_lv_list {
struct dm_list list;
- vg_t *vg;
-} vg_list_t;
+ lv_t *lv;
+} lv_list_t;
/**
- * Logical Volume object list.
+ * Physical volume object list.
*
- * The properties of logical volume objects also applies to the list of
- * logical volumes.
+ * Lists of these structures are returned by lvm_vg_list_pvs.
*/
-typedef struct lvm_lv_list {
+typedef struct lvm_pv_list {
struct dm_list list;
- lv_t *lv;
-} lv_list_t;
+ pv_t *pv;
+} pv_list_t;
/**
* String list.
*
* This string list contains read-only strings.
+ * Lists of these structures are returned by lvm_list_vg_names and
+ * lvm_list_vg_uuids.
*/
struct lvm_str_list {
struct dm_list list;
@@ -121,7 +116,6 @@
};
/*************************** generic lvm handling ***************************/
-
/**
* Create a LVM handle.
*
@@ -131,16 +125,24 @@
* \param system_dir
* Set an alternative LVM system directory. Use NULL to use the
* default value. If the environment variable LVM_SYSTEM_DIR is set,
- * it will override any LVM system directory setting.
+ * it will override any system_dir setting.
* \return A valid LVM handle is returned or NULL if there has been a
* memory allocation problem. You have to check if an error occured
* with the lvm_error function.
*/
+// FIXME: Sort out this alignment. "Set an" directly below "system_dir"
+// looks awful. Indent differently? More blank lines?
lvm_t lvm_create(const char *system_dir);
+// FIXME Find a better name. lvm_init.
/**
* Destroy a LVM handle allocated with lvm_create.
*
+ * This function should be used after all LVM operations are complete or after
+ * an unrecoverable error. Destroying the LVM handle frees the memory and
+ * other resources associated with the handle. Once destroyed, the handle
+ * cannot be used subsequently.
+ *
* \param libh
* Handle obtained from lvm_create.
*/
@@ -149,8 +151,9 @@
/**
* Reload the original configuration from the system directory.
*
- * This function should be used when any system configuration changes,
- * and the change is needed by the application.
+ * This function should be used when any LVM configuration changes in the LVM
+ * system_dir or by another lvm_config* function, and the change is needed by
+ * the application.
*
* \param libh
* Handle obtained from lvm_create.
@@ -161,13 +164,14 @@
/**
* Override the LVM configuration with a configuration string.
*
- * This API is equivalent to the --config option on lvm commands.
+ * This function is equivalent to the --config option on lvm commands.
* FIXME: submit a patch to document the --config option
* Once this API has been used to over-ride the configuration,
* you should use lvm_config_reload to apply the new settings.
+ *
* \param libh
* Handle obtained from lvm_create.
- * \param config_settings
+ * \param config_string
* LVM configuration string to apply. See the lvm.conf file man page
* for the format of the config string.
* \return 0 (success) or -1 (failure).
@@ -177,9 +181,13 @@
/**
* Return stored error no describing last LVM API error.
*
- * Users of liblvm should use lvm_errno to determine success or failure
- * of the last call, unless the API indicates another method of determining
- * success or failure.
+ * Users of liblvm should use lvm_errno to determine the details of a any
+ * failure of the last call. A basic success or fail is always returned by
+ * every function, either by returning a 0 or -1, or a non-NULL / NULL.
+ * If a function has failed, lvm_errno may be used to get a more specific
+ * error code describing the failure. In this way, lvm_errno may be used
+ * after every function call, even after a 'get' function call that simply
+ * returns a value.
*
* \param libh
* Handle obtained from lvm_create.
@@ -191,6 +199,9 @@
/**
* Return stored error message describing last LVM error.
*
+ * This function may be used in conjunction with lvm_errno to obtain more
+ * specific error information for a function that is known to have failed.
+ *
* \param libh
* Handle obtained from lvm_create.
*
@@ -214,8 +225,8 @@
* The memory allocated for the list is tied to the lvm_t handle and will be
* released when lvm_destroy is called.
*
- * NOTE: This function will _NOT_ scan devices in the system for LVM metadata.
- * To scan the system, use lvm_scan.
+ * NOTE: This function normally does not scan devices in the system for LVM
+ * metadata. To scan the system, use lvm_scan.
* NOTE: This function currently returns hidden VG names. These names always
* begin with a "#" and should be filtered out and not used.
*
@@ -233,7 +244,8 @@
* }
*
*
- * \return A list of struct lvm_str_list
+ * \return A list with entries of type struct lvm_str_list, containing the
+ * VG name strings of the Volume Groups known to the system.
* NULL is returned if unable to allocate memory.
* An empty list (verify with dm_list_empty) is returned if no VGs
* exist on the system.
@@ -246,15 +258,16 @@
* The memory allocated for the list is tied to the lvm_t handle and will be
* released when lvm_destroy is called.
*
- * NOTE: This function will _NOT_ scan devices in the system for LVM metadata.
- * To scan the system, use lvm_scan.
+ * NOTE: This function normally does not scan devices in the system for LVM
+ * metadata. To scan the system, use lvm_scan.
* NOTE: This function currently returns hidden VG names. These names always
* begin with a "#" and should be filtered out and not used.
*
* \param libh
* Handle obtained from lvm_create.
*
- * \return List of copied uuid strings.
+ * \return A list with entries of type struct lvm_str_list, containing the
+ * VG UUID strings of the Volume Groups known to the system.
* NULL is returned if unable to allocate memory.
* An empty list (verify with dm_list_empty) is returned if no VGs
* exist on the system.
@@ -283,7 +296,7 @@
/**
* Create a VG with default parameters.
*
- * This API requires calling lvm_vg_write to commit the change to disk.
+ * This function creates a Volume Group object in memory.
* Upon success, other APIs may be used to set non-default parameters.
* For example, to set a non-default extent size, use lvm_vg_set_extent_size.
* Next, to add physical storage devices to the volume group, use
@@ -303,9 +316,9 @@
/**
* Write a VG to disk.
*
- * This API commits the VG to disk.
- * Upon failure, retry the operation and/or release the VG handle with
- * lvm_vg_close.
+ * This function commits the Volume Group object referenced by the VG handle
+ * to disk. Upon failure, retry the operation and/or release the VG handle
+ * with lvm_vg_close.
*
* \param vg
* VG handle obtained from lvm_vg_create or lvm_vg_open.
@@ -316,7 +329,7 @@
/**
* Remove a VG from the system.
*
- * This API commits the change to disk and does not require calling
+ * This function commits the change to disk and does not require calling
* lvm_vg_write.
*
* \param vg
@@ -328,7 +341,8 @@
/**
* Close a VG opened with lvm_vg_create or lvm_vg_open.
*
- * This API releases a VG handle and any resources associated with the handle.
+ * This function releases a VG handle and any resources associated with the
+ * handle.
*
* \param vg
* VG handle obtained from lvm_vg_create or lvm_vg_open.
@@ -339,7 +353,7 @@
/**
* Extend a VG by adding a device.
*
- * This API requires calling lvm_vg_write to commit the change to disk.
+ * This function requires calling lvm_vg_write to commit the change to disk.
* After successfully adding a device, use lvm_vg_write to commit the new VG
* to disk. Upon failure, retry the operation or release the VG handle with
* lvm_vg_close.
@@ -351,7 +365,7 @@
* \param vg
* VG handle obtained from lvm_vg_create or lvm_vg_open.
* \param device
- * Name of device to add to VG.
+ * Absolute pathname of device to add to VG.
* \return 0 (success) or -1 (failure).
*/
int lvm_vg_extend(vg_t *vg, const char *device);
@@ -359,7 +373,7 @@
/**
* Reduce a VG by removing an unused device.
*
- * This API requires calling lvm_vg_write to commit the change to disk.
+ * This function requires calling lvm_vg_write to commit the change to disk.
* After successfully removing a device, use lvm_vg_write to commit the new VG
* to disk. Upon failure, retry the operation or release the VG handle with
* lvm_vg_close.
@@ -377,7 +391,7 @@
/**
* Set the extent size of a VG.
*
- * This API requires calling lvm_vg_write to commit the change to disk.
+ * This function requires calling lvm_vg_write to commit the change to disk.
* After successfully setting a new extent size, use lvm_vg_write to commit
* the new VG to disk. Upon failure, retry the operation or release the VG
* handle with lvm_vg_close.
@@ -482,9 +496,9 @@
/**
* Create a linear logical volume.
- * This API commits the change to disk and does _not_ require calling
+ * This function commits the change to disk and does _not_ require calling
* lvm_vg_write.
- * FIXME: This API should probably not commit to disk but require calling
+ * FIXME: This function should probably not commit to disk but require calling
* lvm_vg_write. However, this appears to be non-trivial change until
* lv_create_single is refactored by segtype.
*
@@ -502,9 +516,9 @@
/**
* Activate a logical volume.
*
- * This API is the equivalent of the lvm command "lvchange -ay".
+ * This function is the equivalent of the lvm command "lvchange -ay".
*
- * NOTE: This API cannot currently handle LVs with an in-progress pvmove or
+ * NOTE: This function cannot currently handle LVs with an in-progress pvmove or
* lvconvert.
*
* \param lv
@@ -516,7 +530,7 @@
/**
* Deactivate a logical volume.
*
- * This API is the equivalent of the lvm command "lvchange -an".
+ * This function is the equivalent of the lvm command "lvchange -an".
*
* \param lv
* Logical volume handle.
@@ -531,7 +545,7 @@
* lvm_vg_write.
* Currently only removing linear LVs are possible.
*
- * FIXME: This API should probably not commit to disk but require calling
+ * FIXME: This function should probably not commit to disk but require calling
* lvm_vg_write.
*
* \param lv
More information about the lvm-devel
mailing list