Update libblkid documentation.

Fix tst_resolve to use latest blkid API's.

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 3a1a6dd41a38d7080db613b97fb70383012d30cb..87fb84595b8dfe03f8d8df74e5c0e35d1d07a805 100644 (file)
--- a/doc/ChangeLog
+++ b/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

diff --git a/doc/libblkid.txt b/doc/libblkid.txt
new file mode 100644 (file)
index 0000000..7bd6027
--- /dev/null
+++ b/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.

diff --git a/lib/blkid/ChangeLog b/lib/blkid/ChangeLog
index ef6f9681a1395d8a636add0681f87d020c7f45e9..4c95d654bfcdacf62f1f159083fee28b5ec4630d 100644 (file)
--- a/lib/blkid/ChangeLog
+++ b/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.

diff --git a/lib/blkid/libblkid.3.in b/lib/blkid/libblkid.3.in
index d500b2fc4f8b6cffbb96a59ed542ab588e4b939c..c3d316e43c57f6d0e21b8fb68eb79d2ad44c2532 100644 (file)
--- a/lib/blkid/libblkid.3.in
+++ b/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)

diff --git a/lib/blkid/resolve.c b/lib/blkid/resolve.c
index 9e689c685372e812e8125ac64938f9998bcb864e..3dca74ff49a48e057ab055bc4056e59b44ba4984 100644 (file)
--- a/lib/blkid/resolve.c
+++ b/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 {