diff --git a/Makefile.am b/Makefile.am index 6fce69cc5..00ae9df7f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -6,6 +6,7 @@ SUBDIRS = \ fdisk \ getopt \ lib \ + libs \ login-utils \ misc-utils \ po \ diff --git a/configure.ac b/configure.ac index 13b43a364..b019a9a2e 100644 --- a/configure.ac +++ b/configure.ac @@ -709,6 +709,8 @@ getopt/Makefile hwclock/Makefile include/Makefile lib/Makefile +libs/Makefile +libs/blkid/Makefile login-utils/Makefile misc-utils/Makefile mount/Makefile diff --git a/libs/Makefile.am b/libs/Makefile.am new file mode 100644 index 000000000..1e33882ab --- /dev/null +++ b/libs/Makefile.am @@ -0,0 +1 @@ +SUBDIRS = blkid diff --git a/libs/blkid/Makefile.am b/libs/blkid/Makefile.am new file mode 100644 index 000000000..6702b5b3e --- /dev/null +++ b/libs/blkid/Makefile.am @@ -0,0 +1,3 @@ +include $(top_srcdir)/config/include-Makefile.am + +EXTRA_DIST = README.fsprobe diff --git a/libs/blkid/README.blkid b/libs/blkid/README.blkid new file mode 100644 index 000000000..4fa9be1f7 --- /dev/null +++ b/libs/blkid/README.blkid @@ -0,0 +1,78 @@ +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. + +The model of the blkid cache is that each device has a number of +attributes that can be associated with it. Currently the attributes +which are supported (and set) by blkid are: + + TYPE filesystem type + UUID filesystem uuid + LABEL filesystem label + + +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 find a device that matches a following attribute, you +simply call the blkid_get_devname() function: + + if ((devname = blkid_get_devname(cache, attribute_name, value))) { + /* do something with devname */ + string_free(devname); + } + +The cache parameter is optional; if it is NULL, then the blkid library +will load the default blkid.tab cache file, and then release the cache +before function call returns. The return value is an allocated string +which holds the resulting device name (if it is found). If the value +is NULL, then attribute_name is parsed as if it were +"="; if it cannot be so parsed, then the +original attribute_name is returned in a copied allocated string. +This is a convenience to allow user programs to want to translate user +input, whether it is of the form: "/dev/hda1", "LABEL=root", +"UUID=082D-26E3", and get back a device name that it can use. + +Alternatively, of course, the programmer can pass an attribute name of +"LABEL", and value of "root", if that is more convenient. + +Another common usage is to retrieve the value of a specific attribute +for a particular device. This can be used to determine the filesystem +type, or label, or uuid for a particular device: + + if ((value = blkid_get_tag_value(cache, attribute_name, devname))) { + /* do something with value */ + string_free(value); + } + +If a program needs to call multiple blkid functions, then passing in a +cache value of NULL is not recommended, since the /etc/blkid.tab file +will be repeatedly parsed over and over again, with memory allocated +and deallocated. To initialize the blkid cache, blkid_get_cache() +function is used: + + if (blkid_get_cache(&cache, NULL) < 0) + goto errout; + +The second parameter of blkid_get_cache (if non-zero) is the alternate +filename of the blkid cache file (where the default is +/etc/blkid.tab). Normally, programs should just pass in NULL. + +If you have called blkid_get_cache(), you should call blkid_put_cache() +when you are done using the blkid library functions. This will save the +cache to the blkid.tab file, if you have write access to the file. It +will also free all associated devices and tags: + + blkid_put_cache(cache);