Libc-1158.50.2.tar.gz

[apple/libc.git] / gen / compat.5

.Dd June 30, 2010
.Os Darwin
.Dt COMPAT 5
.Sh NAME
.Nm compat
.Nd manipulate compatibility settings
.Sh SYNOPSIS
.Ev COMMAND_MODE=legacy|unix2003
.Lp
.Fd #define _POSIX_C_SOURCE
.Fd #define _DARWIN_C_SOURCE
.Fd #define _NONSTD_SOURCE
.Fd defined(__LP64__)
.Lp
.In sys/cdefs.h
.Fd defined(_DARWIN_FEATURE_UNIX_CONFORMANCE)
.Sh DESCRIPTION
Setting the environment variable
.Ev COMMAND_MODE
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.
.Pp
Setting the environment variable
.Ev COMMAND_MODE 
to the value unix2003 causes utility programs to obey the
.St -susv3
standards even if doing so would alter the behavior of flags used in 10.3.
.Pp
The value of
.Ev COMMAND_MODE
is case insensitive and if it is unset or set to something other than legacy
or unix2003 it behaves as if it were set to unix2003.
.Sh COMPILATION
Defining
.Dv _NONSTD_SOURCE
for i386 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 are
documented in the LEGACY sections of the man pages for the individual function
calls.  Defining this macro when compiling for any other architecture will
result in a compilation error.
.Pp
Defining
.Dv _POSIX_C_SOURCE
or
.Dv _DARWIN_C_SOURCE
causes library and kernel calls to conform to the SUSv3
standards even if doing so would alter the behavior of functions used in 10.3.
Defining
.Dv _POSIX_C_SOURCE
also removes functions, types, and other interfaces that are not part of SUSv3
from the normal C namespace, unless
.Dv _DARWIN_C_SOURCE
is also defined (i.e.,
.Dv _DARWIN_C_SOURCE
is
.Dv _POSIX_C_SOURCE 
with non-POSIX extensions).
In any of these cases, the
.Dv _DARWIN_FEATURE_UNIX_CONFORMANCE
feature macro will be defined to the SUS conformance level (it is undefined
otherwise).
.Pp
Starting in Mac OS X 10.5, if none of the macros
.Dv _NONSTD_SOURCE ,
.Dv _POSIX_C_SOURCE
or
.Dv _DARWIN_C_SOURCE
are defined, and the environment variable
.Ev MACOSX_DEPLOYMENT_TARGET
is either undefined or set to 10.5 or greater (or equivalently, the
.Xr gcc 1
option
.Fl mmacosx-version-min
is either not specified or set to 10.5 or greater), then UNIX conformance will
be on by default, and non-POSIX extensions will also be available
(this is the equivalent of defining
.Dv _DARWIN_C_SOURCE ) .
For version values less that 10.5, UNIX conformance will be off when targeting
i386 (the equivalent of defining
.Dv _NONSTD_SOURCE ) .
.Pp
In order to provide both legacy and conformance versions of functions, two
versions of affected functions are provided.  Legacy variants have symbol names
with no suffix in order to maintain ABI compatibility.  Conformance versions
have a $UNIX2003 suffix appended to their symbol name.  These $UNIX2003
suffixes are automatically appended by the compiler tool-chain and should not
be used directly.
.Pp
Platforms that were released after these updates only have conformance variants
available and do not have a $UNIX2003 suffix.
.Pp
.TS
center;
c s s s s
c c | c c c
c c | c c c
l c | c c c
l c | c c c
l c | c c c
l c | c c c
l c | c c c
l c | c c c
l c | c c c.
T{
.Dv i386
T}
=
user defines	deployment	namespace	conformance	suffix
	target
_
T{
.Em (none)
T}	< 10.5	full	10.3 compatibility	(none)
T{
.Em (none)
T}	>= 10.5	full	SUSv3 conformance	$UNIX2003
T{
.Em _NONSTD_SOURCE
T}	(any)	full	10.3 compatibility	(none)
T{
.Em _DARWIN_C_SOURCE
T}	< 10.4	full	10.3 compatibility	(none)
T{
.Em _DARWIN_C_SOURCE
T}	>= 10.4	full	SUSv3 conformance	$UNIX2003
T{
.Em _POSIX_C_SOURCE
T}	< 10.4	strict	10.3 compatibility	(none)
T{
.Em _POSIX_C_SOURCE
T}	>= 10.4	strict	SUSv3 conformance	$UNIX2003
_
.T&
c s s s s
c c | c c c
c c | c c c
l c | c c c
l c | c s s
l c | c c c
l c | c c c.
T{
.Dv Newer Architectures
T}
=
user defines	deployment	namespace	conformance	suffix
	target
_
T{
.Em (none)
T}	(any)	full	SUSv3 conformance	(none)
T{
.Em _NONSTD_SOURCE
T}	(any)	(error)
T{
.Em _DARWIN_C_SOURCE
T}	(any)	full	SUSv3 conformance	(none)
T{
.Em _POSIX_C_SOURCE
T}	(any)	strict	SUSv3 conformance	(none)
_
.TE
.Sh STANDARDS
With COMMAND_MODE set to anything other than legacy, utility functions conform to 
.St -susv3 .
.Pp
With
.Dv _POSIX_C_SOURCE
or
.Dv _DARWIN_C_SOURCE
for i386, or when building for any other architecture,
system and library calls conform to
.St -susv3 .
.Sh BUGS
Different parts of a program can be compiled with different compatibility
settings.
The resultant program will normally work as expected, for example a regex
created by the SUSv3
.Fn regcomp 3
can be passed to the legacy
.Fn regfree 3
with no unexpected results.  Some cases are less clear cut, for example
what does the programmer intend when they use the SUSv3
.Fn regcomp 3
to compile a regex, but the legacy
.Fn regexec 3
to execute it?  Any interpretation will surprise someone.