header files -- Overview

A header file is a file  of C code that contains definitions, declarations,
and structures commonly used in  a given situation.  By tradition, a header
file always  has the suffix  ``.h''.  Header files  are invoked within  a C
program by the command #include, which  is read by cpp, the C preprocessor;
for this reason, they are also called ``include files''.

Header files are one of the  most useful tools available to a C programmer.
They  allow you  to put  into  one place  all of  the information  that the
different modules  of your program share.  Proper use  of header files will
make your programs easier to maintain and to port to other environments.

COHERENT includes the following header files:

a.out.h........Include all COFF header files
acct.h.........Format for process-accounting file
ar.h...........Format for archive files
assert.h.......Define assert()
sys/buf.h......Buffer header
sys/cdrom.h....Definitions for CD-ROM drives
coff.h.........Format for COHERENT objects
sys/con.h......Configure device drivers
sys/core.h.....Declare structure of a core file
ctype.h........Header file for data tests
curses.h.......Declare/define curses routines
dbm.h..........Header file for DBM routines
sys/deftty.h...Default tty settings
dirent.h.......Define constant dirent
errno.h........Error numbers used by errno()
fcntl.h........Manifest constants for file-handling functions
sys/fd.h.......Declare file-descriptor structure
sys/fdioctl.h..Control floppy-disk I/O
sys/fdisk.h....Fixed-disk constants and structures
sys/filsys.h...Structures and constants for super block
float.h........Define constants for floating-point numbers
fnmatch.h......Constants used with function fnmatch()
fperr.h........Constants used with floating-point exception codes
gdbm.h.........Header file for GDBM routines
gdbmerrno.h....Define error messages used by GDBM routines
grp.h..........Declare group structure
sys/hdioctl.h..Control hard-disk I/O
sys/ino.h......Constants and structures for i-nodes
sys/inode.h....Constants and structures for memory-resident i-nodes
sys/io.h.......Constants and structures used by I/O
sys/ipc.h......Declarations for interprocess communication
sys/kb.h.......Define keys for loadable keyboard driver
l.out.h........Format for COHERENT-286 objects
limits.h.......Define numerical limits
sys/lpioctl.h..Definitions for line-printer I/O control
math.h.........Declare mathematics functions
mnttab.h.......Structure for mount table
mon.h..........Read profile output files
sys/mount.h....Define the mount table
mprec.h........Multiple-precision arithmetic
sys/msg.h......Definitions for message facility
mtab.h.........Currently mounted file systems
sys/mtioctl.h..Magnetic-tape I/O control
mtype.h........List processor code numbers
n.out.h........Define n.out file structure
ndbm.h.........Header file for NDBM routines
netdb.h........Define structures used to describe networks
path.h.........Define/declare constants and functions used with path
poll.h.........Define structures/constants used with polling devices
sys/proc.h.....Define structures/constants used with processes
sys/ptrace.h...Perform process tracing
pwd.h..........Define password structure
regexp.h.......Header file for regular-expression functions
sys/sched.h....Define constants used with scheduling
sys/seg.h......Definitions used with segmentation
sys/sem.h......Definitions used by semaphore facility
setjmp.h.......Define setjmp() and longjmp()
sgtty.h........Definitions used to control terminal I/O
shadow.h.......Definitions used with shadow passwords
sys/shm.h......Definitions used with shared memory
signal.h.......Define signals
socket.h.......Define constants and structures with sockets
sys/stat.h.....Definitions and declarations used to obtain file status
stdarg.h.......Declare/define routines for variable arguments
stddef.h.......Declare/define standard definitions
stdio.h........Declarations and definitions for I/O
stdlib.h.......Declare/define general functions
sys/stream.h...Definitions for message facility
string.h.......Declare string functions
stropts.h......User-level STREAMS routines
termio.h.......Definitions used with terminal input and output
termios.h......Definitions used with POSIX extended terminal interface
time.h.........Give time-description structure
sys/timeb.h....Define timeb structure
sys/times.h....Definitions used with times() system call
sys/tty.h......Define flags used with tty processing
sys/types.h....Define system-specific data types
ulimit.h.......Define manifest constants used by system call ulimit()
unctrl.h.......Define macro unctrl()
unistd.h.......Define constants for file-handling routines
sys/uproc.h....Definitions used with user processes
utime.h........Declare system call utime()
utmp.h.........Login accounting information
sys/utsname.h..Define utsname structure
varargs.h......Declare/define routines for variable arguments
sys/wait.h.....Define wait routines

Compilation Environments and Feature Tests

The COHERENT  header files are  designed to let  you invoke any  of several
``compilation environments''.  Each environment offers its own features; in
this way,  you can easily  import code that  conforms to the  POSIX or ANSI
standards, compile device drivers, or otherwise fine tune how your programs
are compiled.   To invoke a  given compilation environment, you  must set a
feature test.

As discussed  in the Lexicon article name space,  the ISO Standard reserves
for  the  implementation   every  identifier  that  begins  with  a  single
underscore followed  by an upper-case  letter.  The POSIX  Standards define
several  symbols in  this name  space  that the  implementation can  use as
``feature tests''  -- that is, as  symbols that you can  use in your source
code  to determine  the  presence or  absence  of a  particular feature  or
combination  of  features.   Note   that  a  feature  test  applies  to  an
implementation of  C, rather than  to an operating system.   A feature test
combines aspects of the host system and the language translator: some tests
apply to the operating system, some purely to the C translator.

The  operating  system's   header  files  can  define  them  (for  example,
_POSIX_SAVED_IDS)  to control  compilation  of user  code or  to deal  with
optional  features,  or  you can  define  them  (e.g., _POSIX_C_SOURCE)  to
control how  the system's header files declare  or define constants, types,
structures, and macros.

In general,  a feature  test must  either be undefined  or have  an integer
value.  It must not be defined  as having no expansion text, or expand into
a string.  For example,

    # CORRECT
    cc -D_POSIX_C_SOURCE=1 foo.c

is correct, as is:

    # CORRECT
    cc -U_POSIX_C_SOURCE foo.c

However,

    # WRONG
    cc -D_POSIX_C_SOURCE foo.c

is incorrect, as is:

    # WRONG
    cc -D_POSIX_C_SOURCE="yes" foo.c

This is to permit the constants to be tested with expressions like

    #if _POSIX_C_SOURCE > 1

where an integer  value is required.  (If the symbol  is used in a #if test
and is  undefined, cpp  replaces it  with zero, which  is still  an integer
value).  This  permits the  implementation to  use different values  of the
feature test  to invoke different  feature sets; and  it simplifies testing
for complex combinations of feature tests.

Although nearly  all feature tests behave  as shown above, there  are a few
exceptions, namely _POSIX_SOURCE and _KERNEL. These symbols are not defined
as having a  specific value, so many users do  not supply a value.  To deal
with this,  the COHERENT  header files  check whether these  constants have
expansion text.  If they do  not, the header files redefine these constants
with value  1, so that they  can be used like the  other feature tests that
the COHERENT header files define.

The  following describes  the  feature tests  used in  the COHERENT  header
files,  and briefly  describes  the compilation  environment each  invokes.
Because we are continually adding new  features to the kernel, this list is
not guaranteed to be complete.

_DDI_DKI
     Invoke the environment for compiling device drivers.  This environment
     makes visible  all DDI/DKI  function prototypes and  data definitions,
     and defines  all fundamental data types and  structures as mandated by
     UNIX System V, Release 4.

     Please note  that this feature  test is an COHERENT  extension, and is
     not portable to other operating systems.

_KERNEL
     Invoke the  environment for compiling  the kernel or  a device driver.
     This  environment gives  code full access  to system's  private header
     files.  Under COHERENT, this option is equivalent to defining _DDI_DKI
     to value  1, because COHERENT  only supports compiling  DDI/DKI driver
     source code from System V, Release 4.  This means that the definitions
     of many fundamental data types such as pid_t are changed to the System
     V,  Release  4  definitions  rather  than  the  System  V,  Release  3
     definitions used by user code.  (This is a System V convention.)

_POSIX_SOURCE
_POSIX_C_SOURCE
     Select  a  ``clean'' compilation  environment,  in  which the  headers
     defined in  the POSIX.1 or  POSIX.2 standards define  no symbols other
     than   the   ones   that   those   environments   require.    Defining
     _POSIX_C_SOURCE  with  value 1  selects  the  POSIX.1 environment,  as
     defined in the  POSIX.1 standard.  Defining _POSIX_C_SOURCE with value
     2 selects the POSIX.2 environment, as defined in the POSIX.2 standard.
     Defining _POSIX_SOURCE has the same effect as defining _POSIX_C_SOURCE
     with value 1.

_STDC_SOURCE
     Select a ``clean''  compilation environment.  In this environment, the
     headers that the ANSI C  standard defines define no symbols other than
     those that  the standard requires.   This feature test  is designed to
     let you compile  conforming Standard C programs that themselves define
     functions or macros that the COHERENT header files defined in addition
     to those described in the ANSI standard.

     Please note  that this feature  test is an COHERENT  extension, and is
     not portable to other operating systems.

_SUPPRESS_BSD_DEFINITIONS
     This feature test  invokes a compilation environment that excludes all
     definitions that  are included  for compatibility with  Berkeley UNIX.
     As of  this writing,  this feature test  affects only the  header file
     <string.h>, and  prevents it  from defining the  macros bcopy(),
     bzero(),  index(),  and  rindex().  Note  that  selecting a  POSIX  or
     Standard C environment also suppresses these definitions.

     Please note  that this feature  test is an COHERENT  extension, and is
     not portable to other operating systems.

_SYSV3
     This  feature test  invokes  a compilation  environment  in which  all
     fundamental types and data structures have the definitions mandated by
     UNIX System V, Release 3.

_SYSV4
     This  feature test  invokes  a compilation  environment  in which  all
     fundamental types and data structures have the definitions mandated by
     UNIX  System V,  Release  4.  As  of  this writing,  this facility  is
     incomplete and used mainly to develop device drivers and extensions to
     the kernel.

     Please note  that this feature  test is an COHERENT  extension, and is
     not portable to other operating systems.

See Also

#include,
C language,
cpp,
portability

© 2012 by Stephen A. Ness