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