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