* SECTION: alignment
* @title: Align LBA
* @short_description: function to align partitions and work with disk topology and geometry.
+ *
+ * The libfdisk aligns the end of the partitions to make it possible to align
+ * the next partition to the "grain" (see fdisk_get_grain()). The grain is
+ * usually 1MiB (or more for devices where optimal I/O is greater than 1MiB).
+ *
+ * It means that the library does not align strictly to physical sector size
+ * (or minimal or optimal I/O), but it uses greater granularity. It makes
+ * partition tables more portable. If you copy disk layout from 512-sector to
+ * 4K-sector device, all partitions are still aligned to physical sectors.
+ *
+ * This unified concept also makes partition tables more user friendly, all
+ * tables look same, LBA of the first partition is 2048 sectors everywhere, etc.
+ *
+ * It's recommended to not change any alignment or device properties. All is
+ * initialized by default by fdisk_assign_device().
+ *
+ * Note that terminology used by libfdisk is:
+ * - device properties: I/O limits (topology), geometry, sector size, ...
+ * - alignment: first, last LBA, grain, ...
+ *
+ * The alignment setting may be modified by disk label driver.
*/
/*
- * Alignment according to logical granulity (usually 1MiB)
+ * Alignment according to logical granularity (usually 1MiB)
*/
static int lba_is_aligned(struct fdisk_context *cxt, sector_t lba)
{
* @lba: address to align
* @direction: FDISK_ALIGN_{UP,DOWN,NEAREST}
*
+ * This function aligns @lba to the "grain" (see fdisk_get_grain()). If the
+ * device uses alignment offset then the result is moved according the offset
+ * to be on the physical boundary.
+ *
* Returns: alignment LBA.
*/
sector_t fdisk_align_lba(struct fdisk_context *cxt, sector_t lba, int direction)
* @cxt: context
* @lba: LBA to check
*
- * Check if the @lba is aligned.
+ * Check if the @lba is aligned to physical sector boundary.
*
* Returns: 1 if aligned.
*/
* @heads: user specified heads
* @sectors: user specified sectors
*
- * Overrides autodiscovery and apply user specified geometry. The function
- * fdisk_reset_device_properties() restores the original setting.
+ * Overrides auto-discovery. The function fdisk_reset_device_properties()
+ * restores the original setting.
+ *
+ * The difference between fdisk_override_geometry() and fdisk_save_user_geometry()
+ * is that saved user geometry is persistent setting and it's applied always
+ * when device is assigned to the context or device properties are reseted.
*
* Returns: 0 on success, < 0 on error.
*/
*
* Save user defined geometry to use it for partitioning.
*
+ * The user properties are applied by fdisk_assign_device() or
+ * fdisk_reset_device_properties().
+
* Returns: <0 on error, 0 on success.
*/
int fdisk_save_user_geometry(struct fdisk_context *cxt,
*
* Save user defined sector sizes to use it for partitioning.
*
+ * The user properties are applied by fdisk_assign_device() or
+ * fdisk_reset_device_properties().
+ *
* Returns: <0 on error, 0 on success.
*/
int fdisk_save_user_sector_size(struct fdisk_context *cxt,
memset(&cxt->geom, 0, sizeof(struct fdisk_geometry));
}
+/**
+ * fdisk_reset_device_properties:
+ * @cxt: context
+ *
+ * Resets and discovery topology (I/O limits), geometry, re-read the first
+ * rector on the device if necessary and apply user device setting (geometry
+ * and sector size), then initialize alignment according to label driver (see
+ * fdisk_reset_alignment()).
+ *
+ * You don't have to use this function by default, fdisk_assign_device() is
+ * smart enough to initialize all necessary setting.
+ *
+ * Returns: 0 on success, <0 on error.
+ */
int fdisk_reset_device_properties(struct fdisk_context *cxt)
{
int rc;
return res;
}
-/*
- * The LBA of the first partition is based on the device geometry and topology.
- * This offset is generic generic (and recommended) for all labels.
- *
- * Returns: 0 on error or number of bytes.
- */
static unsigned long topology_get_grain(struct fdisk_context *cxt)
{
unsigned long res;
* fdisk_reset_alignment:
* @cxt: fdisk context
*
- * Resets alignment setting to the default or label specific values.
+ * Resets alignment setting to the default and label specific values. This
+ * function does not change device properties (I/O limits, geometry etc.).
*
* Returns: 0 on success, < 0 in case of error.
*/
* fdisk_reread_partition_table:
* @cxt: context
*
- * Force *system kernel* to re-read partition table.
+ * Force *kernel* to re-read partition table on block devices.
+ *
+ * Returns: 0 on success, < 0 in case of error.
*/
int fdisk_reread_partition_table(struct fdisk_context *cxt)
{
* @title: libfdisk handler
* @short_description: stores infor about device, labels etc.
*
- * Partitioning data:
+ * The library distinguish between three types of partitioning objects.
*
* on-disk data
- * The libfdisk reads PT when you assign device to the context, the
- * function fdisk_write_disklabel() modify on-disk data.
+ * - disk label specific
+ * - probed and read by disklabel drivers when assign device to the context
+ * or when switch to another disk label type
+ * - only fdisk_write_disklabel() modify on-disk data
*
* in-memory data
- * All data are label specific, but usually stored in the first sector
- * which is cached in memory and shared between all label drivers (see
- * labelsection for more details). All label operations are based on
- * in-memory data.
+ * - generic data and disklabel specific data stored in struct fdisk_label
+ * - all partitioning operations are based on in-memory data only
*
* struct fdisk_partition
- * The struct provides abstraction to present partitions to users (for
- * example to generate human readable info about PT) and it's also unified
- * way how to define partition template that can be used by label driver to
- * create a new partition. It's necessary to understand the struct
- * fdisk_partition is always completely independent object and any change to
- * the object has no effect to in-memory (or on-disk) label data.
+ * - provides abstraction to present partitions to users
+ * - fdisk_partition is possible to gather to fdisk_table container
+ * - used as unified template for new partitions
+ * - the struct fdisk_partition is always completely independent object and
+ * any change to the object has no effect to in-memory (or on-disk) label data
*/
/**
* fdisk_ref_context:
* @cxt: context pointer
*
- * Incremparts reference counter.
+ * Increments reference counter.
*/
void fdisk_ref_context(struct fdisk_context *cxt)
{
return 0;
}
-/**
- * fdisk_switch_label:
- * @cxt: context
- * @name: label name (e.g. "gpt")
- *
- * Forces libfdisk to use the label driver. It's usually bad idea to use this
- * function, it's better to use fdisk_create_disklabel().
- *
- *
- * Returns: 0 on succes, <0 in case of error.
- */
-int fdisk_switch_label(struct fdisk_context *cxt, const char *name)
-{
- return __fdisk_switch_label(cxt, fdisk_get_label(cxt, name));
-}
-
/**
* fdisk_has_label:
* @cxt: fdisk context
* fdisk_get_npartitions:
* @cxt: context
*
+ * The maximal number of the partitions depends on disklabel and does not
+ * have to describe the real limit of PT.
+ *
+ * For example the limit for MBR without extend partition is 4, with extended
+ * partition it's unlimited (so the function returns the current number of all
+ * partitions in this case).
+ *
+ * And for example for GPT it depends on space allocated on disk for array of
+ * entry records (usually 128).
+ *
+ * It's fine to use fdisk_get_npartitions() in loops, but don't forget that
+ * partition may be unused (see fdisk_is_partition_used()).
+ *
+ * <informalexample>
+ * <programlisting>
+ * struct fdisk_partition *pa = NULL;
+ * size_t i, nmax = fdisk_get_npartitions(cxt);
+ *
+ * for (i = 0; i < nmax; i++) {
+ * if (!fdisk_is_partition_used(cxt, i))
+ * continue;
+ * ... do something ...
+ * }
+ * </programlisting>
+ * </informalexample>
+ *
+ * Note that the recommended way to list partitions is to use
+ * fdisk_get_partitions() and struct fdisk_table than ask disk driver for each
+ * individual partitions.
+ *
* Returns: maximal number of partitions for the current label.
*/
size_t fdisk_get_npartitions(struct fdisk_context *cxt)
*
* Close device and call fsync(). If the @cxt is nested context than the
* request is redirected to the parent.
+ *
+ * Returns: 0 on success, < 0 on error.
*/
int fdisk_deassign_device(struct fdisk_context *cxt, int nosync)
{
* @ask_cb: callback
* @data: callback data
*
- * Set callbacks for dialog driven partitioning and library warnings/errors.
+ * Set callback for dialog driven partitioning and library warnings/errors.
*
* Returns: 0 on success, < 0 on error.
*/
* anyway libfdisk never returns zero. If the optimal I/O size is not provided
* then libfdisk returns minimal I/O size or sector size.
*
- * Returns: optimal I/O size
+ * Returns: optimal I/O size in bytes.
*/
unsigned long fdisk_get_optimal_iosize(struct fdisk_context *cxt)
{
* fdisk_get_minimal_iosize:
* @cxt: context
*
- * Returns: minimal I/O size
+ * Returns: minimal I/O size in bytes
*/
unsigned long fdisk_get_minimal_iosize(struct fdisk_context *cxt)
{
* fdisk_get_physector_size:
* @cxt: context
*
- * Returns: physical sector size
+ * Returns: physical sector size in bytes
*/
unsigned long fdisk_get_physector_size(struct fdisk_context *cxt)
{
* fdisk_get_sector_size:
* @cxt: context
*
- * Returns: sector size
+ * Returns: logical sector size in bytes
*/
unsigned long fdisk_get_sector_size(struct fdisk_context *cxt)
{
* fdisk_get_alignment_offset
* @cxt: context
*
- * Returns: alignment offset (used by 4K disks for backward compatibility with DOS tools).
+ * The alignment offset is offset between logical and physical sectors. For
+ * backward compatibility the first logical sector on 4K disks does no have to
+ * start on the same place like physical sectors.
+ *
+ * Returns: alignment offset in bytes
*/
unsigned long fdisk_get_alignment_offset(struct fdisk_context *cxt)
{
* fdisk_get_grain_size:
* @cxt: context
*
- * Returns: usual grain used to align partitions
+ * Returns: grain in bytes used to align partitions (usually 1MiB)
*/
unsigned long fdisk_get_grain_size(struct fdisk_context *cxt)
{
/**
* fdisk_set_first_lba:
* @cxt: fdisk context
- * @lba: first possible sector for data
+ * @lba: first possible logical sector for data
*
* It's strongly recommended to use the default library setting. The first LBA
* is always reseted by fdisk_assign_device(), fdisk_override_geometry()
* and fdisk_reset_alignment(). This is very low level function and library
* does not check if your setting makes any sense.
*
+ * This function is necessary only when you want to work with very unusual
+ * partition tables like GPT protective MBR or hybrid partition tables on
+ * bootable media where the first partition may start on very crazy offsets.
+ *
* Returns: 0 on success, <0 on error.
*/
sector_t fdisk_set_first_lba(struct fdisk_context *cxt, sector_t lba)
/**
* fdisk_set_last_lba:
* @cxt: fdisk context
- * @lba: last possible sector
+ * @lba: last possible logical sector
*
* It's strongly recommended to use the default library setting. The last LBA
* is always reseted by fdisk_assign_device(), fdisk_override_geometry() and
* fdisk_reset_alignment().
*
+ * The default is number of sectors on the device, but maybe modified by the
+ * current disklabel driver (for example GPT uses and of disk for backup
+ * header, so last_lba is smaller than total number of sectors).
+ *
* Returns: 0 on success, <0 on error.
*/
sector_t fdisk_set_last_lba(struct fdisk_context *cxt, sector_t lba)
* fdisk_get_nsectors:
* @cxt: context
*
- * Returns: size of the device in (real) sectors.
+ * Returns: size of the device in logical sectors.
*/
sector_t fdisk_get_nsectors(struct fdisk_context *cxt)
{