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