diff options
Diffstat (limited to '')
| -rw-r--r-- | LIBRECRYPT_VERSION_CMP_BUILD.3 | 123 | ||||
| -rw-r--r-- | LIBRECRYPT_VERSION_CMP_LINK.3 | 145 | ||||
| l--------- | LIBRECRYPT_VERSION_MAJOR.3 | 1 | ||||
| l--------- | LIBRECRYPT_VERSION_MINOR.3 | 1 | ||||
| l--------- | LIBRECRYPT_VERSION_PATCH.3 | 1 | ||||
| -rw-r--r-- | Makefile | 16 | ||||
| -rw-r--r-- | README | 22 | ||||
| -rw-r--r-- | TODO | 8 | ||||
| -rw-r--r-- | librecrypt.7 | 26 | ||||
| -rw-r--r-- | librecrypt.h | 14 | ||||
| l--------- | librecrypt_version_major.3 | 1 | ||||
| l--------- | librecrypt_version_minor.3 | 1 | ||||
| l--------- | librecrypt_version_patch.3 | 1 |
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 @@ -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: @@ -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. @@ -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 |