1libblkid - a library to handle device identification and token extraction
2
3Basic usage is as follows - there are two normal usage patterns:
4
5For cases where a program wants information about multiple devices, or
6expects to be doing multiple token searches, the program should
7directly initialize cache file via (second parameter is cache
8filename, NULL = default):
9
10	blkid_cache cache = NULL;
11	if (blkid_get_cache(&cache, NULL) < 0)
12		/* error reading the cache file, not really fatal */
13
14Note that if no cache file exists, an empty cache struct is still
15allocated.  Usage of libblkid functions will use the cache to avoid
16needless device scans.
17
18The model of the blkid cache is that each device has a number of
19attributes that can be associated with it.  Currently the attributes
20which are supported (and set) by blkid are:
21
22	TYPE		filesystem type
23	UUID		filesystem uuid
24	LABEL		filesystem label
25
26
27How to use libblkid?  Normally, you either want to find a device with
28a specific NAME=value token, or you want to output token(s) from a
29device.  To find a device that matches a following attribute, you
30simply call the blkid_get_devname() function: 
31
32	if ((devname = blkid_get_devname(cache, attribute_name, value))) {
33		/* do something with devname */
34		string_free(devname);
35	}
36
37The cache parameter is optional; if it is NULL, then the blkid library
38will load the default blkid.tab cache file, and then release the cache
39before function call returns.  The return value is an allocated string
40which holds the resulting device name (if it is found).  If the value
41is NULL, then attribute_name is parsed as if it were
42"<attribute_name>=<value>"; if it cannot be so parsed, then the
43original attribute_name is returned in a copied allocated string.
44This is a convenience to allow user programs to want to translate user
45input, whether it is of the form: "/dev/hda1", "LABEL=root",
46"UUID=082D-26E3", and get back a device name that it can use.
47
48Alternatively, of course, the programmer can pass an attribute name of
49"LABEL", and value of "root", if that is more convenient.
50
51Another common usage is to retrieve the value of a specific attribute
52for a particular device.  This can be used to determine the filesystem
53type, or label, or uuid for a particular device:
54
55	if ((value = blkid_get_tag_value(cache, attribute_name, devname))) {
56		/* do something with value */
57		string_free(value);
58	}
59
60If a program needs to call multiple blkid functions, then passing in a
61cache value of NULL is not recommended, since the /etc/blkid.tab file
62will be repeatedly parsed over and over again, with memory allocated
63and deallocated.  To initialize the blkid cache, blkid_get_cache()
64function is used:
65
66	if (blkid_get_cache(&cache, NULL) < 0)
67		goto errout;
68
69The second parameter of blkid_get_cache (if non-zero) is the alternate
70filename of the blkid cache file (where the default is
71/etc/blkid.tab).  Normally, programs should just pass in NULL.
72
73If you have called blkid_get_cache(), you should call blkid_put_cache()
74when you are done using the blkid library functions.  This will save the
75cache to the blkid.tab file, if you have write access to the file.  It
76will also free all associated devices and tags:
77
78	blkid_put_cache(cache); 
79