Add man pages for version interospectionHEAD1.2master

Signed-off-by: Mattias Andrée <m@maandree.se>

13 files changed, 341 insertions, 19 deletions

diff --git a/LIBRECRYPT_VERSION_CMP_BUILD.3 b/LIBRECRYPT_VERSION_CMP_BUILD.3
new file mode 100644
index 0000000..1ec33d4
--- /dev/null
+++ b/LIBRECRYPT_VERSION_CMP_BUILD.3
@@ -0,0 +1,123 @@
+.TH LIBRECRYPT_VERSION_CMP_BUILD 3 LIBRECRYPT
+.SH NAME
+LIBRECRYPT_VERSION_CMP_BUILD - Compare version against compiled against version
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+#define \fBLIBRECRYPT_VERSION_MAJOR\fP /* version-dependent int value */
+#define \fBLIBRECRYPT_VERSION_MINOR\fP /* version-dependent int value */
+#define \fBLIBRECRYPT_VERSION_PATCH\fP /* version-dependent int value */
+
+#define \fBLIBRECRYPT_VERSION_CMP_BUILD\fP(\fIMAJOR\fP, \fIMINOR\fP, \fIPATCH\fP) /* implementation omitted */
+.fi
+
+.SH DESCRIPTION
+The
+.BR LIBRECRYPT_VERSION_MAJOR ,
+.BR LIBRECRYPT_VERSION_MINOR ,
+and
+.B LIBRECRYPT_VERSION_PATCH
+macros are compile-time constant expression
+describing the version number of the version of
+.B librecrypt
+that the application is compiled against.
+Each of these are simple integer-literals of the
+type
+.IR int .
+.PP
+.B LIBRECRYPT_VERSION_MAJOR
+is the major number. It is increased when there
+are backwards incompatible changes, necessitating
+the that the application is recompiled or even
+rewritten
+.PP
+.B LIBRECRYPT_VERSION_MINOR
+is the minor number. It is increased when the API
+is extended. It is reset to zero when the major
+number is modified.
+.PP
+.B LIBRECRYPT_VERSION_PATCH
+is the patch number. It is increased when the
+software is modified but the API and ABI are
+unmodified. It is reset to zero when the major or
+minor number is modified.
+.PP
+The
+.B LIBRECRYPT_VERSION_CMP_BUILD
+macro compares
+.IR MAJOR ,
+.IR MINOR ,
+and
+.I PATCH
+against
+.BR LIBRECRYPT_VERSION_MAJOR ,
+.BR LIBRECRYPT_VERSION_MINOR ,
+and
+.BR LIBRECRYPT_VERSION_PATCH .
+.PP
+If the versions are the same, the macro expands to an
+expression with the value 0 and the type
+.IR int .
+.PP
+If the specified version is newer than the version
+the application is compiled against, the macro expands
+to an expression with a positive value of the type
+.IR int .
+.PP
+If the specified version is older than the version
+the application is compiled against, the macro expands
+to an expression with a negative value of the type
+.IR int .
+.PP
+If the versions are different, the most most significant
+different number determines the absolute value of the
+value the macro expands to. If the major numbers are
+different, the absolute value is 3, otherwise if the
+minor numbers are different, the absolute value is 3,
+otherwise (if the patch numbers are different), the
+absolute value is 1.
+
+.SH APPLICATION USAGE
+Use
+.I #if !defined(LIBRECRYPT_VERSION_MAJOR)
+to detect when the version number is lower than 1.2.
+There are no macros defined between 1.0 and 1.2,
+so getting the exact number is not possible.
+
+.SH NOTES
+The version number of
+.B librecrypt
+is formatted as
+.IR major.minor.patch.revision ,
+or
+.IR major.minor.patch
+when
+.I reversion
+is 0, or
+.IR major.minor
+when both
+.I patch
+and
+.I revision
+are 0.
+.PP
+.I revision
+cannot be tested agaist since it is only incremented
+when no changes are made to the library software but
+for example only to documentation or build script
+(or reset to 0 when any of the other numbers are modified).
+
+.SH HISTORY
+The
+.BR LIBRECRYPT_VERSION_MAJOR ,
+.BR LIBRECRYPT_VERSION_MINOR ,
+.BR LIBRECRYPT_VERSION_PATCH ,
+.BR LIBRECRYPT_VERSION_CMP_BUILD ,
+macros were introduced in version 1.2 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR LIBRECRYPT_VERSION_CMP_LINK (3)
diff --git a/LIBRECRYPT_VERSION_CMP_LINK.3 b/LIBRECRYPT_VERSION_CMP_LINK.3
new file mode 100644
index 0000000..4fc810c
--- /dev/null
+++ b/LIBRECRYPT_VERSION_CMP_LINK.3
@@ -0,0 +1,145 @@
+.TH LIBRECRYPT_VERSION_CMP_LINK 3 LIBRECRYPT
+.SH NAME
+LIBRECRYPT_VERSION_CMP_LINK - Compare version against linked against version
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+extern const int \fBlibrecrypt_version_major\fP;
+extern const int \fBlibrecrypt_version_minor\fP;
+extern const int \fBlibrecrypt_version_patch\fP;
+
+#define \fBLIBRECRYPT_VERSION_CMP_LINK\fP(\fIMAJOR\fP, \fIMINOR\fP, \fIPATCH\fP) /* implementation omitted */
+
+.fi
+.PP
+Link with
+.IR -lrecrypt .
+
+.SH DESCRIPTION
+The
+.BR librecrypt_version_major ,
+.BR librecrypt_version_minor ,
+and
+.B librecrypt_version_patch
+variables describe the version number of the
+version of
+.B librecrypt
+that the application is linked against.
+.PP
+.B librecrypt_version_major
+is the major number. It is increased when there
+are backwards incompatible changes, necessitating
+the that the application is recompiled or even
+rewritten
+.PP
+.B librecrypt_version_minor
+is the minor number. It is increased when the API
+is extended. It is reset to zero when the major
+number is modified.
+.PP
+.B librecrypt_version_patch
+is the patch number. It is increased when the
+software is modified but the API and ABI are
+unmodified. It is reset to zero when the major or
+minor number is modified.
+.PP
+The
+.B LIBRECRYPT_VERSION_CMP_LINK
+macro compares
+.IR MAJOR ,
+.IR MINOR ,
+and
+.I PATCH
+against
+.BR librecrypt_version_major ,
+.BR librecrypt_version_minor ,
+and
+.BR librecrypt_version_patch .
+.PP
+If the versions are the same, the macro expands to an
+expression with the value 0 and the type
+.IR int .
+.PP
+If the specified version is newer than the version
+the application is linked against, the macro expands
+to an expression with a positive value of the type
+.IR int .
+.PP
+If the specified version is older than the version
+the application is linked against, the macro expands
+to an expression with a negative value of the type
+.IR int .
+.PP
+If the versions are different, the most most significant
+different number determines the absolute value of the
+value the macro expands to. If the major numbers are
+different, the absolute value is 3, otherwise if the
+minor numbers are different, the absolute value is 3,
+otherwise (if the patch numbers are different), the
+absolute value is 1.
+
+.SH APPLICATION USAGE
+Because these variables were introduced in version
+1.2 of
+.BR librecrypt ,
+it is impossible to check the exact version if
+it is lower than 1.2, however, using weak
+linkage it is possible to check if the linked
+version is lower than 1.2: in your application
+define this variable with weak linkage. You
+can set it to 0 and let the library replace it
+if it has defined it, or you can simply declare
+it as an external symbol without providing it:
+then taking the address of it will return
+.B NULL
+if it doesn't exist: you can use this trick with
+any function may be want to use as well.
+.PP
+Additionally, without
+.BR librecrypt_version_major ,
+.BR librecrypt_version_minor ,
+and
+.B librecrypt_version_patch
+properly linked,
+.B LIBRECRYPT_VERSION_CMP_LINK
+will fail at runtime.
+
+.SH NOTES
+The version number of
+.B librecrypt
+is formatted as
+.IR major.minor.patch.revision ,
+or
+.IR major.minor.patch
+when
+.I reversion
+is 0, or
+.IR major.minor
+when both
+.I patch
+and
+.I revision
+are 0.
+.PP
+.I revision
+cannot be tested agaist since it is only incremented
+when no changes are made to the library software but
+for example only to documentation or build script
+(or reset to 0 when any of the other numbers are modified).
+
+.SH HISTORY
+The
+.BR librecrypt_version_major ,
+.BR librecrypt_version_minor ,
+and
+.B librecrypt_version_patch
+variables and the
+.B LIBRECRYPT_VERSION_CMP_LINK
+macro were introduced in version 1.2 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR LIBRECRYPT_VERSION_CMP_BUILD (3)
diff --git a/LIBRECRYPT_VERSION_MAJOR.3 b/LIBRECRYPT_VERSION_MAJOR.3
new file mode 120000
index 0000000..2bd8d26
--- /dev/null
+++ b/LIBRECRYPT_VERSION_MAJOR.3
@@ -0,0 +1 @@
+LIBRECRYPT_VERSION_CMP_BUILD.3
\ No newline at end of file
diff --git a/LIBRECRYPT_VERSION_MINOR.3 b/LIBRECRYPT_VERSION_MINOR.3
new file mode 120000
index 0000000..2bd8d26
--- /dev/null
+++ b/LIBRECRYPT_VERSION_MINOR.3
@@ -0,0 +1 @@
+LIBRECRYPT_VERSION_CMP_BUILD.3
\ No newline at end of file
diff --git a/LIBRECRYPT_VERSION_PATCH.3 b/LIBRECRYPT_VERSION_PATCH.3
new file mode 120000
index 0000000..2bd8d26
--- /dev/null
+++ b/LIBRECRYPT_VERSION_PATCH.3
@@ -0,0 +1 @@
+LIBRECRYPT_VERSION_CMP_BUILD.3
\ No newline at end of file
diff --git a/Makefile b/Makefile
index 364d44c..d509c85 100644
--- a/Makefile
+++ b/Makefile
@@ -46,8 +46,7 @@ OBJ_PUBLIC_NO_FUZZ =\
 	librecrypt_set_user_data.o\
 	librecrypt_get_user_data.o\
 	librecrypt_set_pepper.o\
-	librecrypt_set_custom_algorithms.o\
-	librecrypt_version.o
+	librecrypt_set_custom_algorithms.o
 
 OBJ_PUBLIC =\
 	$(OBJ_PUBLIC_FUZZ)\
@@ -78,6 +77,7 @@ OBJ_PRIVATE =\
 	librecrypt_raw_len_to_base64_len_.o\
 	librecrypt_base64_len_to_raw_len_.o\
 	librecrypt_is_base64_properly_padded_.o\
+	librecrypt_version.o\
 	$(OBJ_COMMON_RFC4848S4)
 
 USE_OBJ_COMMON_RFC4848S4 =\
@@ -91,12 +91,22 @@ HDR =\
 	common.h\
 	algorithms.h
 
+MAN3 = \
+	$(OBJ_PUBLIC:.o=.3)\
+	LIBRECRYPT_VERSION_MAJOR.3\
+	LIBRECRYPT_VERSION_MINOR.3\
+	LIBRECRYPT_VERSION_PATCH.3\
+	librecrypt_version_major.3\
+	librecrypt_version_minor.3\
+	librecrypt_version_patch.3\
+	LIBRECRYPT_VERSION_CMP_BUILD.3\
+	LIBRECRYPT_VERSION_CMP_LINK.3
+
 LOBJ = $(OBJ:.o=.lo)
 TOBJ = $(OBJ:.o=.to)
 TEST = $(OBJ:.o=.t)
 FOBJ = $(OBJ_PUBLIC_FUZZ:.o=.fo)
 FUZZ = $(OBJ_PUBLIC_FUZZ:.o=.f)
-MAN3 = $(OBJ_PUBLIC:.o=.3)
 MAN7 = librecrypt.7
 
 all:
diff --git a/README b/README
index 197e6eb..6e375f7 100644
--- a/README
+++ b/README
@@ -108,13 +108,33 @@ DESCRIPTION
 
    Library introspection (ADVANCED):
 	librecrypt_is_enabled(3)
-		Check whenther the library is compiled with support
+		Check whether the library is compiled with support
 		for a specific hash algorithm.
 
 	librecrypt_hash_algorithm_end(3)
 		Number of hash algorithms the linked library knows
 		about.
 
+	librecrypt_version_major(3)
+	librecrypt_version_minor(3)
+	librecrypt_version_patch(3)
+		Get the version of the library the application
+		is linked against.
+
+	LIBRECRYPT_VERSION_MAJOR(3)
+	LIBRECRYPT_VERSION_MINOR(3)
+	LIBRECRYPT_VERSION_PATCH(3)
+		Get the version of the library the application
+		is compiled against.
+
+	LIBRECRYPT_VERSION_CMP_LINK(3)
+		Compare a version number against the version of the
+		library the application is linked against
+
+	LIBRECRYPT_VERSION_CMP_BUILD(3)
+		Compare a version number against the version of the
+		library the application is compiled against
+
    Library tweaking functions (ADVANCED):
 	librecrypt_create_context(3)
 		Create a library configuration object.
diff --git a/TODO b/TODO
index 3c5e8f4..3144966 100644
--- a/TODO
+++ b/TODO
@@ -1,12 +1,4 @@
 Document `struct librecrypt_algorithm` in librecrypt_set_custom_algorithms.3
-Add man pages to LIBRECRYPT_VERSION_MAJOR,
-                 LIBRECRYPT_VERSION_MINOR,
-                 LIBRECRYPT_VERSION_PATCH,
-                 librecrypt_version_major,
-                 librecrypt_version_minor,
-                 librecrypt_version_patch,
-                 LIBRECRYPT_VERSION_CMP_BUILD,
-                 LIBRECRYPT_VERSION_CMP_LINK
 Write fuzzing code for the files listed in OBJ_PUBLIC.
 Add corpuses for fuzzing.
 Add documentation similar to crypt(5).
diff --git a/librecrypt.7 b/librecrypt.7
index caf7eda..785ee1e 100644
--- a/librecrypt.7
+++ b/librecrypt.7
@@ -132,12 +132,36 @@ chain.
 .SS Library introspection (ADVANCED):
 .TP
 .BR librecrypt_is_enabled (3)
-Check whenther the library is compiled with support
+Check whether the library is compiled with support
 for a specific hash algorithm.
 .TP
 .BR librecrypt_hash_algorithm_end (3)
 Number of hash algorithms the linked library knows
 about.
+.TP
+.BR librecrypt_version_major (3)
+.TQ
+.BR librecrypt_version_minor (3)
+.TQ
+.BR librecrypt_version_patch (3)
+Get the version of the library the application
+is linked against.
+.TP
+.BR LIBRECRYPT_VERSION_MAJOR (3)
+.TQ
+.BR LIBRECRYPT_VERSION_MINOR (3)
+.TQ
+.BR LIBRECRYPT_VERSION_PATCH (3)
+Get the version of the library the application
+is compiled against.
+.TP
+.BR LIBRECRYPT_VERSION_CMP_LINK (3)
+Compare a version number against the version of the
+library the application is linked against
+.TP
+.BR LIBRECRYPT_VERSION_CMP_BUILD (3)
+Compare a version number against the version of the
+library the application is compiled against
 .sp
 .SS Library tweaking functions (ADVANCED):
 .TP
diff --git a/librecrypt.h b/librecrypt.h
index aec7574..86d0d81 100644
--- a/librecrypt.h
+++ b/librecrypt.h
@@ -59,8 +59,8 @@
  * is recompiled or even rewritten
  *
  * Use `#if !defined(LIBRECRYPT_VERSION_MAJOR)` to
- * when the version number is lower than 1.2;
- * there are no macros defined between 1.0 and 1.2,
+ * detect when the version number is lower than 1.2.
+ * There are no macros defined between 1.0 and 1.2,
  * so getting the exact number is not possible.
  *
  * @seealso  librecrypt_version_major
@@ -76,7 +76,8 @@
  * The minor number of the version of librecrypt
  * that that the application is compiled against
  *
- * Increased when the API is extended
+ * Increased when the API is extended, or reset
+ * to zero when the major number is modified.
  *
  * @seealso  librecrypt_version_minor
  * @seealso  LIBRECRYPT_VERSION_MAJOR
@@ -91,9 +92,10 @@
  * The patch number of the version of librecrypt
  * that that the application is compiled against
  *
- * Incrased when the software is modified but
- * the API and ABI are unmodified, or extended
- * without adding new functionality proper
+ * Increased when the software is modified but
+ * the API and ABI are unmodified. It is reset
+ * to zero when the major or minor number is
+ * modified
  *
  * @seealso  librecrypt_version_patch
  * @seealso  LIBRECRYPT_VERSION_MAJOR
diff --git a/librecrypt_version_major.3 b/librecrypt_version_major.3
new file mode 120000
index 0000000..bb3a1d4
--- /dev/null
+++ b/librecrypt_version_major.3
@@ -0,0 +1 @@
+LIBRECRYPT_VERSION_CMP_LINK.3
\ No newline at end of file
diff --git a/librecrypt_version_minor.3 b/librecrypt_version_minor.3
new file mode 120000
index 0000000..bb3a1d4
--- /dev/null
+++ b/librecrypt_version_minor.3
@@ -0,0 +1 @@
+LIBRECRYPT_VERSION_CMP_LINK.3
\ No newline at end of file
diff --git a/librecrypt_version_patch.3 b/librecrypt_version_patch.3
new file mode 120000
index 0000000..bb3a1d4
--- /dev/null
+++ b/librecrypt_version_patch.3
@@ -0,0 +1 @@
+LIBRECRYPT_VERSION_CMP_LINK.3
\ No newline at end of file