From e7a8a9df55bae3f189a68f5bf7ae461441bb3a21 Mon Sep 17 00:00:00 2001 From: Theodore Ts'o Date: Mon, 21 Jul 2003 20:03:59 -0400 Subject: [PATCH] libblkid.txt: Clarify documentation file --- doc/ChangeLog | 4 +++ doc/libblkid.txt | 78 ++++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 55 insertions(+), 27 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index b89a0a3..ee1fc83 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2003-07-21 Theodore Ts'o + + * libblkid.txt: Clarify documentation file + 2003-04-21 Theodore Ts'o * Release of E2fsprogs 1.33 diff --git a/doc/libblkid.txt b/doc/libblkid.txt index 7bd6027..8da1203 100644 --- a/doc/libblkid.txt +++ b/doc/libblkid.txt @@ -3,53 +3,77 @@ libblkid - a library to handle device identification and token extraction Basic usage is as follows - there are two normal usage patterns: For cases where a program wants information about multiple devices, or -expects to be doing multiple token searches, the program should directly -initialize cache file via (second parameter is cache filename, NULL = default): +expects to be doing multiple token searches, the program should +directly initialize cache file via (second parameter is cache +filename, NULL = default): blkid_cache cache = NULL; if (blkid_get_cache(&cache, NULL) < 0) /* error reading the cache file, not really fatal */ -Note that if no cache file exists, an empty cache struct is still allocated. -Usage of libblkid functions will use the cache to avoid needless device scans. +Note that if no cache file exists, an empty cache struct is still +allocated. Usage of libblkid functions will use the cache to avoid +needless device scans. -For cases where a program only wants to find a single token, or display -information about a specific device, it is often not necessary to manually -load the cache. For functions which deal with a single device, they will -probe the device directly if no cache is given. For "get" functions which -do searching, they will read/free the cache internally. +The model of the blkid cache is that each device has a number of +attributes that can be associated with it. Currently the attributes +which are supported (and set) by blkid are: + TYPE filesystem type + UUID filesystem uuid + LABEL filesystem label -How to use libblkid? Normally, you either want to find a device with a -specific NAME=value token, or you want to output token(s) from a device. -To locate a specific token, you can call: - if ((devname = blkid_get_devname(cache, token, value))) { +How to use libblkid? Normally, you either want to find a device with +a specific NAME=value token, or you want to output token(s) from a +device. To find a device that matches a following attribute, you +simply call the blkid_get_devname() function: + + if ((devname = blkid_get_devname(cache, attribute_name, value))) { /* do something with devname */ string_free(devname); } -where cache is optionally loaded, token is either a "NAME=value" string, -or "NAME" and value gives the desired value to look for. The return -value is an allocated string which holds the resulting device name (if -found) or "NAME" if we do not have a proper value, or NULL if a specific -token was not found. This allows you to pass token = "/dev/hda1" or -token = "LABEL=root" and get a valid device name back if possible. The -returned string must be freed with "free(devname)". +The cache parameter is optional; if it is NULL, then the blkid library +will load the default blkid.tab cache file, and the release the cache +before function call returns. The return value is an allocated string +which holds the resulting device name (if it is found). If the value +is NULL, then attribute_name is parsed as if it were +"="; if it cannot be so parsed, then the +original attribute_name is returned in a copied allocated string. +This is a convenience to allow user programs to want to translate user +input, whether it is of the form: "/dev/hda1", "LABEL=root", +"UUID=082D-26E3", and get back a device name that it can use. + +Alternatively, of course, the programmer can pass an attribute name of +"LABEL", and value of "root", if that is more convenient. -The other common usage is to want the value of a specific tag on a device. +Another common usage is to retrieve the value of a specific attribute +for a particular device. This can be used to used to determine the +filesystem type, or label, or uuid for a particular device: - if ((value = blkid_get_tag_value(cache, tagname, devname))) { + if ((value = blkid_get_tag_value(cache, attribute_name, devname))) { /* do something with value */ string_free(value); } -If you have directly loaded the cache from the program, you need to clean -up by saving the cache (assuming you have write access to the cache, this -happens automatically if you didn't load it directly), and freeing it (this +If a program need to call multiple blkid functions, then passing in a +cache value of NULL is not recommended, since the /etc/blkid.tab file +will be repeatedly parsed over and over again, with a memory allocated +and deallocated. To initialize the blkid cache, blkid_get_cache() +function is used: + + if (blkid_get_cache(&cache, NULL) < 0) + goto errout; + +The second parameter of blkid_get_cache (if non-zero) is the alternate +filename of the blkid cache file (where the default is +/etc/blkid.tab). Normally, programs should just pass in NULL. + +If you have called blkid_get_cache(), you need to clean up by saving +the cache (assuming you have write access to the cache, this happens +automatically if you didn't load it directly), and freeing it (this will also free all associated devices/tags): blkid_put_cache(cache); -In all cases, any data returned by the searching functions from the cache -is first verified from disk to ensure that it is still valid. -- 1.8.3.1