openssl/doc/man7/openssl_user_macros.pod.in

98 lines
2.5 KiB
Plaintext
Raw Normal View History

=pod
=head1 NAME
openssl_user_macros, OPENSSL_API_COMPAT - User defined macros
=head1 DESCRIPTION
User defined macros allow the programmer to control certain aspects of
what is exposed by the OpenSSL headers.
B<NOTE:> to be effective, a user defined macro I<must be defined
before including any header file that depends on it>, either in the
compilation command (C<cc -DMACRO=value>) or by defining the macro in
source before including any headers.
Other manual pages may refer to this page when declarations depend on
user defined macros.
=head2 The macros
=over 4
=item B<OPENSSL_API_COMPAT>
The value is a version number similar to the
L<OPENSSL_VERSION_NUMBER(3)> macro. Any symbol that is deprecated in
versions up to and including the version given in this macro will not
be declared.
The version number assigned to this macro can take one of two forms:
=over 4
=item C<0xMNNFF000L>
This is the form supported for all versions up 1.1.x, where C<M>
represents the major number, C<NN> represents the minor number, and
C<FF> represents the fix number. For version 1.1.0, that's
C<0x10100000L>.
Any version number may be given, but these numbers are
the current known major deprecation points, making them the most
meaningful:
=over 4
=item C<0x00908000L> (version 0.9.8)
=item C<0x10000000L> (version 1.0.0)
=item C<0x10100000L> (version 1.1.0)
=back
For convenience, higher numbers are accepted as well, as long as
feasible. For example, C<0x60000000L> will work as expected.
However, it is recommended to start using the second form instead:
=item C<m>
This form is a simple number that represents the major version number
and is supported for version 3.0.0 and up. For extra convenience,
these numbers are also available:
=over 4
=item Z<>0 (C<0x00908000L>, i.e. version 0.9.8)
=item Z<>1 (C<0x10000000L>, i.e. version 1.0.0)
=item Z<>2 (C<0x10100000L>, i.e. version 1.1.0)
=back
For all other numbers C<m>, they are equivalent to version m.0.0.
=back
If not set, this macro will default to
C<{- join('', map { my @x = split /=/,$_; $x[1] }
grep /^OPENSSL_MIN_API=/, @{$config{openssl_api_defines} // []})
|| '0x00000000L'
-}>.
=back
=head1 COPYRIGHT
Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut