libstorage Documentation

Interface

The functionality of libstorage is entirely accessed through the abstract interface class StorageInterface. To ensure maximal possible compatibility user of libstorage must only include the header file StorageInterface.h.

Caching

All modifying functions of libstorage can either operate on an internal cache or directly on the system.

When the caching mode is enabled a call of e.g. createPartition() will only change the internal cache. The user has to call commit() later on to actually create the partition on the disk.

When caching mode is disabled the call of e.g. createPartition() will immediately create the partition on the disk.

Caching mode can be set with setCacheChanges() and queried with isCacheChanges().

Locking

During initialisation libstorage installs a global lock so that several programs trying to use libstorage at the same time do not interfere. This lock is either read-only or read-write depending on the readonly parameter used in createStorageInterface() .

Several processes may hold a read-lock, but only one process may hold a read-write lock. An read-write lock excludes all other locks, both read-only and read-write.

The support for multiple read-only locks is experimental.

Locking may also fail for other reasons, e.g. limited permissions.

File

During initialisation libstorage reads the default filesystem and default mount-by method from /etc/sysconfig/storage. Libstorage does not write that file.

Nomenclature

Sizes with postfix K are in kilobytes (1024 bytes).

The only size in bytes instead of kilobytes is the cylinder size of disks.

Example

Here is a simple example to demonstrate the usage of libstorage:

 #include <storage/StorageInterface.h>

 using namespace storage;

 int
 main()
 {
     // Environment for StorageInterface with read-write enabled.
     Environment env(false);

     // Create a concrete StorageInterface object.
     StorageInterface* s = createStorageInterface(env);

     int ret;
     string name;

     // Create a primary partition on /dev/sdb.
     ret = s->createPartitionKb("/dev/sdb", PRIMARY, 0, 100000, name);

     // Commit the change to the system.
     ret = s->commit();

     // Finally destroy the StorageInterface object.
     destroyStorageInterface(s);
 }

If you have installed the latest libstorage-devel package you can find more examples in the directory /usr/share/doc/packages/libstorage/examples.

doxygen