libblkid: cleanup definitions and add docs for return values

* make it possible to use #ifdef for the return values

* add docs for the return values

Addresses: https://github.com/util-linux/util-linux/issues/1939
Signed-off-by: Karel Zak <kzak@redhat.com>

diff --git a/libblkid/docs/libblkid-sections.txt b/libblkid/docs/libblkid-sections.txt
index c0dc0d48d7274f586139ce35210e8f829cc32325..8684fdb5a26633d4854e442c78dfafc9bbbc30b7 100644 (file)
--- a/libblkid/docs/libblkid-sections.txt
+++ b/libblkid/docs/libblkid-sections.txt
@@ -63,6 +63,10 @@ blkid_probe_set_hint
 blkid_probe_set_sectorsize
 blkid_probe_step_back
 blkid_reset_probe
+BLKID_PROBE_OK
+BLKID_PROBE_NONE
+BLKID_PROBE_ERROR
+BLKID_PROBE_AMBIGUOUS
 </SECTION>
 
 <SECTION>

diff --git a/libblkid/src/blkid.h.in b/libblkid/src/blkid.h.in
index 0f1f1df84f610c8a5604fcf80a7a7782e304dc1c..6132cb8a1acf91866eac3fb2243eabdf93897772 100644 (file)
--- a/libblkid/src/blkid.h.in
+++ b/libblkid/src/blkid.h.in
@@ -418,12 +418,31 @@ extern int blkid_do_safeprobe(blkid_probe pr)
 extern int blkid_do_fullprobe(blkid_probe pr)
                        __ul_attribute__((nonnull));
 
-enum {
-       BLKID_PROBE_OK          = 0,
-       BLKID_PROBE_NONE        = 1,
-       BLKID_PROBE_ERROR       = -1,
-       BLKID_PROBE_AMBIGUOUS   = -2
-};
+/**
+ * BLKID_PROBE_OK:
+ *
+ * probing return value; superblock (RAID, partiton table, ...) succesfully detected
+ */
+#define BLKID_PROBE_OK 0
+/**
+ * BLKID_PROBE_NONE:
+ *
+ * probing return value; found nothing
+ */
+#define BLKID_PROBE_NONE       1
+/**
+ * BLKID_PROBE_ERROR:
+ *
+ * probing return value; probing ends with en error (see errno for more details)
+ */
+#define BLKID_PROBE_ERROR      -1
+/**
+ * BLKID_PROBE_AMBIGUOUS:
+ *
+ * probing return value; more than one probing result, in this case, it's not
+ * safe to use the device automaticaly and user intervention is recommended
+ */
+#define BLKID_PROBE_AMBIGUOUS  -2
 
 extern int blkid_probe_numof_values(blkid_probe pr)
                        __ul_attribute__((nonnull));