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