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