Add man pages for version interospectionHEAD1.2master

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

1 files changed, 123 insertions, 0 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)