diff options
Diffstat (limited to 'doc/API')
| -rw-r--r-- | doc/API | 286 |
1 files changed, 286 insertions, 0 deletions
@@ -0,0 +1,286 @@ +=============================================================================== + 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 +-------------- |