Header Files

When a library function is referenced in a source file, the related header files (shown in the synopsis for that function) should be included in that source file. The header files provide the proper declarations for the functions and for the number and types of arguments used with them. Constant values used in conjunction with the functions are also declared. The files can be included in any order.

This chapter describes the header files supplied with the C library:

• Conforming to standards
• Header files in /usr/include
• Header files in /usr/include/sys
• Header files provided for compatibility

Conforming to standards

When the Watcom C compiler option za is used ("ANSI conformance"), the macro NO_EXT_KEYS is predefined. Use the za option when you're creating an application that must conform to a certain standard, whether it be ANSI or POSIX. The effect on the inclusion of ANSI- and POSIX-defined header files is that certain portions of the header files are omitted:

• for ANSI header files, these are the portions that go beyond the ANSI standard
• for POSIX header files, these are the portions that go beyond the POSIX standard

Feature test macros may then be defined to select those portions that are omitted. Two feature test macros may be defined:

_POSIX_SOURCE

Include those portions of the ANSI header files that relate to the POSIX standard (IEEE Standard Portable Operating System Interface for Computer Environments - POSIX 1003.1)

_QNX_SOURCE

Include those portions of the ANSI and POSIX header files that relate to the POSIX standard and all extensions provided by the QNX system. In essence, the definition of _QNX_SOURCE before any header files are included is equivalent to omitting the specification of the za compiler option.

---

When _QNX_SOURCE is defined, it encompasses _POSIX_SOURCE, so it isn't necessary to define _POSIX_SOURCE as well.

---

Feature test macros may be defined on the command line, or in the source file before any header files are included. The latter is illustrated in the following example, in which an ANSI- and POSIX-conforming application is being developed.

    #define _POSIX_SOURCE
    #include <limits.h>
    #include <stdio.h>
      .
      .
      .
    #if defined(_QNX_SOURCE)
      #include "non_POSIX_header1.h"
      #include "non_POSIX_header2.h"
      #include "non_POSIX_header3.h"
    #endif

The source code is then compiled using the za option.

The following ANSI header files are affected by the _POSIX_SOURCE feature test macro:

• <limits.h>
• <setjmp.h>
• <signal.h>
• <stdio.h>
• <stdlib.h>
• <time.h>

The following ANSI and POSIX header files are affected by the _QNX_SOURCE feature test macro:

/usr/include

The following header files are provided with the software. The header files that are located in the /usr/include directory are described first.

<assert.h>

This ANSI header file is required when an assert() macro is used. These assertions are ignored when the identifier NDEBUG is defined.

<_comdef.h>

This header file contains common macro definitions used in other header files.

<conio.h>

This header file provides the declarations for console and Intel 80x86 port input/output functions.

<crtdbg.h>

This header file provides runtime debugging support.

<ctype.h>

This ANSI header file provides the declarations for functions that manipulate characters.

<curses.h>

This header file contains definitions for the ncurses package.

The QNX proprietary term_* functions have been deprecated in favor of ncurses. ncurses is a set of terminal-independent routines for painting screens and handling input events. It's a freeware implementation that's based on the System V and X/Open curses API. For more information, see the Miscellaneous Utilities bookset in the online documentation.

<dirent.h>

This POSIX header file provides the declarations for functions related to directories, and for the type DIR, which describes an entry in a directory.

<env.h>

This POSIX header file contains prototypes for environment string functions.

<errno.h>

This ANSI header file provides the extern declaration for error variable errno, and provides the symbolic names for error codes that can be placed in the error variable.

<eti.h>

This header file contains definitions of error codes for the ncurses package.

<fcntl.h>

This POSIX header file provides the flags used by the creat(), fcntl(), open() and sopen() functions.

<float.h>

This ANSI header file contains declarations for constants related to floating-point numbers, declarations for low-level floating-point functions, and the declaration of the floating-point exception codes.

<fnmatch.h>

This header file provides the declaration for the fnmatch() pattern-matching function.

<form.h>

This header file contains definitions of forms for the ncurses package.

<graph.h>

This header file contains structure definitions and function prototypes for the Watcom C Graphics library functions.

These functions aren't documented; use Photon instead.

<grp.h>

This POSIX header file contains structures and prototypes for group operations.

<i86.h>

This header file is used with functions that interact with the Intel architecture. It defines the structs and unions used to handle the input and output registers for the Intel 80x86 and 80386/80486 interrupt interface routines. It includes prototypes for the interrupt functions, definitions for the FP_OFF(), FP_SEG() and MK_FP() macros, and definitions for the following structures and unions:

REGS

describes the CPU registers for Intel 8086 family.

SREGS

describes the segment registers for the Intel 8086 family.

REGPACK

describes the CPU registers and segment registers for Intel 8086 family.

INTPACK

describes the input parameter to an "interrupt" function.

<limits.h>

This ANSI header file contains constant declarations for limits or boundary values for ranges of integers and characters.

<locale.h>

This ANSI header file contains declarations for the categories (LC...) of locales that can be selected using the setlocale() function, which is also declared.

<malloc.h>

This header file provides declarations for the memory allocation and deallocation functions.

<math.h>

This ANSI header file contains declarations for the mathematical functions (which operate with floating-point numbers) and for the structures:

exception

describes the exception structure passed to the matherr() function; symbolic constants for the types of exceptions are included

complex

declares a complex number. See cabs() for more information.

<mbctype.h>

The header file contains definitions and functions for multibyte characters.

<mbstring.h>

The header file defines Multibyte-Character-Set (MBCS) functions.

<mem.h>

This header file defines memory-manipulation functions.

<mig.h>

This header file defines functions and macros for migrating to QNX.

<menu.h>

This header file contains definitions of menus for the ncurses package.

<mqueue.h>

This header file contains declarations that are used by the functions that deal with message queues. For more information, see "Message-queue structures" in the chapter on POSIX.4 message queues.

<panel.h>

This header file contains definitions of panels for the ncurses package.

<pgchart.h>

This header file defines Presentation Graphics functions.

These functions aren't documented; use Photon instead.

<process.h>

This header file contains function declarations for the spawn... functions, the exec... functions, and the system() function. The file also contains declarations for the constants P_WAIT, P_NOWAIT, P_NOWAITO and P_OVERLAY. These constants are discussed in the section on the spawn... functions.

<pwd.h>

This POSIX header file contains structure definitions and prototypes for password operations.

<queue.h>

This header file defines queueing functions.

<regex.h>

This header file contains structure definitions and prototypes for regular expression handling.

<search.h>

This header file contains function prototypes for the lfind() and lsearch() functions.

<semaphore.h>

This header file contains declarations used by the semaphore functions.

<setjmp.h>

This ANSI header file provides declarations to be used with the setjmp() and longjmp() functions.

<share.h>

This header file defines constants for shared access to files using the sopen() function.

<signal.h>

This ANSI header file contains the declarations related to the signal() and raise() functions.

<stdarg.h>

This ANSI header file contains the declarations for the macros that handle variable argument lists.

<stddef.h>

This ANSI header file contains declarations for a few popular constants, including NULL (null pointer), size_t (unsigned size of an object), and ptrdiff_t (difference between two pointers). It also contains a declaration for the offsetof() macro.

<stdio.h>

This ANSI header file relates to "standard" input/output functions. Files, devices and directories are referenced using pointers to objects of the type FILE. The header file contains declarations for these functions and macros, defines the FILE type, and contains various constants related to files.

<stdlib.h>

This ANSI header file contains declarations for many standard functions, excluding those declared in other header files discussed in this section.

<string.h>

This ANSI header file contains declarations for functions that manipulate strings or blocks of memory.

<syslog.h>

This header file contains definitions for the system message log.

<tar.h>

This POSIX header file contains header block information for the tar format.

<tchar.h>

This header file defines generic international text function macros.

<term.h>

This header file contains terminal information definitions for use with ncurses.

The QNX proprietary term_* functions have been deprecated in favor of ncurses. ncurses is a set of terminal-independent routines for painting screens and handling input events. It's a freeware implementation that's based on the System V and X/Open curses API. For more information, see the Miscellaneous Utilities bookset in the online documentation. If you want to continue to use termlib, you'll have to link it into your program explicitly with the option -ltermlib. The file /usr/include/term.h is now an ncurses header file; you'll find the old <term.h> in /usr/include/sys/term.h. An error message is displayed if you combine the old term_* and ncurses header files.

<termios.h>

This POSIX header file contains terminal I/O system types.

<time.h>

This ANSI header file declares the functions related to times and dates, and defines the structured type struct tm, which contains the following fields:

int tm_sec

seconds after the minute, in the range [0,61], allowing for leap seconds

int tm_min

minutes after the hour, in the range [0,59]

int tm_hour

hours after midnight, in the range [0,23]

int tm_mday

day of the month, in the range [1,31]

int tm_mon

months since January, in the range [0,11]

int tm_year

years since 1900

int tm_wday

days since Sunday, in the range [0,6]

int tm_yday

days since January 1, in the range [0,365], allowing for leap years

int tm_isdst

Daylight Savings Time flag

<unctrl.h>

This header file contains definitions for displaying printable versions of control characters in the ncurses package.

<unicode.h>

This header file defines the Unicode character set.

<unistd.h>

This POSIX header file contains the declarations for functions that perform input/output operations at the operating system level. These functions use file descriptors to reference files or devices. The function fstat() is declared in the <sys/stat.h> header file.

<unix.h>

This header file contains definitions that aid in porting traditional UNIX code.

<utime.h>

This POSIX header file contains a declaration for the utime() function, and for the structured type utimbuf used by it. See the utime() function for a description of the utimbuf structure.

<varargs.h>

This UNIX System V header file provides an alternate way of handling variable argument lists. The equivalent ANSI header file is <stdarg.h>.

/usr/include/sys

The following header files are present in the sys subdirectory. Their presence in this directory indicates that they are system-dependent header files.

<sys/audio.h>

This header file defines macros and types for use with audio.

<sys/cdrom.h>

This header file contains definitions for use with CD ROMs.

<sys/con_msg.h>

This header file contains definitions for the console driver.

<sys/console.h>

This header file contains "public" definitions for the console driver.

<sys/debug.h>

This header file contains debugger data structures.

<sys/dev.h>

This header file contains "public" device administrator definitions.

<sys/dev_msg.h>

This header file contains "public" device driver messages.

<sys/disk.h>

This header file contains nonportable file system definitions.

<sys/dumper.h>

This header file contains the dumper file structure.

<sys/fd.h>

This header file contains file descriptor data structures.

<sys/fsys.h>

This header file contains nonportable file system definitions.

<sys/fsysinfo.h>

This header file contains declarations related to the fsysinfo() function.

<sys/fsys_msg.h>

This header file contains nonportable file system message definitions.

<sys/inline.h>

This header file contains handy pragmas that are often used when doing low-level programming.

<sys/io_msg.h>

This header file contains nonportable low-level I/O definitions.

<sys/irqinfo.h>

This header file contains structure definitions and prototypes for interrupt request functions.

<sys/kernel.h>

This header file contains prototypes and pragmas for kernel function calls.

<sys/lmf.h>

This header file contains structure definitions for load module format.

<sys/locking.h>

This header file contains the manifest constants used by the locking() function.

<sys/magic.h>

This header file contains a definition for the _magic structure.

<sys/mman.h>

This header file contains declarations related to the memory mapping functions.

At least the following protection bits are defined in <sys/mman.h>:

PROT_EXEC

The region can be executed.

PROT_NOCACHE

Disable caching of the region (for example, can be used to access dual ported memory).

PROT_NONE

The region cannot be accessed.

PROT_READ

The region can be read.

PROT_WRITE

The region can be written.

<sys/mouse.h>

This header file contains structure definitions and prototypes for mouse operations.

<sys/mous_msg.h>

This header file contains "private" definitions for the mouse driver.

<sys/name.h>

This header file contains structure definitions and prototypes for QNX qnx_name... functions.

<sys/osinfo.h>

This header file contains manifests, structure definitions and prototypes for operating system information.

<sys/osstat.h>

This header file contains manifests, structure definitions and prototypes for operating system status information.

<sys/pci.h>

This header file contains declarations for PCI functions.

<sys/prfx.h>

This header file contains file prefix prototypes.

<sys/proc_msg.h>

This header file contains process data structures and definitions.

<sys/proxy.h>

This header file contains proxy process prototypes.

<sys/psinfo.h>

This header file contains manifests and structure definitions for process information.

<sys/qioctl.h>

This header files contains manifests and structures for common qnx_ioctl() messages.

<sys/qnx_glob.h>

This header file contains a structure definition for the QNX process-spawning global data area, qnx_spawn_options.

<sys/qnxterm.h>

This header file contains terminal capability definitions.

<sys/sched.h>

This header file contains manifests and prototypes for process scheduling.

<sys/seginfo.h>

This header file contains segment information data structures.

<sys/select.h>

This header file contains the prototype for the select() function.

<sys/sendmx.h>

This header file contains a definition for _setmx(), and a definition of the _mxfer_entry structure. See _setmx() for a description of the _mxfer_entry structure.

<sys/ser_msg.h>

This header file contains "public" serial driver messages.

<sys/sidinfo.h>

This header file contains session information data structures.

<sys/stat.h>

This POSIX header file contains the declarations pertaining to file status, including definitions for the fstat() and stat() functions and for the structure:

stat

describes the information obtained for a directory, file or device

This header file also defines access permission bits for the owner of a file, the owner's group, and other users.

The following bits define permissions for the owner:

S_IRWXU is the bitwise inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.

The following bits define permissions for the group:

S_IRWXG is the bitwise inclusive OR of S_IRGRP, S_IWGRP and S_IXGRP.

The following bits define permissions for others:

S_IRWXO is the bitwise inclusive OR of S_IROTH, S_IWOTH and S_IXOTH.

The following bits define miscellaneous permissions used by other implementations:

<sys/sys_msg.h>

This header file contains standard system message definitions.

<sys/term.h>

This header file contains terminal information definitions for use with the QNX proprietary term_* functions.

The QNX proprietary term_* functions have been deprecated in favor of ncurses. ncurses is a set of terminal-independent routines for painting screens and handling input events. It's a freeware implementation that's based on the System V and X/Open curses API. For more information, see the Miscellaneous Utilities bookset in the online documentation. If you want to continue to use termlib, you'll have to link it into your program explicitly with the option -ltermlib. The file /usr/include/term.h is now an ncurses header file; you'll find the old <term.h> in /usr/include/sys/term.h. An error message is displayed if you combine the old term_* and ncurses header files.

<sys/timeb.h>

This header file describes the timeb structure used in conjunction with the ftime() function. See the description of ftime() for a description of this structure.

<sys/timers.h>

This POSIX header file contains interval timer definitions from POSIX 1003.4.

<sys/times.h>

This POSIX header file contains process timing definitions from POSIX 1003.1.

<sys/trace.h>

This header file contains trace data structures and definitions. These are described with the Trace... functions.

<sys/tracecod.h>

This header file contains the trace codes used by the Trace() functions. These are described with the Trace... functions.

<sys/types.h>

This POSIX header file contains declarations for the types used by system-level calls to obtain file status or time information.

<sys/uscsi.h>

This file contains definitions for SCSI I/O control.

<sys/uio.h>

This header file contains declarations related to the readv() and writev() functions.

<sys/utsname.h>

This POSIX header file contains a definition of the utsname structure, and a prototype for the uname() function. See the description of uname() for more information on this structure.

<sys/vc.h>

This header file contains manifests and prototypes for virtual circuit functions.

<sys/wait.h>

This POSIX header file contains manifests and prototypes for the wait() and waitpid() functions.

Header files provided for compatibility

The following headers are included in order to resolve references to items found on other operating systems. They may be helpful when porting code.

• /usr/include/ftw.h
• /usr/include/ioctl.h
• /usr/include/libc.h
• /usr/include/sgtty.h
• /usr/include/shadow.h
• /usr/include/termcap.h
• /usr/include/termio.h
• /usr/include/ustat.h
• /usr/include/utmp.h
• /usr/include/sys/dir.h
• /usr/include/sys/file.h
• /usr/include/sys/ioctl.h
• /usr/include/sys/statfs.h
• /usr/include/sys/termio.h
• /usr/include/sys/time.h