doc/API

   1 ===============================================================================
   2                                GNU libparted API
   3 ===============================================================================
   4
   5
   6
   7
   8
   9
  10
  11
  12                 <<< This file is deprecated and being converted
  13                        to Doxygen in-line documentation.
  14                   Until this is finished, both are incomplete
  15                     but fully document the API together. >>>
  16
  17
  18                             ( scroll down to read )
  19
  20
  21
  22
  23
  24       by Andrew Clausen <clausen@gnu.org>,
  25          Leslie P. Polzer <polzer@gnu.org>
  26
  27       Copyright (C) 1999, 2000, 2001, 2002, 2003, 2005, 2006, 2007
  28       Free Software Foundation, Inc.
  29
  30       Permission is granted to copy, distribute and/or modify this document
  31       under the terms of the GNU Free Documentation License, Version 1.3
  32       or any later version published by the Free Software Foundation;
  33       with the no Invariant Sections, with the no Front-Cover Texts, and
  34       with no Back-Cover Texts.  A copy of the license is included in the
  35       file, COPYING.DOC.
  36
  37
  38 CONTENTS
  39 --------
  40
  41 1       Introduction
  42 2       Initialising libparted
  43 3       PedDevice
  44 4       PedDisk, PedDiskType
  45 5       PedGeometry
  46 6       PedPartition, PedPartitionType
  47 7       PedFileSystem, PedFileSystemType
  48 8       PedConstraint, PedAlignment
  49 9       PedTimer
  50 10      PedUnit
  51 11      Exceptions
  52
  53 -------------------------------------------------------------------------------
  54 1       INTRODUCTION
  55 -------------------------------------------------------------------------------
  56
  57 GNU Parted is built on top of libparted, which does all of the real work.
  58 libparted provides an API capable of manipulating partition tables, and
  59 the filesystems on them.
  60
  61 The main motivation for separating the back-end into a separate library was
  62 to encourage different GNU/Linux distributions to encorporate their own
  63 customized front-end into the install process.
  64
  65 This documents the API -- not the implementation details of libparted.
  66 Documentation that is not relevant to programs using the API are marked with
  67 INTERNAL.  Apart from this file, a good place to look would be
  68 parted/parted.c, the front-end's source, and the TUTORIAL file (not finished
  69 yet!).
  70
  71 This documentation isn't as complete as it should be.  Feel free to ask
  72 questions, either to me personally (clausen@gnu.org), or to the mailing list
  73 (bug-parted@gnu.org).
  74
  75 1.1     TERMINOLOGY
  76 -------------------
  77 Some of the terminology is a bit weird, so you might want to read this.
  78
  79 CONSTRAINT              a set of conditions that must be satisfied, for
  80                         a given GEOMETRY of a PARTITION.
  81
  82 DEVICE                  a storage device.
  83
  84 DISK                    a storage device, with a valid partition table.
  85
  86 EXCEPTION               an event that needs attention.
  87
  88 EXTENDED PARTITION      a PRIMARY PARTITION, that may contain LOGICAL
  89                         PARTITIONS instead of a file system.  There is at most
  90                         one extended partition.
  91
  92 FILE SYSTEM             any data that resides on a partition.  For the purposes
  93                         for GNU Parted, this includes swap devices.
  94
  95 GEOMETRY                a description of a continuous region on a disk.  eg,
  96                         partitions have a geometry.
  97
  98 HIDDEN PARTITION        a partition that is hidden from MS operating systems.
  99                         Only FAT partitions may be hidden.
 100
 101 LOGICAL PARTITION       like normal partitions, but they lie inside the
 102                         extended partition.
 103
 104 PARTITION               a continuous region on a disk where a file system may
 105                         reside.
 106
 107 PRIMARY PARTITION       a normal, vanilla, partition.
 108
 109 PARTITION TABLE         also, DISK LABEL.  A description of where the
 110                         partitions lie, and information about those partitions.
 111                         For example, what type of file system resides on them.
 112                         The partition table is usually at the start of the
 113                         disk.
 114
 115 TIMER                   a progress meter.  It is an entity that keeps track
 116                         of time, and who to inform when something interesting
 117                         happens.
 118
 119 1.2     DESIGN
 120 --------------
 121 libparted has a fairly object-oriented design.  The most important objects are:
 122
 123 PedArchitecture         describes support for an "archicture", which is sort
 124                         of like "operating system", but could also be,
 125                         for example, another libparted environment, EVMS, etc.
 126 PedConstraint           a constraint on the geometry of a partition
 127 PedDevice               a storage device
 128 PedDisk                 a device + partition table
 129 PedFileSystem           a filesystem, associated with a PedGeometry, NOT a
 130                         PedPartition.
 131 PedGeometry             a continious region on a device
 132 PedPartition            a partition (basically PedGeometry plus some attributes)
 133 PedTimer                a timer keeps track of progress and time
 134
 135 All functions return 0 (or NULL) on failure and non-zero (or non-NULL) on
 136 success.  If a function fails, an exception is thrown.  This may be handled by
 137 either an exception handler, or the calling function (see the section on
 138 exceptions).
 139
 140 All objects should be considered read-only; they should only be modified by
 141 calls to libparted's API.
 142
 143 -------------------------------------------------------------------------------
 144 2       INITIALISING LIBPARTED
 145 -------------------------------------------------------------------------------
 146
 147 Headers for libparted can be included with:
 148
 149 #include <parted/parted.h>
 150
 151 Parted automatically initialises itself via an __attribute__ ((constructor))
 152 function.
 153
 154 However, you might want to set the exception handler with
 155 ped_exception_set_handler().  libparted does come with a default exception
 156 handler, if you're feeling lazy.
 157
 158 Here's a minimal example:
 159
 160 #include <parted/parted.h>
 161
 162 int
 163 main()
 164 {
 165         /* automatically initialized */
 166         ped_exception_set_handler(exception_handler);   /* see section 7 */
 167         return 0;
 168         /* automatically cleaned up */
 169 }
 170
 171 -----------------------------------------------------------------------------
 172 5       PEDGEOMETRY
 173 -----------------------------------------------------------------------------
 174
 175 5.1     FIELDS
 176 --------------
 177
 178 5.2     FUNCTIONS
 179 -----------------
 180
 181
 182 -----------------------------------------------------------------------------
 183 6       PEDPARTITION, PEDPARTITIONTYPE
 184 -----------------------------------------------------------------------------
 185
 186 interface:              <parted/disk.h>
 187 implementation:         libparted/disk.c
 188
 189 A PedPartition represents a partition (surprise!).  PedPartitions have weird
 190 relationships with PedDisks.  Hence, many functions for manipulating partitions
 191 will be called ped_disk_* - so have a look at the PedDisk documentation as well.
 192
 193 Parted creates "imaginary" free space and metadata partitions.  You can't
 194 do any operations on these partitions (like set_geometry, {set,get}_flag, etc.)
 195 Partitions that are not free space or metadata partitions are said to
 196 be "active" partitions.  You can use ped_partition_is_active() to check.
 197
 198 6.1     FIELDS
 199 --------------
 200
 201
 202 6.2     FUNCTIONS
 203 -----------------
 204
 205
 206 -----------------------------------------------------------------------------
 207 7       PEDFILESYSTEM, PEDFILESYSTEMTYPE
 208 -----------------------------------------------------------------------------
 209
 210
 211 7.1     FIELDS
 212 --------------
 213
 214
 215 7.2     FUNCTIONS
 216 -----------------
 217
 218
 219 -----------------------------------------------------------------------------
 220 8       PEDCONSTRAINT, PEDALIGNMENT
 221 -----------------------------------------------------------------------------
 222
 223
 224 "Alignments" are restrictions on the location of a sector in the form of:
 225
 226         sector = offset + X * grain_size
 227
 228 For example, logical partitions on msdos disk labels usually have a constraint
 229 with offset = 63 and grain_size = 16065 (Long story!).  An important
 230 (and non-obvious!) property of alignment restrictions is they are closed
 231 under intersection,  i.e. if you take two constraints, like (offset, grain_size)
 232 = (63, 16065) and (0, 4), then either:
 233   * there are no valid solutions
 234   * all solutions can be expressed in the form of (offset + X * grain_size)
 235 In the example, the intersection of the constraint is (16128, 64260).
 236
 237 For more information on the maths, see the source -- there's a large comment
 238 containing proofs above ped_alignment_intersect() in libparted/natmath.c
 239
 240 The restrictions on the location of the start and end are in the form of
 241 PedGeometry objects -- continous regions in which the start and end must lie.
 242 Obviously, these restrictions are also closed under intersection.
 243
 244 The other restriction -- the minimum size -- is also closed under intersection.
 245 (The intersection of 2 minimum size restrictions is the maximum of the
 246 2 values)
 247
 248 FIXME: mention ped_alignment_any
 249
 250 8.2     FUNCTIONS
 251 -----------------
 252
 253
 254
 255 -----------------------------------------------------------------------------
 256 9       PEDTIMER
 257 -----------------------------------------------------------------------------
 258
 259 9.1     FIELDS
 260 --------------
 261
 262 typedef void PedTimerHandler (PedTimer* timer, void* context);
 263
 264
 265 9.2     FUNCTIONS
 266 -----------------
 267
 268
 269 -----------------------------------------------------------------------------
 270 10      PEDUNIT
 271 -----------------------------------------------------------------------------
 272
 273
 274 10.1    CONSTANTS
 275 -----------------
 276
 277 10.2    FUNCTIONS
 278 -----------------
 279
 280
 281 -----------------------------------------------------------------------------
 282 11      EXCEPTIONS
 283 -----------------------------------------------------------------------------
 284
 285 11.1    FIELDS
 286 --------------