Edit File: 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 --------------