Latest update. (3.0.0-dev)

doc/man7/openssl_user_macros.pod.in

@@ -0,0 +1,97 @@
+=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
+
+=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
+
+=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
+
+=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
+
+=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