diff options
| -rw-r--r-- | shlibs/blkid/src/blkid.h | 33 | ||||
| -rw-r--r-- | shlibs/blkid/src/cache.c | 45 | ||||
| -rw-r--r-- | shlibs/blkid/src/dev.c | 15 | ||||
| -rw-r--r-- | shlibs/blkid/src/devname.c | 16 | ||||
| -rw-r--r-- | shlibs/blkid/src/encode.c | 9 | ||||
| -rw-r--r-- | shlibs/blkid/src/evaluate.c | 28 | ||||
| -rw-r--r-- | shlibs/blkid/src/probe.c | 11 | ||||
| -rw-r--r-- | shlibs/blkid/src/version.c | 2 |
8 files changed, 149 insertions, 10 deletions
diff --git a/shlibs/blkid/src/blkid.h b/shlibs/blkid/src/blkid.h index c0cda634d..d0eb4b6a3 100644 --- a/shlibs/blkid/src/blkid.h +++ b/shlibs/blkid/src/blkid.h @@ -30,8 +30,25 @@ extern "C" { #endif +/** + * blkid_dev: + * + * The device object keeps information about one device + */ typedef struct blkid_struct_dev *blkid_dev; + +/** + * blkid_cache: + * + * information about all system devices + */ typedef struct blkid_struct_cache *blkid_cache; + +/** + * blkid_probe: + * + * low-level probing setting + */ typedef struct blkid_struct_probe *blkid_probe; /** @@ -62,9 +79,25 @@ typedef struct blkid_struct_partition *blkid_partition; */ typedef struct blkid_struct_parttable *blkid_parttable; +/** + * blkid_loff_t: + * + * 64-bit signed number for offsets and sizes + */ typedef int64_t blkid_loff_t; +/** + * blkid_tag_iterate: + * + * tags iterator for high-level (blkid_cache) API + */ typedef struct blkid_struct_tag_iterate *blkid_tag_iterate; + +/** + * blkid_dev_iterate: + * + * devices iterator for high-level (blkid_cache) API + */ typedef struct blkid_struct_dev_iterate *blkid_dev_iterate; /* diff --git a/shlibs/blkid/src/cache.c b/shlibs/blkid/src/cache.c index acdf96dde..7f983ed76 100644 --- a/shlibs/blkid/src/cache.c +++ b/shlibs/blkid/src/cache.c @@ -33,6 +33,30 @@ int blkid_debug_mask = 0; +/** + * SECTION:cache + * @title: Cache + * @short_description: basic routines to work with libblkid cache + * + * Block device information is normally kept in a cache file /etc/blkid.tab and is + * verified to still be valid before being returned to the user (if the user has + * read permission on the raw block device, otherwise not). The cache file also + * allows unprivileged users (normally anyone other than root, or those not in the + * "disk" group) to locate devices by label/id. The standard location of the + * cache file can be overridden by the environment variable BLKID_FILE. + * + * In situations where one is getting information about a single known device, it + * does not impact performance whether the cache is used or not (unless you are + * not able to read the block device directly). If you are dealing with multiple + * devices, use of the cache is highly recommended (even if empty) as devices will + * be scanned at most one time and the on-disk cache will be updated if possible. + * There is rarely a reason not to use the cache. + * + * In some cases (modular kernels), block devices are not even visible until after + * they are accessed the first time, so it is critical that there is some way to + * locate these devices without enumerating only visible devices, so the use of + * the cache file is required in this situation. + */ char *blkid_safe_getenv(const char *arg) { @@ -120,6 +144,15 @@ char *blkid_get_cache_filename(struct blkid_config *conf) return filename; } +/** + * blkid_get_cache: + * @cache: pointer to return cache handler + * @filename: path to the cache file or NULL for the default path + * + * Allocates and initialize librray cache handler. + * + * Returns: 0 on success or number less than zero in case of error. + */ int blkid_get_cache(blkid_cache *ret_cache, const char *filename) { blkid_cache cache; @@ -147,6 +180,12 @@ int blkid_get_cache(blkid_cache *ret_cache, const char *filename) return 0; } +/** + * blkid_put_cache: + * @cache: cache handler + * + * Saves changes to cache file. + */ void blkid_put_cache(blkid_cache cache) { if (!cache) @@ -188,6 +227,12 @@ void blkid_put_cache(blkid_cache cache) free(cache); } +/** + * blkid_gc_cache: + * @cache: cache handler + * + * Removes garbage (non-existing devices) from the cache. + */ void blkid_gc_cache(blkid_cache cache) { struct list_head *p, *pnext; diff --git a/shlibs/blkid/src/dev.c b/shlibs/blkid/src/dev.c index 31b9fe86f..e02f170c7 100644 --- a/shlibs/blkid/src/dev.c +++ b/shlibs/blkid/src/dev.c @@ -15,6 +15,21 @@ #include "blkidP.h" +/* + * NOTE: reference manual is not structured as code. The following section is a generic + * section for all high-level cache search+iterate routines. + */ + +/** + * SECTION:search + * @title: Search and iterate + * @short_description: search devices and iterate over devices in the cache. + * + * Note that high-level probing API provides information about superblocks + * (filesystems/raids) only. For partitions and topology is necessary to use + * the low-level API. + */ + blkid_dev blkid_new_dev(void) { blkid_dev dev; diff --git a/shlibs/blkid/src/devname.c b/shlibs/blkid/src/devname.c index ef686f4b4..f0672ddcd 100644 --- a/shlibs/blkid/src/devname.c +++ b/shlibs/blkid/src/devname.c @@ -509,6 +509,14 @@ static int probe_all(blkid_cache cache, int only_if_new) return 0; } +/** + * blkid_probe_all: + * @cache: cache handler + * + * Probes all block devices. + * + * Returns: 0 on success, or number less than zero in case of error. + */ int blkid_probe_all(blkid_cache cache) { int ret; @@ -521,6 +529,14 @@ int blkid_probe_all(blkid_cache cache) return ret; } +/** + * blkid_probe_all_new: + * @cache: cache handler + * + * Probes all new block devices. + * + * Returns: 0 on success, or number less than zero in case of error. + */ int blkid_probe_all_new(blkid_cache cache) { int ret; diff --git a/shlibs/blkid/src/encode.c b/shlibs/blkid/src/encode.c index 38c5d231f..a5f800b68 100644 --- a/shlibs/blkid/src/encode.c +++ b/shlibs/blkid/src/encode.c @@ -22,6 +22,13 @@ #define UDEV_ALLOWED_CHARS_INPUT "/ $%?," +/** + * SECTION: encode + * @title: Encoding utils + * @short_description: encode strings to safe udev-compatible formats + * + */ + /* count of characters used to encode one unicode char */ static int utf8_encoded_expected_len(const char *str) { @@ -321,6 +328,8 @@ err: * * Allows plain ascii, hex-escaping and valid utf8. Replaces all whitespaces * with '_'. + * + * Returns: 0 on success or -1 in case of error. */ int blkid_safe_string(const char *str, char *str_safe, size_t len) { diff --git a/shlibs/blkid/src/evaluate.c b/shlibs/blkid/src/evaluate.c index 2308ea80a..9f987b1ad 100644 --- a/shlibs/blkid/src/evaluate.c +++ b/shlibs/blkid/src/evaluate.c @@ -1,15 +1,11 @@ /* * evaluate.c - very high-level API to evaluate LABELs or UUIDs * - * This is simular to blkid_get_devname() from resolve.c, but this - * API supports udev /dev/disk/by-{label,uuid} links. - * * Copyright (C) 2009 Karel Zak <kzak@redhat.com> * * This file may be redistributed under the terms of the * GNU Lesser General Public License. */ - #include <stdio.h> #include <string.h> #include <stdlib.h> @@ -35,6 +31,26 @@ #include "blkdev.h" #include "blkidP.h" +/** + * SECTION:evaluate + * @title: Tags evaluation + * @short_description: top-level API for LABEL and UUID evaluation. + * + * This API provides very simple and portable way how evaluate LABEL and UUID + * tags. The blkid_evaluate_tag() works on 2.4 and 2.6 systems and on systems + * with or without udev. Currently, the libblkid library supports "udev" and + * "scan" methods. The "udev" method uses udev /dev/disk/by-* symlinks and the + * "scan" method scans all block devices from the /proc/partitions file. The + * evaluation could be controlled by the /etc/blkid.conf config file. The + * default is to try "udev" and then "scan" method. + * + * The blkid_evaluate_tag() also automatically informs udevd when an obsolete + * /dev/disk/by-* symlink is detected. + * + * If you are not sure how translate LABEL or UUID to the device name use this + * API. + */ + /* returns zero when the device has NAME=value (LABEL/UUID) */ static int verify_tag(const char *devname, const char *name, const char *value) { @@ -80,7 +96,7 @@ done: * blkid_send_uevent: * @devname: absolute path to the device * - * Returns -1 in case of failure, or 0 on success. + * Returns: -1 in case of failure, or 0 on success. */ int blkid_send_uevent(const char *devname, const char *action) { @@ -194,7 +210,7 @@ static char *evaluate_by_scan(const char *token, const char *value, * @value: token data * @cache: pointer to cache (or NULL when you don't want to re-use the cache) * - * Returns allocated string with device name. + * Returns: allocated string with a device name. */ char *blkid_evaluate_tag(const char *token, const char *value, blkid_cache *cache) { diff --git a/shlibs/blkid/src/probe.c b/shlibs/blkid/src/probe.c index 834259290..421e9f165 100644 --- a/shlibs/blkid/src/probe.c +++ b/shlibs/blkid/src/probe.c @@ -20,8 +20,12 @@ * * The probing routines is possible to filter (enable/disable) by type (e.g. * fstype "vfat" or partype "gpt") or by usage flags (e.g. BLKID_USAGE_RAID). - * These filters are per-chain. For more details see the chain specific - * documenation. + * These filters are per-chain. Note that always when you touch the chain + * filter the current probing position is reseted and probing starts from + * scratch. It means that the chain filter should not be modified during + * probing, for example in loop where you call blkid_do_probe(). + * + * For more details see the chain specific documentation. * * The low-level API provides two ways how access to probing results. * @@ -30,6 +34,7 @@ * * 2. The binary interfaces. These interfaces return data in the native formats. * The interface is always specific to the probing chain. + * */ /** @@ -44,7 +49,7 @@ * * The SUPERBLOCKS chain is enabled by default. The all others chains is * necessary to enable by blkid_probe_enable_'CHAINNAME'(). See chains specific - * documenation. + * documentation. * * The blkid_do_probe() function returns a result from only one probing * routine, and the next call from the next probing routine. It means you need diff --git a/shlibs/blkid/src/version.c b/shlibs/blkid/src/version.c index 838af1146..91fd5117f 100644 --- a/shlibs/blkid/src/version.c +++ b/shlibs/blkid/src/version.c @@ -42,7 +42,7 @@ int blkid_parse_version_string(const char *ver_string) * @ver_string: returns relese version (!= SONAME version) * @date_string: returns date * - * Returns release version code. + * Returns: release version code. */ int blkid_get_library_version(const char **ver_string, const char **date_string) |