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