From 4d72b3371845f8ab9775dd84bee0d174ac6334b7 Mon Sep 17 00:00:00 2001 From: Karel Zak Date: Tue, 15 Sep 2009 22:43:58 +0200 Subject: [PATCH] libblkid: add missing comments to probe.c Signed-off-by: Karel Zak --- shlibs/blkid/src/probe.c | 82 +++++++++++++++++++++++++++++++++++----- 1 file changed, 73 insertions(+), 9 deletions(-) diff --git a/shlibs/blkid/src/probe.c b/shlibs/blkid/src/probe.c index 2be42fc2..a68881db 100644 --- a/shlibs/blkid/src/probe.c +++ b/shlibs/blkid/src/probe.c @@ -1,12 +1,70 @@ /* - * probe.c - reads tags (LABEL, UUID, FS type, ..) from a block device + * Low-level libblkid probing API * - * Copyright (C) 2008 Karel Zak + * Copyright (C) 2008-2009 Karel Zak * * This file may be redistributed under the terms of the * GNU Lesser General Public License. */ +/** + * SECTION: lowprobe + * @title: Low-level probing + * @short_description: low-level prober initialization + * + * The low-level probing routines always and directly read information from + * the selected (see blkid_probe_set_device()) device. + * + * The probing routines are grouped together into separate chains. Currently, + * the librray provides superblocks, partitions and topology chains. + * + * 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. + * + * The low-level API provides two ways how access to probing results. + * + * 1. The NAME=value (tag) interface. This interface is older and returns all data + * as strings. This interface is generic for all chains. + * + * 2. The binary interfaces. These interfaces return data in the native formats. + * The interface is always specific to the probing chain. + */ + +/** + * SECTION: lowprobe-tags + * @title: Low-level tags + * @short_description: generic NAME=value interface. + * + * The probing routines inside the chain are mutually exclusive by default -- + * only few probing routines are marked as "tolerant". The "tolerant" probing + * routines are used for filesystem which can share the same device with any + * other filesystem. The blkid_do_safeprobe() checks for the "tolerant" flag. + * + * The SUPERBLOCKS chain is enabled by default. The all others chains is + * necessary to enable by blkid_probe_enable_'CHAINNAME'(). See chains specific + * documenation. + * + * 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 + * to call the function in loop, for example: + * + * + * + * while((blkid_do_probe(pr) == 0) + * ... use result ... + * + * + * + * The blkid_do_safeprobe() is the same as blkid_do_probe(), but returns only + * first probing result for every enabled chain. This function checks for + * ambivalent results (e.g. more "intolerant" filesystems superblocks on the + * device). + * + * The probing result is set of NAME=value pairs (the NAME is always unique). + */ + #include #include #include @@ -629,13 +687,6 @@ done: return count ? 0 : 1; } -int blkid_probe_numof_values(blkid_probe pr) -{ - if (!pr) - return -1; - return pr->nvals; -} - struct blkid_prval *blkid_probe_assign_value( blkid_probe pr, const char *name) { @@ -693,6 +744,19 @@ int blkid_probe_vsprintf_value(blkid_probe pr, const char *name, return 0; } +/** + * blkid_probe_numof_values: + * @pr: probe + * + * Returns: number of values in probing result or -1 in case of error. + */ +int blkid_probe_numof_values(blkid_probe pr) +{ + if (!pr) + return -1; + return pr->nvals; +} + /** * blkid_probe_get_value: * @pr: probe -- 2.39.5