7e9c36eb76d44606ff737cef82f814d44a1766e7
[openssl.git] / 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  #include <openssl/crypto.h>
31
32  unsigned int OPENSSL_version_major(void);
33  unsigned int OPENSSL_version_minor(void);
34  unsigned int OPENSSL_version_patch(void);
35  const char *OPENSSL_version_pre_release(void);
36  const char *OPENSSL_version_build_metadata(void);
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 filename.
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