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