Liren Large Software Subsidy 7/07.iso/c/c500/4.ddi/WATCOMC.WPK/WATCOMC.HLP

Text File | 1992-05-28 | 238.7 KB | 6,420 lines

::::_BEGINTHREAD
#include \<process.h>
int __far _beginthread(
         void (__far *start_address)(void __far *),
         void __far *stack_bottom,
         unsigned stack_size,
         void __far *arglist );

The _beginthread  function uses the OS/2 function  DosCreateThread  to
begin  a  new  thread  of  execution  at the  function    identified  by
"start_address"  with a single    parameter identified by "arglist". The
new  thread  will  use the memory  identified  by  "stack_bottom"  and
"stack_size"  for its stack.   The thread  ends when it exits from its
main function or calls exit, _exit or _endthread.
::::_BIOS_DISK
#include \<bios.h>
unsigned short _bios_disk( unsigned service,
               struct diskinfo_t *diskinfo );
struct    diskinfo_t {        /* disk parameters     */
    unsigned drive;     /* drive number     */
    unsigned head;        /* head number     */
    unsigned track;     /* track number     */
    unsigned sector;    /* sector number     */
    unsigned nsectors;  /* number of sectors */
    void __far *buffer; /* buffer address     */
};

The  _bios_disk  function  uses INT 0x13 to provide access to the BIOS
disk functions.    Information for the desired "service" is passed the
diskinfo_t structure pointed to by "diskinfo". The value for "service"
can be one of the following values:

_DISK_RESET    Forces  the disk  controller to do a reset on the disk.
           This request does not use the "diskinfo" argument.

_DISK_STATUS   Obtains the status of the last disk operation.

_DISK_READ     Reads the  specified  number of sectors    from the disk.
           This  request uses all of the information passed in the
           "diskinfo" structure.

_DISK_WRITE    Writes the specified amount of data to the disk.   This
           request    uses  all  of the  information    passed    in the
           "diskinfo" structure.

_DISK_VERIFY   Checks the disk to be sure the  specified sectors exist
           and can be read.   A CRC (cyclic redundancy check) test
           is performed.  This request uses all of the information
           passed  in the  "diskinfo"  structure  except  for  the
           "buffer" field.

_DISK_FORMAT   Formats    the  specified track on the disk.   The "head"
           and  "track" fields indicate the track to be formatted.
           Only one track can be formatted per call.  The "buffer"
           field  points to a set of sector  markers, whose format
           depends on the type of disk drive.  This service has no
           return value.
::::_BIOS_EQUIPLIST
#include \<bios.h>
unsigned short _bios_equiplist( void );

The  _bios_equiplist function uses INT 0x11 to determine what hardware
and peripherals are installed on the machine.
::::_BIOS_KEYBRD
#include \<bios.h>
unsigned short _bios_keybrd( unsigned service );

The  _bios_keybrd  function  uses INT 0x16 to access the BIOS keyboard
services.    The  possible  values  for  "service"  are the  following
constants:

_KEYBRD_READ         Reads the next character from the keyboard.   The
             function  will  wait until a  character  has been
             typed.

_KEYBRD_READY         Checks to see if a character has been typed.   If
             there is one,  then its  value  will be returned,
             but it is not removed from the input buffer.

_KEYBRD_SHIFTSTATUS  Returns the current state of special keys.
::::_BIOS_MEMSIZE
#include \<bios.h>
unsigned short _bios_memsize( void );

The _bios_memsize function uses INT 0x12 to determine the total amount
of memory available.
::::_BIOS_PRINTER
#include \<bios.h>
unsigned short _bios_printer( unsigned service,
                  unsigned port,
                  unsigned data );

The  _bios_printer  function  uses INT 0x17 to perform    printer output
services  to the  printer  specified by "port". The values for service
are:

_PRINTER_WRITE      Sends the  low-order    byte of "data" to the  printer
          specified by "port".

_PRINTER_INIT      Initializes the printer specified by "port".

_PRINTER_STATUS   Get the status of the printer specified by "port".
::::_BIOS_SERIALCOM
#include \<bios.h>
unsigned short _bios_serialcom( unsigned service,
                unsigned serial_port,
                unsigned data );

The   _bios_serialcom    function  uses    INT  0x14  to  provide    serial
communications services to the serial port specified by "serial_port".
0  represents  COM1, 1 represents  COM2, etc.    The values for service
are:

_COM_INIT      Initializes the serial port to the parameters specified
           in "data".

_COM_SEND      Transmits  the  low-order  byte of "data" to the serial
           port.

_COM_RECEIVE   Reads an input character from the serial port.

_COM_STATUS    Returns the current status of the serial port.

The  value  passed in "data" for the  _COM_INIT  service  can be built
using the appropriate combination of the following values:

_COM_110      110 baud
_COM_150      150 baud
_COM_300      300 baud
_COM_600      600 baud
_COM_1200      1200 baud
_COM_2400      2400 baud
_COM_4800      4800 baud
_COM_9600      9600 baud

_COM_NOPARITY      No parity
_COM_EVENPARITY   Even parity
_COM_ODDPARITY      Odd parity

_COM_CHR7      7 data bits
_COM_CHR8      8 data bits

_COM_STOP1      1 stop bit
_COM_STOP2      2 stop bits
::::_BIOS_TIMEOFDAY
#include \<bios.h>
unsigned _bios_timeofday( int service, long *timeval );

The  _bios_timeofday  function uses INT 0x1A to get or set the current
system clock value.  The values for service are:

_TIME_GETCLOCK      Places  the    current  system  clock    value  in  the
          location  pointed  to  by  "timeval".  The  function
          returns  zero if  midnight  has not passed since the
          last     time  the  system  clock  was    read  or  set;
          otherwise, it returns 1.

_TIME_SETCLOCK      Sets the  system  clock to the value in the location
          pointed to by "timeval".
::::_CHAIN_INTR
#include \<dos.h>
void _chain_intr( void (__interrupt __far *func)() );

The _chain_intr function is used at the end of an interrupt routine to
start  executing  another  interrupt  handler  (usually  the  previous
handler for that interrupt).  When the interrupt handler designated by
"func"    receives control, the stack and registers appear as though the
interrupt just occurred.
::::_CLEAR87
#include \<float.h>
unsigned int _clear87( void );

The _clear87  function    clears the floating-point status word which is
used to  record  the status of    8087/80287/80387/80486    floating-point
operations.
::::_CONTROL87
#include \<float.h>
unsigned int _control87( unsigned int newcw,
             unsigned int mask );

The   _control87   function   updates    the   control    word   of  the
8087/80287/80387/80486.    If "mask" is zero, then the control word is
not updated.   If "mask" is non-zero, then the control word is updated
with  bits  from  "newcw"  corresponding  to  every  bit that is on in
"mask".
::::_DISABLE
#include \<dos.h>
void _disable( void );

The _disable function causes interrupts to become disabled.

The _disable  function    would be used in  conjunction with the _enable
function  to make sure that a sequence    of  instructions  are executed
without any intervening interrupts occurring.
::::_DOS_ALLOCMEM
#include \<dos.h>
unsigned _dos_allocmem( unsigned size,
            unsigned short *segment);

The  _dos_allocmem  function  uses system call 0x48 to allocate "size"
paragraphs  directly  from DOS.   The size of a paragraph is 16 bytes.
The  allocated    memory    is  always  paragraph  aligned.    The segment
descriptor for the allocated memory is returned in the word pointed to
by  "segment".    If the allocation request fails, the maximum number of
paragraphs that can be allocated is returned in this word instead.
::::_DOS_CLOSE
#include \<dos.h>
unsigned _dos_close( int handle );

The  _dos_close  function  uses  system  call  0x3E  to close the file
indicated by "handle". The value for "handle" is the one returned by a
function call that created or last opened the file.
::::_DOS_CREAT
#include \<dos.h>
unsigned _dos_creat( char *path,
             unsigned attribute,
             int *handle );

The  _dos_creat  function  uses  system call 0x3C to create a new file
named "path," with the access attributes specified by "attribute". The
handle    for  the  new  file  is  returned  in the word    pointed  to by
"handle". If the file already exists, the contents will be erased, and
the attributes of the file will remain unchanged.
::::_DOS_CREATNEW
#include \<dos.h>
unsigned _dos_creatnew( char *path,
            unsigned attribute,
            int *handle );

The  _dos_creatnew function uses system call 0x5B to create a new file
named "path," with the access attributes specified by "attribute". The
handle    for  the  new  file  is  returned  in the word    pointed  to by
"handle". If the file already exists, the create will fail.
::::_DOS_FINDFIRST
#include \<dos.h>
unsigned _dos_findfirst( char *path,
             unsigned attributes,
             struct find_t *buffer );
struct find_t {
  char reserved[21];      /* reserved for use by DOS   */
  char attrib;          /* attribute byte for file   */
  unsigned short wr_time; /* time of last write to file*/
  unsigned short wr_date; /* date of last write to file*/
  unsigned long  size;      /* length of file in bytes   */
  char name[13];      /* null-terminated filename  */
};

The   _dos_findfirst   function   uses    system    call  0x4E  to    return
information  on the  first  file whose name and  attributes  match the
"path" and "attributes" arguments.    The information is returned in a
find_t    structure  pointed  to by  "buffer".  The "path"  argument may
contain wildcard characters ('?' and '*').   The "attributes" argument
may be any combination of the following constants:

_A_NORMAL      Indicates a normal file.    File can be read or written
           without any restrictions.

_A_RDONLY      Indicates a read-only file.   File cannot be opened for
           "write".

_A_HIDDEN      Indicates a hidden file.  This file will not show up in
           a normal directory search.

_A_SYSTEM      Indicates a system file.  This file will not show up in
           a normal directory search.

_A_VOLID       Indicates a volume-ID.

_A_SUBDIR      Indicates a sub-directory.

_A_ARCH        This is the archive flag.   It is set whenever the file
           is  modified,  and  is  cleared    by the    MS-DOS    BACKUP
           command and other backup utility programs.
::::_DOS_FINDNEXT
#include \<dos.h>
unsigned _dos_findnext( struct find_t *buffer );

struct find_t {
  char reserved[21];      /* reserved for use by DOS   */
  char attrib;          /* attribute byte for file   */
  unsigned short wr_time; /* time of last write to file*/
  unsigned short wr_date; /* date of last write to file*/
  unsigned long  size;      /* length of file in bytes   */
  char name[13];      /* null-terminated filename  */
};

The _dos_findnext function uses system call 0x4F to return information
on the next file whose name and  attributes match the pattern supplied
to the _dos_findfirst function.    The function _dos_findfirst must be
called    before _dos_findnext to get information on the first file that
matches.  The information is returned in a find_t structure pointed to
by "buffer".
::::_DOS_FREEMEM
#include \<dos.h>
unsigned _dos_freemem( unsigned segment );

The _dos_freemem function uses system call 0x49 to release memory that
was previously    allocated by  _dos_allocmem.   The value  contained in
"segment" is the one returned by a previous call to _dos_allocmem.
::::_DOS_GETDATE
#include \<dos.h>
void _dos_getdate( struct dosdate_t *date );

struct dosdate_t {
    unsigned char day;    /* 1-31 */
    unsigned char month;    /* 1-12 */
    unsigned short year;    /* 1980-2099 */
    unsigned char dayofweek;/* 0-6 (0=Sunday) */
};

The  _dos_getdate  function  uses  system call 0x2A to get the current
system    date.     The  date  information  is  returned  in a  dosdate_t
structure pointed to by "date".
::::_DOS_GETDISKFREE
#include \<dos.h>
unsigned _dos_getdiskfree( unsigned drive,
            struct diskfree_t *diskspace );
struct diskfree_t {
    unsigned short total_clusters;
    unsigned short avail_clusters;
    unsigned short sectors_per_cluster;
    unsigned short bytes_per_sector;
};

The  _dos_getdiskfree  function uses system call 0x36 to obtain useful
information  on the disk drive specified by "drive". Specify 0 for the
default  drive, 1 for  drive A, 2 for  drive B, etc.   The information
about the drive is  returned in the structure diskfree_t pointed to by
"diskspace".
::::_DOS_GETDRIVE
#include \<dos.h>
void _dos_getdrive( unsigned *drive );

The  _dos_getdrive  function  uses system call 0x19 to get the current
disk drive number.    The current disk drive number is returned in the
word  pointed  to by "drive". A value of 1 is drive A, 2 is drive B, 3
is drive C, etc.
::::_DOS_GETFILEATTR
#include \<dos.h>
unsigned _dos_getfileattr( char *path,
               unsigned *attributes );

The _dos_getfileattr function uses system call 0x43 to get the current
attributes  of the  file or  directory    that  "path"  points to.   The
possible attributes are:

_A_NORMAL      Indicates a normal file.    File can be read or written
           without any restrictions.

_A_RDONLY      Indicates a read-only file.   File cannot be opened for
           "write".

_A_HIDDEN      Indicates a hidden file.  This file will not show up in
           a normal directory search.

_A_SYSTEM      Indicates a system file.  This file will not show up in
           a normal directory search.

_A_VOLID       Indicates a volume-ID.

_A_SUBDIR      Indicates a sub-directory.

_A_ARCH        This is the archive flag.   It is set whenever the file
           is  modified,  and  is  cleared    by the    MS-DOS    BACKUP
           command and other backup utility programs.
::::_DOS_GETFTIME
#include \<dos.h>
unsigned _dos_getftime( int handle,
            unsigned short *date,
            unsigned short *time );

The  _dos_getftime  function uses system call 0x57 to get the date and
time that the file  associated    with "handle" was last modified.   The
date  consists    of the    year,  month  and  day packed  into 16 bits as
follows:

bits 0-4  Day (1-31)
bits 5-8  Month (1-12)
bits 9-15 Year (0-119 representing 1980-2099)

The time  consists  of the hour,  minute and  seconds/2 packed into 16
bits as follows:

bits 0-4  Seconds/2 (0-29)
bits 5-10 Minutes (0-59)
bits 11-15 Hours (0-23)
::::_DOS_GETTIME
#include \<dos.h>
void _dos_gettime( struct dostime_t *time );

struct dostime_t {
    unsigned char hour;    /* 0-23 */
    unsigned char minute;    /* 0-59 */
    unsigned char second;    /* 0-59 */
    unsigned char hsecond;    /* 1/100 second; 0-99 */
};

The  _dos_gettime  function  uses  system call 0x2C to get the current
system    time.     The  time  information  is  returned  in a  dostime_t
structure pointed to by "time".
::::_DOS_GETVECT
#include \<dos.h>
void (__interrupt __far *_dos_getvect(unsigned intnum))();

The  _dos_getvect  function gets the current value of interrupt vector
number "intnum".
::::_DOS_KEEP
#include \<dos.h>
void _dos_keep( unsigned retcode, unsigned memsize );

The _dos_keep  function is used to install terminate-and-stay-resident
programs  ("TSR's")  in  memory.   The    amount of memory  kept for the
program  is  "memsize"    paragraphs  (a paragraph is 16 bytes) from the
Program  Segment  Prefix  which is stored in the  variable _psp.   The
value of "retcode" is returned to the parent process.
::::_DOS_OPEN
#include \<dos.h>
unsigned _dos_open( char *path,
            unsigned mode,
            int *handle );

The  _dos_open    function  uses    system    call  0x3D  to    open  the file
specified  by  "path,"    which must be an  existing  file.   The "mode"
argument   specifies  the  file's  access,   sharing  and  inheritance
permissions.  The access mode must be one of:

O_RDONLY      Read only
O_WRONLY      Write only
O_RDWR          Both read and write

The sharing permissions, if specified, must be one of:

SH_COMPAT      Compatibility mode
SH_DENYRW      Deny reading and writing
SH_DENYRW      Deny writing
SH_DENYRD      Deny reading
SH_DENYNONE      Deny neither

The inheritance permission, if specified, is:

O_NOINHERIT      File is not inherited by a child process
::::_DOS_READ
#include \<dos.h>
unsigned _dos_read( int handle, void __far *buffer,
            unsigned count, unsigned *bytes );

The  _dos_read function uses system call 0x3F to read "count" bytes of
data from the file specified by "handle" into the buffer pointed to by
"buffer".  The number of bytes successfully read will be stored in the
unsigned integer pointed to by "bytes".
::::_DOS_SETBLOCK
#include \<dos.h>
unsigned _dos_setblock( unsigned size, unsigned segment,
            unsigned *maxsize );

The _dos_setblock function uses system call 0x4A to change the size of
"segment,"  which was previously allocated by _dos_allocmem, to "size"
paragraphs.   If the request  fails, the maximum  number of paragraphs
that  this  memory  block  can be changed to is  returned  in the word
pointed to by "maxsize".
::::_DOS_SETDATE
#include \<dos.h>
unsigned _dos_setdate( struct dosdate_t *date );

struct dosdate_t {
    unsigned char day;    /* 1-31 */
    unsigned char month;    /* 1-12 */
    unsigned short year;    /* 1980-2099 */
    unsigned char dayofweek;/* 0-6 (0=Sunday) */
};

The  _dos_setdate  function  uses  system call 0x2B to set the current
system date.   The date information is passed in a dosdate_t structure
pointed to by "date".
::::_DOS_SETDRIVE
#include \<dos.h>
void _dos_setdrive( unsigned drive, unsigned *total );

The  _dos_setdrive  function  uses system call 0x0E to set the current
default  disk drive to be the drive  specified    by  "drive," where 1 =
drive  A, 2 = drive B, etc.    The  total  number  of disk  drives  is
returned in the word pointed to by "total".
::::_DOS_SETFILEATTR
#include \<dos.h>
unsigned _dos_setfileattr( char *path,
               unsigned attributes );

The  _dos_setfileattr  function  uses  system  call  0x43  to set  the
attributes  of the  file or  directory    that  "path"  points to.   The
possible attributes are:

_A_NORMAL      Indicates a normal file.    File can be read or written
           without any restrictions.

_A_RDONLY      Indicates a read-only file.   File cannot be opened for
           "write".

_A_HIDDEN      Indicates a hidden file.  This file will not show up in
           a normal directory search.

_A_SYSTEM      Indicates a system file.  This file will not show up in
           a normal directory search.

_A_VOLID       Indicates a volume-ID.

_A_SUBDIR      Indicates a sub-directory.

_A_ARCH        This is the archive flag.   It is set whenever the file
           is  modified,  and  is  cleared    by the    MS-DOS    BACKUP
           command and other backup utility programs.
::::_DOS_SETFTIME
#include \<dos.h>
unsigned _dos_setftime( int handle,
            unsigned short date,
            unsigned short time );

The  _dos_setftime  function uses system call 0x57 to set the date and
time that the file  associated    with "handle" was last modified.   The
date  consists    of the    year,  month  and  day packed  into 16 bits as
follows:

bits 0-4  Day (1-31)
bits 5-8  Month (1-12)
bits 9-15 Year (0-119 representing 1980-2099)

The time  consists  of the hour,  minute and  seconds/2 packed into 16
bits as follows:

bits 0-4  Seconds/2 (0-29)
bits 5-10 Minutes (0-59)
bits 11-15 Hours (0-23)
::::_DOS_SETTIME
#include \<dos.h>
unsigned _dos_settime( struct dostime_t *time );
struct dostime_t {
    unsigned char hour;    /* 0-23 */
    unsigned char minute;    /* 0-59 */
    unsigned char second;    /* 0-59 */
    unsigned char hsecond;    /* 1/100 second; 0-99 */
};

The  _dos_settime  function  uses  system call 0x2D to set the current
system time.   The time information is passed in a dostime_t structure
pointed to by "time".
::::_DOS_SETVECT
#include \<dos.h>
void _dos_setvect( unsigned intnum,
           void (__interrupt __far *handler)() );

The  _dos_setvect  function sets interrupt  vector number  "intnum" to
point to the interrupt handling function pointed to by "handler".
::::_DOS_WRITE
#include \<dos.h>
unsigned _dos_write( int handle, void __far *buffer,
             unsigned count, unsigned *bytes );

The  _dos_write  function uses system call 0x40 to write "count" bytes
of data from the buffer  pointed to by    "buffer" to the file specified
by "handle".  The number of bytes  successfully written will be stored
in the unsigned integer pointed to by "bytes".
::::_ENABLE
#include \<dos.h>
void _enable( void );

The _enable function causes interrupts to become enabled.

The _enable  function  would be used in  conjunction with the _disable
function  to make sure that a sequence    of  instructions  are executed
without any intervening interrupts occurring.
::::_ENDTHREAD
#include \<process.h>
void __far _endthread(void);

The  _endthread  function  uses the OS/2  function  DosExit to end the
current thread of execution.
::::_EXIT
#include \<stdlib.h>
void _exit( int status );

The _exit function causes normal program termination to occur.

   1. The  functions  registered by the atexit or onexit functions are
      not called.

   2. Any unopened files are not closed and any buffered output is not
      flushed to the associated files or devices.

   3. Any files created by tmpfile are not removed.

   4. The  low-order  byte of "status" is made available to the parent
      process.      The "status" value is typically set to 0 to indicate
      successful  termination  and set to some other value to indicate
      an error.
::::_EXPAND
#include \<malloc.h>
void        * _expand(void      *mem_blk,size_t size);
void __far  *_fexpand(void __far  *mem_blk,size_t size);
void __near *_nexpand(void __near *mem_blk,size_t size);

The  _expand  function    changes the size of the  previously  allocated
block  pointed to by "mem_blk" by attempting to expand or contract the
memory    block  without moving its location in the heap.   The argument
"size"    specifies  the new  desired  size for the memory  block.   The
contents  of the memory  block are  unchanged up to the shorter of the
new and old sizes.

The  _nexpand  function  expands  memory  in the  near    heap,  and the
_fexpand function expands memory in the far heap.

In a small data  memory  model, the  _expand function is equivalent to
the  _nexpand  function;  in a large data  memory  model, the  _expand
function is equivalent to the _fexpand function.
::::_FEXPAND
 ->_EXPAND
::::_FFREE
#include \<malloc.h>
void _ffree( void __far *ptr );

When the value of the argument "ptr" is NULL, the _ffree function does
nothing  otherwise, the _ffree    function  deallocates the memory block
located  by  the  argument  "ptr"  which  points  to  a  memory  block
previously allocated through a call to _fmalloc function.    After the
call, the freed block is available for allocation.

In a large data memory model, the _ffree function is equivalent to the
free function.
::::_FHEAPCHK
 ->_HEAPCHK
::::_FHEAPGROW
 ->_HEAPGROW
::::_FHEAPMIN
 ->_HEAPMIN
::::_FHEAPSET
 ->_HEAPSET
::::_FHEAPSHRINK
 ->_HEAPSHRINK
::::_FHEAPWALK
 ->_HEAPWALK
::::_FMALLOC
#include \<malloc.h>
void __far *_fmalloc( size_t size );

The _fmalloc  function    allocates space for an object of "size" bytes.
Nothing is allocated when "size" is zero.

In a  small  data  memory  model, the _fmalloc    function  acquires the
memory    block  outside    the default data  segment, if  available,  and
inside the default memory block otherwise.   This means that the total
allocations are not limited by the 64K restriction associated with the
default data segment.

In a large data memory    model, the _fmalloc  function is equivalent to
the malloc function.

Blocks    allocated with the _fmalloc  function  should be  de-allocated
using the _ffree function.
::::_FMEMCCPY
 ->MEMCCPY
::::_FMEMCHR
 ->MEMCHR
::::_FMEMCMP
 ->MEMCMP
::::_FMEMCPY
 ->MEMCPY
::::_FMEMICMP
 ->MEMICMP
::::_FMEMMOVE
 ->MEMMOVE
::::_FMEMSET
 ->MEMSET
::::_FMSIZE
 ->_MSIZE
::::_FPRESET
#include \<float.h>
void _fpreset( void );

The  _fpreset  function  should  be called  before the    floating-point
operations are attempted.
::::_FREALLOC
#include \<malloc.h>
void __far *_frealloc(void __far  *old_blk, size_t size);

When  the  value  of the  "old_blk"  argument  is NULL, a new block of
memory of "size" bytes is allocated.

If the value of "size" is zero,  _frealloc  calls the free function to
release the memory pointed to by "old_blk".

Otherwise, the _frealloc  function re-allocates space for an object of
"size" bytes by either:

   * shrinking    the  allocated    size  of the  allocated  memory  block
    "old_blk"  when  "size" is    sufficiently  smaller than the size of
    "old_blk".

   * extending    the  allocated    size  of the  allocated  memory  block
    "old_blk"  if there is a large  enough block of unallocated memory
    immediately following "old_blk".

   * allocating  a new block and  copying the contents of "old_blk" to
    the new block.

Because it is  possible  that a new block will be  allocated, no other
pointers  should point into the memory of  "old_blk".  These  pointers
will point to freed  memory, with  possible disastrous results, when a
new block is allocated.

The  memory  pointed  to by  "old_blk"    is not    freed  if it cannot be
re-allocated.

The  _frealloc    function  reallocates  memory  in the  far heap.    If
_frealloc  cannot  reallocate  the memory in the far heap, it will try
the near heap.

In a large data memory    model, the _frealloc function is equivalent to
the realloc function.

The  _frealloc    function  is a    WATCOM    extension  to the  standard  C
library.
::::_FREECT
#include \<malloc.h>
unsigned int _freect( size_t size );

The  _freect  function    returns the number of times that  _nmalloc (or
malloc    in  small  data  models)  can be called to  allocate a item of
"size"    bytes.     In the  tiny,    small and medium  memory  models,  the
default  data  segment is only    extended as needed to satisfy requests
for memory allocation.    Therefore, you will need to call _nheapgrow in
these  memory  models  before  calling    _freect  in  order  to    get  a
meaningful result.
::::_FSTRCAT
 ->STRCAT
::::_FSTRCHR
 ->STRCHR
::::_FSTRCMP
 ->STRCMP
::::_FSTRCPY
 ->STRCPY
::::_FSTRCSPN
 ->STRCSPN
::::_FSTRICMP
 ->STRICMP
::::_FSTRLEN
 ->STRLEN
::::_FSTRLWR
 ->STRLWR
::::_FSTRNCAT
 ->STRNCAT
::::_FSTRNCMP
 ->STRNCMP
::::_FSTRNCPY
 ->STRNCPY
::::_FSTRNICMP
 ->STRNICMP
::::_FSTRNSET
 ->STRNSET
::::_FSTRPBRK
 ->STRPBRK
::::_FSTRRCHR
 ->STRRCHR
::::_FSTRREV
 ->STRREV
::::_FSTRSET
 ->STRSET
::::_FSTRSPN
 ->STRSPN
::::_FSTRSTR
 ->STRSTR
::::_FSTRTOK
 ->STRTOK
::::_FSTRUPR
 ->STRUPR
::::_FULLPATH
#include \<stdlib.h>
void _fullpath( char *buff,
        const char *path,
        size_t size );

The   _fullpath  function  returns  the  full  pathname  of  the  file
specification  in  "path"  in the  specified  buffer  "buff" of length
"size".

The  maximum  size that might be required for "buff" is PATH_MAX.   If
the buffer  provided  is too small, NULL is returned and errno is set.
If "buff" is NULL then a buffer of size  PATH_MAX  is  allocated using
malloc.

If  "path"  is NULL or    points    to a null string ("") then the current
working directory is returned in "buff".
::::_HARDERR
#include \<dos.h>
void _harderr( int (__far *funcptr)() );
void _hardresume( int action );

The _harderr  routine installs a critical error handler (for INT 0x24)
to handle hardware errors.   This critical error handler will call the
function  specified  by  "funcptr"  when a critical  error occurs (for
example,  attempting  to open a file on a floppy  disk    when the drive
door is open).    The parameters to this function are as follows:

int handler( unsigned deverror,
         unsigned errcode,
         unsigned __far *devhdr );

The low-order byte of "errcode" can be one of the following values:

0x00   Attempt to write to a write-protected disk
0x01   Unknown unit
0x02   Drive not ready
0x03   Unknown command
0x04   CRC error in data
0x05   Bad drive-request structure length
0x06   Seek error
0x07   Unknown media type
0x08   Sector not found
0x09   Printer out of paper
0x0A   Write fault
0x0B   Read fault
0x0C   General failure

The "devhdr"  argument    points to a device  header  control-block that
contains  information  about  the device on which the error  occurred.
Your error  handler may inspect the  information in this control-block
but must not change it.

If the    error  occurred  on a disk  device,  bit 15 of the  "deverror"
argument  will be 0 and the  "deverror"  argument  will  indicate  the
following:

bit 15 0 indicates disk error
bit 14 not used
bit 13 0 indicates "Ignore" response not allowed
bit 12 0 indicates "Retry" response not allowed
bit 11 0 indicates "Fail" response not allowed
bit 9,10 location of error

       00     MS-DOS
       01     File Allocation Table (FAT)
       10     Directory
       11     Data area
bit 8  0 indicates read error, 1 indicates write error

The  low-order    byte of "deverror" indicates the drive where the error
occurred; (0 = drive A, 1 = drive B, etc.).

The handler is very restricted in the type of system calls that it can
perform.  System calls 0x01 through 0x0C, and 0x59 are the only system
calls  allowed to be issued by the  handler.   Therefore,  many of the
standard C run-time  functions    such as stream I/O and    low-level  I/O
cannot be used by the handler.     Console I/O is allowed (eg.  cprintf,
cputs).

The  handler must indicate what action to take by returning one of the
following  values  or calling  _hardresume  with one of the  following
values:

_HARDERR_IGNORE       Ignore the error

_HARDERR_RETRY          Retry the operation

_HARDERR_ABORT          Abort the program issuing INT 0x23

_HARDERR_FAIL          Fail the system  call that is in    progress  (DOS
              3.0 or higher)

See  The  MS-DOS   Encyclopedia   for  more  detailed  information  on
determining the type of error that has occurred.
::::_HARDRESUME
 ->_HARDERR
::::_HEAPCHK
#include \<malloc.h>
int  _heapchk( void );
int _nheapchk( void );
int _fheapchk( void );

The _heapchk  function    along with _heapset and _heapwalk are provided
for debugging heap related problems in programs.

The _heapchk  function    does a    consistency  check on the  unallocated
memory space or "heap".   The consistency check determines whether all
the heap entries are valid.   The  _nheapchk  function checks the near
heap and the _fheapchk function checks the far heap.

In a small data memory    model, the _heapchk  function is equivalent to
the  _nheapchk    function;  in a large data memory  model, the _heapchk
function is equivalent to the _fheapchk function.
::::_HEAPGROW
#include \<malloc.h>
void  _heapgrow( void );
void _nheapgrow( void );
void _fheapgrow( void );

The  _nheapgrow function attempts to grow the near heap to the maximum
size of 64K.  You will want to do this in the small data models if you
are using both malloc and _fmalloc or halloc.  Once a call to _fmalloc
or  halloc  has been  made, you may not be able to allocate any memory
with  malloc  unless  space has been  reserved for the near heap using
either malloc, sbrk or _nheapgrow.

The  _fheapgrow  function  doesn't do anything to the heap because the
far heap will be extended automatically when needed.    If the current
far heap cannot be extended, then another far heap will be started.

In a small data memory    model, the _heapgrow function is equivalent to
the  _nheapgrow  function; in a large data memory model, the _heapgrow
function is equivalent to the _fheapgrow function.
::::_HEAPMIN
#include \<malloc.h>
int  _heapmin( void );
int _nheapmin( void );
int _fheapmin( void );

The  _heapmin  function  attempts  to shrink the heap to its  smallest
possible  size by  returning  all free    entries at the end of the heap
back to the  system.   This can be used to free up as much  memory  as
possible  before  using  the  system  function    or  one  of the  spawn
functions.

In a small data memory    model, the _heapmin  function is equivalent to
the  _nheapmin    function;  in a large data memory  model, the _heapmin
function is equivalent to the _fheapmin function.   It is identical to
the _heapshrink function.
::::_HEAPSET
#include \<malloc.h>
int  _heapset( unsigned char fill_char );
int _nheapset( unsigned char fill_char );
int _fheapset( unsigned char fill_char );

The _heapset  function    along with _heapchk and _heapwalk are provided
for debugging heap related problems in programs.

The _heapset  function    does a    consistency  check on the  unallocated
memory space or "heap" just as _heapchk does, and sets the heap's free
entries  with the  "fill_char"    value.     The  _nheapset  function sets
entries in the near heap and the  _fheapset  function  sets entries in
the far heap.

In a small data memory    model, the _heapset  function is equivalent to
the  _nheapset    function;  in a large data memory  model, the _heapset
function is equivalent to the _fheapset function.
::::_HEAPSHRINK
#include \<malloc.h>
int  _heapshrink( void );
int _nheapshrink( void );
int _fheapshrink( void );

The  _heapshrink  function attempts to shrink the heap to its smallest
possible  size by  returning  all free    entries at the end of the heap
back to the  system.   This can be used to free up as much  memory  as
possible  before  using  the  system  function    or  one  of the  spawn
functions.

In a small data memory    model, the  _heapshrink function is equivalent
to the    _nheapshrink  function;  in a  large  data  memory  model, the
_heapshrink function is equivalent to the _fheapshrink function.    It
is identical to the _heapmin function.
::::_HEAPWALK
#include \<malloc.h>
int  _heapwalk( struct _heapinfo *entry );
int _nheapwalk( struct _heapinfo *entry );
int _fheapwalk( struct _heapinfo *entry );

struct _heapinfo {
    void __far *_pentry;   /* heap pointer */
    size_t     _size;       /* heap entry size */
    int        _useflag;   /* heap entry 'in-use' flag */
};
#define _USEDENTRY    0
#define _FREEENTRY    1

The  _heapwalk    function along with _heapchk and _heapset are provided
for debugging heap related problems in programs.

The  _heapwalk    function  walks  through the heap, one entry per call,
returning a pointer to a _heapinfo structure that contains information
on the next heap entry.   The structure is defined in \<malloc.h>.  The
_nheapwalk  function  walks  through the near heap and the  _fheapwalk
function walks through the far heap.

On 16-bit 80x86  systems, the  _heapwalk function is equivalent to the
_nheapwalk function in a small data memory model; and is equivalent to
the _fheapwalk function in a large data memory model.
::::_LROTL
#include \<stdlib.h>
unsigned long _lrotl( unsigned long value,
              unsigned int shift );

The _lrotl  function  rotates the unsigned long integer, determined by
"value," to the left by the number of bits specified in "shift".
::::_LROTR
#include \<stdlib.h>
unsigned long _lrotr( unsigned long value,
              unsigned int shift );

The _lrotr  function  rotates the unsigned long integer, determined by
"value," to the right by the number of bits specified in "shift".
::::_MAKEPATH
#include \<stdlib.h>
void _makepath( char *path,
        const char *drive,
        const char *dir,
        const char *fname,
        const char *ext );

The  _makepath function constructs a full pathname from the components
consisting  of a drive letter, directory path, file name and file name
extension.   The full  pathname  is placed in the buffer pointed to by
the argument "path".

The maximum size required for each buffer is specified by the manifest
constants  _MAX_PATH,  _MAX_DRIVE,  _MAX_DIR, _MAX_FNAME, and _MAX_EXT
which are defined in \<stdlib.h>.

drive      The "drive" argument points to a buffer containing the drive
      letter (A, B, C, etc.) followed by an optional colon.    The
      _makepath  function will automatically insert a colon in the
      full    pathname  if  it is  missing.    If  "drive"  is a NULL
      pointer  or  points to an empty  string, no drive  letter or
      colon will be placed in the full pathname.

dir      The "dir"  argument  points to a buffer  containing just the
      pathname.  Either forward slashes (/) or backslashes (\) may
      be used.   The trailing  slash is optional.    The  _makepath
      function  will  automatically insert a trailing slash in the
      full pathname if it is missing.   If "dir" is a NULL pointer
      or points to an empty string, no slash will be placed in the
      full pathname.

fname      The "fname"  argument points to a buffer containing the base
      name of the file without any extension (suffix).

ext      The  "ext"  argument    points    to  a  buffer  containing  the
      filename  extension  or  suffix.   A    leading  period (.) is
      optional.  The _makepath routine will automatically insert a
      period in the full pathname if it is missing.  If "ext" is a
      NULL pointer or points to an empty string, no period will be
      placed in the full pathname.
::::_MEMAVL
#include \<malloc.h>
size_t _memavl( void );

The _memavl  function  returns the number of bytes of memory available
for  dynamic  memory  allocation  in the  near    heap (the default data
segment).   In the tiny,  small and medium  memory models, the default
data segment is only extended as needed to satisfy requests for memory
allocation.   Therefore,  you  will need to call  _nheapgrow  in these
memory    models    before    calling  _memavl in order to get a  meaningful
result.

The number  returned by _memavl may not  represent a single contiguous
block  of  memory.    Use the  _memmax    function  to find the  largest
contiguous block of memory that can be allocated.
::::_MEMMAX
#include \<malloc.h>
size_t _memmax( void );

The _memmax  function returns the size of the largest contiguous block
of memory  available  for dynamic  memory  allocation in the near heap
(the  default  data  segment).     In the tiny,  small and medium memory
models, the default data segment is only extended as needed to satisfy
requests  for  memory  allocation.   Therefore,  you will need to call
_nheapgrow  in these memory  models before calling _memmax in order to
get a meaningful result.

::::_MSIZE
#include \<malloc.h>
size_t _msize( void *buffer );
size_t _fmsize( void __far *buffer );
size_t _nmsize( void __near *buffer );

The _msize function returns the size of the memory block pointed to by
"buffer" that was allocated by a call to calloc, malloc, or realloc.

In small data models  (small and medium memory models), _msize maps to
_nmsize.    In    large  data  models  (compact,    large  and huge memory
models), _msize maps to _fmsize.

The _nmsize function returns the size of the memory block allocated by
a call to _nmalloc.

The _fmsize function returns the size of the memory block allocated by
a call to _fmalloc.
::::_NEXPAND
 ->_EXPAND
::::_NFREE
#include \<malloc.h>
void _nfree( void __near *ptr );

When the value of the argument "ptr" is NULL, the _nfree function does
nothing  otherwise, the _nfree    function  deallocates the memory block
located  by  the  argument  "ptr"  which  points  to  a  memory  block
previously allocated through a call to _nmalloc function.    After the
call, the freed block is available for allocation.

In a small data memory model, the _nfree function is equivalent to the
free function.
::::_NHEAPCHK
 ->_HEAPCHK
::::_NHEAPGROW
 ->_HEAPGROW
::::_NHEAPMIN
 ->_HEAPMIN
::::_NHEAPSET
 ->_HEAPSET
::::_NHEAPSHRINK
 ->_HEAPSHRINK
::::_NHEAPWALK
 ->_HEAPWALK
::::_NMALLOC
#include \<malloc.h>
void __near *_nmalloc( size_t size );

The _nmalloc  function    allocates space for an object of "size" bytes.
Nothing is allocated when "size" is zero.

The  _nmalloc  function  acquires  the memory block inside the default
data  segment.     This means that the total  allocations are limited by
the 64K restriction associated with the default data segment.

In a small data memory    model, the _nmalloc  function is equivalent to
the malloc function.

Blocks    allocated with the _nmalloc  function  should be  de-allocated
using the _nfree function.
::::_NMSIZE
 ->_MSIZE
::::_NREALLOC
#include \<malloc.h>
void __near *_nrealloc(void __near *old_blk, size_t size);

When  the  value  of the  "old_blk"  argument  is NULL, a new block of
memory of "size" bytes is allocated.

If the value of "size" is zero,  _nrealloc  calls the free function to
release the memory pointed to by "old_blk".

Otherwise, the _nrealloc  function re-allocates space for an object of
"size" bytes by either:

   * shrinking    the  allocated    size  of the  allocated  memory  block
    "old_blk"  when  "size" is    sufficiently  smaller than the size of
    "old_blk".

   * extending    the  allocated    size  of the  allocated  memory  block
    "old_blk"  if there is a large  enough block of unallocated memory
    immediately following "old_blk".

   * allocating  a new block and  copying the contents of "old_blk" to
    the new block.

Because it is  possible  that a new block will be  allocated, no other
pointers  should point into the memory of  "old_blk".  These  pointers
will point to freed  memory, with  possible disastrous results, when a
new block is allocated.

The  memory  pointed  to by  "old_blk"    is not    freed  if it cannot be
re-allocated.

The _nrealloc function reallocates memory in the near heap.

In a small data memory    model, the _nrealloc function is equivalent to
the realloc function.

The  _nrealloc    function  is a    WATCOM    extension  to the  standard  C
library.
::::_ROTL
#include \<stdlib.h>
unsigned int _rotl( unsigned int value,
            unsigned int shift );

The  _rotl  function  rotates  the  unsigned  integer,    determined  by
"value,"  to the left by the number of bits  specified    in "shift". If
you  port an  application  using  _rotl  between a 16-bit and a 32-bit
environment,  you will get different results because of the difference
in the size of integers.
::::_ROTR
#include \<stdlib.h>
unsigned int _rotr( unsigned int value,
            unsigned int shift );

The  _rotr  function  rotates  the  unsigned  integer,    determined  by
"value,"  to the right by the number of bits  specified in "shift". If
you  port an  application  using  _rotr  between a 16-bit and a 32-bit
environment,  you will get different results because of the difference
in the size of integers.
::::_SEARCHENV
#include \<stdlib.h>
void _searchenv( const char *name,
         const char *env_var,
         char *buffer );

The  _searchenv  function searches for the file specified by "name" in
the list of directories assigned to the environment variable specified
by "env_var". Common values for "env_var" are PATH, LIB and INCLUDE.

The current  directory is searched  first to find the  specified file.
If  the  file  is  not    found in the  current  directory,  each of the
directories specified by the environment variable is searched.

The full  pathname  is placed in the buffer pointed to by the argument
"buffer". If the  specified  file cannot be found, then  "buffer" will
contain an empty string.
::::_SPLITPATH
#include \<stdlib.h>
void _splitpath( const char *path,
               char *drive,
               char *dir,
               char *fname,
               char *ext );

The _splitpath function splits up a full pathname into four components
consisting  of a drive letter, directory path, file name and file name
extension.  The argument "path" points to a buffer containing the full
pathname to be split up.

The maximum size required for each buffer is specified by the manifest
constants  _MAX_PATH,  _MAX_DRIVE,  _MAX_DIR, _MAX_FNAME, and _MAX_EXT
which are defined in \<stdlib.h>.

drive      The  "drive" argument points to a buffer that will be filled
      in with the drive letter (A, B, C, etc.) followed by a colon
      if a drive is specified in the full pathname.

dir      The "dir" argument points to a buffer that will be filled in
      with the  pathname  including  the trailing  slash.    Either
      forward slashes (/) or backslashes (\) may be used.

fname      The  "fname" argument points to a buffer that will be filled
      in  with the base  name of the file  without    any  extension
      (suffix).

ext      The "ext" argument points to a buffer that will be filled in
      with the filename  extension or suffix including the leading
      period.

The  arguments "drive," "dir," "fname" and "ext" will not be filled in
if they are NULL pointers.

For each  component  of the full  pathname  that is not  present,  its
corresponding buffer will be set to an empty string.
::::_STATUS87
#include \<float.h>
unsigned int _status87( void );

The _status87 function returns the floating-point status word which is
used to  record  the status of    8087/80287/80387/80486    floating-point
operations.
::::ABORT
#include \<stdlib.h>
void abort( void );

The abort function raises the signal SIGABRT.    The default action for
SIGABRT is to terminate  program  execution,  returning control to the
process  that  started    the  calling  program  (usually the  operating
system).   The    status    unsuccessful  termination  is  returned to the
invoking process by means of the function call raise(SIGABRT).     Under
DOS and OS/2, the status value is 3.
::::ABS
#include \<stdlib.h>
int abs( int j );

The abs function  returns the absolute    value of its integer  argument
"j".
::::ACCESS
#include \<io.h>
int access( const char *path, int mode );

The access  function  determines if the file or directory specified by
"path" exists and if it can be accessed with the file permission given
by "mode".

When the  value of  "mode"  is zero, only the existence of the file is
verified.   The  read  and/or  write  permission  for  the file can be
determined when "mode" is a combination of the bits:

R_OK        test for read permission

W_OK        test for write permission

X_OK        test for execute permission

F_OK        test for existence of file

With  DOS, all    files  have read permission; it is a good idea to test
for read  permission  anyway, since a later version of DOS may support
write-only files.
::::ACOS
#include \<math.h>
double acos( double x );

The acos  function  computes the  principal  value of the arccosine of
"x". A domain error occurs for arguments not in the range [-1,1].
::::ACOSH
#include \<math.h>
double acosh( double x );

The acosh  function  computes the inverse  hyperbolic cosine of "x". A
domain error occurs if the value of "x" is less than 1.0.
::::ALLOCA
#include \<malloc.h>
void *alloca( size_t size );

The alloca function allocates space for an object of "size" bytes from
the stack.   The allocated  space is  automatically discarded when the
current function exits.   The alloca function should not be used in an
expression that is an argument to a function.
::::ALLOCATION
              Memory Allocation Functions
              ═══════════════════════════

These  functions  allocate  and  de-allocate  blocks  of  memory.  The
following functions are defined:

<alloca>    allocate auto storage from stack
<calloc>    allocate and zero memory
<_expand>    expand a block of memory
<_fexpand>    expand    a  block  of  memory   (outside  default  data
        segment)
<_ffree>    free a block allocated using _fmalloc
<_fmalloc>    allocate a memory block (outside default data segment)
<_fmsize>    return the size of a memory block
<_frealloc>    re-allocate  a    memory    block  (outside  default  data
        segment)
<free>        free a block allocated using malloc, calloc or realloc
<_freect>    return number of objects that can be allocated
<halloc>    allocate huge array
<hfree>     free huge array
<malloc>    allocate a memory block (using current memory model)
<_memavl>    return amount of available memory
<_memmax>    return largest block of memory available
<_msize>    return the size of a memory block
<_nexpand>    expand a block of memory (inside default data segment)
<_nfree>    free a block allocated using _nmalloc
<_nmalloc>    allocate a memory block (inside default data segment)
<_nmsize>    return the size of a memory block
<_nrealloc>    re-allocate   a  memory  block    (inside  default  data
        segment)
<realloc>    re-allocate a block of memory
<sbrk>        set allocation "break" position
<stackavail>    determine available amount of stack space
::::ASCTIME
#include \<time.h>
char *asctime( const struct tm *timeptr );

struct    tm {
  int tm_sec;    /* seconds after the minute -- [0,61] */
  int tm_min;    /* minutes after the hour   -- [0,59] */
  int tm_hour;    /* hours after midnight     -- [0,23] */
  int tm_mday;    /* day of the month        -- [1,31] */
  int tm_mon;    /* months since January     -- [0,11] */
  int tm_year;    /* years since 1900              */
  int tm_wday;    /* days since Sunday        -- [0,6]  */
  int tm_yday;    /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag */
};

The asctime  function  converts the time  information in the structure
pointed  to  by  "timeptr"   into  a  string   containing  exactly  26
characters.  This string has the form shown in the following example:

Sat Mar 21 15:58:27 1987\n\0

All fields have a constant width.  The new-line character '\n' and the
null character '\0' occupy the last two positions of the string.

The area  containing  the returned string is re-used each time asctime
is called.
::::ASIN
#include \<math.h>
double asin( double x );

The asin  function computes the principal value of the arcsine of "x".
A domain error occurs for arguments not in the range [-1,1].
::::ASINH
#include \<math.h>
double asinh( double x );

The asinh function computes the inverse hyperbolic sine of "x".
::::ASSERT
#include \<assert.h>
void assert( int expression );

The  assert macro prints a diagnostic  message upon the stderr    stream
and  terminates  the  program  if  "expression"  is  false (0).    The
diagnostic message has the form

Assertion failed:  "expression," file "filename," line "linenumber"

where  "filename"  is the name of the source  file and "linenumber" is
the  line  number of the  assertion  that  failed in the source  file.
"Filename" and "linenumber" are the values of the preprocessing macros
__FILE__   and     __LINE__   respectively.    No  action  is  taken  if
"expression" is true (non-zero).

The  assert  macro is typically  used during  program  development  to
identify  program  logic  errors.   The given  "expression"  should be
chosen so that it is true when the program is functioning as intended.
After the program has been debugged, the special "no debug" identifier
NDEBUG can be used to remove  assert calls from the program when it is
re-compiled.   If NDEBUG is defined (with any value) with a -d command
line option or with a #define  directive,  the C  preprocessor ignores
all assert calls in the program source.
::::ATAN
#include \<math.h>
double atan( double x );

The atan  function  computes the  principal value of the arctangent of
"x".
::::ATAN2
#include \<math.h>
double atan2( double y, double x );

The atan2  function  computes the principal value of the arctangent of
"y/x,"    using the signs of both arguments to determine the quadrant of
the return value.  A domain error occurs if both arguments are zero.
::::ATANH
#include \<math.h>
double atanh( double x );

The atanh  function  computes the inverse hyperbolic tangent of "x". A
domain error occurs if the value of "x" is outside the range (-1,1).
::::ATEXIT
#include \<stdlib.h>
int atexit( void (*func)(void) );

The atexit  function  is passed the  address of  function "func" to be
called    when the program  terminates  normally.   Successive  calls to
atexit create a list of functions that will be executed on a "last-in,
first-out"  basis.   No more than 32  functions can be registered with
the atexit function.

The functions have no parameters and do not return values.
::::ATOF
#include \<stdlib.h>
double atof( const char *ptr );

The atof  function  converts  the string pointed to by "ptr" to double
representation.  It is equivalent to

strtod( ptr, (char **)NULL )
::::ATOI
#include \<stdlib.h>
int atoi( const char *ptr );

The  atoi  function  converts  the  string  pointed to by "ptr" to int
representation.
::::ATOL
#include \<stdlib.h>
long int atol( const char *ptr );

The atol  function converts the string pointed to by "ptr" to long int
representation.
::::BDOS
#include \<dos.h>
int bdos( int dos_func, unsigned dx, unsigned char al );

The bdos  function causes the computer's central processor (CPU) to be
interrupted  with an interrupt number hexadecimal 21 ( 0x21), which is
a request to invoke a specific DOS  function.    Before the  interrupt,
the DX    register  is loaded  from "dx," the AH register is loaded with
the DOS  function number from "dos_func" and the AL register is loaded
from "al". The remaining registers are passed unchanged to DOS.

You should  consult the  technical documentation for the DOS operating
system    you  are  using to determine  the expected  register  contents
before and after the interrupt in question.
::::BESSEL
#include \<math.h>
double j0( double x );
double j1( double x );
double jn( int n, double x );
double y0( double x );
double y1( double x );
double yn( int n, double x );

Functions j0, j1, and jn return Bessel functions of the first kind.

Functions  y0, y1, and yn return  Bessel functions of the second kind.
The argument "x" must be positive.   If "x" is negative, _matherr will
be  called  to print a DOMAIN  error  message to stderr,  set errno to
EDOM,  and  return the value  -HUGE_VAL.   This error  handling can be
modified by using the matherr routine.
::::BIOS
                BIOS Functions
                ══════════════

This set of  functions allows access to services provided by the BIOS.
The following functions are defined:

<_bios_disk>        provide disk access functions
<_bios_equiplist>   determine equipment list
<_bios_keybrd>        provide low-level keyboard access
<_bios_memsize>     determine amount of system board memory
<_bios_printer>     provide access to printer services
<_bios_serialcom>   provide access to serial services
<_bios_timeofday>   get and set system clock
::::BSEARCH
#include \<stdlib.h>
void *bsearch( const void *key,
           const void *base,
           size_t num,
           size_t width,
           int (*compar)( const void *pkey,
                  const void *pbase) );

The  bsearch  function    performs a binary  search of a sorted array of
"num"  elements,  which  is  pointed  to by "base,"  for an item which
matches  the object  pointed to by "key". Each element in the array is
"width" bytes in size.    The comparison function pointed to by "compar"
is called with two arguments that point to elements in the array.  The
first  argument  "pkey" points to the same object pointed to by "key".
The second  argument  "pbase"  points to a element in the array.   The
comparison  function  shall  return an integer less than, equal to, or
greater  than  zero if the  "key"  object  is less  than, equal to, or
greater than the element in the array.
::::CABS
#include \<math.h>
double cabs( struct complex value );

struct complex {
    double real;    /* real part */
    double imag;    /* imaginary part */
};

The cabs  function  computes the absolute  value of the complex number
"value" by a calculation which is equivalent to

sqrt( (value.x * value.x) + (value.y * value.y) )

In  certain  cases,  overflow  errors  may  occur which will cause the
matherr routine to be invoked.
::::CALLOC
#include \<stdlib.h>
void *calloc( size_t n, size_t size );

The calloc  function allocates space for an array of "n" objects, each
of length "size" bytes.  Each element is initialized to 0.

A block of memory  allocated using the calloc function should be freed
using the free function.
::::CEIL
#include \<math.h>
double ceil( double x );

The ceil function (ceiling function) computes the smallest integer not
less than "x".
::::CGETS
#include \<conio.h>
char *cgets( char *buf );

The  cgets  function  gets a string of    characters  directly  from the
console  and stores the string and its length in the array  pointed to
by "buf". The first  element of the array  "buf[0]"  must  contain the
maximum length in characters of the string to be read.    The array must
be big enough to hold the  string, a  terminating  null character, and
two additional bytes.

The cgets function reads  characters until a carriage-return line-feed
combination  is read, or until the  specified  number of characters is
read.    The string is stored in the array  starting  at  "buf[2]". The
carriage-return  line-feed combination, if read, is replaced by a null
character.    The  actual  length  of the  string  read  is  placed in
"buf[1]".
::::CHARACTER
           Character Manipulation Functions
           ════════════════════════════════

These  functions  operate upon single  characters  of type char.   The
functions  test  characters  in  various ways and convert them between
upper and lower-case.  The following functions are defined:

<isalnum>    test for letter or digit
<isalpha>    test for letter
<isascii>    test for ASCII character
<iscntrl>    test for control character
<isdigit>    test for digit
<isgraph>    test for printable character, except space
<islower>    test for letter in lower-case
<isprint>    test for printable character, including space
<ispunct>    test for punctuation characters
<isspace>    test for "white space" characters
<isupper>    test for letter in upper-case
<isxdigit>    test for hexadecimal digit
<tolower>    convert character to lower-case
<toupper>    convert character to upper-case
::::CHDIR
#include \<sys\types.h>
#include \<direct.h>
int chdir( const char *path );

The  chdir  function  changes  the  current  working  directory to the
specified  "path".  The "path" can be either  relative    to the current
working directory or it can be an absolute path name.
::::CHMOD
#include \<sys\types.h>
#include \<sys\stat.h>
#include \<io.h>
int chmod( const char *path, int permission );

The chmod  function  changes the  permissions  for a file specified by
"path"    to be the  settings  in the  mode given by  "permission".  The
access    permissions  for  the file or  directory  are  specified  as a
combination of bits (defined in the \<sys\stat.h> header file).

The following bits define permissions for the owner.

S_IRWXU     Read, write, execute/search

S_IRUSR     Read permission

S_IWUSR     Write permission

S_IXUSR     Execute/search permission

The following bits define permissions for the group.

S_IRWXG     Read, write, execute/search

S_IRGRP     Read permission

S_IWGRP     Write permission

S_IXGRP     Execute/search permission

The following bits define permissions for others.

S_IRWXO     Read, write, execute/search

S_IROTH     Read permission

S_IWOTH     Write permission

S_IXOTH     Execute/search permission

The  following    bits define  miscellaneous  permissions  used by other
implementations.

S_IREAD     is equivalent to S_IRUSR (read permission)

S_IWRITE    is equivalent to S_IWUSR (write permission)

S_IEXEC     is equivalent to S_IXUSR (execute/search permission)

The following bits may also be specified in "permission".

S_ISUID     set user id on execution

S_ISGID     set group id on execution

If the calling    process does not have  appropriate  privileges, and if
the  group ID of the file does not match the effective group ID or one
of the supplementary group IDs, and if the file is a regular file, bit
S_ISGID  (set  group  ID on  execution)  in the  file's  mode shall be
cleared upon successful return from the chmod function.

Upon  successful  completion,  the chmod function will mark for update
the st_ctime field of the file.
::::CHSIZE
#include \<io.h>
int chsize( int handle, long size );

The  chsize  function  changes    the size of the file  associated  with
"handle"  by  extending or truncating the file to the length specified
by "size". If the file needs to be  extended,  the file is padded with
NULL ('\0') characters.
::::CLEARENV
#include \<env.h>
int clearenv( void );

The  clearenv  function  clears  the process  environment  area.    No
environment  variables    are  defined  immediately  after a call to the
clearenv  function.   Note that this clears the PATH,  COMSPEC, and TZ
environment  variables    which  may then affect the  operation of other
library functions.

The clearenv function may manipulate the value of the pointer environ.
::::CLEARERR
#include \<stdio.h>
void clearerr( FILE *fp );

The clearerr  function clears the end-of-file and error indicators for
the stream  pointed to by "fp". These indicators are cleared only when
the file is  opened  or by an  explicit call to the clearerr or rewind
functions.
::::CLOCK
#include \<time.h>
clock_t clock(void);

The clock function returns the number of clock ticks of processor time
used  by program  since the program  started  executing.   This can be
converted   to    seconds  by   dividing    by  the  value    of  the  macro
CLOCKS_PER_SEC.
::::CLOSE
#include \<io.h>
int close( int handle );

The close function closes a file at the operating system level.    The
"handle"  value is the file  handle returned by a successful execution
of one of the creat, dup, dup2, open or sopen functions.
::::CLOSEDIR
#include \<sys\types.h>
#include \<direct.h>
int closedir( DIR *dirp );

The  closedir  function  closes the directory  specified by "dirp" and
frees the memory allocated by opendir.
::::CONSOLE
             Console I/O Functions
             ═════════════════════

These functions provide the capability to read and write data from the
console.    Data is read or written without any special initialization
(devices are not opened or closed), since the functions operate at the
hardware level.

The following functions are defined:

<cgets>     get a string from the console
<cprintf>    print formatted string to the console
<cputs>     write a string to the console
<cscanf>    scan formatted data from the console
<getch>     get character from console, no echo
<getche>    get character from console, echo it
<kbhit>     test if keystroke available
<putch>     write a character to the console
<ungetch>    push back next character from console
::::CONVERSION
             Conversion Functions
             ════════════════════

These  functions  perform conversions between objects of various types
and strings.  The following functions are defined:

<atof>        string to double
<atoi>        string to int
<atol>        string to long int
<ecvt>        double to E-format string
<fcvt>        double to F-format string
<gcvt>        double to string
<itoa>        int to string
<ltoa>        long int to string
<strtod>    string to double
<strtol>    string to long int
<strtoul>    string to unsigned long int
<ultoa>     unsigned long int to string
<utoa>        unsigned int to string

See also <tolower>, <toupper>, <strlwr> and <strupr> which convert the
cases of characters and strings.
::::COS
#include \<math.h>
double cos( double x );

The cos function computes the cosine of "x" (measured in radians).   A
large  magnitude  argument  may  yield    a  result  with  little  or no
significance.
::::COSH
#include \<math.h>
double cosh( double x );

The cosh function computes the hyperbolic cosine of "x". A range error
occurs if the magnitude of "x" is too large.
::::CPRINTF
#include \<conio.h>
int cprintf( const char *format, ... );

The  cprintf  function    writes    output    directly to the console  under
control of the argument "format". The putch function is used to output
characters to the console.  The "format" string is described under the
description for printf.
::::CPUTS
#include \<conio.h>
int cputs( const char *buf );

The cputs  function  writes the  character  string pointed to by "buf"
directly  to the  console  using the putch function.   Unlike the puts
function,  the     carriage-return  and  line-feed  characters  are  not
appended  to the  string.    The  terminating  null  character    is not
written.
::::CREAT
#include \<sys\types.h>
#include \<sys\stat.h>
#include \<io.h>
int creat( const char *path, int mode );

The creat  function creates (and opens) a file at the operating system
level.    It is equivalent to:

  open( path, O_WRONLY | O_CREAT | O_TRUNC, mode );

The name of the file to be  created  is given by "path". When the file
exists (it must be  writeable), it is truncated to contain no data and
the preceding "mode" setting is unchanged.

When the file does not exist, it is created  with  access  permissions
given by the "mode" argument.    The access permissions for the file or
directory  are    specified  as a  combination  of bits  (defined in the
\<sys\stat.h> header file).

The following bits define permissions for the owner.

S_IRWXU     Read, write, execute/search

S_IRUSR     Read permission

S_IWUSR     Write permission

S_IXUSR     Execute/search permission

The following bits define permissions for the group.

S_IRWXG     Read, write, execute/search

S_IRGRP     Read permission

S_IWGRP     Write permission

S_IXGRP     Execute/search permission

The following bits define permissions for others.

S_IRWXO     Read, write, execute/search

S_IROTH     Read permission

S_IWOTH     Write permission

S_IXOTH     Execute/search permission

The  following    bits define  miscellaneous  permissions  used by other
implementations.

S_IREAD     is equivalent to S_IRUSR (read permission)

S_IWRITE    is equivalent to S_IWUSR (write permission)

S_IEXEC     is equivalent to S_IXUSR (execute/search permission)

All  files  are  readable  with DOS; however, it is a good idea to set
S_IREAD when read permission is intended for the file.
::::CSCANF
#include \<conio.h>
int cscanf( const char *format, ... );

The cscanf  function scans input from the console under control of the
argument  "format". Following the format string is a list of addresses
to receive  values.   The cscanf  function uses the function getche to
read  characters  from the console.   The "format" string is described
under the description of the scanf function.
::::CTIME
#include \<time.h>
char *ctime( const time_t *timer );

The ctime function converts the calendar time pointed to by "timer" to
local time in the form of a string.  It is equivalent to

asctime( localtime( timer ) )

The ctime  function converts the time into a string containing exactly
26  characters.   This    string    has  the  form shown in the  following
example:

Sat Mar 21 15:58:27 1987\n\0

All fields have a constant width.  The new-line character '\n' and the
null character '\0' occupy the last two positions of the string.

The area  containing the returned string is re-used each time ctime is
called.
::::CWAIT
#include \<process.h>
int cwait( int *status, int process_id, int action );

The cwait  function  suspends the calling  process until the specified
child process terminates.

If  "status"  is not  NULL, it points to a word that will be filled in
with the  termination  status  word and return    code of the terminated
child process.

If the child  process  terminated normally, then the low order byte of
the status word will be set to 0, and the high order byte will contain
the low order byte of the return code that the child process passed to
the DOSEXIT  function.     The DOSEXIT  function is called whenever main
returns, or exit or _exit are explicity called.

If the child  process  did not terminate normally, then the high order
byte of the  status word will be set to 0, and the low order byte will
contain one of the following values:

1    Hard-error abort

2    Trap operation

3    SIGTERM signal not intercepted

The  "process_id"  argument specifies which child process to wait for.
This value is  returned by the call to the spawn function that started
the child process.

The  "action"  argument  specifies  when the  parent  process  resumes
execution.  The possible values are:

WAIT_CHILD      Wait until the specified child process has ended.

WAIT_GRANDCHILD   Wait until the  specified  child  process and all of
          the  child  processes  of  that  child  process have
          ended.
::::DELAY
#include \<dos.h>
void delay( unsigned milliseconds );

The  delay  function  suspends    execution by the  specified  number of
"milliseconds".
::::DIFFTIME
#include \<time.h>
double difftime( time_t time1, time_t time0 )

The  difftime  function  calculates  the  difference  between  the two
calendar times:

    time1 - time0
::::DIRECTORY
              Directory Functions
              ═══════════════════

These  functions  pertain  to directory  manipulation.     The following
functions are defined:

<chdir>     change current working directory
<closedir>    close opened directory file
<getcwd>    get current working directory
<mkdir>     make a new directory
<opendir>    open directory file
<readdir>    read file name from directory
<rmdir>     remove a directory
::::DIV
#include \<stdlib.h>
div_t div( int numer, int denom );

typedef struct {
    int quot;      /* quotient */
    int rem;      /* remainder */
} div_t;

The div function calculates the quotient and remainder of the division
of the numerator "numer" by the denominator "denom".
::::DOS
            DOS-Specific Functions
            ══════════════════════

These  functions  provide  the    capability  to    invoke    DOS  functions
directly from a program.  The following functions are defined:

<bdos>            DOS call (short form)
<dosexterr>        extract DOS error information
<_dos_allocmem>     allocate a block of memory
<_dos_close>        close a file
<_dos_creat>        create a file
<_dos_creatnew>     create a new file
<_dos_findfirst>    find first file matching a specified pattern
<_dos_findnext>     find the next file matching a specified pattern
<_dos_freemem>        free a block of memory
<_dos_getdate>        get current system date
<_dos_getdiskfree>  get information about disk
<_dos_getdrive>     get the current drive
<_dos_getfileattr>  get file attributes
<_dos_getftime>     get file's last modification time
<_dos_gettime>        get the current system time
<_dos_getvect>        get contents of interrupt vector
<_dos_keep>        install a terminate-and-stay-resident program
<_dos_open>        open a file
<_dos_read>        read data from a file
<_dos_setblock>     change the size of allocated block
<_dos_setdate>        change current system date
<_dos_setdrive>     change the current default drive
<_dos_setfileattr>  set the attributes of a file
<_dos_setftime>     set a file's last modification time
<_dos_settime>        set the current system time
<_dos_setvect>        set an interrupt vector
<_dos_write>        write data to a file
<intdos>        cause DOS interrupt
<intdosx>        cause DOS interrupt, with segment registers
::::DOSEXTERR
#include \<dos.h>
int dosexterr( struct DOSERROR *err_info );

struct DOSERROR {
    int exterror;    /* contents of AX register */
    char class;    /* contents of BH register */
    char action;    /* contents of BL register */
    char locus;    /* contents of CH register */
};

The dosexterr function extracts extended error information following a
failed DOS  function.    This  information  is placed in the  structure
located by  "err_info".  This function is only useful with DOS version
3.0 or later.

You should  consult the  technical documentation for the DOS system on
your computer for an interpretation of the error information.
::::DUP
#include \<io.h>
int dup( int handle );

The dup  function  duplicates  the file  handle  given by the argument
"handle".  The new file  handle refers to the same open file handle as
the original file handle, and shares any locks.    The new file handle
is  identical  to the  original in that it references the same file or
device, it has the same open mode (read and/or write) and it will have
file position identical to the original.    Changing the position with
one handle will result in a changed position in the other.
::::DUP2
#include \<io.h>
int dup2( int handle, int handle2 );

The  dup2  function  duplicates  the file handle given by the argument
"handle".  The new file handle is identical to the original in that it
references  the same  file or  device, it has the same open mode (read
and/or write) and it will have identical file position to the original
(changing  the    position  with    one  handle  will  result in a changed
position in the other).

The number of the new handle is "handle2". If a file already is opened
with  this  handle,  the  file    is closed  before the  duplication  is
attempted.
::::ECVT
#include \<stdlib.h>
char *ecvt( double value,
        int ndigits,
        int *dec,
        int *sign );

The ecvt function  converts the  floating-point  number "value" into a
character  string.   The parameter  "ndigits"  specifies the number of
significant digits desired.    The converted number will be rounded to
"ndigits" of precision.

The  character    string will contain only digits and is terminated by a
null  character.   The    integer  pointed to by "dec" will be filled in
with a value  indicating the position of the decimal point relative to
the start of the string of digits.  A zero or negative value indicates
that the  decimal  point  lies to the left of the  first  digit.   The
integer pointed to by "sign" will contain 0 if the number is positive,
and non-zero if the number is negative.
::::ENVIRONMENT
              Process Environment
              ═══════════════════

These  functions  deal    with process  identification,  process groups,
system     identification,   system  time,  environment  variables,  and
terminal identification.  The following functions are defined:

<clearenv>    delete environment variables
<getcmd>    get command line
<getpid>    return process ID of calling process
<getenv>    get environment variable value
<isatty>    determine  if  file   descriptor   associated  with  a
        terminal
<putenv>    add, change or delete environment variable
<_searchenv>    search for a file in list of directories
<setenv>    add, change or delete environment variable
<time>        get current calendar time
::::EOF
#include \<io.h>
int eof( int handle );

The eof function determines, at the operating system level, if the end
of the file has been  reached  for the file whose file handle is given
by  "handle".  Because the current file  position is set  following an
input  operation,  the eof function may be called to detect the end of
the  file  before  an  input  operation  beyond the end of the file is
attempted.
::::EXEC
#include \<process.h>
int execl(   path, arg0, arg1..., argn, NULL );
int execle(  path, arg0, arg1..., argn, NULL, envp );
int execlp(  file, arg0, arg1..., argn, NULL );
int execlpe( file, arg0, arg1..., argn, NULL, envp );
int execv(   path, argv );
int execve(  path, argv, envp );
int execvp(  file, argv );
int execvpe( file, argv, envp );
  const char *path;        /* file name incl. path */
  const char *file;        /* file name        */
  const char *arg0, ..., *argn; /* arguments        */
  char *const argv[];        /* array of arguments    */
  char *const envp[];        /* environment strings    */

The exec  functions  load and  execute a new child  process,  named by
"path"    or  "file". If the child  process is  successfully  loaded, it
replaces  the  current    process  in memory.   No return is made to the
original program.

The program is located by using the following logic in sequence:

   1. An attempt is made to locate the    program in the current working
      directory  if no    directory  specification  precedes the program
      name; otherwise, an attempt is made in the specified directory.

   2. If no file  extension  is  given, an attempt is made to find the
      program  name, in the  directory    indicated  in the first point,
      with .COM concatenated to the end of the program name.

   3. If no file  extension  is  given, an attempt is made to find the
      program  name, in the  directory    indicated  in the first point,
      with .EXE concatenated to the end of the program name.

   4. When no  directory specification is given as part of the program
      name, the execlp,  execlpe,  execvp, and execvpe    functions will
      repeat the  preceding  three  steps for each of the  directories
      specified by the PATH environment variable.  The command

      path c:\myapps;d:\lib\applns

      indicates that the two directories

      c:\myapps
      d:\lib\applns

      are to be searched.  The DOS path command (without any directory
      specification)  will  cause  the current path  definition  to be
      displayed.

An error is detected when the program cannot be found.

Arguments  are passed to the child  process by    supplying  one or more
pointers  to  character strings as arguments in the exec call.     These
character  strings are    concatenated  with spaces inserted to separate
the arguments to form one argument string for the child process.   The
length of this    concatenated  string must not exceed 128 bytes in real
mode.

The  arguments    may be passed as a list of  arguments  (execl, execle,
execlp,  and  execlpe)    or as a  vector of  pointers  (execv,  execve,
execvp, and  execvpe).     At least one  argument,  "arg0" or "argv[0]",
must  be  passed  to the child    process.   By  convention,  this first
argument is a pointer to the name of the program.

If the arguments are passed as a list, there must be a NULL pointer to
mark  the end of the  argument    list.    Similarly,  if a pointer to an
argument vector is passed, the argument vector must be terminated by a
NULL pointer.

The  environment  for the invoked program is inherited from the parent
process  when you use the execl,  execlp, execv, and execvp functions.
The execle,  execlpe,  execve, and execvpe functions allow a different
environment  to be  passed  to the child  process  through  the "envp"
argument.    The argument "envp" is a pointer to an array of character
pointers,  each of which  points to a string  defining    an environment
variable.   The array is terminated with a NULL pointer.  Each pointer
locates a character string of the form

    variable=value

that  is  used    to define an  environment  variable.   If the value of
"envp" is NULL, then the child process inherits the environment of the
parent process.

The  environment  is the  collection  of environment  variables  whose
values have been defined with the DOS SET command or by the successful
execution  of the putenv  function.   A program  may read these values
with the getenv function.

The execvpe and execlpe functions are extensions to POSIX 1003.1.
::::EXECL
 ->EXEC
::::EXECLE
 ->EXEC
::::EXECLP
 ->EXEC
::::EXECLPE
 ->EXEC
::::EXECV
 ->EXEC
::::EXECVE
 ->EXEC
::::EXECVP
 ->EXEC
::::EXECVPE
 ->EXEC
::::EXIT
#include \<stdlib.h>
void exit( int status );

The exit function causes normal program termination to occur.

First, all  functions  registered by the atexit function are called in
the  reverse  order of their  registration.   Next, all open files are
flushed  and closed, and all files created by the tmpfile function are
removed.  Finally, the low-order byte of "status" is made available to
the parent  process.   The  "status"  value is    typically  set to 0 to
indicate  successful  termination  and    set to    some  other  value  to
indicate an error.
::::EXP
#include \<math.h>
double exp( double x );

The  exp function  computes the  exponential  function of "x". A range
error occurs if the magnitude of "x" is too large.
::::FABS
#include \<math.h>
double fabs( double x );

The fabs function computes the absolute value of the argument "x".
::::FCLOSE
#include \<stdio.h>
int fclose( FILE *fp );

The fclose  function  closes the file "fp". If there was any unwritten
buffered  data for the    file, it is  written  out  before  the file is
closed.   Any unread  buffered    data is discarded.   If the associated
buffer was automatically allocated, it is deallocated.
::::FCLOSEALL
#include \<stdio.h>
int fcloseall( void );

The  fcloseall    function  closes all open stream  files, except stdin,
stdout,  stderr,  stdaux, and stdprn.    This includes  streams created
(and not yet closed) by fdopen, fopen and freopen.
::::FCVT
#include \<stdlib.h>
char *fcvt( double value,
        int ndigits,
        int *dec,
        int *sign );

The fcvt function  converts the  floating-point  number "value" into a
character  string.   The parameter  "ndigits"  specifies the number of
digits desired after the decimal point.   The converted number will be
rounded to this position.

The  character    string will contain only digits and is terminated by a
null  character.   The    integer  pointed to by "dec" will be filled in
with a value  indicating the position of the decimal point relative to
the start of the string of digits.  A zero or negative value indicates
that the  decimal  point  lies to the left of the  first  digit.   The
integer pointed to by "sign" will contain 0 if the number is positive,
and non-zero if the number is negative.
::::FDOPEN
#include \<stdio.h>
FILE *fdopen( int handle, const char *mode );

The fdopen  function associates a stream with the file handle "handle"
which represents an opened file or device.  The handle was returned by
one of creat, dup, dup2 or open.   The open mode "mode" must match the
mode with which the file or device was originally opened.

The  argument  "mode"  is  described in the  description  of the fopen
function.
::::FEOF
#include \<stdio.h>
int feof( FILE *fp );

The  feof  function  tests the    end-of-file  indicator    for the stream
pointed  to by    "fp".  Because    this  indicator  is set  when an input
operation  attempts to read past the end of the file the feof function
will  detect the end of the file only after an attempt is made to read
beyond    the end of the    file.    Thus, if a file contains 10 lines, the
feof will not detect end of file after the tenth line is read; it will
detect end of file once the program attempts to read more data.
::::FERROR
#include \<stdio.h>
int ferror( FILE *fp );

The ferror  function  tests the error indicator for the stream pointed
to by "fp".
::::FFLUSH
#include \<stdio.h>
int fflush( FILE *fp );

If the    file  "fp" is open for output or update,  the fflush  function
causes any unwritten data to be written to the file.  If the file "fp"
is open for input or update,  the fflush function undoes the effect of
any preceding ungetc operation on the stream.  If the value of "fp" is
NULL, then all files that are open will be flushed.
::::FGETC
#include \<stdio.h>
int fgetc( FILE *fp );

The fgetc function gets the next character from the file designated by
"fp". The character is signed.
::::FGETCHAR
#include \<stdio.h>
int fgetchar( void );

The fgetchar function is equivalent to fgetc with the argument stdin.
::::FGETPOS
#include \<stdio.h>
int fgetpos( FILE *fp, fpos_t *pos );

The  fgetpos  function stores the current position of the file "fp" in
the  object  pointed  to by  "pos". The value  stored is usable by the
fsetpos  function  for    repositioning  the file to its position at the
time of the call to the fgetpos function.
::::FGETS
#include \<stdio.h>
char *fgets( char *buf, size_t n, FILE *fp );

The  fgets  function  gets  a  string  of  characters  from  the  file
designated  by "fp" and stores    them in the array pointed to by "buf".
The  fgets  function  stops  reading  characters  when    end-of-file is
reached, or when a newline character is read, or when "n-1" characters
have been read, whichever comes first.     The new-line character is not
discarded.   A null  character    is placed  immediately    after the last
character read into the array.

The gets is similar to fgets  except  that it  operates with stdin, it
has no size argument and it replaces a newline character with the null
character.
::::FILE
              File Manipulation Functions
              ═══════════════════════════

These functions operate directly with files.   The following functions
are defined:

<access>    test file or directory for mode of access
<chmod>     change permissions for a file
<remove>    delete a file
<rename>    rename a file
<stat>        get file status
<tmpnam>    create name for temporary file
<utime>     set modification time for a file
::::FILELENGTH
#include \<io.h>
long int filelength( int handle );

The filelength function returns the number of bytes in the opened file
indicated by the file handle "handle".
::::FILENO
#include \<stdio.h>
int fileno( FILE *stream );

The fileno function returns the number of the file handle for the file
designated by "stream".
::::FLOOR
#include \<math.h>
double floor( double x );

The floor function computes the largest integer not greater than "x".
::::FLUSHALL
#include \<stdio.h>
int flushall( void );

The flushall function clears all buffers associated with input streams
and writes any buffers associated with output streams.      A subsequent
read  operation  on an input  file causes new data to be read from the
associated file or device.

The  function  is equivalent to calling the fflush for all open stream
files.
::::FMOD
#include \<math.h>
double fmod( double x, double y );

The fmod function computes the floating-point remainder of "x/y," even
if the quotient "x/y" is not representable.
::::FOPEN
#include \<stdio.h>
FILE *fopen( const char *filename, const char *mode );

The fopen  function opens the file whose name is the string pointed to
by "filename," and associates a stream with it.    The argument "mode"
points to a string beginning with one of the following sequences:

"r"   open file for reading; use default file translation

"w"   create file for writing, or truncate to zero length; use default
      file translation

"a"   append:    open text file or create for  writing at  end-of-file;
      use default file translation

"rb"  open binary file for reading

"rt"  open text file for reading

"wb"  create binary file for writing, or truncate to zero length

"wt"  create text file for writing, or truncate to zero length

"ab"  append; open binary file or create for writing at end-of-file

"at"  append; open text file or create for writing at end-of-file

"r+"  open file for update  (reading and/or writing); use default file
      translation

"w+"  create  file for update, or truncate to zero length; use default
      file translation

"a+"  append;  open file or create for update, writing at end-of-file;
      use default file translation

"r+b" open binary file for update (reading and/or writing)

"r+t" open text file for update (reading and/or writing)

"w+b" create binary file for update, or truncate to zero length

"w+t" create text file for update, or truncate to zero length

"a+b" append;  open  binary  file  or  create for  update,  writing at
      end-of-file

"a+t" append;  open  text  file  or  create  for  update,  writing  at
      end-of-file

"rb+" open binary file for update (reading and/or writing)

"rt+" open text file for update (reading and/or writing)

"wb+" create binary file for update, or truncate to zero length

"wt+" create text file for update, or truncate to zero length

"ab+" append;  open  binary  file  or  create for  update,  writing at
      end-of-file

"at+" append;  open  text  file  or  create  for  update,  writing  at
      end-of-file

When default file  translation    is  specified, the value of the global
variable _fmode establishes whether the file is to treated as a binary
or a text  file.   Unless  this value is changed by the  program,  the
default will be text mode.

Opening  a file  with  read  mode ( 'r' as the    first character in the
"mode"    argument)  fails  if the  file    does not exist or it cannot be
read.  Opening a file with append mode ( 'a' as the first character in
the "mode"  argument)  causes all  subsequent writes to the file to be
forced to the current end-of-file, regardless of previous calls to the
fseek function.    When a file is opened with update mode ( '+' as the
second    or  third  character of the "mode"  argument),    both input and
output may be performed on the associated stream.
::::FP_OFF
#include \<dos.h>
unsigned FP_OFF( void __far *far_ptr );

The FP_OFF  macro can be used to obtain the offset  portion of the far
pointer value given in "far_ptr".
::::FP_SEG
#include \<dos.h>
unsigned FP_SEG( void __far *far_ptr );

The FP_SEG  macro can be used to obtain the segment portion of the far
pointer value given in "far_ptr".
::::FPRINTF
#include \<stdio.h>
int fprintf( FILE *fp, const char *format, ... );

The  fprintf  function    writes    output to the file  pointed to by "fp"
under  control    of the    argument  "format".  The  "format"  string  is
described under the description of the printf function.
::::FPUTC
#include \<stdio.h>
int fputc( int c, FILE *fp );

The fputc  function writes the character specified by the argument "c"
to the output stream designated by "fp".
::::FPUTCHAR
#include \<stdio.h>
int fputchar( int c );

The fputchar  function    writes the character specified by the argument
"c" to the output stream stdout.

The function is equivalent to:

    fputc( c, stdout );
::::FPUTS
#include \<stdio.h>
int fputs( const char *buf, FILE *fp );

The fputs  function writes the character string pointed to by "buf" to
the output  stream  designated by "fp". The terminating null character
is not written.
::::FREAD
#include \<stdio.h>
size_t fread( void *buf,
          size_t elsize,
          size_t nelem,
          FILE *fp );

The fread  function reads "nelem" elements of "elsize" bytes each from
the file specified by "fp" into the buffer specified by "buf".
::::FREE
#include \<stdlib.h>
void free( void *ptr );

When the value of the  argument  "ptr" is NULL, the free function does
nothing  otherwise,  the free  function  deallocates  the memory block
located  by  the  argument  "ptr"  which  points  to  a  memory  block
previously  allocated  through    a call    to calloc,  malloc or realloc.
After the call, the freed block is available for allocation.

In a large data  memory  model, the free function is equivalent to the
_ffree    function;  in a small data  memory model, the free function is
equivalent to the _nfree function.
::::FREOPEN
#include \<stdio.h>
FILE *freopen( const char *filename,
           const char *mode,
           FILE *fp );

The stream located by the fp pointer is closed.   The freopen function
opens the file whose name is the string  pointed to by "filename," and
associates a stream with it.   The stream information is placed in the
structure located by the "fp" pointer.

The  argument  "mode"  is  described in the  description  of the fopen
function.
::::FREXP
#include \<math.h>
double frexp( double value, int *exp );

The frexp  function  breaks a  floating-point number into a normalized
fraction and an integral power of 2.   It stores the integral power of
2 in the "int" object pointed to by "exp".
::::FSCANF
#include \<stdio.h>
int fscanf( FILE *fp, const char *format, ... );

The fscanf function scans input from the file designated by "fp" under
control of the argument  "format".  Following  the format  string is a
list of addresses to receive values.  The "format" string is described
under the description of the scanf function.
::::FSEEK
#include \<stdio.h>
int fseek( FILE *fp, long int offset, int where );

The  fseek  function  changes  the  read/write    position  of the  file
specified by "fp". This  position  defines the    character that will be
read or written on the next I/O operation on the file.      The argument
"fp" is a file    pointer  returned  by fopen or freopen.   The argument
"offset" is the position to seek to relative to one of three positions
specified by the argument "where". Allowable values for "where" are:

SEEK_SET       The new file position is computed relative to the start
           of  the    file.     The  value  of  "offset"  must not be
           negative.

SEEK_CUR       The  new file  position    is  computed  relative    to the
           current    file  position.   The value of "offset" may be
           positive, negative or zero.

SEEK_END       The new file  position  is computed relative to the end
           of the file.

The  fseek function  clears the  end-of-file  indicator and undoes any
effects of the ungetc function on the same file.

The ftell  function  can be used to obtain the current position in the
file  before  changing it.   The position can be restored by using the
value returned by ftell in a subsequent call to fseek with the "where"
parameter set to SEEK_SET.
::::FSETPOS
#include \<stdio.h>
int fsetpos( FILE *fp, fpos_t *pos );

The fsetpos function positions the file "fp" according to the value of
the object  pointed to by "pos," which shall be a value returned by an
earlier call to the fgetpos function on the same file.
::::FSTAT
#include \<sys\types.h>
#include \<sys\stat.h>
int fstat( int handle, struct stat *buf );

The fstat  function  obtains information about an open file whose file
handle    is  "handle".  This  information  is  placed in the  structure
located at the address indicated by "buf".

The file \<sys\stat.h> contains definitions for the structure stat.

struct stat {
   dev_t   st_dev;    /* disk drive file resides on */
   ino_t   st_ino;    /* this inode's number        */
   unsigned short st_mode; /* file mode         */
   short   st_nlink;  /* # of hard links        */
   short   st_uid;    /* user-id, always 'root'     */
   short   st_gid;    /* group-id, always 'root'    */
   dev_t   st_rdev;   /* drive #, same as st_dev    */
   off_t   st_size;   /* total file size        */
   time_t  st_atime;  /* time of last access        */
   time_t  st_mtime;  /* time of last modification  */
   time_t  st_ctime;  /* time of last status change */
};

::::FTELL
#include \<stdio.h>
long int ftell( FILE *fp );

The ftell function returns the current read/write position of the file
specified by "fp". This  position  defines the    character that will be
read or  written  by the next I/O  operation  on the file.   The value
returned by ftell can be used in a subsequent call to fseek to set the
file to the same position.
::::FTIME
#include \<sys\timeb.h>
void ftime( struct timeb *timeptr );

struct timeb {
 time_t time;  /* time in seconds since Jan 1, 1970 UTC */
 unsigned short millitm; /* milliseconds */
 short timezone; /* difference in minutes from UTC */
 short dstflag;  /* nonzero if in daylight savings time */
};

The  ftime  function  gets  the  current  time    and  stores  it in the
structure pointed to by "timeptr".
::::FWRITE
#include \<stdio.h>
size_t fwrite( const void *buf,
           size_t elsize,
           size_t nelem,
           FILE *fp );

The fwrite  function writes "nelem" elements of "elsize" bytes each to
the file specified by "fp".
::::GCVT
#include \<stdlib.h>
char *gcvt( double value,
        int ndigits,
        char *buffer );

The gcvt function  converts the  floating-point  number "value" into a
character  string  and    stores the result in "buffer".    The  parameter
"ndigits"  specifies the number of significant    digits    desired.   The
converted number will be rounded to this position.

If the    exponent  of the  number is less than -4 or is greater than or
equal to the number of    significant  digits wanted, then the number is
converted  into  E-format,  otherwise  the  number is formatted  using
F-format.
::::GETC
#include \<stdio.h>
int getc( FILE *fp );

The getc  function gets the next character from the file designated by
"fp". The character is returned as an int value.  The getc function is
equivalent to fgetc, except that it may be implemented as a macro.
::::GETCH
#include \<conio.h>
int getch( void );

The  getch  function  obtains the next    available  keystroke  from the
console.   Nothing is echoed on the screen (the  function  getche will
echo the keystroke, if possible).  When no keystroke is available, the
function waits until a key is depressed.

The  kbhit  function  can be  used  to    determine  if a  keystroke  is
available.
::::GETCHAR
#include \<stdio.h>
int getchar( void );

The getchar function is equivalent to getc with the argument stdin.
::::GETCHE
#include \<conio.h>
int getche( void );

The getche  function  obtains the next    available  keystroke  from the
console.  The function will wait until a keystroke is available.  That
character  is echoed on the screen at the  position of the cursor (use
getch when it is not desired to echo the keystroke).

The  kbhit  function  can be  used  to    determine  if a  keystroke  is
available.
::::GETCMD
#include \<process.h>
char *getcmd( char *cmd_line );

The  getcmd  function  causes the command line    information,  with the
program name  removed, to be copied to    "cmd_line". The information is
terminated with a '\0' character.  This provides a method of obtaining
the original  parameters  to a program unchanged (with the white space
intact).

This  information  can    also  be  obtained by examining  the vector of
program parameters passed to the main function in the program.
::::GETCWD
#include \<direct.h>
char *getcwd( char *buffer, int size );

The getcwd function returns the name of the current working directory.
The  "buffer"  address is either  NULL or is the  location  at which a
string containing the name of the current working directory is placed.
In the latter  case, the value of "size" is the length    (including the
delimiting '\0' character) which can be be used to store this name.

When  "buffer"    has a value of NULL, a string is  allocated to contain
the name of the current working directory.    This string may be freed
using the free function.
::::GETENV
#include \<stdlib.h>
char *getenv( const char *name );

The  getenv  function  searches  the  environment  list  for an  entry
matching   the    string     pointed  to  by  "name".   The   matching  is
case-insensitive;  all    lower-case letters are treated as if they were
in upper case.

Entries  can be added to the environment list with the DOS set command
or  with  the  putenv  or  setenv  functions.     All  entries  in  the
environment list can be displayed by using the DOS set command with no
arguments.

To assign a string to a variable and place it in the environment list:

    C>SET INCLUDE=C:\WATCOM\H

To see what  variables    are in the environment list, and their current
assignments:

    C>SET
    COMSPEC=C:\COMMAND.COM
    PATH=C:\;C:\WATCOM
    INCLUDE=C:\WATCOM\H

    C>
::::GETPID
#include \<process.h>
int getpid(void);

The getpid function returns the process id for the current process.
::::GETS
#include \<stdio.h>
char *gets( char *buf );

The gets function gets a string of characters from the file designated
by stdin  and  stores  them in the  array  pointed  to by "buf"  until
end-of-file  is  encountered  or a  new-line  character is read.   Any
new-line  character  is  discarded,  and a null  character  is    placed
immediately after the last character read into the array.

It is  recommended  that fgets be used    instead of gets  because  data
beyond the array  "buf" will be  destroyed  if a new-line character is
not read from the input stream stdin before the end of the array "buf"
is reached.
::::GMTIME
#include \<time.h>
struct tm *gmtime( const time_t *timer );

struct    tm {
  int tm_sec;    /* seconds after the minute -- [0,61] */
  int tm_min;    /* minutes after the hour   -- [0,59] */
  int tm_hour;    /* hours after midnight     -- [0,23] */
  int tm_mday;    /* day of the month        -- [1,31] */
  int tm_mon;    /* months since January     -- [0,11] */
  int tm_year;    /* years since 1900              */
  int tm_wday;    /* days since Sunday        -- [0,6]  */
  int tm_yday;    /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag */
};

The gmtime  function  converts the calendar time pointed to by "timer"
into a broken-down time, expressed as Coordinated Universal Time (UTC)
(formerly known as Greenwich Mean Time (GMT)).

The time set on the  computer  with the DOS time  command  and the DOS
date command reflects the local time.    The environment variable TZ is
used to establish the time zone to which this local time applies.  See
the section The TZ Environment Variable for a discussion of how to set
the time zone.
::::HALLOC
#include \<malloc.h>
void __huge *halloc( long int numb, size_t size );

The halloc  function allocates space for an array of "numb" objects of
"size" bytes each and initializes each object to 0.   When the size of
the array is greater than 128K bytes, the size must be a power of 2.
::::HEAP
                Heap Functions
                ══════════════

These  functions  provide  the ability to shrink and grow the heap, as
well as, find heap  related  problems.    The  following    functions  are
defined:

<_heapchk>    perform consistency check on the heap
<_fheapchk>    perform consistency check on the far heap
<_nheapchk>    perform consistency check on the near heap
<_heapgrow>    grow the heap
<_fheapgrow>    grow the far heap
<_nheapgrow>    grow the near heap up to its limit of 64K
<_heapmin>    shrink the heap as small as possible
<_fheapmin>    shrink the far heap as small as possible
<_nheapmin>    shrink the near heap as small as possible
<_heapset>    fill unallocated sections of heap with pattern
<_fheapset>    fill unallocated sections of far heap with pattern
<_nheapset>    fill unallocated sections of near heap with pattern
<_heapshrink>    shrink the heap as small as possible
<_fheapshrink>    shrink the far heap as small as possible
<_nheapshrink>    shrink the near heap as small as possible
<_heapwalk>    walk through each entry in the heap
<_fheapwalk>    walk through each entry in the far heap
<_nheapwalk>    walk through each entry in the near heap
::::HFREE
#include \<malloc.h>
void hfree( void __huge *ptr );

The hfree function  deallocates a memory block previously allocated by
the halloc function.    The argument "ptr" points to a memory block to
be  deallocated.   After  the  call, the freed block is available  for
allocation.
::::HYPOT
#include \<math.h>
double hypot( double x, double y );

The hypot  function  computes  the length of the hypotenuse of a right
triangle  whose  sides are "x" and "y"    adjacent  to that right angle.
The calculation is equivalent to

    sqrt( x*x + y*y )

The  computation  may  cause an  overflow,  in which case the  matherr
function will be invoked.
::::INP
#include \<conio.h>
unsigned int inp( int port );

The inp function reads one byte from the hardware port whose number is
given by "port".

A  hardware  port is used to  communicate  with a device.   One or two
bytes can be read  and/or  written  from each port, depending upon the
hardware.   Consult the technical  documentation  for your computer to
determine the port numbers for a device and the expected usage of each
port for a device.
::::INPW
#include \<conio.h>
unsigned int inpw( int port );

The inpw  function  reads a word (two  bytes)  from the  hardware port
whose number is given by "port".

A  hardware  port is used to  communicate  with a device.   One or two
bytes can be read  and/or  written  from each port, depending upon the
hardware.   Consult the technical  documentation  for your computer to
determine the port numbers for a device and the expected usage of each
port for a device.
::::INT386
#include \<dos.h>
int int386( int inter_no,
       const union REGS *in_regs,
       union REGS *out_regs );

The int386  function  causes the computer's central processor (CPU) to
be  interrupted with an interrupt whose number is given by "inter_no".
This function is present in the 386 C libraries and may be executed on
80386/486 systems.  Before the interrupt, the CPU registers are loaded
from the structure  located by "in_regs". Following the interrupt, the
structure located by "out_regs" is filled with the contents of the CPU
registers.   These  structures    may be located at the same location in
memory.

You should consult the technical  documentation  for the computer that
you are using to determine  the expected  register contents before and
after the interrupt in question.
::::INT386X
#include \<dos.h>
int int386x( int inter_no,
         const union REGS *in_regs,
         union REGS *out_regs,
         struct SREGS *seg_regs );

The int386x  function causes the computer's central processor (CPU) to
be  interrupted with an interrupt whose number is given by "inter_no".
This function is present in the 386 C libraries and may be executed on
80386/486 systems.  Before the interrupt, the CPU registers are loaded
from  the  structure  located by  "in_regs"  and the DS, ES, FS and GS
segment registers are loaded from the structure located by "seg_regs".
Following the interrupt, the structure located by "out_regs" is filled
with the contents of the CPU registers.   The "in_regs" and "out_regs"
structures  may be  located  at the  same  location  in memory.    The
original values of the DS, ES, FS and GS registers are restored.   The
structure  "seg_regs"  is  updated  with  the  values  of the  segment
registers following the interrupt.

You should consult the technical  documentation  for the computer that
you are using to determine  the expected  register contents before and
after the interrupt in question.
::::INT86
#include \<dos.h>
int int86( int inter_no,
       const union REGS *in_regs,
       union REGS *out_regs );

The int86 function causes the computer's central processor (CPU) to be
interrupted  with  an interrupt  whose number is given by  "inter_no".
Before the  interrupt, the CPU registers are loaded from the structure
located by "in_regs".  Following the interrupt, the structure  located
by "out_regs" is filled with the contents of the CPU registers.  These
structures may be located at the same location in memory.

You should consult the technical  documentation  for the computer that
you are using to determine  the expected  register contents before and
after the interrupt in question.
::::INT86X
#include \<dos.h>
int int86x( int inter_no,
        const union REGS *in_regs,
        union REGS *out_regs,
        struct SREGS *seg_regs );

The int86x  function  causes the computer's central processor (CPU) to
be  interrupted with an interrupt whose number is given by "inter_no".
Before the  interrupt, the CPU registers are loaded from the structure
located by  "in_regs"  and the DS and ES segment  registers are loaded
from the structure located by "seg_regs". Following the interrupt, the
structure located by "out_regs" is filled with the contents of the CPU
registers.   The "in_regs" and "out_regs" structures may be located at
the same  location  in memory.     The  original values of the DS and ES
registers are restored.   The structure "seg_regs" is updated with the
values of the segment registers following the interrupt.

You should consult the technical  documentation  for the computer that
you are using to determine  the expected  register contents before and
after the interrupt in question.
::::INTDOS
#include \<dos.h>
int intdos( const union REGS *in_regs,
        union REGS *out_regs );

The intdos  function  causes the computer's central processor (CPU) to
be  interrupted with an interrupt number hexadecimal 21 ( 0x21), which
is a request to invoke a specific DOS function.  Before the interrupt,
the CPU  registers are loaded from the structure located by "in_regs".
The AH register  contains a number  indicating the function requested.
Following the interrupt, the structure located by "out_regs" is filled
with  the  contents of the CPU    registers.   These  structures    may be
located at the same location in memory.

You should  consult the  technical documentation for the DOS operating
system that you are using to determine    the expected register contents
before and after the interrupt in question.
::::INTDOSX
#include \<dos.h>
int intdosx( const union REGS *in_regs,
         union REGS *out_regs,
         struct SREGS *seg_regs );

The intdosx  function causes the computer's central processor (CPU) to
be  interrupted with an interrupt number hexadecimal 21 ( 0x21), which
is a request to invoke a specific DOS function.  Before the interrupt,
the CPU  registers  are loaded from the structure located by "in_regs"
and the  segment  registers  DS and ES are loaded  from the  structure
located by  "seg_regs".  The AH register  contains a number indicating
the  function  requested.   Following  the  interrupt,    the  structure
located  by  "out_regs"  is  filled  with  the    contents  of  the  CPU
registers.   The "in_regs" and "out_regs" structures may be located at
the same  location  in memory.     The original values for the DS and ES
registers are restored.   The structure "seg_regs" is updated with the
values of the segment registers following the interrupt.

You should  consult the  technical documentation for the DOS operating
system that you are using to determine    the expected register contents
before and after the interrupt in question.
::::INTEL
          Intel 80x86 Architecture-Specific Functions
          ═══════════════════════════════════════════

These    functions   provide  the  capability  to  invoke  Intel  80x86
processor-related functions directly from a program.    Functions that
apply to the Intel 8086 CPU apply to that  family including the 80286,
80386 and 80486 processors.  The following functions are defined:

<_chain_intr>    chain to the previous interrupt handler
<_disable>    disable interrupts
<_enable>    enable interrupts
<FP_OFF>    get offset part of far pointer
<FP_SEG>    get segment part of far pointer
<inp>        get one byte from hardware port
<inpw>        get two bytes (one word) from hardware port
<int386>    cause 386/486 CPU interrupt
<int386x>    cause 386/486 CPU interrupt, with segment registers
<int86>     cause 8086 CPU interrupt
<int86x>    cause 8086 CPU interrupt, with segment registers
<intr>        cause 8086 CPU interrupt, with segment registers
<MK_FP>     make a far pointer from the segment and offset values
<nosound>    turn off the speaker
<outp>        write one byte to hardware port
<outpw>     write two bytes (one word) to hardware port
<segread>    read segment registers
<sound>     turn on the speaker at specified frequency
::::INTR
#include \<dos.h>
void intr( int inter_no, union REGPACK *regs );

The intr  function causes the computer's central processor (CPU) to be
interrupted  with  an interrupt  whose number is given by  "inter_no".
Before the  interrupt, the CPU registers are loaded from the structure
located by "regs".  Following the interrupt, the structure  located by
"regs" is filled with the contents of the CPU registers.

This  function is similar to the int86x function, except that only one
structure  is used for the register values and that the BP (EBP in 386
library)  register is included in the set of registers that are passed
and saved.

You should consult the technical  documentation  for the computer that
you are using to determine  the expected  register contents before and
after the interrupt in question.
::::ISALNUM
#include \<ctype.h>
int isalnum( int c );

The isalnum  tests if the argument "c" is an alphanumeric character (a
to z, A to Z, or 0 to 9).   An alphanumeric character is any character
for which isalpha or isdigit is true.
::::ISALPHA
#include \<ctype.h>
int isalpha( int c );

The isalpha tests for an alphabetic character (a to z and A to Z).  An
alphabetic  character is any character for which isupper or islower is
true.
::::ISASCII
#include \<ctype.h>
int isascii( int c );

The isascii function tests for a character in the range from 0 to 127.
::::ISATTY
#include \<io.h>
int isatty( int handle );

The isatty  function  tests if the opened file or device referenced by
the  file  handle  "handle"  is a  character  device  (for  example, a
console, printer or port).
::::ISCNTRL
#include \<ctype.h>
int iscntrl( int c );

The  iscntrl  function    tests  for any control    character.   A control
character is any character whose value is from 0 through 31.
::::ISDIGIT
#include \<ctype.h>
int isdigit( int c );

The isdigit function tests for any decimal-digit character '0' through
'9'.
::::ISGRAPH
#include \<ctype.h>
int isgraph( int c );

The isgraph function tests for any  printable  character  except space
(' ').     The  isprint  function  is  similar,  except  that  the space
character is also included in the character set being tested.
::::ISLOWER
#include \<ctype.h>
int islower( int c );

The islower function tests for any lower-case letter 'a' through 'z'.
::::ISPRINT
#include \<ctype.h>
int isprint( int c );

The isprint function tests for any printable character including space
(' ').      The  isgraph    function  is  similar,    except    that the space
character is excluded from the character set being tested.
::::ISPUNCT
#include \<ctype.h>
int ispunct( int c );

The ispunct  function  tests for any  punctuation  character such as a
comma (,) or a period (.).
::::ISSPACE
#include \<ctype.h>
int isspace( int c );

The isspace function tests for the following white-space characters:

' '      space
'\f'      form feed
'\n'      new-line or linefeed
'\r'      carriage return
'\t'      horizontal tab
'\v'      vertical tab
::::ISUPPER
#include \<ctype.h>
int isupper( int c );

The isupper function tests for any upper-case letter 'A' through 'Z'.
::::ISXDIGIT
#include \<ctype.h>
int isxdigit( int c );

The  isxdigit  function  tests    for any  hexadecimal-digit  character.
These characters are the digits ('0' through '9') and the letters ('a'
through 'f') and ('A' through 'F').
::::ITOA
#include \<stdlib.h>
char *itoa( int value, char *buffer, int radix );

The  itoa  function  converts  the  binary  integer  "value"  into the
equivalent  string in base "radix"  notation storing the result in the
character  array  pointed to by "buffer". A null character is appended
to the result.    The size of "buffer" must be at least (8 * sizeof(int)
+ 1) bytes when converting values in base 2.    That makes the size 17
bytes on 16-bit  machines,  and 33 bytes on 32-bit  machines.    If the
value of  "radix"  is 10 and "value" is negative, then a minus sign is
prepended to the result.
::::J0
 ->BESSEL
::::J1
 ->BESSEL
::::JN
 ->BESSEL
::::KBHIT
#include \<conio.h>
int kbhit( void );

The kbhit  function  tests  whether or not a  keystroke  is  currently
available.  When one is available, the function getch or getche may be
used to obtain the keystroke in question.

With  a   stand-alone  program,  the  kbhit  function  may  be    called
continuously until a keystroke is available.
::::LABS
#include \<stdlib.h>
long int labs( long int j );

The  labs  function  returns  the absolute  value of its  long-integer
argument "j".
::::LANG_HELP
                   WATCOM C
                   ════════

Select the topic about which you want help. Press F1 if you want
information on how to use the help system.

Help is available on the following categories of WATCOM C functions.

<allocation>        memory allocation
<bios>            BIOS services access
<character>        character manipulation
<console>        console level I/O operations
<conversion>        convert values from one representation to another
<directory>        directory services
<dos>            DOS-specific functions access
<environment>        process environment
<file>            file manipulation
<graphics>        graphics
<heap>            heap management
<intel>         Intel 80x86 processor-related functions
<math>            mathematical and trigonometric functions
<memory>        memory block manipulation
<miscellaneous>     remaining functions
<multibyte>        multibyte and wide characters manipulation
<operating>        operating system level file operations
<process>        process primitive functions
<searching>        searching and sorting capabilities
<stream>        standard functions to read and write files
<string>        string manipulation
<time>            obtain and manipulate times and dates
<variable>        process variable numbers of arguments
::::LDEXP
#include \<math.h>
double ldexp( double x, int exp );

The ldexp  function  multiplies a floating-point number by an integral
power of 2.  A range error may occur.
::::LDIV
#include \<stdlib.h>
ldiv_t ldiv( long int numer, long int denom );

typedef struct {
    long int quot;     /* quotient */
    long int rem;      /* remainder */
} ldiv_t;

The  ldiv  function  calculates  the  quotient    and  remainder    of the
division of the numerator "numer" by the denominator "denom".
::::LFIND
#include \<search.h>
char *lfind( char *key,       /* object to search for  */
         char *base,      /* base of search data   */
         unsigned *num,   /* number of elements    */
         unsigned width,  /* width of each element */
         int (*compare)( const void *element1,
                 const void *element2 ) );

The lfind function performs a linear search for the value "key" in the
array  of "num"  elements  pointed to by "base".  Each    element of the
array is "width" bytes in size.    The argument "compare" is a pointer
to a  user-supplied  routine that will be called by lfind to determine
the  relationship  of an  array  element  with    the  "key". One of the
arguments  to the "compare" function will be an array element, and the
the other will be "key".

The  "compare"    function should return 0 if "element1" is identical to
"element2" and non-zero if the elements are not identical.
::::LOCALECONV
#include \<locale.h>
struct lconv *localeconv( void );

The  localeconv  function  sets  the  components  of an object of type
struct lconv with values  appropriate  for the    formatting  of numeric
quantities  according to the current  locale.    The  components of the
struct lconv and their meanings are as follows:

char *decimal_point
      The  decimal-point  character  used to  format  non-monetary
      quantities.

char *thousands_sep
      The  character used to separate groups of digits to the left
      of the  decimal-point  character  in formatted  non-monetary
      quantities.

char *grouping
      A string  whose  elements indicate the size of each group of
      digits in formatted non-monetary quantities.

char *int_curr_symbol
      The  international currency symbol applicable to the current
      locale.    The first three characters contain the alphabetic
      international  currency  symbol  in  accordance  with  those
      specified  in ISO  4217  Codes  for  the  Representation  of
      Currency  and  Funds.   The  fourth  character  (immediately
      preceding  the  null    character)  is the  character  used to
      separate the international currency symbol from the monetary
      quantity.

char *currency_symbol
      The local currency symbol applicable to the current locale.

char *mon_decimal_point
      The    decimal-point    character  used  to  format   monetary
      quantities.

char *mon_thousands_sep
      The  character used to separate groups of digits to the left
      of  the   decimal-point   character  in  formatted  monetary
      quantities.

char *mon_grouping
      A string  whose  elements indicate the size of each group of
      digits in formatted monetary quantities.

char *positive_sign
      The  string used to indicate a  nonnegative-valued  monetary
      quantity.

char *negative_sign
      The  string  used  to  indicate a  negative-valued  monetary
      quantity.

char int_frac_digits
      The number of  fractional  digits (those to the right of the
      decimal-point)   to  be  displayed  in  an   internationally
      formatted monetary quantity.

char frac_digits
      The number of  fractional  digits (those to the right of the
      decimal-point)  to  be  displayed  in a  formatted  monetary
      quantity.

char p_cs_precedes
      Set to 1 or 0 if the    currency_symbol  respectively precedes
      or follows the value for a  nonnegative  formatted  monetary
      quantity.

char p_sep_by_space
      Set to 1 or 0 if the    currency_symbol  respectively is or is
      not  separated  by a space from the value for a  nonnegative
      formatted monetary quantity.

char n_cs_precedes
      Set to 1 or 0 if the    currency_symbol  respectively precedes
      or  follows  the  value  for a negative  formatted  monetary
      quantity.

char n_sep_by_space
      Set to 1 or 0 if the    currency_symbol  respectively is or is
      not  separated  by a space  from the    value  for a  negative
      formatted monetary quantity.

char p_sign_posn
      The  position  of  the   positive_sign   for    a  nonnegative
      formatted monetary quantity.

char n_sign_posn
      The position of the  positive_sign  for a negative formatted
      monetary quantity.

The elements of grouping and mon_grouping are interpreted according to
the following:

CHAR_MAX    No further grouping is to be performed.

0        The  previous  element  is to be  repeatedly  used for the
        remainder of the digits.

other        The  value    is the    number    of digits  that  comprise  the
        current group.   The next element is examined to determine
        the size of the next  group of  digits  to the left of the
        current group.

The value of p_sign_posn and n_sign_posn is interpreted as follows:

0      Parentheses surround the quantity and currency_symbol.

1      The sign string precedes the quantity and currency_symbol.

2      The sign string follows the quantity and currency_symbol.

3      The  sign   string   immediately   precedes  the  quantity  and
       currency_symbol.

4      The  sign   string   immediately   follows   the  quantity  and
       currency_symbol.
::::LOCALTIME
#include \<time.h>
struct tm *localtime( const time_t *timer );

struct    tm {
  int tm_sec;    /* seconds after the minute -- [0,61] */
  int tm_min;    /* minutes after the hour   -- [0,59] */
  int tm_hour;    /* hours after midnight     -- [0,23] */
  int tm_mday;    /* day of the month        -- [1,31] */
  int tm_mon;    /* months since January     -- [0,11] */
  int tm_year;    /* years since 1900              */
  int tm_wday;    /* days since Sunday        -- [0,6]  */
  int tm_yday;    /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag */
};

The  localtime    function  converts  the  calendar  time  pointed to by
"timer" into a structure of type tm, of time information, expressed as
local time.

The  calendar  time is usually    obtained  by using the time  function.
That  time is  Coordinated  Universal  Time (UTC)  (formerly  known as
Greenwich Mean Time (GMT)).

The time set on the  computer  with the DOS time  command  and the DOS
date command reflects the local time.    The environment variable TZ is
used to establish the time zone to which this local time applies.  See
the section The TZ Environment Variable for a discussion of how to set
the time zone.
::::LOCK
#include \<io.h>
int lock( int handle,
      unsigned long offset,
      unsigned long nbytes );

The lock function locks "nbytes" amount of data in the file designated
by  "handle"  starting    at byte  "offset" in the file.     This prevents
other  processes  from reading or writing into the locked region until
an  unlock  has  been done for this  locked  region of the file.   All
locked regions of a file must be unlocked before a file is closed.
::::LOCKING
#include \<sys\locking.h>
int locking( int handle, int mode, long nbyte );

The  locking  function    locks  or  unlocks  "nbyte"  bytes of the file
specified  by  "handle".  Locking  a region of a file  prevents  other
processes  from reading or writing the locked  region until the region
has  been  unlocked.   The  locking and  unlocking  takes place at the
current file position.    The argument "mode" specifies the action to be
performed.  The possible values for mode are:

LK_LOCK        Locks the specified region.  The function will retry to
           lock  the  region   after  1  second   intervals  until
           successful or until 10 attempts have been made.

LK_RLCK        Same action as LK_LOCK.

LK_NBLCK       Non-blocking  lock:   makes  only 1 attempt to lock the
           specified region.

LK_NBRLCK      Same action as LK_NBLCK.

LK_UNLCK       Unlocks    the  specified    region.   The region must have
           been previously locked.

Multiple  regions of a file can be locked,  but no overlapping regions
are allowed.   You cannot  unlock  multiple  regions in the same call,
even  if the regions are  contiguous.    All locked  regions  should be
unlocked  before  closing  a file  or  exiting    the program.   Locking
requires  MS-DOS Version 3.0 or later, and that SHARE.COM or SHARE.EXE
is installed.
::::LOG
#include \<math.h>
double log( double x );

The log  function  computes  the  natural logarithm (base e) of "x". A
domain error occurs if the argument is negative.  A range error occurs
if the argument is zero.
::::LOG10
#include \<math.h>
double log10( double x );

The log10  function  computes the logarithm (base 10) of "x". A domain
error occurs if the argument is negative.  A range error occurs if the
argument is zero.
::::LOG2
#include \<math.h>
double log2( double x );

The log2  function  computes  the  logarithm (base 2) of "x". A domain
error occurs if the argument is negative.  A range error occurs if the
argument is zero.
::::LONGJMP
#include \<setjmp.h>
void longjmp( jmp_buf env, int return_value );

The longjmp function restores the environment saved by the most recent
call to the setjmp function with the corresponding jmp_buf argument.
::::LSEARCH
#include \<search.h>
char *lsearch( char *key,      /* object to search for */
           char *base,     /* base of search data  */
           unsigned *num,  /* number of elements   */
           unsigned width, /* width of each element*/
           int (*compare)( const void *element1,
                   const void *element2 ) );

The  lsearch  function performs a linear search for the value "key" in
the array of "num"  elements pointed to by "base". Each element of the
array is "width" bytes in size.    The argument "compare" is a pointer
to a user-supplied routine that will be called by lsearch to determine
the  relationship  of an  array  element  with    the  "key". One of the
arguments  to the "compare" function will be an array element, and the
the other will be "key".

The  "compare"    function should return 0 if "element1" is identical to
"element2" and non-zero if the elements are not identical.
::::LSEEK
#include \<io.h>
#include \<stdio.h>
long int lseek( int handle, long int offset, int whence );

The lseek  function  sets the current file  position at the  operating
system level.     The file is referenced using the file handle "handle"
returned  by a    successful  execution  of one of the creat, dup, dup2,
open or sopen functions.   The value of "offset" is used as a relative
offset    from a file  position  determined by the value of the argument
"whence".

The new file  position    is  determined    in a manner dependent upon the
value of "whence" which may have one of three possible values (defined
in the \<stdio.h> header file):

SEEK_SET       The new file position is computed relative to the start
           of  the    file.     The  value  of  "offset"  must not be
           negative.

SEEK_CUR       The  new file  position    is  computed  relative    to the
           current    file  position.   The value of "offset" may be
           positive, negative or zero.

SEEK_END       The new file  position  is computed relative to the end
           of the file.

An error will occur if the requested file position is before the start
of the file.

The  requested    file  position may be beyond the end of the file.   If
data is later  written at this    point, subsequent reads of data in the
gap  will  return  bytes  whose  value    is equal to zero until data is
actually written in the gap.

The lseek function does not, in itself, extend the size of a file (see
the description of the chsize function).
::::LTOA
#include \<stdlib.h>
char *ltoa( long int value,
        char *buffer,
        int radix );

The  ltoa  function  converts  the  binary  integer  "value"  into the
equivalent  string in base "radix"  notation storing the result in the
character  array  pointed to by "buffer". A null character is appended
to the    result.   The size of  "buffer" must be at least 33 bytes when
converting  values  in    base 2.   If the  value of  "radix"  is 10 and
"value" is negative, then a minus sign is prepended to the result.
::::MAIN
int main( void );
int main( int argc, const char *argv[] );

The function main is a    user-supplied function where program execution
begins.   The command line to the program is broken into a sequence of
tokens    separated  by  blanks  and  are  passed to main as an array of
pointers to character  strings in the  parameter "argv". The number of
arguments  found is passed in the  parameter "argc". The first element
of  "argv"  will be a pointer to a  character  string  containing  the
program name.  The last element of the array pointed to by "argv" will
be a NULL pointer (i.e.    "argv[argc]" will be NULL).    Arguments that
contain  blanks can be passed to main by  enclosing them within double
quote  characters  (which  are removed from that element in the "argv"
vector.

The command line arguments can also be obtained in its original format
by using the getcmd function.
::::MALLOC
#include \<stdlib.h>
void *malloc( size_t size );

The malloc  function  allocates  space for an object of "size"    bytes.
Nothing is allocated when the "size" argument has a value of zero.

In a small data memory model, the malloc function is equivalent to the
_nmalloc  function; in a large data memory  model, the malloc function
is equivalent to the _fmalloc function.
::::MATH
                Math Functions
                ══════════════

These  functions  operate  with  objects of type double, also known as
floating-point numbers.    The Intel 8087 processor (and its successor
chips)    is  commonly  used to implement  floating-point  operations on
personal computers.  Functions ending in "87" pertain to this specific
hardware  and  should be isolated in programs  when  portability  is a
consideration.    The following functions are defined:

<abs>        absolute value of an object of type int
<acos>        arccosine
<acosh>     inverse hyperbolic cosine
<asin>        arcsine
<asinh>     inverse hyperbolic sine
<atan>        arctangent of one argument
<atan2>     arctangent of two arguments
<atanh>     inverse hyperbolic tangent
<bessel>    bessel functions j0, j1, jn, y0, y1, and yn
<cabs>        absolute value of complex number
<ceil>        ceiling function
<_clear87>    clears floating-point status
<_control87>    sets new floating-point control word
<cos>        cosine
<cosh>        hyperbolic cosine
<div>        compute  quotient,  remainder  from division of an int
        object
<exp>        exponential function
<fabs>        absolute value of double
<floor>     floor function
<fmod>        modulus function
<_fpreset>    initializes for floating-point operations
<frexp>     fractional exponent
<hypot>     compute hypotenuse
<j0> <j1> <jn>    return Bessel functions of the first kind
<labs>        absolute value of an object of type long int
<ldexp>     multiply by a power of two
<ldiv>        get  quotient,    remainder  from  division of object of
        type long int
<log>        natural logarithm
<log10>     logarithm, base 10
<log2>        logarithm, base 2
<matherr>    handles error from math functions
<max>        return maximum of two arguments
<min>        return minimum of two arguments
<modf>        get integral, fractional parts of double
<pow>        raise to power
<rand>        random integer
<sin>        sine
<sinh>        hyperbolic sine
<sqrt>        square root
<srand>     set starting  point for  generation  of random numbers
        using rand function
<_status87>    gets floating-point status
<tan>        tangent
<tanh>        hyperbolic tangent
<y0> <y1> <yn>    return Bessel functions of the second kind
::::MATHERR
#include \<math.h>
int matherr( struct exception *err_info );

The  matherr  function    is invoked  each time an error is  detected by
functions in the math library.     The default matherr function supplied
in the    library  returns  zero    which  causes  an error  message to be
displayed  upon  stderr and errno to be set with an  appropriate error
value.     An  alternative  version  of  this  function can be provided,
instead of the    library  version, in order that the error handling for
mathematical errors can be handled by an application.

A program  may    contain a  user-written version of matherr to take any
appropriate action when an error is detected.    When zero is returned,
an error  message will be printed upon stderr and errno will be set as
was  the case with the    default  function.   When a non-zero  value is
returned, no message is printed and errno is not changed.    The value
err_info->retval is used as the return value for the function in which
the error was detected.

The  matherr  function    is  passed a pointer to an  structure  of type
struct    exception  which contains information about the error that has
been detected:

struct exception
{ int type;     /* TYPE OF ERROR         */
  char *name;     /* NAME OF FUNCTION         */
  double arg1;     /* FIRST ARGUMENT TO FUNCTION     */
  double arg2;     /* SECOND ARGUMENT TO FUNCTION  */
  double retval; /* DEFAULT RETURN VALUE     */
};

The type field will contain one of the following values:

DOMAIN           A domain error has occurred, such as sqrt(-1e0).

SING           A singularity will result, such as pow(0e0,-2).

OVERFLOW       An overflow will result, such as pow(10e0,100).

UNDERFLOW      An underflow will result, such as pow(10e0,-100).

TLOSS           Total  loss  of     significance  will  result,  such  as
           exp(1000).

PLOSS           Partial    loss  of  significance    will  result,  such as
           sin(10e70).

The name field    points to a string containing the name of the function
which detected the error.  The fields arg1 and arg2 (if required) give
the  values  which  caused the error.    The field retval  contains the
value  which  will be  returned  by the  function.   This value may be
changed by a user-supplied version of the matherr function.
::::MAX
#include \<stdlib.h>

The max  macro    will evaluate to be the greater of two values.     It is
implemented as follows.

#define max(a,b)  (((a) > (b)) ? (a) : (b))
::::MBLEN
#include \<stdlib.h>
int mblen( const char *s, size_t n );

The  mblen  function  determines  the number of bytes  comprising  the
multibyte  character pointed to by "s". At most "n" bytes of the array
pointed to by "s" will be examined.
::::MBSTOWCS
#include \<stdlib.h>
size_t mbstowcs( wchar_t *pwcs,const char *s,size_t n );

The  mbstowcs  function  converts  a sequence of multibyte  characters
pointed to by "s" into their  corresponding  wide  character codes and
stores    not  more than "n" codes into the array  pointed to by "pwcs".
The mbstowcs function does not convert any multibyte characters beyond
the null character.    At most "n" elements of the array pointed to by
"pwcs" will be modified.
::::MBTOWC
#include \<stdlib.h>
int mbtowc( wchar_t *pwc, const char *s, size_t n );

The mbtowc  function  converts a single multibyte character pointed to
by "s" into the wide character code that corresponds to that multibyte
character.  The code for the null character is zero.  If the multibyte
character is valid and "pwc" is not a NULL pointer, the code is stored
in the    object    pointed  to by    "pwc".    At most "n" bytes of the array
pointed to by "s" will be examined.
::::MEMCCPY
#include \<string.h>
void *memccpy( void *dest, const void *src,
           int c, unsigned cnt );
void __far *_fmemccpy( void __far *dest,
               const void __far *src,
               int c, unsigned cnt );

The memccpy and _fmemccpy functions copy bytes from "src" to "dest" up
to and    including  the first  occurrence of the character "c" or until
"cnt" bytes have been copied, whichever comes first.

The _fmemccpy function is a data model independent form of the memccpy
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::MEMCHR
#include \<string.h>
void *memchr( const void *buf,
          int ch,
          size_t length );
void __far *_fmemchr( const void __far *buf,
              int ch,
              size_t length );

The memchr and _fmemchr  functions locate the first occurrence of "ch"
(converted  to an unsigned  char) in the first    "length" characters of
the object pointed to by "buf".

The  _fmemchr  function is a data model independent form of the memchr
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::MEMCMP
#include \<string.h>
int memcmp( const void *s1,
        const void *s2,
        size_t length );
int _fmemcmp( const void __far *s1,
          const void __far *s2,
          size_t length );

The  memcmp  and  _fmemcmp   functions     compare  the  first  "length"
characters  of the object  pointed to by "s1" to the object pointed to
by "s2".

The  _fmemcmp  function is a data model independent form of the memcmp
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::MEMCPY
#include \<string.h>
void *memcpy( void *dst,
          const void *src,
          size_t length );
void __far *_fmemcpy( void __far *dst,
              const void __far *src,
              size_t length );

The memcpy and _fmemcpy  functions copy "length"  characters  from the
buffer    pointed  to by    "src"  into  the  buffer  pointed to by "dst".
Copying of  overlapping  objects is not  guaranteed  to work properly.
See the memmove function if you wish to copy objects that overlap.

The  _fmemcpy  function is a data model independent form of the memcpy
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::MEMICMP
#include \<string.h>
int memicmp( const void *s1,
         const void *s2,
         size_t length );
int _fmemicmp( const void __far *s1,
           const void __far *s2,
           size_t length );

The memicmp and _fmemicmp  functions  compare, with case insensitivity
(upper- and lower-case    characters are equivalent), the first "length"
characters  of the object  pointed to by "s1" to the object pointed to
by "s2".

The _fmemicmp function is a data model independent form of the memicmp
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::MEMMOVE
#include \<string.h>
void *memmove( void *dst,
           const void *src,
           size_t length );
void __far *_fmemmove( void __far *dst,
               const void __far *src,
               size_t length );

The memmove and _fmemmove  functions copy "length" characters from the
buffer    pointed to by "src" to the buffer pointed to by "dst". Copying
of  overlapping  objects will take place properly.   See the memcpy or
_fmemcpy functions to copy objects that do not overlap.

The _fmemmove function is a data model independent form of the memmove
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::MEMORY
             Memory Manipulation Functions
             ═════════════════════════════

These  functions  manipulate  blocks  of  memory.   In    each case, the
address  of the  memory  block and its size is passed to the function.
The  functions    that  begin  with "_f"    accept far  pointers  as their
arguments  allowing  manipulation of any memory location regardless of
which memory model your program has been compiled for.     The following
functions are defined:

<_fmemccpy>    copy far memory block up to a certain character
<_fmemchr>    search far memory block for a character value
<_fmemcmp>    compare any two memory blocks (near or far)
<_fmemcpy>    copy far memory block, overlap not allowed
<_fmemicmp>    compare far memory, case insensitive
<_fmemmove>    copy far memory block, overlap allowed
<_fmemset>    set any memory block (near of far) to a character
<memccpy>    copy memory block up to a certain character
<memchr>    search memory block for a character value
<memcmp>    compare memory blocks
<memcpy>    copy memory block, overlap not allowed
<memicmp>    compare memory, case insensitive
<memmove>    copy memory block, overlap allowed
<memset>    set memory block to a character
<movedata>    copy memory block, with segment information
<swab>        swap bytes of a memory block

See also <string>  (string manipulation functions) for descriptions of
functions that manipulate strings of data.
::::MEMSET
#include \<string.h>
void *memset( void *s,
          int c,
          size_t length );
void __far *_fmemset( void __far *s,
              int c,
              size_t length );

The memset and _fmemset  functions  fill the first "length" characters
of the object pointed to by "s" with the value "c".

The  _fmemset  function is a data model independent form of the memset
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::MIN
#include \<stdlib.h>

The min  macro    will  evaluate to be the lesser of two values.     It is
implemented as follows.

#define min(a,b)  (((a) < (b)) ? (a) : (b))
::::MISCELLANEOUS
            Miscellaneous Functions
            ═══════════════════════

The following functions are defined:

<assert>    test an assertion
<_fullpath>    return full path specification for file
<_harderr>    critical error handler
<_hardresume>    critical error handler resume
<localeconv>    obtain locale specific conversion information
<longjmp>    return and restore environment saved by setjmp
<_lrotl>    rotate an unsigned long left
<_lrotr>    rotate an unsigned long right
<main>        the main program (user written)
<offsetof>    get offset of field in structure
<_rotl>     rotate an unsigned int left
<_rotr>     rotate an unsigned int right
<setjmp>    save environment for use with longjmp function
<_makepath>    make a full filename from specified components
<setlocale>    set locale category
<_splitpath>    split a filename into its components
::::MK_FP
#include \<dos.h>
void __far *MK_FP( unsigned int segment,
           unsigned int offset );

The MK_FP  macro can be used to obtain the far    pointer value given by
the  "segment"    segment  value and the "offset"  offset value.     These
values may be obtained by using the FP_SEG and FP_OFF macros.
::::MKDIR
#include \<sys\types.h>
#include \<direct.h>
int mkdir( const char *path );

The mkdir  function  creates a new  subdirectory with name "path". The
"path" can be either  relative    to the current working directory or it
can be an absolute path name.
::::MKTIME
#include \<time.h>
time_t mktime( struct tm *timeptr );

struct    tm {
  int tm_sec;    /* seconds after the minute -- [0,61] */
  int tm_min;    /* minutes after the hour   -- [0,59] */
  int tm_hour;    /* hours after midnight     -- [0,23] */
  int tm_mday;    /* day of the month        -- [1,31] */
  int tm_mon;    /* months since January     -- [0,11] */
  int tm_year;    /* years since 1900              */
  int tm_wday;    /* days since Sunday        -- [0,6]  */
  int tm_yday;    /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag */
};

The  mktime  function  converts  the  local  time  information    in the
structure  pointed to by "timeptr"  into a calendar  time (Coordinated
Universal Time) with the same encoding used by the time function.  The
original  values of the fields    tm_sec,  tm_min, tm_hour, tm_mday, and
tm_mon are not restricted to ranges described for struct tm.  If these
fields are not in their  proper ranges, they are adjusted so that they
are in the proper ranges.    Values for the fields tm_wday and tm_yday
are computed after all the other fields have been adjusted.
::::MODF
#include \<math.h>
double modf( double value, double *iptr );

The  modf  function  breaks  the  argument  "value" into  integral and
fractional parts, each of which has the same sign as the argument.  It
stores    the  integral  part  as a  double in the object  pointed to by
"iptr".
::::MOVEDATA
#include \<string.h>
void movedata( unsigned int src_segment,
           unsigned int src_offset,
           unsigned int tgt_segment,
           unsigned int tgt_offset,
           size_t length );

The  movedata  function  copies  "length"  bytes  from the far pointer
calculated as (src_segment:src_offset) to a target location determined
as a far pointer (tgt_segment:tgt_offset).

Overlapping  data may not be  correctly  copied.   When the source and
target areas may overlap, copy the areas one character at a time.

The  function  is useful to move data when the near address(es) of the
source and/or target areas are not known.
::::MULTIBYTE
             Multibyte Character Functions
             ═════════════════════════════

These ANSI C functions    provide  capabilities for processing multibyte
characters.  The following functions are defined:

<mblen>     determine length of next multibyte character
<mbstowcs>    convert  multibyte  character string to wide character
        string
<mbtowc>    convert multibyte character to wide character
<wcstombs>    convert wide character    string to multibyte  character
        string
<wctomb>    convert wide character to multibyte character
::::NOSOUND
#include \<dos.h>
void nosound( void );

The nosound function turns off the PC's speaker.
::::OFFSETOF
#include \<stddef.h>
size_t offsetof( composite, name );

The offsetof macro returns the offset of the element "name" within the
structure or union  "composite".  This    provides a portable  method to
determine the offset.     The macro may not be used to initialize data;
it can only be used with executable statements.
::::ONEXIT
#include \<stdlib.h>
onexit_t onexit( onexit_t func )

The onexit  function  is passed the  address of  function "func" to be
called    when the program  terminates  normally.   Successive  calls to
onexit create a list of functions that will be executed on a "last-in,
first-out"  basis.   No more than 32  functions can be registered with
the onexit function.

The functions have no parameters and do not return values.

NOTE:  The onexit function is not an ANSI function.  The ANSI standard
function  atexit  does the same thing that  onexit  does and should be
used instead of onexit where ANSI portability is concerned.
::::OPEN
#include \<sys\types.h>
#include \<sys\stat.h>
#include \<fcntl.h>
int open( const char *path, int access, ... );

The open  function  opens a file at the  operating system level.   The
name of the file to be    opened    is given by  "path".  The file will be
accessed  according  to the  access  mode  specified by "access".  The
optional  argument is the file permissions to be used when the O_CREAT
flag is on in the "access" mode.

The access  mode is  established  a combination of the bits defined in
\<fcntl.h> header file.  The following bits may be set:

O_RDONLY    permit the file to be only read.

O_WRONLY    permit the file to be only written.

O_RDWR        permit the file to be both read and written.

O_APPEND    causes  each  record  that is written to be written at the
        end of the file.

O_CREAT     has no  effect  when  the  file  indicated    by  "filename"
        already exists; otherwise, the file is created;

O_TRUNC     causes  the file to be  truncated  to contain no data when
        the  file  exists;    has no    effect    when the file does not
        exist.

O_BINARY    causes  the file to be  opened  in binary mode which means
        that  data    will  be  transmitted  to and  from  the  file
        unchanged.

O_TEXT        causes the file to be opened in text mode which means that
        carriage-return characters are written before any linefeed
        character  that  is  written  and  causes  carriage-return
        characters to be removed when encountered during reads.

When neither  O_TEXT nor O_BINARY are  specified, the default value in
the global  variable  _fmode is used to set the file translation mode.
When  the  program  begins  execution,    this  variable    has a value of
O_TEXT.

O_CREAT must be specified when the file does not exist and it is to be
written.

When the file is to be created ( O_CREAT is  specified), an additional
argument must be passed which contains the file permissions to be used
for the new file.   The access    permissions  for the file or directory
are  specified    as a  combination of bits (defined in the \<sys\stat.h>
header file).

The following bits define permissions for the owner.

S_IRWXU     Read, write, execute/search

S_IRUSR     Read permission

S_IWUSR     Write permission

S_IXUSR     Execute/search permission

The following bits define permissions for the group.

S_IRWXG     Read, write, execute/search

S_IRGRP     Read permission

S_IWGRP     Write permission

S_IXGRP     Execute/search permission

The following bits define permissions for others.

S_IRWXO     Read, write, execute/search

S_IROTH     Read permission

S_IWOTH     Write permission

S_IXOTH     Execute/search permission

The  following    bits define  miscellaneous  permissions  used by other
implementations.

S_IREAD     is equivalent to S_IRUSR (read permission)

S_IWRITE    is equivalent to S_IWUSR (write permission)

S_IEXEC     is equivalent to S_IXUSR (execute/search permission)

All  files  are  readable  with DOS; however, it is a good idea to set
S_IREAD when read permission is intended for the file.

The  open  function  applies the current file  permission  mask to the
specified permissions (see umask).
::::OPENDIR
#include \<sys\types.h>
#include \<direct.h>
DIR *opendir( const char *dirname );

The opendir function is used in conjunction with the functions readdir
and  closedir  to  obtain  the    list  of file names  contained    in the
directory  specified by "dirname". The path indicated by "dirname" can
be either  relative  to the  current working directory or it can be an
absolute  path    name.    The last part of  "dirname"  can  contain  the
characters '?' and '*' for matching multiple files.

The file \<direct.h> contains definitions for the structure dirent.

typedef struct dirent {
    char    d_dta[ 21 ];       /* disk transfer area */
    char    d_attr;           /* file's attribute */
    unsigned short int d_time; /* file's time */
    unsigned short int d_date; /* file's date */
    long    d_size;           /* file's size */
    char    d_name[ 13 ];      /* file's name */
    ino_t   d_ino;           /* serial number */
    char    d_first;           /* flag for 1st time */
} DIR;

More  than  one  directory  can  be read at the same  time  using  the
opendir, readdir, and closedir functions.
::::OPERATING
            Operating System I/O Functions
            ══════════════════════════════

These functions operate at the operating-system level and are included
for  compatibility  with other C  implementations.   It is recommended
that the  functions used in the section File Manipulation Functions be
used for new programs, as these functions are defined portably and are
part of the ANSI standard for the C language.

The functions in this section reference opened files and devices using
a file    handle    which is  returned when the file is opened.   The file
handle is passed to the other functions.

The following functions are defined:

<chsize>    change the size of a file
<close>     close file
<creat>     create a file
<dup>        duplicate file handle, get unused handle number
<dup2>        duplicate file handle, supply new handle number
<eof>        test for end of file
<filelength>    get file size
<fileno>    get file handle for stream file
<fstat>     get file status
<lock>        lock a section of a file
<locking>    lock/unlock a section of a file
<lseek>     set current file position
<open>        open a file
<read>        read a record
<setmode>    set file mode
<sopen>     open a file for shared access
<tell>        get current file position
<umask>     set file permission mask
<unlink>    delete a file
<unlock>    unlock a section of a file
<write>     write a record
::::OUTP
#include \<conio.h>
unsigned int outp( int port, int value );

The  outp  function  writes  one byte,    determined  by "value," to the
hardware port whose number is given by "port".

A  hardware  port is used to  communicate  with a device.   One or two
bytes can be read  and/or  written  from each port, depending upon the
hardware.   Consult the technical  documentation  for your computer to
determine the port numbers for a device and the expected usage of each
port for a device.
::::OUTPW
#include \<conio.h>
unsigned int outpw( int port,
            unsigned int value );

The outpw  function  writes a word (two bytes), determined by "value,"
to the hardware port whose number is given by "port".

A  hardware  port is used to  communicate  with a device.   One or two
bytes can be read  and/or  written  from each port, depending upon the
hardware.   Consult the technical  documentation  for your computer to
determine the port numbers for a device and the expected usage of each
port for a device.
::::PERROR
#include \<stdio.h>
void perror( const char *prefix );

The  perror  function  prints, on the file  designated    by stderr, the
error  message    corresponding  to the error number contained in errno.
The perror function is implemented as follows:

#include \<stdio.h>
void perror( const char *prefix )
{
    if( prefix != NULL ) {
    if( *prefix != '\0' ) {
        fprintf( stderr, "%s: ", prefix );
    }
    }
    fprintf( stderr, "%s\n", strerror( errno ) );
}
::::POW
#include \<math.h>
double pow( double x, double y );

The pow  function computes "x" raised to the power "y". A domain error
occurs if "x" is zero and "y" is less than or equal to 0, or if "x" is
negative and "y" is not an integer.  A range error may occur.
::::PRINTF
#include \<stdio.h>
int printf( const char *format, ... );

The printf  function  writes  output to the file  designated by stdout
under control of the argument "format".

Format Control String:

The format control string  consists of ordinary  characters, that are
written  exactly as they occur in the format  string,  and conversion
specifiers,  that  cause  argument  values  to be written as they are
encountered during the processing of the format string.   An ordinary
character in the format string is any character, other than a percent
character  (%),  that  is not  part of a  conversion  specifier.    A
conversion specifier is a sequence of characters in the format string
that  begins  with  a  percent    character  (%)    and is    followed,  in
sequence, by the following:

   * zero  or  more  format  control  flags that can modify the final
    effect of the format directive

   * an optional  decimal  integer, or an asterisk  character  ('*'),
    that  specifies  a minimum    field  width to be  reserved  for the
    formatted item

   * an  optional  precision  specification  in the  form of a period
    character  (.),  followed  by an optional  decimal    integer or an
    asterisk character (*)

   * an optional  type length  specification:    one of "h", "l", "L",
    "N" or "F"

   * a    character  that  specifies  the  type  of  conversion  to  be
    performed:    one of the characters "cdeEfFgGinopsuxX".

The valid format control flags are:

"-"  the formatted item is left-justified within the field; normally,
     items are right-justified

"+"  a    signed,  positive  object  will  always  start    with  a  plus
     character (+); normally, only negative items begin with a sign

" "  a    signed,  positive  object  will  always  start    with a    space
     character; if both "+" and "-" are specified, "+" overrides "-"

"#"  an alternate conversion form is used:

    * for "o"  (unsigned  octal)  conversions,  the  precision is
     incremented, if necessary, so that the first digit is "0".

    * for  "x"  or    "X"  (unsigned    hexadecimal)  conversions,  a
     non-zero value is prepended with "0x" or "0X" respectively

    * for  "e",  "E",  "f",  "g"  or  "G"  (any  floating  point)
     conversions,  the  result  always  contains a    decimal-point
     character,   even  if    no  digits  follow  it;  normally,  a
     decimal-point    character appears in the result only if there
     is a digit to follow it

    * in  addition    to the preceding, for "g" or "G" conversions,
     trailing zeros are not removed from the result

If no field width is specified, or if the value that is given is less
than the number of  characters in the converted value (subject to any
precision  value),  a  field  of  sufficient  width  to  contain  the
converted value is used.  If the converted value has fewer characters
than  are  specified  by the field  width, the value is padded on the
left (or right,  subject to the  left-justification flag) with spaces
or zero characters ("0").  If the field width begins with a zero, the
value  is  padded  with  zeros,  otherwise  the value is padded  with
spaces.   If  the  field  width  is "*", a value of type int from the
argument  list is used    (before a  precision argument or a conversion
argument) as the minimum field width.     A negative field width value
is  interpreted  as a left-justification flag, followed by a positive
field width.

As  with  the  field  width  specifier, a precision  specifier of "*"
causes a value of type int from the  argument  list to be used as the
precision specifier.   If no precision value is given, a precision of
0 is used.  The precision value affects the following conversions:

   * for "d", "i", "o", "u", "x" and "X"  (integer)  conversions, the
    precision specifies the minimum number of digits to appear

   * for   "e",   "E"  and  "f"   (fixed-precision,   floating-point)
    conversions,  the  precision  specifies  the  number of digits to
    appear after the decimal-point character

   * for   "g"     and   "G"    (variable-precision,    floating-point)
    conversions,  the  precision  specifies  the  maximum  number  of
    significant digits to appear

   * for  "s"  (string)  conversions,  the  precision  specifies  the
    maximum number of characters to appear

A type length specifier affects the conversion as follows:

   * "h" causes a "d", "i", "o", "u", "x" or "X" (integer) conversion
    to process a short int or  unsigned short int argument; note that
    although  the  argument  may  have been  promoted  as part of the
    function  call, the value is converted to the smaller type before
    it is converted

   * "h"  causes an "n" (converted  length  assignment)  operation to
    assign the    converted  length to an object of type unsigned short
    int

   * "l" causes a "d", "i", "o", "u", "x" or "X" (integer) conversion
    to process a long int or unsigned long int argument;

   * "l"  causes an "n" (converted  length  assignment)  operation to
    assign the    converted  length to an object of type    unsigned long
    int

   * "F" causes the pointer associated with "n", "p", "s" conversions
    to be treated as a far pointer;

   * "L"  causes an "e", "E", "f", "g", "G"  (double)  conversion  to
    process a long double argument;

   * "N" causes the pointer associated with "n", "p", "s" conversions
    to be treated as a near pointer;

The valid conversion type specifiers are:

c    An argument of type int is converted to a value of type char and
     the  corresponding ASCII character code is written to the output
     stream.

d, i An  argument  of  type  int is  converted    to a  signed  decimal
     notation  and  written  to  the  output  stream.     The  default
     precision    is 1, but if more  digits are required, leading zeros
     are added.

e, E An argument of type double is converted to a decimal notation in
     the form  [-]d.ddde[+|-]ddd  similar to FORTRAN  exponential (E)
     notation.     The  leading  sign  appears  (subject    to the format
     control  flags)  only  if the  argument  is  negative.    If the
     argument  is  non-zero,   the  digit  before  the    decimal-point
     character is non-zero.    The precision is used as the number of
     digits following the decimal-point character.   If the precision
     is not  specified,  a default precision of six is used.   If the
     precision is 0, the decimal-point character is suppressed.   The
     value is rounded to the appropriate number of digits.    For "E"
     conversions,  the exponent  begins with the character "E" rather
     than "e".     The  exponent    sign and a  three-digit  number (that
     indicates    the  power of ten by which the    decimal  fraction  is
     multiplied) are always produced.

f    An argument of type double is converted to a decimal notation in
     the form [-]ddd.ddd similar to FORTRAN fixed-point (F) notation.
     The leading sign appears  (subject to the format  control flags)
     only if the argument is negative.     The precision is used as the
     number of digits following the decimal-point character.   If the
     precision    is not specified, a default precision of six is used.
     If  the   precision  is  0,  the    decimal-point    character  is
     suppressed, otherwise, at least one digit is produced before the
     decimal-point   character.    The     value     is  rounded  to  the
     appropriate number of digits.

g, G An  argument of type double is converted using either the "f" or
     "e" (or "E", for a "G" conversion) style of conversion depending
     on the value of the  argument.   In either  case, the  precision
     specifies the number of significant digits that are contained in
     the result.    "e" style conversion is used only if the exponent
     from such a conversion would be less than -4 or greater than the
     precision.   Trailing  zeros are  removed    from the result and a
     decimal-point  character  only  appears if it is  followed  by a
     digit.

n    The number of  characters    that have been    written to the output
     stream is    assigned  to the  integer pointed to by the argument.
     No output is produced.

o    An  argument  of  type int is  converted  to an  unsigned    octal
     notation  and  written  to  the  output  stream.     The  default
     precision    is 1, but if more  digits are required, leading zeros
     are added.

p, P An  argument  of type void * is converted to a value of type int
     and  the  value  is   formatted   as  for    a  hexadecimal    ("x")
     conversion.

s    Characters from the string specified by an argument of type char
     *, up to,    but not  including  the  terminating  null  character
     ("\0"),  are  written to the output  stream.   If a precision is
     specified, no more than that many characters are written.

u    An  argument  of type int is  converted  to an  unsigned decimal
     notation  and  written  to  the  output  stream.     The  default
     precision    is 1, but if more  digits are required, leading zeros
     are added.

x, X An  argument of type int is converted to an unsigned hexadecimal
     notation  and  written  to  the  output  stream.     The  default
     precision    is 1, but if more  digits are required, leading zeros
     are added.  Hexadecimal notation uses the digits "0" through "9"
     and the characters "a" through "f" or "A" through "F" for "x" or
     "X"  conversions    respectively,  as  the    hexadecimal   digits.
     Subject  to the  alternate-form  control  flag,  "0x" or "0X" is
     prepended to the output.

Any  other  conversion type specifier  character,  including  another
percent  character  (%),  is  written  to the output  stream  with no
special interpretation.

The arguments must  correspond    with the conversion  type specifiers,
left to right in the string;  otherwise,  indeterminate  results will
occur.

For  example, a  specifier of the form "%8.*f" will define a field to
be at least 8 characters wide, and will get the next argument for the
precision to be used in the conversion.

The output from

printf( "f1 = %8.4f f2 = %10.2E x = %#08x i = %d",
    23.45,        3141.5926,     0x1db,     -1 );

would be

f1 =  23.4500 f2 =  3.14E+003 x = 0x0001db i = -1
::::PROCESS
              Process Primitive Functions
              ═══════════════════════════

These functions deal with process creation, execution and termination,
and signal handling.

When a new process is started, it may replace the existing process

   * P_OVERLAY is specified with the spawn...  functions

   * the exec...  routines are invoked

or the    existing  process  may be  suspended  while  the  new  process
executes (control continues at the point following the place where the
new process was started)

   * P_WAIT is specified with the spawn...  functions

   * system is used

The following functions are defined:

<abort>     immediate termination of process, return code 3
<atexit>    register exit routine
<_beginthread>    start a new thread of execution
<cwait>     wait for a child process to terminate
<delay>     delay for number of milliseconds
<_endthread>    end the current thread
<execl>     chain to program
<execle>    chain to program, pass environment
<execlp>    chain to program
<execlpe>    chain to program, pass environment
<execv>     chain to program
<execve>    chain to program, pass environment
<execvp>    chain to program
<execvpe>    chain to program, pass environment
<exit>        exit process, set return code
<_exit>     exit process, set return code
<onexit>    register exit routine
<raise>     signal an exceptional condition
<signal>    set handling for exceptional condition
<sleep>     delay for number of seconds
<spawnl>    create process
<spawnle>    create process, set environment
<spawnlp>    create process
<spawnlpe>    create process, set environment
<spawnv>    create process
<spawnve>    create process, set environment
<spawnvp>    create process
<spawnvpe>    create process, set environment
<system>    execute system command
<wait>        wait for any child process to terminate

There are eight spawn...    and exec...  functions each.  The "..." is
one to three letters:

   * "l" or "v" (one is  required)  to    indicate  the way the  process
    parameters are passed

   * "p" (optional) to indicate  whether the PATH environment variable
    is searched to locate the program for the process

   * "e"  (optional)  to indicate that the  environment  variables are
    being passed
::::PUTC
#include \<stdio.h>
int putc( int c, FILE *fp );

The putc function is equivalent to fputc, except it may be implemented
as a macro.    The putc function writes the character specified by the
argument "c" to the output stream designated by "fp".
::::PUTCH
#include \<conio.h>
int putch( int c );

The putch  function writes the character specified by the argument "c"
to the console.
::::PUTCHAR
#include \<stdio.h>
int putchar( int c );

The putchar  function  writes the  character specified by the argument
"c" to the output stream stdout.

The function is equivalent to

fputc( c, stdout );
::::PUTENV
#include \<process.h>
int putenv( const char *env_name );

The  environment  list consists of a number of environment names, each
of which has a value associated with it.   Entries can be added to the
environment list with the DOS set command or with the putenv function.
All  entries in the environment list can be displayed by using the DOS
set command with no arguments.     A program can obtain the value for an
environment variable by using the getenv function.

When the value of "env_name" has the format

    env_name=value

an  environment  name and its value is added to the  environment list.
When the value of "env_name" has the format

    env_name=

the environment name and value is removed from the environment list.

The matching is  case-insensitive;  all lower-case letters are treated
as if they were in upper case.

The space into which  environment names and their values are placed is
limited.   Consequently,  the  putenv  function can fail when there is
insufficient space remaining to store an additional value.

NOTE:    If the argument "env_name" is not a literal string, you should
duplicate  the    string,  since    putenv    does  not  copy the value; for
example,

    putenv( strdup( buffer ) );

To assign a string to a variable and place it in the environment list:

    C>SET INCLUDE=C:\WATCOM\H

To see what  variables    are in the environment list, and their current
assignments:

    C>SET
    COMSPEC=C:\COMMAND.COM
    PATH=C:\;C:\WATCOM
    INCLUDE=C:\WATCOM\H

    C>
::::PUTS
#include \<stdio.h>
int puts( const char *buf );

The puts  function  writes the character string pointed to by "buf" to
the  output  stream  designated  by  stdout,  and  appends  a new-line
character  to the  output.   The  terminating  null  character    is not
written.
::::QSORT
#include \<stdlib.h>
void qsort( void *base,
        size_t num,
        size_t width,
        int (*compar)
         ( const void *, const void *) );

The qsort  function sorts an array of "num" elements, which is pointed
to by "base," using Hoare's Quicksort algorithm.   Each element in the
array is "width" bytes in size.  The comparison function pointed to by
"compar"  is called  with two  arguments that point to elements in the
array.     The  comparison  function  shall return an integer less than,
equal  to, or greater  than zero if the first  argument  is less than,
equal to, or greater than the second argument.
::::RAISE
#include \<signal.h>
int raise( int condition );

The raise function  signals the exceptional condition indicated by the
"condition"  argument.     The  possible    conditions  are defined in the
\<signal.h>  header file and are  documented  with the signal function.
The signal function can be used to specify the action which is to take
place when such a condition occurs.
::::RAND
#include \<stdlib.h>
int rand( void );

The rand function computes a sequence of pseudo-random integers in the
range 0 to RAND_MAX (32767).  The sequence can be started at different
values by calling the srand function.
::::READ
#include \<io.h>
int read( int handle, char *buffer, int len );

The read  function  reads data at the  operating  system  level.   The
number    of  bytes  transmitted    is  given  by  "len"  and  the data is
transmitted starting at the address specified by "buffer".

The "handle" value is returned by the open function.   The access mode
must have  included  either  O_RDONLY or O_RDWR when the open function
was invoked.    The data is read starting at the current file position
for the file in question.    This file position can be determined with
the tell function and can be set with the lseek function.

When  O_BINARY is included in the access mode, the data is transmitted
unchanged.   When  O_TEXT is  included in the access mode, the data is
transmitted  with the extra carriage  return  character removed before
each linefeed character encountered in the original data.
::::READDIR
#include \<sys\types.h>
#include \<direct.h>
struct dirent *readdir( DIR *dirp );

The readdir  function obtains information about the next matching file
name  from  the  argument  "dirp".  The  argument  "dirp" is the value
returned  from    the  opendir  function.   The readdir  function can be
called    repeatedly  to obtain the list of file names  contained in the
directory  specified by the pathname  given to opendir.   The function
closedir  must    be called to close the    directory  and free the memory
allocated by opendir.

The file \<direct.h> contains definitions for the structure dirent.

typedef struct dirent {
    char    d_dta[ 21 ];       /* disk transfer area */
    char    d_attr;           /* file's attribute */
    unsigned short int d_time; /* file's time */
    unsigned short int d_date; /* file's date */
    long    d_size;           /* file's size */
    char    d_name[ 13 ];      /* file's name */
    ino_t   d_ino;           /* serial number */
    char    d_first;           /* flag for 1st time */
} DIR;

::::REALLOC
#include \<stdlib.h>
void * realloc( void *old_blk, size_t size );

When  the  value  of the  "old_blk"  argument  is NULL, a new block of
memory of "size" bytes is allocated.

If the value of "size" is zero,  realloc  calls the free  function  to
release the memory pointed to by "old_blk".

Otherwise,  the realloc  function  re-allocates space for an object of
"size" bytes by either:

   * shrinking    the  allocated    size  of the  allocated  memory  block
    "old_blk"  when  "size" is    sufficiently  smaller than the size of
    "old_blk".

   * extending    the  allocated    size  of the  allocated  memory  block
    "old_blk"  if there is a large  enough block of unallocated memory
    immediately following "old_blk".

   * allocating  a new block and  copying the contents of "old_blk" to
    the new block.

Because it is  possible  that a new block will be  allocated, no other
pointers  should point into the memory of  "old_blk".  These  pointers
will point to freed  memory, with  possible disastrous results, when a
new block is allocated.

The  memory  pointed  to by  "old_blk"    is not    freed  if it cannot be
re-allocated.

In a small data  memory  model, the  realloc function is equivalent to
the  _nrealloc    function;  in a  large data memory  model, the realloc
function is equivalent to the _frealloc function.
::::REMOVE
#include \<stdio.h>
int remove( const char *filename );

The remove  function deletes the file whose name is the string pointed
to by "filename".
::::RENAME
#include \<stdio.h>
int rename( const char *old, const char *new );

The rename  function  causes the file whose name is  indicated    by the
string "old" to be renamed to the name given by the string "new".
::::REWIND
#include \<stdio.h>
void rewind( FILE *fp );

The rewind  function  sets the file  position indicator for the stream
indicated to by "fp" to the beginning of the file.    It is equivalent
to

    fseek( fp, 0L, SEEK_SET );

except that the error indicator for the stream is cleared.
::::RMDIR
#include \<sys\types.h>
#include \<direct.h>
int rmdir( const char *path );

The rmdir function  removes  (deletes) the specified  directory.   The
directory must not contain any files or directories.    The "path" can
be either  relative  to the  current working directory or it can be an
absolute path name.
::::SBRK
#include \<stdlib.h>
void *sbrk( int increment );

The sbrk sets the "break" value for the program by adding the value of
"increment"  to the  current  break  value.    This  increment    may be
positive or negative.

The  "break"  value  is the  address of the first byte of  unallocated
memory.   When a program  starts  execution, the break value is placed
following  the code and  constant data for the program.   As memory is
allocated,  this  pointer  will  advance  when there is no freed block
large enough to satisfy an allocation request.

A new process started with one of the spawn...     or exec...  functions
is  loaded  following the break value.     Consequently,    decreasing the
break    value    leaves    more  space  available    to  the  new  process.
Similarly,  for a resident  program (a program which remains in memory
while another program executes), increasing the break value will leave
more  space  available to be allocated by the resident    program  after
other programs are loaded.
::::SCANF
#include \<stdio.h>
int scanf( const char *format, ... );

The scanf function scans input from the file designated by stdin under
control of the argument  "format".  Following the format string is the
list of addresses of items to receive values.
::::SEARCHING
              Searching Functions
              ═══════════════════

These  functions  provide  searching  and sorting  capabilities.   The
following functions are defined:

<bsearch>    find a data item in an array using binary search
<lfind>     find a data item in an array using linear search
<lsearch>    linear search array, add item if not found
<qsort>     sort an array
::::SEGREAD
#include \<dos.h>
void segread( struct SREGS *seg_regs );

The segread  function  places the values of the segment registers into
the structure located by "seg_regs".
::::SETBUF
#include \<stdio.h>
void setbuf( FILE *fp, char *buffer );

The setbuf  function  can be used to  associate a buffer with the file
designated  by "fp". If this function is used, it must be called after
the file has been opened and before it has been read or written.    If
the argument "buffer" is NULL, then all input/output for the file "fp"
will be completely unbuffered.     If the argument "buffer" is not NULL,
then it must point to an array that is at least  BUFSIZ  characters in
length, and all input/output will be fully buffered.
::::SETENV
#include \<env.h>
int setenv( const char *name,
        const char *newvalue,
        int overwrite );

The  environment  list consists of a number of environment names, each
of which has a value associated with it.   Entries can be added to the
environment list with the DOS set command or with the setenv function.
All  entries in the environment list can be displayed by using the DOS
set command with no arguments.     A program can obtain the value for an
environment variable by using the getenv function.

The setenv  function searches the environment list for an entry of the
form  "name=value". If no such string is present, setenv adds an entry
of the form  "name=newvalue"  to the environment list.     Otherwise, if
the  "overwrite"  argument is non-zero,  setenv either will change the
existing  value to  "newvalue"    or will delete the string "name=value"
and add the string "name=newvalue".

If  the   "newvalue"   pointer    is  NULL,  all    strings  of  the  form
"name=value" in the environment list will be deleted.

The  value  of the  pointer  environ  may change  across a call to the
setenv function.

The setenv  function  will make copies of the strings  associated with
"name" and "newvalue".

The matching is  case-insensitive;  all lower-case letters are treated
as  if    they  were in upper  case.   Entries  can also be added to the
environment list with the DOS set command or with the putenv or setenv
functions.   All  entries in the  environment  list can be obtained by
using the getenv function.

To assign a string to a variable and place it in the environment list:

    C>SET INCLUDE=C:\WATCOM\H

To see what  variables    are in the environment list, and their current
assignments:

    C>SET
    COMSPEC=C:\COMMAND.COM
    PATH=C:\;C:\WATCOM
    INCLUDE=C:\WATCOM\H

    C>
::::SETJMP
#include \<setjmp.h>
int setjmp( jmp_buf env );

The  setjmp  function  saves  its calling  environment    in its jmp_buf
argument, for subsequent use by the longjmp function.

In some  cases,  error    handling can be implemented by using setjmp to
record    the  point to which a return  will occur  following  an error.
When an error is  detected  in a called  function,  that function uses
longjmp to jump back to the recorded position.     The original function
which  called  setjmp must still be active (it cannot have returned to
the function which called it).

Special  care must be  exercised  to ensure that any side effects that
are  left  undone   (allocated     memory,   opened   files,  etc.)  are
satisfactorily handled.
::::SETLOCALE
#include \<locale.h>
char *setlocale( int category, const char *locale );

The  setlocale    function  selects  a  portion  of a  program's  locale
according to the category given by "category" and the locale specified
by "locale". A locale  affects the  collating  sequence  (the order in
which  characters  compare with one another), the way in which certain
character-handling functions operate, the decimal-point character that
is  used  in formatted    input/output  and string  conversion,  and the
format    and names used in the time  string  produced  by the  strftime
function.

Potentially, there may be many such environments.    WATCOM C supports
only the "C" locale and so  invoking this function will have no effect
upon the behavior of a program at present.

The possible values for the argument "category" are as follows:

LC_ALL           select entire environment

LC_COLLATE     select collating sequence

LC_CTYPE       select the character-handling

LC_MONETARY    select monetary formatting information

LC_NUMERIC     select the numeric-format environment

LC_TIME        select the time-related environment

At the start of a program,  the  equivalent of the following statement
is executed.

    setlocale( LC_ALL, "C" );

::::SETMODE
#include \<io.h>
#include \<fcntl.h>
int setmode( int handle, int mode );

The  setmode  function    sets,  at  the    operating  system  level,  the
translation  mode to be the  value of  "mode"  for the file whose file
handle is given by "handle". The mode, defined in the \<fcntl.h> header
file, can be one of:

O_TEXT      On  input,  a  carriage-return  character  that  immediately
      precedes a linefeed  character is removed from the data that
      is read.  On output, a carriage-return character is inserted
      before each linefeed character.

O_BINARY  Data is read or written unchanged.
::::SETVBUF
#include \<stdio.h>
int setvbuf( FILE *fp,
         char *buf,
         int mode,
         size_t size );

The  setvbuf  function can be used to associate a buffer with the file
designated  by "fp". If this function is used, it must be called after
the file has been opened and before it has been read or written.   The
argument  "mode"  determines  how  the    file "fp" will be buffered, as
follows:

_IOFBF    causes input/output to be fully buffered.

_IOLBF    causes    output to be line buffered (the buffer will be flushed
    when a new-line character is written, when the buffer is full,
    or when input is requested.

_IONBF    causes input/output to be completely unbuffered.

If the    argument  "buf" is not NULL, the array to which it points will
be used instead of an  automatically  allocated buffer.   The argument
"size" specifies the size of the array.
::::SIGNAL
#include \<signal.h>
void ( *signal(int sig, void (*func)(int)) )( int );

The  signal  function  is used to specify an action to take place when
certain  conditions  are  detected  while a program  executes.     These
conditions are defined to be:

SIGABRT   abnormal termination, such as caused by the abort function

SIGBREAK  an  interactive   attention    (CTRL/BREAK  on  keyboard)  is
      signalled

SIGFPE      an  erroneous   floating-point  operation  occurs  (such  as
      division by zero, overflow and underflow)

SIGILL      illegal instruction encountered

SIGINT      an interactive attention (CTRL/C on keyboard) is signalled

SIGSEGV   an illegal memory reference is detected

SIGTERM   a termination request is sent to the program

SIGUSR1   OS/2 process flag A via DosFlagProcess

SIGUSR2   OS/2 process flag B via DosFlagProcess

SIGUSR3   OS/2 process flag C via DosFlagProcess

An action can be specified for each of the above conditions, depending
upon the value of the "func" argument:

function When  "func" is a function name, that function will be called
     equivalently to the following code sequence.

         /* "sig_no" is condition being signalled */
         signal( sig_no, SIG_DFL );
         (*func)( sig_no );

     The "func"  function may terminate the program by calling the
     exit  or  abort  functions  or  call  the  longjmp  function.
     Because   the    next  signal  will  be    handled  with  default
     handling, the program must again call signal if it is desired
     to  handle  the  next    condition  of the  type  that has been
     signalled.

     After    returning  from  the   signal-catching    function,  the
     receiving process will resume execution at the point at which
     it was interrupted.

     The signal catching function is described as follows:

         void func( int sig_no )
         {
         .
         .
         .
         }

     It is not possible to catch the signals SIGKILL and SIGSTOP.

     Since    signal-catching  functions are invoked    asynchronously
     with process  execution, the type sig_atomic_t may be used to
     define   variables  on  which    an  atomic   operation    (e.g.,
     incrementation, decrementation) may be performed.

SIG_DFL  This  value  causes the default  action for the  condition to
     occur.

SIG_IGN  This value causes the indicated condition to be ignored.

SIG_ACK  Used in OS/2 to acknowledge the receipt of a signal.    Once a
     process  receives a given  signal, the  operating system will
     not  send any more  signals of this type until it  receives a
     SIG_ACK acknowledgement back from the process.

When a    condition  is detected, it may be handled by a program, it may
be  ignored,  or it may be handled by the usual  default action (often
causing an error message to be printed upon the stderr stream followed
by program termination).

When the program begins execution, the equivalent of

    signal( SIGABRT, SIG_IGN );
    signal( SIGFPE, SIG_DFL );
    signal( SIGILL, SIG_DFL );
    signal( SIGINT, SIG_IGN );
    signal( SIGSEGV, SIG_DFL );
    signal( SIGTERM, SIG_DFL );

is executed.

A condition can be generated by a program using the raise function.
::::SIN
#include \<math.h>
double sin( double x );

The sin  function  computes the sine of "x" (measured in radians).   A
large  magnitude  argument  may  yield    a  result  with  little  or no
significance.
::::SINH
#include \<math.h>
double sinh( double x );

The sinh  function  computes the hyperbolic sine of "x". A range error
occurs if the magnitude of "x" is too large.
::::SLEEP
#include \<dos.h>
void sleep( unsigned seconds );

The  sleep  function  suspends    execution by the  specified  number of
"seconds".
::::SOPEN
#include \<io.h>
#include \<fcntl.h>
#include \<sys\stat.h>
#include \<sys\types.h>
#include \<share.h>
int sopen( const char *filename,
       int access, int share, ... );

The sopen  function  opens a file at the  operating  system  level for
shared    access.    The    name  of  the  file to be  opened  is given by
"filename".  The file will be  accessed  according  to the access mode
specified  by  "access".  When the file is be  created,  the  optional
argument must be given which establishes the future access permissions
for the file.    Additionally, the sharing mode of the file is given by
the "share" argument.     The optional argument is the file permissions
to be used when O_CREAT flag is on in the "access" mode.

The access  mode is  established  a combination of the bits defined in
\<fcntl.h> header file.  The following bits may be set:

O_RDONLY    permit the file to be only read.

O_WRONLY    permit the file to be only written.

O_RDWR        permit the file to be both read and written.

O_APPEND    causes  each  record  that is written to be written at the
        end of the file.

O_CREAT     has no  effect  when  the  file  indicated    by  "filename"
        already exists; otherwise, the file is created;

O_TRUNC     causes  the file to be  truncated  to contain no data when
        the  file  exists;    has no    effect    when the file does not
        exist.

O_BINARY    causes  the file to be  opened  in binary mode which means
        that  data    will  be  transmitted  to and  from  the  file
        unchanged.

O_TEXT        causes the file to be opened in text mode which means that
        carriage-return characters are written before any linefeed
        character  that  is  written  and  causes  carriage-return
        characters to be removed when encountered during reads.

When neither  O_TEXT nor O_BINARY are  specified, the default value in
the global  variable  _fmode is used to set the file translation mode.
When  the  program  begins  execution,    this  variable    has a value of
O_TEXT.

O_CREAT must be specified when the file does not exist and it is to be
written.

When the file is to be created ( O_CREAT is  specified), an additional
argument must be passed which contains the file permissions to be used
for the new file.   The access    permissions  for the file or directory
are  specified    as a  combination of bits (defined in the \<sys\stat.h>
header file).

The following bits define permissions for the owner.

S_IRWXU     Read, write, execute/search

S_IRUSR     Read permission

S_IWUSR     Write permission

S_IXUSR     Execute/search permission

The following bits define permissions for the group.

S_IRWXG     Read, write, execute/search

S_IRGRP     Read permission

S_IWGRP     Write permission

S_IXGRP     Execute/search permission

The following bits define permissions for others.

S_IRWXO     Read, write, execute/search

S_IROTH     Read permission

S_IWOTH     Write permission

S_IXOTH     Execute/search permission

The  following    bits define  miscellaneous  permissions  used by other
implementations.

S_IREAD     is equivalent to S_IRUSR (read permission)

S_IWRITE    is equivalent to S_IWUSR (write permission)

S_IEXEC     is equivalent to S_IXUSR (execute/search permission)

All  files  are  readable  with DOS; however, it is a good idea to set
S_IREAD when read permission is intended for the file.

The sopen  function  applies the current file  permission  mask to the
specified permissions (see umask).

The shared  access for the file is  established  by the combination of
bits set in "share" where the following values may be set:

SH_COMPAT      Set compatibility mode.

SH_DENYRW      Prevent read or write access to the file.

SH_DENYWR      Prevent write access of the file.

SH_DENYRD      Prevent read access to the file.

SH_DENYNO      Permit both read and write access to the file.

You should consult the technical documentation for the DOS system that
you are using for more detailed information about these sharing modes.
::::SOUND
#include \<dos.h>
void sound( unsigned frequency );

The  sound  function  turns  on  the  PC's  speaker  at the  specified
"frequency".  The  frequency  is in  Hertz  (cycles per second).   The
speaker  can be turned off by calling  the  function  nosound after an
appropriate amount of time.
::::SPAWN
#include \<process.h>
int spawnl(   mode, pgm, arg0, arg1..., argn, NULL );
int spawnle(  mode, pgm, arg0, arg1..., argn, NULL,envp);
int spawnlp(  mode, pgm, arg0, arg1..., argn, NULL );
int spawnlpe( mode, pgm, arg0, arg1..., argn, NULL,envp);
int spawnv(   mode, pgm, argv );
int spawnve(  mode, pgm, argv, envp );
int spawnvp(  mode, pgm, argv );
int spawnvpe( mode, pgm, argv, envp );
   int           mode;         /* mode for parent    */
   const char *pgm;         /* name of file       */
   const char *arg0, ..., *argn; /* arguments           */
   const char *argv[];         /* array of arguments */
   const char *envp[];         /* environment strings*/

The spawn  functions  create and execute a new child process, named by
"pgm". The value of "mode"  determines    how the  program is loaded and
how  the  invoking  program  will behave after the invoked  program is
initiated:

P_WAIT      The  invoked    program  is loaded into  available  memory, is
      executed, and then the original program resumes execution.

P_NOWAIT  Causes the current  program to execute concurrently with the
      new child process.

P_NOWAITO Causes the current  program to execute concurrently with the
      new  child  process.      The  functions  wait    and  cwait are
      ignored.

P_OVERLAY The invoked  program replaces the original program in memory
      and is executed.  No return is made to the original program.
      This is equivalent to calling the appropriate exec function.

The program is located by using the following logic in sequence:

   1. An attempt is made to locate the    program in the current working
      directory  if no    directory  specification  precedes the program
      name; otherwise, an attempt is made in the specified directory.

   2. If no file  extension  is  given, an attempt is made to find the
      program  name, in the  directory    indicated  in the first point,
      with .COM concatenated to the end of the program name.

   3. If no file  extension  is  given, an attempt is made to find the
      program  name, in the  directory    indicated  in the first point,
      with .EXE concatenated to the end of the program name.

   4. When no  directory specification is given as part of the program
      name,  the spawnlp,  spawnlpe,  spawnvp, and spawnvpe  functions
      will   repeat  the   preceding  three  steps  for  each  of  the
      directories  specified by the PATH  environment  variable.   The
      command

      path c:\myapps;d:\lib\applns

      indicates that the two directories

      c:\myapps
      d:\lib\applns

      are to be searched.  The DOS path command (without any directory
      specification)  will  cause  the current path  definition  to be
      displayed.

An error is detected when the program cannot be found.

Arguments  are passed to the child  process by    supplying  one or more
pointers to character strings as arguments in the spawn call.     These
character  strings are    concatenated  with spaces inserted to separate
the arguments to form one argument string for the child process.   The
length of this    concatenated  string must not exceed 128 bytes in real
mode.

The  arguments    may be passed as a list of arguments (spawnl, spawnle,
spawnlp,  and  spawnlpe)  or as a vector of pointers (spawnv, spawnve,
spawnvp, and spawnvpe).    At least one argument, "arg0" or "argv[0]",
must  be  passed  to the child    process.   By  convention,  this first
argument is a pointer to the name of the program.

If the arguments are passed as a list, there must be a NULL pointer to
mark  the end of the  argument    list.    Similarly,  if a pointer to an
argument vector is passed, the argument vector must be terminated by a
NULL pointer.

The  environment  for the invoked program is inherited from the parent
process  when  you  use  the  spawnl,  spawnlp,  spawnv,  and  spawnvp
functions.   The spawnle,  spawnlpe,  spawnve, and spawnvpe  functions
allow  a  different  environment  to be  passed  to the child  process
through the "envp" argument.    The argument "envp" is a pointer to an
array of character pointers, each of which points to a string defining
an environment variable.  The array is terminated with a NULL pointer.
Each pointer locates a character string of the form

    variable=value

that  is  used    to define an  environment  variable.   If the value of
"envp" is NULL, then the child process inherits the environment of the
parent process.

The  environment  is the  collection  of environment  variables  whose
values    that  have  been  defined  with the DOS SET  command or by the
successful execution of the putenv function.  A program may read these
values with the getenv function.
::::SPAWNL
 ->SPAWN
::::SPAWNLE
 ->SPAWN
::::SPAWNLP
 ->SPAWN
::::SPAWNLPE
 ->SPAWN
::::SPAWNV
 ->SPAWN
::::SPAWNVE
 ->SPAWN
::::SPAWNVP
 ->SPAWN
::::SPAWNVPE
 ->SPAWN
::::SPRINTF
#include \<stdio.h>
int sprintf( char *buf, const char *format, ... );

The  sprintf  function    is  equivalent    to  fprintf,  except  that the
argument  "buf"  specifies a character    array into which the generated
output is placed, rather than to a file.    A null character is placed
at the end of the generated character string.    The "format" string is
described under the description for printf.
::::SQRT
#include \<math.h>
double sqrt( double x );

The  sqrt  function  computes the  non-negative  square root of "x". A
domain error occurs if the argument is negative.
::::SRAND
#include \<stdlib.h>
void srand( unsigned int seed );

The srand function uses the argument "seed" to start a new sequence of
pseudo-random integers to be returned by subsequent calls to rand.   A
particular  sequence  of  pseudo-random  integers  can be  repeated by
calling  srand with the same "seed"  value.   The default  sequence of
pseudo-random integers is selected with a "seed" value of 1.
::::SSCANF
#include \<stdio.h>
int sscanf( const char *in_string,
        const char *format, ... );

The sscanf  function scans input from the character string "in_string"
under control of the argument "format". Following the format string is
the list of addresses of items to receive values.

The  format  string is described  under the  description  of the scanf
function.
::::STACKAVAIL
#include \<malloc.h>
size_t stackavail(void);

The   stackavail  function  returns  the  number  of  bytes  currently
available  in the stack.   This value is usually  used to determine an
appropriate amount to allocate using alloca.
::::STAT
#include \<sys\types.h>
#include \<sys\stat.h>
int stat( const char *path, struct stat *buf );

The  stat  function  obtains  information  about the file or directory
referenced  in    "path". This  information  is placed in the  structure
located at the address indicated by "buf".

The file \<sys\stat.h> contains definitions for the structure stat.

struct stat {
   dev_t   st_dev;    /* disk drive file resides on */
   ino_t   st_ino;    /* this inode's number        */
   unsigned short st_mode; /* file mode         */
   short   st_nlink;  /* # of hard links        */
   short   st_uid;    /* user-id, always 'root'     */
   short   st_gid;    /* group-id, always 'root'    */
   dev_t   st_rdev;   /* drive #, same as st_dev    */
   off_t   st_size;   /* total file size        */
   time_t  st_atime;  /* time of last access        */
   time_t  st_mtime;  /* time of last modification  */
   time_t  st_ctime;  /* time of last status change */
};

::::STRCAT
#include \<string.h>
char *strcat( char *dst, const char *src );
char __far *_fstrcat( char __far *dst,
              const char __far *src );

The strcat and    _fstrcat functions append a copy of the string pointed
to by "src"  (including  the terminating null character) to the end of
the  string  pointed  to  by  "dst".  The  first  character  of  "src"
overwrites the null character at the end of "dst".

The  _fstrcat  function is a data model independent form of the strcat
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRCHR
#include \<string.h>
char *strchr( const char *s, int c );
char __far *_fstrchr( const char __far *s, int c );

The strchr and _fstrchr  functions  locate the first occurrence of "c"
(converted to a char) in the string pointed to by "s". The terminating
null character is considered to be part of the string.

The  _fstrchr  function is a data model independent form of the strchr
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRCMP
#include \<string.h>
int strcmp( const char *s1, const char *s2 );
int _fstrcmp( const char __far *s1,
          const char __far *s2 );

The  strcmp and _fstrcmp  functions  compare the string  pointed to by
"s1" to the string pointed to by "s2".

The  _fstrcmp  function is a data model independent form of the strcmp
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::STRCMPI
#include \<string.h>
int strcmpi( const char *s1, const char *s2 );

The strcmpi  function  compares, with case  insensitivity,  the string
pointed to by "s1" to the string pointed to by "s2".
::::STRCOLL
#include \<string.h>
int strcoll( const char *s1,
         const char *s2 );

The  strcoll  function    compares  the string pointed to by "s1" to the
string    pointed to by "s2". The comparison uses the collating sequence
selected by the setlocale function.    The function will be equivalent
to the strcmp  function  when the  collating sequence is selected from
the "C" locale.
::::STRCPY
#include \<string.h>
char *strcpy( char *dst, const char *src );
char __far *_fstrcpy( char __far *dst,
              const char __far *src );

The strcpy and    _fstrcpy functions copy the string pointed to by "src"
(including  the  terminating null character) into the array pointed to
by "dst".  Copying of  overlapping  objects is not  guaranteed to work
properly.   See  the  description  for    the  memmove  function to copy
objects that overlap.

The  _fstrcpy  function is a data model independent form of the strcpy
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRCSPN
#include \<string.h>
size_t strcspn( const char *str,
        const char *charset );
size_t _fstrcspn( const char __far *str,
          const char __far *charset );

The strcspn and  _fstrcspn functions compute the length of the initial
segment of the string  pointed to by "str"  which consists entirely of
characters   not  from    the  string   pointed  to  by  "charset".  The
terminating null character is not considered part of "str".

The _fstrcspn function is a data model independent form of the strcspn
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::STRDUP
#include \<string.h>
char *strdup( const char *src );

The strdup  function creates a duplicate copy of the string pointed to
by "src"  and  returns a pointer to the new copy.   The memory for the
new string is  obtained  by using the malloc function and can be freed
using the free function.
::::STREAM
             Stream I/O Functions
             ════════════════════

A stream  is the name  given to a file or device which has been opened
for data transmission.      When a stream is opened, a pointer to a FILE
structure is returned.      This pointer is used to reference the stream
when other functions are subsequently invoked.

The following functions are defined:

<clearerr>    clear end-of-file and error indicators for stream
<fclose>    close stream
<fcloseall>    close all open streams
<fdopen>    open stream, given handle
<feof>        test for end of file
<ferror>    test for file error
<fflush>    flush output buffer
<fgetc>     get next character from file
<fgetchar>    equivalent to fgetc with the argument stdin
<fgetpos>    get current file position
<fgets>     get a string
<flushall>    flush output buffers for all streams
<fopen>     open a stream
<fprintf>    format output
<fputc>     write a character
<fputchar>    write a character to the stdout stream
<fputs>     write a string
<fread>     read a number of objects
<freopen>    re-opens a stream
<fscanf>    scan input according to format
<fseek>     set current file position, relative
<fsetpos>    set current file position, absolute
<ftell>     get current file position
<fwrite>    write a number of objects
<getc>        read character
<getchar>    get next character from stdin
<gets>        get string from stdin
<perror>    write error message to stderr stream
<printf>    format output to stdout
<putc>        write character to file
<putchar>    write character to stdout
<puts>        write string to stdout
<rewind>    position to start of file
<scanf>     scan input from stdin under format control
<setbuf>    set buffer
<setvbuf>    set buffering
<tmpfile>    create temporary file
<ungetc>    push character back on input stream
<vfprintf>    same as fprintf but with variable arguments
<vfscanf>    same as fscanf but with variable arguments
<vprintf>    same as printf but with variable arguments
<vscanf>    same as scanf but with variable arguments

See  also  <file>  (file   manipulation   functions)  and  <operating>
(operating  system i/o    functions) for other  functions  which operate
upon files.
::::STRERROR
#include \<string.h>
char *strerror( int errnum );

The strerror  function    maps the error number contained in "errnum" to
an error message.
::::STRFTIME
#include \<time.h>
size_t strftime(char *s,
        size_t maxsize,
        const char *format,
        const struct tm *timeptr );

struct    tm {
  int tm_sec;    /* seconds after the minute -- [0,61] */
  int tm_min;    /* minutes after the hour   -- [0,59] */
  int tm_hour;    /* hours after midnight     -- [0,23] */
  int tm_mday;    /* day of the month        -- [1,31] */
  int tm_mon;    /* months since January     -- [0,11] */
  int tm_year;    /* years since 1900              */
  int tm_wday;    /* days since Sunday        -- [0,6]  */
  int tm_yday;    /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag */
};

The strftime  function formats the time in the argument "timeptr" into
the array  pointed to by the  argument    "s"  according to the "format"
argument.  The "format" string consists of zero or more directives and
ordinary characters.  A directive consists of a '%' character followed
by a character that determines the substitution that is to take place.
All ordinary characters are copied unchanged into the array.   No more
than  "maxsize"  characters  are  placed  in the  array.    The format
directives %D, %h, %n, %r, %t, and %T are from POSIX.

%a  locale's abbreviated weekday name

%A  locale's full weekday name

%b  locale's abbreviated month name

%B  locale's full month name

%c  locale's appropriate date and time representation

%d  day of the month as a decimal number (01-31)

%D  date in the format mm/dd/yy (POSIX)

%h  locale's abbreviated month name (POSIX)

%H  hour (24-hour clock) as a decimal number (00-23)

%I  hour (12-hour clock) as a decimal number (01-12)

%j  day of the year as a decimal number (001-366)

%m  month as a decimal number (01-12)

%M  minute as a decimal number (00-59)

%n  newline character (POSIX)

%p  locale's equivalent of either AM or PM

%r  12-hour  clock time (01-12) using the AM/PM notation in the format
    HH:MM:SS (AM|PM) (POSIX)

%S  second as a decimal number (00-59)

%t  tab character (POSIX)

%T  24-hour clock time in the format HH:MM:SS (POSIX)

%U  week  number of the year as a decimal  number (00-52) where Sunday
    is the first day of the week

%w  weekday as a decimal number (0-6) where 0 is Sunday

%W  week  number of the year as a decimal  number (00-52) where Monday
    is the first day of the week

%x  locale's appropriate date representation

%X  locale's appropriate time representation

%y  year without century as a decimal number (00-99)

%Y  year with century as a decimal number

%Z  timezone name, or by no characters if no timezone exists

%%  character %
::::STRICMP
#include \<string.h>
int stricmp( const char *s1, const char *s2 );
int _fstricmp( const char __far *s1,
           const char __far *s2 );

The stricmp and _fstricmp  functions compare, with case insensitivity,
the  string  pointed  to by "s1" to the string pointed to by "s2". All
upper-case  characters from "s1" and "s2" are mapped to lower-case for
the purposes of doing the comparison.

The _fstricmp function is a data model independent form of the stricmp
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::STRING
             String Manipulation Functions
             ═════════════════════════════

A string is an array of characters (with type char) that is terminated
with an extra null  character  ('\0').     Functions are passed only the
address of the string  since the size can be  determined  by searching
for the  terminating  character.   The    functions that begin with "_f"
accept far pointers as their  arguments  allowing  manipulation of any
memory location regardless of which memory model your program has been
compiled for.  The following functions are defined:

<_fstrcat>    concatenate two far strings
<_fstrchr>    locate character in far string
<_fstrcmp>    compare two far strings
<_fstrcpy>    copy far string
<_fstrcspn>    get  number  of  string  characters  not from a set of
        characters
<_fstricmp>    compare two far strings with case insensitivity
<_fstrlen>    length of a far string
<_fstrlwr>    convert far string to lower-case
<_fstrncat>    concatenate two far strings, up to a maximum length
<_fstrncmp>    compare two far strings up to maximum length
<_fstrncpy>    copy a far string, up to a maximum length
<_fstrnicmp>    compare two far strings with case  insensitivity up to
        a maximum length
<_fstrnset>    fill far string with character to a maximum length
<_fstrpbrk>    locate occurrence of a string within a second string
<_fstrrchr>    locate last  occurrence  of character from a character
        set
<_fstrrev>    reverse a far string in place
<_fstrset>    fill far string with a character
<_fstrspn>    find number of characters at start of string which are
        also in a second string
<_fstrstr>    find first occurrence of string in second string
<_fstrtok>    get next token from a far string
<_fstrupr>    convert far string to upper-case
<sprintf>    formatted transmission to string
<sscanf>    scan from string under format control
<strcat>    concatenate string
<strchr>    locate character in string
<strcmp>    compare two strings
<strcmpi>    compare two strings with case insensitivity
<strcoll>    compare two strings using locale collating sequence
<strcpy>    copy a string
<strcspn>    get  number  of  string  characters  not from a set of
        characters
<strdup>    allocate and duplicate a string
<strerror>    get error message as string
<stricmp>    compare two strings with case insensitivity
<strlen>    string length
<strlwr>    convert string to lower-case
<strncat>    concatenate two strings, up to a maximum length
<strncmp>    compare two strings up to maximum length
<strncpy>    copy a string, up to a maximum length
<strnicmp>    compare  two  strings  with case insensitivity up to a
        maximum length
<strnset>    fill string with character to a maximum length
<strpbrk>    locate occurrence of a string within a second string
<strrchr>    locate last  occurrence  of character from a character
        set
<strrev>    reverse a string in place
<strset>    fill string with a character
<strspn>    find number of characters at start of string which are
        also in a second string
<strstr>    find first occurrence of string in second string
<strtok>    get next token from string
<strupr>    convert string to upper-case
<strxfrm>    transform string to locale's collating sequence
<vsprintf>    same as sprintf but with variable arguments
<vsscanf>    same as sscanf but with variable arguments

For  related  functions  see  <conversion>  (conversions to  and  from
strings),  <time>  (formatting    of  dates  and    times),  and  <memory>
(operate on arrays without terminating null character).
::::STRLEN
#include \<string.h>
size_t strlen( const char *s );
size_t _fstrlen( const char __far *s );

The  strlen  and _fstrlen  functions  compute the length of the string
pointed to by "s".

The  _fstrlen  function is a data model independent form of the strlen
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::STRLWR
#include \<string.h>
char *strlwr( char *str );
char __far *_fstrlwr( char __far *str );

These  functions  replace the string str with lower-case characters by
invoking the tolower function for each character in the string.

The  _fstrlwr  function is a data model independent form of the strlwr
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRNCAT
#include \<string.h>
char *strncat( char *dst, const char *src, size_t n );
char __far *_fstrncat( char __far *dst,
               const char __far *src,
               size_t n );

The  strncat  and   _fstrncat  functions  append  not  more  than  "n"
characters  of the string pointed to by "src" to the end of the string
pointed to by "dst". The first    character of "src" overwrites the null
character  at the end of "dst". A terminating null character is always
appended to the result.

The _fstrncat function is a data model independent form of the strncat
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRNCMP
#include \<string.h>
int strncmp( const char *s1,
         const char *s2,
         size_t n );
int _fstrncmp( const char __far *s1,
           const char __far *s2,
           size_t n );

The  strncmp  and  _fstrncmp  functions  compare  not  more  than  "n"
characters from the string pointed to by "s1" to the string pointed to
by "s2".

The _fstrncmp function is a data model independent form of the strncmp
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::STRNCPY
#include \<string.h>
char *strncpy( char *dst,
           const char *src,
           size_t n );
char __far *_fstrncpy( char __far *dst,
               const char __far *src,
               size_t n );

The strncpy and  _fstrncpy  functions copy no more than "n" characters
from  the  string  pointed  to by  "src" into the array  pointed to by
"dst".    Copying  of  overlapping  objects  is not  guaranteed  to work
properly.    See the memmove function if you wish to copy objects that
overlap.

If the string pointed to by "src" is shorter than "n" characters, null
characters  are appended to the copy in the array pointed to by "dst,"
until "n" characters in all have been written.     If the string pointed
to by "src" is longer than "n" characters, then the result will not be
terminated by a null character.

The _fstrncpy function is a data model independent form of the strncpy
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRNICMP
#include \<string.h>
int strnicmp( const char *s1,
          const char *s2,
          size_t len );
int _fstrnicmp( const char __far *s1,
        const char __far *s2,
        size_t len );

The   strnicmp    and  _fstrnicmp   functions   compare,     without  case
sensitivity, the string pointed to by "s1" to the string pointed to by
"s2," for at most "len" characters.

The  _fstrnicmp  function  is a data  model  independent  form    of the
strnicmp  function  that  accepts far pointer  arguments.   It is most
useful in mixed memory model applications.
::::STRNSET
#include \<string.h>
char *strnset( char *s1,
           int fill,
           const size_t len );
char __far *_fstrnset( char __far *s1,
               int fill,
               const size_t len );

The  strnset  and  _fstrnset  functions  fill the string "s1" with the
value of the argument "fill," converted to be a character value.  When
the  value  of    "len" is greater  than the length of the  string,  the
entire string is filled.   Otherwise, that number of characters at the
start of the string are set to the fill character.

The _fstrnset function is a data model independent form of the strnset
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRPBRK
#include \<string.h>
char *strpbrk( const char *str, const char *charset );
char __far *_fstrpbrk( const char __far *str,
               const char __far *charset );

The strpbrk and _fstrpbrk functions locate the first occurrence in the
string pointed to by "str" of any character from the string pointed to
by "charset".

The _fstrpbrk function is a data model independent form of the strpbrk
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRRCHR
#include \<string.h>
char *strrchr( const char *s, int c );
char __far *_fstrrchr( const char __far *s, int c );

The strrchr and  _fstrrchr functions locate the last occurrence of "c"
(converted to a char) in the string pointed to by "s". The terminating
null character is considered to be part of the string.

The _fstrrchr function is a data model independent form of the strrchr
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRREV
#include \<string.h>
char *strrev( char *s1 );
char __far *_fstrrev( char __far *s1 );

The strrev and    _fstrrev functions replace the string s1 with a string
whose characters are in the reverse order.

The  _fstrrev  function is a data model independent form of the strrev
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRSET
#include \<string.h>
char *strset( char *s1, char fill );
char __far *_fstrset( char __far *s1, char fill );

The strset and    _fstrset  functions  fill the string  pointed to by s1
with  the  character  fill.   The  terminating    null  character in the
original string remains unchanged.

The  _fstrset  function is a data model independent form of the strset
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRSPN
#include \<string.h>
size_t strspn( const char *str,
           const char *charset );
size_t _fstrspn( const char __far *str,
         const char __far *charset );

The  strspn and _fstrspn  functions  compute the length of the initial
segment of the string pointed to by "str" which consists of characters
from  the  string  pointed  to    by  "charset".    The  terminating  null
character is not considered to be part of "charset".

The  _fstrspn  function is a data model independent form of the strspn
function  that    accepts far pointer  arguments.   It is most useful in
mixed memory model applications.
::::STRSTR
#include \<string.h>
char *strstr( const char *str,
          const char *substr );
char __far *_fstrstr( const char __far *str,
              const char __far *substr );

The strstr and _fstrstr  functions  locate the first occurrence in the
string    pointed to by "str" of the  sequence  of characters (excluding
the terminating null character) in the string pointed to by "substr".

The  _fstrstr  function is a data model independent form of the strstr
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRTOD
#include \<stdlib.h>
double strtod( const char *ptr, char **endptr );

The strtod  function converts the string pointed to by "ptr" to double
representation.  The function recognizes a string containing :

   * optional white space,

   * an optional plus or minus sign,

   * a sequence of digits containing an optional decimal point,

   * an  optional 'e' or 'E' followed by an optionally signed sequence
    of digits.

The conversion ends at the first unrecognized character.  A pointer to
that  character  will be stored in the object to which "endptr" points
if "endptr" is not NULL.
::::STRTOK
#include \<string.h>
char *strtok( char *s1, const char *s2 );
char __far *_fstrtok( char __far *s1,
              const char __far *s2 );

The strtok and _fstrtok functions are used to break the string pointed
to by "s1"  into a sequence of tokens, each of which is delimited by a
character from the string pointed to by "s2". The first call to strtok
will  return a pointer to the first  token in the string pointed to by
"s1". Subsequent calls to strtok must pass a NULL pointer as the first
argument,  in order to get the next  token in the string.   The set of
delimiters used in each of these calls to strtok can be different from
one call to the next.

The first call in the  sequence  searches "s1" for the first character
that is not contained in the current delimiter string "s2". If no such
character  is  found,  then there are no tokens in "s1" and the strtok
function returns a NULL pointer.   If such a character is found, it is
the start of the first token.

The strtok  function  then searches from there for a character that is
contained in the current  delimiter  string.   If no such character is
found, the  current  token extends to the end of the string pointed to
by "s1". If such a  character  is  found,  it is overwritten by a null
character,  which  terminates the current token.   The strtok function
saves a pointer to the following character, from which the next search
for a token will start when the first argument is a NULL pointer.

Because  strtok may modify the original  string, that string should be
duplicated if the string is to be re-used.

The  _fstrtok  function is a data model independent form of the strtok
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRTOL
#include \<stdlib.h>
long int strtol( const char *ptr,
         char **endptr,
         int base );

The  strtol  function  converts  the string  pointed to by "ptr" to an
object of type long int.  The function recognizes a string containing:

   * optional white space,

   * an optional plus or minus sign,

   * a sequence of digits and letters.

The conversion ends at the first unrecognized character.  A pointer to
that  character  will be stored in the object to which "endptr" points
if "endptr" is not NULL.

If  "base"  is    zero,  the first  characters  after the optional  sign
determine the base used for the conversion.    If the first characters
are "0x" or "0X" the digits are treated as hexadecimal.   If the first
character  is  '0', the digits are  treated as octal.    Otherwise  the
digits are treated as decimal.

If  "base"  is not  zero, it must have a value between 2 and 36.   The
letters  a-z and A-Z  represent the values 10 through 35.   Only those
letters  whose    designated  values are less than "base" are permitted.
If  the  value    of  "base"  is    16,  the  characters  "0x" or "0X" may
optionally precede the sequence of letters and digits.
::::STRTOUL
#include \<stdlib.h>
unsigned long int strtoul( const char *ptr,
               char **endptr,
               int base );

The  strtoul  function    converts  the string pointed to by "ptr" to an
unsigned long.      The function recognizes a string containing optional
white  space,  followed  by a  sequence  of digits and    letters.   The
conversion  ends at the first  unrecognized  character.   A pointer to
that  character  will  be stored in the object    "endptr"  points to if
"endptr" is not NULL.

If "base" is zero, the first  characters  determine  the base used for
the conversion.    If the first characters are "0x" or "0X" the digits
are treated as hexadecimal.  If the first character is '0', the digits
are treated as octal.  Otherwise the digits are treated as decimal.

If "base" is not zero, it must have a value of between 2 and 36.   The
letters  a-z and A-Z  represent the values 10 through 35.   Only those
letters  whose    designated  values are less than "base" are permitted.
If  the  value    of  "base"  is    16,  the  characters  "0x" or "0X" may
optionally precede the sequence of letters and digits.
::::STRUPR
#include \<string.h>
char *strupr( char *s1 );
char __far *_fstrupr( char __far *s1 );

These  functions  replace the string s1 with  upper-case characters by
invoking the toupper function for each character in the string.

The  _fstrupr  function is a data model independent form of the strupr
function.  It accepts far pointer arguments and returns a far pointer.
It is most useful in mixed memory model applications.
::::STRXFRM
#include \<string.h>
size_t strxfrm( char *dst,
        const char *src,
        size_t n );

The strxfrm  function transforms, for no more than "n" characters, the
string    pointed  to by    "src"  to the buffer  pointed to by "dst". The
transformation    uses the collating  sequence selected by the setlocale
function  so  that two    transformed  strings will compare  identically
(using the  strncmp  function)    to a  comparison  of the  original two
strings using the strcoll function.    The function will be equivalent
to the    strncpy  function  (except  there  is no  padding of the "dst"
argument  with null characters when the argument "src" is shorter than
"n"  characters)  when the collating sequence is selected from the "C"
locale.
::::SWAB
#include \<stdlib.h>
void swab( char *src, char *dest, int num );

The swab function copies "num" bytes (which should be even) from "src"
to  "dest"  swapping  every  pair of  characters.   This is useful for
preparing  binary data to be transferred to another machine that has a
different byte ordering.
::::SYSTEM
#include \<stdlib.h>
int system( const char *command );

If the value of "command" is NULL, then the system function determines
whether or not a command  processor  is present (COMMAND.COM in DOS or
CMD.EXE in OS/2).

Otherwise,   the  system  function  invokes  a    copy  of  the  command
processor, and passes the string "command" to it for processing.  This
function  uses    spawnl    to  load  a  copy  of  the  command  processor
identified by the COMSPEC environment variable.

This  means  that  any    command  that  can  be    entered  to DOS can be
executed,  including  programs,  DOS  commands    and batch files.   The
exec...    and    spawn...   functions  can  only  cause    programs to be
executed.
::::TAN
#include \<math.h>
double tan( double x );

The tan function computes the tangent of "x" (measured in radians).  A
large  magnitude  argument  may  yield    a  result  with  little  or no
significance.
::::TANH
#include \<math.h>
double tanh( double x );

The tanh function computes the hyperbolic tangent of "x".

When the "x"  argument is large, partial or total loss of significance
may occur.  The matherr function will be invoked in this case.
::::TELL
#include \<io.h>
long int tell( int handle );

The  tell  function  determines  the  current  file  position  at  the
operating  system  level.    The  "handle"  value  is the file    handle
returned by a successful execution of the open function.

The  returned value may be used in conjunction with the lseek function
to reset the current file position.
::::TIME
                Time Functions
                ══════════════

These  functions  are  concerned with dates and times.     The following
functions are defined:

<asctime>    makes time string from time structure
<clock>     gets time since program start
<ctime>     gets calendar time string
<difftime>    calculate difference between two times
<ftime>     returns the current time in a timeb structure
<gmtime>    convert  calendar  time to Coordinated    Universal Time
        (UTC)
<localtime>    convert calendar time to local time
<mktime>    make calendar time from local time
<strftime>    format date and time
<tzset>     set global variables to reflect the local time zone
::::TIME
#include \<time.h>
time_t time( time_t *tloc );

The time  function determines the current calendar time and encodes it
into the type time_t.

The  time  represents  the  time  since  January  1, 1970  Coordinated
Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)).

The time set on the  computer  with the DOS time  command  and the DOS
date command reflects the local time.    The environment variable TZ is
used to establish the time zone to which this local time applies.  See
the section The TZ Environment Variable for a discussion of how to set
the time zone.
::::TMPFILE
#include \<stdio.h>
FILE *tmpfile( void );

The  tmpfile  function    creates  a  temporary  binary  file  that will
automatically  be removed when it is closed or at program termination.
The file is opened for update.
::::TMPNAM
#include \<stdio.h>
char *tmpnam( char *buffer );

The  tmpnam  function  generates  a  unique  string for use as a valid
filename.
::::TOLOWER
#include \<ctype.h>
int tolower( int c );

The   tolower    function   converts  an   upper-case   letter  to  the
corresponding lower-case letter.
::::TOUPPER
#include \<ctype.h>
int toupper( int c );

The  function  converts  a lower-case  character to the  corresponding
upper-case character.
::::TZSET
#include \<time.h>
void tzset( void );

The tzset function sets the global  variables  daylight,  timezone and
tzname    according to the value of the TZ  environment  variable.   The
section  The  TZ  Environment  Variable  describes  how  to  set  this
variable.

The  global  variables    have  the  following  values  after  tzset  is
executed:

daylight    Zero  indicates that daylight saving time is not supported
        in the locale; a non-zero  value  indicates  that daylight
        saving time is supported in the locale.   This variable is
        cleared/set  after a call to the tzset  function depending
        on    whether  a  daylight   saving  time   abbreviation  is
        specified in the TZ environment variable.

timezone    Contains the number of seconds that the local time zone is
        earlier than  Coordinated  Universal Time (UTC)  (formerly
        known as Greenwich Mean Time (GMT)).

tzname        Two-element   array   pointing   to  strings   giving  the
        abbreviations  for the name of the time zone when standard
        and daylight saving time are in effect.

The time set on the  computer  with the DOS time  command  and the DOS
date command reflects the local time.    The environment variable TZ is
used to establish the time zone to which this local time applies.  See
the section The TZ Environment Variable for a discussion of how to set
the time zone.
::::ULTOA
#include \<stdlib.h>
char *ultoa( unsigned long int value,
         char *buffer,
         int radix );

The ultoa function  converts the unsigned  binary integer "value" into
the  equivalent  string in base "radix" notation storing the result in
the  character    array  pointed    to by  "buffer".  A null  character is
appended  to the  result.   The size of  "buffer"  must be at least 33
bytes when converting values in base 2.
::::UMASK
#include \<sys\types.h>
#include \<sys\stat.h>
#include \<fcntl.h>
#include \<io.h>
int umask( int cmask );

The umask  function  sets the  process's  file mode  creation  mask to
"cmask". The  process's  file mode creation mask is used during creat,
open,  or  sopen  to  turn  off  permission  bits in the  "permission"
argument supplied.    In other words, if a bit in the mask is on, then
the  corresponding  bit in the file's  requested  permission  value is
disallowed.

The argument  "cmask" is a constant expression involving the constants
described below.  The access permissions for the file or directory are
specified as a combination of bits (defined in the \<sys\stat.h> header
file).

The following bits define permissions for the owner.

S_IRWXU     Read, write, execute/search

S_IRUSR     Read permission

S_IWUSR     Write permission

S_IXUSR     Execute/search permission

The following bits define permissions for the group.

S_IRWXG     Read, write, execute/search

S_IRGRP     Read permission

S_IWGRP     Write permission

S_IXGRP     Execute/search permission

The following bits define permissions for others.

S_IRWXO     Read, write, execute/search

S_IROTH     Read permission

S_IWOTH     Write permission

S_IXOTH     Execute/search permission

The  following    bits define  miscellaneous  permissions  used by other
implementations.

S_IREAD     is equivalent to S_IRUSR (read permission)

S_IWRITE    is equivalent to S_IWUSR (write permission)

S_IEXEC     is equivalent to S_IXUSR (execute/search permission)

For  example,  if  S_IREAD is  specified,  then reading is not allowed
(i.e.,    the file is write  only).   If    S_IWRITE  is  specified,  then
writing is not allowed (i.e., the file is read only).
::::UNGETC
#include \<stdio.h>
int ungetc( int c, FILE *fp );

The ungetc  function  pushes the  character specified by "c" back onto
the input  stream  pointed to by "fp". This character will be returned
by the next read on the  stream.   The    pushed-back  character will be
discarded  if a  call  is  made to the    fflush    function  or to a file
positioning  function (fseek, fsetpos, or rewind) before the next read
operation is performed.

Only one character (the most recent one) of pushback is remembered.

The ungetc function clears the end-of-file indicator, unless the value
of "c" is EOF.
::::UNGETCH
#include \<conio.h>
int ungetch( int c );

The ungetch  function  pushes the character specified by "c" back onto
the input stream for the console.   This character will be returned by
the next read from the    console  (with    getch or getche functions) and
will be  detected  by the  function  kbhit.   Only the last  character
returned in this way is remembered.

The ungetch  function  clears the  end-of-file    indicator,  unless the
value of "c" is EOF.
::::UNLINK
#include \<io.h>
int unlink( const char *path );

The unlink  function deletes the file whose name is the string pointed
to by "path". This function is equivalent to the remove function.
::::UNLOCK
#include \<io.h>
int unlock( int handle,
        unsigned long offset,
        unsigned long nbytes );

The unlock  function unlocks "nbytes" amount of previously locked data
in the file  designated  by  "handle" starting at byte "offset" in the
file.    This  allows  other processes to gain access to this region of
the file.

All locked regions of a file must be unlocked before a file is closed.
::::UTIME
#include \<sys\utime.h>
int utime( const char *path,
       const struct utimbuf *times );

struct utimbuf {
    time_t   actime;    /* access time */
    time_t   modtime;    /* modification time */
};

The utime  function  records the access and modification times for the
file identified by "path". Write access to this file must be permitted
for the time to be recorded.

When the  "times"  argument  is NULL, the  current  time is  recorded.
Otherwise,  the  argument must point at an object whose type is struct
utimbuf.   The    modification  time is taken from the modtime  field in
this structure.
::::UTOA
#include \<stdlib.h>
char *utoa( unsigned int value,
        char *buffer,
        int radix );

The utoa function  converts the unsigned  binary integer  "value" into
the  equivalent  string in base "radix" notation storing the result in
the  character    array  pointed    to by  "buffer".  A null  character is
appended  to the  result.   The size of "buffer" must be at least (8 *
sizeof(int) + 1) bytes when converting values in base 2.    That makes
the size 17 bytes on 16-bit machines, and 33 bytes on 32-bit machines.
::::VA_ARG
#include \<stdarg.h>
type va_arg( va_list param, type );

va_arg    is a macro  that can be used to  obtain the next argument in a
list  of  variable  arguments.     It  must be used with the  associated
macros va_start and va_end.  A sequence such as

    va_list curr_arg;
    type next_arg;

    next_arg = va_arg( curr_arg, type );

causes    "next_arg"  to be  assigned  the  value  of the next  variable
argument.  The type is the type of the argument originally passed.

The  macro  va_start  must  be    executed  first  in order to  properly
initialize  the  variable  next_arg  and  the  macro va_end  should be
executed after all arguments have been obtained.

The  data  item  curr_arg  is  of  type  va_list  which  contains  the
information to permit successive acquisitions of the arguments.
::::VA_END
#include \<stdarg.h>
void va_end( va_list param );

va_end is a macro used to complete the acquisition of arguments from a
list  of  variable  arguments.     It  must be used with the  associated
macros    va_start  and  va_arg.     See  the  description    for va_arg for
complete documentation on these macros.
::::VA_START
#include \<stdarg.h>
void va_start( va_list param, previous );

va_start  is a macro used to start the acquisition of arguments from a
list of  variable  arguments.    The  "param"  argument    is used by the
va_arg macro to locate the current acquired argument.    The "previous"
argument is the argument  that immediately precedes the "..". notation
in the    original  function  definition.    It  must  be  used with the
associated  macros  va_arg and va_end.     See the description of va_arg
for complete documentation on these macros.
::::VARIABLE
            Variable-length Argument Lists
            ══════════════════════════════

Variable-length  argument lists are used when a function does not have
a fixed number of arguments.    These macros provide the capability to
access these arguments.  The following functions are defined:

<va_arg>    get next variable argument
<va_end>    complete access of variable arguments
<va_start>    start access of variable arguments
::::VFPRINTF
#include \<stdio.h>
#include \<stdarg.h>
int vfprintf( FILE *fp,
          const char *format,
          va_list arg );

The  vfprintf  function  writes  output to the file pointed to by "fp"
under  control    of the    argument  "format".  The  "format"  string  is
described under the description for printf.   The vfprintf function is
equivalent  to fprintf,  with the variable argument list replaced with
"arg," which has been initialized by the va_start macro.
::::VFSCANF
#include \<stdio.h>
#include \<stdarg.h>
int vfscanf( FILE *fp,
         const char *format,
         va_list arg );

The  vfscanf  function    scans input from the file  designated  by "fp"
under  control of the argument    "format". The format list is described
with the scanf function.

The vfscanf  function is  equivalent  to the fscanf  function,    with a
variable argument list replaced with "arg," which has been initialized
using the va_start macro.
::::VPRINTF
#include \<stdio.h>
#include \<stdarg.h>
int vprintf( const char *format, va_list arg );

The vprintf function writes output to the file stdout under control of
the  argument  "format".  The "format"    string is described  under the
description for printf.  The vprintf function is equivalent to printf,
with the variable  argument  list  replaced with "arg," which has been
initialized by the va_start macro.
::::VSCANF
#include \<stdio.h>
#include \<stdarg.h>
int vscanf( const char *format,
        va_list arg );

The vscanf  function  scans input from the file  designated by "stdin"
under  control of the argument    "format". The format list is described
with the scanf function.

The  vscanf  function  is  equivalent  to the scanf  function,    with a
variable argument list replaced with "arg," which has been initialized
using the va_start macro.
::::VSPRINTF
#include \<stdio.h>
#include \<stdarg.h>
int vsprintf( char *buf,
          const char *format,
          va_list arg );

The  vsprintf  function  formats  data    under  control of the "format"
control  string and writes the result to "buf". The "format" string is
described under the description for printf.   The vsprintf function is
equivalent  to sprintf,  with the variable argument list replaced with
"arg," which has been initialized by the va_start macro.
::::VSSCANF
#include \<stdio.h>
#include \<stdarg.h>
int vsscanf( const char *in_string,
         const char *format,
         va_list arg );

The  vsscanf  function    scans  input  from  the string    designated  by
"in_string" under control of the argument "format". The format list is
described with the scanf function.

The vsscanf  function is  equivalent  to the sscanf  function,    with a
variable argument list replaced with "arg," which has been initialized
using the va_start macro.
::::WAIT
#include \<process.h>
int wait( int *status );

The  wait  function  suspends  the  calling  process  until any of the
caller's immediate child processes terminate.

If  "status"  is not  NULL, it points to a word that will be filled in
with the  termination  status  word and return    code of the terminated
child process.

If the child  process  terminated normally, then the low order byte of
the status word will be set to 0, and the high order byte will contain
the low order byte of the return code that the child process passed to
the DOSEXIT  function.     The DOSEXIT  function is called whenever main
returns, or exit or _exit are explicity called.

If the child  process  did not terminate normally, then the high order
byte of the  status word will be set to 0, and the low order byte will
contain one of the following values:

1    Hard-error abort

2    Trap operation

3    SIGTERM signal not intercepted
::::WCSTOMBS
#include \<stdlib.h>
size_t wcstombs( char *s,const wchar_t *pwcs,size_t n );

The wcstombs function converts a sequence of wide character codes from
the array pointed to by "pwcs" into a sequence of multibyte characters
and stores  them in the array pointed to by "s". The wcstombs function
stops if a  multibyte  character  would  exceed the limit of "n" total
bytes, or if the null character is stored.    At most "n" bytes of the
array pointed to by "s" will be modified.
::::WCTOMB
#include \<stdlib.h>
int wctomb( char *s, wchar_t wchar );

The  wctomb  function  determines  the    number    of  bytes  required to
represent the multibyte  character corresponding to the code contained
in  "wchar".  If "s" is not a NULL  pointer,  the  multibyte character
representation    is  stored  in the  array  pointed  to by "s". At most
MB_CUR_MAX characters will be stored.
::::WRITE
#include \<io.h>
int write( int handle, const char *buffer, int len );

The write  function  writes data at the  operating system level.   The
number    of  bytes  transmitted    is  given  by "len" and the data to be
transmitted is located at the address specified by "buffer".

The "handle" value is returned by the open function.   The access mode
must have  included  either  O_WRONLY or O_RDWR when the open function
was invoked.

The data is  written  to the file at the end when the file was    opened
with  O_APPEND    included  as part of the access mode; otherwise, it is
written at the current file position for the file in question.      This
file  position can be determined with the tell function and can be set
with the lseek function.

When  O_BINARY is included in the access mode, the data is transmitted
unchanged.   When  O_TEXT is  included in the access mode, the data is
transmitted with extra carriage return characters inserted before each
linefeed character encountered in the original data.
::::Y0
 ->BESSEL
::::Y1
 ->BESSEL
::::YN
 ->BESSEL