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