path: root/doc/API

===============================================================================
                               GNU libparted API
===============================================================================








                <<< This file is deprecated and being converted
                       to Doxygen in-line documentation.
                  Until this is finished, both are incomplete
                    but fully document the API together. >>>


                            ( scroll down to read )





      by Andrew Clausen <clausen@gnu.org>,
         Leslie P. Polzer <polzer@gnu.org>

      Copyright (C) 1999, 2000, 2001, 2002, 2003, 2005, 2006, 2007
      Free Software Foundation, Inc.

      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.3
      or any later version published by the Free Software Foundation;
      with the no Invariant Sections, with the no Front-Cover Texts, and
      with no Back-Cover Texts.  A copy of the license is included in the
      file, COPYING.DOC.


CONTENTS
--------

1	Introduction
2	Initialising libparted
3	PedDevice
4	PedDisk, PedDiskType
5	PedGeometry
6	PedPartition, PedPartitionType
7	PedFileSystem, PedFileSystemType
8	PedConstraint, PedAlignment
9	PedTimer
10	PedUnit
11	Exceptions

-------------------------------------------------------------------------------
1	INTRODUCTION
-------------------------------------------------------------------------------

GNU Parted is built on top of libparted, which does all of the real work.
libparted provides an API capable of manipulating partition tables, and
the filesystems on them.

The main motivation for separating the back-end into a separate library was
to encourage different GNU/Linux distributions to encorporate their own
customized front-end into the install process.

This documents the API -- not the implementation details of libparted.
Documentation that is not relevant to programs using the API are marked with
INTERNAL.  Apart from this file, a good place to look would be
parted/parted.c, the front-end's source, and the TUTORIAL file (not finished
yet!).

This documentation isn't as complete as it should be.  Feel free to ask
questions, either to me personally (clausen@gnu.org), or to the mailing list
(bug-parted@gnu.org).

1.1	TERMINOLOGY
-------------------
Some of the terminology is a bit weird, so you might want to read this.

CONSTRAINT		a set of conditions that must be satisfied, for
			a given GEOMETRY of a PARTITION.

DEVICE			a storage device.

DISK			a storage device, with a valid partition table.

EXCEPTION		an event that needs attention.

EXTENDED PARTITION	a PRIMARY PARTITION, that may contain LOGICAL
			PARTITIONS instead of a file system.  There is at most
			one extended partition.

FILE SYSTEM		any data that resides on a partition.  For the purposes
			for GNU Parted, this includes swap devices.

GEOMETRY		a description of a continuous region on a disk.  eg,
			partitions have a geometry.

HIDDEN PARTITION	a partition that is hidden from MS operating systems.
			Only FAT partitions may be hidden.

LOGICAL PARTITION	like normal partitions, but they lie inside the
			extended partition.

PARTITION		a continuous region on a disk where a file system may
			reside.

PRIMARY PARTITION	a normal, vanilla, partition.

PARTITION TABLE		also, DISK LABEL.  A description of where the
			partitions lie, and information about those partitions.
			For example, what type of file system resides on them.
			The partition table is usually at the start of the
			disk.

TIMER			a progress meter.  It is an entity that keeps track
			of time, and who to inform when something interesting
			happens.

1.2	DESIGN
--------------
libparted has a fairly object-oriented design.  The most important objects are:

PedArchitecture		describes support for an "archicture", which is sort
			of like "operating system", but could also be,
			for example, another libparted environment, EVMS, etc.
PedConstraint		a constraint on the geometry of a partition
PedDevice		a storage device
PedDisk			a device + partition table
PedFileSystem		a filesystem, associated with a PedGeometry, NOT a
			PedPartition.
PedGeometry		a continious region on a device
PedPartition		a partition (basically PedGeometry plus some attributes)
PedTimer		a timer keeps track of progress and time

All functions return 0 (or NULL) on failure and non-zero (or non-NULL) on
success.  If a function fails, an exception is thrown.  This may be handled by
either an exception handler, or the calling function (see the section on
exceptions).

All objects should be considered read-only; they should only be modified by
calls to libparted's API.

-------------------------------------------------------------------------------
2	INITIALISING LIBPARTED
-------------------------------------------------------------------------------

Headers for libparted can be included with:

#include <parted/parted.h>

Parted automatically initialises itself via an __attribute__ ((constructor))
function.

However, you might want to set the exception handler with
ped_exception_set_handler().  libparted does come with a default exception
handler, if you're feeling lazy.

Here's a minimal example:

#include <parted/parted.h>

int
main()
{
	/* automatically initialized */
	ped_exception_set_handler(exception_handler);	/* see section 7 */
	return 0;
	/* automatically cleaned up */
}

-----------------------------------------------------------------------------
5	PEDGEOMETRY
-----------------------------------------------------------------------------

5.1	FIELDS
--------------

5.2	FUNCTIONS
-----------------


-----------------------------------------------------------------------------
6	PEDPARTITION, PEDPARTITIONTYPE
-----------------------------------------------------------------------------

interface:		<parted/disk.h>
implementation:		libparted/disk.c

A PedPartition represents a partition (surprise!).  PedPartitions have weird
relationships with PedDisks.  Hence, many functions for manipulating partitions
will be called ped_disk_* - so have a look at the PedDisk documentation as well.

Parted creates "imaginary" free space and metadata partitions.  You can't
do any operations on these partitions (like set_geometry, {set,get}_flag, etc.)
Partitions that are not free space or metadata partitions are said to
be "active" partitions.  You can use ped_partition_is_active() to check.

6.1	FIELDS
--------------


6.2	FUNCTIONS
-----------------


-----------------------------------------------------------------------------
7	PEDFILESYSTEM, PEDFILESYSTEMTYPE
-----------------------------------------------------------------------------


7.1	FIELDS
--------------


7.2	FUNCTIONS
-----------------


-----------------------------------------------------------------------------
8	PEDCONSTRAINT, PEDALIGNMENT
-----------------------------------------------------------------------------


"Alignments" are restrictions on the location of a sector in the form of:

	sector = offset + X * grain_size

For example, logical partitions on msdos disk labels usually have a constraint
with offset = 63 and grain_size = 16065 (Long story!).  An important
(and non-obvious!) property of alignment restrictions is they are closed
under intersection,  i.e. if you take two constraints, like (offset, grain_size)
= (63, 16065) and (0, 4), then either:
  * there are no valid solutions
  * all solutions can be expressed in the form of (offset + X * grain_size)
In the example, the intersection of the constraint is (16128, 64260).

For more information on the maths, see the source -- there's a large comment
containing proofs above ped_alignment_intersect() in libparted/natmath.c

The restrictions on the location of the start and end are in the form of
PedGeometry objects -- continous regions in which the start and end must lie.
Obviously, these restrictions are also closed under intersection.

The other restriction -- the minimum size -- is also closed under intersection.
(The intersection of 2 minimum size restrictions is the maximum of the
2 values)

FIXME: mention ped_alignment_any

8.2	FUNCTIONS
-----------------



-----------------------------------------------------------------------------
9	PEDTIMER
-----------------------------------------------------------------------------

9.1	FIELDS
--------------

typedef void PedTimerHandler (PedTimer* timer, void* context);


9.2	FUNCTIONS
-----------------


-----------------------------------------------------------------------------
10	PEDUNIT
-----------------------------------------------------------------------------


10.1	CONSTANTS
-----------------

10.2	FUNCTIONS
-----------------


-----------------------------------------------------------------------------
11	EXCEPTIONS
-----------------------------------------------------------------------------

11.1	FIELDS
--------------