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 =back
 129
 130 For an unknown B<t>, the text "not available" is returned.
 131
 132 OPENSSL_info() also returns different strings depending on B<t>:
 133
 134 =over 4
 135
 136 =item OPENSSL_INFO_CONFIG_DIR
 137
 138 The configured C<OPENSSLDIR>, which is the default location for
 139 OpenSSL configuration files.
 140
 141 =item OPENSSL_INFO_ENGINES_DIR
 142
 143 The configured C<ENGINESDIR>, which is the default location for
 144 OpenSSL engines.
 145
 146 =item OPENSSL_INFO_MODULES_DIR
 147
 148 The configured C<MODULESDIR>, which is the default location for
 149 dynamically loadable OpenSSL modules other than engines.
 150
 151 =item OPENSSL_INFO_DSO_EXTENSION
 152
 153 The configured dynamically loadable module extension.
 154
 155 =item OPENSSL_INFO_DIR_FILENAME_SEPARATOR
 156
 157 The separator between a directory specification and a file name.
 158 Note that on some operating systems, this is not the same as the
 159 separator between directory elements.
 160
 161 =item OPENSSL_INFO_LIST_SEPARATOR
 162
 163 The OpenSSL list separator.
 164 This is typically used in strings that are lists of items, such as the
 165 value of the environment variable C<$PATH> on Unix (where the
 166 separator is ":") or C<%PATH%> on Windows (where the separator is
 167 ";").
 168
 169 =back
 170
 171 For an unknown B<t>, NULL is returned.
 172
 173 =head1 BACKWARD COMPATIBILITY
 174
 175 For compatibility, some older macros and functions are retained or
 176 synthesised.
 177 They are all considered deprecated.
 178
 179 =head2 Macros
 180
 181 B<OPENSSL_VERSION_NUMBER> is a combination of the major, minor and
 182 patch version into a single integer 0xMNN00PP0L, where:
 183
 184 =over 4
 185
 186 =item M
 187
 188 is the number from B<OPENSSL_VERSION_MAJOR>, in hexadecimal notation
 189
 190 =item NN
 191
 192 is the number from B<OPENSSL_VERSION_MINOR>, in hexadecimal notation
 193
 194 =item PP
 195
 196 is the number from B<OPENSSL_VERSION_PATCH>, in hexadecimal notation
 197
 198 =back
 199
 200 =head2 Functions
 201
 202 OpenSSL_version_num() returns the value of B<OPENSSL_VERSION_NUMBER>.
 203
 204 =head1 RETURN VALUES
 205
 206 OPENSSL_version_major(), OPENSSL_version_minor() and OPENSSL_version_patch()
 207 return the version number parts as integers.
 208
 209 OPENSSL_version_pre_release() and OPENSSL_version_build_metadata() return
 210 the values of B<OPENSSL_VERSION_PRE_RELEASE> and
 211 B<OPENSSL_VERSION_BUILD_METADATA> respectively as constant strings.
 212 For any of them that is undefined, the empty string is returned.
 213
 214 OpenSSL_version() returns constant strings.
 215
 216 =head1 SEE ALSO
 217
 218 L<crypto(7)>
 219
 220 =head1 HISTORY
 221
 222 The macros and functions described here were added in OpenSSL 3.0.0,
 223 with the exception of the L</BACKWARD COMPATIBILITY> ones.
 224
 225 =head1 COPYRIGHT
 226
 227 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
 228
 229 Licensed under the Apache License 2.0 (the "License").  You may not use
 230 this file except in compliance with the License.  You can obtain a copy
 231 in the file LICENSE in the source distribution or at
 232 L<https://www.openssl.org/source/license.html>.
 233
 234 =cut