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