From: Karel Zak <kzak@redhat.com>
Date: Mon, 5 Dec 2022 10:57:13 +0000 (+0100)
Subject: libblkid: cleanup definitions and add docs for return values
X-Git-Tag: v2.39-rc1~391
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=69b73820d43fb7005fca33d135531cbcdc60e8cf;p=thirdparty%2Futil-linux.git

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 c0dc0d48d7..8684fdb5a2 100644
--- 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 0f1f1df84f..6132cb8a1a 100644
--- 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));