gen/compat.5

   1 .Dd July 21, 2020
   2 .Os Darwin
   3 .Dt COMPAT 5
   4 .Sh NAME
   5 .Nm compat
   6 .Nd manipulate compatibility settings
   7 .Sh SYNOPSIS
   8 .Ev COMMAND_MODE=legacy|unix2003
   9 .br
  10 .Ev SYSTEM_VERSION_COMPAT=1
  11 .Lp
  12 .Fd #define _POSIX_C_SOURCE
  13 .Fd #define _DARWIN_C_SOURCE
  14 .Fd #define _NONSTD_SOURCE
  15 .Fd defined(__LP64__)
  16 .Lp
  17 .In sys/cdefs.h
  18 .Fd defined(_DARWIN_FEATURE_UNIX_CONFORMANCE)
  19 .Sh DESCRIPTION
  20 Setting the environment variable
  21 .Ev COMMAND_MODE
  22 to the value legacy causes utility programs to behave as closely to
  23 Mac OS X 10.3's utility programs as possible.  When in this mode all of 10.3's
  24 flags are accepted, and in some cases extra flags are accepted, but no flags
  25 that were used in 10.3 will have been removed or changed in meaning.  Any
  26 behavioral changes in this mode are documented in the LEGACY sections of the
  27 individual utilities.
  28 .Pp
  29 Setting the environment variable
  30 .Ev COMMAND_MODE
  31 to the value unix2003 causes utility programs to obey the
  32 .St -susv3
  33 standards even if doing so would alter the behavior of flags used in 10.3.
  34 .Pp
  35 The value of
  36 .Ev COMMAND_MODE
  37 is case insensitive and if it is unset or set to something other than legacy
  38 or unix2003 it behaves as if it were set to unix2003.
  39 .Pp
  40 Setting the environment variable
  41 .Ev SYSTEM_VERSION_COMPAT
  42 to 1 causes the system version to be reported as 10.16 when running on macOS 11 or later.
  43 .Sh COMPILATION
  44 Defining
  45 .Dv _NONSTD_SOURCE
  46 for i386 causes library and kernel calls to behave as closely to Mac
  47 OS X 10.3's library and kernel calls as possible.  Any behavioral changes are
  48 documented in the LEGACY sections of the man pages for the individual function
  49 calls.  Defining this macro when compiling for any other architecture will
  50 result in a compilation error.
  51 .Pp
  52 Defining
  53 .Dv _POSIX_C_SOURCE
  54 or
  55 .Dv _DARWIN_C_SOURCE
  56 causes library and kernel calls to conform to the SUSv3
  57 standards even if doing so would alter the behavior of functions used in 10.3.
  58 Defining
  59 .Dv _POSIX_C_SOURCE
  60 also removes functions, types, and other interfaces that are not part of SUSv3
  61 from the normal C namespace, unless
  62 .Dv _DARWIN_C_SOURCE
  63 is also defined (i.e.,
  64 .Dv _DARWIN_C_SOURCE
  65 is
  66 .Dv _POSIX_C_SOURCE
  67 with non-POSIX extensions).
  68 In any of these cases, the
  69 .Dv _DARWIN_FEATURE_UNIX_CONFORMANCE
  70 feature macro will be defined to the SUS conformance level (it is undefined
  71 otherwise).
  72 .Pp
  73 Starting in Mac OS X 10.5, if none of the macros
  74 .Dv _NONSTD_SOURCE ,
  75 .Dv _POSIX_C_SOURCE
  76 or
  77 .Dv _DARWIN_C_SOURCE
  78 are defined, and the environment variable
  79 .Ev MACOSX_DEPLOYMENT_TARGET
  80 is either undefined or set to 10.5 or greater (or equivalently, the
  81 .Xr gcc 1
  82 option
  83 .Fl mmacosx-version-min
  84 is either not specified or set to 10.5 or greater), then UNIX conformance will
  85 be on by default, and non-POSIX extensions will also be available
  86 (this is the equivalent of defining
  87 .Dv _DARWIN_C_SOURCE ) .
  88 For version values less that 10.5, UNIX conformance will be off when targeting
  89 i386 (the equivalent of defining
  90 .Dv _NONSTD_SOURCE ) .
  91 .Pp
  92 In order to provide both legacy and conformance versions of functions, two
  93 versions of affected functions are provided.  Legacy variants have symbol names
  94 with no suffix in order to maintain ABI compatibility.  Conformance versions
  95 have a $UNIX2003 suffix appended to their symbol name.  These $UNIX2003
  96 suffixes are automatically appended by the compiler tool-chain and should not
  97 be used directly.
  98 .Pp
  99 Platforms that were released after these updates only have conformance variants
 100 available and do not have a $UNIX2003 suffix.
 101 .Pp
 102 .TS
 103 center;
 104 c s s s s
 105 c c | c c c
 106 c c | c c c
 107 l c | c c c
 108 l c | c c c
 109 l c | c c c
 110 l c | c c c
 111 l c | c c c
 112 l c | c c c
 113 l c | c c c.
 114 T{
 115 .Dv i386
 116 T}
 117 =
 118 user defines    deployment      namespace       conformance     suffix
 119         target
 120 _
 121 T{
 122 .Em (none)
 123 T}      < 10.5  full    10.3 compatibility      (none)
 124 T{
 125 .Em (none)
 126 T}      >= 10.5 full    SUSv3 conformance       $UNIX2003
 127 T{
 128 .Em _NONSTD_SOURCE
 129 T}      (any)   full    10.3 compatibility      (none)
 130 T{
 131 .Em _DARWIN_C_SOURCE
 132 T}      < 10.4  full    10.3 compatibility      (none)
 133 T{
 134 .Em _DARWIN_C_SOURCE
 135 T}      >= 10.4 full    SUSv3 conformance       $UNIX2003
 136 T{
 137 .Em _POSIX_C_SOURCE
 138 T}      < 10.4  strict  10.3 compatibility      (none)
 139 T{
 140 .Em _POSIX_C_SOURCE
 141 T}      >= 10.4 strict  SUSv3 conformance       $UNIX2003
 142 _
 143 .T&
 144 c s s s s
 145 c c | c c c
 146 c c | c c c
 147 l c | c c c
 148 l c | c s s
 149 l c | c c c
 150 l c | c c c.
 151 T{
 152 .Dv Newer Architectures
 153 T}
 154 =
 155 user defines    deployment      namespace       conformance     suffix
 156         target
 157 _
 158 T{
 159 .Em (none)
 160 T}      (any)   full    SUSv3 conformance       (none)
 161 T{
 162 .Em _NONSTD_SOURCE
 163 T}      (any)   (error)
 164 T{
 165 .Em _DARWIN_C_SOURCE
 166 T}      (any)   full    SUSv3 conformance       (none)
 167 T{
 168 .Em _POSIX_C_SOURCE
 169 T}      (any)   strict  SUSv3 conformance       (none)
 170 _
 171 .TE
 172 .Sh STANDARDS
 173 With COMMAND_MODE set to anything other than legacy, utility functions conform to
 174 .St -susv3 .
 175 .Pp
 176 With
 177 .Dv _POSIX_C_SOURCE
 178 or
 179 .Dv _DARWIN_C_SOURCE
 180 for i386, or when building for any other architecture,
 181 system and library calls conform to
 182 .St -susv3 .
 183 .Sh BUGS
 184 Different parts of a program can be compiled with different compatibility
 185 settings.
 186 The resultant program will normally work as expected, for example a regex
 187 created by the SUSv3
 188 .Fn regcomp 3
 189 can be passed to the legacy
 190 .Fn regfree 3
 191 with no unexpected results.  Some cases are less clear cut, for example
 192 what does the programmer intend when they use the SUSv3
 193 .Fn regcomp 3
 194 to compile a regex, but the legacy
 195 .Fn regexec 3
 196 to execute it?  Any interpretation will surprise someone.