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