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 4
  23
  24 =item B<OPENSSL_API_COMPAT>
  25
  26 The value is a version number, given in one of the following two forms:
  27
  28 =over 4
  29
  30 =item C<0xMNNFF000L>
  31
  32 This is the form supported for all versions up to 1.1.x, where C<M>
  33 represents the major number, C<NN> represents the minor number, and
  34 C<FF> represents the fix number, as a hexadecimal number.  For version
  35 1.1.0, that's C<0x10100000L>.
  36
  37 Any version number may be given, but these numbers are
  38 the current known major deprecation points, making them the most
  39 meaningful:
  40
  41 =over 4
  42
  43 =item C<0x00908000L> (version 0.9.8)
  44
  45 =item C<0x10000000L> (version 1.0.0)
  46
  47 =item C<0x10100000L> (version 1.1.0)
  48
  49 =back
  50
  51 For convenience, higher numbers are accepted as well, as long as
  52 feasible.  For example, C<0x60000000L> will work as expected.
  53 However, it is recommended to start using the second form instead:
  54
  55 =item C<mmnnpp>
  56
  57 This form is a simple decimal number calculated with this formula:
  58
  59 I<major> * 10000 + I<minor> * 100 + I<patch>
  60
  61 where I<major>, I<minor> and I<patch> are the desired major,
  62 minor and patch components of the version number.  For example:
  63
  64 =over 4
  65
  66 =item 30000 corresponds to version 3.0.0
  67
  68 =item 10002 corresponds to version 1.0.2
  69
  70 =item 420101 corresponds to version 42.1.1
  71
  72 =back
  73
  74 =back
  75
  76 If not set, this macro will default to
  77 C<{- join('', map { my @x = split /=/,$_; $x[1] }
  78               grep /^OPENSSL_CONFIGURED_API=/, @{$config{openssl_api_defines} // []})
  79      || '0x00000000L'
  80   -}>.
  81
  82 =item B<OPENSSL_NO_DEPRECATED>
  83
  84 If this macro is defined, all deprecated public symbols in all OpenSSL
  85 versions up to and including the version given by B<OPENSSL_API_COMPAT>
  86 will be hidden.
  87
  88 =back
  89
  90 =head1 COPYRIGHT
  91
  92 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
  93
  94 Licensed under the Apache License 2.0 (the "License").  You may not use
  95 this file except in compliance with the License.  You can obtain a copy
  96 in the file LICENSE in the source distribution or at
  97 L<https://www.openssl.org/source/license.html>.
  98
  99 =cut