doc/man3/OpenSSL_version.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR, OPENSSL_VERSION_PATCH,
   6 OPENSSL_VERSION_PRE_RELEASE, OPENSSL_VERSION_BUILD_METADATA,
   7 OPENSSL_VERSION_PRE_RELEASE_STR, OPENSSL_VERSION_BUILD_METADATA_STR,
   8 OPENSSL_VERSION_TEXT,
   9 OPENSSL_version_major, OPENSSL_version_minor, OPENSSL_version_patch,
  10 OPENSSL_version_pre_release, OPENSSL_version_build_metadata, OpenSSL_version,
  11 OPENSSL_VERSION_NUMBER, OpenSSL_version_num
  12 - get OpenSSL version number
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/opensslv.h>
  17
  18  #define OPENSSL_VERSION_MAJOR  x
  19  #define OPENSSL_VERSION_MINOR  y
  20  #define OPENSSL_VERSION_PATCH  z
  21
  22  /* The definitions here are typical release values */
  23  #undef OPENSSL_VERSION_PRE_RELEASE
  24  #undef OPENSSL_VERSION_BUILD_METADATA
  25  #define OPENSSL_VERSION_PRE_RELEASE_STR ""
  26  #define OPENSSL_VERSION_BUILD_METADATA_STR ""
  27
  28  #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx"
  29
  30  unsigned int OPENSSL_version_major(void);
  31  unsigned int OPENSSL_version_minor(void);
  32  unsigned int OPENSSL_version_patch(void);
  33  const char *OPENSSL_version_pre_release(void);
  34  const char *OPENSSL_version_build_metadata(void);
  35
  36  #include <openssl/crypto.h>
  37
  38  const char *OpenSSL_version(int t);
  39
  40 Deprecated:
  41
  42  /* from openssl/opensslv.h */
  43  #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL
  44
  45  /* from openssl/crypto.h */
  46  unsigned long OpenSSL_version_num();
  47
  48 =head1 DESCRIPTION
  49
  50 =head2 Macros
  51
  52 The three macros B<OPENSSL_VERSION_MAJOR>, B<OPENSSL_VERSION_MINOR> and
  53 B<OPENSSL_VERSION_PATCH> represent the three parts of a 3 numbered version
  54 number, MAJOR.MINOR.PATCH.
  55
  56 The macro B<OPENSSL_VERSION_PRE_RELEASE> is an added bit of text that,
  57 when defined, indicates that this is a pre-release version, such as
  58 C<"-dev"> for an ongoing development snapshot, C<"-alpha3"> for an
  59 alpha release, etc...
  60 The value must be a string.
  61
  62 The macro B<OPENSSL_VERSION_BUILD_METADATA> is extra metadata, reserved
  63 for other parties (examples: C<"+fips">, C<"+vendor.1">).
  64 The OpenSSL project will not touch this macro.
  65 The value must be a string.
  66
  67 B<OPENSSL_VERSION_STR> is a convenience macro to get the short version
  68 number string, "MAJOR.MINOR.PATCH".
  69
  70 B<OPENSSL_FULL_VERSION_STR> is a convenience macro to get the longer
  71 version number string, which combines B<OPENSSL_VERSION_STR>,
  72 B<OPENSSL_VERSION_PRE_RELEASE> and B<OPENSSL_VERSION_BUILD_METADATA>.
  73
  74 B<OPENSSL_VERSION_TEXT> is a convenience macro to get a full descriptive
  75 version text, which includes B<OPENSSL_FULL_VERSION_STR> and the release
  76 date.
  77
  78 =head2 Functions
  79
  80 OPENSSL_version_major(), OPENSSL_version_minor(), OPENSSL_version_patch(),
  81 OPENSSL_version_pre_release(), and OPENSSL_version_build_metadata() return
  82 the values of the macros above for the build of the library, respectively.
  83
  84 OpenSSL_version() returns different strings depending on B<t>:
  85
  86 =over 4
  87
  88 =item OPENSSL_VERSION
  89
  90 The value of B<OPENSSL_VERSION_TEXT>
  91
  92 =item OPENSSL_VERSION_STRING
  93
  94 The value of B<OPENSSL_VERSION_STR>
  95
  96 =item OPENSSL_FULL_VERSION_STRING
  97
  98 The value of B<OPENSSL_FULL_VERSION_STR>
  99
 100 =item OPENSSL_CFLAGS
 101
 102 The compiler flags set for the compilation process in the form
 103 "compiler: ..."  if available or "compiler: information not available"
 104 otherwise.
 105
 106 =item OPENSSL_BUILT_ON
 107
 108 The date of the build process in the form "built on: ..." if available
 109 or "built on: date not available" otherwise.
 110
 111 =item OPENSSL_PLATFORM
 112
 113 The "Configure" target of the library build in the form "platform: ..."
 114 if available or "platform: information not available" otherwise.
 115
 116 =item OPENSSL_DIR
 117
 118 The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "...""
 119 if available or "OPENSSLDIR: N/A" otherwise.
 120
 121 =item OPENSSL_ENGINES_DIR
 122
 123 The "ENGINESDIR" setting of the library build in the form "ENGINESDIR: "...""
 124 if available or "ENGINESDIR: N/A" otherwise.
 125
 126 =back
 127
 128 For an unknown B<t>, the text "not available" is returned.
 129
 130 =head1 BACKWARD COMPATIBILITY
 131
 132 For compatibility, some older macros and functions are retained or
 133 synthesised.
 134 They are all considered deprecated.
 135
 136 =head2 Macros
 137
 138 B<OPENSSL_VERSION_NUMBER> is a combination of the major, minor and
 139 patch version into a single integer 0xMNN00PP0L, where:
 140
 141 =over 4
 142
 143 =item M
 144
 145 is the number from B<OPENSSL_VERSION_MAJOR>, in hexadecimal notation
 146
 147 =item NN
 148
 149 is the number from B<OPENSSL_VERSION_MINOR>, in hexadecimal notation
 150
 151 =item PP
 152
 153 is the number from B<OPENSSL_VERSION_PATCH>, in hexadecimal notation
 154
 155 =back
 156
 157 =head2 Functions
 158
 159 OpenSSL_version_num() returns the value of B<OPENSSL_VERSION_NUMBER>.
 160
 161 =head1 RETURN VALUES
 162
 163 OPENSSL_version_major(), OPENSSL_version_minor() and OPENSSL_version_patch()
 164 return the version number parts as integers.
 165
 166 OPENSSL_version_pre_release() and OPENSSL_version_build_metadata() return
 167 the values of B<OPENSSL_VERSION_PRE_RELEASE> and
 168 B<OPENSSL_VERSION_BUILD_METADATA> respectively as constant strings.
 169 For any of them that is undefined, the empty string is returned.
 170
 171 OpenSSL_version() returns constant strings.
 172
 173 =head1 SEE ALSO
 174
 175 L<crypto(7)>
 176
 177 =head1 HISTORY
 178
 179 The macros and functions described here were added in OpenSSL 3.0.0,
 180 with the exception of the L</BACKWARD COMPATIBILITY> ones.
 181
 182 =head1 COPYRIGHT
 183
 184 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
 185
 186 Licensed under the Apache License 2.0 (the "License").  You may not use
 187 this file except in compliance with the License.  You can obtain a copy
 188 in the file LICENSE in the source distribution or at
 189 L<https://www.openssl.org/source/license.html>.
 190
 191 =cut