1=pod
2
3=head1 NAME
4
5openssl_user_macros, OPENSSL_API_COMPAT, OPENSSL_NO_DEPRECATED
6- User defined macros
7
8=head1 DESCRIPTION
9
10User defined macros allow the programmer to control certain aspects of
11what is exposed by the OpenSSL headers.
12
13B<NOTE:> to be effective, a user defined macro I<must be defined
14before including any header file that depends on it>, either in the
15compilation command (C<cc -DMACRO=value>) or by defining the macro in
16source before including any headers.
17
18Other manual pages may refer to this page when declarations depend on
19user defined macros.
20
21=head2 The macros
22
23=over 4
24
25=item B<OPENSSL_API_COMPAT>
26
27The value is a version number, given in one of the following two forms:
28
29=over 4
30
31=item C<0xMNNFF000L>
32
33This is the form supported for all versions up to 1.1.x, where C<M>
34represents the major number, C<NN> represents the minor number, and
35C<FF> represents the fix number, as a hexadecimal number.  For version
361.1.0, that's C<0x10100000L>.
37
38Any version number may be given, but these numbers are
39the current known major deprecation points, making them the most
40meaningful:
41
42=over 4
43
44=item C<0x00908000L> (version 0.9.8)
45
46=item C<0x10000000L> (version 1.0.0)
47
48=item C<0x10100000L> (version 1.1.0)
49
50=back
51
52For convenience, higher numbers are accepted as well, as long as
53feasible.  For example, C<0x60000000L> will work as expected.
54However, it is recommended to start using the second form instead:
55
56=item C<mmnnpp>
57
58This form is a simple decimal number calculated with this formula:
59
60I<major> * 10000 + I<minor> * 100 + I<patch>
61
62where I<major>, I<minor> and I<patch> are the desired major,
63minor and patch components of the version number.  For example:
64
65=over 4
66
67=item 30000 corresponds to version 3.0.0
68
69=item 10002 corresponds to version 1.0.2
70
71=item 420101 corresponds to version 42.1.1
72
73=back
74
75=back
76
77If B<OPENSSL_API_COMPAT> is undefined, this default value is used in its
78place:
79C<{- join('', map { my @x = split /=/,$_; $x[1] }
80              grep /^OPENSSL_CONFIGURED_API=/, @{$config{openssl_api_defines} // []})
81     || '0x00000000L'
82  -}>
83
84=item B<OPENSSL_NO_DEPRECATED>
85
86If this macro is defined, all deprecated public symbols in all OpenSSL
87versions up to and including the version given by B<OPENSSL_API_COMPAT>
88(or the default value given above, when B<OPENSSL_API_COMPAT> isn't defined)
89will be hidden.
90
91=back
92
93=head1 COPYRIGHT
94
95Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
96
97Licensed under the Apache License 2.0 (the "License").  You may not use
98this file except in compliance with the License.  You can obtain a copy
99in the file LICENSE in the source distribution or at
100L<https://www.openssl.org/source/license.html>.
101
102=cut
103