]>
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, | |
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, | |
0109e030 RL |
11 | OPENSSL_VERSION_NUMBER, OpenSSL_version_num, OPENSSL_info |
12 | - get OpenSSL version number and other information | |
3a63dbef RL |
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 | ||
0109e030 RL |
40 | const char *OPENSSL_info(int t); |
41 | ||
3a63dbef RL |
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 | ||
363e941e BE |
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 | ||
3a63dbef RL |
142 | =back |
143 | ||
144 | For an unknown B<t>, the text "not available" is returned. | |
145 | ||
0109e030 RL |
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 file name. | |
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 | ||
363e941e BE |
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 | ||
0109e030 RL |
191 | =back |
192 | ||
193 | For an unknown B<t>, NULL is returned. | |
194 | ||
3a63dbef RL |
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 | ||
4674aaf4 | 244 | The macros and functions described here were added in OpenSSL 3.0, |
3a63dbef RL |
245 | with the exception of the L</BACKWARD COMPATIBILITY> ones. |
246 | ||
247 | =head1 COPYRIGHT | |
248 | ||
363e941e | 249 | Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved. |
3a63dbef | 250 | |
4ace4ccd | 251 | Licensed under the Apache License 2.0 (the "License"). You may not use |
3a63dbef RL |
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 |