===============================================================================
                               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
          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.1
      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
--------------
struct _PedGeometry {
	PedDevice*              dev;
	PedSector               start;
	PedSector               length;
	PedSector               end;
};

5.2	FUNCTIONS
-----------------
int ped_geometry_test_inside (PedGeometry* a, PedGeometry* b);
	Tests if "b" lies completely within "a".  That is, they lie on the same
	physical device, and all of the "b"'s region is contained inside
	"a"'s.

int ped_geometry_test_equal (PedGeometry* a, PedGeometry* b);
	Tests if "a" and "b" refer to the same physical region.

int ped_geometry_test_sector_inside (const PedGeometry* geom, PedSector sect)
	Tests if sect is inside geom.

int ped_geometry_read (PedGeometry* geom, void* buffer, PedSector offset,
		       PedSector count)
	Reads data from the region represented by "geom".  "offset" is the
	location from within the region, not from the start of the disk.
	"count" sectors are read into "buffer".
		This is essentially equivalent to:

	ped_device_read (geom->disk->dev, buffer, geom->start + offset, count)

	Returns 0 on failure.

int ped_geometry_write (PedGeometry* geom, void* buffer, PedSector offset,
			PedSector count)
	Writes data into the region represented by "geom".  "offset" is the
	location from within the region, not from the start of the disk.
	"count" sectors are written.  Returns 0 on failure.

PedSector ped_geometry_check (PedGeometry* geom, void* buffer,
			      PedSector buffer_size, PedSector offset,
			      PedSector granularity, PedSector count)
	Checks a region for physical defects on "geom".  "buffer" is used
	for temporary storage for ped_geometry_check(), and has an undefined
	value.  "buffer" is "buffer_size" sectors long.
		The region checked starts at "offset" sectors inside the
	region represented by "geom", and is "count" sectors long.
	The first bad sector is returned, or 0 if there were no physical
	errors.
		"granularity" specificies how sectors should be grouped
	together.  The first bad sector to be returned will always be in
	the form:
		offset + n * granularity

int ped_geometry_sync (PedGeometry* geom)
	Flushes the cache on "geom".  Returns 0 on failure.

int ped_geometry_sync_fast (PedGeometry* geom)
	Flushes the cache on "geom". Doesn't ensure consistency between
	partitions and device caches of the operating system.
	Returns 0 on failure.

PedSector ped_geometry_map (PedGeometry* dst, PedGeometry* src,
			    PedSector sector)
	If "src" and "dst" overlap, and "sector" on "src" also exists on
	"dst", then the equivalent sector is retruned.
		Returns -1 if "sector" is not within "dst"'s space.

-----------------------------------------------------------------------------
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
--------------
typedef enum {
	PED_PARTITION_NORMAL		= 0x00,
	PED_PARTITION_LOGICAL		= 0x01,
	PED_PARTITION_EXTENDED		= 0x02,
	PED_PARTITION_FREESPACE		= 0x04,
	PED_PARTITION_METADATA		= 0x08
} PedPartitionType;

typedef enum {
	PED_PARTITION_BOOT=1,
	PED_PARTITION_ROOT=2,
	PED_PARTITION_SWAP=3,
	PED_PARTITION_HIDDEN=4,
	PED_PARTITION_RAID=5,
	PED_PARTITION_LVM=6,
	PED_PARTITION_LBA=7
} PedPartitionFlag;
#define PED_PARTITION_FIRST_FLAG        PED_PARTITION_BOOT
#define PED_PARTITION_LAST_FLAG         PED_PARTITION_LBA

struct _PedPartition {
	PedPartition*           prev;
	PedPartition*           next;

        PedDisk*                disk;
	PedGeometry             geom;
	int                     num;

	PedPartitionType        type;
	const PedFileSystemType* fs_type;
	PedPartition*           part_list;      /* for extended partitions */

	void*			disk_specific;
};

Useful fields:
PedDisk*        disk		the partition table of the partition
PedGeometry     geom		geometry of the partition
int		num		the partition number.  In Linux, this is the
				same as the minor number.  No assumption should
				be made about "num" and "type" - different
				disk labels have different rules.
PedPartitionType  type		the type of partition: a bit field of
				PED_PARTITION_LOGICAL, PED_PARTITION_EXTENDED,
				PED_PARTITION_METADATA and
				PED_PARTITION_FREESPACE.  Both the first two,
				and the last two are mutually exclusive.
					An extended partition is a
				primary partition that may contain logical
				partitions.  There is at most one extended
				partition on a disk.
					A logical partition is like a primary
				partition, except it's inside an extended
				partition.
					Internally, pseudo partitions are
				allocated to represent free space, or disk
				label meta-data.  These have the
				PED_PARTITION_FREESPACE or
				PED_PARTITION_METADATA bit set.
PedPartition*	part_list	Only used for an extended partition.  The list
				of logical partitions (and free space and
				metadata within the extended partition).
PedFileSystemType*  fs_type	The type of file system on the partition.
				NULL if unknown.

6.2	FUNCTIONS
-----------------
void ped_partition_destroy (PedPartition* part)
	Destroys a partition.  Should not be called on a partition that is
	in a partition table.  Use ped_disk_delete_partition() instead.

const char* ped_partition_get_name (const PedPartition* part)
	Returns the name of a partition.  This will only work if the disk label
        supports it.
		Note: the returned string should not be modified.  It should
	not be referenced after the partition is destroyed.

const char* ped_partition_type_get_name (PedPartitionType part_type)
	Returns a name that seems mildly appropriate for a partition type.  Eg,
	if you pass (PED_PARTITION_LOGICAL & PED_PARTITION_FREESPACE), it
	will return "free".  This isn't to be taken too seriously - it's just
	useful for user interfaces, so you can show the user something ;-)
		NOTE: the returned string will be in English.  However,
	translations are provided, so the caller can call
	dgettext("parted", RESULT) on the result.

const char* ped_partition_flag_get_name (PedPartitionFlag flag)
	Returns a name for a flag, e.g. PED_PARTITION_BOOT will return
	"boot".
		NOTE: the returned string will be in English.  However,
	translations are provided, so the caller can call
	dgettext("parted", RESULT) on the result.

PedPartitionFlag ped_partition_flag_get_by_name (const char* name)
	Returns the flag associated with "name".  "name" can be the English
	string, or the translation for the native language.

PedPartitionFlag ped_partition_flag_next (PedPartitionFlag flag)
	Iterates through all flags.  Returns the next flag.
	ped_partition_flag_next(0) returns the first flag.  Returns 0 if there
	are no more flags.

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

interface:		<parted/filesys.h>
implementation:		libparted/filesys.c,
			each file system type in fs_<file system name>

File systems exist on a PedGeometry - NOT a PedPartition.


7.1	FIELDS
--------------
struct _PedFileSystemType {
	PedFileSystemType*	next;
	const char* const	name;
	PedFileSystemOps* const	ops;
};

Useful fields:
char*		name		name of the file system type

struct _PedFileSystem {
        PedFileSystemType*      type;
        PedGeometry*            geom;
        int                     checked;

        void*                   type_specific;
};

Useful fields:
PedFileSystemType*      type    the file system type
PedGeometry*	geom		where the file system actually is.
int             checked	        1 if the file system has been checked. 0
                                otherwise.

7.2	FUNCTIONS
-----------------
PedFileSystemType* ped_file_system_type_get (char* name)
	Returns the PedFileSystemType with name "name".  If none is found,
	returns NULL.

PedFileSystemType* ped_file_system_type_get_next (PedFileSystemType* fs_type)
	Returns the next PedFileSystemType, after "fs_type".  If "fs_type"
	is the last one registered, returns NULL.

PedFileSystemType* ped_file_system_probe (PedGeometry* geom)
	Attempts to detect a file system on "geom".  If successful, returns
	the PedFileSystemType.  Otherwise, returns NULL.

PedGeometry* ped_file_system_probe_specific (const PedFileSystemType* fs_type,
                                             PedGeometry* geom)
        Probes for a particular type of file system, returning the region
        the file system believes it occupies.  Returns NULL if that file
        system wasn't detected.

int ped_file_system_clobber (PedGeometry* geom)
	Destroys all file system signatures, so that it won't be probed with
	ped_file_system_probe().  Note: ped_file_system_create() calls this
	before creating a new file system.

PedFileSystem* ped_file_system_open (PedGeometry* geom)
	Opens a filesystem on "geom".  Returns a PedFileSystem object if
	successful.  Returns NULL on failure.  
	This is often called in the following manner:
		fs = ped_file_system_open (&part.geom)

PedFileSystem* ped_file_system_create (PedGeometry* geom,
				       PedFileSystemType* type,
                                       PedTimer* timer)
	Creates a new file system, and returns a PedFileSystem representing it.
	Returns NULL on failure.  If "timer" is non-NULL, it is used as
        the progress meter.

int ped_file_system_close (PedFileSystem* fs)
	Closes "fs".  Returns 0 on failure.

int ped_file_system_check (PedFileSystem* fs, PedTimer* timer)
	Checks "fs" for errors.  Returns 0 on failure (i.e. unfixed errors).

PedFileSystem* ped_file_system_copy (PedFileSystem* fs, PedGeometry* geom,
                                     PedTimer* timer)
	Creates a new file system (of the same type) on "geom", and
	copies the contents of "fs" into the new filesystem.  The new
        file system is returned (NULL on failure).  If "timer" is non-NULL,
        it is used as the progress meter.

int ped_file_system_resize (PedFileSystem* fs, PedGeometry* geom,
                            PedTimer* timer)
	Resizes "fs" to new geometry "geom".  Returns 0 on failure.  Note:
	"geom" should satisfy the ped_file_system_get_resize_constraint().
        (This isn't asserted, so it's not a bug not to... just it's likely
        to fail ;)  If "timer" is non-NULL, it is used as the progress meter.

PedConstraint* ped_file_system_get_create_constraint (
                const PedFileSystemType* fs_type, const PedDevice* dev)
	Returns the constraint on creating the a file system of "fs_type" on
	"dev" with ped_file_system_create().

PedConstraint* ped_file_system_get_resize_constraint (const PedFileSystem* fs)
	Returns a constraint, that represents all of the possible ways the
	file system can be resized with ped_file_system_resize().  Hints:
	* if constraint->start_align->grain_size == 0, or
	constraint->start_geom->length == 1, then the start can not be moved
	* constraint->min_size is the minimum size you can resize the partition
	to.  You might want to tell the user this ;-).

PedConstraint* ped_file_system_get_copy_constraint (
                const PedFileSystem* fs, const PedDevice* dev)
	Returns the constraint on copying "fs" with ped_file_system_copy()
        to somewhere on "dev".

-----------------------------------------------------------------------------
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
-----------------

PedGeometry* ped_constraint_solve_nearest (
        	const PedConstraint* constraint, const PedGeometry* geom)
	Solves "constraint" returning the nearest to "geom".  If there is no
	solution, NULL is returned.


int ped_alignment_init (PedAlignment* align, PedSector offset,
                        PedSector grain_size)

PedAlignment* ped_alignment_new (PedSector offset, PedSector grain_size)
	Returns an alignment object (used by PedConstraint), representing all
	PedSector's that are of the form "offset + X * grain_size".

void ped_alignment_destroy (PedAlignment* align)
	Frees up memory associated with "align".

PedAlignment* ped_alignment_duplicate (const PedAlignment* align)
	Returns a duplicate of "align".

PedAlignment* ped_alignment_intersect (const PedAlignment* a,
		const PedAlignment* b)
	Returns a PedAlignment object, such that a PedSector is a solution,
	if and only if it is a solutin to "a" and "b".  Note: if there are no
	solutions (i.e. no PedSector satisfies both "a" and "b"), then NULL
	is returned.  NULL is a valid PedAlignment object, and can be used
	for ped_alignment_*() function.

PedSector ped_alignment_align_up (const PedAlignment* align,
		const PedGeometry* geom, PedSector sector)
	Returns the closest PedSector to "sector", that lies within "geom" and
	satisfies the "align" restriction, or -1 if there is no such PedSector.
	PedSector's that are not smaller than "sector" are always considered
	closer.

PedSector ped_alignment_align_down (const PedAlignment* align,
		const PedGeometry* geom, PedSector sector)
	Returns the closest PedSector to "sector", that lies within "geom" and
	satisfies the "align" restriction, or -1 if there is no such PedSector.
	PedSector's that are not larger than "sector" are always considered
	closer.

PedSector ped_alignment_align_nearest (const PedAlignment* align,
		const PedGeometry* geom, PedSector sector)
	Returns the closest PedSector to "sector" that lies within "geom" and
	satisfies the "align" restriction, or -1 if there is no such PedSector.

int ped_alignment_is_aligned (const PedAlignment* align,
		const PedGeometry* geom, PedSector sector)
	Returns 1 if "sector" lies within "geom" and satisfies the "align"
	restriction, and 0 otherwise.

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

A PedTimer keeps track of the progress of a single (possibly compound)
operation.  The user of libparted constructs a PedTimer, and passes it
to libparted functions that are likely to be expensive operations
(like ped_file_system_resize).  Use of timers is optional... you may
pass NULL instead.

When you create a PedTimer, you must specify a timer handler function.
This will be called when there's an update on how work is progressing.

Timers may be nested.  When a timer is constructed, you can choose
to assign it a parent, along with an estimate of what proportion of
the total (parent's) time will be used in the nested operation.  In
this case, the nested timer's handler is internal to libparted,
and simply updates the parent's progress, and calls its handler.

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

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

struct _PedTimer {
        float                   frac;           /* fraction of operation done */        time_t                  start;          /* time of start of op */
        time_t                  now;            /* time of last update (now!) */        time_t                  predicted_end;  /* expected finish time */
        const char*             state_name;     /* eg: "copying data" */
        PedTimerHandler*        handler;        /* who to notify on updates */
        void*                   context;        /* context to pass to handler */};

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

PedTimer* ped_timer_new (PedTimerHandler* handler, void* context)
        Creates a timer.  Context will be passed in the "context"
        argument in the handler, when it is invoked.

void ped_timer_destroy (PedTimer* timer)
        Destroys a timer.

PedTimer* ped_timer_new_nested (PedTimer* parent, float nest_frac)
        Creates a new nested timer.  "parent" is the parent timer,
        and "nested_frac" is the estimated proportion (between 0 and 1)
        of the time that will be spent doing the nested timer's operation.
        The timer should only be constructed immediately prior to
        starting the nested operation.  (It will be inaccurate, otherwise)

void ped_timer_destroy_nested (PedTimer* timer)
        Destroys a nested timer.

void ped_timer_touch (PedTimer* timer)
        INTERNAL.  Updates timer->now and recomputes timer->predicted_end, and
        calls the handler.

void ped_timer_reset (PedTimer* timer)
        INTERNAL.  Resets the timer, by setting timer->start and timer->now
        to the current time.

void ped_timer_update (PedTimer* timer, float new_frac)
        INTERNAL.  Sets the new timer->frac, and calls ped_timer_touch().

void ped_timer_set_state_name (PedTimer* timer, const char* state_name)
        INTERNAL.  Sets a new name for the current "phase" of the operation,
        and calls ped_timer_touch().

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

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

The PedUnit module provides a standard mechanism for describing and parsing
locations within devices in human-friendly plain text.  Internally, libparted
uses PedSector (which is typedef'ed to be long long in <parted/device.h>) to
describe device locations such as the start and end of partitions.  However,
sector numbers are often long and unintuitive.  For example, my extended
partition starts at sector 208845.  PedUnit allows this location to be
represented in more intutitive ways, including "106Mb", "0Gb" and "0%", as well
as "208845s".  PedUnit aims to provide facilities to provide a consistent
system for describing device locations all throughout libparted.

PedUnit provides two basic services: converting a PedSector into a text
representation, and parsing a text representation into a PedSector.
PedUnit currently supports these units:

	sectors, bytes, kilobytes, megabytes, gigabytes, terabytes, compact,
	cylinder and percent.

PedUnit has a global variable that contains the default unit for all
conversions.

10.1	CONSTANTS
-----------------
typedef enum {
	PED_UNIT_SECTOR,
	PED_UNIT_BYTE,
	PED_UNIT_KILOBYTE,
	PED_UNIT_MEGABYTE,
	PED_UNIT_GIGABYTE,
	PED_UNIT_TERABYTE,
	PED_UNIT_COMPACT,
	PED_UNIT_CYLINDER,
	PED_UNIT_PERCENT
} PedUnit;

10.2	FUNCTIONS
-----------------
const char* ped_unit_get_name (PedUnit unit)
	Returns a textual representation of "unit".  For example, the textual
	representation of PED_UNIT_SECTOR is "s".  This is not
	internationalized.

PedUnit ped_unit_get_by_name (const char* unit_name)
	Returns a unit based on its textual representation.  For example,
	ped_unit_get_by_name("Mb") returns PED_UNIT_MEGABYTE.

void ped_unit_set_default (PedUnit unit)
	Sets the default unit.

PedUnit ped_unit_get_default ()
	Returns the default unit.

char* ped_unit_format_byte (PedDevice* dev, PedSector byte)
	Returns a string that describes the location of the "byte" on device
	"dev".  The string is described with the default unit, which is set
	by ped_unit_set_default().  The returned string must be freed with
	ped_free().

char* ped_unit_format_custom_byte (PedDevice* dev, PedSector byte,
				   PedUnit unit)
	Returns a string that describes the location of the "byte" on device
	"dev".  The string is described with the desired unit.  The returned
	string must be freed with ped_free().

char* ped_unit_format (PedDevice* dev, PedSector sector)
	Returns a string that describes the location "sector" on device "dev".
	The string is described with the default unit, which is set by
	ped_unit_set_default().  The returned string must be freed with
	ped_free().

char* ped_unit_format_custom (PedDevice* dev, PedSector sector, PedUnit unit)
	Returns a string that describes the location "sector" on device "dev".
	The string is described with the desired unit.  The returned string
	must be freed with ped_free().

int ped_unit_parse (const char* str, PedDevice* dev, PedSector *sector,
		    PedGeometry** range)
	If str contains a valid description of a location on dev, then *sector
	is modified to describe the location and a geometry is created in
	*range describing a 2 units large area centered on *sector.  If the
	range as described here would be partially outside the device, the
	geometry returned is the intersection between the former and the whole
	device geometry.  If no units are specified, then the default unit is
	assumed.  This function returns 1 if str is a valid location
	description, and 0 otherwise.

int ped_unit_parse_custom (const char* str, PedDevice* dev, PedUnit unit,
			   PedSector *sector, PedGeometry** range)
	If str contains a valid description of a location on dev, then *sector
	is modified to describe the location and a geometry is created in
	*range describing a 2 units large area centered on *sector.  If the
	range as described here would be partially outside the device, the
	geometry returned is the intersection between the former and the whole
	device geometry.  If no units are specified, then the desired unit is
	assumed.  This function returns 1 if str is a valid location
	description, and 0 otherwise.


-----------------------------------------------------------------------------
11	EXCEPTIONS
-----------------------------------------------------------------------------
There are a few types of exceptions: PED_EXCEPTION_INFORMATION,
PED_EXCEPTION_WARNING, PED_EXCEPTION_ERROR, PED_EXCEPTION_FATAL,
PED_EXCEPTION_BUG.


11.1	FIELDS
--------------
enum _PedExceptionType {
	PED_EXCEPTION_INFORMATION=1,
	PED_EXCEPTION_WARNING=2,
	PED_EXCEPTION_ERROR=3,
	PED_EXCEPTION_FATAL=4,
	PED_EXCEPTION_BUG=5,
	PED_EXCEPTION_NO_FEATURE=6
};
typedef enum _PedExceptionType PedExceptionType;

enum _PedExceptionOption {
	PED_EXCEPTION_UNHANDLED=0,
	PED_EXCEPTION_FIX=1,
	PED_EXCEPTION_YES=2,
	PED_EXCEPTION_NO=4,
	PED_EXCEPTION_OK=8,
	PED_EXCEPTION_RETRY=16,
	PED_EXCEPTION_IGNORE=32,
	PED_EXCEPTION_CANCEL=64,
};
typedef enum _PedExceptionOption PedExceptionOption;

struct _PedException {
	char*			message;
	PedExceptionType	type;
	PedExceptionOption	options;
};

PedExceptionType	type		the type of exception
PedExceptionOption	options		the ways an exception can be resolved

