]>
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 | ||
128 | =back | |
129 | ||
130 | For an unknown B<t>, the text "not available" is returned. | |
131 | ||
0109e030 RL |
132 | OPENSSL_info() also returns different strings depending on B<t>: |
133 | ||
134 | =over 4 | |
135 | ||
136 | =item OPENSSL_INFO_CONFIG_DIR | |
137 | ||
138 | The configured C<OPENSSLDIR>, which is the default location for | |
139 | OpenSSL configuration files. | |
140 | ||
141 | =item OPENSSL_INFO_ENGINES_DIR | |
142 | ||
143 | The configured C<ENGINESDIR>, which is the default location for | |
144 | OpenSSL engines. | |
145 | ||
146 | =item OPENSSL_INFO_MODULES_DIR | |
147 | ||
148 | The configured C<MODULESDIR>, which is the default location for | |
149 | dynamically loadable OpenSSL modules other than engines. | |
150 | ||
151 | =item OPENSSL_INFO_DSO_EXTENSION | |
152 | ||
153 | The configured dynamically loadable module extension. | |
154 | ||
155 | =item OPENSSL_INFO_DIR_FILENAME_SEPARATOR | |
156 | ||
157 | The separator between a directory specification and a file name. | |
158 | Note that on some operating systems, this is not the same as the | |
159 | separator between directory elements. | |
160 | ||
161 | =item OPENSSL_INFO_LIST_SEPARATOR | |
162 | ||
163 | The OpenSSL list separator. | |
164 | This is typically used in strings that are lists of items, such as the | |
165 | value of the environment variable C<$PATH> on Unix (where the | |
166 | separator is ":") or C<%PATH%> on Windows (where the separator is | |
167 | ";"). | |
168 | ||
169 | =back | |
170 | ||
171 | For an unknown B<t>, NULL is returned. | |
172 | ||
3a63dbef RL |
173 | =head1 BACKWARD COMPATIBILITY |
174 | ||
175 | For compatibility, some older macros and functions are retained or | |
176 | synthesised. | |
177 | They are all considered deprecated. | |
178 | ||
179 | =head2 Macros | |
180 | ||
181 | B<OPENSSL_VERSION_NUMBER> is a combination of the major, minor and | |
182 | patch version into a single integer 0xMNN00PP0L, where: | |
183 | ||
184 | =over 4 | |
185 | ||
186 | =item M | |
187 | ||
188 | is the number from B<OPENSSL_VERSION_MAJOR>, in hexadecimal notation | |
189 | ||
190 | =item NN | |
191 | ||
192 | is the number from B<OPENSSL_VERSION_MINOR>, in hexadecimal notation | |
193 | ||
194 | =item PP | |
195 | ||
196 | is the number from B<OPENSSL_VERSION_PATCH>, in hexadecimal notation | |
197 | ||
198 | =back | |
199 | ||
200 | =head2 Functions | |
201 | ||
202 | OpenSSL_version_num() returns the value of B<OPENSSL_VERSION_NUMBER>. | |
203 | ||
204 | =head1 RETURN VALUES | |
205 | ||
206 | OPENSSL_version_major(), OPENSSL_version_minor() and OPENSSL_version_patch() | |
207 | return the version number parts as integers. | |
208 | ||
209 | OPENSSL_version_pre_release() and OPENSSL_version_build_metadata() return | |
210 | the values of B<OPENSSL_VERSION_PRE_RELEASE> and | |
211 | B<OPENSSL_VERSION_BUILD_METADATA> respectively as constant strings. | |
212 | For any of them that is undefined, the empty string is returned. | |
213 | ||
214 | OpenSSL_version() returns constant strings. | |
215 | ||
216 | =head1 SEE ALSO | |
217 | ||
218 | L<crypto(7)> | |
219 | ||
220 | =head1 HISTORY | |
221 | ||
fc5ecadd | 222 | The macros and functions described here were added in OpenSSL 3.0.0, |
3a63dbef RL |
223 | with the exception of the L</BACKWARD COMPATIBILITY> ones. |
224 | ||
225 | =head1 COPYRIGHT | |
226 | ||
227 | Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. | |
228 | ||
4ace4ccd | 229 | Licensed under the Apache License 2.0 (the "License"). You may not use |
3a63dbef RL |
230 | this file except in compliance with the License. You can obtain a copy |
231 | in the file LICENSE in the source distribution or at | |
232 | L<https://www.openssl.org/source/license.html>. | |
233 | ||
234 | =cut |