shaba/lvm2
1
0
Fork 0
mirror of git://sourceware.org/git/lvm2.git synced 2024-10-27 18:55:19 +03:00
Code Releases Activity

Update lvm.h to address feeback.

Browse Source 
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?
This commit is contained in:
Dave Wysochanski 2009-07-28 00:36:58 +00:00
parent d4b311970d
commit 42a871b3df
1 changed files with 84 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
liblvm/lvm.h
View File

@ -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,22 +47,14 @@ struct logical_volume;
/**
* 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.
*
@ -69,51 +68,47 @@ typedef struct volume_group vg_t;
/**
* 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;
/**
* Volume group object list.
*
* The properties of volume group objects also applies to the list of
* volume groups.
*/
typedef struct lvm_vg_list {
struct dm_list list;
vg_t *vg;
} vg_list_t;
typedef struct physical_volume pv_t;
/**
* Logical 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 {
struct dm_list list;
lv_t *lv;
} lv_list_t;
/**
* Physical volume object list.
*
* Lists of these structures are returned by lvm_vg_list_pvs.
*/
typedef struct lvm_pv_list {
struct dm_list list;
pv_t *pv;
} pv_list_t;
/**
* String list.
*
* This string list contains read-only strings.
* Lists of these structures are returned by lvm_list_vg_names and
* lvm_list_vg_uuids.
*/
struct lvm_str_list {
struct dm_list list;
@ -121,7 +116,6 @@ struct lvm_str_list {
};
/*************************** generic lvm handling ***************************/
/**
* Create a LVM handle.
*
@ -131,16 +125,24 @@ struct lvm_str_list {
* \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 @@ void lvm_destroy(lvm_t libh);
/**
* 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 @@ int lvm_config_reload(lvm_t libh);
/**
* 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 @@ int lvm_config_override(lvm_t libh, const char *config_string);
/**
* Return stored error no describing last LVM API error.
*
* Users of liblvm should use lvm_errno to determine 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 @@ int lvm_errno(lvm_t libh);
/**
* Return stored error message describing last LVM error.
*
* This function may be used in conjunction with lvm_errno to obtain more
* specific error information for a function that is known to have failed.
*
* \param libh
* Handle obtained from lvm_create.
*
@ -214,8 +225,8 @@ int lvm_scan(lvm_t libh);
* 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 @@ int lvm_scan(lvm_t libh);
* }
*
*
* \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 @@ struct dm_list *lvm_list_vg_names(lvm_t libh);
* 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 @@ vg_t *lvm_vg_open(lvm_t libh, const char *vgname, const char *mode,
/**
* 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 @@ vg_t *lvm_vg_create(lvm_t libh, const char *vg_name);
/**
* 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 @@ int lvm_vg_write(vg_t *vg);
/**
* 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 @@ int lvm_vg_remove(vg_t *vg);
/**
* 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 @@ int lvm_vg_close(vg_t *vg);
/**
* 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 @@ int lvm_vg_close(vg_t *vg);
* \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 @@ int lvm_vg_extend(vg_t *vg, const char *device);
/**
* 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 @@ int lvm_vg_reduce(vg_t *vg, const char *device);
/**
* 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 @@ struct dm_list *lvm_vg_list_lvs(vg_t *vg);
/**
* 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 @@ lv_t *lvm_vg_create_lv_linear(vg_t *vg, const char *name, uint64_t size);
/**
* 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 @@ int lvm_lv_activate(lv_t *lv);
/**
* 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 @@ int lvm_lv_deactivate(lv_t *lv);
* 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