[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Header files (again)

Hi guys,

The following feature test macros can be used to control the definitions 
included by the glibc headers.  This information is from the README if I 
remember correctly.  Of particular note is the _BSD_SOURCE and the BSD 
compatibility library.  It may be of use when porting source written for
BSD flavour unices.

Feature Test Macros

The exact set of features available when you compile a source file is 
controlled by which "feature test macros" defined.  When a program is 
compiled using `gcc -ansi', only the ISO C library features are enabled, 
unless additional features are explicitly requested by defining one or more 
of the feature macros.  These macros are enabled using `#define' preprocessor 
directives at the top of a source code files.  The directives must come before 
any `#include' of a system header file.  It is best to make them the very first 
thing in the file, preceded only by comments.  Alternatively the `-D' option 
to gcc can be used to define a feature test macro. 

When this macro is defined the functionality from the POSIX.1 standard 
(IEEE Standard 1003.1) is available, as well as all of the ISO C facilities. 

When this macro is defined with a value of  1, the functionality from the 
POSIX.1 standard (IEEE Standard 1003.1) is made available.  If this macro 
is defined with a value of 2, then the functionality from both the POSIX.1 
standard and the POSIX.2 standard (IEEE Standard 1003.2) is made available.  
This is in addition to the ISO C facilities. 

When this macro is defined the functionality derived from 4.3 BSD Unix is 
included as well as the ISO C, POSIX.1, and POSIX.2 material.  Some of the 
features derived from 4.3 BSD Unix conflict with the corresponding features 
specified by the POSIX.1 standard.  When macro is defined, the 4.3 BSD 
definitions take precedence over the POSIX definitions.  Due to the nature 
of some of the conflicts between 4.3 BSD and POSIX.1,  a special "BSD 
compatibility library" must be used when linking programs compiled for BSD 
compatibility.  This is because some functions must be defined in two 
different ways, one of them in the normal C library, and one of them in the 
compatibility library.  When defining _BSD_SOURCE, pass the option 
`-lbsd-compat' when linking.  Then the linker will find the functions in the
compatibility library before looking for them in the normal C library. 

When this macro is defined functionality derived from SVID is included as well 
as the ISO C, POSIX.1, POSIX.2, and X/Open material. 

When this macro is defined functionality described in the X/Open Portability 
Guide is included.  This is a superset of the POSIX.1 and POSIX.2 functionality.
In fact _POSIX_SOURCE and _POSIX_C_SOURCE are automatically defined with this 
macro.  Since this is the unification of all Unices, functionality available 
only in BSD and SVID is also included.  If the macro _XOPEN_SOURCE_EXTENDED is 
also defined, even more functionality is available.  All functions necessary 
for the X/Open Unix brand are made available.  If the macro _XOPEN_SOURCE is 
defined to have the value 500 then all the functionality described so far plus 
some new definitions from the Single Unix specification, version 2 are made 

When this macro is defined some extra functions are available which rectify 
a few shortcomings in all previous standards.  More concrete implementations 
of  the functions fseeko and ftello are available.  Without these functions 
the difference between the ISO C interface fseek, ftell and the low-level 
POSIX interface lseek would lead to problems.  This macro was introduced as 
part of the Large File Support extension (LFS). 

When this macro is defined an additional set of functions is made available 
which enables 32 bit systems to use files of sizes beyond the usual limit 
of 2GB.  This interface is not available if the system does not support files 
that large.  On systems where the natural file size limit is greater than 
2GB (i.e., on 64 bit systems) the new functions are identical to the replaced 
functions.  This new functionality is made available via a new set of types 
and functions which replace the existing ones. 

The names of these new objects contain `64' to indicate the intention.  For 
example: off_t vs. off64_t and fseeko vs. fseeko64.   This macro was 
introduced as part of the Large File Support extension (LFS).  This is a 
transition interface for the time when 64 bit files offsets are not generally 

Defining this macro allows the programmer to decide which file system interface 
shall be used.  This macro allows the programmer to specify which interface will
be available (ie: either 32 bit or 64 bit offsets), while _LARGEFILE64_SOURCE 
makes the 64 bit interface available as an additional interface.  
_FILE_OFFSET_BITS allows to use the 64 bit interface to replace the 32 bit 
interface completely. 

If _FILE_OFFSET_BITS is undefined or defined to the value 32 then nothing 
changes.  The 32 bit interface is used and types like off_t have a size of 
32 bits on 32 bit systems.  If the macro is defined to the value 64 the large 
file interface replaces the 32 bit interface, the functions are not made 
available under different names as they are when _LARGEFILE64_SOURCE is 
defined.  Instead the old function names now reference the new functions, a 
call to fseeko now calls fseeko64. 

This macro should only be selected if the system provides mechanisms for 
handling large files.  On 64 bit systems this macro has no effect since the 
`*64' functions are identical to the normal functions.  This macro was 
introduced as part of the Large File Support extension (LFS). 

When this macro is defined everything is included: ISO C, POSIX.1, POSIX.2, 
BSD, SVID, X/Open, LFS, and the GNU extensions.  In the cases where POSIX.1 
conflicts with BSD, the POSIX definitions take precedence.  If you want to 
get the full effect of _GNU_SOURCE but make the BSD definitions take precedence 
over the POSIX definitions, use the following sequence of definitions: 

          #define _GNU_SOURCE 
          #define _BSD_SOURCE 
          #define _SVID_SOURCE

When this is done a program must be linked with the BSD compatibility library 
by passing the `-lbsd-compat' option when linking. 

When one of these macros is defined reentrant versions of several functions 
get declared.  Some of the functions are specified in POSIX.1c but many others 
are only available on a few other systems or are unique to GNU libc.  The 
problem is that the standardization of the thread safe C library interface 
still is behind.  Unlike some other systems no special version of the C 
library must be used for linking.  There is only one version of libc, but 
this version must have been compiled as thread safe. 

These affect the header files in three ways: 

1) The include files define prototypes for the reentrant variants of some of 
the standard library functions, e.g. gethostbyname_r() as a reentrant 
equivalent to gethostbyname(). 

2) Some <stdio.h> functions are no longer defined as macros, e.g. getc() and 
putc(). In a multithreaded program, stdio functions require additional locking,
which the macros don't perform. 

3) Most importantly, <errno.h> redefines errno, so errno refers to the 
thread-specific errno location rather than the global errno variable. This is 
achieved by the following #define in <errno.h>: 

                 #define errno (*(__errno_location())) 

This causes each reference to errno to call the __errno_location() function 
to obtain the location where error codes should be stored. This returns the
location in  the thread descriptor reserved for holding the current value of
errno for the calling thread. Thus, each thread operates on a different errno 
location.  If all threads were to store error codes in the same, global errno 
variable, then the value of errno after a system call or library function 
returns would be unpredictable: between the time a system call stores its 
error code in the global errno and your code inspects errno to see which error 
occurred, another thread might have stored another error code in the same 
errno location. 

The glibc designers recommend _GNU_SOURCE be defined in new programs.  If the 
`-ansi' option to gcc is not specified and none of the feature test macros are
defined explicitly, the effect of defininge _GNU_SOURCE is equivalent to 
defining _POSIX_C_SOURCE equal to 2, and defining _POSIX_SOURCE,  _SVID_SOURCE,
and _BSD_SOURCE equal to 1. 

When a feature test macro is defined to request a larger class of features, 
it is harmless to define in addition a feature test macro for a subset of 
those features.  For example, if  _POSIX_C_SOURCE is defined, then defining 
_POSIX_SOURCE as well has no effect.  Likewise, if _GNU_SOURCE is defined, 
then defining either _POSIX_SOURCE or _POSIX_C_SOURCE or _SVID_SOURCE as 
well has no effect. 

Note, however, that the features of _BSD_SOURCE are not a subset of any of the 
other feature test macros supported.  This is because it defines BSD features 
that take precedence over the POSIX features that are requested by the other 
macros.  For this reason, defining _BSD_SOURCE in addition to any of the other 
feature test macros does have an effect: it causes the BSD features to take 
priority over any conflicting POSIX features. 

Jim Pick wrote:
> Turbo Fredriksson <turbo@tripnet.se> writes:
> > I can hardly build any package, without there being trouble with the header files.
> >
> > They seem to be in quite a mess... This time it's 'netbase'...
> I did netbase already for local use, you are right, it is a mess.
> I think the probably is that most of the source code came from *BSD,
> so it needs to be hacked in order to compile with glibc 2.1.
> You can see the hacks I did to it in the source packages I made:
> gandalf:/mnt/debs/dists/gandalf-local/main/source/net# ls
> netbase_3.11-1.1.arm.diff.gz  netstd_3.07-2.1.arm.diff.gz
> netbase_3.11-1.1.arm.dsc      netstd_3.07-2.1.arm.dsc
> netbase_3.11.orig.tar.gz      netstd_3.07.orig.tar.gz
> These need to be redone in a portable manner, of course.  It's a big
> job.  If you are going to do this, it's probably best to collaborate
> with the maintainer.
> Cheers,
>  - Jim
> --
> To UNSUBSCRIBE, email to debian-arm-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org


 Scott Bambrough, Software Engineer    
 Corel Computer Corporation         
 150 Isabella St, Suite 1000     scottb@corelcomputer.com
 Ottawa, ON       CANADA         +2 (613) 788-6008, x6116 [voice]
 K1S 1V7                         +2 (613) 230-4888        [fax]

Reply to: