gen/compat.5

   1 .Dd October 23, 2005
   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 Mac OS X 10.3's utility programs as possible.  When in this mode all of 10.3's flags are accepted, and in some cases extra flags are accepted, but no flags that were used in 10.3 will have been removed or changed in meaning.  Any behavioral changes in this mode are documented in the LEGACY sections of the individual utilities.
  21 .Pp
  22 Setting the environment variable
  23 .Ev COMMAND_MODE
  24 to the value unix03 causes utility programs to obey the
  25 .St -susv3
  26 standards even if doing so would alter the behavior of flags used in 10.3.
  27 .Pp
  28 The value of
  29 .Ev COMMAND_MODE
  30 is case insensitive and if it is unset or set to something other than legacy or unix03 it behaves as if it were set to unix03.
  31 .Sh 32-BIT COMPILATION
  32 Defining
  33 .Dv _NONSTD_SOURCE
  34 causes library and kernel calls to behave as closely to Mac OS X 10.3's library and kernel calls as possible.  Any behavioral changes in this mode are documented in the LEGACY sections of the individual function calls.
  35 .Pp
  36 Defining
  37 .Dv _POSIX_C_SOURCE
  38 or
  39 .Dv _DARWIN_C_SOURCE
  40 causes library and kernel calls to conform to the SUSv3
  41 standards even if doing so would alter the behavior of functions used in 10.3.
  42 Defining
  43 .Dv _POSIX_C_SOURCE
  44 also removes functions, types, and other interfaces that are not part of SUSv3
  45 from the normal C namespace, unless
  46 .Dv _DARWIN_C_SOURCE
  47 is also defined (i.e.,
  48 .Dv _DARWIN_C_SOURCE
  49 is
  50 .Dv _POSIX_C_SOURCE
  51 with non-POSIX extensions).
  52 In any of these cases, the
  53 .Dv _DARWIN_FEATURE_UNIX_CONFORMANCE
  54 feature macro will be defined to the SUS conformance level (it is undefined
  55 otherwise).
  56 .Pp
  57 Starting in Mac OS X 10.5, if none of the macros
  58 .Dv _NONSTD_SOURCE ,
  59 .Dv _POSIX_C_SOURCE
  60 or
  61 .Dv _DARWIN_C_SOURCE
  62 are defined, and the environment variable
  63 .Ev MACOSX_DEPLOYMENT_TARGET
  64 is either undefined or set to 10.5 or greater (or equivalently, the
  65 .Xr gcc 1
  66 option
  67 .Fl mmacosx-version-min
  68 is either not specified or set to 10.5 or greater), then UNIX conformance will
  69 be on by default, and non-POSIX extensions will also be available
  70 (this is the equivalent of defining
  71 .Dv _DARWIN_C_SOURCE ) .
  72 For version values less that 10.5, UNIX conformance will be off (the
  73 equivalent of defining
  74 .Dv _NONSTD_SOURCE ) .
  75 .Sh 64-BIT COMPILATION
  76 When compiling for 64-bit architectures, the
  77 .Dv __LP64__
  78 macro will be defined to 1, and UNIX conformance is always on (the
  79 .Dv _DARWIN_FEATURE_UNIX_CONFORMANCE
  80 macro will also be defined to the SUS conformance level).
  81 Defining
  82 .Dv _NONSTD_SOURCE
  83 will cause a compilation error.
  84 .Sh STANDARDS
  85 With COMMAND_MODE set to unix2003 utility functions conform to
  86 .St -susv3 .
  87 .Pp
  88 With
  89 .Dv _POSIX_C_SOURCE ,
  90 .Dv _DARWIN_C_SOURCE ,
  91 or
  92 .Dv __LP64__ ,
  93 system and library calls conform to
  94 .St -susv3 .
  95 .Sh BUGS
  96 Different parts of a program can be compiled with different compatibility
  97 settings.
  98 The resultant program will normally work as expected, for example a regex
  99 created by the SUSv3
 100 .Fn regcomp 3
 101 can be passed to the legacy
 102 .Fn regfree 3
 103 with no unexpected results.  Some cases are less clear cut, for example
 104 what does the programmer intend when they use the SUSv3
 105 .Fn regcomp 3
 106 to compile a regex, but the legacy
 107 .Fn regexec 3
 108 to execute it?  Any interpretation will surprise someone.