[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[patch] doc/API
|
From: |
Neal H Walfield |
|
Subject: |
[patch] doc/API |
|
Date: |
Tue, 14 Aug 2001 10:11:29 +0200 |
|
User-agent: |
Mutt/1.3.18i |
This patch fixes a variety of mistakes and a few technical errors in the
documentation. It also does a small update on the ped_disk
functionality.
Here is a change log entry:
2001-08-14 Neal H Walfield <address@hidden>
* doc/API: Fix errors.
Update section the section on ped_disk.
diff --exclude aclocal.m4 --exclude configure --exclude Makefile.in -urNp
parted-1.5.4-pre1.orig/doc/API parted-1.5.4-pre1/doc/API
--- parted-1.5.4-pre1.orig/doc/API Wed Jun 13 07:04:21 2001
+++ parted-1.5.4-pre1/doc/API Mon Aug 13 18:44:02 2001
@@ -33,16 +33,16 @@ CONTENTS
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 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.
+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
+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
@@ -54,7 +54,7 @@ questions, either to me personally (clau
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
- the GEOMETRY of a PARTITION.
+ a given GEOMETRY of a PARTITION.
DEVICE a storage device.
@@ -75,10 +75,10 @@ GEOMETRY a description of a continuous
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.
+LOGICAL PARTITION like normal partitions, but they lie inside the
+ extended partition.
-PARTITION a continous region on a disk, where a file system may
+PARTITION a continuous region on a disk where a file system may
reside.
PRIMARY PARTITION a normal, vanilla, partition.
@@ -102,12 +102,12 @@ PedPartition a partition (basically Ped
PedConstraint a constraint on the geometry of a partition
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)
+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 are read-only. They should only be modified by calls to API
-functions.
+All objects should be considered read-only; they should only be modified by
+calls to libparted's API.
-------------------------------------------------------------------------------
2 INITIALISING LIBPARTED
@@ -117,9 +117,9 @@ Headers for libparted can be included wi
#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.
+Before any API functions are called, ped_init() must be called. There is one
+exception: you can set the exception handler with ped_exception_set_handler().
+This way, if an error occurs 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
@@ -202,12 +202,12 @@ 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.
+ Closes/frees all devices. Called by ped_done(), so you do not need
+ to 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(),
+ Gets the device "name", where name is usually the block device, e.g.
+ /dev/sdb. If the device wasn't detected with ped_device_probe_all(),
an attempt will be made to detect it again. If it is found, it will
be added to the list.
@@ -240,21 +240,21 @@ int ped_device_sync (PedDevice* dev)
int ped_device_begin_external_access (PedDevice* dev)
Begins external access mode. External access mode allows you to
safely do IO on the device. If a PedDevice is open, then you should
- not do any IO on that device (eg: by calling an external program,
- like e2fsck), unless you put it in external access mode. You should
- not use any libparted commands that do IO to a device (eg:
+ not do any IO on that device, e.g. by calling an external program
+ like e2fsck, unless you put it in external access mode. You should
+ not use any libparted commands that do IO to a device, e.g.
ped_file_system_{open|resize|copy}, ped_disk_{read|write}), while
a device is in external access mode.
Also, you should not ped_device_close() a device, while it is
in external access mode.
Note: ped_device_begin_external_access_mode() does things like
- tell the kernel to flush it's caches, and re-read the partition table.
+ tell the kernel to flush its caches, and reread the partition table.
Returns zero on failure.
int ped_device_end_external_access (PedDevice* dev)
Ends external access mode.
Note: ped_device_end_external_access_mode() does things like
- tell the kernel to flush it's caches, and re-read the partition table.
+ tell the kernel to flush it's caches, and reread the partition table.
Returns zero on failure.
-----------------------------------------------------------------------------
@@ -264,7 +264,7 @@ int ped_device_end_external_access (PedD
interface: <parted/disk.h>
implementation: libparted/disk.c
-Most programs will need to use ped_disk_open() or ped_disk_create() to get
+Most programs will need to use ped_disk_new() or ped_disk_new_fresh() 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.
@@ -310,25 +310,22 @@ PedDiskType* ped_disk_type_get (char* na
Returns the disk type with a name of "name". If there are none,
returns NULL.
-PedDisk* ped_disk_open (PedDevice* dev)
+PedDisk* ped_disk_new (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.
+ are incorrect.
-PedDisk* ped_disk_create (PedDevice* dev, PedDiskType* type)
+PedDisk* ped_disk_new_fresh (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)
+int ped_disk_destory (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_commit (PedDisk* disk)
+ Flushes the partition table to "disk". Returns 0 on failure.
int ped_disk_add_partition (PedDisk* disk, PedPartition* part,
PedConstraint* constraint)
@@ -337,11 +334,14 @@ int ped_disk_add_partition (PedDisk* dis
You could set "constraint" to ped_constraint_exact(&part->geom), but
many partition table schemes have special requirements on the start
and end of partitions. Therefore, having an overly strict constraint
- will probably mean ped_disk_add_partition() will fail (in which case,
- "part" will be left unmodified)
+ will probably mean that ped_disk_add_partition() will fail (in which
+ case, "part" will be left unmodified)
"part" is assigned a number (part->num) in this process.
Returns 0 on failure.
+int ped_disk_remove_partition (PedDisk* disk, PedPartition* part)
+ ???
+
int ped_disk_delete_partition (PedDisk* disk, PedPartition* part)
Removes "part" from "disk", and destroys "part". Returns 0 on failure.
@@ -351,15 +351,15 @@ int ped_disk_delete_all (PedDisk* disk)
int ped_disk_set_partition_geom (PedDisk* disk, PedPartition* part,
PedConstraint* constraint, 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
+ Sets the geometry of "part". This can fail for many reasons, e.g.
+ can't overlap with other partitions. If it does fail, "part" will
remain unchanged. Returns 0 on failure.
- "part"'s geometry may be set to something different to
- "start" and "end", subject to "constraint".
+ "part"'s geometry may be set to something different from
+ "start" and "end" subject to "constraint".
int ped_disk_maximize_partition (PedDisk* disk, PedPartition* part,
PedConstraint* constraint)
- Grows "part"'s geometry to the maximum possible, subject to
+ Grows "part"'s geometry to the maximum possible subject to
"constraint". The new geometry will be a superset of the old geometry.
Returns 0 on failure.
@@ -377,8 +377,9 @@ PedPartition* ped_disk_next_partition (P
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
+ If this is called repeatedly passing the return value as
"part", a depth-first traversal is executed.
+ Must ped_disk_read be called first?
PedPartition* ped_disk_get_partition (PedDisk* disk, int num)
Returns the partition numbered "num". If no such partition exists,
@@ -392,7 +393,7 @@ int ped_disk_get_last_partition_num (Ped
PedPartition* ped_disk_get_partition_by_sector (PedDisk* disk, PedSector sect)
Returns the partition that 'owns' "sect". If sect lies inside a
- logical partition
+ logical partition FIXME.
PedPartition* ped_disk_extended_partition (PedDisk* disk)
Returns the extended partition, or NULL if there isn't one.
@@ -404,8 +405,8 @@ PedPartition* ped_disk_extended_partitio
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
+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.
The following conditions are always true on a PedGeometry object:
@@ -423,11 +424,11 @@ struct _PedGeometry {
};
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
+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
-----------------
@@ -454,11 +455,11 @@ void ped_geometry_set (PedGeometry* 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.
+ Assigns a 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.
+ 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)
@@ -466,7 +467,7 @@ int ped_geometry_test_overlap (PedGeomet
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
+ 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.
@@ -486,7 +487,7 @@ int ped_geometry_read (PedGeometry* geom
int ped_geometry_write (PedGeometry* geom, void* buffer, PedSector offset,
PedSector count)
- Writes data from the region represented by "geom". "offset" is the
+ 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.
@@ -510,9 +511,9 @@ int ped_geometry_sync (PedGeometry* geom
PedSector ped_geometry_map (PedGeometry* dst, PedGeometry* src,
PedSector sector)
- If "src" and "dst" overlap, and "sector" on "src" is exists also on
+ If "src" and "dst" overlap, and "sector" on "src" also exists on
"dst", then the equivalent sector is retruned.
- -1 is returned if "sector" is not within "dst"'s space.
+ Returns -1 if "sector" is not within "dst"'s space.
-----------------------------------------------------------------------------
6 PEDPARTITION, PEDPARTITIONTYPE
@@ -590,9 +591,9 @@ PedPartitionType type the type of part
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)
+ metadata within the extended partition).
PedFileSystemType* fs_type The type of file system on the partition.
- NULL if not known.
+ NULL if unknown.
6.2 FUNCTIONS
-----------------
@@ -607,12 +608,13 @@ PedPartition* ped_partition_new (PedDisk
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
+ Returns whether or not the partition is "active". If part->type is
PED_PARTITION_METADATA or PED_PARTITION_FREE, then it's inactive.
Otherwise, it's active.
@@ -620,28 +622,28 @@ int ped_partition_set_flag (PedPartition
int state)
Sets the state (1 or 0) of a flag on a partition.
Flags are disk label specific, although they have a global
- "namespace". e.g. the flag, PED_PARTITION_BOOT roughly means "this
+ "namespace". e.g. the flag PED_PARTITION_BOOT roughly means "this
partition is bootable". But, this means different things on different
disk labels (and may not be defined on some disk labels). For example,
on msdos disk labels, there can only be one boot partition, and this
refers to the partition that will be booted from on startup. On PC98
disk labels, the user can choose from any bootable partition on startup.
- It is an error to call this on an unavailable flag - see
+ It is an error to call this on an unavailable flag -- see
ped_partition_is_flag_available().
int ped_partition_get_flag (const PedPartition* part, PedPartitionFlag flag)
Returns the state (1 or 0) of a flag on a partition.
- It is an error to call this on an unavailable flag - see
+ It is an error to call this on an unavailable flag -- see
ped_partition_is_flag_available().
int ped_partition_is_flag_available (const PedPartition* part,
PedPartitionFlag flag)
- Returns if 1 if a flag is available on a partition, and 0 otherwise.
+ Returns 1 if a flag is available on a partition, 0 otherwise.
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.
+ file system, e.g. to determine if it's FAT16 or FAT32.
int ped_partition_set_name (PedPartition* part, const char* name);
Sets the name of a partition. This will only work if the disk label
@@ -658,7 +660,7 @@ const char* ped_partition_get_name (cons
not be referenced after the partition is destroyed.
int ped_partition_is_busy (PedPartition* part)
- Returns 1 if a partition is busy (i.e. mounted), 0 otherwise. If part
+ Returns 1 if a partition is busy, i.e. mounted, 0 otherwise. If part
is an extended partition, then it is busy if any logical partitions are
mounted.
@@ -672,8 +674,8 @@ const char* ped_partition_type_get_name
dgettext("parted", RESULT) on the result.
const char* ped_partition_flag_get_name (PedPartitionFlag flag)
- Returns a name for a flag. Eg: PED_PARTITION_BOOT will return
- _("boot").
+ 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.
@@ -683,7 +685,7 @@ PedPartitionFlag ped_partition_flag_get_
string, or the translation for the native language.
PedPartitionFlag ped_partition_flag_next (PedPartitionFlag flag)
- Function for iterating through all flags. Returns the next 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.
@@ -735,7 +737,7 @@ PedFileSystemType* ped_file_system_probe
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:
+ This is often called in the following manner:
fs = ped_file_system_open (&part.geom)
PedFileSystem* ped_file_system_create (PedGeometry* geom,
@@ -769,7 +771,7 @@ PedConstraint* ped_file_system_get_resiz
* if constraint->start_align->grain_size == 0, or
constraint->max_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 ;-)
+ to. You might want to tell the user this ;-).
-----------------------------------------------------------------------------
8 PEDCONSTRAINT, PEDALIGNMENT
@@ -783,33 +785,33 @@ ped_file_system_resize() at the moment).
on the location and alignment of the start and end of a partition, and the
minimum size.
-"Alignments" are restrictions on the location of a sector, in the form of:
+"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
+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)
+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
+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.
+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 other restriction -- the minimum size -- is also closed under intersection.
(The intersection of 2 minimum size restrictions is the maximum of the
2 values)
Therefore, constraints are closed under intersection. libparted can compute
the intersection of constraints very efficiently. Therefore, you can satisfy
-an arbitary number of constraints, by finding the intersection of all the
+an arbitary number of constraints by finding the intersection of all the
constraints.
The interface consists of construction constraints, finding the intersection
@@ -840,7 +842,7 @@ int ped_constraint_init (
const PedGeometry* start_range,
const PedGeometry* end_range,
PedSector min_size)
- Initialises a pre-allocate piece of memory, to contain a constraint.
+ Initialises a pre-allocated piece of memory to contain a constraint.
Returns 0 on failure.
PedConstraint* ped_constraint_new (
@@ -855,11 +857,11 @@ PedConstraint* ped_constraint_duplicate
Duplicates "constraint".
void ped_constraint_done (PedConstraint* constraint)
- Frees up memory allocated for "constraint", initialized with
+ Frees up memory allocated for "constraint" initialized with
ped_constraint_init().
void ped_constraint_destroy (PedConstraint* constraint)
- Frees up memory allocated for "constraint", allocated with
+ Frees up memory allocated for "constraint" allocated with
ped_constraint_new().
PedConstraint* ped_constraint_intersect (
@@ -867,16 +869,16 @@ PedConstraint* ped_constraint_intersect
Creates a new constraint, such that a PedGeometry is a solution to the
new constraint if and only if it is a solution to both "a" and "b".
If there are no PedGeometry objects that can satisfy both "a" and
- "b", then NULL is returned. NULL is a valid PedConstraint object,
+ "b", then NULL is returned. NULL is a valid PedConstraint object
that can be used for all ped_constraint_* functions.
PedGeometry* ped_constraint_solve_max (const PedConstraint* constraint)
- Finds the largest solution (i.e. geometry with maximum length) for
+ Finds the largest solution, i.e. geometry with maximum length, for
"constraint". Returns NULL if there is no solution.
PedGeometry* ped_constraint_solve_nearest (
const PedConstraint* constraint, const PedGeometry* geom)
- Solves "constraint", returning the nearest to "geom". If there is no
+ Solves "constraint" returning the nearest to "geom". If there is no
solution, NULL is returned.
int ped_constraint_is_solution (const PedConstraint* constraint,
@@ -902,7 +904,7 @@ PedAlignment* ped_alignment_new (PedSect
PedSector's that are of the form "offset + X * grain_size".
void ped_alignment_destroy (PedAlignment* align)
- Frees up memory associated "align".
+ Frees up memory associated with "align".
PedAlignment* ped_alignment_duplicate (const PedAlignment* align)
Returns a duplicate of "align".
@@ -931,7 +933,7 @@ PedSector ped_alignment_align_down (cons
PedSector ped_alignment_align_nearest (const PedAlignment* align,
const PedGeometry* geom, PedSector sector)
- Returns the closest PedSector to "sector", that lies within "geom" and
+ 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,
@@ -951,14 +953,14 @@ PED_EXCEPTION_WARNING, PED_EXCEPTION_ERR
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
+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
+text describing 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
+ After an exception is thrown, there are two things that
can happen:
(1) an exception handler is called, which selects how the exception
should be resolved (usually by asking the user). Also note: an exception
@@ -1019,7 +1021,7 @@ PedExceptionOption ped_exception_throw (
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:
+ "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
@@ -1037,7 +1039,7 @@ void ped_exception_fetch_all()
ped_exception_throw() will return PED_EXCEPTION_UNHANDLED.
void ped_exception_leave_all()
- Indicate that the calling function does not want to accept any
+ Indicates 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.
pgpY3xn8hjdD7.pgp
Description: PGP signature
- [patch] doc/API,
Neal H Walfield <=