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;
/**
*/
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;
/*
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)
{
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;
return 0;
}
+/**
+ * blkid_put_cache:
+ * @cache: cache handler
+ *
+ * Saves changes to cache file.
+ */
void blkid_put_cache(blkid_cache cache)
{
if (!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;
#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;
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;
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;
#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)
{
*
* 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)
{
/*
* 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>
#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)
{
* 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)
{
* @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)
{
*
* 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.
*
*
* 2. The binary interfaces. These interfaces return data in the native formats.
* The interface is always specific to the probing chain.
+ *
*/
/**
*
* 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
* @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)
projects / util-linux / commitdiff