gen/compat.5

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