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

      Copyright (C) 1999-2000 Andrew Clausen

      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
1.1	Terminology
1.2	Design

2	Initialising libparted

3	PedDevice
3.1	Fields
3.2	Functions

4	PedDisk, PedDiskType
4.1	Fields
4.2	Functions

5	PedGeometry
5.1	Fields
5.2	Functions

6	PedPartition, PedPartitionType
6.1	Fields
6.2	Functions

7	PedFileSystem, PedFileSystemType
7.1	Fields
7.2	Functions

8	Exceptions
8.1	Fields
8.2	Functions

-------------------------------------------------------------------------------
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
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 the
parted/parted.c - the front-end's source, and the TUTORIAL file (not finished
yet!).

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

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 lie inside the extended
			partition.

PARTITION		a continous 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.

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

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)

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 be
either an exception handler, or the calling function (see section on
exceptions)

All objects are read-only.  They should only be modified by calls to API
functions.

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

Headers for libparted can be included with:

#include <parted/parted.h>

Before any API functions are called, ped_init() must called.  There is one
exception: you can set the exception handler with ped_exception_set_handler(),
beforehand, so if there's an error in ped_init(), it can be handled properly.
libparted does come with a default exception handler, if you're feeling lazy.

Before the program terminates, ped_done() must be called.  Otherwise, nasty
things can happen, like the partition table not being re-read by the kernel...

Here's a minimal example:

#include <parted/parted.h>

int
main()
{
	ped_exception_set_handler(exception_handler);	/* see section 7 */
	ped_init();
	ped_done();
	return 0;
}

-----------------------------------------------------------------------------
3	PEDDEVICE
-----------------------------------------------------------------------------

interface:		<parted/device.h>
implementation:		libparted/device.c, libparted/llseek.c.

When ped_device_probe_all() is called, libparted attempts to detect all
devices.  It constructs a list, which can be accessed with
ped_device_get_next().

3.1	FIELDS
--------------
#define PED_SECTOR_SIZE         512
typedef long long PedSector;

typedef enum {
	PED_DEVICE_UNKNOWN      = 0,
	PED_DEVICE_SCSI         = 1,
	PED_DEVICE_IDE          = 2,
	PED_DEVICE_DAC960       = 3
} PedDeviceType;

typedef struct _PedDevice PedDevice;

struct _PedDevice {
	PedDevice*      next;

	char*           model;
	char*           path;

	PedDeviceType   type;
	int             sector_size;
	int             heads, sectors, cylinders;
	int		geom_known;
	short           host, did;
	PedSector       length;

	int             open_count;
	int             dirty;
#ifndef __MSDOS__
	int             fd;
#endif
};

Useful fields are:

char*		model		A description of the hardware manufacturer and
				model

char*		path		Usually the block device.  Eg. /dev/sdb

PedSector	length		The size of the device, in sectors

3.2	FUNCTIONS
-----------------

void ped_device_probe_all ()
	Attempts to detect all devices.

void ped_device_free_all ()
	Closes/frees up all devices.  Called by ped_done(), so  you need not
	worry about it.

PedDevice* ped_device_get (char* name)
	Gets the device "name", where name is usually the block device (eg
	/dev/sdb).  If the device wasn't detected with ped_device_probe_all(),
	an attempt will be made to detect it again.

PedDevice* ped_device_get_next (PedDevice* dev)
	Returns the next device that was detected by ped_device_probe_all(), or
	calls to ped_device_get_next().  If dev is NULL, returns the first
	device.  Returns NULL if dev is the last device.

int ped_device_open (PedDevice* dev)
	INTERNAL:  Attempts to open dev, to allow use uf ped_device_read(),
	ped_device_write() and ped_device_sync().  Returns zero on failure.

int ped_device_close (PedDevice* dev)
	INTERNAL: Closes dev.  Returns zero on failure.

int ped_device_read (PedDevice* dev, void* buffer, PedSector start,
                     PedSector count)
	INTERNAL: Reads count sectors, beginning with sector start, from dev.
	Returns zero on failure.

int ped_device_write (PedDevice* dev, void* buffer, PedSector start,
                      PedSector count)
	INTERNAL: Writes count sectors, beginning with sector start, from dev.
	Returns zero on failure.

int ped_device_sync (PedDevice* dev)
	INTERNAL: Flushes the write cache.
	Returns zero on failure.

-----------------------------------------------------------------------------
4	PEDDISK, PEDDISKTYPE
-----------------------------------------------------------------------------

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

Most programs will need to use ped_disk_open() or ped_disk_create() to get
anything done.  A PedDisk is always associated with a device, and has a
partition table.  There are different types of partition tables (or disk
labels).  These are represented by PedDiskType's.

4.1	FIELDS
--------------

struct _PedDiskType {
	PedDiskType*            next;
	char*                   name;
	PedDiskOps*             ops;

/* office use only ;-) */
	int			update_mode;
};

Useful fields are:
char*		name		the name of the partition table type.

struct _PedDisk {
	PedDevice*              dev;
	PedDiskType*            type;
	PedPartition*           part_list;
};

Useful fields are:
PedDiskType*    type		the type of disk label
PedPartition*   part_list	this is the list of partitions on the disk.
				It should be accessed with
				ped_disk_next_partition()

4.2	FUNCTIONS
-----------------

PedDiskType* ped_disk_type_get_next (PedDiskType* type)
	Returns the next disk type registers, after "type".  If "type" is
	NULL, returns the first disk type.  If "type" is the last registered
	disk type, returns NULL.

PedDiskType* ped_disk_type_get (char* name)
	Returns the disk type with a name of "name".  If there are none,
	returns NULL.

PedDisk* ped_disk_open (PedDevice* dev)
	Constructs a PedDisk object from dev, and reads the partition table.
	Returns zero on failure.
	WARNING: this can modify dev->cylinders, dev->heads and dev->sectors,
	because the partition table might indicate that the existing values
	were incorrect.

PedDisk* ped_disk_create (PedDevice* dev, PedDiskType* type)
	Creates a partition table on dev, and constructs a PedDisk object for
	it.  Returns NULL on failure.

int ped_disk_close (PedDisk* disk)
	Closes "disk".  Returns 0 on failure.

int ped_disk_read (PedDisk* disk)
	Reads the partition table "disk".  Returns 0 on failure.

int ped_disk_write (PedDisk* disk)
	Writes the partition table to "disk".  Returns 0 on failure.

int ped_disk_add_partition (PedDisk* disk, PedPartition* part)
	Adds "part" to "disk".  "part"'s geometry may be changed in this
	process.  Sorry, I know this is bad, but there is no other way.  Some
	brain-dead partition table systems, not mentionioning any
	Micros^H^H^H^H^H^Hnames require certain alignments which can't be
	pre-calculated.
		"part" is assigned a number in this process.
	Returns 0 on failure.

int ped_disk_delete_partition (PedDisk* disk, PedPartition* part)
	Removes "part" from "disk", and destroys "part".  Returns 0 on failure.

int ped_disk_delete_all (PedDisk* disk)
	Removes and destroys all partitions on "disk".  Returns 0 on failure.

int ped_disk_set_partition_geom (PedDisk* disk, PedPartition* part,
                                 PedSector start, PedSector end)
	Sets the geometry of "part".  This can fail for many reasons (eg:
	can't overlap with other partitions).  If it does fail, "part" will
	remain unchanged.  Returns 0 on failure.

int ped_disk_maximize_partition (PedDisk* disk, PedPartition* part)
	Grows "part"'s geometry to the maximum possible.  The new geometry
	will be a superset of the old geometry.  Returns 0 on failure.

int ped_disk_minimize_extended_partition (PedDisk* disk)
	Reduces the extended partition on "disk" to the minimum possible.
	Returns 0 on failure.

PedPartition* ped_disk_next_partition (PedDisk* disk, PedPartition* part)
	Returns the next partition after "part" on "disk".  If "part" is NULL,
	returns the first partition.  If "part" is the last partition, returns
	NULL.  If "part" is an extended partition, returns the first logical
	partition.
		If this is called repeatededly, passing the return value as
	"part", a depth-first traversal is executed.

PedPartition* ped_disk_get_partition (PedDisk* disk, int num)
	Returns the partition numbered "num".  If no such partition exists,
	returns NULL.

PedPartition* ped_disk_get_partition_by_sector (PedDisk* disk, PedSector sect)
	Returns the partition that 'owns' "sect".  If sect lies inside a
	logical partition

PedPartition* ped_disk_extended_partition (PedDisk* disk)
	Returns the extended partition, or NULL if there isn't one.

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

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

PedGeometry is created by ped_geometry_new(), from a PedDisk.  It represents
a continuous region on a device (i.e. disk->dev).  All addressing through
a PedGeometry object is in terms of the start of the continuous region.

Most programs will never need to create a PedGeometry object, or call any
of it's functions.

5.1	FIELDS
--------------
struct _PedGeometry {
	PedDisk*                disk;
	PedSector               start;
	PedSector               length;
	PedSector               end;
};

Useful fields:
PedDisk*        disk		the disk
PedSector       start		the start of the region, in sectors.  (one
				sector = 512 bytes)
PedSector       length		the length of the region, in sectors
PedSector       end		the end of the region, in sectors

5.2	FUNCTIONS
-----------------
PedGeometry* ped_geometry_new (PedDisk* disk, PedSector start, PedSector length)
	Creates a new PedGeometry object on "disk", starting at "start", of
	"length" sectors (units of 512 byte).  Returns NULL on failure.

PedGeometry* ped_geometry_duplicate (PedGeometry* geom)
	Duplicates a PedGeometry object.  Returns NULL on failure.

void ped_geometry_destroy (PedGeometry* geom)
	Destroys a PedGeometry object.

void ped_geometry_set (PedGeometry* geom, PedSector start, PedSector length)
	Assigns a new geom->start, geom->end and geom->length to "geom".
	geom->end is calculated from "start" and "length".

void ped_geometry_set_start (PedGeometry* geom, PedSector start)
	Assigns as new geom->start to "geom", without changing geom->end.
	geom->length is updated accordingly.

void ped_geometry_set_end (PedGeometry* geom, PedSector end);
	Assigns as new geom->end to "geom", without changing geom->start.
	geom->length is updated accordingly.

int ped_geometry_test_overlap (PedGeometry* a, PedGeometry* b)
	Tests if "a" overlaps with "b".  That is, they lie on the same
	physical device, and they share (some of) the same physical region.

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

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

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

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

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

6.1	FIELDS
--------------
typedef enum {
	PED_PARTITION_PRIMARY		= 0x00,
	PED_PARTITION_LOGICAL		= 0x01,
	PED_PARTITION_EXTENDED		= 0x02,
	PED_PARTITION_FREESPACE		= 0x04,
	PED_PARTITION_METADATA		= 0x08
} PedPartitionType;

struct _PedPartition {
	PedPartition*           prev;
	PedPartition*           next;

	PedGeometry             geom;
	int                     num;
	int                     hidden;

	PedPartitionType        type;
	PedPartition*           part_list;

	unsigned char           system;
	unsigned char           bootable;

	PedFileSystemType*      fs_type;
};

Useful fields:
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.
int             hidden          set to 1 if the partition is hidden.  See
				the introduction for information on HIDDEN
				PARTITIONS.
PedPartitionType  type		the type of partition: always one of
				PED_PARTITION_PRIMARY, PED_PARTITION_LOGICAL or
				PED_PARTITION_EXTENDED.
					A primary partition is a "normal"
				partition.  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)
unsigned char   system		The type of filesystem on the partition.
				This should be determined by
				ped_file_system_get_part_id().
unsigned char   bootable	Set if this partition should be the one that
				gets booted off.
PedFileSystemType*  fs_type	The type of file system on the partition.
				NULL if not known.

6.2	FUNCTIONS
-----------------
PedPartition* ped_partition_new (PedDisk* disk,
				 PedPartitionType type,
				 unsigned char system,
				 unsigned char bootable,
				 PedSector start, PedSector end)
	Creates a new PedPartition on "disk", starting at sector "start",
	and ending at "end".  "type" is one of PED_PARTITION_PRIMARY,
	PED_PARTITION_LOGICAL or PED_PARTITION_EXTENDED.  (PED_PARTITION_FREE
	and PED_PARTITION_METADATA are used internally).
		The new partition is NOT added to the disk's internal
	representation of the partition table.  Use ped_disk_add_partition()
	to do this.

PedPartition* ped_partition_duplicate (PedPartition* part)
	Duplicates a partition.  Returns NULL on failure.
		The new partition is NOT added to the disk's internal
	representation of the partition table.  Use ped_disk_add_partition()
	to do this.

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.

int ped_partition_is_active (PedPartition* part)
	Returns if the partition is "active".  If part->type is
	PED_PARTITION_METADATA or PED_PARTITION_FREE, then it's inactive.
	Otherwise, it's active.

int ped_partition_get_hide_state (PedPartition* part)
	Returns 1 if "part" is hidden, 0 otherwise.

int ped_partition_set_hide_state (PedPartition* part, int state)
	Hides ("state" == 1) or unhides ("state" == 0) "part".

int ped_partition_set_system (PedPartition* part, PedFileSystemType* fs_type)
	Sets the system type on the partition to be fs_type.  Note: the
	file system may be opened, to get more information about the
	file system.  Eg: to determine if it's FAT16 or FAT32.

int ped_partition_is_busy (PedPartition* part)
	Returns 1 if a partition is busy (i.e. mounted), 0 otherwise.

-----------------------------------------------------------------------------
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;
	char*			name;
	PedFileSystemOps*	ops;
};

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

struct _PedFileSystem {
	PedFileSystemType*	type;
	PedGeometry*		geom;
	void*			type_specific;
};

Useful fields:
PedGeometry*	geom		where the file system actually is.

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.

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 like this:
		fs = ped_file_system_open (&part.geom)

PedFileSystem* ped_file_system_create (PedGeometry* geom,
				       PedFileSystemType* type)
	Creates a new file system, and returns a PedFileSystem representing it.
	Returns NULL on failure.

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

int ped_file_system_check (PedFileSystem* fs)
	Checks "fs" for errors.  Returns 0 on failure.

int ped_file_system_copy (PedFileSystem* fs, PedGeometry* geom)
	Creates a new file system (of the same type) on "geom", and
	copies the contents of "fs" into the new filesystem. 
	Returns 0 on failure.

int ped_file_system_resize (PedFileSystem* fs, PedGeometry* geom)
	Resizes "fs" to new geometry "geom".  Returns 0 on failure.

PedSector ped_file_system_get_min_size (PedFileSystem* fs)
	Returns the minimum size that "fs" can be resized to, in sectors.

char ped_file_system_get_system (PedFileSystem* fs, PedDiskType* disk_type)
	INTERNAL: Returns the number that should be used for "fs" to say
	what file system type it is.

-----------------------------------------------------------------------------
8	EXCEPTIONS
-----------------------------------------------------------------------------

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

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

They are "thrown" when one of the above events occur while executing
a libparted function.  For example, if ped_device_open() fails, because the
device doesn't exist, an exception will be thrown.  Exceptions contain
text describeing what the event was.  In this case: the device
doesn't exist.
	It will give at least one option for resolving the exception:
PED_EXCEPTION_FIX, PED_EXCEPTION_YES, PED_EXCEPTION_NO, PED_EXCEPTION_OK,
PED_EXCEPTION_RETRY, PED_EXCEPTION_IGNORE, PED_EXCEPTION_CANCEL.
	After an exception is thrown, there are a two things that
can happen:
(1) an exception handler is called, which selects how the exception
should be resolved (usually by asking the user).
(2) the exception is not handled, because the caller of the function wants
to handle everything itself.

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

8.2	FUNCTIONS
-----------------
char* ped_exception_get_type_string (PedExceptionType ex_type)
	Returns a string describing an exception type.

char* ped_exception_get_option_string (PedExceptionOption ex_opt)
	Returns a string describing an exception option.

typedef PedExceptionOption (PedExceptionHandler) (PedException* ex);
void ped_exception_set_handler (PedExceptionHandler* handler)
	Sets the exception handler.  The exception handler should return
	ONE of the options set in ex->options, indicating the way the
	event should be resolved.

PedExceptionOption ped_exception_throw (PedExceptionType ex_type,
		PedExceptionOption ex_opt, const char* message, ...)
	INTERNAL: throws an exception.  You can also use this in a front-end
	to libparted.
		message is a printf like format string.  So you can do:
	ped_exception_throw (PED_EXCEPTION_ERROR, PED_EXCEPTION_RETRY_CANCEL,
			     "Can't open %s", file_name);
	Returns the option selected to resolve the exception.  If the exception
	was unhandled, PED_EXCEPTION_UNHANDLED is returned.

PedExceptionOption ped_exception_rethrow()
	Rethrows an unhandled exception.

void ped_exception_catch()
	Asserts that the exception has been resolved.

void ped_exception_fetch_all()
	Indicates that exceptions should not go to the exception handler, but
	passed up to the calling function(s).  All calls to
	ped_exception_throw() will return PED_EXCEPTION_UNHANDLED.

void ped_exception_leave_all()
	Indicate that the calling function does not want to accept any
	responsibilty for exceptions any more.  Note: a caller of that
	function may still want responsibility, so ped_exception_throw()
	may not invoke the exception handler.

