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