Update libblkid documentation.

Fix tst_resolve to use latest blkid API's.

doc/ChangeLog

@@ -1,3 +1,8 @@
+2003-03-01  Theodore Ts'o  <tytso@mit.edu>
+
+	* libblkid.txt (token): New file which gives basic
+		documentation to the libblkid library.
+
 2002-11-09  Theodore Ts'o  <tytso@mit.edu>
 
 	* Release of E2fsprogs 1.32

doc/libblkid.txt

@@ -0,0 +1,55 @@
+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):
+
+	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.
+
+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.
+
+
+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))) {
+		/* 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 other common usage is to want the value of a specific tag on a device.
+
+	if ((value = blkid_get_tag_value(cache, tagname, 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
+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.

lib/blkid/ChangeLog

@@ -1,5 +1,10 @@
 2003-03-01  Theodore Ts'o  <tytso@mit.edu>
 
+	* resolve.c (main): Update debugging test program so that it
+		compiles with the latest blkid API changes.
+
+	* libblkid.3.in: Update manual page to reflect recent API changes.
+
 	* resolve.c (blkid_get_tag_value): If the passed-in cache is NULL,
 		then get and release a temporary cache as a convenience to
 		the calling application.

lib/blkid/libblkid.3.in

@@ -30,11 +30,6 @@ and is verified to still be valid before being returned to the user
 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.
 .P
-Functions with "get" in their name will first search the cache (if given)
-for the specified data, and failing that will search visible block devices
-for this information.  Functions with "find" in their name will only search
-the existing cache data for the specified device.
-.P
 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
@@ -51,14 +46,14 @@ in this situation.
 .SH AUTHOR
 .B libblkid
 was written by Andreas Dilger for the ext2 filesystem utilties, with input
-from Ted Ts'o.
+from Ted Ts'o.  The library was subsequently heavily modified by Ted Ts'o.
 .SH FILES
 .TP
 .I /etc/blkid.tab 
 Caches data extracted from each recognized block device.
 .SH AVAILABILITY
 .B libblkid
-is part of the e2fsprogs package since version 1.25 and is available from
+is part of the e2fsprogs package since version 1.33 and is available from
 http://e2fsprogs.sourceforge.net.
 .SH COPYING
 .B libblkid
@@ -84,8 +79,6 @@ http://www.gnu.org/licenses/licenses.html#LGPL
 .BR blkid_put_cache (3),
 .BR blkid_get_dev (3),
 .BR blkid_probe_all (3),
-.BR blkid_free_dev (3),
-.BR blkid_find_tag_dev (3),
-.BR blkid_get_tagname_devname (3),
-.BR blkid_get_token (3),
+.BR blkid_get_devname (3),
+.BR blkid_get_tag_value (3),
 .BR blkid.tab (7)

lib/blkid/resolve.c

@@ -127,7 +127,7 @@ int main(int argc, char **argv)
 	}
 	
 	if (argv[2]) {
-		value = blkid_get_tagname_devname(cache, argv[1], argv[2]);
+		value = blkid_get_tag_value(cache, argv[1], argv[2]);
 		printf("%s has tag %s=%s\n", argv[2], argv[1],
 		       value ? value : "<missing>");
 	} else {