.TH "header files"  "" "" Overview
.PC
.II "include file"
.PP
A
.I "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 \*(QL.h\*(QR.
Header files are invoked within a C program by the command \fB#include\fR,
which is read by
.BR cpp ,
the C preprocessor;
for this reason, they are also called \*(QLinclude files\*(QR.
.PP
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.
.PP
\*(PN includes the following header files:
.LB
\fBa.out.h\fR	Include all COFF header files
\fBacct.h\fR	Format for process-accounting file
\fBar.h\fR	Format for archive files
\fBassert.h\fR	Define \fBassert()\fR
\fBsys/buf.h\fR	Buffer header
\fBsys/cdrom.h\fR	Definitions for CD-ROM drives
\fBcoff.h\fR	Format for \*(CO objects
\fBsys/con.h\fR	Configure device drivers
\fBsys/core.h\fR	Declare structure of a \fBcore\fR file
\fBctype.h\fR	Header file for data tests
\fBcurses.h\fR	Declare/define \fBcurses\fR routines
\fBdbm.h\fR	Header file for DBM routines
\fBsys/deftty.h\fR	Default tty settings
\fBdirent.h\fR	Define constant \fBdirent\fR
\fBerrno.h\fR	Error numbers used by \fBerrno()\fR
\fBfcntl.h\fR	Manifest constants for file-handling functions
\fBsys/fd.h\fR	Declare file-descriptor structure
\fBsys/fdioctl.h\fR	Control floppy-disk I/O
\fBsys/fdisk.h\fR	Fixed-disk constants and structures
\fBsys/filsys.h\fR	Structures and constants for super block
\fBfloat.h\fR	Define constants for floating-point numbers
\fBfnmatch.h\fR	Constants used with function \fBfnmatch()\fR
\fBfperr.h\fR	Constants used with floating-point exception codes
\fBgdbm.h\fR	Header file for GDBM routines
\fBgdbmerrno.h\fR	Define error messages used by GDBM routines
\fBgrp.h\fR	Declare group structure
\fBsys/hdioctl.h\fR	Control hard-disk I/O
\fBsys/ino.h\fR	Constants and structures for i-nodes
\fBsys/inode.h\fR	Constants and structures for memory-resident i-nodes
\fBsys/io.h\fR	Constants and structures used by I/O
\fBsys/ipc.h\fR	Declarations for interprocess communication
\fBsys/kb.h\fR	Define keys for loadable keyboard driver
\fBl.out.h\fR	Format for \*(CO-286 objects
\fBlimits.h\fR	Define numerical limits
\fBsys/lpioctl.h\fR	Definitions for line-printer I/O control
\fBmath.h\fR	Declare mathematics functions
\fBmnttab.h\fR	Structure for mount table
\fBmon.h\fR	Read profile output files
\fBsys/mount.h\fR	Define the mount table
\fBmprec.h\fR	Multiple-precision arithmetic
\fBsys/msg.h\fR	Definitions for message facility
\fBmtab.h\fR	Currently mounted file systems
\fBsys/mtioctl.h\fR	Magnetic-tape I/O control
\fBmtype.h\fR	List processor code numbers
\fBn.out.h\fR	Define \fBn.out\fR file structure
\fBndbm.h\fR	Header file for NDBM routines
\fBnetdb.h\fR	Define structures used to describe networks
\fBpath.h\fR	Define/declare constants and functions used with \fBpath\fR
\fBpoll.h\fR	Define structures/constants used with polling devices
\fBsys/proc.h\fR	Define structures/constants used with processes
\fBsys/ptrace.h\fR	Perform process tracing
\fBpwd.h\fR	Define password structure
\fBregexp.h\fR	Header file for regular-expression functions
\fBsys/sched.h\fR	Define constants used with scheduling
\fBsys/seg.h\fR	Definitions used with segmentation
\fBsys/sem.h\fR	Definitions used by semaphore facility
\fBsetjmp.h\fR	Define \fBsetjmp()\fR and \fBlongjmp()\fR
\fBsgtty.h\fR	Definitions used to control terminal I/O
\fBshadow.h\fR	Definitions used with shadow passwords
\fBsys/shm.h\fR	Definitions used with shared memory
\fBsignal.h\fR	Define signals
\fBsocket.h\fR	Define constants and structures with \fBsockets\fR
\fBsys/stat.h\fR	Definitions and declarations used to obtain file status
\fBstdarg.h\fR	Declare/define routines for variable arguments
\fBstddef.h\fR	Declare/define standard definitions
\fBstdio.h\fR	Declarations and definitions for I/O
\fBstdlib.h\fR	Declare/define general functions
\fBsys/stream.h\fR	Definitions for message facility
\fBstring.h\fR	Declare string functions
\fBstropts.h\fR	User-level \*(ST routines
\fBtermio.h\fR	Definitions used with terminal input and output
\fBtermios.h\fR	Definitions used with POSIX extended terminal interface
\fBtime.h\fR	Give time-description structure
\fBsys/timeb.h\fR	Define \fBtimeb\fR structure
\fBsys/times.h\fR	Definitions used with \fBtimes()\fR system call
\fBsys/tty.h\fR	Define flags used with tty processing
\fBsys/types.h\fR	Define system-specific data types
\fBulimit.h\fR	Define manifest constants used by system call \fBulimit()\fR
\fBunctrl.h\fR	Define macro \fBunctrl()\fR
\fBunistd.h\fR	Define constants for file-handling routines
\fBsys/uproc.h\fR	Definitions used with user processes
\fButime.h\fR	Declare system call \fButime()\fR
\fButmp.h\fR	Login accounting information
\fBsys/utsname.h\fR	Define \fButsname\fR structure
\fBvarargs.h\fR	Declare/define routines for variable arguments
\fBsys/wait.h\fR	Define wait routines
.SH "Compilation Environments and Feature Tests"
.II "header files^feature tests"
.II "feature tests"
The \*(CO 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
.IR "feature test" .
.PP
As discussed in the Lexicon article
.BR "name space" ,
the \*(IO reserves for the implementation every identifier
that begins with a single underscore followed by an upper-case letter.
The \*(PXs define several symbols in this name space
that the implementation can use as ``feature tests'' \(em 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
.I 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.
.PP
The operating system's header files can define them (for example,
.BR _POSIX_SAVED_IDS )
to control compilation of user code or to deal with optional features,
or you can define them (e.g.,
.BR _POSIX_C_SOURCE )
to control how the system's header files declare or define
constants, types, structures, and macros.
.PP
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,
.DM
	# CORRECT
	cc -D_POSIX_C_SOURCE=1 foo.c
.DE
.PP
is correct, as is:
.DM
	# CORRECT
	cc -U_POSIX_C_SOURCE foo.c
.DE
.PP
However,
.DM
	# WRONG
	cc -D_POSIX_C_SOURCE foo.c
.DE
.PP
is incorrect, as is:
.DM
	# WRONG
	cc -D_POSIX_C_SOURCE="yes" foo.c
.DE
.PP
This is to permit the constants
to be tested with expressions like
.DM
	#if _POSIX_C_SOURCE > 1
.DE
.PP
where an integer value is required.
(If the symbol is used in a
.B #if
test and is undefined,
.B 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.
.PP
Although nearly all feature tests behave as shown above,
there are a few exceptions, namely
.B _POSIX_SOURCE
and
.BR _KERNEL .
These symbols are not defined as having a specific value,
so many users do not supply a value.
To deal with this, the \*(CO 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 \*(CO header files define.
.PP
The following describes the feature tests used in the \*(CO 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.
.II _DDI_DKI
.II DDI/DKI
.IP \fB_DDI_DKI\fR
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 \*(UN System V, Release 4.
.IP
Please note that this feature test is an \*(CO extension,
and is not portable to other operating systems.
.II _KERNEL
.IP \fB_KERNEL\fR
Invoke the environment for compiling the kernel or a device driver.
This environment gives code full access to system's private header files.
Under \*(CO, this option is equivalent to defining
.B _DDI_DKI
to value 1, because \*(CO 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
.B 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.)
.II _POSIX_SOURCE
.II _POSIX_C_SOURCE
.IP \fB_POSIX_SOURCE\fR
.IS \fB_POSIX_C_SOURCE\fR
Select a ``clean'' compilation environment, in which the headers defined in the
.B POSIX.1
or
.B POSIX.2
standards define no symbols other than the ones that those environments require.
Defining
.B _POSIX_C_SOURCE
with value 1 selects the
.B POSIX.1
environment, as defined in the POSIX.1 standard.
Defining
.B _POSIX_C_SOURCE
with value 2 selects the
.B POSIX.2
environment, as defined in the POSIX.2 standard.
Defining
.B _POSIX_SOURCE
has the same effect as defining
.B _POSIX_C_SOURCE
with value 1.
.II _STDC_SOURCE
.IP \fB_STDC_SOURCE\fR
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 \*(CO header files defined in addition to those described in
the ANSI standard.
.IP
Please note that this feature test is an \*(CO extension,
and is not portable to other operating systems.
.II _SUPPRESS_BSD_DEFINITIONS
.IP \fB_SUPPRESS_BSD_DEFINITIONS\fR
This feature test invokes a compilation environment that
excludes all definitions that are included
for compatibility with Berkeley \*(UN.
As of this writing, this feature test affects only the header file
.BR <string.h> ,
and prevents it from defining the macros
.BR bcopy() ,
.BR bzero() ,
.BR index() ,
and
.BR rindex() .
Note that selecting a POSIX or Standard C environment also
suppresses these definitions.
.IP
Please note that this feature test is an \*(CO extension,
and is not portable to other operating systems.
.II _SYS3
.IP \fB_SYSV3\fR
This feature test invokes a compilation environment
in which all fundamental types and data structures
have the definitions mandated by \*(UN System V, Release 3.
.II _SYSV4
.IP \fB_SYSV4\fR
This feature test invokes a compilation environment
in which all fundamental types and data structures
have the definitions mandated by \*(UN System V, Release 4.
As of this writing, this facility is incomplete and used mainly to
develop device drivers and extensions to the kernel.
.IP
Please note that this feature test is an \*(CO extension,
and is not portable to other operating systems.
.\".SH "Changes from Release 4.0"
.\"Note that the design of \*(CO's suite of header files has changed radically
.\"between releases 4.0 and 4.2.
.\"These changes are intended to bring \*(CO closer to the \*(PX,
.\"and to improve the implementation of many structures and macros used by
.\"\*(CO.
.\"Header files now also include prototypes for all functions and system calls,
.\"as required by the \*(PX.
.\"For details on how a header file has changed from its previous form under
.\"\*(CO 4.0, see the comments in the header file itself.
.\".PP
.\"The following header files are included with \*(CO 4.2.
.\"They are obsolete, however, and their use is deprecated.
.\"They will be dropped from future releases of \*(CO:
.\".IP \fB<sys/alloc.h>\fR
.\".II alloc.h
.\"This header file defined structures for accessing a kernel-memory allocator
.\"used by some device drivers.
.\"This facility is now obsolete and should not be used.
.\"New drivers should use the DDI/DKI-compliant facility defined in
.\".BR <sys/kmem.h> .
.\".IP \fB<canon.h>\fR
.\".II canon.h
.\"The facilities for data-format conversion defined in this
.\"header are deprecated, because they are non-portable and poorly organized.
.\"Applications that use this header will not compile on future releases of \*(CO.
.\".IP \fB<sys/clist.h>\fR
.\".II clist.h
.\"This header file defines character-list structures used in device drivers
.\"prior to release 4.2 of \*(CO.
.\"These structures are still used in drivers, but are obsolete, and should
.\"not be used in new code.
.\".IP \fB<sys/coherent.h>\fR
.\".II coherent.h
.\"This header file defines miscellaneous things used by the obsolete \*(CO
.\"device-driver interface.
.\"They are obsolete, and should not be used in new code.
.\".IP \fB<sys/const.h>\fR
.\".II const.h
.\"This header defined some constants used in the kernel in
.\"versions of \*(CO prior to version 4.0.
.\"Programs that use this header should be changed to use the modern portable
.\"equivalents to the definitions that were in this header.
.\"In particular, references to the constant
.\".B HZ
.\"should be replaced with references to
.\".B CLOCKS_PER_SEC
.\"or
.\".BR CLK_TCK ,
.\"as appropriate.
.\".IP \fB<dumptape.h>\fR
.\".II dumptape.h
.\"The facility defined by this header and the command
.\".B dump
.\"is obsolete.
.\"You are referred to the commands
.\".B gtar
.\"or
.\".B gnucpio
.\"instead.
.\".IP \fB<sys/ktty.h>\fR
.\"This header file defines the kernel portion of the
.\".B tty
.\"structure.
.\"It is used in some drivers used by device drivers written to the obsolete
.\"\*(CO device-driver interface, but should not be used in new code.
.\".IP \fB<sys/machine.h>\fR
.\".II machine.h
.\"This header file contained kernel internal definitions for
.\"releases of \*(CO prior to 4.0.
.\".IP \fB<sys/malloc.h>\fR
.\".II malloc.h
.\"This header contained internal definitions for the user-level
.\".B malloc()
.\"library call.
.\"Applications can no longer depend on the algorithm used by
.\".BR malloc() ,
.\"so that we have the freedom to substitute an improved algorithm.
.\".IP \fB<sys/msig.h>\fR
.\".II msig.h
.\"This header defined a set of signals that were
.\"``machine dependent'' in releases of \*(CO prior to 4.0.
.\"This distinction did not prove useful.
.\".\"(and was completely wrong in many places).
.\"All signals are defined in
.\".BR <signal.h> .
.\".IP \fB<sys/param.h>\fR
.\".II param.h
.\"In \*(CO 4.0, the definitions in this header were used in
.\"place of those in
.\".BR <sys/const.h> .
.\"Because there are no
.\"definitions in either header of interest to user programs,
.\"both are scheduled to be removed.
.\".IP \fB<sys/timeout.h>\fR
.\".II timeout.h
.\"The timeout facility defined in this header for device-driver
.\"use is deprecated in favor of the DDI/DKI facility.
.\".SH "Deleted Header Files"
.\"The following describes header files that have been dropped
.\"from \*(CO release 4.2:
.\".IP \fB<access.h>\fR
.\".II access.h
.\"The function
.\".B access()
.\"and related constants are now defined in the header file
.\".BR <unistd.h> ,
.\"as specified in POSIX.
.\".IP \fB<action.h>\fR
.\".II action.h
.\"This header file was used by the files generated by old versions of
.\".BR yacc .
.\"Beginning with \*(CO release 4.2,
.\".B yacc
.\"has built this file's data into the parser skeleton in
.\".BR /lib/yyparse ;
.\"therefore, this header is obsolete and has been removed.
.\"You should re-run
.\".B yacc
.\"to update the source files generated by previous versions of
.\".BR yacc .
.\".IP \fB<sys/ascii.h>\fR
.\".II ascii.h
.\"This header originally defined constants for members of the ASCII code set.
.\"This did nothing to increase the portability
.\"of application programs, and has been removed.
.\"Code-set dependencies in application programs should be avoided at all costs.
.\".IP \fB<sys/chars.h>\fR
.\".II chars.h
.\"This header has been removed.
.\"The definitions it supplied were not portable,
.\"and did nothing to enhance the portability of application code.
.\".IP \fB<sys/dir.h>\fR
.\".II dir.h
.\"This \*(CO-286 file has been removed, because its definitions
.\"did not apply at all to \*(CO-386 (that is, \*(CO release 4.0 and up).
.\"Code which uses
.\".B "struct direct"
.\"must be changed to use the portable
.\"\fBopendir()\fR/\fBreaddir()\fR/\fBclosedir()\fR
.\"interface instead.
.\".IP \fB<ebcdic.h>\fR
.\".II ebcdic.h
.\"This header has been removed.
.\"The definitions it contained did nothing to enhance application portability.
.\".IP \fB<sys/fblk.h>\fR
.\"This header file defined the disk-free block.
.\"It has been merged into
.\".BR <sys/filsys.h> ,
.\"as these header files were not truly independent.
.\"You should include
.\".B <sys/filsys.h>
.\"in place of this file.
.\".IP \fB<sys/fun.h>\fR
.\".II fun.h
.\"This header file held miscellaneous definitions used by the obsolete \*(CO
.\"device-driver interface.
.\"It holds nothing of interest, and so has been deleted.
.\".IP \fB<sys/mdata.h>\fR
.\".II mdata.h
.\"This header originally defined non-portable substitutes for
.\"the portable definitions in
.\".BR <limits.h> .
.\"Use
.\".B <limits.h>
.\"instead.
.\".IP \fB<sys/mmu.h>\fR
.\".II /usr/include/kernel
.\".II mmu.h
.\"This header file definitions for memory-management unit.
.\"It has been moved to
.\".BR /usr/include/kernel .
.\"The contents of this directory are in flux and therefore must
.\".I never
.\"be used in drivers or user-level applications.
.\".IP \fB<sys/systab.h>\fR
.\"This header held definitions for the system-call table.
.\"It has been deleted.
.\".IP \fB<timef.h>\fR
.\".II timef.h
.\"The facility that was defined in this header is not supported
.\"in \*(CO releases 4.0 and above, so this header has been removed.
.SH "See Also"
.Xr "#include," _23include
.Xr "C language," c_languag
.Xr "cpp," cpp
.Xr "portability" portabili
