libblkid.txt: Clarify documentation file

diff --git a/doc/ChangeLog b/doc/ChangeLog
index b89a0a3..ee1fc83 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2003-07-21  Theodore Ts'o  <tytso@mit.edu>
+
+       * libblkid.txt: Clarify documentation file
+
 2003-04-21  Theodore Ts'o  <tytso@mit.edu>
 
        * Release of E2fsprogs 1.33

diff --git a/doc/libblkid.txt b/doc/libblkid.txt
index 7bd6027..8da1203 100644 (file)
--- 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
+"<attribute_name>=<value>"; 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.