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_TEXT, OPENSSL_VERSION_PREREQ, OPENSSL_version_major,
   8 OPENSSL_version_minor, OPENSSL_version_patch, OPENSSL_version_pre_release,
   9 OPENSSL_version_build_metadata, OpenSSL_version, OPENSSL_VERSION_NUMBER,
  10 OpenSSL_version_num, OPENSSL_info
  11 - get OpenSSL version number and other information
  12
  13 =head1 SYNOPSIS
  14
  15  #include <openssl/opensslv.h>
  16
  17  #define OPENSSL_VERSION_MAJOR  x
  18  #define OPENSSL_VERSION_MINOR  y
  19  #define OPENSSL_VERSION_PATCH  z
  20
  21  /* The definitions here are typical release values */
  22  #define OPENSSL_VERSION_PRE_RELEASE ""
  23  #define OPENSSL_VERSION_BUILD_METADATA ""
  24
  25  #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx"
  26
  27  #define OPENSSL_VERSION_PREREQ(maj,min)
  28
  29  #include <openssl/crypto.h>
  30
  31  unsigned int OPENSSL_version_major(void);
  32  unsigned int OPENSSL_version_minor(void);
  33  unsigned int OPENSSL_version_patch(void);
  34  const char *OPENSSL_version_pre_release(void);
  35  const char *OPENSSL_version_build_metadata(void);
  36
  37  const char *OpenSSL_version(int t);
  38
  39  const char *OPENSSL_info(int t);
  40
  41 Deprecated:
  42
  43  /* from openssl/opensslv.h */
  44  #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnL
  45
  46  /* from openssl/crypto.h */
  47  unsigned long OpenSSL_version_num();
  48
  49 =head1 DESCRIPTION
  50
  51 =head2 Macros
  52
  53 The three macros B<OPENSSL_VERSION_MAJOR>, B<OPENSSL_VERSION_MINOR> and
  54 B<OPENSSL_VERSION_PATCH> represent the three parts of a version
  55 identifier, B<I<MAJOR>.I<MINOR>.I<PATCH>>.
  56
  57 The macro B<OPENSSL_VERSION_PRE_RELEASE> is an added bit of text that
  58 indicates that this is a pre-release version, such as C<"-dev"> for an
  59 ongoing development snapshot or C<"-alpha3"> for an alpha release.
  60 The value must be a string.
  61
  62 The macro B<OPENSSL_VERSION_BUILD_METADATA> is extra information, reserved
  63 for other parties, such as C<"+fips">, or C<"+vendor.1">).
  64 The OpenSSL project will not touch this macro (will leave it an empty string).
  65 The value must be a string.
  66
  67 B<OPENSSL_VERSION_STR> is a convenience macro to get the short version
  68 identifier string, C<"I<MAJOR>.I<MINOR>.I<PATCH>">.
  69
  70 B<OPENSSL_FULL_VERSION_STR> is a convenience macro to get the longer
  71 version identifier 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 B<OPENSSL_VERSION_PREREQ> is a useful macro for checking whether the OpenSSL
  79 version for the headers in use is at least at the given pre-requisite major
  80 (B<maj>) and minor (B<min>) number or not. It will evaluate to true if the
  81 header version number (B<OPENSSL_VERSION_MAJOR>.B<OPENSSL_VERSION_MINOR>) is
  82 greater than or equal to B<maj>.B<min>.
  83
  84 =head2 Functions
  85
  86 OPENSSL_version_major(), OPENSSL_version_minor(), OPENSSL_version_patch(),
  87 OPENSSL_version_pre_release(), and OPENSSL_version_build_metadata() return
  88 the values of the macros above for the build of the library, respectively.
  89
  90 OpenSSL_version() returns different strings depending on I<t>:
  91
  92 =over 4
  93
  94 =item OPENSSL_VERSION
  95
  96 The value of B<OPENSSL_VERSION_TEXT>
  97
  98 =item OPENSSL_VERSION_STRING
  99
 100 The value of B<OPENSSL_VERSION_STR>
 101
 102 =item OPENSSL_FULL_VERSION_STRING
 103
 104 The value of B<OPENSSL_FULL_VERSION_STR>
 105
 106 =item OPENSSL_CFLAGS
 107
 108 The compiler flags set for the compilation process in the form
 109 C<compiler: ...>  if available, or C<compiler: information not available>
 110 otherwise.
 111
 112 =item OPENSSL_BUILT_ON
 113
 114 The date of the build process in the form C<built on: ...> if available
 115 or C<built on: date not available> otherwise.
 116 The date would not be available in a reproducible build, for example.
 117
 118 =item OPENSSL_PLATFORM
 119
 120 The "Configure" target of the library build in the form C<platform: ...>
 121 if available, or C<platform: information not available> otherwise.
 122
 123 =item OPENSSL_DIR
 124
 125 The B<OPENSSLDIR> setting of the library build in the form C<OPENSSLDIR: "...">
 126 if available, or C<OPENSSLDIR: N/A> otherwise.
 127
 128 =item OPENSSL_ENGINES_DIR
 129
 130 The B<ENGINESDIR> setting of the library build in the form C<ENGINESDIR: "...">
 131 if available, or C<ENGINESDIR: N/A> otherwise. This option is deprecated in
 132 OpenSSL 3.0.
 133
 134 =item OPENSSL_MODULES_DIR
 135
 136 The B<MODULESDIR> setting of the library build in the form C<MODULESDIR: "...">
 137 if available, or C<MODULESDIR: N/A> otherwise.
 138
 139 =item OPENSSL_CPU_INFO
 140
 141 The current OpenSSL cpu settings.
 142 This is the current setting of the cpu capability flags. It is usually
 143 automatically configured but may be set via an environment variable.
 144 The value has the same syntax as the environment variable.
 145 For x86 the string looks like C<CPUINFO: OPENSSL_ia32cap=0x123:0x456>
 146 or C<CPUINFO: N/A> if not available.
 147
 148 =back
 149
 150 For an unknown I<t>, the text C<not available> is returned.
 151
 152 OPENSSL_info() also returns different strings depending on I<t>:
 153
 154 =over 4
 155
 156 =item OPENSSL_INFO_CONFIG_DIR
 157
 158 The configured C<OPENSSLDIR>, which is the default location for
 159 OpenSSL configuration files.
 160
 161 =item OPENSSL_INFO_ENGINES_DIR
 162
 163 The configured C<ENGINESDIR>, which is the default location for
 164 OpenSSL engines.
 165
 166 =item OPENSSL_INFO_MODULES_DIR
 167
 168 The configured C<MODULESDIR>, which is the default location for
 169 dynamically loadable OpenSSL modules other than engines.
 170
 171 =item OPENSSL_INFO_DSO_EXTENSION
 172
 173 The configured dynamically loadable module extension.
 174
 175 =item OPENSSL_INFO_DIR_FILENAME_SEPARATOR
 176
 177 The separator between a directory specification and a filename.
 178 Note that on some operating systems, this is not the same as the
 179 separator between directory elements.
 180
 181 =item OPENSSL_INFO_LIST_SEPARATOR
 182
 183 The OpenSSL list separator.
 184 This is typically used in strings that are lists of items, such as the
 185 value of the environment variable C<$PATH> on Unix (where the
 186 separator is C<:>) or C<%PATH%> on Windows (where the separator is
 187 C<;>).
 188
 189 =item OPENSSL_INFO_CPU_SETTINGS
 190
 191 The current OpenSSL cpu settings.
 192 This is the current setting of the cpu capability flags. It is usually
 193 automatically configured but may be set via an environment variable.
 194 The value has the same syntax as the environment variable.
 195 For x86 the string looks like C<OPENSSL_ia32cap=0x123:0x456>.
 196
 197 =back
 198
 199 For an unknown I<t>, NULL is returned.
 200
 201 =head1 BACKWARD COMPATIBILITY
 202
 203 For compatibility, some older macros and functions are retained or
 204 synthesised.
 205 They are all considered deprecated.
 206
 207 =head2 Macros
 208
 209 B<OPENSSL_VERSION_NUMBER> is a combination of the major, minor and
 210 patch version into a single integer 0xMNN00PP0L, where:
 211
 212 =over 4
 213
 214 =item M
 215
 216 is the number from B<OPENSSL_VERSION_MAJOR>, in hexadecimal notation
 217
 218 =item NN
 219
 220 is the number from B<OPENSSL_VERSION_MINOR>, in hexadecimal notation
 221
 222 =item PP
 223
 224 is the number from B<OPENSSL_VERSION_PATCH>, in hexadecimal notation
 225
 226 =back
 227
 228 =head2 Functions
 229
 230 OpenSSL_version_num() returns the value of B<OPENSSL_VERSION_NUMBER>.
 231
 232 =head1 RETURN VALUES
 233
 234 OPENSSL_version_major(), OPENSSL_version_minor() and OPENSSL_version_patch()
 235 return the version number parts as integers.
 236
 237 OPENSSL_version_pre_release() and OPENSSL_version_build_metadata() return
 238 the values of B<OPENSSL_VERSION_PRE_RELEASE> and
 239 B<OPENSSL_VERSION_BUILD_METADATA> respectively as constant strings.
 240 For any of them that is undefined, the empty string is returned.
 241
 242 OpenSSL_version() returns constant strings.
 243
 244 =head1 SEE ALSO
 245
 246 L<crypto(7)>
 247
 248 =head1 HISTORY
 249
 250 The macros and functions described here were added in OpenSSL 3.0,
 251 with the exception of the L</BACKWARD COMPATIBILITY> ones.
 252
 253 =head1 COPYRIGHT
 254
 255 Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
 256
 257 Licensed under the Apache License 2.0 (the "License").  You may not use
 258 this file except in compliance with the License.  You can obtain a copy
 259 in the file LICENSE in the source distribution or at
 260 L<https://www.openssl.org/source/license.html>.
 261
 262 =cut