===============================================================================
emxlib.doc        emx 0.9c     C LIBRARY REFERENCE                  09-Sep-1996
===============================================================================
                                     Copyright (c) 1990-1996 by Eberhard Mattes

Table of Contents
=================

1      Introduction to the emx C Library Reference
1.1      Preliminary notes
1.2      Libraries
1.3      Headers
2      Dynamic memory allocation
2.1      Allocating blocks
2.2      Deallocating (freeing) blocks
2.3      Resizing blocks
2.4      ISO 9899 standard
2.5      Tiled memory
2.6      Multiple heaps
2.7      Tiled heaps
2.8      Default heaps
2.9      Shared heaps
2.10     Checking heaps
2.11     Other heap-related functions
2.12     Why multiple heaps?
2.13     Non-contiguous heaps
2.14     Replacing malloc()
3      General terminal interface
3.1      System V terminal interface
3.2      POSIX.1 terminal interface
3.3      Terminal parameters
4      Signal processing
4.1      Signal actions
4.2      Blocking signals
4.3      Signal processing models
4.4      Available signals
4.5      Catching signals
4.6      Signals generated by the system
4.6.1      SIGINT and SIGBREAK
4.6.2      SIGFPE
4.6.3      SIGTERM
4.6.4      SIGCHLD
4.6.5      SIGTRAP
4.7      Sending signals to other processes
4.8      Inheriting signal handlers
5      Sockets
5.1      Porting Unix applications
5.2      Porting OS/2 applications
6      Floating-point math
7      Mutex semaphores
7.1      _fmutex semaphores
7.2      _rmutex semaphores
7.3      _smutex semaphores
8      Function reference
9      Variable reference
10     System calls


1 Introduction to the emx C Library Reference
=============================================


1.1 Preliminary notes
---------------------

- `C90' is short for ISO 9899-1990, the ANSI/ISO standard for the C
  programming language

- `C9X' is short for the upcoming version of ISO 9899

- Not all functions declared in the headers are implemented.

- By default, text mode is used for files.  See fread() and fwrite()
  for details.  The default can be globally changed to binary mode by
  linking with binmode.o or binmode.obj (-Zbin-files option of GCC).

- See the description of g_mode() for general information about the
  graphics library.

- See the description of v_init() for general information about the
  video library.

- See the description of wm_init() for general information about the
  window manager functions.


1.2 Libraries
-------------

The following emx libraries are provided:

st/c

    The single-thread C library.  This library includes the ISO C
    library functions, Unix extensions and emx extensions.  Only
    functions are included which are common to all types of
    applications and DLLs.  See also c_app, c_dllnrt, c_dllrt, and
    c_dllso.

mt/c

    The multithread C library.  See library st/c.  This library is
    used instead of library st/c if the -Zmt or -Zmts option is
    specified.

c_alias

    Aliases for non-ISO-C symbols.  This library maps, for instance,
    eof() to _eof().  The static and dynamic C libraries contain these
    symbols with one underscore prepended to the names.  In
    consequence, redefining a non-ISO-C library function should be
    possible even if the C library uses the function internally.
    (c_alias has not been merged into the static, dynamic, and import
    libraries due to restrictions in LINK386, ar, and emxomfar.)

st/c_app

    This library is used in addition to st/c for building a
    single-thread statically linked application.

st/c_app_p

    Like library st/c_app, with profiling hooks.  This library is used
    instead of library st/c_app if the -pg option is specified.

mt/c_app

    This library is used in addition to st/c for building a
    multithread statically linked application.

c_dllrt

    This library is used in addition to st/c for building a DLL
    without runtime environment.

st/c_dllrt

    This library is used in addition to st/c for building a
    single-thread custom C runtime DLL.

mt/c_dllrt

    This library is used in addition to mt/c for building a
    multithread custom C runtime DLL.

st/c_dllso

    This library is used in addition to mt/c for building a
    single-thread stand-alone DLL.  Such a DLL has its own runtime
    environment.

mt/c_dllso

    This library is used in addition to mt/c for building a
    multithread stand-alone DLL.  Such a DLL has its own runtime
    environment.

st/c_import

    Import library for emxlibcs.dll.  This library is used instead of
    libraries c, c_app, and gcc if the -Zcrtdll option without the
    -Zmt option is specified.

mt/c_import

    Import library for emxlibcm.dll.  This library is used instead of
    libraries c, c_app, and gcc if the -Zcrtdll and -Zmt options (or
    -Zmtd) are specified.

st/c_p

    The single-thread C library, with profiling hooks.  See library
    st/c.  This library is used instead of library st/c if the -pg
    option is specified.

c_static

    Code which must be statically linked when linking the C library
    dynamically.  This library is searched if the -Zcrtdll option of
    GCC is specified.

st/emx

    System call interface to emx for single-thread programs.  For
    instance, this library translates the __open() system call to
    system call 0x2b of emx.  When using this library, emx.dll is
    required under OS/2.  This library is always required for DOS
    programs.

mt/emx

    System call interface to emx for multithread programs.  For
    instance, this library translates the __open() system call to
    system call 0x2b of emx.  When using this library, emx.dll is
    required.

emx2

    Import library for emx.dll.  This library is used by libraries
    emx.a, emx.lib, os2.a, and os2.lib (unless sys.lib is used, see
    -Zsys).

emxio

    Import library for emxio.dll.  When using hardware port I/O
    functions such as _outp8() with non-standard libraries, you may
    have to use this library.  With the standard emx libraries,
    -lemxio is not required.  -lemxio must not be used if the program
    should also run under DOS.

end.lib

    Library defining the edata, end, and etext symbols.  ld
    automatically defines these symbols, therefore there is no end.a
    library.  GCC uses -lend if -Zomf is given on the command line.

g

    Dummy debugging library.  GCC uses -lg if -g is given on the
    command line.

gcc

    Compiler helper functions for GCC.  The functions of library gcc
    are duplicated in emxlibcm.dll and emxlibcs.dll.  As library gcc
    requires functions from library c and library c requires functions
    from library gcc, -lgcc must be given twice on the command line of
    the Unix-style linker: -lgcc -lc -lgcc.

gcc_p

    Compiler helper functions for GCC, with profiling hooks.  See
    library gcc.  This library is used instead of library gcc if the
    -pg option is specified.

graph

    Graphics library

m

    Dummy math library.  This library is provided for makefile
    compatibility; it isn't required as the math functions are
    contained in library c.

st/malloc1

    Old malloc() library of emx 0.9b and older, single-thread.  This
    library is provided as fall back in case the new malloc()
    implementation turns out not to work properly.

mt/malloc1

    Old malloc() library of emx 0.9b and older, multithread.  This
    library is provided as fall back in case the new malloc()
    implementation turns out not to work properly.

moddef

    Functions for reading module definition files.  See _md_open() for
    details.  This library can be used for single-thread programs and
    multithread programs.

omflib

    Functions for reading and creating OMF (Object Module Formats)
    libraries, that is, .lib files.

os2

    Import library for OS/2 API.  This library is not a pure import
    library, it also contains static code for DosGetMessage and
    DosQueryMessageCP and for the 32-bit wrappers.  emx2.a, emx2.lib,
    or sys.lib is required by the 32-bit wrappers.

os2_p

    Profiling hooks and import definitions for OS/2 API.  See library
    os2.  This library is used instead of library os2 if the -pg
    option is specified.

socket

    Socket library.

st/sys

    System call emulation library for single-thread programs.  This
    library is used instead of emx.a or emx.lib for creating
    stand-alone OS/2 applications (-Zsys).  It is provided in OMF
    style only (st/sys.lib).

mt/sys

    Multithread version of st/sys (see above).  This library is
    provided in OMF style only (mt/sys.lib).  It is used instead of
    st/sys.lib if the -Zmt option is specified.

tmalloc

    Implement _tmalloc() etc. on top of malloc() etc. This library is
    required if you replace the emx implementation of malloc() with an
    implementation of malloc() (GNU malloc, for instance) that has not
    _tmalloc() built in.

video

    Video library.  This library contains the functions declared in
    <sys/video.h> and <sys/winmgr.h>.

wrap

    Import library for emxwrap.dll.  Use this library (-lwrap) to
    reduce the size of your executable file when using 16-bit OS/2 API
    functions.  If you don't use -lwrap, the wrapper functions are
    taken from library os2.


The following dynamic link libraries are provided:
--------------------------------------------------

emx.dll

    This is the emx run-time support.  The import library for emx.dll
    is emx2.

emxio.dll

    Access to hardware ports.  The import library for emxio.dll is
    emxio.

emxlibc.dll

    Forwarder DLL.  This DLL is provided to maintain compatibility of
    existing applications using emxlibc.dll.  Entry points are
    forwarded to emxlibcm.dll.

emxlibcm.dll

    Multithread emx C library.  Contains all functions of the
    libraries mt/c, mt/c_dllrt, and gcc.  For compatibility with
    existing programs, emxlibcm.dll contains dummy functions for port
    I/O, though these didn't work in emxlibc.dll of emx 0.8e.  The
    import library for emxlibcm.dll is mt/c_import.

emxlibcs.dll

    Single-thread emx C library.  Contains all functions of the
    libraries st/c, st/c_dllrt, and gcc.  The import library for
    emxlibcs.dll is st/c_import.

emxwrap.dll

    32-bit wrappers for 16-bit OS/2 API functions.  This DLL uses
    emx.dll.  The import library for emxwrap.dll is wrap.  The
    functions contained in emxwrap.dll are also available for static
    linking in library os2.


1.3 Headers
-----------

This section briefly describes the headers.

<a_out.h>

    Contains definitions for the a.out file format (.o and executable
    files).

<alloca.h>

    Makes the alloca() built-in function available.

<ar.h>

    Contains definitions for the archive file format (.a files).

<assert.h>

    Implements assertions for debugging (C90): assert().

<conio.h>

    Defines getch() and getche() for porting MS-DOS programs.

<ctype.h>

    Character classification macros and functions.  Letter case
    conversion.  If you include this header, you get the macro (and
    inline) versions of the routines.  Otherwise, you get the function
    versions.

    C90 functions and macros: isalnum(), isalpha(), iscntrl(),
    isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(),
    isupper(), isxdigit(), tolower(), toupper().

    Additional functions and macros: isascii(), _tolower(),
    _toupper().

<curses.h>

    Declarations and definitions of the BSD curses screen library.

<dirent.h>

    Functions for reading directories.

    POSIX.1 functions: closedir(), opendir(), readdir(), rewinddir().

    Additional functions: seekdir(), telldir().

<dos.h>

    Declares the _int86() function and associated structures.

<errno.h>

    Declares the errno object and defines error code constants (C90).

<fcntl.h>

    Defines file mode constants such as O_RDONLY and other constants.
    Declares the fcntl() and flock() functions.  Includes
    <sys/fcntl.h>.

<float.h>

    Floating point constants and functions for controlling the math
    coprocessor (C90).

    Non-standard functions: _clear87(), _control87(), _fpreset(),
    _status87().

<fnmatch.h>

    Declares the fnmatch() function and defines constants for
    fnmatch() (POSIX.2).

<ftw.h>

    File tree walk: ftw().  Apply a function to all files in a
    directory tree.

<getopt.h>

    Declares getopt() for parsing command line options (POSIX.2).

<glob.h>

    Declares the glob() and globfree() functions and defines the
    glob_t type and constants for glob() (POSIX.2).

<graph.h>

    Declares the emx graphics library functions and defines associated
    constants.

    Functions: g_box(), g_clear(), g_clip(), g_ellipse(), g_get(),
    g_hline(), g_line(), g_lock(), g_mode(), g_modeset(), g_polygon(),
    g_set(), g_triangle(), g_unlock(), g_unlockall(), g_vgapal(),
    g_vline(), g_waitv(), g_wmode().

<grp.h>

    Declares the getgrgid() and getgrnam() functions and defines
    struct group (POSIX.1).

<ieee.h>

    Constants describing the IEEE floating point format used under
    emx.

<io.h>

    Declares low-level I/O functions.

    Functions: access(), chmod(), chsize(), close(), creat(), _crlf(),
    dup(), dup2(), eof(), filelength(), fstat(), fsync(), ftruncate(),
    _imphandle(), ioctl(), isatty(), _isterm(), lseek(), mkstemp(),
    mktemp(), open(), pipe(), read(), remove(), rename(), _seek_hdr(),
    select(), setmode(), sopen(), stat(), tell(), truncate(), umask(),
    unlink(), write().

<limits.h>

    Data type limit constants (C90).

<locale.h>

    Functions and constants for localization.

    C90 functions: localeconv(), setlocale().

<malloc.h>

    Declares functions for dynamic memory allocation.  For
    portability, use <stdlib.h> instead of <malloc.h>.

    C90 functions (note that <malloc.h> is not a C90 header):
    calloc(), free(), malloc(), realloc().

    Functions for allocating tiled memory: _tcalloc(), _tfree(),
    _tmalloc(), _trealloc().

    Additional non-standard functions: _expand(), _heapchk(),
    _heapmin(), _heapset(), _msize().

<math.h>

    Declares floating-point functions.

    C90 functions: acos(), asin(), atan(), atan2(), ceil(), cos(),
    cosh(), exp(), fabs(), floor(), fmod(), frexp(), ldexp(), log(),
    log10(), modf(), pow(), sin(), sinh(), sqrt(), tan(), tanh().

    Functions proposed for C9X: acosl(), asinl(), atanl(), atan2l(),
    ceill(), copysign(), copysignf(), copysignl(), cosl(), coshl(),
    expl(), fabsl(), floorl(), fmodl(), frexpl(), hypot(), hypotl(),
    ldexpl(), logl(), log10l(), modfl(), nextafter(), nextafterf(),
    nextafterl(), powl(), rint(), rintl(), sinl(), sinhl(), sqrtl(),
    tanl(), tanhl(), trunc(), truncl().

    Macros proposed for C9X: fpclassify(), isfinite(), isnan(),
    isnormal(), signbit().

    Other functions: atof(), _atofl(), cbrt(), _cbrtl().

<memory.h>

    Declares functions dealing with blocks of memory.  New programs
    should use <string.h> instead.

    Functions: memccpy(), memchr(), memcmp(), _memcount(), memcpy(),
    _memdif(), memicmp(), memmove(), _memrchr(), memset(), _memswap().

<os2.h>

    Include this header to get all or part of the OS/2 constants,
    macros and functions.  Includes either <os2emx.h> or <os2tk.h>.
    Either change <os2.h> or #define USE_OS2_TOOLKIT_HEADERS in your
    source file to use the header files of the Programmer's Toolkit
    for OS/2 2.x (an IBM product).

<os2emx.h>

    A subset of the OS/2 definitions and declarations.  This header
    file is included by <os2.h> unless you choose to use the header
    files of the Programmer's Toolkit for OS/2 2.x (an IBM product).

<os2thunk.h>

    Thunking support, included by <os2.h>.  You don't have to include
    this header in your programs unless you want to create thunks
    without including <os2.h>.

<os2tk.h>

    Makes the header files of the Developer's Toolkit for OS/2 2.x
    usable for emx and GCC.

<process.h>

    Process management.  Includes <sys/process.h>.

    Functions: abort(), atexit(), execl(), execle(), execlp(),
    execlpe(), execv(), execve(), execvp(), execvpe(), exit(),
    _exit(), fork(), getpid(), getppid(), spawnl(), spawnle(),
    spawnlp(), spawnlpe(), spawnv(), spawnve(), spawnvp(), spawnvpe(),
    system(), wait(), hpt{waitpid()}.

<pwd.h>

    Password management.

    POSIX.1 functions: getpwnam(), getpwuid().

    Additional functions: endpwent(), getpass(), _getpass1(),
    _getpass2(), getpwent(), setpwent().

<setjmp.h>

    Non-local jumps.  Defines jmp_buf and sigjmp_buf.

    C90 functions: longjmp(), setjmp().

    POSIX.1 functions: siglongjmp(), sigsetjmp().

<sgtty.h>

    Empty file.  emx doesn't have a BSD-style general terminal
    interface.

<share.h>

    Constants for file sharing.

<signal.h>

    Signal processing.  Includes <sys/signal.h>.

    C90 functions: signal(), raise().

    POSIX.1 functions: kill(), pause(), sigaction(), sigaddset(),
    sigdelset(), sigemptyset(), sigfillset(), sigismember(),
    sigpending(), sigprocmask(), sigsuspend().

<stdarg.h>

    Macros to implement functions with variable number of arguments --
    ISO C version.

    C90 macros: va_start(), va_arg(), va_end().

<stddef.h>

    Various definitions.

    C90 macros: offsetof().

    Other macros: _threadid.

<stdio.h>

    Stream I/O library.

    C90 functions: clearerr(), fclose(), feof(), ferror(), fflush(),
    fgetc(), fgetpos(), fgets(), fopen(), fprintf(), fputc(), fputs(),
    fread(), freopen(), fscanf(), fseek(), fsetpos(), ftell(),
    fwrite(), getc(), getchar(), gets(), perror(), printf(), putc(),
    putchar(), puts(), remove(), rename(), rewind(), scanf(),
    setbuf(), setvbuf(), sprintf(), sscanf(), tmpfile(), tmpnam(),
    ungetc(), vfprintf(), vprintf(), vsprintf().

    POSIX.1 functions: fdopen(), fileno().

    POSIX.2 functions: pclose(), popen().

    Additional functions: cuserid(), _fassign(), fcloseall(),
    fgetchar(), flushall(), fputchar(), _fseek_hdr(), _fsetmode(),
    _fsopen(), getw(), _mfclose(), _mfopen(), putw(), setbuffer(),
    snprintf(), tempnam(), vfscanf(), vscanf(), vsnprintf(),
    vsscanf().

<stdlib.h>

    Various library functions and global variables.  Includes
    <malloc.h>.

    C90 string conversion functons: atof(), atoi(), atol(), strtod(),
    strtol(), strtoul().

    C90 functions for generating pseudo-random sequences: rand(),
    srand().

    C90 memory management functions: calloc(), free(), malloc(),
    realloc().

    C90 functions for searching and sorting: bsearch(), qsort().

    C90 integer arithmetic functions: abs(), div(), labs(), ldiv().

    C90 multibyte character functions: mblen(), mbstowcs(), mbtowc(),
    wcstombs(), wctomb().

    Other C90 functions: abort(), atexit(), exit(), getenv(),
    system().

    String conversion functions proposed for C9X: strtof(), strtold().

    Additional string conversion functions (to and from strings):
    _atofl(), _atoll(), gcvt(), _itoa(), _lltoa(), _ltoa(),
    _strtoll(), _strtoull(), _ulltoa(), _ultoa().

    Additional functions for generating pseudo-random sequences:
    initstate(), random(), setstate(), srandom().

    Additional memory management functions: brk(), _expand(),
    _heapchk(), _heapmin(), _heapset(), _msize(), sbrk().

    Additional functions for allocating tiled memory: _tcalloc(),
    _tfree(), _tmalloc(), _trealloc().

    Additional functions for searching and sorting: heapsort().

    Additional integer arithmetic functions: _lldiv(), _uldiv(),
    _ulldiv().

    Additional functions for managing directories and disk drives:
    chdir(), _chdir2(), _chdrive(), _filesys(), getcwd(), _getcwd1(),
    _getcwd2(), _getvol(), getwd(), mkdir(), rmdir().

    Additional functions for processing file names: _abspath(),
    _defext(), _fncmp(), _fnexplode(), _fnexplodefree(),
    _fngetdrive(), _fnisabs(), _fnisrel(), _fnlwr(), _fnlwr2(),
    _fnslashify(), _fullpath(), _getdrive(), _getext(), _getext2(),
    _getname(), _makepath(), _path(), _remext(), _rfnlwr(), _sfnlwr(),
    _splitpath().

    Additional functions for multithread programs: _beginthread(),
    _endthread(), _gettid(), _threadstore().

    Additional functions for managing the command line: _envargs(),
    _response(), _wildcard().

    Miscellaneous additional functions: alarm(), _core(), _execname(),
    _exit(), getpagesize(), _getsockhandle(), perror(), putenv(),
    _read_kbd(), _scrsize(), _searchenv(), sleep(), _sleep2(),
    _splitargs(), swab(), _swchar(), _syserrno(), ulimit().

<string.h>

    This header declares functions for processing null-terminated
    strings and for processing arrays of characters and objects
    treated as arrays of characters.

    C90 functions for processing null-terminated strings: strcat(),
    strchr(), strcmp(), strcoll(), strcpy(), strcspn(), strerror(),
    strlen(), strncat(), strncmp(), strncpy(), strpbrk(), strrchr(),
    strspn(), strstr(), strtok(), strxfrm().

    C90 functions for processing arrays of characters: memchr(),
    memcmp(), memcpy(), memmove(), memset().

    Non-standard functions for processing null-terminated strings:
    strdup(), stricmp(), strlwr(), _strncpy(), strnicmp(), strnset(),
    strrev(), strsep(), strset(), strupr().

    Non-standard functions for processing arrays of characters:
    memccpy(), _memcount(), _memdif(), memicmp(), _memrchr(),
    _memswap().

<strings.h>

    This header defines the BSD string and memory functions and
    includes <string.h>.

    BSD functions: bcmp(), bcopy(), bzero(), ffs(), index(), rindex().

<termcap.h>

    Terminal data base (FSF).

<termio.h>

    Defines struct termio and constants for the general terminal
    interface (System V variant).  Includes <sys/termio.h>.

<termios.h>

    Declares functions and defines struct termios and constants for
    the general terminal interface (POSIX.1 variant).

    POSIX.1 functions: cfgetispeed(), cfgetospeed(), cfsetispeed(),
    cfsetospeed(), tcdrain(), tcflow(), tcflush(), tcgetattr(),
    tcsendbreak(), tcsetattr().

<time.h>

    Functions and structures for converting time values between
    various formats.

    C90 functions: asctime(), ctime(), clock(), difftime(), gmtime(),
    localtime(), mktime(), strftime(), time().

    POSIX.1 functions: tzset().

    Additional functions: strptime().

<ulimit.h>

    Declares the ulimit() function and defines constants for ulimit().

<umalloc.h>

    Declares heap-specific functions for dynamic memory allocation.
    See _ucreate2() for details.

    Functions for allocating memory: _ucalloc(), _umalloc().

    Functions for allocating tiled memory: _utcalloc(), _utmalloc().

    Functions for maintaining heaps: _theapmin(), _uaddmem(),
    _uclose(), _ucreate() _ucreate2(), _udefault(), _udestroy(),
    _uheapchk(), _uheapmin(), _uheapset(), _uopen(), _utdefault().

    Functions for getting information about blocks and heaps:
    _mheap(), _uheap_type(), _uheap_walk(), _uheap_walk2(), _ustats().

    Functions declared in <malloc.h> which can also be used on blocks
    allocated by heap-specific functions: _expand(), free(), _msize(),
    realloc().

<unistd.h>

    Various POSIX.1-related definitions and declarations.

    POSIX.1 functions: access(), alarm(), chdir(), close(), cuserid(),
    dup(), dup2(), execl(), execle(), execlp(), execv(), execve(),
    execvp(), _exit(), fork(), fpathconf(), getcwd(), getegid(),
    geteuid(), getgid(), getgroups(), getlogin(), getpgrp(), getpid(),
    getppid(), getuid(), isatty(), lseek(), pathconf(), pause(),
    pipe(), read(), rmdir(), setgid(), setpgid(), setsid(), setuid(),
    sleep(), sysconf(), tcgetpgrp(), tcsetpgrp(), ttyname(), unlink(),
    write().

    POSIX.2 functions: getopt().

    Additional functions: brk(), getpass(), _getpass1(), _getpass2(),
    mkstemp(), mktemp(), profil(), sbrk().

<utime.h>

    Declares utime() and defines struct utimbuf.  Includes
    <sys/utime.h>.

<varargs.h>

    Functions with variable number of arguments -- traditional Unix
    version.  New programs should use <stdarg.h> instead of
    <varargs.h>, therefore the macros of <varargs.h> are not
    documented here.

<emx/bigint.h>

    Internal header file for the implementation of decimal to binary
    and binary to decimal conversions of floating point numbers.
    Application programs should never include this header -- it's used
    for library modules only.

<emx/float.h>

    Internal header file for the implementation of floating point
    math.  Application programs should never include this header --
    it's used for library modules only.

<emx/io.h>

    Internal header file for the implementation of low-level I/O and
    stream I/O.  Application programs should never include this header
    -- it's used for library modules only.

<emx/nls.h>

    Internal header file for the implementation of some functions of
    <sys/nls.h>.  Application programs should never include this
    header -- it's used for library modules only.

<emx/pwd.h>

    Internal header file for the implementation of some functions of
    <pwd.h>.  Application programs should never include this header --
    it's used for library modules only.

<emx/startup.h>

    Internal header file for the implementation of startup and cleanup
    code.  Application programs should never include this header --
    it's used for library modules only.

<emx/syscalls.h>

    Declare emx syscall functions and defines constants and types for
    emx syscalls.  Application programs should never include this
    header -- it's used for library modules only.

<emx/thread.h>

    Internal header file for the implementation of thread-local
    variables used by library functions.  Application programs should
    never include this header -- it's used for library modules only.

<emx/time.h>

    Internal header file for the implementation of time-related
    library functions.  Application programs should never include this
    header -- it's used for library modules only.

<emx/umalloc.h>

    Internal header file for the implementation of malloc().
    Application programs should never include this header -- it's used
    for library modules only.

<sys/builtin.h>

    Defines inline assembly functions for some low-level tasks.
    Several of these functions are provided for compatibility with
    functions declared in the <builtin.h> header of IBM's Visual Age
    C++ 3.0 compiler (VAC++).

    Functions for RAM semaphores: __cxchg(), __lxchg(), __sxchg().

    Functions for disabling and enabling interrupts: __disable(),
    __enable().

    Functions for bit operations: _crotl(), _crotr(), __fls(),
    _lrotl(), _lrotr(), _srotl(), _srotr().

<sys/dir.h>

    Prerequisite header: <sys/types.h>You should use <dirent.h>
    instead of <sys/dir.h>.

    Functions: closedir(), readdir(), rewinddir(), opendir(),
    seekdir(), telldir().

<sys/dirent.h>

    Defines struct dirent and associated constants.  This header file
    is used by <dirent.h>, you don't have to include <sys/dirent.h>
    yourself.

<sys/dirtree.h>

    Declares the emx directory tree functions and defines associated
    constants and types.

    Functions: _dt_free(), _dt_read(), _dt_sort(), _dt_split().

<sys/ea.h>

    Defines struct _ea and declares the emx functions for low-level
    extended attributes handling.  See also <sys/ead.h> -- don't
    confuse these two different approaches to extended attributes.

    Functions: _ea_free(), _ea_get(), _ea_put(), _ea_remove().

<sys/ead.h>

    Declares the _ead type and the emx functions for high-level
    extended attributes handling via `EA descriptors'.  See also also
    <sys/ea.h> -- don't confuse these two different approaches to
    extended attributes.

    Functions: _ead_add(), _ead_clear(), _ead_copy(), _ead_count(),
    _ead_create(), _ead_delete(), _ead_destroy(),
    _ead_fea2list_size(), _ead_fea2list_to_fealist(),
    _ead_fealist_to_fea2list(), _ead_find(), _ead_get_fea2list(),
    _ead_get_flags(), _ead_get_name(), _ead_get_value(),
    _ead_name_len(), _ead_read(), _ead_replace(), _ead_sort(),
    _ead_use_fea2list(), _ead_value_size(), _ead_write().

<sys/emxload.h>

    Declares functions for keeping programs in memory with
    emxload.exe.

    Functions: _emxload_env(), _emxload_this(), _emxload_prog(),
    _emxload_unload(), _emxload_list_start(), _emxload_list_get(),
    _emxload_connect(), _emxload_disconnect(), _emxload_stop().

<sys/fcntl.h>

    Defines file mode constants such as O_RDONLY and other constants.
    Declares the fcntl() and flock() functions.  You should include
    <fcntl.h> instead.

<sys/file.h>

    This header is provided for compatibility with Unix systems -- it
    includes <sys/fcntl.h>.

<sys/fmutex.h>

    Prerequisite header: <sys/builtin.h>

    This header contains definitions and declarations for _fmutex
    semaphores.  _fmutex semaphores are fast RAM semaphores which
    control access to a resources shared by threads or processes.  See
    `_fmutex semaphores' for details.

    Functions: _fmutex_available(), _fmutex_checked_close(),
    _fmutex_checked_create(), _fmutex_checked_open(),
    _fmutex_checked_release(), _fmutex_checked_request(),
    _fmutex_close(), _fmutex_create(), _fmutex_dummy(),
    _fmutex_open(), _fmutex_release(), _fmutex_request().

<sys/hw.h>

    Declares the emx port access and memory access functions.

    Function: _inp8(), _inp16(), _inp32(), _inps8(), _inps16(),
    _inps32(), _memaccess(), _outp8(), _outp16(), _outp32(),
    _outps8(), _outps16(), _outps32(), _outpt(), _outps8dac(),
    _portaccess(), _wait0(), _wait01(), _wait1(), _wait10().

<sys/ioctl.h>

    Declares the ioctl() function and defines various constants to be
    used with ioctl().  This header includes <sys/so_ioctl.h> if a
    TCP/IP-related header such as <sys/socket.h> has been included
    before <sys/ioctl.h>.

<sys/ipc.h>

    This header contains some definitions for System V IPC facilities.
    However, these are not yet implemented in emx.

<sys/kbdscan.h>

    Defines keyboard scan codes.

<sys/moddef.h>

    Declares types and functions for reading module definition files.

    Functions: _md_close(), _md_errmsg(), _md_get_linenumber(),
    _md_get_number(), _md_get_string(), _md_get_token(),
    _md_next_token(), _md_open(), _md_parse(), _md_use_file().

<sys/msg.h>

    This header contains some definitions for System V message queues.
    However, these are not yet implemented in emx.

<sys/nls.h>

    Declares the emx national-language support functions and macros.

    Functions: _nls_init(), _nls_strlwr(), _nls_strupr().

    Macros: _nls_tolower(), _nls_toupper(), _nls_is_dbcs_lead().

<sys/param.h>

    Defines constants such as MAXNAMLEN which describe system
    parameters.

<sys/process.h>

    Process handling.  Application programs should include <process.h>
    instead.  See <process.h> for details.

<sys/ptrace.h>

    Declares the ptrace() function and defines associated constants.

<sys/reg.h>

    Defines register offset constants.  These are usually used with
    ptrace() and for reading core dump files.

<sys/resource.h>

    This header is empty.

<sys/rmutex.h>

    Prerequisite headers: <sys/builtin.h>, <sys/fmutex.h>

    This header contains definitions and declarations for _rmutex
    semaphores.  _rmutex semaphores are registered _fmutex semaphores.
    See `_fmutex semaphores' for details.

    Functions: _rmutex_available(), _rmutex_checked_close(),
    _rmutex_checked_create(), _rmutex_checked_open(),
    _rmutex_checked_release(), _rmutex_checked_request(),
    _rmutex_close(), _rmutex_create(), _rmutex_dummy(),
    _rmutex_open(), _rmutex_release(), _rmutex_request().

<sys/select.h>

    Defines the fd_set type and macros (FD_SET etc.) for select().

<sys/signal.h>

    Functions and constants for signal processing.  Application
    programs should include <signal.h> instead.

<sys/smutex.h>

    Prerequisite header: <sys/builtin.h>

    This header contains definitions and declarations for _smutex
    semaphores.  _smutex semaphores are very simple RAM semaphores
    which control access to a resources shared by threads or
    processes.  See `_smutex semaphores' for details.

    Functions: _smutex_available(), _smutex_release(),
    _smutex_request().

<sys/socket.h>

    Definitions and declarations related to sockets.

<sys/so_ioctl.h>

    Socket-specific definitions for ioctl().  This header is
    automatically included by <sys/ioctl.h> if a TCP/IP-related header
    such as <sys/socket.h> has been included before <sys/ioctl.h>.

<sys/stat.h>

    Prerequisite header: <sys/types.h>

    Defines struct stat for stat() and fstat().  Defines S_IREAD,
    S_IWRITE and S_IEXEC for open().  Defines S_IFCHR etc. constants
    and S_ISCHR etc. macros for checking file types.  Declares the
    stat() and fstat() functions.

<sys/statfs.h>

    Declares struct statfs -- which is not yet supported by emx.

<sys/termio.h>

    Defines struct termio and constants for the general terminal
    interface (System V variant).

<sys/time.h>

    Declares utimes(), gettimeofday() and settimeofday().

<sys/timeb.h>

    Declares ftime() and defines struct timeb.

<sys/times.h>

    Prerequisite header: <time.h>

    Declares times() and defines struct tms.

<sys/types.h>

    Defines various types such as ino_t for <sys/stat.h>.  Defines the
    fd_set type and macros (FD_SET etc.) for select().

<sys/uio.h>

    Declares struct iovec and the readv() and writev() functions.

<sys/uflags.h>

    Declares the _uflags() function and constants for _uflags().

<sys/user.h>

    Declares struct user which is used by ptrace() and in core dump
    files.  See also <sys/reg.h> and <sys/ptrace.h>.

<sys/utime.h>

    Declares utime() and defines struct utimbuf.  You should include
    <utime.h> instead.

<sys/utsname.h>

    Declares uname() and defines struct utsname.

<sys/video.h>

    Declares the emx video library functions and defines associated
    constants.

    Functions: v_attrib(), v_backsp(), v_clear(), v_clreol(),
    v_ctype(), v_delline(), v_dimen(), v_fclose(), v_fopen(),
    v_getattr(), v_getctype(), v_getline(), v_getxy(), v_gotoxy(),
    v_hardware(), v_hidecursor(), v_init(), v_insline(), v_putc(),
    v_putline(), v_putm(), v_putmask(), v_putn(), v_puts(),
    v_scroll(), v_scrollup(), v_printf(), v_vprintf().

<sys/wait.h>

    Declares wait() and waitpid().  Defines constants and macros for
    using these functions.

<sys/winmgr.h>

    Declares the emx window manager library functions and the
    wm_handle type.  Defines window manager constants.

    Functions for mangaging windows: wm_border(), wm_bottom(),
    wm_close(), wm_close_all(), wm_create(), wm_delete(), wm_dimen(),
    wm_down(), wm_exit(), wm_find(), wm_get_pos(), wm_init(),
    wm_move(), wm_open(), wm_top(), wm_up(), wm_update().

    Functions for managing the cursor: wm_chide(), wm_ctype(),
    wm_cursor(), wm_cvis(), wm_get_cursor(), wm_getx(), wm_getxy(),
    wm_gety(), wm_gotoxy().

    Functions for scrolling: wm_del_char(), wm_del_line(),
    wm_ins_char(), wm_ins_line(), wm_scroll(),

    Functions for output to a window: wm_attrib(), wm_attrib_all(),
    wm_backsp(), wm_clear(), wm_clr_eol(), wm_fclose(), wm_fopen(),
    wm_get_attrib(), wm_printf(), wm_puta_at(), wm_putc(),
    wm_putc_at(), wm_putca(), wm_putca_at(), wm_puts(), wm_puts_at(),
    wm_putsa(), wm_putsa_at(), wm_vprintf(), wm_wrap().


2 Dynamic memory allocation
===========================

Dynamic memory allocation means allocation of objects at runtime where
the lifetime of the objects is independent of the nesting of blocks
and functions.


2.1 Allocating blocks
---------------------

The malloc() function is used to dynamically allocate an object.  You
pass the size of the object to malloc() and malloc will return a
pointer to a block of memory allocated from a heap.  The contents of
the block are indeterminate.  If you need a block of memory
initialized to zeros, use the calloc() function.  calloc() takes two
arguments: the number of objects and the size of one object.  The size
of the block is the product of the two numbers.  Using calloc() can be
more efficient than calling malloc() and zeroing the block with
memset() because calloc() can avoid zeroing the block if it knows that
it already is zeroed.


2.2 Deallocating (freeing) blocks
---------------------------------

When you no longer need the object, you can deallocate it by passing a
pointer to the object to the free() function.  After deallocating a
block, you must no longer use the block.  (Strictly, you are even no
longer allowed to use the pointer to the block.) The memory block can
be reused later by malloc() etc. for other dynamically allocated
objects.


2.3 Resizing blocks
-------------------

The size of blocks allocated with malloc() etc. can be changed with
the realloc() function.  Quite often, the size of a block cannot be
changed in place, that is, the block must be moved to another location
in the heap.  Therefore, realloc() returns a pointer to the new
location of block, which might happen to be equal to the old one.

The _expand() function attempts to resize a block in place, that is,
without moving it.  In most cases, blocks cannot be resized in place.
If resizing the block fails, _expand() does not move the block to
another location.


2.4 ISO 9899 standard
---------------------

Whenever possible, you should use only calloc(), free(), malloc(), and
realloc() for dynamic memory allocation.  All other functions
described here are not defined by the ISO standard for the C
programming language.


2.5 Tiled memory
----------------

16-bit OS/2 API functions have special requirements for the alignment
of objects.  A `tiled' object is an object which meets these
requirements.  The _tmalloc() function dynamically allocates a tiled
object from the tiled default heap.  The _tcalloc() function allocates
a tiled object initialized to zeros.  The _trealloc() function resizes
a tiled object -- the object will remain tiled.  The _tfree() function
deallocates a tiled object allocated with _tmalloc() or _tcalloc().


2.6 Multiple heaps
------------------

The emx C library maintains a runtime heap, from which malloc()
allocates by default and a tiled runtime heap, from which _tmalloc()
allocates by default.  (These two runtime heaps happen to be identical
in the current implementation, so there's in fact only one runtime
heap.)

However, you can create your own heaps in addition to the runtime
heaps.  The interface to multiple heaps is more or less compatible to
the one of IBM's Visual Age C++ compiler.  Definitions and
declarations for using multiple heaps are in the <umalloc.h> header.

To create a heap, you have to reserve a memory area for the heap.
This memory area can be statically allocated, obtained with sbrk(),
obtained with DosAllocMem, or even allocated from another heap.  The
_ucreate() function creates a heap in the memory area you provide and
returns a pointer to the new heap.  Before using the new heap, you
have to open the heap by calling _uopen().

To allocate from a specific heap, call _umalloc() instead of malloc(),
passing a pointer to the heap as first argument.  _ucalloc() allocates
a zero-initialized block from the hea pointed to by the first
argument.

You can use realloc() to resize a block of any heap -- realloc()
automatically determines from which heap the block has been allocated
and will keep the block in that heap.  You can use free() to
deallocate a block from any heap -- free() automatically determines
from which heap the block has been allocated.

If you no longer need a heap, you can close it with _uclose() and then
destroy it with _udestroy().  You are responsible for deallocating the
memory area in which the heap was created; if you allocated the memory
area with DosAllocMem, deallocate it with DosFreeMem.

Note that only memory obtained with brk() and sbrk() is dumped into
the core file.  Heaps in memory objects allocated with DosAllocMem are
not visible when performing post-mortem debugging.


2.7 Tiled heaps
---------------

The _utmalloc() function allocates a tiled object from a heap which is
not tiled.  Objects allocated with _utmalloc() can be resized with
realloc() and can be dealllocated with free().  _utcalloc() allocates
a tiled object initialized to zeros.  Note that allocating tiled
objects from a regular (untiled) heap may increase fragmentation of
the heap.

You can create a tiled heap by passing the _HEAP_TILED flag to
_ucreate().  All objects allocated from a tiled heap are tiled
objects.  Again, realloc() and free() can be used instead of
_trealloc() and _tfree(), respectively.


2.8 Default heaps
-----------------

The main thread and each thread created with _beginthread() has its
own two pointers to its two default heaps (regular and tiled), that
is, different threads can have different default heaps.  Do not
confuse the default heaps of a thread with the runtime heaps; the
runtime heaps are special heaps maintained by the C library.
Initially, each thread has the runtime heap as its default heap and
the tiled runtime heap as its tiled default heap.  (Note that the two
runtime heaps happen to be identical in the current implementation,
that is, the two heap pointers of a thread initially point to the same
heap, the runtime heap.)

For each thread, you can select a default heap with the _udefault()
function which takes a pointer to the heap to be used.  After
selecting a default heap for a thread, all malloc() calls in that
thread will allocate memory from the selected heap.  You can switch
back to the runtime heap by passing _RUNTIME_HEAP to _udefault();
_RUNTIME_HEAP is a pointer to the runtime heap.

For each thread, you can select a tiled default heap with the
_utdefault() function which takes a pointer to the heap to be used.
After selecting a tiled default heap for a thread, all _tmalloc()
calls in that thread will allocate memory from the selected heap.

If a tiled heap is selected as default heap with _udefault(), malloc()
always allocates tiled objects.


2.9 Shared heaps
----------------

Heaps created with _ucreate() can be shared between processes.  To
create a shared heap, allocate shared memory with DosAllocSharedMem
and pass the _HEAP_SHARED flag to _ucreate().  Each process (except
the process which created the shared memory object) which wants to
access such a shared heap must first obtain access to the shared
memory allocated with DosAllocSharedMem.  This is done with
DosGetNamedSharedMem, DosGetSharedMem, or DosGiveSharedMem.  Then,
each process, including the process which created the heap, must
obtain access to the heap.  This is done with _uopen().  _udefault()
can be used to use a shared heap as default heap.

If a shared heap is no longer needed by a process, that process should
close the heap with _uclose() and relinquish access to the shared
memory object with DosFreeMem.  After all processes, including the
process which created the heap, have closed the heap with _uclose(),
the heap can be destroyed with _udestroy().


2.10 Checking heaps
-------------------

Heap corruption is a quite common problem of C programs.  To track
down such errors, you can periodically call the _heapchk() function to
check the default heap and the tiled default heap of the current
thread for consistency.  The _uheapchk() function checks a specific
heap.

Sometimes, programs erroneously depend on the contents of dynamically
allocated blocks.  To debug these problems, you can call _heapset() to
fill all bytes of all free blocks of the default heap and the tiled
default heap with a certain value.  _uheapset() does the same thing
for a specific heap.

The _heap_walk() function calls a user-supplied function for each
block of the default heap and the tiled default heap, passing the
address, size, and status (used or free) of one block per call.  This
can be used to identify memory leaks.  The _uheap_walk() function does
the same thing for a specific heap.


2.11 Other heap-related functions
---------------------------------

The _heapmin() function attempts to minimize the size of the default
heap by deallocating memory areas which are not used for any blocks.
The _theapmin() function attempts to minimize the tiled default heap.
The _uheapmin() function attempts to minimize a specific heap.

You can add memory to a heap by calling the _uaddmem() function.  For
instance, the memory area passed to _uaddmem() can be allocated with
DosAllocMem.

The _msize() function returns the size of the block pointed to by its
argument.  The _mheap() function returns a pointer to the heap
containing the block pointed to by its argument.  For both functions,
the pointer must point to a used object of a heap.

The _ustats() function reports the amount of memory used for a heap,
the total number of allocated bytes, the size of the biggest free
block, etc.


2.12 Why multiple heaps?
------------------------

Using multiple heaps has several advantages:
  If you need a lot of objects of the same size, you can reduce
  fragmentation of memory by creating a separate heap for those
  objects.  Using separate heaps for untiled and tiled objects also
  reduces fragmentation.

- By having different heaps for different threads, access to the heaps
  does not have to be serialized, making the application more
  efficient, especially on machines with multiple CPUs.  Moreover, the
  probability of one thread corrupting another thread's objects is
  reduced if objects are allocated in different heaps for different
  threads.

- You can deallocate all objects of a heap at once, by destroying the
  heap.  Though this is not good programming practice, you can use
  this scheme if you can't keep track of all the pointers.

- You can create heaps shared by multiple processes.


2.13 Non-contiguous heaps
-------------------------

The malloc() implementation of the emx C library supports
non-contiguous memory.  A heap can consist of several non-contiguous
segments.

Currently, there are some restrictions when using a non-contiguous
heap.  See sbrk() for details.


2.14 Replacing malloc()
-----------------------

You can replace the emx implementation of malloc() with an alternate
implementation of malloc() such as GNU malloc.  This is done by
linking with that alternate malloc() library.  Additionally, you have
to link with the tmalloc library which implements _tmalloc() etc. on
top of malloc().  Example:

    gcc -o program.exe src1.c src2.c -lvideo -ltmalloc gmalloc.a

If the linker complains about malloc() being multiply defined, you
probably forgot to link with the tmalloc library.  (There is a hack in
the emx C library which tries to provoke this behavior to guard
against forgetting to link with the tmalloc library.)

You must not replace the emx implementation of malloc() if you are
using a C runtime DLL (emxlibcs.dll, for instance) unless you replace
malloc() in that library.  The application and all DLLs (with the
exception of stand-alone DLLs) must use the same implementation of
malloc().


3 General terminal interface
============================

Both the System V and POSIX.1 terminal interfaces are supported by
emx.

Currently, only the keyboard device is supported.  The file descriptor
used by the terminal interface must refer to the keyboard.  Moreover,
the file descriptor must currently be 0 under DOS.

Both terminal interfaces are not supported with the system call
library sys.lib (-Zsys).

The main implementation-specific difference between the two interfaces
is the usage of the IDEFAULT bit of the c_lflag member of
struct termio and struct termios for diabling the general terminal
interface.  The POSIX.1 terminal interface does not use the IDEFAULT
bit.


3.1 System V terminal interface
-------------------------------

The System V terminal interface uses the TCGETA, TCSETA, TCSETAF,
TCSETAW, TCFLSH, TCSBRK, and TCXONC requests of ioctl() for
controlling terminals.  The TCGETA, TCSETA, TCSETAF, and TCSETAW
requests employ the following structure defined in <sys/termio.h>:

    struct termio
    {
      unsigned int  c_iflag;      /* input modes */
      unsigned int  c_oflag;      /* output modes */
      unsigned int  c_cflag;      /* control modes */
      unsigned int  c_lflag;      /* local modes */
      unsigned int  c_line;       /* unused */
      unsigned char c_cc[NCC];    /* control characters etc. */
    };

If c_lflag includes IDEFAULT, the default operating system input
method is used (including line editing).  Input is always done line by
line.  All other fields of the termio structure are ignored in this
case.

If c_lflag does not include IDEFAULT, UNIX-like input processing is
performed.

All bits of c_oflag, c_cflag, and c_line are currently ignored.


3.2 POSIX.1 terminal interface
------------------------------

The POSIX.1 terminal interface uses cfgetispeed(), cfgetospeed(),
cfsetispeed(), cfsetospeed(), tcdrain(), tcflow(), tcflush(),
tcgetattr(), tcsendbreak(), and tcsetattr().

The tcgetattr() and tcsetattr() functions employ the following
structure defined in <termios.h>:

    struct termios
    {
      tcflag_t c_iflag;           /* input modes */
      tcflag_t c_oflag;           /* output modes */
      tcflag_t c_cflag;           /* control modes */
      tcflag_t c_lflag;           /* local modes */
      cc_t c_cc[NCCS];            /* control characters etc. */
      int c_reserved[4];          /* currently unused */
    };

The POSIX.1 terminal interface is enabled by calling tcsetattr().
Before the first invocation of tcsetattr(), the default operating
system input method is used (including line editing).

All bits of c_oflag, and c_cflag are currently ignored.


3.3 Terminal parameters
-----------------------

This description applies to both the System V and the POSIX.1 terminal
interfaces, unless otherwise indicated.

The following bits of c_iflag are used by emx in the following
sequence:

IDELETE
        Backspace key generates DEL character (emx extension)

ISTRIP  Clear bit 7 of all input characters

INLCR   Translate linefeed into carriage return

IGNCR   Ignore carriage return

ICRNL   Translate carriage return into linefeed

IUCLC   Convert upper case letters (A-Z) into lower case (a-z)

If IDELETE is set, the two meanings of the backspace key (the one
above the Return key) are swapped: Backspace generates DEL and
Ctrl-Backspace generates Ctrl-H.  If IDELETE is not set, Backspace
generates Ctrl-H and Ctrl-Backspace generates DEL.  The IDELETE bit
applies only to the backspace key and does not affect other methods of
entering Ctrl-H or DEL.

The following bits of c_lflag are used by emx:

IDEFAULT
        Disable special processing for the terminal interface (emx
        extension, this bit is always clear for the POSIX.1 terminal
        interface).  If this bit is set, the default operating system
        input method is used (including line editing).  For the System
        V terminal interface, this bit is initially set

ISIG    Enable signal processing (see VINTR and VQUIT)

ICANON  Read input line by line, enable line editing

ECHO    Echo input

ECHOK   Echo CR/LF after VKILL

The c_cc array contains control characters.  If an element of c_cc is
set to zero (for the System V terminal interface) or _POSIX_VDISABLE
(for the POSIX.1 terminal interface), no character will trigger the
action associated with that element.

VINTR   Generate SIGINT (in thread 1) if ISIG is set in c_iflag

VQUIT   Generate SIGQUIT (in thread 1) if ISIG is set in c_iflag

The following characters are used if ICANON is set:

VERASE  Delete one character to the left (default: Ctrl-H)

VKILL   Deletes the entire input line (default: Ctrl-U)

VEOF    Indicates end of file (default: Ctrl-D)

VEOL    Indicates end of line (default: none)

VSUSP   Stop process (POSIX.1, ignored by emx)

VSTOP   Suspend output (POSIX.1, ignored by emx)

VSTART  Resume output (POSIX.1, ignored by emx)

The VERASE, VKILL and VEOF characters can be escaped by preceding them
with a backslash.  End of file at the beginning of a line is usually
interpreted as end of input.

The following elements are used if ICANON is not set:

VMIN    Minimum number of characters to be read (default: 6)

VTIME   Time-Out in 0.1 seconds (default: 1)

Note that VMIN and VTIME are not equal to VEOF and VEOL, respectively.
Unix uses the VEOF field for both VEOF and VMIN, the VEOL field for
both VEOL and VTIME.  emx uses separate fields for the four values.

There are four cases for VMIN and VTIME (that is, c_cc[VMIN] and
c_cc[VTIME]):

VMIN = 0, VTIME = 0

    Return all the characters stored in the input buffer.  If there
    are no characters in the buffer, read() returns immediately.
    read() doesn't wait for input.

VMIN = 0, VTIME > 0

    Return after at least one character has been received or after
    waiting for VTIME * 0.1 seconds, whichever happens first.  In the
    latter case, read() will return 0.

VMIN > 0, VTIME = 0

    Return after at least VMIN characters have been received.

VMIN > 0, VTIME > 0

    Return after at least VMIN characters have been received or if no
    characters have been received for VMIN * 0.1 seconds after receipt
    of a character (the time-out applies after at least one character
    has been received and is reset after each character).

In all cases, read() will return as many characters as are available
in the input buffer, up to the number of characters requested in the
read() call.

If O_NONBLOCK (alias O_NDELAY) has been set for the file descriptor
with fcntl(), read() will always immediately return.  If there is not
enough data available with respect to VMIN, read() will immediately
return -1 and set errno to EAGAIN.

If the general terminal interface is enabled, the text/binary mode of
the handle is ignored: the conversions are controlled by c_iflag,
including CR-to-LF conversion and the end-of-file character.

If ICANON is not set, function keys are returned as two characters.
The first one is a null ('\0') character, the second one is the scan
code.  See <sys/kbdscan.h> for scan codes.


4 Signal processing
===================

Signals are conditions that may be reported synchronously or
asynchronously during program execution.  Each signal is associated
with a signal action, which specifies what action to perform when the
signal occurs.


4.1 Signal actions
------------------

Each signal is associated with one of the following actions:

SIG_DFL
        Default signal action.  The action depends on the signal, see
        the table below.

SIG_IGN
        Ignore the signal.

signal-catching function
        Upon receipt of the signal, a signal-catching function (also
        known as signal handler) is called.  The signal number is
        passed as the only argument to the signal-catching function.
        Before the signal-catching funcion is called, the signal is
        blocked or the signal action is reset to SIG_DFL, depending on
        the signal processing model.

The signal action can be changed with the signal() and sigaction()
functions.  The signal action for SIGKILL is SIG_DFL and cannot be
changed.  Signal actions are private to each thread of multithread
programs.

If a signal which isn't ignored (that is, SIG_DFL or handler
installed) occurs while calling read() with the general terminal
interface enabled, -1 will be returned by read() and errno will be set
to EINTR.  The buffer will flushed.

For all signals, the initial signal handler is SIG_DFL (unless SIG_IGN
is inherited from the parent process), sa_mask is 0, and sa_flags is
SA_ACK.  Initially, all signals are not blocked.

Only certain library functions can be called by a signal-catching
function.  All other library functions are considered to be unsafe.
Calling an unsafe function in a signal-catching function which
interrupted an unsafe function causes undefined behavior.


4.2 Blocking signals
--------------------

Signals can be blocked with the sigprocmask() function.  If a signal
is generated while it is blocked, it won't be delivered until
unblocked, that is, the generated signal will be pending while the
signal is blocked.  As soon as the signal is unblocked, the pending
signal will be delivered.  At most one signal of each kind can be
pending, that is, if a signal is generated twice while it is blocked,
it will be delivered only once as soon as it will be unblocked.
However, SIGCHLD will be stay pending until termination status for all
terminated child processes has been fetched with wait() or waitpid().
The action taken on delivery is determined by the signal action in
effect when the signal is delivered, not when the signal is generated.
If a signal like SIGILL is caused by an exception while it is blocked,
the default action will be taken.


4.3 Signal processing models
----------------------------

The following signal processing models are available:

emx     On entry to a signal handler, the signal is blocked.  To
        unblock (acknowledge) the signal,

            signal (signo, SIG_ACK);

        must be called (by the signal handler, usually), otherwise
        that signal cannot be delivered again.  For compatibility with
        existing emx programs, this model is the default.

System V
        On entry to a signal handler, the action for the signal is set
        to SIG_DFL.  The signal handler has to be reinstalled with
        sigaction() or signal().  Note that there is a timing window;
        for instance, the process will be terminated if two SIGINT
        signals occur in quick succession.

BSD and POSIX.1
        On entry to a signal handler, the signal is blocked.  It will
        be unblocked automatically when the signal handler returns.

With the system call library sys.lib (-Zsys), only the `emx' signal
processing model is available with signal(); however, sigaction() is
fully supported.

When using signal() to install a signal handler, the signal processing
model for that signal is by default `emx'.  To use the `System V'
model for signal(), link with sigsysv.o by using the -Zsysv-signals
option of GCC.  To use the `BSD' model for signal(), link with
sigbsd.o by using the -Zbsd-signals option of GCC.  -Zsysv-signals and
-Zbsd-signals cannot be used with -Zsys.

When using sigaction() to install a signal handler, the signal
processing model for that signal is `BSD', which conforms to POSIX.1.
The `emx' model can be selected by setting the SA_ACK bit of the
sa_flags member of struct sigaction.  The `System V' model can be
selected by setting the SA_SYSV bit of the sa_flags member of
struct sigaction.


4.4 Available signals
---------------------

The following signals are defined by emx:

    Signal     SIG_DFL   Standard  Description
    
    SIGHUP    terminate  POSIX.1   Hangup
    SIGINT    terminate  C90       Interrupt (Ctrl-C or Ctrl-Break)
    SIGQUIT     core     POSIX.1   Quit
    SIGILL      core     C90       Illegal instruction
    SIGTRAP     core               Single step (debugging)
    SIGABRT     core     C90       abort ()
    SIGEMT      core               EMT instruction
    SIGFPE      core     C90       Floating point exception
    SIGKILL   terminate  POSIX.1   Kill process, cannot be caught or ignored
    SIGBUS      core               Bus error
    SIGSEGV     core     C90       Segmentation violation
    SIGSYS      core               Invalid argument to system call
    SIGPIPE   terminate  POSIX.1   Broken pipe
    SIGALRM   terminate  POSIX.1   Alarm lock
    SIGTERM   terminate  C90       Termination, process killed
    SIGUSR1    ignore    POSIX.1   User-defined signal #1
    SIGUSR2    ignore    POSIX.1   User-defined signal #2
    SIGCHLD    ignore    POSIX.1   Death of a child process
    SIGCLD     ignore    SysV      Synonym for SIGCHLD
    SIGBREAK  terminate            Break (Ctrl-Break)

The SIG_DFL column gives the default action for the signals, that is,
when the signal action is SIG_DFL:

terminate
        Terminate the process with return code 3.

core    Dump core and terminate the process.  A file whose name is
        `core' will be written in the current working directory.  A
        `core' file contains a memory dump and the values of the
        registers at the time the signal was delivered.  It can be
        used for post-mortem debugging.  If LINK386 was used for
        linking, no core dump file will be written.

ignore  The signal is ignored, the process will be continued at the
        place it was interrupted.


4.5 Catching signals
--------------------

You can use sigaction() or signal() to set signal handlers for all
signals but SIGKILL.

If a signal handler returns, further processing depends on how the
signal was generated.  If the signal was generated by raise() or
kill(), processing will continue where it was interrupted.  If the
signal was generated by an exception (this applies to signals SIGILL,
SIGSEGV, SIGFPE), core will be dumped and the process will be
terminated with return code 3.

If LINK386 was used for linking, no core dump file will be written.

In the `emx' signal model, the signal handler should call

    signal (signal_number, SIG_ACK);

before returning to unblock the signal.  In the `System V' signal
model, the signal handler should reinstall itself as soon as possible.
However, for SIGCHLD and SIGCLD, wait() or waitpid() must be called
before reinstalling the signal handler.

In the `BSD' and `POSIX.1' signal models, the signal handler need not
unblock the signal as the signal mask which was active before calling
the signal handler is reinstalled after the signal handler returns.

A signal handler usually looks like this in the `emx' signal model:

    void handler (int signo)
    {
      /* Do the work here, the signal is blocked */
      signal (signo, SIG_ACK);
    }

A signal handler usually looks like this in the `System V' signal
model:

    void handler (int signo)
    {
      /* Call wait() or waitpid() here for SIGCHLD aka SIGCLD */
      signal (signo, handler);
      /* Do other work here (the signal is not blocked!) */
    }

A signal handler usually looks like this in the `BSD' and `POSIX.1'
signal models:

    void handler (int signo)
    {
      /* Do the work here, the signal is blocked */
    }

Do not use floating point math in a signal handler if the signal
handler will return to the interrupted code.  File I/O in the signal
handler is also dangerous because a file I/O function could have been
interrupted by the signal.

Only one signal of any type may be pending.  However, SIGCHLD will be
stay pending until termination status for all terminated child
processes has been fetched with wait() or waitpid().


4.6 Signals generated by the system
-----------------------------------

The following signals can be generated by the system:

SIGINT  Ctrl-C typed by user (or VINTR, see `General terminal
        interface')

SIGQUIT
        VQUIT character entered (see `General terminal interface')

SIGILL  Illegal instruction

SIGFPE  Floating point exception or division by zero

SIGSEGV
        Segmentation violation

SIGPIPE
        An attempt is made to write to a pipe or named pipe that is
        not open for reading by any process

SIGALRM
        alarm() timer expired

SIGTERM
        Process termination request

SIGCHLD
        Termination status for a child process is available

SIGBREAK
        Ctrl-Break typed by user

The signals SIGINT, SIGQUIT, SIGALRM, SIGTERM, SIGCHLD and SIGBREAK
are generated in the main thread (thread 1).

The signals SIGILL, SIGFPE and SIGSEGV are generated in the thread
which caused the exception.  If generated by an exception, these
signals are delivered even if blocked and SIG_IGN is treated like
SIG_DFL (however, under OS/2, the core dump will be suppressed by
SIG_IGN).


4.6.1 SIGINT and SIGBREAK
-------------------------

If you want to trap Ctrl-C and Ctrl-Break, register a signal handler
for both SIGINT and SIGBREAK.  Note that typing Ctrl-Break generates
SIGINT unless termio is used under OS/2 with the IDEFAULT bit reset.
With a future release of emx, Ctrl-Break may generate SIGBREAK in all
cases.  Under DOS, SIGINT generated by Ctrl-Break is delivered on
return from the next system call or on return to protected mode from
the next hardware interrupt, whichever comes first; SIGINT generated
by Ctrl-C is delivered on return from the next system call which uses
a DOS call which checks for Ctrl-C.  Under OS/2, SIGINT is generated
and delivered asynchronously.


4.6.2 SIGFPE
------------

By default, all floating point exceptions are masked: The coprocessor
will perform a default action (replace the result with a NaN, for
instance) and continue without generating SIGFPE.  Use _control87() to
enable floating point exceptions.  However, SIGFPE is not reliable.
Under DOS, SIGFPE is not supported for machines not compatible enough
with the industry standard.


4.6.3 SIGTERM
-------------

SIGTERM is implemented only under OS/2.  It is sent to a process if
the user or another process requests the termination of the process.
Continuing the process by calling longjmp() is not a good idea.


4.6.4 SIGCHLD
-------------

SIGCHLD will be generated again if there is termination status
available for a child process on return from the signal handler for
SIGCHLD or when unblocking SIGCHLD or when, for the `System V' signal
processing model, installing a signal handler for SIGCHLD.  That is,
the signal handler must call wait() or waitpid() before returning or
unblocking the signal to avoid infinite invocation of the signal
handler.

Note that SIGCHLD and SIGCLD are synonyms; both names refer to the
same signal.

In contrast to System V, emx currently treats SIG_DFL and SIG_IGN
identically for SIGCHLD, that is, child processes are turned into
zombies when they terminate even if the action for SIGCHLD is SIG_IGN.
Moreover, the behavior of wait() and waitpid() is not affected by the
action for SIGCHLD.

With the system call library sys.lib (-Zsys), SIGCHLD is not generated
by the system.


4.6.5 SIGTRAP
-------------

In addition to the signals which can be generated by the system, the
SIGTRAP signal can be returned by wait() when using ptrace().  SIGTRAP
is returned after single-stepping one instruction.


4.7 Sending signals to other processes
--------------------------------------

Due to OS/2 restrictions, only SIGINT and SIGBREAK can be sent to
arbitrary child processes.  A process can send the other signals only
to itself, see raise(), or to other emx programs (which use emx.dll
under OS/2) being immediate children of the process.


4.8 Inheriting signal handlers
------------------------------

Programs which use emx.dll or emx.exe inherit the signal actions of
the parent process if the parent process also uses emx.dll or emx.exe:
Signals set to SIG_IGN in the parent process will be set to SIG_IGN in
the child process, signals set to SIG_DFL in the parent process will
be set to SIG_DFL in the child process, signals caught in the child
process will be set to SIG_DFL in the child process.

Programs which don't use emx.dll or emx.exe or have not been started
by a program which uses emx.dll or emx.exe will have all signal
actions set to SIG_DFL initially.

Processes created by fork() inherit all signal settings (including
sa_mask and sa_flags) of their parent process.


5 Sockets
=========

emx includes support for sockets of IBM TCP/IP for OS/2 (including the
Internet Access Kit of OS/2 3.0).  The headers files are derived from
NetBSD and are packaged in bsddev.zip.  Some manual pages are packaged
in bsddoc.zip.

To use IBM TCP/IP 4.0, you must compile your applications with
-DTCPIPV4.  Programs which use <net/if.h> are compatible either with
TCP/IP 4.0 or older versions, not both.

Use the -lsocket option to link with the socket library.  Note that
-lsocket, like all -l option, should be given AFTER the source files:

    gcc mymain.c mysub.c -lsocket

emx tries to provide seamless support for sockets, like Unix systems
do.  This approach is quite different from the one taken by IBM's
TCP/IP for OS/2 Toolkit.

Sockets are not supported with the system call library sys.lib
(-Zsys).

The header <sys/so_ioctl.h>, which includes TCP/IP-specific
definitions for ioctl(), is included by <sys/ioctl.h> only if a
TCP/IP-related header such as <sys/socket.h> has been included before
<sys/ioctl.h>.  If you don't want to reorder the #include directives,
define the symbol _EMX_TCPIP before including <sys/ioctl.h>, or
include <sys/so_ioctl.h> directly (however, the last alternative is
not recommended).


5.1 Porting Unix applications
-----------------------------

When porting Unix applications, please note the following
restrictions:

- Socket handles are not inherited across exec*() and spawn*().  (Note
  that a process created by fork() inherits the socket handles of its
  parent process.)  Inheriting socket handles is planned for a future
  release of emx.

- The size of messages is restricted to 32767 bytes (this is a
  limitation of IBM TCP/IP for OS/2).

- Initially, sockets are in binary mode.  Use setmode() to switch to
  text mode.  Text mode applies to read() and write(), only.  recv()
  and send() always use binary mode.

- The functions recvmsg(), sendmsg(), and socketpair() are not
  implemented.


5.2 Porting OS/2 applications
-----------------------------

When porting OS/2 applications written for IBM's TCP/IP for OS/2
Toolkit, please note the following differences:

- Socket handles and file handles share a common handle space which is
  managed by emx.dll.  To obtain the internal socket handle (used by
  IBM TCP/IP for OS/2) associated with a handle, use the
  _getsockhandle() function.

- sock_init() is not required and not implemented.

- Use close() instead of soclose().

- You can use read() and write() on sockets.

- The select() function uses BSD semantics (except for the return
  value) and works for sockets and some other types of file handles.

- Use errno instead of sock_errno(), and perror() instead of
  psock_errno().

- ioctl() of emx takes three arguments whereas the ioctl() function of
  the IBM TCP/IP for OS/2 Toolkit takes four arguments.

- The functions recvmsg(), sendmsg(), and socketpair() are not
  implemented.


6 Floating-point math
=====================

Applications which need to conform to IEEE 754 to obtain the same
results across architectures should call _control87() to change the
precision to a mantissa size of 53 bits:

    _control87 (PC_53, MCW_PC);

The default precision is 64 bits.

By default, all floating-point exceptions are masked off.  You can use
_control87() to enable floating-point exceptions.  SIGFPE will be
raised if an unmasked floating-point exception occurs.

Decimal to binary conversions (scanf(), strtod(), ...) and binary to
decimal conversions (gcvt(), printf(), ...) by default conform to IEEE
754.  Conversion from decimal to binary does not round correctly if
the decimal number has more than DECIMAL_DIG significant digits.
Currently, conversion always rounds to nearest/even, no matter what
rounding mode is selected.

The IEEE 754 conversion routines are slow and big.  To use the faster
and smaller, but inaccurate, conversion routines, use the -Zsmall-conv
option of GCC.  This saves about 14KB for programs which use binary to
decimal conversions, about 11KB for programs which use decimal to
binary conversions, and about 15KB for programs which use both.


7 Mutex semaphores
==================

In addition to OS/2's mutex semaphores (HMTX), the emx runtime library
offers three types of mutex semaphores: _fmutex semaphores, _rmutex
semaphores, and _smutex semaphores.

A mutex semaphore has two states: available and owned.  At most one
thread can own a mutex semaphore.  If a thread request ownership of a
mutex semaphore which is already owned, the thread will be suspended
until the semaphores becomes available.  When ownership of a mutex
semaphore is relinquished, exactly one of the threads waiting for the
semaphore will become the new owner and will resume execution.

For all three types of emx semaphores, ownership of a semaphore is not
tied to a thread, that is, it's not a thread which owns the semaphore.
This is in contrast to OS/2's mutex semaphores.  Deadlock will occur
if ownership of a semaphore is requested twice for the same semaphore
by the same thread without relinquishing ownership of the semaphore
between the two request.  This fact is important to keep in mind in
presence of signals.  Signal handlers must not request semaphores
which can be owned by the interrupted code.  You might want to block
signals before requesting ownership of an emx semaphore.


7.1 _fmutex semaphores
----------------------

_fmutex semaphores are fast RAM semaphores which control access to a
resource shared by threads or processes.  _fmutex semaphores must be
created with _fmutex_create().  The _fmutex_request() function is used
to request ownership of an _fmutex semaphore: If the semaphore is
available, it will be set to owned and _fmutex_request() will return
immediately.  If the semaphore is owned, _fmutex_request() will block
while the semaphore is owned.  When the semaphore becomes available,
one of the threads blocking in _fmutex_request() will unblock and
become the owner of the semaphore.  Ownership of an _fmutex semaphore
is relinquished with _fmutex_release().  If another thread blocks in
_fmutex_request(), _fmutex_release() will unblock one of the blocking
threads.

_fmutex_open() obtains access to a shared _fmutex semaphore created by
another process.  All threads of the process which called
_fmutex_create() have access to the semaphore without calling
_fmutex_open().  _fmutex_close() closes an _fmutex semaphore.
Destroying _fmutex objects without calling _fmutex_close() will cause
a semaphore leak.  _fmutex_available() returns the status of an
_fmutex semaphore without blocking and without changing the state of
the semaphore.

Unlike _rmutex semaphores, _fmutex semaphores are not inherited by
child processes created with fork().  In most cases, _fmutex
semaphores cannot be used by programs which use fork().


7.2 _rmutex semaphores
----------------------

_rmutex semaphores are fast RAM semaphores like _fmutex semaphores.
However, the runtime library keeps track of _rmutex semaphores (the
`r' is for `registered'); in consequence, _rmutex semaphores are
inherited by child processes created with fork().  However, this
applies only to non-shared _rmutex semaphores; shared _rmutex
semaphores (created with the _FMC_SHARED flag) behave like _fmutex
semaphores.  Copying and assigning _rmutex semaphores is not allowed.
An _rmutex object must not go out of scope or be deallocated while the
_rmutex semaphore is open; you must close the semaphore before
destroying the object!  _rmutex semaphores must be created with
_rmutex_create().


7.3 _smutex semaphores
----------------------

_smutex semaphores are very simple RAM semaphores which control access
to a resource shared by threads or processes.  These semaphores need
not be created and destroyed, _smutex objects just have to be
initialized to zero.  _smutex semaphores are implemented with looping
and DosSleep.  Therefore, they should be used only if a collision is
very unlikely, for instance, during initializing.  In all other cases,
_fmutex, _rmutex, or HMTX semaphores should be used.

An _smutex semaphore is available if object of type _smutex is
(explicitely or implicitely initialized to) zero.  The
_smutex_request() function is used to request ownership of an _smutex
semaphore: If the semaphore is available, it will be set to owned and
_smutex_request() will return immediately.  If the semaphore is owned,
_smutex_request() will not return while the semaphore is owned.  When
the semaphore becomes available, one of the threads blocking in
_smutex_request() will unblock sooner or later and will become the
owner of the semaphore.  Ownership of an _smutex semaphore is
relinquished with _smutex_release().  _smutex_available() returns the
status of an _smutex semaphore without blocking and without changing
the state of the semaphore.  An _smutex semaphore can be used by
multiple processes if the _smutex object is in shared memory.


8 Function reference
====================

The functions are listed almost alphabetically.  The origin of most of
the functions is shown in [brackets] at the end of the first line.
Functions which are not available or are limited with the system call
library (-Zsys, sys.lib) are marked * in [brackets].

------------------------------------------------------------------------------
#include <stdlib.h>                                              [C90 POSIX.1]

void abort (void);

    abort() causes abnormal termination of the process, unless the
    signal SIGABRT is caught, and not blocked, and the signal handler
    does not return.  If SIGABRT is blocked, the signal handler won't
    be called.

    If abort() causes termination of the process, open streams and
    file handles will be closed prior to termination of the process.
    The process is terminated by calling raise (SIGABRT) with the
    signal action associated with SIGABRT being set to SIG_DFL.

  Return value:

    abort() does not return.

  Implementation-defined behavior:

    The default action for SIGABRT is to display the message

        Abnormal program termination

    and dump core (for post mortem debugging) and terminate the
    process with return code 3.

  See also: exit(), _exit(), raise(), sigaction(), signal()

------------------------------------------------------------------------------
#include <stdlib.h>     /* use this */                                   [C90]
#include <math.h>       /* or this */

int abs (int n);

    Return the absolute value of N: If N is negative, -N is returned.
    Otherwise, N is returned.

  Return value:

    abs() returns the absolute value of its argument.

  Implementation-defined behavior:

    In-line code is generated for this function.

  See also: fabs(), labs()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _abspath (char *dst, const char *src, int size);

    Construct an absolute path name for the file name or directory
    name pointed to by SRC.  The absolute path name is written to the
    array pointed to by DST.  It is assumed that there are SIZE bytes
    available at DST, this includes the terminating null character.
    If there is an error, -1 is returned.  If _abspath() succeeds, 0
    is returned.  If SIZE is too small, errno is set to ERANGE and -1
    is returned.  DST can be identical to SRC.  Backslashes are
    translated into forward slashes.  The absolute path name is not
    translated to lower case.  If the string pointed to by SRC ends
    with a slash or backslash, the string pointed to by DST will end
    with a slash.

    In contrast to _fullpath(), _abspath() works with non-existing
    paths: it accesses the appropriate drive only for finding out the
    current working directory if necessary.

    _abspath() properly handles DBCS characters.

  Return value:

    0       success

    -1      error

  See also: _fnisabs(), _fnisrel(), _fullpath(), _nls_init()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int access (const char *name, int mode);

    Check whether MODE access is allowed for the file or directory
    whose name is in the string pointed to NAME.  If MODE is F_OK (0),
    access() checks only for existence of the file or directory.  If
    MODE is W_OK (2), access() checks for write permission.  If MODE
    is R_OK (4), access() checks for read permission (always granted
    under DOS and OS/2 if the file exists).  If MODE is R_OK|W_OK (6),
    access() checks for read and write permission.

  Return value:

    access() returns 0 if the file or directory is accessible in mode
    MODE.  Otherwise, access() set errno and returns -1.

  Errors:

    EACCES  Access to the file or directory is not permitted

    ENAMETOOLONG
            The file or directory name is too long

    ENOENT  The file or directory does not exist

  Restrictions:

    access() does not work with devices (errno is set to ENOENT).
    X_OK is ignored.

  See also: open(), stat()

------------------------------------------------------------------------------
#include <stdlib.h>                                                   [UNIX *]

unsigned alarm (unsigned sec);

    Cause SIGALRM to be generated after SEC seconds have expired.
    alarm() returns immediately after setting the alarm clock.  There
    is only one alarm clock; when calling alarm() while the alarm
    clock is running the time will be reset to the new value.  If SEC
    is zero, the alarm clock will be stopped.

  Return value:

    alarm() returns the number of seconds remaining on the alarm clock
    before setting the new value.

  Implementation-defined behavior:

    In a multithread process, there is a single alarm clock which can
    be set from all the threads.  SIGALRM is always generated and
    delivered in the main thread (thread 1).

  Restrictions:

    alarm() is not available with the system call library sys.lib
    (-Zsys).

    Under DOS, SIGALRM is not delivered until return from DOS if the
    timer expired during a DOS call.

  See also: raise(), sigaction(), signal(), sleep(), _sleep2()

------------------------------------------------------------------------------
#include <alloca.h>

void *alloca (size_t n);

    Allocate N bytes from the current stack frame.  The memory space
    allocated by alloca() will be freed on exit from the current
    function.  Do not pass the pointer returned by alloca() to free().

  Return value:

    alloca() returns a pointer to a block of memory in the stack.

  Restrictions:

    This note applies only if you need stack probes (-mprobe option of
    GCC):

    If alloca() with constant argument occurs in the first statement
    of a function with less than 4096 bytes of local data or if two
    calls to alloca() with constant arguments occur twice in a row
    without accessing the memory pointed to by the return value of the
    first call, you have to change your code to make GCC generate
    correct stack probes.  This can be done by storing a dummy value
    to the return value of alloca().  Example:

        p = alloca (0xf00);
        {char *fix=alloca (0); *fix = 0;}
        q = alloca (0xf00);

  See also: malloc(), _tmalloc()

  Example:

    void test (void)
    {
      char local[0xf00], *p;
    
      {char *fix=alloca (0); *fix = 0;}
      p = alloca (0xf00);
      /*...*/
    }

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

char *asctime (const struct tm *t);

    Convert the time and date in the structure pointed to by T to a
    string.  A pointer to the string is returned.  There is only one
    memory location for the ctime() and asctime() results, a call to
    ctime() or asctime() overwrites the result of a previous calls to
    ctime() or asctime().  As localtime() is called by ctime(), the
    memory location shared by localtime(), gmtime(), and mktime() is
    overwritten.  The string looks like

        "Sun Mar  2 07:59:18 1992\n"

    with a terminating null character.  All fields have fixed width.

  Return value:

    asctime() returns a pointer to a string containing the textual
    representation of its argument.

  See also: ctime(), gmtime(), localtime(), mktime()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double acos (double x);
double asin (double x);
double atan (double x);
double atan2 (double y, double x);

long double acosl (long double x);
long double asinl (long double x);
long double atanl (long double x);
long double atan2l (long double y, long double x);

    asin(), acos(), and atan() compute the arc sine, arc cosine and
    arc tangent of X, respectively.  atan2() computes the arctangent
    of Y/X, using the signs of Y and X to determine the quadrant.  If
    X is outside [-1,1], asin() and acos() return a NaN and set errno
    to EDOM.

    acosl(), asinl(), atanl() and atan2l() use the long double format.

  Return value:

    acos(), asin(), atan() and atan2() return the arc sine, arc cosine
    or arc tangent, respectively, of their argument.  These functions
    return a NaN on error.

  See also: cos(), sin(), tan()

------------------------------------------------------------------------------
#include <assert.h>                                                      [C90]

void assert (int exp);

    If the preprocessor macro NDEBUG is defined at the time <assert.h>
    is included, assert() does nothing.  Otherwise, if EXP is zero,
    the message

        Assertion failed: EXP, file FILE, line LINE

    is displayed and the program is aborted by calling abort().  EXP,
    FILE and LINE are replaced with EXP (as text), the source file
    name and the source line number, respectively.  If EXP is
    non-zero, nothing is done.

  See also: abort()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

int atexit (void (*func)(void));

    The function FUNC will be called when the process is terminated.
    The last function installed by calling atexit() will be called
    first.

  Return value:

    0       success

    -1      error

  Implementation-defined behavior:

    Up to 32 functions can be installed.

  See also: abort(), exit(), _exit()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]
#include <math.h>  /* alternate include file for atof() */

double atof (const char *string);
int atoi (const char *string);
long atol (const char *string);

long double _atofl (const char *string);
long long _atoll (const char *string);

    Convert the textual, decimal representation of a number in the
    string pointed to by STRING to a number.  Leading whitespace is
    ignored.  If the string cannot be converted, 0 (or 0.0) is
    returned.  The value of errno is not reliable.

    The decimal point character of the current locale is used by
    atof() and _atofl().

    _atofl() uses the long double format and is not an ISO C function.
    _atoll() uses the long long format and is not an ISO C function.

  Return value:

    These functions return their argument as number.  They return 0
    (or 0.0) on error.

  See also: _ltoa(), scanf(), setlocale(), strtod(), strtol()

------------------------------------------------------------------------------
#include <strings.h>                                                     [BSD]

int bcmp (const void *buffer1, const void *buffer2, size_t n);

    Compare the first N bytes at BUFFER1 to the first N bytes at
    BUFFER2.  If the two buffers are identical (or if N is zero), 0 is
    returned.  Otherwise, a non-zero value is returned.

  Return value:

    0       the buffers are identical

    non-0   the buffers are different

  See also: memcmp()

------------------------------------------------------------------------------
#include <strings.h>                                                     [BSD]

void bcopy (const void *src, void *dst, size_t n);

    Copy memory.  Copy N bytes from SRC to DST.

  Implementation-defined behavior:

    The two regions may overlap.

  See also: memcpy(), memmove()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

int _beginthread (void (*start)(void *arg), void *stack, unsigned stack_size,
                  void *arg_list);

    Start a thread.  START is the start address (a function).
    ARG_LIST will be passed in the ARG parameter of the START
    function.  STACK is ignored, using NULL is recommended.
    STACK_SIZE is the size of the stack for the new thread.  When the
    START function returns, the thread is terminated by an automatic
    call to _endthread().  A thread can also terminate itself by
    calling _endthread().  If successful, _beginthread() returns the
    thread ID.  On error, _beginthread() sets errno and returns -1.
    The stack allocated for the new thread is completely committed,
    that is, stack probes are not required.

    _beginthread() is preferred over DosCreateThread because it
    initializes the C library.

  Return value:

    _beginthread() returns the thread ID of the new thread.  It
    returns -1 on error.

  Restrictions:

    _beginthread() is available in the multithread libraries only
    (-Zmt, -Zmts, or -Zmtd).

  Hints:

    STACK_SIZE should be at least 32768.  Specifying a big stack size
    doesn't hurt.

  See also: _endthread(), _gettid(), _threadid, _threadstore()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [UNIX]

void *brk (void *addr);

    Change the end address of the data segment to ADDR.  On success,
    brk() returns 0, cast as pointer.  Otherwise, -1 cast as pointer
    is returned and errno set to ENOMEM.  Please don't use brk() --
    use malloc() instead for memory allocation.

    brk() never allocates non-contiguous memory; in consequence,
    allocation with brk() is limited by the size of the memory object
    of the heap.  On the other hand, sbrk() may add memory objects to
    the heap if non-contiguous allocation has been enabled with
    _uflags().  Setting back the memory limit into a gap produced
    non-contiguous allocation by sbrk() is not possible.  However,
    brk() can be used to deallocate memory objects allocated by
    sbrk().

  Return value:

    (void *)0

        success

    (void *)-1

        error

  See also: malloc(), sbrk(), _uflags(), ulimit()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

void *bsearch (const void *key, const void *base, size_t num, size_t width,
               int (*compare)(const void *key, const void *element));

    Perform a binary search on the sorted array BASE to find KEY.  The
    array has NUM elements of size WIDTH bytes each.  bsearch() calls
    COMPARE to compare an array element pointed to by ELEMENT with
    KEY.  COMPARE should return 0 if KEY and ELEMENT are equal; a
    negative value, if KEY is smaller than ELEMENT; a positive value
    if KEY is greater than ELEMENT with respect to the sorting order
    of BASE.  If there are multiple occurrences of KEY in BASE,
    bsearch() returns a pointer to any one of the entries.  If the
    array pointed to by BASE is not sorted, bsearch() does not work.

  Return value:

    bsearch() returns a pointer to an occurrence of KEY in the array.
    If KEY is not found, bsearch() returns NULL.

  See also: qsort()

------------------------------------------------------------------------------
#include <strings.h>                                                     [BSD]

void bzero (void *buffer, size_t n);

    Set N bytes at BUFFER to 0.

  See also: calloc(), memset()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

void *calloc (size_t elements, size_t size);

    Allocate a block of memory big enough for holding ELEMENTS
    elements of SIZE bytes each.  calloc() fills the block with zeros.
    If there is an error, calloc() returns NULL.

  Implementation-defined behavior:

    calloc() allocates from the default heap of the current thread.
    If at least one argument is zero, calloc() returns a non-NULL
    pointer if there's enough space left in the heap for a block of
    the minimum size.

  Return value:

    calloc() returns a pointer to a newly allocated block of memory.
    On error, calloc() returns NULL.

  See also: free(), malloc(), _msize(), _tcalloc(), _ucalloc(),
            _udefault()

------------------------------------------------------------------------------
#include <math.h>

double cbrt (double x);
long double _cbrtl (long double x);

    Compute the cube root of X.  This is done by calling pow() and
    adjusting the sign.

    _cbrtl() uses the long double format and is an emx-specific
    function.

  Return value:

    cbrt() returns the cube root of its argument.

  See also: pow(), sqrt()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double ceil (double x);
long double ceill (long double x);

    Compute the smallest integer that is greater than or equal to X
    (round up).

    ceill() uses the long double format.

  Return value:

    ceil() returns as floating-point number the smallest integer that
    is greater than or equal to X.

  See also: floor(), rint(), trunc()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

speed_t cfgetispeed (const struct termios *ptermios);
speed_t cfgetospeed (const struct termios *ptermios);

    cfgetispeed() returns the input bit rate stored in the structure
    pointed to by PTERMIOS.

    cfgetospeed() returns the output bit rate stored in the structure
    pointed to by PTERMIOS.

    See `General terminal interface' for details.

  Return value:

    cfgetispeed() and cfgetospeed() return a bit rate.  Bit rates are
    represented by the symbols B0 through B38400.

  Restrictions:

    Asynchronous lines are not yet supported.

  See also: cfsetispeed(), cfsetospeed(), tcgetattr(), tcsetattr()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int cfsetispeed (struct termios *ptermios, speed_t speed);
int cfsetospeed (struct termios *ptermios, speed_t speed);

    cfsetispeed() and cfsetospeed() set the input bit rate and output
    bit rate, respectively, in the structure pointed to by PTERMIOS
    from the value of SPEED.  Bit rates are represented by the symbols
    B0 through B38400.

    See `General terminal interface' for details.

  Return value:

    cfsetispeed() and cfsetospeed() return 0 if successful.
    Otherwise, cfsetispeed() and cfsetospeed() set errno and return
    -1.

  Errors:

    EINVAL  The bit rate SPEED is not valid.

  Restrictions:

    Asynchronous lines are not yet supported.

  See also: cfgetispeed(), cfgetospeed(), tcgetattr(), tcsetattr()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [UNIX]

int chdir (const char *name);

    Change to directory whose name is in the string pointed to by
    NAME.  If the name contains a drive letter, the working directory
    on that drive is changed, but the selected drive does not change.

    chdir() properly handles DBCS characters.

  Return value:

    0       success

    -1      error

  Restrictions:

    Under DOS, the current working directory is not a property of a
    process, it is a system-wide property.  That may change in a
    future release of emx.  chdir ("..") fails if the current working
    directory is the root directory.

  See also: _chdir2(), getcwd(), _nls_init()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _chdir2 (const char *name);

    Change to the directory whose name is in the string pointed to by
    NAME.  If the name contains a drive letter, that drive is selected
    before changing to the directory.  If the name contains a drive
    letter, the directory can be omitted:

    _chdir2() properly handles DBCS characters.

        _chdir2 ("c:")

    is equivalent to

        _chdrive ('C')

  Return value:

    0       success

    -1      error

  Restrictions:

    Under DOS, the current working directory and the default drive is
    not a property of a process, it's a system-wide property.  That
    may change in a future release of emx.  _chdir ("..") fails if the
    current working directory is the root directory.

  See also: chdir(), getcwd(), _nls_init()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

int _chdrive (char drive);

    Make the disk drive DRIVE the default drive.  DRIVE must be in 'A'
    through 'Z' or in 'a' through 'z'.

  Return value:

    _chdrive() always returns 0, even if the drive does not exist.

  See also: _chdir2(), _getdrive()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]
#include <sys/stat.h>

int chmod (const char *name, int pmode);

    Change permission settings of the file whose name is in the string
    pointed to by NAME to PMODE.  There is only one permission bit
    under OS/2 and DOS, the read-only attribute.  The read-only bit is
    set if S_IWRITE is not included in PMODE.  Either specify
    S_IREAD|S_IWRITE or S_IREAD for PMODE.

  Return value:

    0       success

    -1      error

  Restrictions:

    Only the S_IWRITE bit of PMODE is used.

  See also: creat(), open(), stat(), umask()

------------------------------------------------------------------------------
#include <io.h>                                                           [PC]

int chsize (int handle, long size);

    Change the length of the file associated with HANDLE to SIZE
    bytes.  The position of the file pointer is undefined after
    calling this function.  If SIZE is greater than the current length
    of the file, bytes of zeros are appended.  HANDLE must be open for
    writing.

  Return value:

    0       success

    -1      error

  See also: ftruncate(), lseek()

------------------------------------------------------------------------------
#include <float.h>                                                        [PC]

unsigned _clear87 (void);

    Clear the coprocessor status word.

  Return value:

    _clear87() returns the previous value of the status word.

  See also: _control87(), _fpreset(), _status87()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

void clearerr (FILE *stream);

    Clear the error and end-of-file indicators of STREAM.

  See also: ferror(), feof()

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

clock_t clock (void);

    clock() returns the amount of processor time (timer ticks) used by
    the calling process since the process has been started.  There are
    CLOCKS_PER_SEC timer ticks per second.

  Return value:

    clock() returns the number of timer ticks used by the process.

  Restrictions:

    clock() returns the time elapsed, not the CPU time.

  See also: time()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int close (int handle);

    Close the file associated with the handle HANDLE.

  Return value:

    0       success

    -1      error

  See also: dup(), open()

------------------------------------------------------------------------------
#include <float.h>                                                        [PC]

unsigned _control87 (unsigned new_cw, unsigned mask);

    Set the coprocessor control word.  Bits of the control word set in
    MASK are replaced with the matching bits of NEW_CW:

        cw = ((cw & ~mask) | (new_cw & mask));

    If MASK is 0, the control word is not changed.  MASK should be one
    of the following symbols:

    MCW_EM  Exception masks

    MCW_IC  Infinity control (ignored by the 387 and later)

    MCW_RC  Rounding control

    MCW_PC  Precision control

    To pass multiple values in NEW_CW, use the | operator to combine
    the symbols described below.

    If MASK includes MCW_EM, any combination of the following symbols,
    including none (0), can be used in NEW_CW.  If one of these symbol
    is included, the corresponding exception is masked off, that is,
    the coprocessor will take a corrective action and continue.  If an
    exception is not masked off, SIGFPE will be generated by that
    exception.

    EM_INVALID
            Invalid operation (corrective action: return a NaN)

    EM_DENORMAL
            Denormalized operand (corrective action: use gradual
            underflow)

    EM_ZERODIVIDE
            Division by zero (corrective action: return infinity)

    EM_OVERFLOW
            Overflow (corrective action: return infinity)

    EM_UNDERFLOW
            Underflow (corrective action: return a denormal or zero)

    EM_INEXACT
            Precision lost (corrective action: ignore)

    By default, all floating-point exceptions are masked off.

    If MASK includes MCW_RC, exactly one of the following symbols
    should be used in NEW_CW:

    RC_NEAR
            Round to nearest or even (default)

    RC_DOWN
            Round down toward -infinity

    RC_UP   Round up toward infinity

    RC_CHOP
            Chop by truncating toward zero

    If MASK includes MCW_PC, exactly one of the following symbols
    should be used in NEW_CW:

    PC_24   24-bit mantissa

    PC_53   53-bit mantissa

    PC_64   64-bit mantissa (default)

    Only addition, subtraction, multiplication, division, and sqrt()
    are affected by the precision-control bits.  Note that IEEE 754
    requires PC_53, which is not the default setting.

  Return value:

    _control87() returns the previous value of the control word.

  See also: _clear87(), _fpreset()

  Example:

    _control87 (PC_53, MCW_PC);     /* Round to 64-bit double */

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

double copysign (double x, double y);
float copysignf (float x, float y);
long double copysignl (long double x, long double y);

    Return a value with the magnitude of X and the sign bit of Y.

  Return value:

    copysign() returns a value with the magnitude of X and the sign
    bit of Y.

  See also: fpclassify(), nextafter(), signbit()

------------------------------------------------------------------------------
#include <stdlib.h>                                                    [emx *]

int _core (int handle);

    Write a core dump to the file associated with HANDLE.  HANDLE must
    be open for writing.  The core dump file can be used later for
    debugging or for creating another .exe file which includes the
    data as saved when _core() was called.

  Return value:

    0       success

    -1      error

  Restrictions:

    _core() works only in programs linked with ld.  It does not work
    in programs linked with LINK386.  _core() is not available with
    the system call library sys.lib (-Zsys).

  See also: close(), open(), raise(), sigaction(), signal()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double cos (double x);
double sin (double x);
double tan (double x);

long double cosl (long double x);
long double sinl (long double x);
long double tanl (long double x);

    cos(), sin(), and tan() compute the sine, cosine and tangent of X,
    respectively.

    cosl(), sinl() and tanl() use the long double format.

  Return value:

    The cos(), sin() and tan() functions return the cosine, sine and
    tangent, respectively, of their argument.

  Implementation-defined behavior:

    If the absolute value of X is greater than or equal to 2^63,
    sin(), sinl(), tan(), and tanl() return 0.0, cos() and cosl()
    return 1.0.

  See also: acos(), asin(), atan()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double cosh (double x);
double sinh (double x);
double tanh (double x);

long double coshl (long double x);
long double sinhl (long double x);
long double tanhl (long double x);

    cosh(), sinh(), and tanh() compute the hyperbolic cosine,
    hyperbolic sine and hyperbolic tangent of X, respectively.  On
    overflow, +INF or -INF is returned and errno set to ERANGE.

    coshl(), sinhl() and tanhl() use the long double format.

  Return value:

    The cosh(), sinh() and tanh() functions return the hyperbolic
    cosine, hyperbolic sine and hyperbolic tangent, respectively, of
    their argument.  These functions return NaN on error.

  See also: exp()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]
#include <sys/stat.h>

int creat (const char *name, int pmode);

    Create a file whose name is in the string pointed to by NAME with
    permission settings PMODE.  This is equivalent to

        open (name, O_WRONLY|O_TRUNC|O_CREAT, pmode)

  Return value:

    creat() returns a file handle of the new file.  On error, creat()
    sets errno and returns -1.

  See also: open()

------------------------------------------------------------------------------
#include <io.h>                                                          [emx]

int _crlf (char *buf, size_t size, size_t *new_size);

    Translate CR/LF pairs to newline characters.  The conversion is
    done in-place in the array of SIZE characters pointed to by BUF.
    The new size is stored to *NEW_SIZE.

  Return value:

    _crlf() returns 1 if the buffer ends with a CR.  Otherwise,
    _crlf() returns 0.

  See also: fread(), _fsetmode(), read(), setmode()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                               [VAC++]

unsigned char _crotl (unsigned char value, int shift);
unsigned char _crotr (unsigned char value, int shift);

    _crotl() returns VALUE (8 bits) rotated left by SHIFT bits.  If
    SHIFT is 1, bit 6 is returned as bit 7, bit 5 is returned as bit
    6, and so on, bit 0 is returned as bit 1, and bit 7 is returned as
    bit 0.

    _crotr() returns VALUE (8 bits) rotated right by SHIFT bits.  If
    SHIFT is 1, bit 1 is returned as bit 0, bit 2 is returned as bit
    1, and so on, bit 7 is returned as bit 6, and bit 0 is returned as
    bit 7.

    SHIFT should be 0 through 7.

    These functions are implemented as inline functions.

  See also: _lrotl(), _lrotr(), _srotl(), _srotr()

------------------------------------------------------------------------------
                                                                        [OS/2]
int _CRT_init (void);
void _CRT_term (void);

    These two functions are provided for being called from
    _DLL_InitTerm(), the DLL initialization and termination function.

    _CRT_init() initializes the C run-time library if it has not yet
    been initialized.

    _CRT_term() terminates the C run-time library if it has not yet
    been terminated.

  Return value:

    _CRT_init() returns

    0       if successful

    -1      on error

  See also: _DLL_InitTerm(), __ctordtorInit(), __ctordtorTerm()

  Example: See /emx/test/testdll1.c

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

char *ctime (const time_t *t);

    Convert the number of seconds elapsed since 00:00:00 1-Jan-1970
    Coordinated Universal Time (UTC, GMT) in the variable pointed to
    by T to a string representing that moment for the local timezone.
    A pointer to the string is returned.  There is only one memory
    location for the ctime() and asctime() results, a call to ctime()
    or asctime() overwrites the result of a previous calls to ctime()
    or asctime().  As localtime() is called by ctime(), the memory
    location shared by localtime(), gmtime(), and mktime() is
    overwritten.  The string looks like

        "Sun Mar  2 07:59:18 1992\n"

    with a terminating null character.  All fields have fixed width.

  Return value:

    ctime() returns a pointer to a string containing the textual
    representation of its argument.

  See also: asctime(), gmtime(), localtime(), mktime()

------------------------------------------------------------------------------
                                                                        [OS/2]
void __ctordtorInit (void);
void __ctordtorTerm (void);

    These two functions are provided for being called from
    _DLL_InitTerm(), the DLL initialization and termination function.

    __ctordtorInit() invokes the constructors for the static objects
    of the DLL.  You should call __ctordtorInit() after calling
    _CRT_init().

    __ctordtorTerm() invokes the destructors for the static objects of
    the DLL.  You should call __ctordtorTerm() before calling
    _CRT_term().

  See also: _CRT_init(), _CRT_term(), _DLL_InitTerm()

------------------------------------------------------------------------------
#include <stdio.h>              /* prototype and L_cuserid constant */  [UNIX]
#include <unistd.h>             /* prototype */

char *cuserid (char *buffer);

    Return the login name of the owner of current process.  If BUFFER
    is NULL, a pointer to a statically allocated buffer is returned.
    Otherwise, the login name is copied to the array pointed to by
    BUFFER.  The array must be big enough to hold L_cuserid
    characters.  If there is an error, NULL is returned.

  Implementation-defined behavior:

    The emx implementation of cuserid() takes the login name from the
    USER environment variable.  If that environment variable is not
    defined, the login name is "root".

  Return value:

    cuserid() returns BUFFER if BUFFER is not a null pointer.
    cuserid() returns a pointer to a statically allocated buffer if
    BUFFER is NULL.  cuserid() returns NULL on error.

  See also: getpwent()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                               [VAC++]

signed char __cxchg (volatile signed char *p, signed char v);
int         __lxchg (volatile int *p,         int v);
short       __sxchg (volatile short *p,       short v);

    These functions atomically store V in the object pointed to by P
    and return the previous value of that object.  As this operation
    is done atomically, these functions can be used for implementing
    semaphores.  In fact, __cxchg() is used for implementing _fmutex
    and _smutex semaphores.

    These functions are implemented as inline functions.

  Return value:

    These functions return the previous value of the object pointed to
    by P.

  See also: _fmutex_request(), _smutex_request()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _defext (char *dst, const char *ext);

    Add the default extension EXT to the file name pointed to by DST.
    If the file name part of the string pointed to by DST contains an
    extension (including the empty extension), nothing will be done.
    Otherwise, a dot and the string pointed to by EXT will be
    appended.

    _defext() properly handles DBCS characters.

  See also: _getext(), _nls_init(), _remext(), _splitpath()

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

double difftime (time_t t1, time_t t0);

    Compute the difference (in seconds) between two time values.

  Return value:

    difftime() returns the difference (in seconds) T1-T0 between T0
    and T1.

------------------------------------------------------------------------------
#include <sys/builtin.h>                                               [VAC++]

void __disable (void);
void __enable (void);

    __disable() disables interrupts, __enable() enables interrupts.
    Note that these functions cause an access violation unless dirty
    tricks are used (see xf86sup.sys).

    These functions are implemented as inline functions.

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

div_t div (int num, int den);
ldiv_t ldiv (long num, long den);

    Perform an integer division, dividing NUM by DEN.  The quotient
    and the remainder are returned in the quot and rem fields,
    respectively.

    The following table shows the signs of quot and rem depending on
    the signs of NUM and DEN:

        NUM DEN  quot rem
        
         +   +    +    +
         +   -    -    +
         -   +    -    -
         -   -    +    -

    Note: Do not use the -fpcc-struct-return option of GCC.

  Return value:

    div() and ldiv() return a structure which contains the quotient
    and the remainder in the quot and rem fields, respectively.

  See also: _lldiv(), _uldiv(), _ulldiv()

------------------------------------------------------------------------------
                                                                        [OS/2]
unsigned long _DLL_InitTerm (unsigned long mod_handle, unsigned long flag);

    _DLL_InitTerm() is the library initialization and termination
    function for dynamic link libraries.  It is called by the
    operating system to initialize the library (if FLAG is zero) or to
    terminate the library (if FLAG is one).  MOD_HANDLE is the module
    handle of the dynamic link library.

    For all types of DLLs, the default _DLL_InitTerm() function calls
    __ctordtorInit() and __ctordtorTerm().  _CRT_init() is called for
    all types of DLLs except for DLLs without runtime environment
    (-Zno-rte).  _CRT_term() is called for stand-alone DLLs (-Zso) and
    for custom C runtime DLLs.

    If you write your own _DLL_InitTerm() to perform additional
    actions, don't forget to call _CRT_init() -- if required -- to
    initialize the runtime environment and to call __ctordtorInit()
    (after calling _CRT_init()) to invoke the static constructors of
    the DLL.  On termination (FLAG is one), you should call
    _CRT_term() in DLLs which include a C runtime environment .  To
    invoke the static destructors of the DLL, call __ctordtorTerm()
    before calling _CRT_term().

    If the DLL shares the heap with the program (for instance, if both
    use emxlibcs.dll) and if _DLL_InitTerm() uses the heap (by calling
    sbrk(), malloc(), etc.), fork() will always fail for that program.

  Return value:

    _DLL_InitTerm() should return 1 to indicate success.  On failure,
    _DLL_InitTerm() should return 0.

  See also: _CRT_init(), _CRT_term(), __ctordtorInit(),
            __ctordtorTerm(), fork()

  Example:

    /* This is the default _DLL_InitTerm() function for
       stand-alone dynamic link libraries. */
    
    int _CRT_init (void);
    void _CRT_term (void);
    void __ctordtorInit (void);
    void __ctordtorTerm (void);
    
    unsigned long _DLL_InitTerm (unsigned long mod_handle,
                                 unsigned long flag)
    {
      switch (flag)
        {
        case 0:
          if (_CRT_init () != 0)
            return 0;
          __ctordtorInit ();
         return 1;
        case 1:
          __ctordtorTerm ();
          _CRT_term ();
          return 1;
        default:
          return 0;
        }
      return 1;
    }

------------------------------------------------------------------------------
#include <sys/dirtree.h>                                                 [emx]

void _dt_free (struct _dt_tree *dt);

    Deallocate the memory allocated by _dt_read() for the directory
    tree DT.

  See also: _dt_read()

------------------------------------------------------------------------------
#include <sys/dirtree.h>                                                 [emx]

struct _dt_tree *_dt_read (const char *dir, const char *mask, unsigned flags);

    Create a directory tree in memory.  The tree consists of a linked
    list of _dt_node structures.  Subtrees are attached to the sub
    field of _dt_node structures for directories.  Files matching the
    wildcard in the string pointed to by MASK in the directory whose
    name is in the string pointed to by DIR are put into the tree.  If
    FLAGS includes _DT_TREE, all subdirectories of DIR are also
    scanned for files and directories matching the wildcard.  If
    _DT_TREE is not included, the subdirectories of the directory are
    not scanned.  If FLAGS includes _DT_NOCPDIR, the `.' and `..'
    entries are omitted.

    _fnlwr() is used to convert file names to lower case on
    upper-case-only file systems.  _dt_read() properly handles DBCS
    characters.

  Return value:

    If successful, _dt_read() returns a pointer to a _dt_tree
    structure.  The tree field of that structure is the root of the
    tree.  On error, _dt_read() sets the errno variable and returns
    NULL.

  See also: _dt_free(), _dt_sort(), _dt_split(), _fnlwr(),
            _fnexplode(), _nls_init()

  Example: See /emx/test/dttest.c

------------------------------------------------------------------------------
#include <sys/dirtree.h>                                                 [emx]

void _dt_sort (struct _dt_tree *dt, const char *spec);

    Sort the directory tree DT according to the string pointed to by
    SPEC.  DT is a directory tree created by _dt_read().  SPEC points
    to a string of characters which is read from left to right.  Each
    character tells _dt_sort() how to compare two tree nodes.  If the
    nodes compare equal, the next character is examined.  This is
    repeated until the two nodes are different according to the
    sorting criterion indicated by a character of the string pointed
    to by SPEC or the end of the SPEC string is reached.  If the end
    of the string pointed to by SPEC is reached, the two nodes are
    considered equal and the two nodes are put in an arbitrary order.
    The following characters are defined in the string pointed to by
    SPEC:

    e       File name extensions are compared, ascending ASCII order

    E       File name extensions are compared, descending ASCII order

    f       Directories are placed before files

    F       Files are placed before directories

    n       File names are compared, ascending ASCII order

    N       File names are compared, descending ASCII order

    s       File size is compared, ascending

    S       File size is compared, descending

    t       Time stamps (last modification) are compared, ascending

    T       Time stamps (last modification) are compared, descending

    All other characters are ignored.  _fncmp() is used for comparing
    file names.  If _fncmp() returns 0, strcmp() is used in addition.
    Then, strcmp() can return a non-zero value only if the current
    code page does not match the code page used for creating the
    directory entries.

  See also: _dt_read(), _fncmp()

------------------------------------------------------------------------------
#include <sys/dirtree.h>                                                 [emx]

int _dt_split (const char *src, char *dir, char *mask);

    Split the path name pointed to by SRC into a directory part and a
    name part for _dt_read().  The directory part is stored to the
    array pointed to by DIR, the name part is stored to the array
    pointed to by MASK.  If the string pointed to by SRC is the name
    of a directory, the array pointed to by MASK is set to "*.*".

    _dt_split() properly handles DBCS characters.

  Return value:

    0       success

    -1      error (errno set)

  See also: _dt_read(), _nls_init()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int dup (int handle);
int dup2 (int handle1, int handle2);

    Create a duplicate of the file handle HANDLE or HANDLE1,
    respectively, that is, another handle that refers to the same file
    or device or pipe as the handle given.  Both handles share the
    same file pointer.  dup() chooses the lowest numbered available
    handle.  dup2() uses HANDLE2 for the new file handle.  If HANDLE2
    is open when dup2() is called, it will be closed by dup2() unless
    HANDLE1 is invalid or identical to HANDLE2.

    If HANDLE1 is a valid open file handle and is equal to HANDLE2,
    dup2() returns HANDLE2 without closing it.

  Return value:

    dup() and dup2() return the new file handle (which is HANDLE2 if
    dup2() succeeds).  They return -1 on error.

  Errors:

    EBADF   The HANDLE or HANDLE1 argument is not a valid open file
            descriptor or HANDLE2 is out of range.

    EMFILE  No file descriptor is available.

  Restrictions:

    Duplicated file handles should share the file status flags
    O_APPEND and O_NONBLOCK; however, dup() and dup2() just copy the
    file status flags, changing the file status flags after
    duplicating a file handle does not affect the other file handle.

    dup2() currently doesn't work correctly under DOS.

  See also: close(), fcntl(), open()

------------------------------------------------------------------------------
#include <sys/ea.h>                                                      [emx]

void _ea_free (struct _ea *ptr);

    Free the memory allocated for the value of an extended attribute
    stored in the structure pointed to by PTR.  If the value field of
    the structure is non-NULL, free() is called for that pointer.
    Then, the value field is set to NULL.

  See also: _ea_get()

------------------------------------------------------------------------------
#include <sys/ea.h>                                                      [emx]

int _ea_get (struct _ea *dst, const char *path, int handle,
             const char *name);

    Retrieve the extended attribute whose name is in the string
    pointed to by NAME of a file or directory.  If PATH is non-NULL,
    an extended attribute of the file or directory whose name is in
    the string pointed to by PATH is retrieved.  Otherwise, an
    extended attribute of the file referred to by HANDLE is retrieved.
    The letter case of NAME is ignored.  The flags, the value and the
    size of the value of the extended attribute is copied to the
    structure pointed to by DST.  If the extended attribute does not
    exist, the size member of the structure pointed to by DST is set
    to 0 and the value member of the structure pointed to by DST is
    set to NULL.  _ea_get() allocates memory for the value of the
    extended attribute by calling malloc().  The structure declaration
    is:

        struct _ea
        {
          int flags;
          int size;
          void *value;
        };

    The flags member contains the flags byte of the extended attribute
    (only bits 0 through 7 of flags are used).  Currently, OS/2
    defines only bit 7: it's set for critical EAs.  size is the length
    of the value in bytes.  The value member points to the (binary)
    value of the extended attribute.

    Use _ead_read() to retrieve all the extended attributes of a file
    or directory.

  Return value:

    0       success or EA not found

    -1      error

  See also: _ea_free(), _ea_put(), _ead_read()

------------------------------------------------------------------------------
#include <sys/ea.h>                                                      [emx]

int _ea_put (struct _ea *src, const char *path, int handle,
             const char *name);

    Add an extended attribute to a file or directory.  If PATH is
    non-NULL, the extended attribute is added to the file or directory
    whose name is in the string pointed to by PATH.  Otherwise, the
    extended attribute is added to the file referred to by HANDLE
    which must be open for writing.  The string pointed to by NAME
    contains the name of the extended attribute.  The letter case of
    the name is ignored.  SRC points to an _ea structure which holds
    the flags, size and value of the extended attribute to be added.
    If the size member is 0, the extended attribute is removed.  Bits
    0 though 7 of flags contain the flags byte for the extended
    attribute.  Currently, OS/2 defines only bit: the critical EA bit.
    The flags member should be zero unless you exactly know what you
    are doing.

    Use _ead_write() to replace or update multiple extended attributes
    at once.

  Return value:

    0       success

    -1      error (errno is set)

  See also: _ea_get(), _ea_remove(), _ead_write()

------------------------------------------------------------------------------
#include <sys/ea.h>                                                      [emx]

int _ea_remove (const char *path, int handle, const char *name);

    Remove the extended attribute whose name is in the string pointed
    to by NAME from a file or directory.  If PATH is non-NULL, the
    extended attribute is removed from the file or directory whose
    name is in the string pointed to by PATH.  Otherwise, the extended
    attribute is removed from the file referred to by HANDLE.  The
    letter case of the string pointed to by NAME is ignored.  Removing
    a non-existing extended attribute of an existing file or directory
    is not an error.

  Return value:

    0       success

    -1      error (errno is set)

  See also: _ea_put(), _ead_write()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_add (_ead ead, const char *name, int flags, const void *value,
              int size);

    Add the extended attribute whose name is in the string pointed to
    by NAME to the extended attributes descriptor EAD.  NAME should
    point to a null-terminated string.  The value of the extended
    attribute is set to SIZE bytes of the array pointed to by VALUE.
    The flags byte of the extended attribute is set to FLAGS.  Only
    bits 0 through 7 of FLAGS are used.  Currently, OS/2 defines only
    bit 7 of the flags byte: it's the critical EA bit.  FLAGS should
    be zero unless you exactly know what you are doing.  If an
    extended attribute with the name in the string pointed to by NAME
    already exists in EAD, it is updated with FLAGS, SIZE and the
    array pointed to by VALUE.  The extended attributes on disk are
    not affected.  After calling _ead_add(), the pointers returned by
    previous invocations of _ead_get_fea2list(), _ead_get_name() and
    _ead_get_value() will be invalid.  As _ead_add() does a
    case-sensitive search, you should pass an upper-case names in the
    string pointed to by NAME.  If there are two extended attributes
    in an extended attributes descriptor whose names differ only in
    letter case, only one of both will be written to the disk by
    _ead_write().

  Return value:

    _ead_add() returns the index of the new (or updated) extended
    attribute.  On error, _ead_add() sets errno and returns a negative
    value.

  See also: _ead_delete(), _ead_replace(), _ead_write(), _nls_strupr()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

void _ead_clear (_ead ead);

    Discard the extended attributes of the extended attributes
    descriptor EAD.  After calling _ead_clear(), _ead_count() will
    return 0 for EAD.  The extended attributes on disk are not
    modified.  After calling _ead_clear(), do not use pointers
    returned by _ead_get_name(), _ead_get_value() and
    _ead_get_fea2list() for that descriptor.

  See also: _ead_create(), _ead_destroy(), _ead_read()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_copy (_ead dst_ead, _ead src_ead, int src_index);

    Copy the extended attribute SRC_INDEX from the extended attributes
    descriptor SRC_EAD to the extended attributes descriptor DST_EAD.
    If SRC_INDEX is 0, all extended attributes of SRC_EAD are copied
    to DST_EAD.  Otherwise, SRC_INDEX must be a number between 1 and
    the number of extended attributes of SRC_EAD.  _ead_copy() uses
    _ead_add() to copy the extended attributes.  The extended
    attributes on disk are not affected.

  Return value:

    0       success

    -1      error (errno is set)

  See also: _ead_add()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_count (_ead ead);

    Get the number of extended attributes available from the extended
    attributes descriptor EAD.

  Return value:

    _ead_count() returns the number of extended attributes available
    from the extended attributes descriptor EAD.

  See also: _ead_create(), _ead_get_name(), _ead_get_value()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

_ead _ead_create (void)

    Create an extended attributes descriptor.  Such a descriptor is
    used for handling the extended attributes of files and
    directories.  Use _ead_destroy() if you no longer need the
    descriptor.  To copy all the extended attributes of a file or a
    directory to an extended attributes descriptor, use _ead_read().
    Initially, no extended attributes are held by an extended
    attributes descriptor.

  Return value:

    _ead_create() returns a descriptor which can be used by the other
    functions for handling extended attributes.  On error,
    _ead_create() sets errno and returns NULL.

  See also: _ead_destroy(), _ead_get_name(), _ead_get_value(),
            _ead_read()

  Example: See /emx/samples/eatool.c

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_delete (_ead ead, int index);

    Delete the extended attribute INDEX from the extended attributes
    descriptor EAD.  INDEX must be a number between 1 and the number
    of extended attributes of EAD.  After calling _ead_delete(), the
    pointers returned by previous invocations of _ead_get_fea2list(),
    _ead_get_name() and _ead_get_value() will be invalid.  Moreover,
    _ead_delete() invalidates index numbers.

  Return value:

    _ead_delete() returns 0 if successful.  On error, _ead_delete()
    sets errno and returns a negative number.

  See also: _ead_add(), _ead_find()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

void _ead_destroy (_ead ead);

    Invalidate the extended attributes descriptor EAD which has been
    created by _ead_create().  All memory associated with EAD is
    released.  EAD must not be NULL.  After calling _ead_destroy(),
    EAD is invalid and can no longer be used.  After calling
    _ead_destroy(), do not use pointers returned by _ead_get_name(),
    _ead_get_value() and _ead_get_fea2list() for that descriptor.

  See also: _ead_clear(), _ead_create()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_fea2list_size (_ead ead);

    Get the size of the FEA2LIST of the extended attributes descriptor
    EAD.  If EAD doesn't hold any extended attributes, the size is 0.

  Return value:

    _ead_fea2list_size() returns the size of the FEA2LIST of the
    extended attributes descriptor EAD.  _ead_fea2list_size() returns
    0 if EAD doesn't hold any extended attributes.

  See also: _ead_get_fea2list()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

void *_ead_fea2list_to_fealist (const void *src);

    Convert the FEA2LIST SRC (OS/2 2.x format) to a FEALIST (OS/2 1.2
    format).  SRC must not be NULL.  This function allocates memory
    with malloc() to hold the converted list.  A pointer to the
    converted list is returned.  If you no longer need the buffer
    allocated by this function, you should deallocate it with free().
    SRC is of type PFEA2LIST, the return value is of type PFEALIST.
    To avoid having to include <os2.h> when including <sys/ead.h>,
    void pointers are used instead.

  Return value:

    _ead_fea2list_to_fealist() returns a pointer to a FEALIST,
    allocated with malloc().  On error, _ead_fea2list_to_fealist()
    sets errno and returns NULL.

  See also: _ead_fealist_to_fea2list(), _ead_get_fea2list()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

void *_ead_fealist_to_fea2list (const void *src);

    Convert the FEALIST SRC (OS/2 1.2 format) to a FEA2LIST (OS/2 2.x
    format).  SRC must not be NULL.  This function allocates memory
    with malloc() to hold the converted list.  A pointer to the
    converted list is returned.  If you no longer need the buffer
    allocated by this function, you should deallocate it with free().
    SRC is of type PFEALIST, the return value is of type PFEA2LIST.
    To avoid having to include <os2.h> when including <sys/ead.h>,
    void pointers are used instead.

  Return value:

    _ead_fealist_to_fea2list() returns a pointer to a FEA2LIST,
    allocated with malloc().  On error, _ead_fealist_to_fea2list()
    sets errno and returns NULL.

  See also: _ead_fea2list_to_fealist()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_find (_ead ead, const char *name);

    Retrieve the index of the extended attribute whose name is in the
    string pointed to by NAME of the extended attributes descriptor
    EAD.  NAME should point to a null-terminated string.  If there is
    no such extended attribute, errno is set to ENOENT and -1 is
    returned.  Otherwise, a number between 1 and the number of
    extended attributes of EAD is returned.  Note that OS/2 converts
    names of extended attributes to upper case when writing them to
    the disk.  As _ead_find() does a case-sensitive compare,
    lower-case names are not found.

  Return value:

    _ead_find() returns the index of the extended attribute.  If the
    extended attribute is not found, _ead_find() returns -1.

  See also: _ead_count(), _ead_get_name(), _ead_get_value(),
            _nls_strupr()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

const void *_ead_get_fea2list (_ead ead);

    Retrieve a pointer to the FEA2LIST of the extended attributes
    descriptor EAD.  You should cast the return value to PFEA2LIST.
    The return type of _ead_get_fea2list() is not PFEA2LIST to be able
    to include <sys/ead.h> without having to include <os2.h>.  The
    pointer points to memory allocated by the extended attributes
    functions -- do not use the pointer after calling _ead_add(),
    _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or
    _ead_replace() and do not write to the buffer.

  Return value:

    _ead_get_fea2list() returns a pointer to the FEA2LIST of the
    extended attributes descriptor EAD.

  See also: _ead_fea2list_size(), _ead_fea2list_to_fealist()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_get_flags (_ead ead, int index);

    Get the flags byte of the extended attribute INDEX of the extended
    attributes descriptor EAD.  INDEX must be a number between 1 and
    the number of extended attributes of EAD.  On error, errno is set
    and -1 is returned.

  Return value:

    _ead_get_flags() returns the flags by of an extended attribute.
    On error, _ead_get_flags() returns -1.

  See also: _ead_count(), _ead_get_value()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

const char *_ead_get_name (_ead ead, int index);

    Return a pointer to the name of the extended attribute INDEX of
    the extended attributes descriptor EAD.  INDEX must be a number
    between 1 and the number of extended attributes of EAD.  The
    pointer points to memory allocated by the extended attributes
    functions -- do not use the pointer after calling _ead_add(),
    _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or
    _ead_replace() and do not write to the buffer.  On error, errno is
    set and NULL is returned.

  Return value:

    _ead_get_name() returns a pointer to the name of an extended
    attribute.  On error, _ead_get_name() returns NULL.

  See also: _ead_count(), _ead_name_len()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

const void *_ead_get_value (_ead ead, int index);

    Return a pointer to the value of the extended attribute INDEX of
    the extended attributes descriptor EAD.  INDEX must be a number
    between 1 and the number of extended attributes of EAD.  The
    pointer points to memory allocated by the extended attributes
    functions -- do not use the pointer after calling _ead_add(),
    _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or
    _ead_replace() and do not write to the buffer.  On error, errno is
    set and NULL is returned.

  Return value:

    _ead_get_value() returns a pointer to the value of an extended
    attribute.  On error, _ead_get_value() returns NULL.

  See also: _ead_count(), _ead_find(), _ead_get_flags(),
            _ead_value_size()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_name_len (_ead ead, int index);

    Get the length of the name of the extended attribute INDEX of the
    extended attributes descriptor EAD.  If INDEX is 0, the total
    length of all the names is returned, not including the terminating
    null characters.  Otherwise, INDEX must be a number between 1 and
    the number of extended attributes of EAD; the length of the name
    of the INDEXth extended attribute is returned.  The terminating
    null character is not included in the length.  On error, errno is
    set and -1 is returned.

  Return value:

    _ead_name_len() returns the length of the name of an extended
    attribute.  On error, _ead_name_len() returns -1.

  See also: _ead_count(), _ead_get_name()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_read (_ead ead, const char *path, int handle, int flags);

    Copy the extended attributes of a file or directory to the
    extended attributes descriptor EAD.  The extended attributes held
    previously by EAD are discarded.  If PATH is not NULL, the
    extended attributes of file or directory whose name is in the
    string pointed to by PATH are copied to EAD.  If PATH is NULL, the
    extended attributes of the file referred to by the file handle
    HANDLE are copied to EAD.  FLAGS is not yet used and must be 0.
    _ead_read() calls _ead_clear(), reads all the extended attributes
    and stores them in memory.  Use _ead_destroy() to deallocate that
    memory and invalidate EAD.  When using a non-NULL PATH,
    _ead_read() does not lock the file while while reading the
    extended attributes.  You might want to open a handle in
    deny-write mode and pass it in HANDLE to avoid problems due to
    other threads or processes modifying the extended attributes while
    _ead_read() is reading.  This doesn't work with and isn't required
    for directories.  _ead_read() can also be used under DOS though no
    extended attributes will be copied.  Therefore, your program
    doesn't have to decide whether to use these functions or not.

    Use _ea_get() to retrieve extended attributes one by one.

  Return value:

    If successful, _ead_read() returns 0.  On error, _ead_read() sets
    errno and returns a negative number.

  See also: _ea_get(), _ead_create(), _ead_destroy(), _ead_get_name(),
            _ead_get_value(), _ead_write()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_replace (_ead ead, int index, int flags, const void *value,
                  int size);

    Update the extended attribute INDEX of the extended attributes
    descriptor EAD with FLAGS and SIZE bytes of VALUE.  INDEX must be
    a number between 1 and the number of extended attributes of EAD.
    The extended attributes on disk are not affected.  After calling
    _ead_replace(), the pointers returned by previous invocations of
    _ead_get_fea2list(), _ead_get_name() and _ead_get_value() will be
    invalid.

  Return value:

    On success, _ead_replace() returns 0.  On error, _ead_replace()
    sets errno and returns a negative value.

  See also: _ead_add(), _ead_write()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

void _ead_sort (_ead ead);

    Sort by name the extended attributes of the extended attributes
    descriptor EAD.  Sorting is done in memory -- the extended
    attributes on disk are not affected.  After calling _ead_sort(),
    index 1 refers to the extended attribute with the lexically
    smallest name.  strcmp() is used for comparing names.  _ead_sort()
    sorts the index, not the extended attributes proper.  Therefore,
    all functions that modify the extended attributes of EAD undo the
    effect of _ead_sort().

  See also: _ead_create(), _ead_get_name(), _ead_read()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_use_fea2list (_ead ead, const void *src);

    Copy all the extended attributes from the FEA2LIST SRC (OS/2 2.x
    format) to the extended attributes descriptor EAD.  All extended
    attributes previously held by EAD are discarded.  The extended
    attributes on the disk are not affected.

  Return value:

    If successful, _ead_use_fea2list() returns 0.  Otherwise,
    _ead_use_fea2list() sets errno and returns a negative value.

  See also: _ead_write()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_value_size (_ead ead, int index);

    Get the size of the extended attribute INDEX of the extended
    attributes descriptor EAD.  If INDEX is 0, the total size of all
    the values of EAD is returned.  Otherwise, INDEX must be a number
    between 1 and the number of extended attributes of EAD; the size
    of the INDEXth extended attribute is returned.  On error, errno is
    set and -1 is returned.

  Return value:

    _ead_value_size() returns the length of the value of an extended
    attribute.  On error, _ead_value_size() returns -1.

  See also: _ead_count(), _ead_get_value()

------------------------------------------------------------------------------
#include <sys/ead.h>                                                     [emx]

int _ead_write (_ead ead, const char *path, int handle, int flags);

    Write all the extended attributes of the extended attributes
    descriptor EAD to the file or directory whose name is in the
    string pointed to by PATH or to the file associated with HANDLE.
    The extended attributes previously attached to that file or
    directory are discarded and replaced by the extended attributes of
    EAD if FLAGS is 0.  This is done by deleting the extended
    attributes of the file or directory which are not in EAD.  If
    FLAGS is _EAD_MERGE, the extended attributes of the file or
    directory which are also present in EAD are replaced by those of
    EAD.  Extended attributes of EAD which are not attached to the
    file or directory are added to the extended attributes of the file
    or directory.  If PATH is non-NULL, the extended attributes are
    written to the file or directory whose name is in the string
    pointed to by PATH.  If PATH is NULL, the extended attributes are
    written to the file referred to by the file handle HANDLE.  The
    extended attributes of EAD are not modified.

    Use _ea_put() to add or update extended attributes one by one.

  Return value:

    _ead_write() returns 0 if successful.  On error, _ead_write() sets
    errno and returns a negative value.  Under DOS, _ead_write() does
    nothing and always returns 0.

  See also: _ea_put(), _ead_clear(), _ead_read(), _ead_use_fea2list()

------------------------------------------------------------------------------
#include <os2.h>                                                         [emx]

void *_emx_16to32 (_far16ptr ptr);
_far16ptr _emx_32to16 (void *ptr);

    _emx_16to32() converts a 16-bit far pointer (16:16 format) to a
    32-bit flat pointer.

    _emx_32to16() converts a 32-bit flat pointer to a 16-bit far
    pointer (16:16 format).

    The type _far16ptr is used for 16-bit far pointers.

  Return value:

    _emx_16to32() returns a 32-bit flat pointer.  _emx_32to16()
    returns a 16-bit far pointer.

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_connect (void)
int _emxload_disconnect (void)

    Call _emxload_connect() to explicitly connect to the emxload
    server process.  The connection will be kept open until
    _emxload_disconnect() or _emxload_stop() is called to terminate
    the connection.  A counter is maintained which is incremented for
    each successful call to _emxload_connect() and decremented by each
    successful call to _emxload_disconnect().  The connection is
    closed when the counter reaches zero.

    If _emxload_connect() has not been called, _emxload_env(),
    _emxload_prog(), _emxload_this(), _emxload_stop() and
    _emxload_unload() open and close a temporary connection to the
    emxload server process.

    The emxload server process is started by _emxload_connect() if the
    emxload server process is not already running.

  Return value:

    0       connection sucessfully established or closed

    -1      the emxload server process could not be started

  Restrictions:

    Under DOS, _emxload_connect() and _emxload_disconnect() do nothing
    and return -1.

  See also: _emxload_disconnect(), _emxload_prog(), _emxload_stop()

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_env (const char *name)

    Keep (another copy of) the current program in memory if the
    environment variable whose name is in the string pointed to by
    NAME is set and contains a number.  That number specifies the
    number of minutes the process should be kept in memory.

    The emxload server process is started by _emxload_env() if the
    environment variable is valid and the emxload server process is
    not already running.

  Return value:

    0       request successfully sent to the emxload server process

    -1      error: the environment variable is not set, or does not
            contain a valid number or the emxload server process could
            not be started

  Restrictions:

    Under DOS, _emxload_env() does nothing and returns -1.

  See also: _emxload_prog(), _emxload_this(), _emxload_unload()

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_list_start (void);
int _emxload_list_get (char *buf, size_t buf_size, int *pseconds);

    Get a list of all preloaded programs.  To start the list, call
    _emxload_list_start().  If _emxload_list_start() returns 0, call
    _emxload_list_get() to receive the names and timeouts of the
    preloaded programs until _emxload_list_get() returns a non-zero
    value.

    _emxload_list_get() stores the complete path name of the program
    to the array pointed to by BUF.  BUF_SIZE is the size of the
    array, including the trailing null character.  The number of
    seconds remaining until automatic unloading is stored to the
    integer pointed to by PSECONDS.  If automatic unloading is
    disabled for that program, _EMXLOAD_INDEFINITE is stored.

    If you stop calling _emxload_list_get() before information about
    all the programs has been transferred, you should call
    _emxload_disconnect() to close the connection.  Calling
    _emxload_disconnect() is not required if _emxload_list_start()
    returns a non-zero value or after _emxload_list_get() returns a
    non-zero value.

    Do not call _emxload_list_get() without prior calling
    _emxload_list_start().  Do not call _emxload_list_get() if the
    previous call to _emxload_list_start() or _emxload_list_get()
    returned a non-zero value.

  Return value:

    0       request processed successfully

    -1      an error occured

    1       end of the list of programs (_emxload_list_get() only)

  Restrictions:

    Under DOS, _emxload_list_start() and _emxload_list_get() do
    nothing and return -1.

  See also: _emxload_prog(), _emxload_disconnect()

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_prog (const char *name, int seconds)

    Keep a program in memory for SECONDS seconds.  NAME points to a
    string containing the file name of the program.  If SECONDS is
    _EMXLOAD_INDEFINITE, the program will not be unloaded
    automatically.  The default extension of the name is .exe, the
    PATH environment variable is used for finding the executable file.

    The emxload server process is started by _emxload_prog() if
    SECONDS and the string pointed to by NAME are valid and the
    emxload server process is not already running.

  Return value:

    0       request successfully sent to the emxload server process

    -1      error: the program has not been found or the emxload
            server process could not be started

  Restrictions:

    Under DOS, _emxload_prog() does nothing and returns -1.

  See also: _emxload_connect(), _emxload_env(), _emxload_list_start(),
            _emxload_this(), _emxload_unload()

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_stop (int wait_flag)

    Stop the emxload server process.  All preloaded programs will be
    unloaded.  If WAIT_FLAG is zero, _emxload_stop() returns
    immediately after sending the request to the server.  If WAIT_FLAG
    is non-zero, _emxload_stop() waits until the server process no
    longer exists.

  Return value:

    0       emxload server process stopped

    -1      the emxload server process was not running or could not be
            stopped

  Restrictions:

    Under DOS, _emxload_stop() does nothing and returns -1.

  See also: _emxload_connect()

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_this (int seconds)

    Keep (another copy of) the current program in memory for SECONDS
    seconds.  If SECONDS is _EMXLOAD_INDEFINITE, the program will not
    be unloaded automatically.

    The emxload server process is started by _emxload_this() if
    SECONDS is valid and the emxload server process is not already
    running.

  Return value:

    0       request successfully sent to the emxload server process

    -1      error: SECONDS is invalid or the emxload server process
            could not be started

  Restrictions:

    Under DOS, _emxload_this() does nothing and returns -1.

  See also: _emxload_env(), _emxload_prog(), _emxload_unload()

------------------------------------------------------------------------------
#include <sys/emxload.h>                                                 [emx]

int _emxload_unload (const char *name, int wait_flag)

    Unload a preloaded program.  NAME points to a string containing
    the file name of the program.  The default extension for the file
    name is .exe, the PATH environment variable is used for finding
    the executable file.  If WAIT_FLAG is zero, _emxload_unload()
    returns immediately after sending the request to the server.  If
    WAIT_FLAG is non-zero, _emxload_unload() waits until the server
    process has unloaded the program.

  Return value:

    0       request successfully sent to the emxload server process

    -1      error: the program has not been found

  Restrictions:

    Under DOS, _emxload_unload() does nothing and returns -1.

  See also: _emxload_prog(), _emxload_stop()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

void _endthread (void);

    A thread that has been created by _beginthread() can call
    _endthread() to end its execution.  A thread also ends when the
    function started with _beginthread() returns.  In that case,
    _endthread() will be called automatically.  Terminating the main
    thread (thread 1) of a process terminates the process (return
    value will be 0).  Do not use DosExit to end a thread started by
    _beginthread().

    _endthread() is available only in the multithread libraries (-Zmt,
    -Zmts, or -Zmtd).

  See also: _beginthread()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _envargs (int *argcp, char ***argvp, const char *name);

    Take arguments from the environment variable whose name is in the
    string pointed to by NAME and insert them before the arguments
    given on the command line.  If you want to get arguments from the
    environment variable MYPROGOPT, insert

        _envargs (&argc, &argv, "MYPROGOPT");

    at the beginning of main().  The contents of the environment
    variable is parsed the same way as the command line, including
    quoting.  If you call _response() or _wildcard() after _envargs(),
    the arguments taken from the environment variable are treated like
    command line arguments, that is, _wildcard() will expand wildcards
    in the value of the environment variable unless they are quoted.

    If the environment variable is not defined or if there is not
    enough memory, _envargs() does not modify *ARGCP and *ARGVP.

  See also: getenv(), main(), _response(), _wildcard()

------------------------------------------------------------------------------
#include <io.h>                                                           [PC]

int eof (int handle);

    Check whether the current position of HANDLE is at the end of the
    file or not.

  Return value:

    1       at end of file

    0       not at end of file

    -1      error

------------------------------------------------------------------------------
#include <errno.h>                                                       [emx]

int *_errno (void);

    Return the address of the errno value.  In single-thread programs,
    errno is a variable, in multithread programs, errno is an lvalue
    that depends on the thread number.  In consequence, you cannot
    create a library that uses errno and can be used for both
    single-thread and multithread programs.  To solve this problem,
    the _errno() function has been provided: it returns a pointer to
    the errno value in both single-thread and multithread programs.
    Use the option

        -D__ST_MT_ERRNO__

    on the GCC command line to define errno to call _errno().
    However, using _errno() doesn't remove any other reasons why your
    library might not be thread-safe.

  See also: errno

------------------------------------------------------------------------------
#include <process.h>                                                    [UNIX]

int execl (const char *name, const char *arg0, ...);
int execle (const char *name, const char *arg0, ...);
int execlp (const char *name, const char *arg0, ...);
int execlpe (const char *name, const char *arg0, ...);
int execv (const char *name, char * const argv[]);
int execve (const char *name, char * const argv[], char * const envp[]);
int execvp (const char *name, char * const argv[]);
int execvpe(const char *name, char * const argv[], char * const envp[]);

    Replace calling process with a new process.  The calling process
    terminates after starting the new process.  NAME points to a
    string containing the name of the executable file to run.

    Use execl(), execle(), execlp() or execlpe() for passing a fixed
    number of arguments.  ARG0 points to a string containing the 0th
    argument which is the program name, by convention.  Following
    ARG0, pointers to the argument strings are passed.  After the last
    argument pointer, a null pointer cast to `char *' must be
    following.  At least ARG0 must be specified.

    Use execv(), execve(), execvp() or execvpe() for passing a
    variable number of arguments.  ARGV points to an array of pointers
    to strings.  The first entry is the program name, by convention.
    The last argument must be followed by a null pointer.

    execl(), execlp(), execv() and execvp() pass the environment of
    the current process to the new process.  To pass a different
    environment to the new process, pass a pointer to an array of
    pointers to strings after the null argument pointer of execle()
    and execlpe() or pass the pointer in the ENVP argument of execve()
    and execvpe().  The last pointer to an environment string in the
    array must be followed by a null pointer.

    If both the old process and the new process use emx.exe or
    emx.dll, the new process will inherit the signal actions of the
    old process: Signals set to SIG_IGN in the old process will be set
    to SIG_IGN in the new process, signals set to SIG_DFL in the old
    process will be set to SIG_DFL in the new process, signals caught
    in the old process will be set to SIG_DFL in the new process.

    When the new process ends, the parent process will be notified by
    SIGCHLD and wait() will return the original process ID.

  Return value:

    These functions return -1 if an error occurs.  On success, they do
    not return.

  Restrictions:

    Native DOS programs cannot be run.  The new process gets a new
    process ID.  Unless the new process is an emx program (using
    emx.dll or emx.exe), the actions for all signals are reset to
    SIG_DFL in the new process

  See also: fork(), sigaction(), signal(), spawn*(), wait(), waitpid()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _execname (char *buf, size_t bufsize);

    Copy the full path name of the executable file for the current
    process to the array pointed to by BUF.  It is assumed that there
    are BUFSIZE bytes available at BUF, including the terminating null
    character.

  Return value:

    _execname() returns 0 on success, -1 on error (buffer too small,
    for instance).

  Restrictions:

    _execname() is not yet implemented under DOS.

  See also: main()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

void exit (int ret);

    Flush streams, remove temporary files, call functions set by
    atexit() and terminate the current process.  The return code RET
    is passed to the parent process.  If RET is negative or greater
    than 255, 255 will be used instead to avoid returning 0 (success)
    for non-zero RET due to truncation to 8 bits.

  See also: abort(), atexit(), _exit()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [UNIX]

void _exit (int ret);

    Terminate the process without flushing streams, removing temporary
    files or calling functions set by atexit().  The return code RET
    is passed to the parent process.  If RET is negative or greater
    than 255, 255 will be used instead to avoid returning 0 (success)
    for non-zero RET due to truncation to 8 bits.

  See also: abort(), atexit(), exit()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double exp (double x);
long double expl (long double x);

    exp() computes the exponential function of X.  On overflow, +INF
    is returned and errno set to ERANGE.

    expl() uses the long double format.

  Return value:

    exp() returns e^X.  On overflow, exp() returns +INF.

  See also: log(), pow()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

void *_expand (void *mem, size_t new_size);

    Try to expand the memory block pointed to by MEM to the new size
    NEW_SIZE.  If the block cannot be expanded, NULL is returned.
    Otherwise, MEM is returned.  Please do not use this function --
    use realloc() instead.

  Return value:

    _expand() returns MEM if the block could be resized.  Otherwise,
    _expand() returns NULL.

  See also: realloc()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double fabs (double x);
long double fabsl (long double x);

    Return the absolute value of X: If X is negative, -X is returned.
    Otherwise, X is returned.

    fabsl() uses the long double format.

  Return value:

    fabs() returns the absolute value of its argument.

  See also: abs(), labs()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]

FILE *_fassign (FILE *target, FILE *source);

    Replace the stream pointed to by TARGET with the stream pointed to
    by SOURCE.  After a successful call of _fassign(), the stream
    pointed to by SOURCE is no longer available and the stream pointed
    to by TARGET is associated with the file with which the stream
    pointed to by SOURCE was associated.  _fassign() closes the file
    previously associated with the stream pointed to by TARGET.

    If TARGET and SOURCE are equal and both point to a stream,
    _fassign() does nothing.

  Return value:

    _fsasign() returns TARGET if successful.  _fassign() returns NULL
    on error.

  See also: freopen(), _mfopen(), v_fopen(), wm_fopen()

  Example:

    #include <stdio.h>
    #include <sys/winmgr.h>
    
    wm_handle wh_stderr;
    
    void init (void)
    {
      FILE *f;
    
      /*...*/
      f = wm_fopen (wh_stderr);
      _fassign (stderr, f);
    }

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fclose (FILE *stream);

    Flush and close the stream STREAM.  STREAM must be open prior to
    calling fclose().  If the stream buffer was automatically
    allocated, it will be deallocated.  If the stream was created with
    tmpfile(), the temporary file will be deleted.

  Return value:

    0       success

    EOF     error

  See also: fcloseall(), fflush(), fopen(), tmpfile()

------------------------------------------------------------------------------
#include <stdio.h>                                                        [PC]

int fcloseall (void);

    Close all open streams.

  Return value:

    fcloseall() returns the number of streams closed.  On error,
    fcloseall() returns EOF.

  See also: fclose(), flushall(), fopen()

------------------------------------------------------------------------------
#include <fcntl.h>                                                     [BSD *]

int fcntl (int handle, int request);
int fcntl (int handle, int request, int arg);

    File control.  The following REQUEST codes are implemented
    (partially):

    F_DUPFD
            Create a duplicate of the file handle HANDLE, that is,
            another handle that refers to the same file or device or
            pipe as HANDLE.  Both handles share the same file pointer.
            The lowest numbered available file handle greater than or
            equal to ARG will be used and returned.

    F_GETFL
            Return the file flags of the file associated with HANDLE.
            Currently, only two file flags are supported by fcntl():
            O_APPEND and O_NONBLOCK (alias O_NDELAY).

    F_SETFL
            Set the file flags of the file associated with HANDLE.
            Currently, only two file flags are supported by fcntl():
            O_APPEND and O_NONBLOCK (alias O_NDELAY).  O_NONBLOCK has
            an effect only if HANDLE is 0 and HANDLE refers to the
            keyboard and the IDEFAULT and ICANON bits are not set.
            O_NONBLOCK also works for pipes created by emx programs,
            for named pipes, and for sockets.  See `General terminal
            interface' and read().

    F_GETFD
            Return file descriptor flags.  If the return value
            includes FD_CLOEXEC (close-on-exec flag), HANDLE will not
            be inherited by child processes created with exec*() and
            spawn*().

    F_SETFD
            Set file-descriptor flags.  If the flags include
            FD_CLOEXEC, (close-on-exec flag), HANDLE will not be
            inherited by child processes created with exec*() and
            spawn*().

  Return value:

    On error, fcntl() sets errno and returns -1.  Otherwise, fcntl()
    returns 0 unless a different return value is defined above.

  Errors:

    EBADF   The HANDLE argument is not a valid open file descriptor.

    EINVAL  REQUEST is invalid.

            REQUEST is F_DUPFD and ARG is out of range.

            REQUEST is F_SETFL and ARG is not a combination of
            supported flags.

    EMFILE  REQUEST is F_DUPFD and no file descriptor greater than or
            equal to ARG is available.

  Restrictions:

    O_NONBLOCK is not supported by the system call library sys.lib
    (-Zsys).

    Duplicated file handles should share the file status flags
    O_APPEND and O_NONBLOCK; however, F_DUPFD, dup(), and dup2() just
    copy the file status flags, changing the file status flags after
    duplicating a file handle does not affect the other file handle.

    F_GETFL should return the access mode but doesn't.

    Under DOS, FD_CLOEXEC is currently ignored for child processes
    which are DOS programs (vs.  emx programs).

  See also: dup(), ioctl(), open(), read()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

FILE *fdopen (int handle, const char *mode);

    Create a stream for the file handle HANDLE.  The flags in the mode
    string pointed to by MODE should match the mode used for opening
    the file handle HANDLE.  If b or t is used in the mode string, the
    handle will be changed using setmode() to O_BINARY or O_TEXT mode,
    respectively.  If neither b nor t is used, the translation mode is
    not changed.  You should not rely on this behavior: always specify
    the desired translation mode.

  Return value:

    fdopen() returns a new stream.  On error, fdopen() returns NULL.

  See also: fopen(), open()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int ferror (FILE *stream);
int feof (FILE *stream);

    ferror() checks STREAM for an error condition.  feof() checks
    STREAM for an end-of-file condition.

  Return value:

    ferror() returns a non-zero value if the error indicator of STREAM
    is set.  Otherwise, ferror() returns zero.  feof() returns a
    non-zero value if the end-of-file indicator of STREAM is set.
    Otherwise, feof() returns zero.

  Hints:

    The end-of-file indicator is not set if the file position
    indicator reaches the end of the file; rather, it is set when
    attempting to read past end-of-file.

  See also: clearerr(), fgetc(), rewind()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fflush (FILE *stream);

    If STREAM is an output stream or an update stream in write mode,
    write unwritten data of STREAM's buffer to its file.  If STREAM is
    NULL, fflush() is applied to all open output streams and update
    streams in write mode.

    If STREAM is an update stream in write mode, the next operation on
    STREAM may be input or output.

  Return value:

    fflush() returns EOF if a write error occurs, otherwise zero.

  Implementation-defined behavior:

    If STREAM is an input stream, fflush() discards the buffer
    contents and undoes any effects of ungetc().  If the stream is
    connected to a disk file, the buffer will be refilled (no data
    lost) on the next input operation.  If the stream is connected to
    a character device, a pipe, or a socket, the buffer contents will
    be lost.  (Note that this does not clear the type-ahead buffer of
    the keyboard device!  Only the data which has been read into the
    buffer will be discarded.)

  Hints:

    Use fflush() for switching an update stream from write mode to
    read mode: output may not be directly followed by input --
    fflush(), fseek(), fsetpos(), or rewind() must be called between
    output and input.

    Use fflush() to force output (for instance, a prompt) of a
    buffered stream to a device: you should do

        fflush (stdout);

    before getting input from stdin, in case stdout is connected to a
    pipe (a stream connected to a pipe is buffered by default).

  See also: fclose(), fopen(), fseek(), ungetc()

------------------------------------------------------------------------------
#include <strings.h>                                                     [BSD]

int ffs (int i);

    Find the first (least significant, right-most) bit in I which is
    set and return the index of that bit.  The least significant bit
    is numbered 1, the most significant bit is numbered 32.

  Return value:

    ffs() returns the smallest number N for which bit N is set in I
    (the least significant bit is numbered 1).  If there are no bits
    set in I (that is, I is zero), ffs() returns zero.

  See also: __fls()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fgetc (FILE *stream);

    Read the next character (as unsigned char converted to an int)
    from the input stream STREAM and advance the file position
    indicator of the stream (if defined).  All input from streams
    takes place as if characters were read by successive calls to
    fgetc().

    fgetc() is a function, in contrast to getc().

  Return value:

    fgetc() returns the next character from the stream.  If the stream
    is at end-of-file (before fgetc() is called), fgetc() sets the
    end-of-file indicator of the stream and returns EOF.  If a read
    error occurs, fgetc() sets the error indicator of the stream and
    returns EOF.

  Hints:

    Use feof() and ferror() to distinguish an end-of-file condition
    from a read error.

    If you assign the return value of fgetc() to a char variable, you
    cannot compare it to EOF.  Use an int variable instead.

  See also: feof(), ferror(), fgetchar(), getc(), getchar()

------------------------------------------------------------------------------
#include <stdio.h>                                                        [PC]

int fgetchar (void);

    fgetchar() is equivalent to fgetc (stdin).

  Return value:

    fgetchar() returns the next character from stdin.  If stdin is at
    end-of-file (before fgetchar() is called), fgetchar() sets the
    end-of-file indicator of stdin and returns EOF.  If a read error
    occurs, fgetchar() sets the error indicator of stdin and returns
    EOF.

  Hints:

    Use getchar() or fgetc(stdin) instead of fgetchar() as fgetchar()
    is not portable.

  See also: fgetc(), getchar()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fgetpos (FILE *stream, fpos_t *pos);

    Store the current position of the file pointer of the file STREAM
    in the variable pointed to by POS.

  Return value:

    0       success

    non-0   error

  Restrictions:

    fgetpos() does not work for text-mode streams unless either CR/LF
    pairs or LF only is used for all lines of the file.  If there are
    lines terminated with CR/LF and lines terminated with LF,
    fgetpos() does not work correctly.

  See also: fsetpos(), ftell()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

char *fgets (char *buffer, int n, FILE *stream);

    Read a string from STREAM to the array pointed to by BUFFER.  Stop
    after reading N-1 characters or after a newline character has been
    read.  A null character is appended.

  Return value:

    fgets() returns BUFFER.  If an error occurs or the end of the file
    is reached, fgets() returns NULL.

  See also: gets(), scanf()

------------------------------------------------------------------------------
#include <io.h>                                                           [PC]

long filelength (int handle);

    Get the length of the file HANDLE, in bytes.

  Return value:

    filelength() returns the length of the file HANDLE.  If there is
    an error, filelength() returns -1.

  See also: chsize(), ftruncate(), lseek()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

int fileno (FILE *stream);

    Get the file handle associated with STREAM.

  Return value:

    fileno() returns the file handle associated with STREAM.

  See also: fdopen()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _filesys (const char *drive, char *name, size_t size);

    Copy the file system type of the disk drive whose name is in the
    string pointed to by DRIVE to the array pointed to by NAME.  The
    size of the array is SIZE bytes.  DRIVE must point to a drive
    letter followed by a colon.  Examples for file system types are:
    FAT, LAN, HPFS, CDFS, NFS.

  Return value:

    0       Success.  The file system type has been copied to NAME.

    -1      Error.  errno contains the error number.

  See also: _fnlwr()

  Example:

    char drive[3] = "C:";
    char fsys[16];
    
    if (_filesys (drive, fsys, sizeof (fsys)) != 0)
      perror ("_filesys");
    else
      printf ("File system: %s\n", fsys);

    Typical output of the example:

        File system: FAT

------------------------------------------------------------------------------
#include <fcntl.h>                                                      [UNIX]

int flock (int handle, int operation)

    Perform file locking.

  Return value:

    0       success

    -1      error

  Restrictions:

    flock() is not yet implemented (dummy function).

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double floor (double x);
long double floorl (long double x);

    Compute the largest integer that is less than or equal to X (round
    down).

    floorl() uses the long double format.

  Return value:

    Return as floating-point number the largest integer that is less
    than or equal to X.

  See also: ceil(), rint(), trunc()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]

int __fls (int i);

    Find the last (most significant, left-most) bit in I which is set
    and return the index of that bit.  The most significant bit is
    numbered 32, the least significant bit is numbered 1.

    This function is implemented as inline function.

  Return value:

    __fls() returns the greatest number N for which bit N is set in I
    (the least significant bit is numbered 1).  If there are no bits
    set in I (that is, I is zero), __fls() returns zero.

  See also: ffs()

------------------------------------------------------------------------------
#include <stdio.h>                                                        [PC]

int flushall (void);

    Flush the buffers of all open streams.  Write the buffers of
    streams open for writing to their files, clear the buffers of
    streams open for reading.

    Locked streams are ignored; therefore, flushall() can be called in
    signal handlers.

  Return value:

    flushall() returns the number of open streams.

  Hints:

    If you don't need the return value (that is, the number of open
    streams) and deadlock on locked streams cannot occur, you should
    use

        fflush (NULL)

    instead of flushall().

  See also: fflush()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double fmod (double x, double y);
long double fmodl (long double x, long double y);

    Compute remainder of X/Y.  The return value z is calculated such
    that X = i * Y + z, where i is an integer, z has the same sign as
    X and |z| < |Y|.  If Y is 0.0, fmod() returns 0.0.

    fmodl() uses the long double format.

  Return value:

    See above.

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

int _fmutex_available (_fmutex *sem);

    Check if the _fmutex semaphore pointed to by SEM is available or
    owned, without changing the state of the semaphore and without
    blocking.  Return zero if the semaphore is owned, return a
    non-zero value if the semaphore is available.  Note that
    _fmutex_available() just returns a snapshot of the state of the
    semaphore; in presence of other threads or, in case of a shared
    semaphore, other processes, the state may change at any time, even
    before _fmutex_available() returns.  This function can be used to
    avoid deadlock.

  Return value:

    _fmutex_available() returns a non-zero value if the semaphore is
    available.  _fmutex_available() returns 0 if the semaphore is
    owned.  The return value is undefined if the object pointed to by
    SEM has not been initialized by _fmutex_create().

  See also: _fmutex_close(), _fmutex_create(), _fmutex_open(),
            _fmutex_release(), _fmutex_request(), _rmutex_available(),
            _smutex_available()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

unsigned _fmutex_close (_fmutex *sem);
void _fmutex_checked_close (_fmutex *sem);

    Close an _fmutex semaphore.  SEM should point to an _fmutex object
    initialized by _fmutex_create().  If there have been N calls to
    _fmutex_open() for this semaphore, N+1 calls to _fmutex_close()
    are required to destroy the semaphore, one call for
    _fmutex_create() and one call per _fmutex_open().  The semaphore
    can no longer be used after it has been destroyed.

    _fmutex_checked_close() does not return an error code; it calls
    abort() on failure.

  Return value:

    _fmutex_close() returns 0 if successful.  Otherwise,
    _fmutex_close() returns an OS/2 error code defined in <os2.h> such
    as ERROR_INVALID_HANDLE.  Under DOS, _fmutex_close() always
    returns 0.

  See also: abort(), atexit(), _fmutex_available(), _fmutex_create(),
            _fmutex_open(), _fmutex_release(), _fmutex_request(),
            _rmutex_close()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

unsigned _fmutex_create (_fmutex *sem, unsigned flags);
void _fmutex_checked_create (_fmutex *sem, unsigned flags);

    Create an _fmutex semaphore.  SEM points to the _fmutex object to
    be initialized.  The semaphore is local to the process if FLAGS is
    0.  The semaphore can be shared by multiple processes if FLAGS is
    _FMC_SHARED.  A shared _fmutex semaphore must be located in shared
    memory (that is, SEM must point to an object in shared memory).

    _fmutex_checked_create() does not return an error code; it calls
    abort() on failure.

  Return value:

    _fmutex_create() returns 0 if successful.  Otherwise,
    _fmutex_create() returns an OS/2 error code defined in <os2.h>
    such as ERROR_TOO_MANY_HANDLES.  Under DOS, _fmutex_create()
    always returns 0.

  See also: abort(), _fmutex_available(), _fmutex_close(),
            _fmutex_dummy(), _fmutex_open(), _fmutex_release(),
            _fmutex_request(), _rmutex_create()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

void _fmutex_dummy (_fmutex *sem);

    Create a dummy _fmutex semaphore.  SEM points to the _fmutex
    object to be initialized.  Behavior is undefined if ownership of a
    dummy _fmutex semaphore is requested when the semaphore is owned.
    _fmutex_close() must not be called on a dummy _fmutex semaphore.

  See also: _fmutex_create(), _rmutex_dummy()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

unsigned _fmutex_open (_fmutex *sem);
void _fmutex_checked_open (_fmutex *sem);

    Open an _fmutex semaphore.  SEM should point to an _fmutex object
    initialized by _fmutex_create().  _fmutex_open() is used to obtain
    access to a shared _fmutex semaphore created by another process.
    All threads of the process which called _fmutex_create() have
    access to the semaphore without calling _fmutex_open().  Call
    _fmutex_close() when you no longer need access to the semaphore.

    _fmutex_checked_open() does not return an error code; it calls
    abort() on failure.

  Return value:

    _fmutex_open() returns 0 if successful.  Otherwise, _fmutex_open()
    returns an OS/2 error code defined in <os2.h> such as
    ERROR_INVALID_HANDLE.  Under DOS, _fmutex_open() always returns 0.

  See also: abort(), atexit(), _fmutex_available(), _fmutex_close(),
            _fmutex_create(), _fmutex_release(), _fmutex_request(),
            _rmutex_open()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

unsigned _fmutex_release (_fmutex *sem);
void _fmutex_checked_release (_fmutex *sem);

    Relinquish ownership of the _fmutex semaphore pointed to by SEM.
    If another thread blocks in _fmutex_request() for this semaphore,
    _fmutex_release() will unblock one of the blocking threads.  The
    semaphore should be owned when _fmutex_release() is called.
    Though not strictly necessary, ownership of the semaphore should
    have been requested by the same thread.

    _fmutex_checked_release() does not return an error code; it calls
    abort() on failure.  Note that _fmutex_checked_release() is slower
    than _fmutex_release() because it is not inlined.

  Return value:

    _fmutex_release() returns 0 if successful.  Otherwise,
    _fmutex_release() returns an OS/2 error code defined in <os2.h>
    such as ERROR_TOO_MANY_HANDLES.

  See also: abort(), __cxchg(), _fmutex_available(), _fmutex_close(),
            _fmutex_create(), _fmutex_open(), _fmutex_request(),
            _rmutex_release()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>

unsigned _fmutex_request (_fmutex *sem, unsigned flags);
void _fmutex_checked_request (_fmutex *sem, unsigned flags);

    Request ownership of the _fmutex semaphore pointed to by SEM.  If
    FLAGS is 0, _fmutex_request() returns ERROR_INTERRUPT if
    interrupted by a signal while blocking.  FLAGS is zero or a set of
    flags combined with the | operator.  If FLAGS includes
    _FMR_IGNINT, _fmutex_request() does not return if a signal occurs
    while blocking.  If FLAGS includes _FMR_NOWAIT and the semaphore
    is owned, _fmutex_request() returns immediately ERROR_MUTEX_OWNED.

    _fmutex_checked_request() does not return an error code; it calls
    abort() on failure.  Note that _fmutex_checked_request() is slower
    than _fmutex_request() because it is not inlined.

    If the semaphore is available, it will be set to owned and
    _fmutex_request() will return immediately.  If the semaphore is
    owned, _fmutex_request() will block while the semaphore is owned.
    When _fmutex_release() is called for the semaphore, one of the
    threads blocking in _fmutex_request() for this semaphore will wake
    up and gain ownership of the semaphore.

    Note that ownership of an _fmutex semaphore is not tied to a
    thread, that is, it's not a thread which owns the semaphore.  This
    is in contrast to OS/2's mutex semaphores (HMTX).  Deadlock will
    occur if _fmutex_request() is called twice for the same semaphore
    by the same thread without an intervening call to
    _fmutex_release().  This fact is important to keep in mind in
    presence of signals.  Signal handlers must not request semaphores
    which can be owned by the interrupted code.  You might want to
    block signals before requesting ownership of an _fmutex semaphore.

  Return value:

    _fmutex_request() returns 0 if successful.  Otherwise,
    _fmutex_request() returns an OS/2 error code defined in <os2.h>
    such as ERROR_INTERRUPT.

  Restrictions:

    Under DOS, _fmutex_request() and _fmutex_checked_request() crash
    if the semaphore is already owned.

  See also: abort(), __cxchg(), _fmutex_available(), _fmutex_close(),
            _fmutex_create(), _fmutex_open(), _fmutex_release(),
            _rmutex_request()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _fncmp (const unsigned char *string1, const unsigned char *string2);

    _fncmp() compares the two file name strings pointed to by STRING1
    and STRING2 and returns zero if the two strings are identical
    after conversion to upper case.  Otherwise, a non-zero value is
    returned which is negative if the string pointed to by STRING1 is
    less than the string pointed to by STRING2 and positive if the
    string pointed to by STRING1 is greater than the string pointed to
    by STRING2 after conversion to upper case.  Conversion to upper
    case includes accented characters etc., depending on the current
    country code and code page, DBCS characters are compared as is.

  Return value:

    <0      1st string < 2nd string

    =0      1st string = 2nd string

    >0      1st string > 2nd string

  See also: _nls_init(), _nls_strupr(), strcmp()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char **_fnexplode (const char *mask);
void _fnexplodefree (char **list);

    Wildcard expansion of MASK.  _fnexplode() returns a vector
    containing pointers to the file name strings.  The list includes
    directories.  Hidden and system files are omitted.  The end of the
    list is marked by a NULL pointer.  On error, NULL is returned.
    MASK not being a wildcard or no files matching MASK is treated as
    error.  Memory is allocated with malloc().

    _fnlwr() is used to convert file names to lower case on
    upper-case-only file systems.

    Use _fnexplodefree() to free the memory allocated for a file name
    list.

  Return value:

    _fnexplode() returns a vector containing pointers to file name
    strings.

  See also: _dt_read(), _fnlwr(), glob(), opendir(), _wildcard()

  Example: See /emx/samples/eatool.c

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char _fngetdrive (const char *src);

    Extract the drive name of the path name SRC.

  Return value:

    _fngetdrive () return as upper-case letter the drive name in the
    path name pointed to by SRC.  If the string does not contain a
    drive name, _fngetdrive() returns 0.

  See also: _fnisabs(), _fnisrel(), _getdrive()

  Example:

    /* this fails if the -r emx option is used */
    
    char *fname, drive;
    
    drive = _fngetdrive (fname);
    if (drive == 0)
      drive = _getdrive ();

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _fnisabs (const char *name);
int _fnisrel (const char *name);

    _fnisabs() returns a non-zero value if the string pointed to by
    NAME is an absolute file name.  Otherwise, it returns 0.  Absolute
    file names start with \ or /, optionally preceded by a drive name.
    If _fnisabs() returns a non-zero value, the location of the file
    whose name is in the string pointed to by NAME does not depend on
    the current working directory (though it may depend on the current
    drive).

    _fnisrel() returns a non-zero value if the string pointed to by
    NAME is a relative file name.  Otherwise is returns 0.  Relative
    file names do not start with \ or / or a drive name.  If
    _fnisrel() returns a non-zero value, you can prepend a directory
    to the string pointed to by NAME.

    Note that both _fnisabs() and _fnisrel() return 0 for path names
    which start with a drive name not followed by \ or /.

        name                   _fnisabs (name)  _fnisrel (name)
        
        "\\"                   non-zero         zero
        "/etc/passwd"          non-zero         zero
        "c:\\foo\\bar"         non-zero         zero
        "c:/"                  non-zero         zero
        "foo"                  zero             non-zero
        "foo/bar"              zero             non-zero
        "c:foo"                zero             zero
        "d:"                   zero             zero
        ""                     zero             zero

  Return value:

    _fnisabs() returns a non-zero value if the string pointed to by
    NAME is an absolute file name.  Otherwise, _fnisabs() returns 0.

    _fnisrel() returns a non-zero value if the string pointed to by
    NAME is a relative file name.  Otherwise _fnisrel() returns 0.

  See also: _abspath(), _fngetdrive()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _fnlwr (char *name);
void _fnlwr2 (char *name, const char *base);
void _rfnlwr (void);
void _sfnlwr (const char *name);

    _fnlwr() converts the file name pointed to by NAME to lower case
    unless the file system is case preserving.  Accented characters
    etc. are converted as well, DBCS characters are not changed.  If
    the file name does not contain a drive letter, it is assumed to
    refer to the drive set by _sfnlwr().  To save time, _fnlwr()
    caches information about file systems.  If the file system of a
    drive changes or if the current drive changes, you should call
    _rfnlwr() to reset the cache.  _sfnlwr() takes the drive name from
    the string pointed to by NAME for future _fnlwr() calls.  If
    _sfnlwr() hasn't been called since the last call to _rfnlwr() or
    if the file name does not contain a drive letter, _fnlwr() uses
    the current drive.

    _fnlwr2() is a variant of _fnlwr() which should be used when
    converting only a suffix of a path name to lower case.  NAME
    points to the suffix, BASE points to the beginning of the path
    name.  The string pointed to by BASE is used for getting the drive
    letter.

  Hints:

    _fnlwr2() should be used instead of _sfnlwr() and _fnlwr()
    whenever possible.

  See also: _filesys(), _nls_init(), _nls_strlwr()

------------------------------------------------------------------------------
#include <fnmatch.h>                                                 [POSIX.2]

int fnmatch (const char *pattern, const char *name, int flags);

    The fnmatch() function checks the string pointed to by NAME to see
    if it matches the file name pattern pointed to by the PATTERN
    argument.  The interpretation of the strings pointed to by PATTERN
    and NAME are is modified by FLAGS, which is the bitwise OR of zero
    or more of the following flags:

    FNM_NOESCAPE
            If FNM_NOESCAPE is NOT set, a backslash character (`\') in
            the string pointed to by PATTERN followed by any other
            character matches that second character in the string
            pointed to by NAME.  In particular, `\\' matches a
            backslash in the string pointed to by NAME.

            If FNM_NOESCAPE is set, a backslash character in the
            string pointed to by PATTERN is treated as an ordinary
            character.

    FNM_PATHNAME
            If FNM_PATHNAME is set, a slash character (`/') in the
            string pointed to by NAME must be explicitely matched by a
            slash in the string pointed to by PATTERN; it is not
            matched by `?', `*', or `[]' in the string pointed to by
            PATTERN.

            If FNM_PATHNAME is not set, a slash character in the
            string pointed to by NAME is treated as an ordinary
            character.

            If _FNM_OS2 or _FNM_DOS is set, the backslash character is
            treated like a slash, with repect to FNM_PATHNAME.

    FNM_PERIOD
            If FNM_PERIOD is set, then a `leading' period character
            (`.') in the string pointed to by NAME matches a period
            (but not `?', `*', and `[]') in the string pointed to by
            PATTERN.  The meaning of `leading' depends on
            FNM_PATHNAME: If FNM_PATHNAME is set, a period is
            `leading' if it is the first character in the string
            pointed to by NAME or if it immediately follows a slash.
            If FNM_PATHNAME is not set, a period is `leading' if it is
            the first character of the string pointed to by NAME.

            If FNM_PERIOD is not set, a period in the string pointed
            to by NAME is treated as an ordinary character.

    _FNM_IGNORECASE
            If _FNM_IGNORECASE is set, letter case is ignored, that
            is, lower case letters match the corresponding upper case
            letters.  If _FNM_IGNORECASE is not set, lower case
            letters and upper case letters are distinct.

            _FNM_IGNORECASE is an emx extension.

    _FNM_PATHPREFIX
            If _FNM_PATHPREFIX is set, the string pointed to by
            PATTERN may match a complete path prefix of the string
            pointed to by NAME, that is, the string pointed to by NAME
            can have additional path components at the end.

            _FNM_PATHPREFIX is an emx extension.

    _FNM_POSIX
            If _FNM_POSIX is set, or none of _FNM_OS2 and _FNM_DOS are
            set, fnmatch() has POSIX.2 semantics.

            _FNM_POSIX is an emx extension.

    _FNM_OS2
            If _FNM_OS2 is set, fnmatch() has OS/2 semantics: Path
            components in the string pointed to by NAME have an
            implicit period at the end if they don't contain a period.
            A period at the end of a component in the string pointed
            to by PATTERN may match zero characters at the end of a
            component of the string pointed to by NAME.  `?' may match
            zero characters at the end of a component of the string
            pointed to by NAME or before a period.  "/*/" does not
            match UNC names.  `[' in the string pointed to by PATTERN
            is treated as an ordinary character.  `\' is a path
            separator.  _FNM_NOESCAPE implied.

            _FNM_OS2 is an emx extension.  At most one of _FNM_POSIX,
            _FNM_OS2, and _FNM_DOS can be set.

    _FNM_DOS
            If _FNM_OS2 is set, fnmatch() has DOS semantics: Path
            components in the string pointed to by NAME have an
            implicit period at the end if they don't contain a period.
            A period at the end of a component in the string pointed
            to by PATTERN may match zero characters at the end of a
            component of the string pointed to by NAME.  `?' may match
            zero characters at the end of a component of the string
            pointed to by NAME or before a period.  `*' does not match
            a period.  "/*/" does not match UNC names.  `[' in the
            string pointed to by PATTERN is treated as an ordinary
            character.  `\' is a path separator.  _FNM_NOESCAPE is
            implied.

            _FNM_DOS is an emx extension.  At most one of _FNM_POSIX,
            _FNM_OS2, and _FNM_DOS can be set.

    The characters `?', `*', and `[]' are interpreted as wildcard
    characters in the pattern.  `?' matches one character, `*' matches
    zero or more characters.  For _FNM_POSIX, `[]' matches the set of
    characters listed between the brackets, ranges (such as `[0-9]')
    are allowed.  If the first character after `[' is `!', all
    characters NOT in the set match the set.  DBCS characters are not
    allowed in sets.

  Return value:

    fnmatch() returns 0 if the string pointed to by NAME matches the
    string pointed to by PATTERN.  fnmatch() returns FNM_NOMATCH if
    the string pointed to by NAME does not match the string pointed to
    by PATTERN.  fnmatch() returns another non-zero value on error.

  Implementation-defined behavior:

    If the first character after `[' is `^', all characters NOT in the
    set match the set.

  Bugs:

    Ranges in `[]' which include letters don't work correctly if
    _FNM_IGNORECASE is set.

  See also: glob(), _nls_tolower()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char *_fnslashify (char *name);

    _fnslashify() replaces backslashes by slashes in the string
    pointed to by NAME.

    _fnslashify() properly handles DBCS characters.

  Return value:

    _fnslashify() returns NAME.

  See also: _nls_init()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

FILE *fopen (const char *fname, const char *mode);

    Open a stream.  FNAME points to a string giving the name of the
    file, MODE points to a string which specifies the file mode:

    r

        Open the file for reading.  The file must exist.

    w

        Open the file for writing.  If the file exists, it will be
        truncated to 0 bytes, destroying its contents.  If the file
        does not exist, it will be created.

    a

        Open the file for appending.  Writing will always take place
        at the end of the file.  If the file does not exist, it will
        be created.

    r+

        Open the file for both reading and writing.  The file must
        exist.

    w+

        Open the file for both reading and writing.  If the file
        exists, it will be truncated to 0 bytes, destroying its
        contents.  If the file does not exist, it will be created.

    a+

        Open the file for both reading and appending.  Writing will
        always take place at the end of the file.  If the file does
        not exist, it will be created.

    There are two additional MODE flags which can be appended to one
    of the above modes: t for text mode, b for binary mode.  Text
    mode, which is the default, skips CR characters on input and
    converts newline characters to CR/LF pairs on output.  If the last
    character of a file is Ctrl-Z, it is discarded on input.  Binary
    mode disables these transformations.

    The file is opened in the sharing mode SH_DENYNO, see sopen().  If
    you want to use a different sharing mode, use _fsopen().

  Return value:

    fopen() returns a new stream.  On error, fopen() returns NULL.

  See also: fclose(), fdopen(), freopen(), _fsopen(), sopen()

------------------------------------------------------------------------------
#include <unistd.h>                                                [POSIX.1 *]

int fork (void);

    Duplicate the current process.  A child process is created which
    is a copy of the calling process.  Both the parent process and the
    child process resume at the point where fork() was called.  The
    child process inherits the following attributes of the parent
    process:

    - environment

    - memory (data segment, heap, stack, and data segments of DLLs
      created with emx 0.9c or later)

    - signal actions

    - file handles

    - current working directories

    - umask

    - flags set with _uflags()

    - break points.  This is an OS/2 bug.  To debug a program
      containing fork(), set a breakpoint in the branch of execution
      that's executed only in the parent process

    The new process differs from the parent process in the following
    ways:

    - the child process has a unique process ID

    - the child process has a different parent process ID (the process
      ID of the parent process)

    - the child process has copies of the file descriptors of the
      parent process.  The file pointers are shared

    - Terminal settings are reset in the child process (that is, the
      IDEFAULT bit is set)

    - all resources allocated using OS/2 calls are not inherited by
      the child process: semaphores, queues, threads, memory, file
      handles, etc.

    - the alarm clock is turned off

    - the CPU time (returned by clock()) is set to 0

    - non-shared _rmutex semaphores

    When the new process terminates, SIGCHLD is sent to the process
    which forked that process.

  Return value:

    On success, fork() returns the process ID of the new process to
    the calling process, 0 to the new process.  On error, fork()
    returns -1.

  Restrictions:

    fork() is not implemented for DOS.  fork() works only in programs
    linked by ld.  It does not work in programs linked by LINK386.
    fork() is not available with the system call library sys.lib
    (-Zsys).

    The data segments of dynamic link libraries created with emx 0.9c
    or later are copied, therefore fork() can be used with the
    -Zcrtdll option of GCC and with DLLs created with emx 0.9c and
    later.  However, data segments of DLLs not created with emx or
    created with emx 0.9b or older are not duplicated, therefore
    fork() does not work correctly when using such DLLs.

    fork() is very inefficient for OS/2.  To start a child process,
    use spawn*() instead of fork() and exec*().

    If the parent process uses the general terminal interface for the
    keyboard, the child process cannot read from the keyboard using
    _read_kbd(), the general terminal interface, or the Kbd OS/2 API
    functions.

    If the process has a non-contiguous heap (that is, multiple heap
    objects), fork() will fail.  Increase the initial heap size to
    work around this problem.  If any DLL used by the program shares
    the heap with the program and uses the heap in _DLL_InitTerm() by
    calling sbrk(), malloc(), etc., fork() will fail.  In both cases,
    fork() will return -1 and set errno to ENOMEM.

  See also: alarm(), exec*(), _rmutex_create(), sbrk(), sigaction(),
            signal(), spawn*(), _uflags(), wait(), waitpid()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

int fpclassify (float x);
int fpclassify (double x);
int fpclassify (long double x);

    Classify X as zero (FP_ZERO), subnormal (FP_SUBNORMAL), normal
    (FP_NORMAL), infinite (FP_INFINITE), or NaN (FP_NAN).  The
    argument X must be of a floating-point type.  Classification is
    based on the type of the argument.

  Return value:

    fpclassify() returns the value of one of the following macros:
    FP_ZERO, FP_SUBNORMAL, FP_NORMAL, FP_INFINITE, FP_NAN.

  See also: copysign(), isfinite(), isnan(), isnormal(), signbit()

------------------------------------------------------------------------------
#include <float.h>                                                        [PC]

void _fpreset (void);

    Reset the floating point coprocessor.

  See also: _clear87(), _control87()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fprintf (FILE *stream, const char *format, ...);

    Formatted output to the stream STREAM.  See printf() for details.

  Return value:

    On success, fprintf() returns the number of characters written to
    STREAM.  On error, fprintf() returns EOF.

  See also: fscanf(), printf()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fputc (int c, FILE *stream);

    Write the character C (converted to an unsigned char) to the
    output stream STREAM and advance the file position indicator of
    the stream (if defined).  All output to streams takes place as if
    characters were written by successive calls to fputc().

    fputc() is a function, in contrast to putc().

  Return value:

    fputc() returns the character written.  On error, fputc() sets the
    error indicator of the stream and returns EOF.

  See also: ferror(), fprintf(), fputchar(), fputs(), putc(),
            putchar()

------------------------------------------------------------------------------
#include <stdio.h>                                                        [PC]

int fputchar (int c);

    fputchar (c) is equivalent to fputc (c, stdout).

  Return value:

    fputchar() returns the character written.  On error, fputchar()
    sets the error indicator of stdout and returns EOF.

  Hints:

    Use putchar() or fputc (c, stdout) instead of fputchar() as
    fputchar() is not portable.

  See also: fputc(), putchar()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fputs (const char *string, FILE *stream);

    Write the string pointed to by STRING to STREAM.  In contrast to
    puts(), a newline character is not appended automatically.

  Return value:

    fputs() returns a non-negative value if successful.  On error,
    fputs() returns EOF.

  See also: fgets(), fputc(), printf(), puts(), setvbuf()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

size_t fread (void *buffer, size_t size, size_t count, FILE *stream);

    Read up to COUNT elements whose size is SIZE from STREAM to the
    array pointed to by BUFFER.  The file pointer is incremented by
    the number of bytes read.  If STREAM has been opened in text mode,
    CR/LF pairs are translated to newline characters and a Ctrl-Z
    character is discarded if it is the last character of the file.
    If fread() fails, the position of the file pointer will be
    undefined.

  Return value:

    fread() returns the number of elements successfully read, which
    may be less than COUNT if an error occurs or if the end of the
    file is reached.  Use ferror() and feof() to distinguish between
    these two conditions.

    Text mode translation does not affect the return value -- SIZE and
    COUNT are applied after translation.

  See also: fgetc(), fgets(), _fsetmode(), fwrite()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

void free (void *mem);

    Deallocate the block of memory pointed to by MEM.  MEM must point
    to a block which is still in use (that is, has not been freed) and
    must have been returned by calloc(), malloc(), realloc(),
    _tcalloc(), _tmalloc(), _trealloc(), _ucalloc(), _umalloc(),
    _utcalloc(), or _utmalloc().  Do not use the memory pointed to by
    MEM after calling free().  If MEM is NULL, free() does nothing.

  See also: calloc(), _heapmin(), malloc(), realloc(), _tfree(),
            _umalloc()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

FILE *freopen (const char *fname, const char *mode, FILE *stream);

    Open the file whose name is in the string pointed to by FNAME in
    the mode given by the string pointed to by MODE (see fopen()) and
    associate STREAM with that file.  If STREAM is associated with a
    file when freopen() is called, freopen() will close the file,
    ignoring any errors, before opening the file whose name is in the
    string pointed to by FNAME.

  Return value:

    If successful, freopen() returns STREAM.  On error, freopen()
    returns NULL.

  Hints:

    The major application of freopen() is to redirect stdin, stdout,
    or stderr.

  See also: _fassign(), fclose(), fopen(), stderr

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double frexp (double x, int *exp_ptr);
long double frexpl (long double x, int *exp_ptr);

    Extract mantissa and exponent of X.  The mantissa is returned, the
    exponent, an integer, is stored to *EXP_PTR.  The following holds
    for the mantissa m: 0.5 <= |m| < 1.0.  If X is zero, both the
    mantissa and the exponent are 0.

    frexpl() uses the long double format.

  Return value:

    frexp() returns the mantissa of X.

  See also: ldexp(), log()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fscanf (FILE *stream, const char *format, ...);

    The stream STREAM is read and input is parsed according to the
    format string FORMAT.  For each field in the string pointed to by
    FORMAT there must be a pointer to the location receiving the
    value.  The pointers are passed after the FORMAT argument.

  Return value:

    If successful, fscanf() returns the number of fields converted.
    On error, fscanf() returns EOF.

  See also: fprintf(), scanf()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fseek (FILE *stream, long offset, int origin);

    fseek() moves the file pointer of STREAM.  The new position OFFSET
    is relative to ORIGIN: If ORIGIN is SEEK_SET, OFFSET is relative
    to the beginning of the file, if ORIGIN is SEEK_CUR, OFFSET is
    relative to the current position, if ORIGIN is SEEK_END, OFFSET is
    relative to the end of the file.  The file pointer cannot be moved
    before the beginning of the file.

    For text-mode streams, OFFSET must be either zero (with ORIGIN
    equal to SEEK_SET, SEEK_CUR, or SEEK_END) or a value returned by a
    call to ftell() on the same stream (with ORIGIN equal to
    SEEK_SET).

    If successful, fseek() resets the end-of-file indicator of the
    stream and undoes ungetc().  If STREAM is open for reading and
    writing (update), the next operation after fseek() can be either
    input or output.

  Return value:

    0       success

    non-0   error

  Implementation-defined behavior:

    For binary-mode streams, the file position can be set beyond end
    of file; the data between end of file and the new position is
    undefined.

    For text-mode streams ending with a Ctrl-Z, SEEK_END is not
    allowed.

  Restrictions:

    fseek() does not work for text-mode streams unless either CR/LF
    pairs or LF only is used for all lines of the file.  If there are
    lines terminated with CR/LF and lines terminated with LF, fseek()
    does not work correctly.

  See also: chsize(), fgetpos(), fsetpos(), ftell(), lseek(), rewind()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]

int _fseek_hdr (FILE *stream);

    Move the file pointer of STREAM to the a.out header of an
    executable file (a.out or bound .exe).  _fseek_hdr() assumes that
    the file pointer points to the beginning of the header (ie, the
    beginning of the file).  If no header is found, the file pointer
    will be repositioned to the original position.

  Return value:

    0       success

    -1      error (errno is set)

  See also: _seek_hdr()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]

int _fsetmode (FILE *stream, const char *mode);

    Change the text/binary mode of a stream.  MODE must point either
    to "b" or to "t".  _fsetmode() is usually used to switch stdin or
    stdout to binary mode.

  Return value:

    0       success

    -1      error

  Restrictions:

    Do not call _fsetmode() on a stream with non-empty buffer.  If
    there is data in the buffer (either data to be read or data to be
    written), call fflush() before _fsetmode().  Otherwise, future
    behavior of the stream will be undefined.

  See also: fopen()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int fsetpos (FILE *stream, const fpos_t *pos);

    Restore the position of the file pointer of the file STREAM to the
    position saved by fgetpos() in the variable pointed to by POS.

  Return value:

    0       success

    non-0   error

  Restrictions:

    fsetpos() does not work for text-mode streams unless either CR/LF
    pairs or LF only is used for all lines of the file.  If there are
    lines terminated with CR/LF and lines terminated with LF,
    fsetpos() does not work correctly.

  See also: fgetpos(), fseek()

------------------------------------------------------------------------------
#include <stdio.h>                                                        [PC]
#include <share.h>

FILE *_fsopen (const char *fname, const char *mode, int shflag);

    Open a stream.  FNAME points to a string giving the name of the
    file, MODE points to a string which specifies the file mode, see
    fopen() for details.

    The sharing mode of the file is given by SHFLAG.  The following
    sharing modes are available:

    SH_DENYRW
            Deny read and write access

    SH_DENYRD
            Deny read access (permit write access)

    SH_DENYWR
            Deny write access (permit read access)

    SH_DENYNO
            Deny nothing (permit read and write access)

  Return value:

    _fsopen() returns a new stream.  On error, _fsopen() returns NULL.

  See also: fopen(), sopen()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]
#include <sys/types.h>
#include <sys/stat.h>

int fstat (int handle, struct stat *buffer);

    Retrieve information about the open file HANDLE.  fstat() will put
    the data into the structure pointed to by BUFFER.

    See stat() for a description of struct stat.

  Return value:

    0       success

    -1      error (errno is set)

  Restrictions:

    st_dev and st_rdev are set to zero.  Each call to fstat() returns
    a different value for st_ino.

  See also: ioctl(), stat(), ttyname()

------------------------------------------------------------------------------
#include <io.h>                                                          [BSD]

int fsync (int handle);

    Flush the buffers associated with HANDLE and update the directory.

  Return value:

    0       success

    -1      error

  Restrictions:

    fsync() is currently not implemented for DOS: errno is set to
    ENOSYS.

    Due to a bug in HPFS.IFS, calling fsync() can be quite dangerous.
    If HPFS.IFS has the bug, and fsync() (i.e., DosResetBuffer) is
    called after writing to a file, and Ctrl+Alt+Del is pressed while
    the file is still open, HPFS.IFS will corrupt the allocation
    bitmap of the partition containing that file.  This may damange
    existing and future files and directories.  The bug is present in
    all HPFS.IFS versions of (at least) OS/2 2.0 through OS/2 Warp
    3.0, red box of 1994.  That HPFS.IFS bug seems to be fixed in
    FixPak XR_W005 and later.  Performing a system shutdown instead of
    pressing Ctrl+Alt+Del causes the same problem if the process that
    wrote to the file and called fsync() or DosResetBuffer cannot be
    killed.  As you cannot assume that the user of your application
    has a working HPFS.IFS, better don't call fsync() and
    DosResetBuffer.

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

long ftell (FILE *stream);

    ftell() retrieves the current position of the file pointer of
    STREAM.

  Return value:

    ftell() returns the current position of the file pointer of
    STREAM, in characters.  On error, ftell() returns -1.

  Restrictions:

    ftell() does not work for text-mode streams unless either CR/LF
    pairs or LF only is used for all lines of the file.  If there are
    lines terminated with CR/LF and lines terminated with LF, ftell()
    does not work correctly.

  See also: fgetpos(), fseek()

------------------------------------------------------------------------------
#include <sys/timeb.h>                                                  [SysV]

void ftime (struct timeb *ptr);

    Get the current time and store it to the structure pointed to by
    PTR.  That structure has the following fields:

    dstflag

        Non-zero if daylight saving time is active for the local
        timezone.

    millitm

        Milliseconds of current time.

    time

        Current time in seconds since 00:00:00 1-Jan-1970 Coordinated
        Universal Time (UTC, GMT).

    timezone

        Difference between UTC and local time in minutes.  Positive
        values are to the west of the Prime Meridian.

    See tzset() for a description of the TZ environment variable.

  See also: gettimeofday(), settimeofday(), time(), tzset()

------------------------------------------------------------------------------
#include <io.h>                                                          [BSD]

int ftruncate (int handle, long length);

    Truncate the file associated with HANDLE to at most LENGTH bytes.
    The position of the file pointer is undefined after calling this
    function.  If LENGTH is greater than the current length of the
    file, the length is not changed.  HANDLE must be open for writing.

  Return value:

    0       success

    -1      error

  See also: chsize(), truncate()

------------------------------------------------------------------------------
#include <sys/types.h>                                                  [UNIX]
#include <sys/stat.h>
#include <ftw.h>

int ftw (const char *path,
         int (*fn)(const char *name, const struct stat *stat_ptr, int flag),
         int depth);

    Call FN for all entries of the directory tree whose root directory
    is in the string pointed to by PATH.  Directories are visited
    before the entries they contain.  FN is not called for the
    directories `.' and `..'.  A pointer to a string holding the name
    of the entry is passed in NAME.  Forward slashes are used to
    separate directories (backslashes in PATH are not converted to
    forward slashes).  _fnlwr() is called to convert the file names to
    lower case on upper-case-only file systems.  A structure filled in
    by stat() is pointed to by STAT_PTR.  FLAG is one of the
    following:

    FTW_D   NAME is a directory

    FTW_F   NAME is a file

    FTW_NS  stat() failed, the contents of structure pointed to by
            STAT_PTR are undefined

    FTW_DNR
            the directory whose name is in the string pointed to by
            NAME is unreadable (does not happen under DOS and OS/2)

    If FN returns 0, ftw() continues.  Otherwise, ftw() terminates and
    returns the value returned by FN.

    The DEPTH argument is ignored by this implementation of ftw().  In
    other implementations, DEPTH is used to restrict the number of
    file handles used by ftw(): one file handle is required for each
    level.  If DEPTH is less than the number of levels, ftw() will be
    slow.

    ftw() properly handles DBCS characters.

  Return value:

    If FN returns a non-zero value, ftw() returns that value.
    Otherwise, ftw() returns 0.  On error, ftw() returns -1.

  See also: _fnlwr(), _nls_init(), opendir()

  Example: See /emx/test/ftwtest.c

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

int _fullpath (char *dst, const char *src, int size);

    Construct an absolute path name for the file name or directory
    name pointed to by SRC.  The absolute path name is written to the
    array pointed to by DST.  It is assumed that there are SIZE bytes
    available at DST, this includes the terminating null character.
    DST can be identical to SRC.  Backslashes are translated into
    forward slashes.  The absolute path name is not translated to
    lower case.

    _fullpath() accesses the appropriate drive.  It fails if a
    directory does not exist unless the non-existing directory is the
    last member of the resulting path name.

    _fullpath() properly handles DBCS characters.

  Return value:

    If successful, _fullpath() returns 0.  If there is an error,
    _fullpath() returns -1.  If SIZE is too small, _fullpath() sets
    errno to ERANGE and returns -1.

  See also: _abspath(), _nls_init()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

size_t fwrite (const void *buffer, size_t size, size_t count, FILE *stream);

    Write COUNT elements whose size is SIZE from the array pointed to
    by BUFFER to STREAM.  The file pointer is incremented by the
    number of bytes written.  If fwrite() fails, the value of the file
    pointer is undefined.  If STREAM has been opened in text mode,
    newline characters are translated to CR/LF pairs.

  Return value:

    fwrite() returns the number of elements successfully written,
    which will be less than COUNT if an error occurs.  Text mode
    translation does not affect the return value -- SIZE and COUNT are
    applied before the translation.

  See also: fputc(), fputs(), fread(), _fsetmode(), printf(),
            setvbuf()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_box (int x0, int y0, int x1, int y1, int color, int fill_flag);

    Draw a box which has the four vertices (X0,Y0), (X0,Y1), (X1, Y0)
    and (X1, Y1).  If FILL_FLAG is G_OUTLINE, the outline is drawn,
    that is, four lines between the vertices.  If FILL_FLAG is G_FILL,
    the interior of the box is filled.  The color COLOR is used for
    drawing.

  See also: g_clip()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_clear (int color);

    Clear the screen (graphics mode, only).  All pixels are set to the
    color COLOR.  The clipping rectangle is ignored.

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_clip (int x0, int y0, int x1, int y1);

    Define the clipping rectangle.  Only pixels with X coordinate
    between X0 and X1 (inclusive) and with Y coordinate between Y0 and
    Y1 (inclusive) are drawn.  No drawing is performed outside that
    clipping rectangle.  After switching to graphics mode with
    g_mode(), the clipping rectangle is set to the entire screen.
    This is equivalent to calling

        g_clip (0, 0, g_xsize-1, g_ysize-1);

  See also: g_mode(), g_xsize, g_ysize

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_ellipse (int cx, int cy, int rx, int ry, int color, int fill_flag);

    Draw an ellipse or a circle.  One axis is horizontal, the other
    one vertical.  The center of the ellipse is at (CX,CY).  The
    horizontal radius is RX, the vertical radius is RY.  It's
    impossible to draw an ellipse with even length of an axis.  If
    FILL_FLAG is G_OUTLINE, the outline of the ellipse is drawn.  If
    FILL_FLAG is G_FILL, the interior of the ellipse is filled.  The
    color COLOR is used for drawing.

  See also: g_clip()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_get (int x, int y);

    Return the color of the pixel at (X,Y).  If (X,Y) is outside the
    clipping rectangle, -1 is returned.

  See also: g_clip(), g_set()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_hline (int y, int x0, int x1, int color);

    Draw a horizontal line between (X0,Y) and (X1,Y).  The color COLOR
    is used for drawing.

  See also: g_box(), g_clip(), g_line(), g_vline()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_line (int x0, int y0, int x1, int y1, int color);

    Draw a line of arbitrary slope between (X0,Y0) and (X1,Y1).  The
    color COLOR is used for drawing.  To draw horizontal or vertical
    lines, you should use g_hline() and g_vline(), respectively, which
    are specialized functions optimized for speed.

  See also: g_clip(), g_hline(), g_polygon(), g_triangle(), g_vline()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_lock (void);

    Lock the screen.  Under OS/2, the screen must be locked while
    access graphics memory.  All the graphics drawing functions lock
    the screen, draw, and unlock the screen unless it's already
    locked.  To avoid the overhead of locking and unlocking for each
    function call, you can lock and unlock the screen yourself when
    performing many successive drawing operations.  Note that you
    should not lock the screen for more than a few seconds.  g_lock()
    increments a counter, which is initialized to zero by g_mode().
    The screen is locked while the counter is non-zero.  g_unlock()
    decrements the counter and unlocks the screen if the counter
    reaches zero.

  See also: g_unlock()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_mode (int mode);

    Select graphics mode.  If MODE is G_MODE_OFF, graphics mode is
    turned off and 0 is returned.  Other values of MODE select the
    following graphics modes:

    G_MODE_EGA_C
            640x200 EGA mode with 16 colors

    G_MODE_EGA_E
            640x350 EGA mode with 16 colors

    G_MODE_VGA_H
            640x480 VGA mode with 16 colors

    G_MODE_VGA_L
            320x200 VGA mode with 256 colors

    The global variables g_xsize, g_ysize and g_colors are set.  The
    clipping rectangle is set to the entire screen.

    General information about the graphics library: Programs using the
    graphics library work both under DOS and in OS/2 full-screen
    sessions.  The coordinates of the screen are (0,0) (upper left)
    through (g_xsize-1,g_ysize-1) (lower right).  You have to link
    with -lgraph.  Under DOS, emx option -acm is required, see `Using
    emx options'.

  Return value:

    If switching to graphics mode succeeds, gmode() returns 1.
    Otherwise, gmode() returns 0.

  See also: g_clip(), g_modeset(), g_colors, g_xsize, g_ysize

  Example: See /emx/samples/graph.c

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_modeset (int mode, int flag);

    Modify a graphics mode number.  The mode number to be modified is
    passed in MODE, the value passed in FLAG specifies how to modify
    the mode number: G_SET_KEEP causes the mode number to be not
    modified.

    The global variables g_xsize, g_ysize and g_colors are set.

  Return value:

    g_modeset() returns the new mode number.  On failure, g_modeset()
    returns G_MODE_OFF.

  Restrictions:

    As only G_SET_KEEP is implemented, g_modeset() is useless.  It's
    included for compatibility with existing programs.

  See also: g_mode(), g_colors, g_xsize, g_ysize

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_polygon (const int *x, const int *y, int n, int color,
                int fill_flag);

    Draw a polygon.  The N vertices are stored in the X and Y arrays:
    (X[i],Y[i]) for i = 0, ..., N-1.  If FILL_FLAG is G_OUTLINE, the
    outline of the polygon is drawn, that is, a line from vertex 0 to
    vertex 1, from vertex 1 to vertex 2, ..., vertex N-2 to vertex
    N-1, vertex N-1 to vertex 0.  If FILL_FLAG is G_FILL, the interior
    of the polygon is filled.  A point is defined to be in the
    interior of the polygon, if an infinite line to any side of that
    pixel intersects the polygon an odd number of times.  The color
    COLOR is used for drawing.

  See also: g_clip(), g_line(), g_triangle()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_set (int x, int y, int color);

    Set the pixel (X,Y) to the color COLOR.

  See also: g_clip(), g_get()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_triangle (int x0, int y0, int x1, int y1, int x2, int y2, int color,
                 int fill_flag);

    Draw a triangle.  The vertices are (X0,Y0), (X1,Y1) and (X2,Y2).
    If FILL_FLAG is G_OUTLINE, the outline of the triangle is drawn,
    that is, a line from (X0,Y0) to (X1,Y1), a line from (X1,Y1) to
    (X2,Y2) and a line from (X2,Y2) to (X0,Y0).  If FILL_FLAG is
    G_FILL, the interior of the triangle is filled.  The color COLOR
    is used for drawing.

  See also: g_clip(), g_line(), g_polygon()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_unlock (void);
void g_unlockall (void);

    Unlock the screen.  g_unlock() undoes one invocation of g_lock()
    by decrementing the counter incremented by g_lock().  If the
    counter reaches zero, the screen is unlocked.  If the counter
    already was zero, the counter is not changed.  g_unlockall()
    undoes all invocations of g_lock() by resetting the counter to
    zero and unlocking the screen if the counter was non-zero.

  See also: g_lock()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_vgapal (const char *pal, int first, int n, int wait_flag);

    Set the VGA palette.  This function sets N (1 through 256) DAC
    registers starting with register FIRST (0 through 255).  For each
    register, 3 bytes are taken from the array pointed to by PAL: red,
    green, blue.  Each byte should have a value between 0 and 63,
    inclusive.  If WAIT_FLAG is non-zero, g_vgapal() waits for the
    vertical retrace to avoid snow on the screen, see g_waitv().
    Under DOS, emx option -ai is required, see `Using emx options'.
    Under OS/2, emxio.dll is required.

  See also: g_waitv(), _outps8dac()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_vline (int x, int y0, int y1, int color);

    Draw a vertical line between (X,Y0) and (X,Y1).  The color COLOR
    is used for drawing.

  See also: g_box(), g_clip(), g_hline(), g_line()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_waitv (void);

    Wait for vertical retrace.  Under DOS, emx option -ai is required,
    see `Using emx options'.  Under OS/2, emxio.dll is required.  Note
    that this function eats a lot of CPU time.

  See also: g_vgapal(), _wait01()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_wmode (int wmode);

    Select a `writing mode'.  This is not yet implemented.

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [UNIX]

char *gcvt (double value, int digits, char *buffer);

    Convert the floating point number VALUE to a null-terminated
    string of ASCII digits in the array pointed to by BUFFER, using
    exponential-decimal format or floating-decimal and return a
    pointer to BUFFER.  gcvt() produces DIGITS significant digits.
    Trailing zeros and a trailing decimal point are removed.  The
    array pointed to by BUFFER must be big enough for holding the
    string.

    The decimal point character of the current locale is used.

    Exponential format is used if the absolute value of VALUE is less
    than 0.1 or if the exponent is greater than or equal to DIGITS.

    The empty string is stored to the array pointed to by BUFFER if
    DIGITS is less than one.

  Return value:

    gcvt() returns BUFFER.

  Restrictions:

    NaN and other special values are not yet handled correctly.

  See also: setlocale(), sprintf()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int getc (FILE *stream);

    Read the next character (as unsigned char converted to an int)
    from the input stream STREAM and advance the file position
    indicator of the stream (if defined).  getc() is equivalent to
    fgetc().

    getc() may be implemented as macro, in contrast to fgetc().  In
    consequence, getc() may evaluate its argument more than once.

  Return value:

    getc() returns the next character from the stream.  If the stream
    is at end-of-file (before getc() is called), getc() sets the
    end-of-file indicator of the stream and returns EOF.  If a read
    error occurs, getc() sets the error indicator of the stream and
    returns EOF.

  Implementation-defined behavior:

    getc() is implemented as in-line function for single-thread
    programs.

  Hints:

    Use getc() instead of fgetc() if you want to read a lot of
    characters.

    The argument of getc() should not be an expression with side
    effects.

  See also: fgetc(), getchar()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int getchar (void);

    getchar() is equivalent to getc (stdin).

  Return value:

    getchar() returns the next character from stdin.  If stdin is at
    end-of-file (before getchar() is called), getchar() sets the
    end-of-file indicator of stdin and returns EOF.  If a read error
    occurs, getchar() sets the error indicator of stdin and returns
    EOF.

  Implementation-defined behavior:

    getchar() is implemented as in-line function for single-thread
    programs.

  Hints:

    Use getchar() instead of fgetc(stdin) if you want to read a lot of
    characters.

  See also: fgetc(), getc()

------------------------------------------------------------------------------
#include <stdlib.h>                                                  [POSIX.1]

char *getcwd (char *buffer, size_t size);

    getcwd() retrieves the name of the current working directory
    (excluding the drive name) and stores it to the array pointed to
    by BUFFER.  It is assumed that there are SIZE bytes available at
    BUFFER.  This includes the terminating 0.  If BUFFER is NULL, an
    array of suitable size, but at least SIZE bytes, is allocated with
    malloc().  getcwd() translates backslashes into forward slashes.
    It does not translate upper-case directory names to lower case.

    _getcwd() properly handles DBCS characters.

  Return value:

    If successful, getcwd() returns BUFFER, or a buffer allocated with
    malloc() if BUFFER is NULL.  On error, getcwd() sets errno and
    returns NULL.

  Errors:

    EINVAL  SIZE is zero

    ENOMEM  BUFFER is NULL and malloc() failed

    ERANGE  BUFFER is not NULL and SIZE is positive and the length of
            the pathname plus 1 is greater than SIZE

  See also: chdir(), _getcwd1(), _getcwd2(), getwd(), _nls_init()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _getcwd1 (char *buffer, char drive);

    _getcwd1() retrieves the name of the current working directory
    (starting with a slash, excluding the drive name) of drive DRIVE
    and stores it to the array pointed to by BUFFER.  If DRIVE is 0,
    the currently selected drive is used.  Otherwise, DRIVE must be in
    'A' through 'Z'.  It is assumed that there are enough bytes
    available at BUFFER.  _getcwd1() translates backslashes into
    forward slashes.  It does not translate upper-case directory names
    to lower case.

    _getcwd1() properly handles DBCS characters.

  Return value:

    0       success

    -1      error

  See also: chdir(), getcwd(), _getcwd2(), _nls_init()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char *_getcwd2 (char *buffer, int size);

    _getcwd2() retrieves the name of the current working directory
    (including the drive name) and stores it to the array pointed to
    by BUFFER.  It is assumed that there are SIZE bytes available at
    BUFFER.  This includes the terminating 0.  If BUFFER is NULL, an
    array of suitable size, but at least SIZE bytes, is allocated with
    malloc().  _getcwd2() translates backslashes into forward slashes.
    It does not translate upper-case directory names to lower case.

    _getcwd2() properly handles DBCS characters.

  Return value:

    If successful, _getcwd2() returns BUFFER, or a buffer allocated
    with malloc() if BUFFER is NULL.  On error, _getcwd2() sets errno
    and returns NULL.

  Errors:

    EINVAL  SIZE is zero

    ENOMEM  BUFFER is NULL and malloc() failed

    ERANGE  BUFFER is not NULL and SIZE is positive and the length of
            the pathname plus 3 is greater than SIZE

  See also: chdir(), getcwd(), _getcwd1(), _nls_init()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

char _getdrive (void);

    Get the currently selected drive.

  Return value:

    _getdrive() returns as upper-case letter the currently selected
    drive.

  See also: _chdir2(), _chdrive(), _getcwd2()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

char *getenv (const char *name);

    Find NAME in the environment.

  Return value:

    If the variable is found, getenv() returns a pointer to the value.
    Otherwise, getenv() returns NULL.

  See also: environ, putenv()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char *_getext (const char *path);
char *_getext2 (const char *path);

    _getext() and _getext2() return a pointer to the extension of the
    file name pointed to by PATH.  The pointer points to the dot
    character that starts the extension.  If there is no extension,
    _getext() returns NULL and _getext2() returns the empty string "".
    If the last member of the string pointed to by PATH starts with a
    dot ("/usr/mattes/.profile", for instance), _getext() returns NULL
    and _getext2() returns the empty string "".

    _getext() and _getext2() properly handle DBCS characters.

  Return value:

    See above.

  See also: _defext(), _getname(), _nls_init(), _remext(),
            _splitpath()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char *_getname (const char *path);

    Return a pointer to the name part (last component, including the
    extension) of the file name pointed to by PATH.  The pointer
    returned by _getname() points to the character after the last path
    separator (slash, backslash and colon).  If there is no path
    separator, PATH is returned.

    _getname() properly handles DBCS characters.

  Return value:

    See above.

  See also: _getext(), _nls_init(), _remext(), _splitpath()

  Example:

    int main (int argc, char *argv[])
    {
      argv[0] = _getname (argv[0]);   /* Remove pathname */
      ...
    }

------------------------------------------------------------------------------
#include <unistd.h>     /* without extensions */                     [POSIX.2]
#include <getopt.h>     /* with extensions */

int getopt (int argc, char **argv, const char *opt_str);

    Parse command line options.  ARGC is the number of argument
    strings, ARGV points to an array of pointers to argument strings,
    OPT_STR points to a string describing the available options.
    Typically, the ARGC and ARGV arguments of main() are passed to
    getopt().  Each option is of one of the following types:

    - option without argument: the option letter is listed in the
      string pointed to by OPT_STR;

    - option with mandatory argument: the option letter in the string
      pointed to by OPT_STR is followed by a colon

    - option with optional argument: the option letter in the string
      pointed to by OPT_STR is followed by two colons.

    For instance,

        c = getopt (argc, argv, "abc:d::v");

    defines five options: -a, -b, -c and -v don't take arguments, -c
    takes a mandatory argument, -d takes an optional argument.

    Before the first call to getopt(), the global variable optind must
    be set to 0 (that's the initial value, see also bugs below).
    Calling getopt() parses the next command line option.  If there
    are no more command line options, getopt() returns -1.  After
    calling getopt(), optind is the index of the next command line
    argument.  After calling getopt(), the global variable optarg
    points to the argument of the option.  If there is no argument,
    optarg is NULL.

    There are three modes of operation, which are controlled by the
    global variable optmode declared in <getopt.h>:

    GETOPT_UNIX
            Options are at the start of the command line.  When the
            first non-option is reached, parsing options stops and
            getopt() returns -1.  GETOPT_UNIX is the default.

    GETOPT_ANY
            Options may appear anywhere on the command line.  ARGV is
            reordered to move the non-options to the end.  When there
            are no more options, getopt() returns -1.  The remaining
            arguments are all the arguments of the command line which
            are not options.

    GETOPT_KEEP
            Options may appear anywhere on the command line.  If the
            current argument is not an option, getopt() returns 0.
            optarg will point to the argument.  The next call to
            getopt() examines the next command line argument.

    The behavior on error (invalid option or missing argument) depends
    on the global variable opterr (which is non-zero unless set by the
    application) and the first character of the string pointed to by
    OPT_STR: If the global variable opterr is non-zero and the first
    character of the string pointed to by OPT_STR is not a colon,
    getopt() writes an appropriate error message to stderr and returns
    '?' or ':'.  If opterr is zero and the first character of the
    string pointed to by OPT_STR is not a colon, getopt() does not
    display an error message and returns '?'.  If the first character
    of the string pointed to by OPT_STR is a colon, getopt() does not
    display an error message and returns '?' or ':'.  In all cases,
    the global variable optopt is set to the character code of the
    option which caused the error.  The error message includes the
    program name which is taken from ARGV[0].

    The global variable optswchar declared in <getopt.h> is a string
    of characters which start options.  The default value is "-", that
    is, options are started by hyphens.  You might want to assign "-/"
    or "/" to optswchar.

    If a command line argument consists of two equal switch characters
    (see optswchar), the remaining command line arguments are not
    treated as options.

    Options may be clustered, that is, if an option does not take an
    argument, getopt() treats the following character of the same
    command line argument as option.  If an option takes a mandatory
    argument, the argument either follows immediately the option or is
    taken from the next command line argument.  If an option takes an
    optional argument, the argument must immediately follow the
    option.

    When writing portable programs, you should not use optmode,
    optswchar and options taking optional arguments.  Only letters
    should be used as options.

    optmode must not be changed after the first call to getopt().
    optswchar, however, may be changed at any time.

  Return value:

    getopt() returns the next option character.  If there are no more
    command line options, -1 is returned (note that the value of the
    EOF macro defined in <stdio.h> is -1).  If an invalid option is
    encountered, '?'  is returned.  If an argument is missing for an
    option which requires an argument, ':' (if the first character of
    the string pointed to by OPT_STR is a colon) or '?' (if the first
    character of the string pointed to by OPT_STR is not a colon) is
    returned.  If optmode is GETOPT_KEEP and the current command line
    argument is not an option, 0 is returned.

  Implementation-defined behavior:

    The variables optswchar and optmode are extensions.  Both are
    declared in <getopt.h> but not in <unistd.h>.  Optional arguments
    (two colons) are an extension.

    To reinitialize getopt(), that is, to restart parsing options, set
    optind to zero.

  Bugs:

    For POSIX.2, the ARGV argument should be a const pointer; however,
    GETOPT_ANY reorders the array pointed to by ARGV.

  See also: main(), _swchar()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [BSD]

int getpagesize (void);

    Return the page size, which is 4096 for the 386.

  Return value:

    getpagesize() returns the page size.

------------------------------------------------------------------------------
#include <pwd.h>                                                        [UNIX]
#include <unistd.h>

char *getpass (const char *prompt);

    Print the string pointed to by PROMPT on stderr and read a
    password from the keyboard device without echoing.  Up to
    _PASSWORD_LEN (which is 128, defined in <pwd.h>) characters can be
    entered.

  Return value:

    getpass() returns a pointer to a statically allocated buffer.  The
    string will be null-terminated.

  See also: _getpass1(), _getpass2()

------------------------------------------------------------------------------
#include <pwd.h>                                                         [emx]
#include <unistd.h>

char *_getpass1 (const char *prompt);
char *_getpass2 (const char *prompt, int kbd);

    Print the string pointed to by PROMPT on stderr and read a
    password from the keyboard device or from standard input without
    echoing.  Up to _PASSWORD_LEN (which is 128, defined in <pwd.h>)
    characters can be entered.

    _getpass1() reads from the keyboard device if standard input is
    associated with the console.  Otherwise, _getpass1() reads from
    standard input.

    _getpass2() reads from the keyboard device if KBD is non-zero.
    _getpass2() reads from standard input if KBD is zero.

  Return value:

    _getpass1() and _getpass2() return a pointer to a statically
    allocated buffer.  The buffer is shared by getpass(), _getpass1(),
    and _getpass2().  The string will be null-terminated.

  Hints:

    Use _getpass2() passing zero for KBD if the application should
    work correctly with pseudo ttys (ptys).

  See also: getpass()

------------------------------------------------------------------------------
#include <process.h>                                                    [UNIX]

int getpid (void);

    Get the process identification number of the calling process.

  Return value:

    getpid() returns the process identification number of the calling
    process.

  See also: getppid(), _gettid()

------------------------------------------------------------------------------
#include <process.h>                                                    [UNIX]

int getppid (void);

    Get the process identification number of the parent process of the
    calling process.

  Return value:

    getppid() returnes the process identification number of the parent
    process of the calling process.

  See also: getpid()

------------------------------------------------------------------------------
#include <pwd.h>                                                        [UNIX]

struct passwd *getpwent (void);
struct passwd *getpwuid (int uid);
struct passwd *getpwnam (char *name);
void setpwent (void);
void endpwent (void);

    Dummy functions.

  See also: cuserid()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

char *gets (char *buffer);

    Read a string from stdin to the array pointed to by BUFFER.  Stop
    after a newline (LF) character has been read.  The newline
    character is replaced with a null character.  Use fgets() instead
    as gets() doesn't know how big the array pointed to by BUFFER is.

  Return value:

    gets() returns BUFFER.  If an error occurs or the end of the file
    is reached, gets() returns NULL.

  See also: fgets(), scanf()

------------------------------------------------------------------------------
#include <stdlib.h>                                                    [emx *]

int _getsockhandle (int handle);

    Return the internal socket handle associated with socket handle
    HANDLE.  As emx.dll maps socket handles internally, you cannot
    pass handles directly to IBM TCP/IP for OS/2 functions.  Use
    _getsockhandle() to retrieve the internal socket handle (for IBM
    TCP/IP for OS/2) of a socket handle.  Internal socket handles can
    be used with IBM TCP/IP for OS/2 functions, only.  Note that you
    cannot use socket handles and internal socket handles with OS/2
    API functions such as DosRead.

    You have to link with the socket library (use the -lsocket
    option).

  Return value:

    _getsockhandle() returns an internal socket handle.  On error,
    _getsockhandle() sets errno and returns -1.

  Restrictions:

    _getsockhandle() is implemented for OS/2 only.

    _getsockhandle() is not available with the system call library
    sys.lib (-Zsys).

  Hints:

    _getsockhandle() can be used with _impsockhandle() to pass socket
    handles down to child processes.  See _impsockhandle() for
    details.

  See also: _impsockhandle()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _gettid (void);

    Get the thread identification number of the calling thread.

  Return value:

    _gettid() returns the thread identification number of the calling
    thread.  Under DOS, _gettid() always returns 1.

  See also: _beginthread(), getpid(), _threadid, _threadstore()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char *_getvol (char drive);

    Retrieve the volume label of the drive DRIVE.  DRIVE must be zero
    (for retrieving the volume label of the currently selected drive)
    or in 'A' through 'Z' or in 'a' through 'z'.

  Return value:

    If successful, _getvol() returns a pointer to a statically
    allocated string of up to 11 characters containing the volume
    label.  That string will be overwritten by the next call to
    _getvol().  On error, _getvol() returns NULL.

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

int getw (FILE *stream);

    Read a word (int) from STREAM.  Avoid using this function.

  Return value:

    getw() returns the word read.  On error, getw() returns -1.  As -1
    is also a possible word value, you have to use ferror() to
    recognize an error condition.

  See also: putw(), fwrite()

------------------------------------------------------------------------------
#include <stdlib.h>

char *getwd (char *buffer);

    getwd() retrieves the name of the current working directory
    (excluding the drive name) and stores it to the array pointed to
    by BUFFER.  It is assumed that there are MAXPATHLEN bytes
    available at BUFFER.  This includes the terminating 0.  MAXPATHLEN
    is defined in <sys/param.h>.  getwd() translates backslashes into
    forward slashes.  It does not translate upper-case directory names
    to lower case.

    _getwd() properly handles DBCS characters.

  Return value:

    If successful, getwd() returns BUFFER.  On error, getwd() copies
    an error message to BUFFER and returns NULL.

  See also: getcwd(), _nls_init()

------------------------------------------------------------------------------
#include <sys/time.h>                                                    [BSD]

int gettimeofday (struct timeval *tp, struct timezone *tzp);

    Obtain the current time and timezone.  If TP is not NULL, the
    current Coordinated Universal Time (UTC, GMT), expressed in
    seconds and microseconds since 00:00 1-Jan-1970, is stored to *TP.
    If TZP is not NULL, information about the timezone is stored to
    *TZP.

    The timeval structure is defined as follows:

        struct timeval
        {
          long tv_sec;
          long tv_usec;
        };

    tv_sec and tv_usec are the number of seconds and microseconds,
    respectively, elapsed since 00:00:00 1-Jan-1970 Coordinated
    Universal Time (UTC, GMT).

  Return value:

    0       success

    -1      error

  See also: ftime(), settimeofday(), time()

------------------------------------------------------------------------------
#include <glob.h>                                                    [POSIX.2]

int glob (const char *pattern, int flags,
          int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);
void globfree (glob_t *pglob);

    The glob() function generates pathnames matching PATTERN.  The
    value of FLAGS is the bitwise OR of zero or more of the following
    flags:

    GLOB_APPEND
            Append new pathnames to the ones generated by a previous
            call of glob().  When calling glob() with GLOB_APPEND,
            glob() must have been called without GLOB_APPEND for the
            structure pointed to by PGLOB and the members of that
            structure must have the same values as after the previous
            call to glob().  Moreover, the GLOB_DOOFFS bit of FLAGS
            must have the same value as for the previous call of
            glob().

    GLOB_DOOFFS
            Add null pointers at the beginning of PGLOB->gl_pathv.
            The number of null pointers is specified by
            PGLOB->gl_offs.  If GLOB_APPEND is set, the number of null
            pointers is not changed.

    GLOB_ERR
            Return when a non-readable directory is encountered.  If
            GLOB_ERR is not set, glob() ignores non-readable
            directories.

    GLOB_MARK
            Append a slash to pathnames that are directories.

    GLOB_NOESCAPE
            Do not treat backslash as an escape character.  If
            GLOB_NOESCAPE is not set, backslash can be used to remove
            the special meaning from special characters such as` *'
            and `['.

    GLOB_NOCHECK
            If PATTERN does not match any pathname, add PATTERN to
            PGLOB->gl_pathv.  If PATTERN does not match any pathname
            and GLOB_NOCHECK is not set, glob() returns an error.

    GLOB_NOSORT
            Do not sort the pathnames.  If GLOB_NOSORT is not set, the
            pathnames added by this call of glob() are sorted
            according to strcoll().

    GLOB_PERIOD
            Also include pathnames that have a component starting with
            a period.  If GLOB_PERIOD is not set, those pathnames are
            excluded.

    If a non-readable directory is encountered and ERRFUNC is not a
    null pointer, ERRFUNC will be called with EPATH pointing to the
    pathname of the non-readable directory and EERRNO set to the errno
    value.  If ERRFUNC returns a non-zero value, glob() will stop the
    scan and return GLOB_ABEND.  If ERRFUNC returns zero, the behavior
    depends on GLOB_ERR.

    PGLOB points to a structure of type glob_t which is defined as
    follows:

        typedef struct
        {
          size_t gl_pathc;
          char **gl_pathv;
          size_t gl_offs;
          /* Members used internally are not shown here */
        } glob_t;

    The gl_pathc member contains the number of pathnames matched by
    PATTERN.  If gl_pathc is zero, the value of gl_pathv is undefined.
    gl_pathv contains a pointer to an array of pointers to pathnames:
    If GLOB_DOOFFS is set, the array starts with gl_offs null
    pointers.  If GLOB_DOOFFS is not set, gl_offs is ignored (treated
    as zero).  Following these null pointers (if any), glob() stores
    gl_pathc pointers to pathnames.  A null pointer follows the last
    pathname.

    The characters `?', `*', and `[]' are interpreted as wildcard
    characters in the pattern.  `?' matches one character, `*' matches
    zero or more characters.  `[]' matches the set of characters
    listed between the brackets, ranges (such as `[0-9]') are allowed.
    If the first character after `[' is `!', all characters NOT in the
    set match the set.

    globfree() deallocates any memory allocated by glob() for the
    structure pointed to by PGLOB.  glob() must have been called for
    the structure pointed to by PGLOB and the members of that
    structure must have the same values as after the last call to
    glob().

  Return value:

    glob() returns one of the following values:

    0       Success

    GLOB_ABEND
            The operation of glob() was stopped for a non-readable
            directory because GLOB_ERR was set or ERRFUNC returned a
            non-zero value

    GLOB_NOMATCH
            No pathname matching PATTERN found

    GLOB_NOSPACE
            Out of memory

    Even if glob() returns a non-zero value, gl_pathc and gl_pathv of
    the structure pointed to by PGLOB are set.

  Implementation-defined behavior:

    If the first character after `[' is `^', all characters NOT in the
    set match the set.

  See also: _fnexplode(), fnmatch(), strcoll(), _wildcard()

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

struct tm *gmtime (const time_t *t);

    Convert the number of seconds elapsed since 00:00:00 1-Jan-1970
    Coordinated Universal Time (UTC, GMT) in the variable pointed to
    by T to a time and date structure (UTC) and return a pointer to
    the structure.  gmtime(), mktime() and localtime() use the same
    memory location, therefore the values are overwritten if one of
    these functions is called.

  Return value:

    gmtime() returns a pointer to a structure.

  See also: asctime(), ctime(), localtime(), mktime(), time()

------------------------------------------------------------------------------
#include <malloc.h>                                                       [PC]

int _heapchk (void);

    _heapchk() checks the default heap and the tiled default heap and
    all their blocks for consistency.  Note that _heapchk() may crash
    if the heap is corrupted.  _heapchk() can help debugging programs
    which experience heap problems.

  Return value:

    _heapchk() returns one of the following values:

    _HEAPBADBEGIN
            The heap is corrupted.

    _HEAPBADNODE
            A block of the heap is damaged or the heap is corrupted.

    _HEAPEMPTY
            The heap has not been initialized.

    _HEAPOK
            The heap seems to be consistent.

  See also: _udefault(), _heapset(), _uheapchk(), _utdefault()

------------------------------------------------------------------------------
#include <malloc.h>                                                    [VAC++]

int _heapmin (void);

    The _heapmin() function returns unused memory of the default
    regular heap to the operating system.  The heap is never made
    smaller than its initial size.  Calling _heapmin() is equivalent
    to calling _uheapmin() for the default heap.

  Return value:

    0       success

    -1      error

  See also: brk(), _heapchk(), sbrk(), _theapmin(), _udefault(),
            _uheapmin()

------------------------------------------------------------------------------
#include <malloc.h>                                                       [PC]

int _heapset (unsigned fill);

    _heapset() fills all bytes of all unused blocks of the default
    heap and the tiled default heap with FILL.  Note that _heapset()
    may crash if the heap is corrupted.  _heapset() can help debugging
    programs which erroneously depend on the contents of dynamically
    allocated blocks.  _heapchk() checks the heap more thoroughly than
    _heapset().

  Return value:

    _heapset() returns one of the following values:

    _HEAPBADBEGIN
            The heap is corrupted.

    _HEAPBADNODE
            A block of the heap is damaged or the heap is corrupted.

    _HEAPEMPTY
            The heap has not been initialized.

    _HEAPOK
            The heap seems to be consistent.

  See also: _udefault(), _heapchk(), _uheapset(), _utdefault()

------------------------------------------------------------------------------
#include <malloc.h>     /* for _heap_walk() */                         [VAC++]
#include <umalloc.h>    /* for _uheap_walk() */

int _heap_walk (int (*callback)(const void *, size_t, int, int,
                                const char *, size_t));
int _uheap_walk (Heap_t h, int (*callback)(const void *, size_t, int, int,
                                           const char *, size_t));

    _heap_walk() applies the function pointed to by CALLBACK to all
    free and used blocks of the default heap and the tiled default
    heap.

    _uheap_walk() applies the function pointed to by CALLBACK to all
    free and used blocks of the heap H.

    Note that the heap is locked, so using the heap in the callback
    function will cause a deadlock.

        int my_walker (const void *BLOCK, size_t SIZE, int FLAG,
                       int STATUS, const char *FNAME, size_t LINENO);

    BLOCK points to a block of SIZE bytes.  FLAG is either _USEDENTRY
    (for a used block) or _FREEENTRY (for a free block).  STATUS is
    one of the following values, describing the status of the block:

    _HEAPBADBEGIN
            The heap is corrupted.

    _HEAPBADNODE
            The block is damaged.

    _HEAPEMPTY
            The heap has not been initialized.

    _HEAPOK
            The heap seems to be consistent (_HEAPOK is 0).

    FNAME points to the file name of the source file in which the
    block has been allocated.  LINENO is the line number in which the
    block has been allocated.  FNAME is NULL if that information is
    not available, that is, if the object has not been allocated with
    a debugging heap function.

  Return value:

    _heap_walk() and _uheap_walk() return the last status (see above
    for a list of values) unless the callback function returned a
    non-zero value.  If the callback function returned a non-zero
    value, _heap_walk() and _uheap_walk() return that value.

  Restrictions:

    FNAME is current always NULL as there are no debugging heap
    functions.

  Hints:

    Use an extra heap if you want to allocate memory in the callback
    function.

  See also: _heapchk(), _udefault(), _uheapchk(), _uheap_walk2()

  Example:

    #include <stdio.h>
    #include <malloc.h>
    #include <umalloc.h>
    
    static int walk_dump (const void *obj, size_t size, int flag,
                          int status, const char *fname, size_t lineno)
    {
      if (status == _HEAPOK)
        printf ("0x%.8lx 0x%.8lx %s\n",
                (unsigned long)obj, (unsigned long)size,
                flag == _FREEENTRY ? "free" : "used");
      return status;
    }
    
    int main (void)
    {
      void *p;
    
      /* Avoid deadlock due to buffer allocation in printf()! */
      setvbuf (stdout, NULL, _IOLBF, BUFSIZ);
    
      p = malloc (1000);
      malloc (2000);
      free (p);
      _heap_walk (walk_dump);
      return 0;
    }

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

double hypot (double x, double y);
long double hypotl (long double x, long double y);

    Compute and return

        sqrt (X*X + Y*Y)

    On overflow, +INF is returned and errno is set to ERANGE.

    hypotl() uses the long double format.

  Return value:

    See above.

  See also: sqrt()

------------------------------------------------------------------------------
#include <io.h>                                                          [emx]

int _imphandle (int handle);

    Register an OS/2 file handle (created by DosOpen, for instance)
    with the emx run-time system.  Without importing an OS/2 file
    handle with _imphandle() into the emx run-time system, that handle
    cannot be used with any C library function.  If necessary,
    _imphandle() relocates the file handle (this happens when sockets
    are used).  After calling _imphandle(), you can use the returned
    file handle both with library functions and OS/2 API functions,
    and HANDLE can no longer be used (unless identical to the handle
    returned).  _imphandle() must not be called for file handles not
    created by an OS/2 API function.  _imphandle() must not be called
    for socket handles.  Handles inherited from the parent process are
    already registered with the emx run-time system.

  Return value:

    _imphandle() returns a file handle.  On error, _imphandle() sets
    errno and returns -1.

  See also: dup(), _impsockhandle(), open()

------------------------------------------------------------------------------
#include <sys/socket.h>                                                  [emx]

int _impsockhandle (int handle, int reserved);

    Register a socket handle of IBM TCP/IP with the emx run-time
    system.  HANDLE is the socket handle.  It must not be an emx
    socket handle.  To obtain the IBM TCP/IP socket handle of an emx
    socket handle, use _getsockhandle().  RESERVED must be zero.

    You have to link with the socket library (use the -lsocket
    option).

  Return value:

    _impsockhandle() returns a file handle.  On error,
    _impsockhandle() sets errno and returns -1.

  Restrictions:

    _getsockhandle() is implemented for OS/2 only.

    _impsockhandle() is not available with the system call library
    sys.lib (-Zsys).

  Hints:

    _getsockhandle() and _impsockhandle() can be used to pass down
    socket handles to child processes.  Call _getsockhandle() in the
    parent process, pass the value returned by _getsockhandle() to the
    child process (on the command line, for instance), and call
    _impsockhandle() on that value in the child process.  Do not close
    the socket in the parent process until the child process has
    called _impsockhandle() for that socket (use a semaphore if the
    child process is run asynchronously)!  Note that socket handles
    are automatically inherited across fork(), therefore
    _impsockhandle() must not be used with fork().

  See also: _getsockhandle(), _imphandle()

------------------------------------------------------------------------------
#include <strings.h>                                                     [BSD]

char *index (const char *string, int c);

    Return a pointer to the first occurrence of the character C in the
    null-terminated string pointed to by STRING.  If there is no
    character C in that string, NULL is returned.  If C is the null
    character (0), a pointer to the terminating null character of that
    string is returned.

  Return value:

    See above.

  See also: rindex(), strchr()

------------------------------------------------------------------------------
#include <sys/hw.h>                                                    [emx *]

unsigned _inp8 (unsigned port);
unsigned _inp16 (unsigned port);
unsigned _inp32 (unsigned port);

    These functions read a single byte or word from a hardware port.
    _inp8() reads a byte from PORT, _inp16() reads a 16-bit word from
    PORT, _inp32() reads a 32-bit word from PORT.

    You have to call _portaccess() first to enable access to a range
    of ports.  To make your program work under DOS, you have to use
    emx option -ai, see `Using emx options'.  Under OS/2, your program
    requires emxio.dll in a directory listed in LIBPATH.

  Return value:

    _inp8(), _inp16() and _inp32() return the value read from PORT.

  See also: _portaccess(), _inps8(), _outp8(), _wait0()

------------------------------------------------------------------------------
#include <sys/hw.h>                                                    [emx *]

void _inps8 (unsigned port, unsigned char *dst, unsigned count);
void _inps16 (unsigned port, unsigned short *dst, unsigned count);
void _inps32 (unsigned port, unsigned long *dst, unsigned count);

    These functions read multiple bytes or words from a hardware port.
    _inps8() reads COUNT bytes from PORT to the array pointed to by
    DST.  _inps16() reads COUNT 16-bit words from PORT to the array
    pointed to by DST.  _inps32() reads COUNT 32-bit words from PORT
    to the array pointed to by DST.

    The COUNT argument of _inps8() must not exceed 65535.

    The array pointed to by DST of _inps16() must be aligned on a
    16-bit boundary, that is, the address must be even.  COUNT must
    not exceed 32768.

    The array pointed to by DST of _inps32() must be aligned on a
    32-bit boundary, that is, the address must be a multiple of four.
    COUNT must not exceed 65536.

    You have to call _portaccess() first to enable access to a range
    of ports.  To make your program work under DOS, you have to use
    emx option -ai, see `Using emx options'.  Under OS/2, your program
    requires emxio.dll in a directory listed in LIBPATH.

  See also: _portaccess(), _inp8(), _outps8()

------------------------------------------------------------------------------
#include <dos.h>                                                          [PC]

int _int86 (int int_num, const union REGS *inp_regs, union REGS *out_regs);

    Issue a software interrupt under DOS.  This function loads the
    processor registers EAX, EBX, ECX, EDX, ESI and EDI from INP_REGS,
    calls software interrupt INT_NUM and stores the processor
    registers EAX, EBX, ECX, EDX, ESI, EDI and the flags register to
    OUT_REGS.

    emx option -ac must be used to enable _int86().  If -ac is not
    used, a protection violation exception occurs when _int86() is
    called.  See `Using emx options'.

  Return value:

    _int86() returns the value of the EAX register.

  Restrictions:

    _int86() is not supported under OS/2 (there are no software
    interrupts under OS/2).  Calling _int86() under OS/2 results in a
    protection violation.

    The emx DOS extender currently supports only interrupts 0x10,
    0x11, 0x14, 0x16, 0x17, 0x21 and 0x33.  Please note the following
    difference to DOS C compilers: the REGS union does not contain an
    x.cflag field.  The complete flags register is stored to the
    e.eflags field instead.  The carry flag is available in bit 0 of
    the e.eflags and x.flags fields.

    The following functions of interrupt 0x10 (video) are supported
    (the AH register contains the function number):

        0x00-0x0f, 0x10 (only subfunctions which don't involve
        pointers), 0x13, 0x1a, 0x40-0x4e (Hercules GRAFIX), 0x4f
        (VESA, subfunction AL=0x06 not supported), 0x6f, 0xf0, 0xf1,
        0xf6

    The following functions of interrupt 0x21 (DOS call) are supported
    (the AH register contains the function number):

        0x01-0x0c, 0x0e, 0x19, 0x2a-0x2e, 0x30, 0x33, 0x36-0x37,
        0x39-0x47, 0x4b-0x4f, 0x54, 0x56, 0x57, 0x5a, 0x5b

    The following functions of interrupt 0x33 (mouse) are supported
    (the AX register contains the function number):

        0x00-0x0b, 0x0d-0x13, 0x15, 0x1a-0x28, 0x2a, 0x2f-0x32, 0x35

    No pointer conversion is done for interrupts 0x11, 0x14, 0x16 and
    0x17.  That is, you cannot use functions which involve pointers to
    buffers in memory.

  Example: See /emx/test/int10.c

------------------------------------------------------------------------------
#include <sys/ioctl.h>                                                [SysV *]
#include <sys/termio.h>   /* for System V terminal interface */
#include <sys/kbdscan.h>  /* optional, for extended scan codes */

int ioctl (int handle, int request, int int_arg);
int ioctl (int handle, int request, void *ptr_arg);
int ioctl (int handle, int request, struct termio *tio);

    Device control for HANDLE.  REQUEST codes are:

    TCGETA  Get the parameters associated with the terminal HANDLE and
            store them in the object pointed to by TIO.  See also
            `General terminal interface'.

    TCSETA  Immediately set the parameters associated with the
            terminal HANDLE from the object pointed to by TIO.  See
            also `General terminal interface'.

    TCSETAF
            Set the parameters associated with the terminal HANDLE
            from the object pointed to by TIO after waiting for the
            output to drain and after fglusing the input queue.  See
            also `General terminal interface'.

    TCSETAW
            Set the parameters associated with the terminal HANDLE
            from the object pointed to by TIO after waiting for the
            output to drain.  See also `General terminal interface'.

    TCFLSH  Flush the terminal queues.  If INT_ARG is 0, the input
            queue is flushed; if INT_ARG is 1, the output queue is
            flushed; if INT_ARG is 2, both the input and output queues
            are flushed.  Works only if HANDLE refers to the keyboard.
            Only flushing the keyboard queue is implemented.

    TCSBRK  Wait for output to drain and then send a break.  The
            length of the break depends on INT_ARG.  Currently
            ignored.  It is not yet specified how the length of the
            break depends on INT_ARG.

    TCXONC  flow control, depending on INT_ARG.  Currently ignored

    FIONREAD
            Get number of available characters.  The number of
            available characters is stored to the int pointed to by
            PTR_ARG.  FIONREAD is implemented for the following types
            of handles:

            - Terminal handles (keyboard) for which the general
              terminal interface is enabled.  Note that if ICANON is
              set, the number of characters in the keyboard buffer is
              returned which is not the number of characters available
              for read(), as at least one of the buffered characters
              (carriage return) is used for command line editing

            - Pseudo TTYs and console device implemented by
              xf86sup.sys

            - Named pipes

            - Pipes created with pipe() by programs using emx.dll

            - Sockets

            - All file handles under DOS (0 or 1 character available).

    FGETHTYPE
            Get the handle type and store it to the int pointed to by
            PTR_ARG.  See <sys/ioctl.h> for handle types (HT_FILE, for
            instance).

    There are additional REQUESTS codes for socket handles.

  Return value:

    On error, ioctl() sets errno and returns -1.  Otherwise, ioctl()
    returns 0 unless a different return value is defined above.

  Restrictions:

    With the system call library sys.lib (-Zsys), only the FGETHTYPE
    request is available.

    The TCSBRK and TCXONC requests are currently ignored.

    Under DOS, for requests TCGETA, TCSETA, TCSETAF, TCSETAW, and
    TCFLSH, the value of the HANDLE argument must be 0.

    TCFLSH is implemented for the keyboard, only.

  See also: fcntl(), open(), read()

------------------------------------------------------------------------------
#include <ctype.h>                                                      [UNIX]

int isascii (int c);

    Return a non-zero value iff C is a valid ASCII character (0
    through 127).  isascii() can be applied to all integer values.
    isascii() is implemented both as macro and as function.

  Return value:

    See above.

  See also: isalnum()

------------------------------------------------------------------------------
#include <ctype.h>                                                       [C90]

int isalnum (int c);
int isalpha (int c);
int iscntrl (int c);
int isdigit (int c);
int isgraph (int c);
int islower (int c);
int isprint (int c);
int ispunct (int c);
int isspace (int c);
int isupper (int c);
int isxdigit (int c);

    These functions (or macros) are used for determining the type of a
    character, depending on the current locale.  C must be an integer
    which is representable as unsigned char (that is, 0 through 255),
    or equal to EOF; otherwise the behavior is undefined.  These
    functions are implemented both as macros and as functions.

    isalnum() tests for alphanumeric characters, that is, any
    character for which isalpha() or isdigit() is true.

    isalpha() tests for alphabetic characters, that is, any character
    for which islower() or isupper() is true.  For locales other than
    "C", isalpha() may also return true for characters for which none
    of iscntrl(), isdigit(), ispunct() or isspace() is true.

    iscntrl() tests for control characters.  Control characters are
    not printing characters.

    isdigit() tests for decimal digits ('0' through '9').

    isgraph() tests for printing characters except space (' '), that
    is, any character (except space) for which isprint() is true.

    islower() tests for lower-case characters, that is, 'a' trough
    'z'.  For locales other than "C", islower() may also return true
    for characters for which none of iscntrl(), isdigit(), ispunct()
    or isspace() is true.

    isprint() tests for printing characters including space (' ').
    Printing characters are characters which occupy one printing
    position on a display device.

    ispunct() tests for punctutation characters, that is, printing
    characters for which isalnum() is false and which are not space
    (' ').

    isspace() tests for white-space characters.  In locales other than
    "C", isspace() may return true for characters for which isalnum()
    is false.

    isupper() tests for upper-case characters, that is, 'A' trough
    'Z'.  For locales other than "C", isupper() may also return true
    for characters for which none of iscntrl(), isdigit(), ispunct()
    or isspace() is true.

    isxdigit() tests for hexadecimal digits ('0' through '9', 'a'
    through 'f', and 'A' through 'F').

  Return value:

    These functions return a non-zero value if the condition is true,
    or 0 if it is not true.

  Restrictions:

    Currently, locale is ignored.

  See also: isascii(), setlocale(), tolower(), toupper(), _tolower(),
            _toupper()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int isatty (int handle);

    Returns a non-zero value if HANDLE refers to a character device.
    Returns 0 if HANDLE does not refer to a character file (file or
    pipe).  If there is an error, errno is set and -1 is returned.

  Return value:

    See above.

  See also: _isterm(), ioctl()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

int isfinite (float x);
int isfinite (double x);
int isfinite (long double x);

    Determine whether X is finite (zero, subnormal, normal) or not
    (infinite, NaN).  The argument X must be of a floating-point type.
    Determination is based on the type of the argument.

  Return value:

    isfinite() returns a non-zero value if X is has a finite value;
    isfinite() returns 0 otherwise.

  See also: fpclassify(), isnan(), isnormal(), signbit()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

int isnan (float x);
int isnan (double x);
int isnan (long double x);

    Determine whether X is a NaN.  The argument X must be of a
    floating-point type.  Determination is based on the type of the
    argument.

  Return value:

    isnan() returns a non-zero value if X has a NaN value; isnan()
    returns 0 otherwise.

  See also: fpclassify(), isfinite(), isnormal(), signbit()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

int isnormal (float x);
int isnormal (double x);
int isnormal (long double x);

    Determine whether X is normal or not (zero, subnormal, infinite,
    NaN).  The argument X must be of a floating-point type.
    Determination is based on the type of the argument.

  Return value:

    isnormal() returns a non-zero value if X has a normal value;
    isnormal() returns 0 otherwise.

  See also: fpclassify(), isfinite(), isnan(), signbit()

------------------------------------------------------------------------------
#include <io.h>                                                          [emx]

int _isterm (int handle);

    Returns a non-zero value if HANDLE refers to the standard input
    (keyboard) or standard output (screen) device.  Otherwise, returns
    0.  If there is an error, errno is set and 0 is returned.

    Consider using ioctl (FGETHTYPE) instead.

  Return value:

    See above.

  See also: isatty(), ioctl()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

char *_itoa (int value, char *string, int radix);
char *_ltoa (long value, char *string, int radix);
char *_ultoa (unsigned long value, char *string, int radix);

    Convert the number VALUE to a string using the number base RADIX
    (between 2 and 36).  The string is stored to the array pointed to
    by STRING.

  Return value:

    _itoa(), _ltoa() and _ultoa() return STRING.

  See also: atoi(), _lltoa(), sprintf(), strtol()

------------------------------------------------------------------------------
#include <signal.h>                                                   [UNIX *]

int kill (int pid, int sig);

    Send the signal SIG to process PID.  If PID is smaller than -1,
    the signal is sent to process -PID and its children.

    If PID is the process ID of the process which is calling kill(),
    the signal is sent to the main thread (thread 1) of that process
    (unless the syscam call library is used).  Use raise() to generate
    a signal in the current thread.

    If SIG is 0, kill() checks only whether PID is valid or not.

    See section 4 for details on signal processing.

  Return value:

    If successful, kill() returns 0.  Otherwise kill() sets errno and
    returns -1.

  Errors:

    EINVAL  SIG is not a valid signal number

    ESRCH   PID is not the process ID of a process or process PID is
            not a child process

  Restrictions:

    Only SIGINT and SIGBREAK can be sent to arbitrary child processes.
    A process can send the other signals only to itself, see raise(),
    or to other emx programs.

    Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
    Negative values of PID are implemented for OS/2 only and work only
    for direct children of the caller.

    When using the system call library sys.lib (-Zsys), a process can
    send arbitrary signals to itself, only SIGINT and SIGBREAK can be
    sent to only child processes, negative values of PID are not
    allowed.  Moreover, kill() cannot be used to send a signal to
    thread 1; the signal will be generated in the current thread.

  See also: pause(), raise(), sigaction(), signal()

------------------------------------------------------------------------------
#include <stdlib.h>     /* use this */                                   [C90]
#include <math.h>       /* or this */

long labs (long n);

    Compute the absolute value of N.  In-line code is generated for
    this function.

  Return value:

    If N is negative, labs() returns -N.  Otherwise, labs() returns N.

  See also: abs(), fabs()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double ldexp (double x, int exp);
long double ldexpl (long double x, int exp);

    Compute and return X * 2 ^ EXP.  On overflow, NaN is returned and
    errno is set to ERANGE.

    ldexpl() uses the long double format.

  Return value:

    See above.

  See also: frexp(), pow()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

_lldiv_t _lldiv (long long num, long long den);
_uldiv_t _uldiv (unsigned long num, unsigned long den);
_ulldiv_t _ulldiv (unsigned long long num, unsigned long long den);

    Perform an integer division, dividing NUM by DEN.  The quotient
    and the remainder are returned in the quot and rem fields,
    respectively.

    The following table shows the signs of quot and rem depending on
    the signs of NUM and DEN for _lldiv():

        NUM DEN  quot rem
        
         +   +    +    +
         +   -    -    +
         -   +    -    -
         -   -    +    -

    Note: Do not use the -fpcc-struct-return option of GCC.

  Return value:

    _lldiv(), _uldiv() and _ulldiv() return a structure which contains
    the quotient and the remainder in the quot and rem fields,
    respectively.

  See also: div(), ldiv()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char *_lltoa (long long value, char *string, int radix);
char *_ulltoa (unsigned long long value, char *string, int radix);

    Convert the number VALUE to a string using the number base RADIX
    (between 2 and 36).  The string is stored to the array pointed to
    by STRING.

  Return value:

    _lltoa() and _ulltoa() return STRING.

  See also: atoi(), _itoa(), _strtoll(), _strtoull()

------------------------------------------------------------------------------
#include <locale.h>                                                      [C90]

struct lconv *localeconv (void);

    Return the address of a structure containing values for the
    formatting of umeric and monetary quantities according to the
    current locale.

    The structure is defined as follows:

        struct lconv
        {
          char *decimal_point;
          char *thousands_sep;
          char *grouping;
          char *int_curr_symbol;
          char *currency_symbol;
          char *mon_decimal_point;
          char *mon_thousands_sep;
          char *mon_grouping;
          char *positive_sign;
          char *negative_sign;
          char int_frac_digits;
          char frac_digits;
          char p_cs_precedes;
          char p_sep_by_space;
          char n_cs_precedes;
          char n_sep_by_space;
          char p_sign_posn;
          char n_sign_posn;
        };

    If a string member points to "", the value is not available in the
    current locale or is of zero length.  Note that decimal_point
    never points to "".  The char members are non-negative numbers.
    CHAR_MAX indicates that the value is not available in the current
    locale.

    The members have the following meaning:

    decimal_point

        The decimal point character used for formatting numbers (which
        are not monetary quantities).

    thousands_sep

        The character used for separating groups of digits before the
        decimal point in numbers (which are not monetary quantities).

    grouping

        An array containing the sizes of the groups of digits (right
        to left), terminated by zero (the previous size is to be used
        repeatedly for the remainder of the digits) or CHAR_MAX (no
        further grouping is to be performed).  This is used for
        numbers which are not monetary quantities.

    int_curr_symbol

        The first three characters contain the international currency
        symbol, the fourth character (which is the last one) is the
        character used for separating the international currency
        symbol from the monetary quantity.

    currency_symbol

        The local currency symbol.

    mon_decimal_point

        The decimal point character used for formatting monetary
        quantities.

    mon_thousands_sep

        The character used for separating groups of digits before the
        decimal point in monetary quantities.

    mon_grouping

        An array containing the sizes of the groups of digits (right
        to left), terminated by zero (the previous size is to be used
        repeatedly for the remainder of the digits) or CHAR_MAX (no
        further grouping is to be performed).  This is used for
        monetary quantities.

    positive_sign

        The string used for indicating that a monetary quantity is not
        negative (zero or positive).

    negative_sign

        The string used for indicating that a monetary quantity is
        negative.

    int_frac_digits

        The number of digits after the decimal point in monetary
        quantities (international format).

    frac_digits

        The number of digits after the decimal point in monetary
        quantities (local format).

    p_cs_precedes

        1 or 0 if currency_symbol respectively precedes or succeeds
        the monetary quantity if it is not negative (zero or
        positive).

    p_sep_by_space

        1 or 0 if a space respectively does or does not separate
        currency_symbol from a non-negative (zero or positive)
        monetary quantity.

    n_cs_precedes

        1 or 0 if currency_symbol respectively precedes or succeeds
        the monetary quantity if it is negative.

    n_sep_by_space

        1 or 0 if a space respectively does or does not separate
        currency_symbol from a negative monetary quantity.

    p_sign_posn

        A number indicating the position of positive_sign for a
        non-negative (zero or positive) monetary quantity:

        0       Parentheses surround the monetary quantity and
                currency_symbol.

        1       The sign string precedes the quantity and
                currency_symbol.

        2       The sign string succeeds the quantity and
                currency_symbol.

        3       The sign string immediately precedes currency_symbol.

        4       The sign string immediately succeeds currency_symbol.

    n_sign_posn

        A number indicating the position of positive_sign for a
        negative monetary quantity.  See p_sign_posn for a description
        of the values.

  Return value:

    localeconv() returns a pointer to a statically allocated
    structure.  The contents of that structure can be changed by the
    next call to localeconv() or setlocale().  You must not write to
    the structure.

  Restrictions:

    The contents of the structure are adjusted to use CHAR_MAX for the
    char type of the module calling localeconv().  When mixing modules
    with different char types, this will break.  When calling
    localeconv() in a library, CHAR_MAX of the library will be used
    instead of CHAR_MAX of the program using the library.

    When calling the function version of localeconv(), for instance by
    suppressing macro expansion, it is assumed that char is signed.

  See also: setlocale()

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

struct tm *localtime (const time_t *t);

    Convert the number of seconds elapsed since 00:00:00 1-Jan-1970
    Coordinated Universal Time (UTC, GMT) in the variable pointed to
    by T to a time and date structure for the local timezone and
    return a pointer to the structure.  gmtime(), mktime() and
    localtime() use the same memory location, therefore the values are
    overwritten if one of these functions is called.

  Return value:

    localtime() returns a pointer to a statically allocated structure.

  See also: asctime(), ctime(), gmtime(), mktime(), time()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double log (double x);
double log10 (double x);

long double logl (long double x);
long double log10l (long double x);

    log() returns the natural logarithm of X.  log10() returns the
    base-10 logarithm of X.

    If X is zero, -INF is returned and errno set to EDOM.  If X is
    negative, a NaN is returned and errno set to EDOM.

    logl() and log10l() use the long double format.

  Return value:

    See above.

  See also: exp(), pow()

------------------------------------------------------------------------------
#include <setjmp.h>                                                      [C90]

void longjmp (jmp_buf there, int n);

    Restore the context saved in THERE by setjmp().  longjmp() does a
    non-local goto, causing execution to continue at the setjmp() call
    which most recently saved a stack context in THERE.  setjmp() will
    return N.  If N is 0, setjmp() will return 1.  When calling
    longjmp() in a signal handler or in a function called by a signal
    handler (that is, while a signal handler is active), the signal
    handler will be unwound, that is, it is assumed that the signal
    handler doesn't return.  longjmp() must be called in the same
    thread as the most recent call to setjmp() for THERE.  Moreover,
    the function which most recently called setjmp() to save a stack
    context in THERE must still be active.  Don't expect local
    variables to be preserved unless declared volatile.

    As jmp_buf is an array type, the & operator need not be applied.

  See also: setjmp(), sigaction(), siglongjmp(), sigsetjmp(), signal()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                               [VAC++]

unsigned long _lrotl (unsigned long value, int shift);
unsigned long _lrotr (unsigned long value, int shift);

    _lrotl() returns VALUE (32 bits) rotated left by SHIFT bits.  If
    SHIFT is 1, bit 30 is returned as bit 31, bit 29 is returned as
    bit 30, and so on, bit 0 is returned as bit 1, and bit 31 is
    returned as bit 0.

    _lrotr() returns VALUE (32 bits) rotated right by SHIFT bits.  If
    SHIFT is 1, bit 1 is returned as bit 0, bit 2 is returned as bit
    1, and so on, bit 31 is returned as bit 30, and bit 0 is returned
    as bit 31.

    SHIFT should be 0 through 31.

    These functions are implemented as inline functions.

  See also: _crotl(), _crotr(), _srotl(), _srotr()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

long lseek (int handle, long offset, int origin);

    lseek() moves the file pointer of HANDLE.  The new position OFFSET
    is relative to ORIGIN: If ORIGIN is SEEK_SET, OFFSET is relative
    to the beginning of the file, if ORIGIN is SEEK_CUR, OFFSET is
    relative to the current position, if ORIGIN is SEEK_END, OFFSET is
    relative to the end of the file.  The file pointer cannot be moved
    before the beginning of the file.  lseek() does not change the
    size of the file.

  Return value:

    lseek() returns the new position relative to the beginning of the
    file.  If there is an error, lseek() returns -1.

  Restrictions:

    If the file pointer is set beyond the end of file, the data
    between the end of file and the new position is undefined (it
    should be read as zeros, but isn't).

    For text-mode files, OFFSET must be either zero (with ORIGIN equal
    to SEEK_SET, SEEK_CUR, or SEEK_END) or a value returned by a call
    to tell() on the same file (with ORIGIN equal to SEEK_SET).  For
    text-mode files ending with a Ctrl-Z, SEEK_END is not allowed.

  See also: chsize(), filelength(), tell()

------------------------------------------------------------------------------
                                                                         [C90]
int main (void);
int main (int argc, char *argv[]);
int main (int argc, char *argv[], char *envp[]);

    This is the function called by the startup code to run your
    program.  It is not a library function.  ARGC is the number of
    command line arguments, including the program name.  ARGV points
    to an array of pointers to the command line arguments.  ENVP
    points to an array of pointers to the environment strings.  The
    last entry of each array is a NULL pointer.  main() should always
    return a value.  If main() returns, exit() is called using the
    return value of main() as argument.  If main() ends without return
    statement and without calling exit(), the return code of the
    program is undefined.  This should be avoided.  After changing the
    environment with putenv(), you should use the environ global
    variable instead of the ENVP argument of main().

  Return value:

    The return value of main() will be the return code of the process.

  See also: _envargs(), environ, _execname(), exit(), putenv(),
            _response(), _wildcard()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

void _makepath (char *dst, const char *drive, const char *dir,
                const char *fname, const char *ext);

    Build a path name from components and store it to the array
    pointed to by DST.  The array at DST should be of size _MAX_PATH.
    If DRIVE is not NULL and does not point to the empty string, the
    first character of the string (a drive name) pointed to by DRIVE
    followed by a colon is stored to the array pointed to by DST.  If
    DIR is not NULL and does not point to the empty string, the string
    (a directory name) pointed to by DIR is copied to DST.  If it does
    not end with \ or /, _makepath() appends a / character (or a \
    character if the string pointed to by DIR contains at least one
    backslash).  If FNAME is not NULL, the string pointed to by FNAME
    (a filename) is copied to DST.  If EXT is not NULL and does not
    point to the empty string, the string pointed to by EXT (an
    extension) is copied to DST.  If the string pointed to by EXT does
    not start with a .  character, _makepath() inserts a . in front of
    the string pointed to by EXT.  If the length of the resulting
    string (including the terminating null character) exceeds
    _MAX_PATH, the string is truncated to _MAX_PATH characters
    (including the terminating null character).

    _makepath() properly handles DBCS characters.

  See also: _nls_init(), _splitpath()

  Example:

    char drive[_MAX_DRIVE], dir[_MAX_DIR];
    char tmp[_MAX_PATH];
    _splitpath (path, drive, dir, NULL, NULL);
    _makepath (tmp, drive, dir, "tmpfile", "$$$");

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

void *malloc (size_t size);

    Allocate a block of memory big enough for holding SIZE bytes.  If
    there is an error, malloc() returns NULL.  If SIZE is 0, zero
    bytes of memory are allocated, the return value will be unequal
    NULL.

  Return value:

    malloc() returns a pointer to a newly allocated block of memory.
    On error, malloc() returns NULL.

  Implementation-defined behavior:

    malloc() allocates from the default heap of the current thread.
    malloc(0) returns a non-NULL pointer if there's enough space left
    in the heap for a block of the minimum size.

  Restrictions:

    It's possible to replace the emx C library's malloc()
    implementation; for instance, you can use GNU malloc.  However, do
    not replace malloc() etc. when dynamically linking to the C
    runtime library as the functions in the DLL won't call your
    replacements.

  See also: calloc(), free(), _msize(), realloc(), _tmalloc(),
            _udefault(), _umalloc()

------------------------------------------------------------------------------
#include <math.h>                                                       [SysV]

int matherr (struct exception *x);

    Exception handler for floating point math.

  Return value:

    0       success

    non-0   error

  Restrictions:

    matherr() is not implemented.

  See also: sigaction(), signal()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

int mblen (const char *s, size_t n);

    Compute the number of bytes comprising the multibyte character
    pointed to by S.  If S is NULL, the shift state is reset to the
    initial state.  At most N bytes at S are examined; a multibyte
    character consisting of more than N bytes is deemed invalid.

    Except for the different shift states, this is equivalent to

        mbtowc (NULL, S, N)

    The shift state of mbtowc() is not affected.

    In programs linked with the multithread libraries, each thread has
    its own shift state for mblen().

  Return value:

    If S is NULL, mblen() returns a non-zero value (if state-dependent
    encoding is used) or a zero value (if state-dependent encoding is
    not used).  If S is not NULL, mblen() returns 0 (if S points to
    the null character), the number of bytes comprising the multibyte
    character pointed to by S (if there is a valid multibyte
    character), or -1 (if there is not a valid multibyte character).

  See also: mbtowc(), setlocale()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n);

    Convert the null-terminated sequence of multibyte character
    pointed to by S to a sequence of wchar_t codes pointed to by PWCS.
    The multibyte character sequence starts in the initial shift
    state.  At most N codes are stored to PWCS.  PWCS will be
    terminated with a code of value zero if N is big enough.

    The shift state of mbtowc() and mblen() is not affected.

  Return value:

    mbstowcs() returns the number of codes stored to PWCS (excluding
    the terminating zero code) or (size_t)-1 if an invalid multibyte
    character is encountered.

  See also: mblen(), mbtowc(), setlocale(), wcstombs()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

int mbtowc (wchar_t *pwc, const char *s, size_t n);

    Convert the multibyte character pointed to by S to a wchar_t code
    and store it to PWC.  If S is NULL, the shift state is reset to
    the initial state.  At most N bytes at S are examined; a multibyte
    character consisting of more than N bytes is deemed invalid.

    The shift state of mblen() is not affected.

    In programs linked with the multithread libraries, each thread has
    its own shift state for mbtowc().

  Return value:

    If S is NULL, mbtowc() returns a non-zero value (if
    state-dependent encoding is used) or a zero value (if
    state-dependent encoding is not used).  If S is not NULL, mbtowc()
    returns 0 (if S points to the null character), the number of bytes
    comprising the multibyte character pointed to by S (if there is a
    valid multibyte character), or -1 (if there is not a valid
    multibyte character).

  See also: mblen(), mbstowcs(), setlocale(), wctomb()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

int _md_close (struct _md *md);

    Destroy the descriptor MD.  MD must have been returned by
    _md_open() or _md_use_file().  If MD has been returned by
    _md_open(), the file will be closed.  If MD has been returned by
    _md_use_file(), the file won't be closed.  _md_close() frees the
    memory associated with MD.  Do not use MD after calling
    _md_close().

    You have to link with the moddef library (use the -lmoddef
    option).

  Return value:

    0       success

    -1      error

  See also: _md_open(), _md_use_file()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

const char *_md_errmsg (_md_error code);

    Return a pointer to the default error message for the error code
    CODE.  This function can be used in the callback function of
    _md_parse().

    You have to link with the moddef library (use the -lmoddef
    option).

  See also: _md_parse()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

_md_token _md_get_token (struct _md *md);
long _md_get_number (const struct _md *md);
const char *_md_get_string (const struct _md *md);
long _md_get_linenumber (const struct _md *md);

    Retrieve information about the current token of MD (the token most
    recently read by _md_next_token (md)).

    _md_get_token() returns the token identifier (see _md_next_token()
    for details).  If _md_get_token() has not been called for MD,
    _MD_eof is returned.

    If the current token is a number, _md_get_number() returns the
    value of the number.  Otherwise, _md_get_number() returns 0.

    _md_get_string() returns the string value of the current token.
    The string value consists of all the characters that are part of
    the token.

    _md_get_linenumber() returns the number of the line from which the
    token has been read.  The first line is numbered 1.

    You have to link with the moddef library (use the -lmoddef
    option).

  See also: _md_next_token()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

_md_token _md_next_token (struct _md *md);

    Read the next token from the module definition file MD and return
    the token identifier.  See <sys/moddef.h> for token identifiers.
    Most token identifiers identify a keyword.  For instance, _MD_NAME
    is returned for the NAME keyword.  The following special token
    identfiers are defined:

    _MD_dot

        The character `.'.

    _MD_at

        The character `@'.

    _MD_equal

        The character `='.

    _MD_number

        A number.  Use _md_get_number() to retrieve the value.

    _MD_word

        A word which isn't a keyword.  Use _md_get_string() to
        retrieve the value.

    _MD_quote

        A quoted string.  _md_get_string() to retrieve the value.

    _MD_eof

        The end of the file has been reached.

    _MD_ioerror

        An I/O error occured while reading from the file (fatal
        error).

    _MD_missingquote

        A quote character is missing (fatal error).  Quote characters
        must come in pairs.

    After calling _md_next_token(), you can retrieve the token
    identifier, numeric value, string value and line number of the
    current token by calling _md_get_token(), _md_get_number(),
    _md_get_string() and _md_get_linenumber(), respectively.

    You have to link with the moddef library (use the -lmoddef
    option).

  See also: _md_get_linenumber(), _md_get_number(), _md_get_string(),
            _md_get_token(), _md_open(), _md_parse(), _md_use_file()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

struct _md *_md_open (const char *fname);

    Create a descriptor for reading module definition statements from
    the file whose name is in the string pointed to by FNAME.  The
    file is opened in SH_DENYWR mode.  On error (file cannot be opened
    or out of memory), _md_open() sets errno and returns NULL.
    Otherwise, a descriptor is returned which can be passed to
    _md_next_token() or _md_parse() to parse the file.  Call
    _md_close() to close the file and to destroy the descriptor.

    You have to link with the moddef library (use the -lmoddef
    option).

  See also: _md_next_token(), _md_parse(), _md_use_file()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

int _md_parse (struct _md *md,
               int (*callback)(struct _md *md, const _md_stmt *stmt,
                               _md_token token, void *arg),
               void *arg);

    Parse the module definition file MD, calling CALLBACK for each
    statement.  The token identifier of the statement is passed in
    TOKEN to CALLBACK.  Information about the statement is passed in
    STMT.  Moreover, CALLBACK receives _md_parse()'s MD and ARG
    arguments.  ARG can be used to pass additional user data to
    CALLBACK.

    CALLBACK is also called if an error is encountered.  In that case,
    TOKEN has the special value _MD_parseerror.

    _md_parse() starts parsing at the current token, that is,
    _md_next_token() has to be called before invoking _md_parse().
    _md_parse() stops parsing when reaching the end of the file or
    when CALLBACK returns a non-zero value.  In the latter case,
    _md_parse() returns the value returned by CALLBACK.  In all other
    cases, _md_parse() returns 0.

    The following values of TOKEN can be passed to CALLBACK:

    _MD_BASE

        BASE statement.  The base address is available in
        STMT->base.addr.

    _MD_CODE

        CODE statement.  The segment attributes are available in
        STMT->segment.attr, using a combination of constants like
        _MDS_IOPL.

    _MD_DATA

        DATA statement.  The segment attributes are available in
        STMT->segment.attr, using a combination of constants like
        _MDS_MULTIPLE.

    _MD_DESCRIPTION

        DESCRIPTION statement.  The description string is available in
        STMT->descr.string.

    _MD_EXETYPE

        EXETYPE statement.  The executable type is available in
        STMT->exetype.type using a constant like _MDX_OS2.  For
        _MDX_WINDOWS, the minor and major version numbers are
        available in STMT->exetype.minor_version and
        STMT->exetype.major_version, respectively.  If the version
        numbers are not specified or if the executable type is not
        WINDOWS, these fields are 0.

    _MD_EXPORTS

        One export entry of an EXPORTS statement.  Information about
        the export entry is available in STMT->export:

        flags

            If an ordinal number is present, _MDEP_ORDINAL is set.  If
            the NONAME keyword is present, _MDEP_NONAME is set.  If
            the RESIDENTNAME keyword is present, _MDEP_RESIDENTNAME is
            set.  If the NODATA keyword is present, _MDEP_NODATA is
            set.  If the number of parameter words is present,
            _MDEP_PWORDS is set.

        internalname

            The internal name of the entry point.  If no internal name
            is specified, the string is empty.

        entryname

            The external name of the entry point.

        ordinal

            The ordinal number, if flags contains _MDEP_ORDINAL.
            Otherwise, this field is 0.

        pwords

            The number of parameter words, if flags contains
            _MDEP_PWORDS.  Otherwise, this field is 0.

    _MD_HEAPSIZE

        HEAPSIZE statement.  If a heap size is specified, the heap
        size is available in STMT->heapsize.size and
        STMT->heapsize.maxval is 0.  If MAXVAL is specified,
        STMT->heapsize.maxval is non-zero and STMT->heapsize.size is
        0.

    _MD_IMPORTS

        One import entry of an IMPORTS statement.  Information about
        the import entry is available in STMT->import:

        flags

            If an ordinal number is present, _MDIP_ORDINAL is set.

        internalname

            The internal name of the entry point.  If no internal name
            is specified, the string is empty.

        entryname

            The external name of the entry point.  If no external name
            is specified (that is, if _MDIP_ORDINAL is set), the
            string is empty.

        modulename

            The name of the dynamic link library.

        ordinal

            The ordinal number, if flags contains _MDIP_ORDINAL.
            Otherwise, this field is 0.

    _MD_LIBRARY

        LIBRARY statement.  The name is available in
        STMT->library.name.  The library initialization and
        termination modes are available in STMT->library.init and
        STMT->library.term, respectively.  These fields are set to
        _MDIT_DEFAULT if no modes are specified.  Otherwise,
        _MDIT_INSTANCE or _MDIT_GLOBAL is used.

    _MD_NAME

        NAME statement.  The name is available in STMT->name.name.
        The application type is available in STMT->name.pmtype.  That
        field is set to _MDT_DEFAULT (if no type is specified),
        _MDT_WINDOWAPI, _MDT_WINDOWCOMPAT or _MDT_NOTWINDOWCOMPAT.  If
        NEWFILES is specified, the STMT->name.newfiles field is
        non-zero.

    _MD_OLD

        OLD statement.  The file name is available in STMT->old.name.

    _MD_PHYSICAL

        PHYSICAL DEVICE statement.  The name is available in
        STMT->device.name.

    _MD_PROTMODE

        PROTMODE statement.  No additional information is available.

    _MD_REALMODE

        REALMODE statement.  No additional information is available.

    _MD_SEGMENTS

        One segment definition of a SEGMENTS statement.  The segment
        attributes are available in STMT->segment.attr, using a
        combination of constants like _MDS_SHARED.  The segment name
        is available in STMT->segment.segname.  The class name is
        available in STMT->segment.classname.  If no class name is
        specified, that string is empty.

    _MD_STACKSIZE

        STACKSIZE statement.  The stack size is available in
        STMT->stacksize.size.

    _MD_STUB

        STUB statement.  The file name is available in
        STMT->stub.name.  If the NONE keyword is used, STMT->stub.none
        is none-zero and the string is empty.

    _MD_VIRTUAL

        VIRTUAL DEVICE statement.  The name is available in
        STMT->device.name.

    _MD_parseerror

        _md_parse() has detected an error.  The token identifier of
        the current statement is available in STMT->error.stmt.  An
        error code is available in STMT->error.code.  The following
        error codes are defined:

        _MDE_IO_ERROR

            _md_next_token() returned _MD_ioerror because an I/O error
            occured while reading from the file.

        _MDE_MISSING_QUOTE

            _md_next_token() returned _MD_missingquote because a quote
            character is missing.  Quote characters must come in
            pairs.

        _MDE_EMPTY

            The module definition file is empty, there are no
            statements.  This error also occurs if _md_next_token()
            wasn't called before calling _md_parse().

        _MDE_NAME_EXPECTED

            A name (segment name, class name, entry name) was
            expected, but a different token was read.

        _MDE_STRING_EXPECTED

            A quoted string was expected, but a different token was
            read.

        _MDE_NUMBER_EXPECTED

            A number was expected, but a different token was read.

        _MDE_DEVICE_EXPECTED

            The VIRTUAL or PHYSICAL keyword isn't followed by the
            DEVICE keyword.

        _MDE_EQUAL_EXPECTED

            An `=' character was expected, but a different token was
            read.

        _MDE_DOT_EXPECTED

            A `.' character was expected, but a different token was
            read.

        _MDE_STRING_TOO_LONG

            A string is too long.

        _MDE_INVALID_ORDINAL

            An ordinal number is invalid.  Valid ordinal numbers are
            in 1 through 65535.

        _MDE_INVALID_STMT

            An invalid keyword (which doesn't start a statement) was
            read.

        You can use _md_errmsg() to get a default error message for
        the error code.

        If CALLBACK returns 0, _md_parse() skips tokens until finding
        a keyword which starts a statement or until hitting end of
        file.  If CALLBACK returns a non-zero number, that number will
        be immediately returned by _md_parse().

    You have to link with the moddef library (use the -lmoddef
    option).

  See also: _md_errmsg(), _md_next_token(), _md_open(), _md_use_file()

  Example: See /emx/test/mdecho.c

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/moddef.h>

struct _md *_md_use_file (FILE *f);

    Create a descriptor for reading module definition statements from
    the file F.  On error (out of memory), _md_use_file() sets errno
    and returns NULL.  Otherwise, a descriptor is returned which can
    be passed to _md_next_token() or _md_parse() to parse the file.
    Don't close F before calling _md_close().  Call _md_close() to
    destroy the descriptor.

    You have to link with the moddef library (use the -lmoddef
    option).

  See also: _md_close(), _md_next_token(), _md_open()

------------------------------------------------------------------------------
#include <sys/hw.h>                                                      [emx]

void *_memaccess (unsigned first, unsigned last, int flag);

    Gain access to physical memory under DOS.  To access memory which
    is outside the memory space of the current process, you have to
    call _memaccess().  emx option -am must be used to enable
    _memaccess(), see `Using emx options'.

    FIRST is the address of the first byte of the physical memory
    area, LAST is the address of the last byte of the physical memory
    area to be accessed.  Both addresses are physical addresses.
    FIRST and LAST+1 must be page aligned: FIRST and LAST+1 must be
    integral multiples of 4096.  That is, with using hexadecimal
    notation, FIRST must end with 000, LAST must end with fff.  If
    FLAG is 0, read access is granted.  If FLAG is 1, read and write
    access is granted.  Write access can be granted if the address
    range of the physical memory area is entirely in the range 0xa0000
    to 0xbffff.  If bytes outside this range are included in FIRST to
    LAST, emx option -aw must be used to enable write access, see
    `Using emx options'.

  Return value:

    _memaccess() returns a pointer to virtual memory mapped to the
    physical memory area.  On failure, _memaccess() sets errno and
    returns NULL.

  Errors:

    EACCES  FIRST not page aligned; LAST+1 not page aligned; LAST not
            greater than FIRST; write access not allowed

    EINVAL  FLAG is not 0 or 1

    ENOMEM  not enough virtual memory for storing the paging tables;
            linear address space of process not big enough for the
            request

  Restrictions:

    _memaccess() is not available under OS/2.  Obtaining access to
    memory by linear address is not yet supported.

  See also: _portaccess()

  Example: See /emx/test/hw_mem.c

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                    [PC]
#include <memory.h>     /* or this */

void *memccpy (void *s1, const void *s2, int c, size_t n);

    Copy at most the first N bytes from S2 to S1, stopping after
    copying a byte equal to the lower 8 bits C.  If memccpy() stops
    because a byte equal to C has been found, a pointer to the byte
    after the last destination byte (which is equal to C) is returned.
    If N bytes have been copied without finding a byte equal to C,
    NULL is returned.

  Return value:

    See above.

  See also: memchr(), memcpy(), memmove(), strcpy(), strncpy()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [C90]
#include <memory.h>     /* or this */

void *memchr (const void *s, int c, size_t n);

    Search the first N bytes at S for a byte equal to the lower 8 bits
    of C.  If a byte equal to C is found, a pointer to the first
    occurrence of C is returned.  If there is no such byte, NULL is
    returned.

  Return value:

    See above.

  See also: _memrchr(), strchr()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [C90]
#include <memory.h>     /* or this */

int memcmp (const void *s1, const void *s2, size_t n);

    Compare the first N bytes at S1 to the first N bytes at S2.  If
    the two buffers are identical (or if N is zero), 0 is returned.
    Otherwise, a value is returned which indicates the relationship of
    the first differing byte: a negative value means buffer S1 is
    lexically less than buffer S2, a positive value means buffer S1 is
    lexically greater than buffer S2.

  Return value:

    <0      S1 < S2

    =0      S1 = S2

    >0      S1 > S2

  See also: bcmp(), _memdif(), memicmp()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [emx]
#include <memory.h>     /* or this */

size_t _memcount (const void *mem, int c, size_t n);

    Count and return the number of occurrences of character C in the
    memory area of size N bytes pointed to by MEM.

  Return value:

    See above.

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [C90]
#include <memory.h>     /* or this */

void *memcpy (void *s1, const void *s2, size_t n);

    Copy memory.  Copy N bytes from S2 to S1.  The two regions must
    not overlap.  GCC generates in-line code for special applications
    of memcpy().  Use memmove() instead of memcpy() to copy
    overlapping regions of memory.

  Return value:

    memcpy() returns S1.

  See also: bcopy(), memmove()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [emx]
#include <memory.h>     /* or this */

size_t _memdif (const void *mem1, const void *mem2, size_t n);

    Compare the first N bytes pointed to by MEM1 to the first N bytes
    pointed to by MEM2.  If the two buffers are identical (or if N is
    zero), _MEMDIF_EQ is returned.  Otherwise, the byte offset of the
    first difference is returned.

  Return value:

    See above.

  See also: memcmp()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                    [PC]
#include <memory.h>     /* or this */

int memicmp (const void *s1, const void *s2, size_t n);

    Compare the first N bytes at S1 to the first N bytes at S2,
    ignoring letter case.  If the two buffers are identical (or if N
    is zero), 0 is returned.  Otherwise, a value is returned which
    indicates the relationship of the first differing byte: a negative
    value means buffer S1 is lexically less than buffer S2 (after
    conversion to lower case), a positive value means buffer S1 is
    lexically greater than buffer S2 (after conversion to lower case).

  Return value:

    <0      S1 < S2

    =0      S1 = S2

    >0      S1 > S2

  See also: memcmp(), tolower()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [C90]
#include <memory.h>     /* or this */

void *memmove (void *s1, const void *s2, size_t n);

    Copy memory.  Copy N bytes from S2 to S1.  The two regions may
    overlap.

  Return value:

    memmove() returns S1.

  See also: bcopy(), memcpy()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [emx]
#include <memory.h>     /* or this */

void *_memrchr (const void *s, int c, size_t n);

    Search the first N bytes at S for a byte equal to the lower 8 bits
    of C.  If a byte equal to C is found, a pointer to the last
    occurrence of C is returned.  If there is no such byte, NULL is
    returned.

  Return value:

    See above.

  See also: memchr(), strrchr()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [C90]
#include <memory.h>     /* or this */

void *memset (void *s, int c, size_t n);

    Fill memory.  Set N bytes at S to C.

  Return value:

    memset() returns S.

  See also: bzero()

------------------------------------------------------------------------------
#include <string.h>     /* use this */                                   [emx]
#include <memory.h>     /* or this */

void _memswap (void *s1, void *s2, size_t n);

    Swap two areas of memory of N bytes each, pointed to by S1 and S2.
    The two areas must not overlap.

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]

char *_mfclose (FILE *stream);

    Close a memory file.  A pointer to the buffer is returned.  On
    error, NULL is returned.  Use ftell() before calling _mfclose() to
    get the number of characters in the buffer.  If the BUF argument
    of _mfopen() was NULL, use free() to deallocate the buffer.

  Return value:

    See above.

  See also: _mfopen()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]

FILE *_mfopen (char *buf, const char *mode, size_t size, int inc);

    Open a memory file.  All output to a memory file goes to a buffer
    in memory.  The stream returned by _mfopen() can be used with
    fprintf(), fputc(), ftell() and fwrite().  If BUF is non-NULL,
    output goes to the array of SIZE bytes pointed to by BUF.  INC
    must be zero.  If BUF is NULL, output goes to a buffer allocated
    with malloc() and resized with realloc().  The initial size of the
    buffer is SIZE bytes (which can be zero).  INC must be non-zero.
    If INC is positive, the buffer size is increased by INC bytes
    whenever it is full.  If INC is -2, the buffer size is doubled
    whenever the buffer is full.  If SIZE is 0 and INC is -2, the
    initial buffer size is 512 bytes, the buffer will be allocated on
    the first output to the stream.  Currently, MODE must point to
    "wb".  On error, _mfopen() returns NULL.  Do not use fclose() on a
    stream created by _mfopen(), use _mfclose() instead.  Do not read
    from a stream created by _mfopen().

  Return value:

    _mfopen() returns a new stream.  On error, _mfopen() returns NULL.

  Restrictions:

    _fsetmode() doesn't work, newline characters written to the stream
    are not expanded to CR/LF.

  See also: _fassign(), fopen(), _mfclose(), sprintf()

  Example: See /emx/test/mftest.c

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

Heap_t _mheap (const void *mem);

    Return a pointer to the heap in which the memory block MEM has
    been allocated.  MEM must be the pointer obtained by calling
    calloc(), malloc(), realloc(), _tcalloc(), _tmalloc(),
    _trealloc(), _ucalloc(), _umalloc(), _utcalloc(), or _utmalloc().
    _mheap() returns NULL if MEM is NULL.  The return value of
    _mheap() is undefined if MEM points to a memory block which has
    been freed.  _mheap() may crash if MEM does not point to a memory
    block allocated by one of the functions listed above.

  Return value:

    _mheap() returns a pointer to the heap in which the memory block
    MEM has been allocated.  _mheap() returns NULL if MEM is NULL.

  See also: malloc(), _msize(), _ucreate(), _ucreate2(), _udefault(),
            _umalloc()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [BSD]

int mkdir (const char *name, long mode);

    Create a directory whose name is in the string pointed to by NAME.
    Only one directory can be created in one step, therefore all but
    the last component of the string pointed to by NAME must exist.
    MODE (containing the permission bits) is ignored.

  Return value:

    0       success

    -1      error

  See also: chdir(), rmdir()

------------------------------------------------------------------------------
#include <unistd.h>                                                      [BSD]

int mkstemp (char *string);

    Create a unique file name by modifying the string pointed to by
    STRING and open a file descriptor for that file using O_RDWR mode.
    Trailing X characters of the string pointed to by STRING are
    replaced by a letter followed by digits (the process ID).  There
    should be 6 trailing X characters.  Only 26 different file names
    per process can be created.

  Return value:

    On success, mkstemp() returns a file descriptor.  On failure,
    mkstemp() sets errno and returns -1.

  Hints:

    Note that the string pointed to by STRING will be modified; do not
    use a string constant!

    mkstemp() opens the file in text mode; use setmode() to switch the
    file descriptor to binary mode.

    mkstemp() avoids the race condition of mktemp(), however it is
    less portable than mktemp().

  See also: mktemp(), setmode(), tmpfile()

------------------------------------------------------------------------------
#include <unistd.h>                                                     [UNIX]

char *mktemp (char *string);

    Create a unique file name by modifying the string pointed to by
    STRING.  Trailing X characters of the string pointed to by STRING
    are replaced by a letter followed by digits (the process ID).
    There should be 6 trailing X characters.  Only 26 different file
    names per process can be created.

  Return value:

    On success, mktemp() returns STRING.  On failure, mktemp() returns
    NULL.

  Hints:

    Note that the string pointed to by STRING will be modified; do not
    use a string constant!

    Note that mktemp() is subject to a race condition: other threads
    of the same process may use the same temporary file name before
    you have a chance to create the temporary file.

  See also: mkstemp(), tempnam(), tmpfile(), tmpnam()

  Example:

    char tmp[20];
    
    strcpy (tmp, "exXXXXXX");
    if (mktemp (tmp) != NULL)
      {
        /* ... */
      }

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

time_t mktime (struct tm *t);

    Compute the number of seconds elapsed between 00:00:00 1-Jan-1970
    Coordinated Universal Time (UTC, GMT) and the time in the
    structure pointed to by T, interpreted as local time.  The tm_wday
    and tm_yday members of the structure are ignored.  The members of
    the structure are allowed to be out of range; mktime() modifies
    the structure to force the values to the usual ranges.  The
    tm_mday member is not set until the tm_mon and tm_year members
    have been adjusted.  The time in the structure is assumed to
    initially represent standard time if tm_isdst is zero.  The time
    in the structure is assumed to initially represent daylight saving
    time if tm_isdst is positive.  If tm_isdst is negative, mktime()
    determines whether daylight saving time is in effect for the
    specified time.  mktime() sets the tm_wday, tm_yday, and tm_isdst
    members of the structure as appropriate.

    See tzset() for a description of the TZ environment variable.

  Return value:

    mktime() returns the number of seconds elapsed between 00:00:00
    1-Jan-1970 UTC and the time in the structure pointed to by T.  If
    the time cannot be represented, mktime() returns -1 cast as
    time_t.

  Implementation-defined behavior:

    If tm_isdst is negative and the specified time is in the time gap
    between standard time and daylight saving time, mktime() assumes
    that daylight saving time is not in effect for the specified time.

  See also: gmtime(), localtime(), tzset()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double modf (double x, double *int_ptr);
long double modfl (long double x, long double *int_ptr);

    Split X into fractional part (which is returned) and integer part
    (which is stored to *INT_PTR).  Both the fractional and the
    integer part have the same sign as X.

    modfl() uses the long double format.

  Return value:

    modf() returns the fractional part of X.

  See also: ceil(), floor(), frexp(), rint(), trunc()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

size_t _msize (const void *mem);

    Return the size of the memory block MEM which has been allocated
    by one of the C library's memory allocation functions.  MEM must
    be the pointer obtained by calling calloc(), malloc(), realloc(),
    _tcalloc(), _tmalloc(), _trealloc(), _ucalloc(), _umalloc(),
    _utcalloc(), or _utmalloc().  _msize() returns zero if MEM is
    NULL.  The return value of _msize() is undefined if MEM points to
    a memory block which has been freed.

  Return value:

    _msize() returns the number of bytes allocated to MEM or zero if
    MEM is NULL.

  See also: _expand(), malloc(), _mheap(), _umalloc()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

double nextafter (double x, double y);
float nextafterf (float x, float y);
long double nextafterl (long double x, long double y);

    Return the next representable value after X, in the type of the
    function, in the direction of Y.

  Return value:

    Return Y if X==Y is true.  If both X and Y are NaNs, return one of
    them.  If X or Y is a NaN, return that NaN.  If Y is greater than
    X, return the smallest value in the type of the function that is
    greater than X.  If Y is smaller than X, return the greatest value
    in the type of the function that is smaller than X.

  See also: copysign(), fpclassify()

------------------------------------------------------------------------------
#include <sys/nls.h>                                                     [emx]

void _nls_init (void);

    Initialize the global variables _nls_tolower_tab,
    _nls_toupper_tab, and _nls_ctype_tab, which are used by
    _nls_tolower(), _nls_toupper(), _nls_strlwr(), _nls_strupr(), and
    _nls_is_dbcs_lead().  The tables are initialized appropriately for
    the current country code and code page.  _nls_init() is
    automatically called by the startup code, therefore you don't have
    to call _nls_init() unless you change the country code or the code
    page: _nls_init() should be called after changing the country code
    or code page.

  See also: _defext(), _fncmp(), _getext(), _getname(),
            _nls_is_dbcs_lead(), _nls_strlwr(), _nls_tolower(),
            _remext(), _splitpath()

------------------------------------------------------------------------------
#include <sys/nls.h>                                                     [emx]

int _nls_is_dbcs_lead (int c);

    This macro evaluates to a non-zero value if C is the lead byte of
    a DBCS character.  C must be an integer which is representable as
    unsigned char (that is, 0 through 255).  Note that C must not be
    EOF.

  Return value:

    _nls_is_dbcs_lead() returns zero if its argument is not a DBCS
    lead byte.  _nls_is_dbcs_lead() returns a non-zero value if its
    argument is a DBCS lead byte.

  See also: _nls_init(), _nls_strlwr(), _nls_strupr()

------------------------------------------------------------------------------
#include <sys/nls.h>                                                     [emx]

unsigned char *_nls_strlwr (unsigned char *string);
unsigned char *_nls_strupr (unsigned char *string);

    These functions convert all the characters of the string pointed
    to by STRING to lower case or upper case, respectively.  Accented
    characters etc. are converted as well, DBCS characters are not
    changed.

  Return value:

    _nls_strlwr() and _nls_strupr() return STRING.

  See also: _nls_init(), _nls_is_dbcs_lead(), _nls_tolower(),
            _nls_toupper()

------------------------------------------------------------------------------
#include <sys/nls.h>                                                     [emx]

unsigned char _nls_tolower (unsigned char c);
unsigned char _nls_toupper (unsigned char c);

    These macros convert the character C to lower case or upper case,
    respectively.  Accented characters etc. are converted as well.
    The result is undefined if C is a DBCS lead byte.

  Return value:

    _nls_tolower() returns its argument converted to lower case.
    _nls_toupper() returns its argument converted to upper case.

  See also: _nls_init(), _nls_strlwr(), _nls_strupr()

------------------------------------------------------------------------------
#include <stddef.h>                                                      [C90]

size_t offsetof (type, member);

    The offsetof() macro expands to an integral constant expression of
    type size_t.  The value of that expression is the offset in bytes
    from the beginning of the structure designated by TYPE to the
    structure member designated by MEMBER.

    The structure member must not be a bit-field.  Given the
    declaration

        static TYPE s;

    the expression

        &(s.MEMBER)

    must evaluate to an address constant.

  Return value:

    See above.

  Example:

    #include <stddef.h>
    
    struct sample
    {
      int a;
      struct
        {
          int b[2];
        } inner;
    };
    
    size_t offset_a  = offsetof (struct sample, a);
    size_t offset_b0 = offsetof (struct sample, inner.b[0]);
    size_t offset_b1 = offsetof (struct sample, inner.b[1]);

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>

int open (const char *name, int oflag);
int open (const char *name, int oflag, int pmode);

int open (const char *name, int oflag, unsigned long isize);
int open (const char *name, int oflag, int pmode, unsigned long isize);

    Open a file or device.  NAME points to the name of the file or
    device.  OFLAG contains one or more of the following values,
    combined by the | operator:

    O_RDONLY
            Open for reading.  Writing is not allowed

    O_WRONLY
            Open for writing.  Reading is not allowed

    O_RDWR  Open for reading and writing

    O_APPEND
            Move the file pointer to the end of file before any write
            operation takes place.  This is used for appending to a
            file

    O_CREAT
            Create the file if it does not exist.  If this flag is
            set, the PMODE argument is required

    O_TRUNC
            Truncate the size of the file to 0

    O_EXCL  Fail if the O_CREAT flag is used and the file already
            exists

    O_NONBLOCK and O_NDELAY
            Currently ignored

    O_BINARY
            Binary mode, no translation.  See below

    O_TEXT  Text mode, translate CR/LF to the newline character.  See
            below

    O_NOINHERIT
            Child processes won't inherit the file handle

    O_SYNC  Write operations are synchronous, that is, write() waits
            until file data has been physically written

    O_SIZE  Set the initial size of the file to ISIZE if the file is a
            new file (O_CREAT) or an existing file truncated
            (O_TRUNC).  If this flag is set, the ISIZE argument is
            required.  O_SIZE is ignored under DOS

    If a new file is created, PMODE (modified by the umask value), is
    used to set the file permissions.  S_IREAD grants read access,
    S_IWRITE grants write access.  S_IREAD is ignored (DOS and OS/2
    limitation).  To grant both read and write access, use
    S_IREAD|S_IWRITE.

    There are two additional OFLAG flags: O_TEXT for text mode,
    O_BINARY for binary mode.  Text mode, which is the default,
    translates each CR/LF pair to a newline character on input and
    translates newline characters to CR/LF pairs on output.  If the
    last character of a file is Ctrl-Z, it is discarded on input.
    Binary mode disables these transformations.

    If the file or device cannot be opened, open() sets errno and
    returns -1.  If open() succeeds, the file handle is returned.  The
    file handle is always greater than -1.

    The mode O_TRUNC|O_RDONLY is not implemented.  A Ctrl-Z at the end
    of the file is removed only when opening a file for appending in
    text mode.  Ctrl-Z at the end of the file is obsolete, anyway.

    The file is opened in the sharing mode SH_DENYNO, see sopen().

  Return value:

    open() returns a file handle for the file.  On error, open() sets
    errno and returns -1.

  Implementation-defined behavior:

    O_SIZE is an emx extension.  It's the caller's responsibility to
    truncate the file if its size should be less than ISIZE bytes.
    O_SIZE is ignored under DOS.

  Restrictions:

    Under DOS, the O_NOINHERIT flag is currently ignored for child
    processes which are DOS programs (vs.  emx programs).  Under DOS,
    the O_SYNC and O_SIZE flags are ignored.

  See also: close(), fcntl(), fdopen(), ftruncate(), sopen()

------------------------------------------------------------------------------
#include <sys/types.h>                                               [POSIX.1]
#include <dirent.h>             /* this is recommended */
#include <sys/dir.h>            /* this also works (for now) */

DIR *opendir (char *name);
int closedir (DIR *dirp);
struct dirent *readdir (DIR *dirp);
void seekdir (DIR *dirp, long off);
long telldir (DIR *dirp);
void rewinddir (DIR *dirp);

    Scan directories.  opendir() opens the directory whose name is in
    the string pointed to by NAME for scanning.  If there is an error,
    NULL is returned.  Otherwise a value is returned which is used
    with the other functions to continue the scanning.

    closedir() ends the directory scan of DIRP.  After closing DIRP,
    you must not use DIRP.  You should close all handles created by
    opendir().

    readdir() retrieves the next directory entry for DIRP.  If there
    are no more directory entries, NULL is returned.

    seekdir() moves to the specified directory entry of DIRP.  If OFF
    is 0, the first directory entry will be read next.  If OFF is 1,
    the second directory entry will be read next.  And so on.
    seekdir() is not a POSIX.1 function.

    telldir() returns the current position in DIRP.  0 is returned for
    the first directory entry.  telldir() is not a POSIX.1 function.

    rewinddir() is equivalent to seekdir (0).

    These functions use _fnlwr() to convert the file names to lower
    case on upper-case-only file systems.

  Return value:

    opendir() returns a descriptor to be used with the other
    functions.  On error, opendir() returns NULL.

    closedir() returns 0 if successful, -1 on error.

    readdir() returns a pointer to a directory entry.  If there are no
    more directory entries, readdir() returns NULL.

    telldir() returns the current position in DIRP.

  See also: _fnlwr(), _wildcard()

------------------------------------------------------------------------------
#include <sys/hw.h>                                                    [emx *]

void _outp8 (unsigned port, unsigned value);
void _outp16 (unsigned port, unsigned value);
void _outp32 (unsigned port, unsigned value);

    These functions write a single byte or word to a hardware port.
    _outp8() writes the byte VALUE to PORT, _outp16() writes the
    16-bit word VALUE to PORT, _outp32() writes the 32-bit word VALUE
    to PORT.

    You have to call _portaccess() first to enable access to a range
    of ports.  To make your program work under DOS, you have to use
    emx option -ai, see `Using emx options'.  Under OS/2, your program
    requires emxio.dll in a directory listed in LIBPATH.

  See also: _portaccess(), _inp8(), _outps8()

------------------------------------------------------------------------------
#include <sys/hw.h>                                                    [emx *]

void _outps8 (unsigned port, const unsigned char *src, unsigned count);
void _outps16 (unsigned port, const unsigned short *src, unsigned count);
void _outps32 (unsigned port, const unsigned short *src, unsigned count);
void _outps8dac (unsigned port, const unsigned char *src, unsigned count);

    These functions write multiple bytes or words to a hardware port.
    _outps8() writes COUNT bytes from the array pointed to by SRC to
    PORT.  _outps16() writes COUNT 16-bit words from the array pointed
    to by SRC to PORT.  _outps32() writes COUNT 32-bit words from the
    array pointed to by SRC to PORT.

    The COUNT argument of _outps8() must not exceed 65535.

    The array pointed to by SRC of _outps16() must be aligned on a
    16-bit boundary, that is, the address must be even.  COUNT must
    not exceed 32768.

    The array pointed to by SRC of _outps32() must be aligned on a
    32-bit boundary, that is, the address must be a multiple of four.
    COUNT must not exceed 65536.

    _outps8dac() is a slowed-down version of _outps8() suitable for
    writing to the VGA palette registers.

    You have to call _portaccess() first to enable access to a range
    of ports.  To make your program work under DOS, you have to use
    emx option -ai, see `Using emx options'.  Under OS/2, your program
    requires emxio.dll in a directory listed in LIBPATH.

  See also: _portaccess(), _inps8(), _outp8()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

int _path (char *dst, const char *name);

    Find an executable file.  If the string pointed to by NAME
    contains a colon, a slash or a backslash, only that name will be
    tried.  If the string pointed to by NAME does not contain colons,
    slashes or backslashes, the file will be sought in the directories
    listed in the EMXPATH and PATH environment variables.  If the file
    is not found, the empty string will be stored to the array pointed
    to by DST, errno will be ENOENT and -1 will be returned.  If the
    file is found, the path name will be copied to the array pointed
    to by DST and 0 will be returned.  No default extension is used.

  Return value:

    See above.

  See also: getenv(), _searchenv()

------------------------------------------------------------------------------
#include <unistd.h>                                                  [POSIX.1]

long pathconf (const char *path, int name);
long fpathconf (int handle, int name);

    Return the current value of the configurable limit or option NAME
    associated with the file or directory associated with HANDLE or
    whose name is in the string pointed to by PATH.  NAME is one of
    the following constants:

    _PC_LINK_MAX
            corresponds to LINK_MAX (maximum value of a file's link
            count)

    _PC_MAX_CANON
            corresponds to MAX_CANON (maximum number of bytes in a
            terminal canonical input line)

    _PC_MAX_INPUT
            corresponds to MAX_INPUT (maximum number of bytes for
            which space will be available in a terminal input queue)

    _PC_NAME_MAX
            corresponds to NAME_MAX (maximum number of bytes in a file
            name)

    _PC_PATH_MAX
            corresponds to PATH_MAX (maximum number of bytes in a path
            name)

    _PC_PIPE_BUF
            corresponds to PIPE_BUF (maximum number of bytes that can
            be written atomically to a pipe)

    _PC_CHOWN_RESTRICTED
            corresponds to _POSIX_CHOWN_RESTRICTED (see POSIX.1 for
            details)

    _PC_NO_TRUNC
            corresponds to _POSIX_NO_TRUNC (path name components
            longer than NAME_MAX generate an error)

    _PC_VDISABLE
            corresponds to _POSIX_VDISABLE (terminal special
            characters can be disabled using this character value, if
            it is defined)

    See POSIX.1 for more details.

  Return value:

    If NAME is invalid, pathconf() and fpathconf() set errno to EINVAL
    and return -1.  If the value associated with NAME has no limit for
    the path or handle, pathconf() and fpathconf() return -1 without
    changing errno.  If the implementation needs to use PATH or HANDLE
    to determine the value of NAME and the implementation does not
    support the association of NAME with the file specified by PATH or
    HANDLE, respectively, or if HANDLE is an invalid file descriptor,
    pathconf() and fpathconf() set errno and return -1.  Otherwise,
    pathconf() and fpathconf() return the current value of the
    variable.

  Restrictions:

    pathconf() and fpathconf() currently return just the POSIX.1
    minimum values.

  See also: sysconf()

------------------------------------------------------------------------------
#include <signal.h>                                                     [UNIX]

int pause (void);

    Wait until a signal is received.  The process is suspended until
    delivery of a signal for which a signal handler is installed.
    pause() returns after the signal handler returns.

    The process will be terminated (and pause() won't return) if an
    uncaught signal is delivered which terminates the process.

  Return value:

    pause() returns -1 and sets errno to EINTR (if it returns at all).

  Restrictions:

    pause() is not implemented under DOS.

  See also: alarm(), kill(), raise(), sigaction(), signal(),
            sigsuspend()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

int pclose (FILE *stream);

    Close a pipe created by popen().  pclose() waits until the child
    process started by popen() ends and then closes STREAM.  The
    termination status of the child process is returned.  See wait()
    for details about the return value.

  Return value:

    0       success

    -1      error

  Restrictions:

    pclose() is not implemented under DOS.

  See also: popen(), wait()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

void perror (const char *string);

    Print an appropriate error message for the current errno value to
    stderr.  If STRING is NULL or points to the empty string "", just
    the error message is printed.  Otherwise, the string pointed to by
    STRING and a colon precede the error message.

  See also: errno, strerror(), sys_errlist, sys_nerr

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int pipe (int *two_handles);

    Create an unnamed pipe.  The handle used for reading from the pipe
    is stored to TWO_HANDLES[0], the handle used for writing to the
    pipe is stored to TWO_HANDLES[1].  Both handles are in text mode;
    use setmode() if you want to switch to binary mode.

  Return value:

    0       success

    -1      error

  Restrictions:

    pipe() is implemented for OS/2 only.

  See also: close(), dup(), popen(), setmode()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

FILE *popen (const char *command, const char *mode);

    Start a child process and connect one end of a pipe to it.
    popen() runs the command whose name is in the string pointed to by
    COMMAND by starting a command processor.  See system() for details
    on locating and running the command processor.  MODE must point to
    a string starting with r or w.  If the string starts with r,
    standard output of the command will be redirected, you can get the
    output by reading from the stream returned by popen().  If the
    mode string starts with w, standard input of the command will be
    redirected, you can send data to the command by writing to the
    stream returned by popen().  Append b for binary mode or t for
    text mode to the mode string.  The default is text mode, see also
    fopen().  If an error occurs, popen() returns NULL.  Otherwise,
    popen() returns a stream which is connected to the local end of
    the pipe.  Use pclose() to close the stream.

  Return value:

    popen() returns a new stream.  On error, popen() returns NULL.

  Restrictions:

    popen() is not implemented under DOS.

  See also: pclose(), pipe(), system()

------------------------------------------------------------------------------
#include <sys/hw.h>                                                      [emx]

int _portaccess (unsigned first, unsigned last);

    Gain access to hardware ports.  To access hardware ports, you have
    to call _portaccess().  FIRST is the address of the first port,
    LAST is the address of the last port.  emx option -ai must be used
    to enable _portaccess() under DOS, see `Using emx options'.

    _portaccess() always succeeds under OS/2.

  Return value:

    0       success

    -1      error

  See also: _memaccess(), _inp8(), _outp8(), _wait0()

  Example: See /emx/test/hw_io.c

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double pow (double x, double y);
long double powl (long double x, long double y);

    Raise X to the power of Y and return the result.  If pow() is
    undefined for a given pair of X and Y, pow() returns an
    implementation-defined value and sets errno to EDOM.  On overflow,
    pow() returns HUGE_VAL and sets errno to ERANGE.

    pow() returns 1.0 for all values of X if Y is zero.

    powl() uses the long double format.

  Return value:

    pow() returns X^Y.

  See also: cbrt(), exp(), ldexp(), log(), sqrt()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int printf (const char *format, ...);

    printf() performs formatted output to the stdout stream.  On
    success, the number of characters written to stdout is returned.
    Otherwise, EOF is returned.

    Characters in the string pointed to by FORMAT are copied
    unmodified to the destination unless a format specification is
    hit.  A format specification has the following format:

        %[<flags>][<width>][.<precision>][<size>]<type>

    where items in brackets are optional.  For each format
    specification an argument of the specified type is taken from the
    argument list, is formatted according to the format specification
    and written to the destination.  To include one percent sign in
    the output, put two percent signs (%%) into the FORMAT string.

    A <flag> character can be specified to modify the formatting.  The
    following <flags> characters are available:

    -

        Left-justify the converted value in the field.  Without this
        flag, the value is right-justified.  The value will be padded
        with blanks on the right (note that - overrides 0).  If - is
        not given, the value is padded on the left with blanks or
        zeros, according to the 0 flag and the <type>.

    +

        Always insert sign (+ or -) for the conversion of a signed
        number (that is, <type> being d, e, E, f, g, G or i).  + is
        ignored for all other conversions.  + overrides space.  If +
        is not specified, the sign is printed only for negative
        numbers and for -0.0.

    space

        Insert a space if the conversion of a signed number (that is,
        <type> being d, e, E, f, g, G or i) doesn't start with a sign
        (+ or -).  For all other conversions, space is ignored.  If
        both + and space are given, space is ignored.

    0

        Pad numbers with '0' characters instead of blanks.  This flag
        is ignored for non-numeric conversions, if - is used, or if
        <precision> is given.

    #

        Use alternate conversion.  For the o conversion, the precision
        will be increased to force the first digit of the result to be
        a zero.  For the x and X conversions, the number will be
        prefixed with 0x unless it is zero.  For the e, E, f, g and G
        conversions, a decimal point will always be printed, even if
        no digits follow it.  For the g and G conversions, trailing
        zeros are not removed.

    If the length of the converted value is less than <width>, it is
    padded with blanks or '0' characters.  Unless the - flag is used,
    the field is padded on the left.  Padding is done with zeros for
    numeric conversions if the 0 flag is given, the - flag is not
    given and <precision> is not given.  Otherwise, blanks are used
    for padding.  If the length of the converted value is greater than
    <width>, the field is not truncated.  <width> is either a decimal
    number or a * character.  In the latter case, the width is taken
    from the argument list.

    <precision> specifies the number of decimal digits after the
    decimal point of a floating point number when using the e, E or f
    conversions.  For the g and G conversions, <precision> specifies
    the maximum number of significant digits.  The number will be
    rounded according to <precision> for the floating point
    conversions.  For the d, i, o, u, x and X conversions, <precision>
    specifies the minimum number of digits to print.  If the number
    has less digits, it will be padded with zeros on the left.  If the
    precision is 0 and the integer is 0, no output will be produced
    for this field (except for the o conversion if the # flag is
    given).  For the s conversion, <precision> specifies the maximum
    string length.  For all other conversions, <precision> is ignored.
    <precision> is either a decimal number or a * character.  In the
    latter case, the precision is taken from the argument list.  If a
    decimal point without <precision> is given, the precision will be
    0.

    <size> is either h for a short type (h is available for the d, i,
    o, u, x, and X conversions and for n) or l for a long type (l is
    available for the d, i, o, u, x, and X conversions and for n) or L
    for the long double type (L is available for the e, E, f, g, and G
    conversions).  If <size> is not specified, the default size is
    used.

    <type> (the conversion type) is one of the following characters:

    c

        Character.  The argument (char, signed char, unsigned char or
        int) is converted to an unsigned char and that character code
        will be printed.  <size> is ignored.

    d

        Signed decimal number.  The argument is converted to a signed
        integer and printed in decimal notation.  Use %hd to print a
        short int, %ld to print a long int and %Ld to print a
        long long int.

    e

        Floating-point number (double), using e as exponent sign:
        -#.###e+##.  There's exactly one digit before the decimal
        point.  The number of digits after the decimal point is
        specified by <precision>.  If <precision> is missing, 6 digits
        are printed after the decimal point.  If <precision> is zero,
        no decimal point is printed unless the # flag is given.  The
        exponent has at least 2 digits.  If the number is zero, the
        exponent is 00.  The decimal point character of the current
        locale is used.  A NaN is printed as `nan', infinity as `inf'.

    E

        Floating-point number (double); same as e, except for E being
        used instead of e to introduce the exponent, and `NAN' and
        `INF' being printed instead of `nan' and `inf', respectively.

    f

        Floating-point number (double) printed in fixed-point format.
        The number of digits after the decimal point is specified by
        <precision>.  If <precision> is missing, 6 digits are printed.
        If <precision> is specified as zero, no decimal point is
        printed unless the # flag is given.  There's always at least
        one digit before the decimal point.  The decimal point
        character of the current locale is used.  A NaN is printed as
        `nan', infinity as `inf'.

    F

        Floating-point number (double); same as f, except for `NAN'
        and `INF' being printed instead of `nan' and `inf',
        respectively.

    g

        Floating-point number (double).  The number is printed in
        exponential or fixed-point format, depending on the magnitude.
        If the number is an integer, it is printed as integer, without
        decimal point (unless the # flag is used).  If the exponent
        (of e format output) is less than -4 or greater than
        <precision> (the default is 6), type e is used.  Otherwise,
        type f is used.  In both cases, trailing zeros (and the
        decimal point, if it isn't followed by any digits) will be
        removed unless the # flag is used.  <precision> specifies the
        number of significant digits to print.  If <precision> is
        missing, 6 significant digits are printed.  If <precision> is
        zero, a precision of 1 will be used instead.  The decimal
        point character of the current locale is used.  A NaN is
        printed as `nan', infinity as `inf'.

    G

        Floating-point number (double); same as g, except for E being
        used instead of e to introduce the exponent, and `NAN' and
        `INF' being printed instead of `nan' and `inf', respectively.

    i

        Signed decimal number.  Same as d.

    n

        Store the number of characters formatted up to this point in
        the FORMAT string (int *).  This `conversion' does not create
        any output.  Use %hn when passing a pointer to a short int,
        %ln when passing a pointer to a long int and %Ln when passing
        a pointer to a long long int.

    o

        Unsigned octal number.  The argument is converted to an
        unsigned integer and printed in octal notation.  Use %ho to
        print an unsigned short int, %lo to print an unsigned long int
        and %Lo to print an unsigned long long int.  If the # flag is
        given, the precision will be increased to force the first
        digit of the result to be a zero.  If the number is zero and
        the precision is zero (after taking the # flag into account),
        the result will be empty.

    p

        Pointer (void *).  The output format of a pointer is
        implementation-dependent.  In this implementation, p is
        equivalent to x.

    s

        String (char *).  Print characters of the string until a null
        character is reached or <precision> (if specified) is
        exhausted.  If <precision> is not specified, the string must
        have a terminating null character.  If <precision> is
        specified, the string length is limited by <precision>.

    u

        Unsigned decimal number.  The argument is converted to an
        unsigned integer and printed in decimal notation.  Use %hu to
        print an unsigned short int, %lu to print an unsigned long int
        and %Lu to print an unsigned long long int.

    x

        Unsigned hexadecimal number.  The argument is converted to an
        unsigned integer and printed in hexadecimal notation, using
        lower-case letters.  Use %hx to print an unsigned short int,
        %lx to print an unsigned long int and %Lx to print an
        unsigned long long int.  If the # flag is given and the number
        is non-zero, 0x is prepended.

    X

        Hexadecimal number (unsigned int); same as x, except for
        upper-case letters being used instead of lower-case letters.

    The behavior for other <type> characters is undefined, except for
    % immediately following %.

  Return value:

    printf() returns the number of characters written to stdout.  On
    error, printf() returns EOF.

  Implementation-defined behavior:

    The # flag is ignored for the c, d, i, n, p, s and u conversions.

    <size> can be L for the long long type (L is available for the d,
    i, o, u, x, and X conversions and for n).  ll is an alternate
    spelling for L.

  Restrictions:

    The output could be more accurate for floating point values.

  Hints:

    Note that %lf is not a valid conversion specifier, use %f instead.
    Contrast with scanf().

  See also: fopen(), fwrite(), _itoa(), scanf(), setlocale(),
            strftime()

  Example:

    int year, month, day;
    ...
    printf ("%d/%.2d/%.2d\n", year, month, day);

------------------------------------------------------------------------------
#include <unistd.h>                                                   [UNIX *]

int profil (void *buff, unsigned bufsiz, unsigned offset, unsigned scale);

    Sampling profiler.  This function is very experimental, therefore
    no documentation is provided.  profil() might disappear in the
    future.

  Return value:

    0       success

    -1      error

  Implementation-defined behavior:

    The sampling frequency is 1024Hz under DOS, 1000Hz under OS/2.
    Counters are 32-bit words (under Unix, counters usually are 16-bit
    words).

  Restrictions:

    When an attempt to update a counter causes an exception, the
    program will be terminated (under OS/2) or the system will be
    stopped (under DOS).

    Under OS/2, SCALE must be 0x4000, 0x8000, or 0x10000.

    Under OS/2, profil() uses an unsupported and undocumented OS/2 API
    which has several bugs and may be dropped in future versions.  It
    has been tested on OS/2 3.0 only.

    profil() is not available with the system call library sys.lib
    (-Zsys).

------------------------------------------------------------------------------
#include <sys/ptrace.h>                                               [SysV *]

int ptrace (int request, int pid, int addr, int data);

    Debug a child process.  The child process is identified by PID.
    The following REQUEST codes are defined:

    PTRACE_TRACEME
            Not implemented -- use spawn (P_DEBUG) instead

    PTRACE_PEEKTEXT
            Read a 32-bit word from the text space of the child
            process.  ADDR is the address of the word.  The word at
            ADDR is returned.

    PTRACE_PEEKDATA
            See PTRACE_PEEKTEXT.  On machines with separate data and
            text space, this request will read from the data space.

    PTRACE_PEEKUSER
            Read a 32-bit word from the process table of the child
            process.  This can be used to read the registers of the
            child process.  See <sys/user.h> for details.

    PTRACE_POKETEXT
            Write the 32-bit word DATA to address ADDR of the text
            space of the child process.

    PTRACE_POKEDATA
            See PTRACE_POKETEXT.  On machines with separate data and
            text space, this request will write to the data space.

    PTRACE_POKEUSER
            Write a 32-bit word to the process table of the child
            process.  This can be used to alter the registers of the
            child process.  See <sys/user.h> for details.  Not all
            registers can be modified.

    PTRACE_RESUME
            Resume the child process.  All pending signals will be
            canceled.  If DATA is non-zero, the child process will
            continue as if it had received that signal.  The child
            process will run until another signal occurs.

    PTRACE_EXIT
            Kill the child process.

    PTRACE_STEP
            Execute the next instruction of the child process.  All
            pending signals will be canceled.  If DATA is non-zero,
            the child process will continue as if it had received that
            signal.  If _UF_PTRACE_MULTITHREAD is selected and PID
            includes a thread ID, one instruction of that thread only
            will be executed.  Otherwise, one instruction of any of
            the ready threads will be executed.

    PTRACE_SESSION
            If DATA is 0, select the session of the calling process.
            If DATA is 1, select the child session.  If DATA is 2, the
            child session is automatically selected by the next
            PTRACE_STEP (on CALL instructions only) or PTRACE_RESUME
            command.  This request is emx specific and is ignored
            under DOS.

    PTRACE_NOTIFICATION
            Return the last notification and store data associated
            with that notification to the buffer pointed to by ADDR.
            DATA is the size of the buffer.  If ADDR is NULL or if the
            size is too small, data won't be stored.  See below for
            notification codes and data structures.  This request is
            emx specific and is ignored under DOS.

    PTRACE_CONT
            Continue after a notification has been reported.  The
            previous PTRACE_RESUME or PTRACE_STEP request will be
            continued.  This request is emx specific and is ignored
            under DOS.

    PTRACE_THAW
            Thaw (enable) the thread identified by PID (which contains
            both a process ID and a thread ID).  This request is emx
            specific and is ignored under DOS.

    PTRACE_FREEZE
            Freeze (disable) the thread identified by PID (which
            contains both a process ID and a thread ID).  Note that an
            attempt to apply PTRACE_STEP to a frozen thread will
            result in an error.  This request is emx specific and is
            ignored under DOS.

    PTRACE_ATTACH
            Attach a debugger to the process identified by PID.  That
            process must be a direct or indirect child process of a
            process started with the P_DEBUGDESC flag set (see
            spawn*()) and the debugger process debugging the direct
            parent process of the process identified by PID must still
            exist (and must continue to exist while the process
            identified by PID is being debugged).  For each process of
            this kind, at most one process (debugger) can attach to
            that process.

    PTRACE_DETACH
            Detach a debugger from the process identified by PID.
            That process must have been attached to with PTRACE_ATTACH
            by the same process.  ADDR must be either 0 or 1.  If ADDR
            is 0, the process identified by PID will remain stopped
            (allowing another process to attach).  If ADDR is 1, the
            process identified by PID will resume execution.  The
            debugger process debugging the direct parent process of
            the process identified by PID must continue to exist
            during the entire lifetime of the process identified by
            PID, otherwise that process will be terminated prematurely
            or may block.

    If _UF_PTRACE_NOTIFY or _UF_PTRACE_MULTITHREAD has been set with
    _uflags(), ptrace() will report creation and termination of
    threads and loading and freeing of modules (DLLs).  If a
    notification is pending, wait() and waitpid() report the child
    process as having been stopped by SIGPTRACENOTIFY.  In that case,
    use the PTRACE_NOTIFICATION request of ptrace() to get more
    information.  If successful, the PTRACE_NOTIFICATION request of
    ptrace() will report one of the following values:

    PTN_THREAD_NEW
            Creation of a new thread.  To obtain the thread ID, pass a
            pointer to an object of type struct ptn_thread in ADDR.
            That structure is defined as follows:

                struct ptn_thread
                {
                  unsigned tid;
                  unsigned long reserved[31];
                };

            The tid member will be set to the thread ID.  Creation of
            the initial thread (thread 1) is also reported.

    PTN_THREAD_END
            Termination of a thread.  To obtain the thread ID, pass a
            pointer to an object of type struct ptn_thread in ADDR.
            The tid member of that structure will be set to the thread
            ID.  Termination of the initial thread (thread 1) is also
            reported.

    PTN_MODULE_LOAD
            Loading of a module.  To obtain the module handle and the
            full path name of the module, pass a pointer to an object
            of type struct ptn_module in ADDR.  That structure is
            defined as follows:

                struct ptn_module
                {
                  unsigned long hmte;
                  unsigned long text_start;
                  unsigned long text_size;
                  unsigned long data_start;
                  unsigned long data_size;
                  unsigned long bss_start;
                  unsigned long bss_size;
                  unsigned long flags;
                  unsigned long reserved[24];
                  char name[260];
                };

            The hmte member will be set to the module handle.  The
            text_start member will be set to the start address of the
            text segment, the text_size member will be set to the size
            of the text segment.  The data_start member will be set to
            the start address of the initialized data segment, the
            data_size member will be set to the size of the
            initialized data segment.  The bss_start member will be
            set to the start address of the uninitialized data
            segment, the bss_size member will be set to the size of
            the uninitialized data segment.  The flags member will
            have zero or more of the following flags set: PTNMOD_DLL
            means that the module is a DLL (otherwise, it's the
            executable file of the program being debugged),
            PTNMOD_AOUT means that the module has been created with ld
            and emxbind (otherwise, it has been created with LINK386).
            The name member will be set to the full path name of the
            module.

    PTN_MODULE_FREE
            Free a module (DLL).  To obtain the module handle and the
            full path name of the DLL, pass a pointer to an object of
            type struct ptn_module in ADDR.  The hmte member of that
            structure will be set to the module handle, the name
            member will be set to the full path name of the DLL.

    PTN_PROC_NEW
            Descendant process started.  This notification occurs only
            for processes started with the P_DEBUGDESC flag of
            spawn*() and for child processes of such processes.  The
            notification is reported to the debugger process debugging
            the parent process of the new process.  To obtain the
            process ID and the full path name of the executable file
            of the descendant process, pass a pointer to an object of
            type struct ptn_proc in ADDR.  That structure is defined
            as follows:

                struct ptn_proc
                {
                  unsigned pid;
                  unsigned long flags;
                  unsigned long fork_addr;
                  unsigned long reserved[29];
                  char name[260];
                };

            The pid member of that structure will be set to the
            process ID of the descendant.  The flags member will have
            zero or more of the following flags set: PTNPROC_FORK
            means that the descendant has been created with fork(),
            PTNPROC_AOUT means that the executable file has been
            created with ld and emxbind (otherwise, it has been
            created with LINK386).  If PTNPROC_FORK is set, fork_addr
            will contain the return address of the __fork() system
            call, that is, the address at which the parent and child
            processes will continue.  If that address cannot be
            determined (should not happen), fork_addr will be zero.
            The name member will be set to the full path name of the
            executable file.

            The descendant process will block until a debugger process
            attaches to the descendant process with PTRACE_ATTACH.  To
            let the descendant process continue without being
            debugged, apply PTRACE_ATTACH and then PTRACE_DETACH to
            the descendant process.  If the descendant process has
            been created with fork(), the parent process also blocks
            until the startup code of the descendant process has been
            executed.

    If _UF_PTRACE_MULTITHREAD has been selected with _uflags(),
    ptrace() supports debugging of multithread procdesses.  In that
    case, the PID argument of ptrace() contains both a process ID and
    a thread ID.  The PTRACE_PEEKUSER, PTRACE_POKEUSER, and
    PTRACE_STEP requests apply to the specified thread only.
    Moreover, wait() and waitpid() will return both a process ID and a
    thread ID.  The following macros are used to deal with combined
    process IDs and thread IDs:

    PTRACE_GETPID
            Extract the process ID from the value passed as argument.

    PTRACE_GETTID
            Extract the thread ID from the value passed as argument.

    PTRACE_PIDTID
            Build the PID argument for ptrace(): the first argument is
            the process ID, the second argument is the thread ID.

  Return value:

    See above.  As -1 is a legal return value for the PTRACE_PEEK
    requests, you should set errno to 0 before calling ptrace() and
    check errno after the call.

  Restrictions:

    Under DOS, a process can debug only one child process.  ptrace()
    is not available with the system call library sys.lib (-Zsys).
    Under OS/2, the only signal number which can be passed in DATA for
    PTRACE_RESUME and PTRACE_STEP is the one of the signal by which
    the child process has been stopped.  Notifications, multithread
    processes, and debugging of descendants are not supported under
    DOS.  PTRACE_ATTACH works only under certain circumstances defined
    above.

  See also: spawn*(), _uflags(), wait(), waitpid()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int putc (int c, FILE *stream);

    Write the character C (converted to an unsigned char) to the
    output stream STREAM and advance the file position indicator of
    the stream (if defined).

    putc() may be implemented as macro, in contrast to fputc().  In
    consequence, putc() may evaluate its arguments more than once.

  Return value:

    putc() returns the character written.  On error, putc() sets the
    error indicator of the stream and returns EOF.

  Implementation-defined behavior:

    putc() is implemented as in-line function for single-thread
    programs.

  Hints:

    Use putc() instead of fputc() if you want to write a lot of
    characters.

    The arguments of putc() should not be expressions with side
    effects.

  See also: fputc(), putchar()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int putchar (int c);

    putchar (c) is equivalent to putc (c, stdout).

  Return value:

    putchar() returns the character written.  On error, putchar() sets
    the error indicator of stdout and returns EOF.

  Implementation-defined behavior:

    putchar() is implemented as in-line function for single-thread
    programs.

  Hints:

    Use putchar() instead of fputc() if you want to write a lot of
    characters to stdout.

    The argument of putchar() should not be an expression with side
    effects.

  See also: fputc(), putc()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [BSD]

int putenv (const char *string);

    Put a value into the environment of the calling process.  STRING
    is a pointer to a string of the form

        "NAME=VALUE"

    where NAME is the name of the environment variable and VALUE is
    the value of the environment variable.  If the environment
    variable NAME already exists, the current value is replaced by the
    new value, VALUE.  If NAME is not already in the environment,
    STRING is put into the environment.  Do not free or reuse the
    string pointed to by STRING after calling putenv().  Using an auto
    variable is also a bad idea.  After calling putenv(), do not use
    the ENVP argument of main().  Use environ instead.

  Return value:

    0       success

    -1      error

  See also: getenv()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int puts (const char *string);

    Write the string pointed to by STRING followed by a newline (LF)
    character (which is translated to CR/LF if stdout is in text mode)
    to the stdout stream.

  Return value:

    On failure, puts() returns EOF.  Otherwise, puts() returns a
    non-negative value.

  See also: fputs(), fgets()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

int putw (int x, FILE *stream);

    Write the word (int) X to STREAM and return it.  Avoid using this
    function.

  Return value:

    putw() returns X.  On error, getw() returns -1.  As -1 is also a
    possible word value, you have to use ferror() to recognize an
    error condition.

  See also: getw(), fwrite()

------------------------------------------------------------------------------
#include <stdlib.h> /* use this */                                       [C90]
#include <search.h> /* or this */

void qsort (void *base, size_t num, size_t width,
            int (*compare)(const void *x1, const void *x2));

    Sort an array.  BASE is a pointer to the beginning of the array.
    The array contains NUM elements of WIDTH bytes each.  COMPARE is
    called to compare the two elements pointed to by X1 and X2.
    COMPARE should return a negative value, if element X1 is less than
    element X2, zero, if element X1 equals element X2, and a positive
    value if element X1 is greater than element X2.

    Note: qsort() is not stable: the order of equal elements is
    undefined.  To make qsort() stable, add a field to the sort key
    which holds the index of the element.

------------------------------------------------------------------------------
#include <signal.h>                                                      [C90]

int raise (int sig);

    Generate the signal SIG.  If the signal SIG is blocked, the signal
    will be made pending, to be delivered when it is unblocked.

    Each thread has its own set of signal handlers.  raise() generates
    the signal in the thread in which it is called.  Use kill() to
    send the signal to the main thread (thread 1).

    See section 4 for details on signal processing.

  Return value:

    If successful, raise() returns 0.  Otherwise -1 is returned and
    errno is set.

  Errors:

    EINVAL  SIG is not a valid signal number

  See also: abort(), kill(), sigaction(), signal()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

int rand (void);
void srand (unsigned int seed);

    rand() returns a pseudo-random number in the range 0 through
    RAND_MAX (32767).  RAND_MAX is defined in <stdlib.h>.  srand()
    initializes the sequence of random numbers.  The initial SEED
    value (if srand() is not called) is 1.

    The quality of the random numbers generated by rand() is poor,
    though it is not as poor as in other implementations of rand().
    If you need good random numbers, you should use random(), which is
    in the BSD library.

    In programs linked with the multithread libraries (-Zmt, -Zmts, or
    -Zmtd), rand() will generate identical sequences of random numbers
    in all the threads and srand() will affect only the thread in
    which it is called.  The behavior of rand() is undefined in
    multithread programs linked with single-thread libraries.

    You must not call rand() or srand() in a thread created by
    DosCreateThread.

  Return value:

    See above.

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int read (int handle, void *buf, size_t nbyte);

    Read up to NBYTE characters from file HANDLE to the buffer BUF.
    The number of characters read is returned.  If there is an error,
    -1 is returned.  The return value may be less than NBYTE.  For
    instance, this happens if the end of the file is reached.  See
    also `General terminal interface'.  If HANDLE is 0 and HANDLE
    refers to the keyboard and O_NONBLOCK (alias O_NDELAY) has been
    set with fcntl() for HANDLE and the IDEFAULT and ICANON bits have
    been reset with ioctl() for HANDLE, -1 is returned and errno is
    set to EAGAIN if the call to read() would block.  Even if there is
    some data available, but not enough with respect to VMIN, -1 is
    returned.

    If HANDLE has been opened in text mode, CR/LF pairs are translated
    to newline characters and a Ctrl-Z character is discarded if it is
    the last character of the file.

  Return value:

    See above.

  See also: open(), setmode(), write()

------------------------------------------------------------------------------
#include <stdlib.h>                                                    [emx *]
#include <sys/kbdscan.h>  /* optional, for extended scan codes */

int _read_kbd (int echo, int wait, int sig);

    Get a character from the keyboard.  Extended codes are preceded by
    a null character (call _read_kbd() again!), the scan codes are
    defined in <sys/kbdscan.h>.  If ECHO is non-zero, input will be
    echoed, if WAIT is non-zero, _read_kbd() will wait until a
    character is available, if WAIT is zero and no character is
    available, _read_kbd() will return -1, if SIG is zero, Ctrl-C will
    be ignored.  Examples (taken from <conio.h>):

        #define getch()  _read_kbd (0, 1, 0)
        #define getche() _read_kbd (1, 1, 0)

    Please use the general terminal interface instead.

    It's important to call _read_kbd() again if _read_kbd() returns 0.
    To see what happens if you don't, type Ctrl-S F10 under DOS.

  Return value:

    See above.

  See also: ioctl(), read()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

void *realloc (void *mem, size_t size);

    Reallocate the block of memory pointed to by MEM, making it big
    enough to hold SIZE bytes.  If MEM is NULL, a new block of memory
    is allocated by calling malloc().  Otherwise, MEM must be a
    pointer returned by calloc(), malloc(), realloc(), _ucalloc(),
    _umalloc(), or _utcalloc().  In this case, the size of the block
    pointer to by MEM is changed to SIZE.  If the block pointed to by
    MEM cannot be expanded in-place, it is moved.  If MEM is non-NULL
    and SIZE is zero, the block is freed and NULL is returned.  A
    pointer to the new, resized block of memory is returned.  If there
    is not enough memory available, NULL is returned.

  Return value:

    realloc() returns MEM (if the block could be resized without
    moving), a pointer to a newly allocated block of memory, or NULL
    (if there wasn't enough memory, or if MEM is non-NULL and SIZE is
    zero).

  Implementation-defined behavior:

    Some implementations of realloc() can be applied to blocks freed
    by free() as long as calloc(), malloc(), and realloc() have not
    been called since freeing the block.  This implementation of
    realloc() cannot be applied to freed blocks.

    If MEM is not NULL and the block cannot be moved, realloc() will
    allocate the new block in MEM's heap.  If MEM is NULL, realloc()
    will allocate memory from the default heap of the current thread.

  See also: malloc(), _mheap(), _trealloc(), _udefault()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _remext (char *path);

    Remove the extension from the file name pointed to by PATH.  If
    the last member of the string starts with a dot
    ("/usr/mattes/.profile", for instance) the string isn't modified.

    _remext() properly handles DBCS characters.

  See also: _defext(), _getext(), _nls_init(), _splitpath()

------------------------------------------------------------------------------
#include <stdio.h>      /* use this */                                   [C90]
#include <io.h>         /* or this */

int remove (const char *name);

    Delete a file.  NAME is a pointer to a string containing the name
    of the file to be deleted.  Under OS/2 and DOS, remove() and
    unlink() are equivalent.

  Return value:

    0       success

    -1      error

  Implementation-defined behavior:

    If the read-only attribute of the file is set, remove() sets errno
    to EPERM and returns -1.

    If the file is open in any process, remove() sets errno to EACCES
    and returns -1.

  See also: unlink()

------------------------------------------------------------------------------
#include <stdio.h>      /* use this */                                   [C90]
#include <io.h>         /* or this */

int rename (const char *old_name, const char *new_name);

    Rename the file or directory whose name is in the string pointed
    to by OLD_NAME to the name pointed to by NEW_NAME.  Moving a file
    to a different directory on the same drive is possible.  If a file
    or directory with the name pointed to by NEW_NAME already exists,
    rename() fails.

  Return value:

    0       success

    -1      error

  Implementation-defined behavior:

    If the file is open in any process, rename() sets errno to EACCES
    and returns -1.

  Restrictions:

    rename() may set errno to EACCES instead of EEXIST if a file or
    directory with the name pointed to by NEW_NAME already exists.
    (Why does OS/2 return ERROR_ACCESS_DENIED instead of
    ERROR_FILE_EXISTS?)

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _response (int *argcp, char ***argvp);

    Expand response files.  If you want response files (@filename, the
    file filename contains a list of arguments, one per line) to be
    expanded, call

        _response (&argc, &argv);

    at the beginning of main().  Response file arguments enclosed in
    double quotes won't be expanded.  If a response file cannot be
    opened, the argument is kept unchanged.

  See also: _envargs(), main(), _wildcard()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

void rewind (FILE *stream);

    Move the file pointer of STREAM to the beginning of the file and
    clear the error and end-of-file indicators.

  See also: fseek()

------------------------------------------------------------------------------
#include <strings.h>                                                     [BSD]

char *rindex (const char *string, int c);

    Return a pointer to the last occurrence of the character C in the
    null-terminated string pointed to by STRING.  If there is no
    character C in the string pointed to by STRING, NULL is returned.
    If C is 0, a pointer to the terminating null character of the
    string pointed to by STRING is returned.

  Return value:

    See above.

  See also: index(), strrchr()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

double rint (double x);
long double rintl (long double x);

    Return as floating-point number the integer that is nearest to X.
    rint (X) is even if there's a tie, that is if

    rintl() uses the long double format.

        fabs (rint (X) - X) == 0.5

  Return value:

    See above.

  See also: ceil(), floor(), trunc()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [BSD]

int rmdir (const char *name);

    Remove the directory whose name is in the string pointed to by
    NAME.  Only one directory is removed in one step.  If the
    directory (or a subdirectory thereof) is the current working
    directory of a process, it cannot be removed.

  Return value:

    0       success

    -1      error

  See also: mkdir()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

int _rmtmp (void);

    Close and delete the files created by tmpfile() in the current
    working directory.  It must be used only in the directory in which
    tmpfile() created the temporary files.

  Return value:

    _rmtmp() returns the number of closed (and deleted) files.

  See also: tmpfile()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

int _rmutex_available (_rmutex *sem);

    Check if the _rmutex semaphore pointed to by SEM is available or
    owned, without changing the state of the semaphore and without
    blocking.  Return zero if the semaphore is owned, return a
    non-zero value if the semaphore is available.  Note that
    _rmutex_available() just returns a snapshot of the state of the
    semaphore; in presence of other threads or, in case of a shared
    semaphore, other processes, the state may change at any time, even
    before _rmutex_available() returns.  This function can be used to
    avoid deadlock.

  Return value:

    _rmutex_available() returns a non-zero value if the semaphore is
    available.  _rmutex_available() returns 0 if the semaphore is
    owned.  The return value is undefined if the object pointed to by
    SEM has not been initialized by _rmutex_create().

  See also: _fmutex_available(), _rmutex_close(), _rmutex_create(),
            _rmutex_open(), _rmutex_release(), _rmutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

unsigned _rmutex_close (_rmutex *sem);
void _rmutex_checked_close (_rmutex *sem);

    Close an _rmutex semaphore.  SEM should point to an _rmutex object
    initialized by _rmutex_create().  If there have been N calls to
    _rmutex_open() for this semaphore, N+1 calls to _rmutex_close()
    are required to destroy the semaphore, one call for
    _rmutex_create() and one call per _rmutex_open().  The semaphore
    can no longer be used after it has been destroyed.

    _rmutex_checked_close() does not return an error code; it calls
    abort() on failure.

  Return value:

    _rmutex_close() returns 0 if successful.  Otherwise,
    _rmutex_close() returns an OS/2 error code defined in <os2.h> such
    as ERROR_INVALID_HANDLE.  Under DOS, _rmutex_close() always
    returns 0.

  See also: abort(), atexit(), _fmutex_close(), _rmutex_available(),
            _rmutex_create(), _rmutex_open(), _rmutex_release(),
            _rmutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

unsigned _rmutex_create (_rmutex *sem, unsigned flags);
void _rmutex_checked_create (_rmutex *sem, unsigned flags);

    Create an _rmutex semaphore.  SEM points to the _rmutex object to
    be initialized.  The semaphore is local to the process if FLAGS is
    0.  The semaphore can be shared by multiple processes if FLAGS is
    _FMC_SHARED.  A shared _rmutex semaphore must be located in shared
    memory (that is, SEM must point to an object in shared memory).

    _rmutex_checked_create() does not return an error code; it calls
    abort() on failure.

  Return value:

    _rmutex_create() returns 0 if successful.  Otherwise,
    _rmutex_create() returns an OS/2 error code defined in <os2.h>
    such as ERROR_TOO_MANY_HANDLES.  Under DOS, _rmutex_create()
    always returns 0.

  See also: abort(), _fmutex_create(), _rmutex_available(),
            _rmutex_close(), _rmutex_dummy(), _rmutex_open(),
            _rmutex_release(), _rmutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

void _rmutex_dummy (_rmutex *sem);

    Create a dummy _rmutex semaphore.  SEM points to the _rmutex
    object to be initialized.  Behavior is undefined if ownership of a
    dummy _rmutex semaphore is requested when the semaphore is owned.
    _rmutex_close() must not be called on a dummy _rmutex semaphore.

  See also: _fmutex_dummy(), _rmutex_create()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

unsigned _rmutex_open (_rmutex *sem);
void _rmutex_checked_open (_rmutex *sem);

    Open an _rmutex semaphore.  SEM should point to an _rmutex object
    initialized by _rmutex_create().  _rmutex_open() is used to obtain
    access to a shared _rmutex semaphore created by another process.
    All threads of the process which called _rmutex_create() have
    access to the semaphore without calling _rmutex_open().  Call
    _rmutex_close() when you no longer need access to the semaphore.

    _rmutex_checked_open() does not return an error code; it calls
    abort() on failure.

  Return value:

    _rmutex_open() returns 0 if successful.  Otherwise, _rmutex_open()
    returns an OS/2 error code defined in <os2.h> such as
    ERROR_INVALID_HANDLE.  Under DOS, _rmutex_open() always returns 0.

  See also: abort(), atexit(), _fmutex_open(), _rmutex_available(),
            _rmutex_close(), _rmutex_create(), _rmutex_release(),
            _rmutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

unsigned _rmutex_release (_rmutex *sem);
void _rmutex_checked_release (_rmutex *sem);

    Relinquish ownership of the _rmutex semaphore pointed to by SEM.
    If another thread blocks in _rmutex_request() for this semaphore,
    _rmutex_release() will unblock one of the blocking threads.  The
    semaphore should be owned when _rmutex_release() is called.
    Though not strictly necessary, ownership of the semaphore should
    have been requested by the same thread.

    _rmutex_checked_release() does not return an error code; it calls
    abort() on failure.  Note that _rmutex_checked_release() is slower
    than _rmutex_release() because it is not inlined.

  Return value:

    _rmutex_release() returns 0 if successful.  Otherwise,
    _rmutex_release() returns an OS/2 error code defined in <os2.h>
    such as ERROR_TOO_MANY_HANDLES.

  See also: abort(), __cxchg(), _fmutex_release(),
            _rmutex_available(), _rmutex_close(), _rmutex_create(),
            _rmutex_open(), _rmutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/fmutex.h>
#include <sys/rmutex.h>

unsigned _rmutex_request (_rmutex *sem, unsigned flags);
void _rmutex_checked_request (_rmutex *sem, unsigned flags);

    Request ownership of the _rmutex semaphore pointed to by SEM.  If
    FLAGS is 0, _rmutex_request() returns ERROR_INTERRUPT if
    interrupted by a signal while blocking.  FLAGS is zero or a set of
    flags combined with the | operator.  If FLAGS includes
    _FMR_IGNINT, _rmutex_request() does not return if a signal occurs
    while blocking.  If FLAGS includes _FMR_NOWAIT and the semaphore
    is owned, _rmutex_request() returns immediately ERROR_MUTEX_OWNED.

    _rmutex_checked_request() does not return an error code; it calls
    abort() on failure.  Note that _rmutex_checked_request() is slower
    than _rmutex_request() because it is not inlined.

    If the semaphore is available, it will be set to owned and
    _rmutex_request() will return immediately.  If the semaphore is
    owned, _rmutex_request() will block while the semaphore is owned.
    When _rmutex_release() is called for the semaphore, one of the
    threads blocking in _rmutex_request() for this semaphore will wake
    up and gain ownership of the semaphore.

    Note that ownership of an _rmutex semaphore is not tied to a
    thread, that is, it's not a thread which owns the semaphore.  This
    is in contrast to OS/2's mutex semaphores (HMTX).  Deadlock will
    occur if _rmutex_request() is called twice for the same semaphore
    by the same thread without an intervening call to
    _rmutex_release().  This fact is important to keep in mind in
    presence of signals.  Signal handlers must not request semaphores
    which can be owned by the interrupted code.  You might want to
    block signals before requesting ownership of an _rmutex semaphore.

  Return value:

    _rmutex_request() returns 0 if successful.  Otherwise,
    _rmutex_request() returns an OS/2 error code defined in <os2.h>
    such as ERROR_INTERRUPT.

  Restrictions:

    Under DOS, _rmutex_request() and _rmutex_checked_request() crash
    if the semaphore is already owned.

  See also: abort(), __cxchg(), _fmutex_request(),
            _rmutex_available(), _rmutex_close(), _rmutex_create(),
            _rmutex_open(), _rmutex_release()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [UNIX]

void *sbrk (int incr);

    Change memory allocation by INCR bytes.  If INCR is positive, the
    memory limit is increased.  If INCR is negative, the memory limit
    is decreased.  On success, sbrk() returns the previous memory
    limit.  Otherwise, -1 cast as pointer is returned and errno set to
    ENOMEM.  Please don't use sbrk() -- use malloc() instead for
    memory allocation.

    If non-contiguous memory allocation with monotonous addresses
    (_UF_SBRK_MONOTONOUS) has been enabled with _uflags(), sbrk() may
    allocate non-contiguous memory.  In that case, sbrk() with
    non-negative argument returns the base address of the newly added
    memory area.  Any memory in the gap between the previous memory
    limit and the base address returned by sbrk() is not accessible.
    Setting back the memory limit into a gap is not possible.  If
    non-contiguous memory allocation with arbitrary addresses
    (_UF_SBRK_ARBITRARY) has been enabled with _uflags(), sbrk() may
    allocate non-contiguous memory; the memory object may even be at a
    lower address than the previous one.  In both cases, at most one
    memory object can be deallocated with sbrk() at a time, that is,
    you cannot reset the break address with sbrk() to an address
    outside the most recently allocated memory object.  However, you
    can deallocate the most recently allcoated memory object by
    resetting the break address to the start of the that memory
    object; after doing so, sbrk(0) will return the break address of
    the memory object which became the top one.

    Currently, there are some restrictions when using a non-contiguous
    memory: emxbind cannot create a preloaded executable with more
    than one heap object.  fork() fails if there is more than one heap
    object.

  Return value:

    See above.

  See also: brk(), fork(), malloc(), _uflags(), ulimit()

  Example:

    /* Allocate memory with sbrk().  This function fails if sbrk()
       does not return contiguous memory.  Return a pointer to the
       new memory area.  Return NULL on error.  This function assumes
       that no other thread calls sbrk(). */
    
    void *more_memory (size_t n)
    {
      oid *prev, *base;
    
      if ((int)n < 0)               /* Check for overflow */
        return NULL;
      prev = sbrk (0);              /* Get current memory limit */
      if (prev == (void *)-1)
        return NULL;                /* Error */
      base = sbrk ((int)n);         /* Allocate memory */
      if (base == (void *)-1)
        return NULL;                /* Error */
      if (prev != base)             /* Non-contiguous? */
        {
          sbrk (-(int)n);           /* Free non-contiguous memory */
          return NULL;              /* Failure */
        }
      return base;                  /* Success */
    }

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int scanf (const char *format, ...);

    The stdin stream is read and input is parsed according to the
    format string pointed to by FORMAT.  For each field in the format
    string there must be a pointer to the location receiving the
    value.  The pointers are passed after the FORMAT argument.

    Whitespace (any number of spaces) in the format string matches
    whitespace (any number of spaces, including zero) in the input.
    All other characters except for % are compared to the input.
    Parsing ends when a mismatch is encountered.  %% in the format
    string matches % in the input.  A % which is not followed by
    another % or the end of the string starts a field specification.
    The field in the input is interpreted according to the field
    specification.  For most field types, whitespace is ignored at the
    start of a field.  Field specifications have the format

        %[*][<width>][<size>]<type>

    where items in brackets are optional.  If the * is present, the
    value is not assigned.  No pointer will be fetched from the
    argument list and the value is ignored.

    <width> is a positive integral decimal number specifying the
    maximum field width.  At most this many characters are read for
    this field.

    <size> is either h for a short type (h is available for the d, i,
    o, u, and x conversions and for n), l for a long type (l is
    available for the d, i, o, u, and x conversions and for n) or the
    double type (l is also available for the e, f, and g conversions)
    or L for the long double type (L is available for the e, f, and g
    conversions).  If <size> is omitted, the default size is used.

    <type> is one of the following characters:

    c

        Character (char).  Whitespace is not skipped.  If a field
        width is specified, that many characters are read and
        assigned, without a terminating null character (char[]).  If
        no field width is specified, one character will be read and
        assigned.

    d

        Signed decimal integer (int).  %hd is used for short int, %ld
        is used for long int and %Ld is used for long long int.

    e f g E F G

        Floating-point number (float).  %le etc. is used for double,
        %Le etc. is used for long double.  scanf() accepts the same
        format of float-point numbers as strtod().  The decimal point
        character of the current locale is used.

    i

        Decimal, octal or hexadecimal signed integer (int).  %hi is
        used for short int, %li is used for long int and %Li is used
        for long long.  The base is 16 if the number begins with 0x or
        0X.  The base is 8 if the number begins with 0 (not followed
        by an x or X).  Otherwise, the base is 10.

    n

        Number of characters read so far (int).  No input is taken.
        The number of characters read so far is assigned to the
        integer (unless assignment is suppressed with the * flag).
        Use %hn to assign to a short int, %ln to assign to a long int
        or %Ln to assign to a long long int.

    o

        Octal unsigned integer (unsigned).  %ho is used for
        unsigned short, %lo is used for unsigned long int and %Lo is
        used for unsigned long long int.  The input may contain a sign
        character.

    p

        Pointer (void *).  The input format of a pointer is
        implementation-dependent.  In this implementation, p is
        equivalent to x.

    s

        Read and assign characters until the field width is exhausted
        or hitting whitespace (char[]).  The destination array must be
        big enough to hold all the characters.  Note that initial
        whitespace is skipped.  Perhaps you want to use %[...] instead
        of %s.

    u

        Unsigned decimal integer (unsigned int).  %hu is used for
        unsigned short int, %lu is used for unsigned long int and %Lu
        is used for unsigned long long int.  The input may contain a
        sign character.

    x

        hexadecimal integer (unsigned int).  %hx is used for
        unsigned short int, %lx is used for unsigned long int and %Lx
        is used for unsigned long long int.  The input may contain a
        sign character.

    [

        Null-terminated string (char[]).  White space is not skipped.
        [ is followed by a set of characters which is delimited by ].
        The field ends at the first character not in the character set
        [...].  If [^...] is used, the field ends at the first
        character in that set.  The field also ends when the field
        width is exhausted.  The set contains all characters listed in
        the brackets.  To include a ] in the set, make it the first
        character of the set.  You can specify a range of characters
        by listing the first and the last character, separated by a -.
        To include a - in the set, make it the last character of the
        set.  The destination array must be big enough to hold all the
        characters.

    scanf() puts back into the stream at most one conflicting
    character.  In consequence, some character sequences acceptable to
    strtod(), strtof(), strtol(), strtold(), and strtoul() are not
    acceptable to scanf().

  Return value:

    If successful, scanf() returns the number of fields converted.  On
    error, scanf() returns EOF.

  Implementation-defined behavior:

    <size> can be L for long long types (L is available for the d, i,
    o, u, and x conversions and for n)).

  Hints:

    To read user input, you should use fgets() and sscanf() instead of
    scanf() because scanf() doesn't stop reading at the end of the
    line.

    Use %lf for variables of type double.  Contrast with printf().

  See also: fgets(), fread(), fscanf(), printf(), setlocale(),
            sscanf(), strptime(), strtod(), strtol(), vscanf()

  Example:

    int year, month, day;
    ...
    if (scanf ("%d/%d/%d", &year, &month, &day) == 3)
      {
        ...
      }

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _scrsize (int *dst);

    Retrieve the screen (window) size.  The number of text columns
    (width) is stored to DST[0], the number of text rows (height) is
    stored to DST[1].

  See also: v_dimen()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

void _searchenv (const char *name, const char *var, char *path);

    Search a file in the directories listed in an environment
    variable.  First, the file name pointed to by NAME is tried as is.
    If that file does not exist, the directories listed in the
    environment variable whose name is in the string pointed to by VAR
    are searched.  If the file is found, the constructed path name
    (either the string pointed to by NAME or a directory plus the
    string pointed to by NAME) will be copied to the array pointed to
    by PATH.  If the file is not found, the empty string will be
    stored to the array pointed to by PATH.

    _searchenv() properly handles DBCS characters.

  See also: getenv(), _nls_init(), _path()

------------------------------------------------------------------------------
#include <io.h>                                                          [emx]

int _seek_hdr (int handle);

    Move the file pointer of HANDLE to the a.out header of an
    executable file (a.out or bound .exe).  _seek_hdr() assumes that
    the file pointer points to the beginning of the header (ie, the
    beginning of the file).  If no header is found, the file pointer
    will be repositioned to the original position.

  Return value:

    0       success

    -1      error (errno is set)

  See also: _fseek_hdr()

------------------------------------------------------------------------------
#include <sys/select.h>                                               [UNIX *]

int select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
            struct timeval *timeout);

    Wait for a file handle to become ready for reading, writing, or
    until an exceptional situation exists for a file handle, or until
    a time-out expires.  `Ready for reading' means that a call to
    read() in blocking mode (O_NONBLOCK not being set) will return
    immediately, that is, will transfer data and return a positive
    number, will transfer no data and return zero, or will report an
    error (except EAGAIN alias EWOULDBLOCK) by returning -1.  `Ready
    for writing' means that a call to write() in blocking mode will
    return immediately, that is, will transfer data and return a
    positive number, will transfer no data and return zero, or will
    report an error (except EAGAIN alias EWOULDBLOCK) by returning -1.
    `Exceptional situations' means pending errors for sockets.  No
    other exceptional situations are currently defined.

    select() returns as soon as any handle in the set pointed to by
    READFDS is ready for reading, or a handle in the set pointed to by
    WRITEFDS is ready for writing, or an exceptional situation exists
    for a handle in the set pointed to by EXCEPTFDS.  READFDS,
    WRITEFDS, and EXCEPTFDS can each be NULL.  If TIMEOUT is NULL,
    select() waits indefinitely.  Otherwise, waiting terminates after
    the time-out pointed to by TIMEOUT expired.  NFDS is the number of
    handles to be checked.

    select() updates the objects pointed to by READFDS, WRITEFDS, and
    EXCEPTFDS to include only the handles which are ready for reading,
    writing, or for which an exceptional situation exists,
    respectively, and returns the number of those handles.

    Some implementations of select() update the object pointed to by
    TIMEOUT to reflect the amount of time remaining.  The emx
    implementation of select() currently doesn't do this and probably
    won't do this.

    The following macros are available for handling the bitstrings
    used by select():

    FD_ZERO(S)

        clear all bits of S

    FD_SET(N,S)

        set bit N in S

    FD_CLR(N,S)

        clear bit N in S

    FD_ISSET(N,S)

        return a non-zero value iff bit N is set in S

    The FD_SETSIZE macro specifies the number of file handles in an
    fd_set object.  The default value is 256.  To increase the number
    of file descriptors in fd_set, define FD_SETSIZE before including
    <sys/types.h> and <sys/select.h>.  The FD_ZERO macro and
    assignment of fd_set objects use the size of the object; in
    consequence, you must be careful when passing pointers to fd_set
    objects between modules which have been compiled with different
    values for FD_SETSIZE (libraries!).

    select() is implemented for the following types of handles:

    - Standard input handles (keyboard) with IDEFAULT not set (DOS:
      handle 0 only).  Note that if ICANON is set, read() has to wait
      until the line is completed.  If IDEFAULT is set (that's the
      initial setting), standard input handles are reported as being
      ready

    - Pseudo TTYs of xf86sup.sys

    - Named pipes.  Named pipes are always reported to be ready for
      writing

    - Pipes created with pipe() by programs using emx.dll; such pipes
      are always reported to be ready for writing

    - Sockets

    - All file handles under DOS; regular files are reported to be
      ready for reading if the file pointer is not at the end of the
      file -- this behavior may change in the future: regular files
      should be reported to be always ready for reading

    All handle types not supported by select() are reported to be
    ready for reading and ready for writing and having no exceptional
    situation pending.

    The timeval structure is defined as follows:

        struct timeval
        {
          long tv_sec;
          long tv_usec;
        };

    tv_sec and tv_usec are the number of seconds and microseconds,
    respectively.

  Return value:

    >0      number of ready handles

    0       time out

    -1      error

  Restrictions:

    select() is not available with the system call library sys.lib
    (-Zsys).

  See also: ioctl(), pipe()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int setbuf (FILE *stream, char *buffer);

    Associate the buffer of size BUFSIZ pointed to by BUFFER with
    STREAM.  This must be done before the file has been read or
    written.  If BUFFER is NULL, the file is unbuffered.  You should
    use setvbuf() instead.

  Return value:

    0       success

    EOF     error

    BSD setbuf() seems to have an int return value, therefore emx
    setbuf() has an int return value.  This should not break programs
    which expect void setbuf().

  See also: setbuffer(), setvbuf()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

int setbuffer (FILE *stream, char *buffer, size_t size);

    Associate the buffer of size SIZE pointed to by BUFFER with
    STREAM.  This must be done before the file has been read or
    written.  If BUFFER is NULL, the file is unbuffered.  You should
    use setvbuf() instead.

  Return value:

    0       success

    EOF     error

    BSD setbuffer() seems to have an int return value, therefore emx
    setbuffer() has an int return value.  This should not break
    programs which expect void setbuffer().

  See also: setvbuf()

------------------------------------------------------------------------------
#include <setjmp.h>                                                      [C90]

int setjmp (jmp_buf here);

    Save the current stack context in HERE and return 0.  Later, you
    can continue at this point by calling longjmp().  When execution
    continues at setjmp() after calling longjmp(), the second argument
    of longjmp() is returned, which is always non-zero (if zero is
    used as second argument of longjmp(), it will be turned into 1).

    setjmp() may be implemented as macro.  setjmp() can be used only
    in the following contexts:

    - the entire controlling expression of a do, if, switch, or while
      statement

    - the operand to the ! operator if the resulting expression is the
      entire controlling expression of one of the statements listed
      above

    - the operand of a relational or equality operator if the
      resulting expression is the entire controlling expression of one
      of the statements listed above and the other operand is an
      integral constant expression

    - the entire expression of an expression statement.

  Return value:

    setjmp() returns 0 when directly called.  When returning from a
    call to longjmp(), setjmp() returns a non-zero value (supplied by
    the call to longjmp()).

  Implementation-defined behavior:

    The restrictions on the contexts in which setjmp() can be used do
    not apply.

  Hints:

    As jmp_buf is an array type, the & operator need not be applied.

  See also: longjmp(), siglongjmp(), sigsetjmp()

------------------------------------------------------------------------------
#include <locale.h>                                                      [C90]

char *setlocale (int category, const char *locale);

    Select a locale.  Either the entire locale or a portion of the
    locale is set, depending on CATEGORY:

    LC_ALL

        Set the entire locale, including categories LC_COLLATE,
        LC_CTYPE, LC_MONETARY, LC_NUMERIC and LC_TIME.

    LC_COLLATE

        Control the behavior of strcoll() and strxfrm().

    LC_CTYPE

        Control the behavior of isalnum(), isalpha(), iscntrl(),
        isgraph(), islower(), isprint(), ispunct(), isspace(),
        isupper(), tolower(), toupper(), mblen(), mbstowcs(),
        mbtowc(), wcstombs() and wctomb().  This also affects the
        interpretation of multibyte character format strings by
        printf(), scanf() and strftime().  Note that isdigit() and
        isxdigit() are not affected.

    LC_MONETARY

        Set the information related to formatting of monetary
        quantities.  This affects the contents of the structure
        returned by localeconv().

    LC_NUMERIC

        Select the decimal point character for atof(), _atofl(),
        gcvt(), printf(), scanf(), strtod(), strtof(), and strtold().
        Set the information related to formatting of numeric
        quantities.  This affects the contents of the structure
        returned by localeconv().

    LC_TIME

        Control the behavior of strftime().

    If LOCALE points to the empty string "", the value of the
    environment variable LANG is taken instead.  If LANG is not set,
    "C" is used for LOCALE.  "C" is the initial locale at program
    startup.  It provides the usual C conversions.

    Other possible values of LOCALE are LC_C_FRANCE, LC_C_GERMANY,
    LC_C_ITALY, LC_C_SPAIN, LC_C_UK, LC_C_USA, "de_de", "en_us", and
    "en_gb".

    If LOCALE is a null pointer, a pointer to the string associated
    with CATEGORY for the currently selected locale is returned.  That
    string can be used as LOCALE with CATEGORY for restoring that
    locale.  If CATEGORY is LC_ALL and different locale strings are
    associated with the categories, a pointer to a string is returned
    which selects those locales when used with LC_ALL.

    All threads of a process share the same locale.

  Return value:

    setlocale() returns NULL on error.  Otherwise, it returns a
    pointer to the string associated with CATEGORY for the new locale
    (or the current one if LOCALE is NULL).  The string must not be
    modified by the program; it may be overwritten by a subsequent
    call to setlocale().

  Restrictions:

    Currently, information associated with LC_COLLATE and LC_CTYPE is
    ignored.  Moreover, strftime() always assumes that code page 850
    is in effect.

  See also: isupper(), localeconv(), mbtowc(), strcoll(), strftime(),
            strxfrm()

------------------------------------------------------------------------------
#include <io.h>                                                           [PC]
#include <fcntl.h>

int setmode (int handle, int mode);

    Change the text/binary mode of a file handle.  MODE must be either
    O_BINARY or O_TEXT.

    Note: Use _fsetmode() to change the mode of a stream.

  Return value:

    If there's an error, setmode() returns -1 and sets errno to EBADF
    or EINVAL otherwise setmode() returns the previous mode, that is,
    O_BINARY or O_TEXT.

  See also: _fsetmode(), open()

------------------------------------------------------------------------------
#include <sys/time.h>                                                    [BSD]

int settimeofday (const struct timeval *tp, const struct timezone *tzp);

    Set the system time and timezone.  If TP is not NULL, the system
    time is set to the time (Coordinated Universal Time) specified by
    the structure pointed to by TP.  If TZP is not NULL, the timezone
    is set according to the structure pointed to by TZP.

    The timeval structure is defined as follows:

        struct timeval
        {
          long tv_sec;
          long tv_usec;
        };

    tv_sec and tv_usec are the number of seconds and microseconds,
    respectively, elapsed since 00:00:00 1-Jan-1970 UTC.

  Return value:

    0       success

    -1      error

  Restrictions:

    Setting the timezone is not implemented, TZP must be a null
    pointer.  The real time clock is not set under DOS versions
    earlier than 3.3.

  See also: gettimeofday(), ftime(), time()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int setvbuf (FILE *stream, char *buffer, int mode, size_t size);

    Set the buffering mode of STREAM to MODE.  The array of SIZE bytes
    pointed to by BUFFER may be used instead of a buffer allocated by
    setvbuf() if BUFFER is not NULL.  Available modes are:

    _IONBF  the file is unbuffered, BUFFER and SIZE are always ignored

    _IOFBF  the file is full buffered

    _IOLBF  the file is line buffered

    The file must not have been read or written since it was opened.

  Return value:

    On success, setvbuf() returns 0.  On failure, setvbuf() returns a
    non-zero value.

  Implementation-defined behavior:

    This implementation of setvbuf() uses BUFFER unless MODE is _IONBF
    or SIZE is invalid.  If SIZE is invalid, a buffer of BUFSIZ bytes
    is used.

    For reading a file, _IOFBF and _IOLBF are equivalent.  Each time a
    newline character is written to a line-buffered file, the buffer
    is flushed.  The buffer is also flushed if it becomes full while
    writing.  The buffer is filled by reading from the disk file (or
    device) if the buffer becomes empty while reading.

  See also: fflush(), fputs(), fwrite()

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigaction (int sig, const struct sigaction *iact,
               struct sigaction *oact);

    Examine and/or specify the action associated with the signal SIG.
    If IACT is not NULL, it points to a structure specifying the
    action to be associated with the signal SIG.  If IACT is NULL, the
    action for signal SIG won't be changed.  If OACT is not NULL, the
    previous action for signal SIG will be stored to the object
    pointed to by OACT.

    The sigaction structure is defined as follows:

        struct sigaction
        {
          void (*sa_handler)(int sig);
          sigset_t sa_mask;
          int sa_flags;
        };

    sa_handler can be SIG_DFL (to get the default action), SIG_IGN (to
    ignore the signal), or the address of a signal-catching function
    (signal handler).

    sa_mask is a set of signals to be blocked prior to calling the
    signal-catching function.  sa_mask is ignored for the `emx' and
    `System V' signal models.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

    sa_flags is a set of flag bits used to modify the behavior of the
    signal SIG.  The following flag bits are available:

    SA_NOCLDSTOP
            Do not generate SIGCHLD when a child process stops.

    SA_SYSV
            Use the `System V' signal model for the signal SIG: before
            calling a signal-catching function, reset the signal
            action to SIG_DFL, don't block the signal, and ignore
            sa_mask.

    SA_ACK  Use the `emx' signal model for the signal SIG: ignore
            sa_mask, use SIG_ACK for unblocking the signal.

    In a multithread program, sigaction() examines and sets the signal
    action for the thread in which it is called.  Signal action
    settings are private to each thread.

    If the previous signal action for signal SIG has been set by
    signal(), the value of the object pointed to by OACT is
    unspecified; however, if that object is subsequently used for
    setting the signal action with sigaction(), handling of the signal
    is as if the original call to signal() were repeated.

    See section 4 for details on signal processing.

  Return value:

    If successful, sigaction() returns 0.  Otherwise sigaction() sets
    errno and returns -1.

  Errors:

    EINVAL  SIG is not a valid signal number or an attempt was made to
            catch a signal that cannot be caught or to ignore a signal
            that cannot be ignored.

  Implementation-defined behavior:

    The SA_ACK and SA_SYSV flag bits of sa_flags are emx extensions.

  Restrictions:

    The SA_NOCLDSTOP flag bit of sa_flags is ignored as stopped
    processes are not supported (except for ptrace()).

  See also: raise(), kill(), sigemptyset(), signal(), sigpending(),
            sigprocmask()

  Example:

    void sig_cleanup (int signo)
    {
      cleanup ();
      printf ("Process terminated by signal %d\n", signo);
      exit (99);
    }
    
    void sig_init (void)
    {
      struct sigaction sa;
    
      sa.sa_handler = sig_cleanup;
      sa.sa_flags = 0;
      sigemptyset (&sa.sa_mask);
      sigaction (SIGINT, &sa, NULL);
    }

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigaddset (sigset_t *set, int sig);
int sigdelset (sigset_t *set, int sig);

    sigaddset() adds the signal SIG to the set of signals pointed to
    by SET.

    sigdelset() deletes the signal SIG from the set of signals pointed
    to by SET.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

  Return value:

    If successful, sigaddset() and sigdelset() return 0.  Otherwise,
    these functions set errno and return -1.

  Errors:

    EINVAL  SIG is not a valid signal number.

  See also: sigemptyset(), sigfillset(), sigismember()

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigemptyset (sigset_t *set);
int sigfillset (sigset_t *set);

    sigemptyset() initializes the object pointed to by SET to an empty
    set of signals.

    sigfillset() initializes the object pointed to by SET to a signal
    set which includes all signals.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

  Return value:

    If successful, sigemptyset() and sigfillset() return 0.
    Otherwise, these functions set errno and return -1.

  See also: sigaction(), sigaddset(), sigdelset(), sigprocmask(),
            sigismember()

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigismember (const sigset_t *set, int sig);

    sigismember() tests whether the signal SIG is a member of the set
    of signals pointed to by SET.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

  Return value:

    sigismember() returns 1 if the signal SIG is a member of the set
    of signals pointed to by SET, or 0 if the signal SIG is not a
    member of the set of signals pointed to by SET.  On error,
    sigismember() sets errno and returns -1.

  Errors:

    EINVAL  SIG is not a valid signal number.

  See also: sigaddset(), sigdelset(), sigemptyset(), sigfillset()

------------------------------------------------------------------------------
#include <setjmp.h>                                                  [POSIX.1]

void siglongjmp (sigjmp_buf there, int n);

    Restore the context saved in THERE by sigsetjmp() and -- if the
    SAVEMASK argument of sigsetjmp() was non-zero -- restore the
    signal mask saved by sigsetjmp() .  siglongjmp() does a non-local
    goto, causing execution to continue at the sigsetjmp() call which
    most recently saved a stack context in THERE.  sigsetjmp() will
    return N.  If N is 0, sigsetjmp() will return 1.  When calling
    siglongjmp() in a signal handler or in a function called by a
    signal handler (that is, while a signal handler is active), the
    signal handler will be unwound, that is, it is assumed that the
    signal handler doesn't return.  siglongjmp() must be called in the
    same thread as the most recent call to sigsetjmp() for THERE.
    Moreover, the function which most recently called sigsetjmp() to
    save a stack context in THERE must still be active.  Don't expect
    local variables to be preserved unless declared volatile.

    As sigjmp_buf is an array type, the & operator need not be
    applied.

  See also: longjmp(), setjmp(), sigaction(), sigprocmask(),
            sigsetjmp(), signal()

------------------------------------------------------------------------------
#include <signal.h>                                                      [C90]

void (*signal (int sig, void (*handler)()))(int sig);

    Set the signal action associated with signal SIG.  HANDLER can be
    SIG_DFL (to get the default action), SIG_IGN (to ignore the
    signal), or the address of a signal-catching function (signal
    handler).

    On delivery of the signal, the signal number is passed as the only
    argument to the signal-catching function.  Before the
    signal-catching funcion is called, the signal is blocked or the
    signal action is reset to SIG_DFL, depending on the signal
    processing model.

    The action associated with SIGKILL cannot be changed.

    In a multithread program, signal() sets a signal handler for the
    thread in which it is called.  The set of signal handlers is
    private to each thread.

    On delivery, the signal is blocked before calling the signal
    handler, if the `emx' signal model is used and the signal is
    caught (that is, a signal handler is installed).  To unblock the
    signal SIG, call

        signal (sig, SIG_ACK)

    See section 4 for details on signal processing.

  Return value:

    If successful, signal() returns the previous signal action
    (SIG_IGN or SIG_DFL or the address of a signal handler) associated
    with signal SIG.  On failure, signal() returns SIG_ERR.  If
    HANDLER is SIG_ACK, signal() returns the current signal action
    associated with the signal SIG.

  See also: abort(), kill(), raise(), sigaction(), sigprocmask()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

int signbit (float x);
int signbit (double x);
int signbit (long double x);

    Determine the sign of X.  The argument X must be of a
    floating-point type.

  Return value:

    signbit() returns a non-zero value if the sign of X is negative;
    signbit() returns 0 otherwise.

  See also: copysign(), fpclassify(), isfinite(), isnan(), isnormal()

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigpending (sigset_t *set);

    Store in the object pointed to by SET the set of signals that are
    blocked and pending.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

  Return value:

    If successful, sigpending() returns 0.  Otherwise sigpending()
    returns -1 and sets errno.

  See also: kill(), raise(), sigaction(), sigprocmask(), sigismember()

  Example:

    int poll_sigint (void)
    {
      sigset_t s;
    
      sigemptyset (&s);
      return (sigprocmask (&s) == 0
              && sigismember (&s, SIGINT) == 1);
    }

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigprocmask (int how, const sigset_t *iset, sigset_t *oset);

    Examine and/or change the signal mask (set of blocked signals) of
    the calling process.  If ISET is not NULL, it points to a set of
    signals used to change the signal mask.  The following values are
    available for HOW to indicate how to modify the signal mask:

    SIG_BLOCK
            Add the signals of the set pointed to by ISET to the set
            of blocked signals.  The resulting signal mask will be the
            union of the current signal mask and the signal set
            pointed to by ISET.

    SIG_UNBLOCK
            Remove the signals of the set pointed to by ISET from the
            set of blocked signals.  The resulting signal mask will be
            the intersection of the current signal mask and the
            complement of the signal set pointed to by ISET.

    SIG_SETMASK
            Replace the current signal mask with the signal set
            pointed to by ISET.

    SIGKILL cannot be blocked; any attempt to block SIGKILL is ignored
    by sigprocmask() without indication of an error.

    If ISET is NULL, the signal mask won't be changed.

    If OSET is not NULL, the previous signal mask will be stored in
    the object pointed to by OSET.

    If any unblocked signal is pending, at least one unblocked pending
    signal will be delivered before sigprocmask() returns.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

  Return value:

    If successful, sigprocmask() returns 0.  Otherwise sigprocmask()
    returns -1 and sets errno.

  Errors:

    EINVAL  HOW is not SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK

  See also: kill(), raise(), sigaction(), sigemptyset(),
            sigismember(), siglongjmp(), sigpending(), sigsetjmp()

  Example:

    void block_sigint (void)
    {
      sigset_t s;
    
      sigemptyset (&s);
      sigaddset (&s, SIGINT);
      sigprocmask (SIG_BLOCK, &s, NULL);
    }

------------------------------------------------------------------------------
#include <setjmp.h>                                                  [POSIX.1]

int sigsetjmp (sigjmp_buf here, int savemask);

    Save the current stack context in HERE and return 0.  If SAVEMASK
    is non-zero, also save the current signal mask (set of blocked
    signals) to HERE.  Later, you can continue at this point by
    calling siglongjmp().  When execution continues at sigsetjmp()
    after calling siglongjmp(), the second argument of siglongjmp() is
    returned, which is always non-zero (if zero is used as second
    argument of siglongjmp(), it will be turned into 1).

    sigsetjmp() must not be used in compliated expressions.

    As sigjmp_buf is an array type, the & operator need not be
    applied.

  Return value:

    sigsetjmp() returns 0 when directly called.  When returning from a
    call to siglongjmp(), sigsetjmp() returns a non-zero value
    (supplied by the call to siglongjmp()).

  See also: longjmp(), setjmp(), siglongjmp(), sigprocmask()

------------------------------------------------------------------------------
#include <signal.h>                                                [POSIX.1 *]

int sigsuspend (const sigset_t *mask);

    Replace the signal mask with the set of signals pointed to by MASK
    and then suspend the process until delivery of a signal for which
    a signal handler is installed.  sigsuspend() returns after the
    signal handler returns.  Before returning, sigsuspends() restores
    the signal mask to the set that existed prior to the sigsuspend()
    call.

    The process will be terminated (and sigsuspend() won't return) if
    an uncaught signal is delivered which terminates the process.

    SIGKILL cannot be blocked; any attempt to block SIGKILL is ignored
    by sigsuspend() without indication of an error.

    Every object of type sigset_t should be initialized at least once
    with either sigemptyset() or sigfillset() before any use.  When
    using an uninitialized object of type sigset_t, the results are
    undefined.

  Return value:

    sigsuspend() sets errno to EINTR and returns -1.

  Restrictions:

    sigsuspend() is not implemented under DOS.

  See also: alarm(), kill(), pause(), sigaction(), sigemptyset(),
            sigprocmask()

------------------------------------------------------------------------------
#include <stdlib.h>                                                  [POSIX.1]

unsigned sleep (unsigned sec);

    Suspend the calling process for SEC seconds or until an unblocked
    signal is caught.  SEC should not exceed 4294967.

  Return value:

    If interrupted by a caught signal, sleep() returns the number of
    remaining seconds.  Otherwise, sleep() returns 0.

  Implementation-defined behavior:

    alarm() and SIGALRM don't interfer with the operation of sleep().

  Restrictions:

    sleep() is also interrupted by ignored signals and, under OS/2, by
    blocked signals.

  See also: alarm(), sigaction(), signal(), sigprocmask(), _sleep2()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

unsigned _sleep2 (unsigned millisec);

    Suspend the calling process for MILLISEC milliseconds.  As the
    system clock is used for timing, the actual duration of the time
    interval depends on the granularity of the system clock.  The time
    interval is rounded up to the next clock tick.  Also note that
    calling _sleep2() involves an overhead.

    Delivery of a signal which is caught interrupts _sleep2().

  Return value:

    _sleep2() returns 0.

  Restrictions:

    Under OS/2, sleep() is also interrupted by ignored signals and by
    blocked signals.  Under DOS, sleep() is not interrupted by
    signals.

  See also: alarm(), sigaction(), signal(), sigprocmask(), sleep()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/smutex.h>

int _smutex_available (volatile _smutex *sem);

    Check if the _smutex semaphore pointed to by SEM is available or
    owned, without changing the state of the semaphore and without
    blocking.  Return zero if the semaphore is owned, return a
    non-zero value if the semaphore is available.  Note that
    _smutex_available() just returns a snapshot of the state of the
    semaphore; in presence of other threads or other processes having
    access to the semaphore, the state may change at any time, even
    before _smutex_available() returns.  This function can be used to
    avoid deadlock.

  Return value:

    _smutex_available() returns a non-zero value if the semaphore is
    available.  _smutex_available() returns 0 if the semaphore is
    owned.

  See also: _smutex_release(), _smutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/smutex.h>

void _smutex_release (volatile _smutex *sem);

    Relinquish ownership of the _smutex semaphore pointed to by SEM.
    Unblocking any process blocking in _smutex_request() for this
    semaphore won't occur before the current time slice ends.

  See also: __cxchg(), _smutex_available(), _smutex_request()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                                 [emx]
#include <sys/smutex.h>

void _smutex_request (volatile _smutex *sem);

    Request ownership of the _smutex semaphore pointed to by SEM.  If
    the semaphore is available, it will be set to owned and
    _smutex_request() will return immediately.

    If the semaphore is owned, _smutex_request() will suspend the
    current thread, periodically checking whether the semaphore is
    available or still owned.  If the semaphore is available, it will
    be set atomically to owned and _smutex_request() will return.
    Otherwise, _smutex_request() will continue polling.
    _smutex_request() does not return if a signal occurs while
    blocking.

    Note that ownership of an _smutex semaphore is not tied to a
    thread, that is, it's not a thread which owns the semaphore.  This
    is in contrast to OS/2's mutex semaphores (HMTX).  Deadlock will
    occur if _smutex_request() is called twice for the same semaphore
    by the same thread without an intervening call to
    _smutex_release().  This fact is important to keep in mind in
    presence of signals.  Signal handlers must not request semaphores
    which can be owned by the interrupted code.  You might want to
    block signals before requesting ownership of an _smutex semaphore.

  Restrictions:

    Under DOS, _smutex_request() crashes if the semaphore is already
    owned.

  See also: __cxchg(), _fmutex_create(), _rmutex_create(),
            _smutex_available(), _smutex_release()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [BSD]

int snprintf (char *buffer, size_t n, const char *format, ...);

    Formatted output to the string pointed to by BUFFER.  Up to N-1
    characters and a terminating null character will be written to
    BUFFER.  If formatting yields more than N-1 characters, output
    will be truncated.  The terminating null character will be put
    into BUFFER even if output is truncated.

  Return value:

    On success, snprintf() returns the number of characters copied to
    BUFFER (excluding the terminating null character).  If the length
    of formatted output exceeds N-1 characters, snprintf() will return
    a value greater than or equal to N.  On error, snprintf() returns
    EOF.

  See also: sprintf(), vsnprintf()

------------------------------------------------------------------------------
#include <io.h>                                                           [PC]
#include <share.h>

int sopen (const char *name, int oflag, int shflag);
int sopen (const char *name, int oflag, int shflag, int pmode);

int sopen (const char *name, int oflag, int shflag,
           unsigned long isize);
int sopen (const char *name, int oflag, int shflag, int pmode,
           unsigned long isize);

    Open a file or device with an explicit sharing mode.  NAME points
    to the name of the file or device.  OFLAG contains one or more of
    the following values, combined by the | operator:

    O_RDONLY
            Open for reading.  Writing is not allowed

    O_WRONLY
            Open for writing.  Reading is not allowed

    O_RDWR  Open for reading and writing

    O_APPEND
            Move the file pointer to the end of file before any write
            operation takes place.  This is used for appending to a
            file

    O_CREAT
            Create the file if it does not exist.  If this flag is
            set, the PMODE argument is required

    O_TRUNC
            Truncate the size of the file to 0

    O_EXCL  Fail if the O_CREAT is used and the file already exists

    O_NONBLOCK alias O_NDELAY
            Currently ignored

    O_BINARY
            Binary mode, no translation.  See below

    O_TEXT  Text mode, translate CR/LF to newline.  See below

    O_NOINHERIT
            Child processes won't inherit the file handle

    O_SYNC  Write operations are synchronous, that is, write() waits
            until file data has been physically written

    O_SIZE  Set the initial size of the file to ISIZE if the file is a
            new file (O_CREAT) or an existing file truncated
            (O_TRUNC).  If this flag is set, the ISIZE argument is
            required.  O_SIZE is ignored under DOS

    If a new file is created, PMODE (modified by the umask value), is
    used to set the file permissions.  S_IREAD grants read access,
    S_IWRITE grants write access.  S_IREAD is ignored (DOS and OS/2
    limitation).

    There are two additional OFLAG flags: O_TEXT for text mode,
    O_BINARY for binary mode.  Text mode, which is the default,
    translates each CR/LF pair to a newline character on input and
    translates newline characters to CR/LF pairs on output.  If the
    last character of a file is Ctrl-Z, it is discarded on input.
    Binary mode disables these transformations.

    If the file or device cannot be opened, open() sets errno and
    returns -1.  If open() succeeds, the file handle is returned.  The
    file handle is always greater than -1.

    The mode O_TRUNC|O_RDONLY is not implemented.  A Ctrl-Z at the end
    of the file is removed only when opening a file for appending in
    text mode.  Ctrl-Z at the end of the file is obsolete, anyway.

    The sharing mode of the file is given by SHFLAG.  The following
    sharing modes are available:

    SH_DENYRW
            Deny read and write access

    SH_DENYRD
            Deny read access (permit write access)

    SH_DENYWR
            Deny write access (permit read access)

    SH_DENYNO
            Deny nothing (permit read and write access)

  Return value:

    sopen() returns a file handle for the file.  On error, sopen()
    sets errno and returns -1.

  Implementation-defined behavior:

    O_SIZE is an emx extension.  It's the caller's responsibility to
    truncate the file if its size should be less than ISIZE bytes.
    O_SIZE is ignored under DOS.

  Restrictions:

    Under DOS, the O_NOINHERIT flag is currently ignored for child
    processes which are DOS programs (vs.  emx programs).  Under DOS,
    the O_SYNC and O_SIZE flags are ignored.

  See also: close(), fcntl(), fdopen(), ftruncate(), open()

------------------------------------------------------------------------------
#include <process.h>                                                    [PC *]

int spawnl (int mode, const char *name, const char *arg0, ...);
int spawnle (int mode, const char *name, const char *arg0, ...);
int spawnlp (int mode, const char *name, const char *arg0, ...);
int spawnlpe (int mode, const char *name, const char *arg0, ...);
int spawnv (int mode, const char *name, char * const argv[]);
int spawnve (int mode, const char *name,char * const argv[],
             char * const envp[]);
int spawnvp (int mode, const char *name, char * const argv[]);
int spawnvpe (int mode, const char *name, char * const argv[],
              char * const envp[]);

    Run a program.  NAME points to the name of the executable file to
    run.

    Use spawnl(), spawnle(), spawnlp() or spawnlpe() for passing a
    fixed number of arguments.  ARG0 points to a string containing the
    0th argument which is the program name, by convention.  Following
    ARG0, pointers to the arguments are passed.  After the last
    argument pointer, a null pointer cast to `char *' must be
    following.  At least ARG0 must be specified.

    Use spawnv(), spawnve(), spawnvp() or spawnvpe() for passing a
    variable number of arguments.  ARGV points to an array of pointers
    to strings.  The first entry is the program name, by convention.
    The last argument pointer must be followed by a null pointer.

    spawnl(), spawnlp(), spawnv() and spawnvp() pass the environment
    of the current process to the child process.  To pass a different
    environment to the child process pass a pointer to an array of
    strings after the null argument pointer of spawnle() and
    spawnlpe() or pass the pointer in the ENVP argument of spawnve()
    and spawnvpe().  The last string pointer in the array must be
    followed by a null pointer.

    If both the child process and the parent process use emx.exe or
    emx.dll, the child process will inherit the signal actions of the
    parent process: Signals set to SIG_IGN in the parent process will
    be set to SIG_IGN in the child process, signals set to SIG_DFL in
    the parent process will be set to SIG_DFL in the child process,
    signals caught in the parent process will be set to SIG_DFL in the
    child process.

    The MODE argument specifies how to run the child process.  You
    have to include exactly one of the following values:

    P_WAIT  run the process synchronously, that is, control returns to
            the parent process after the child process finishes

    P_NOWAIT
            run the process asynchronously, that is in parallel with
            the parent process.  Use wait() to wait for completion of
            the child process and to get its termination status.
            Under DOS, the process is run synchronously

    P_OVERLAY
            replace the parent process, that is, run the child process
            and terminate the parent process

    P_DEBUG
            run the process in debugging mode, that is, under control
            of the parent process.  Use ptrace() to control the child
            process

    P_DETACH
            run the process detached, that is, without input and
            output.  P_DETACH is not available under DOS

    P_SESSION
            run the process in a separate session.  P_SESSION is not
            available under DOS.

    P_PM    the process is a Presentation Manager program.  P_PM is
            not available under DOS.

    Additional flags are available for P_SESSION, which can be added
    by using the | operator:

    P_QUOTE
            Quote all the arguments, that is, suppress expansion of
            command line arguments by _wildcard() and _response() in
            the child process.  Without P_QUOTE, arguments are not
            quoted

    P_TILDE
            Use the `MKS Korn shell' method for passing command line
            arguments (OS/2, only; this was the default in emx 0.8h
            and earlier).  That method passes the arguments in the
            third and following strings of DosExecPgm.  The tilde
            character is used as flag at the start of the third string

    Use one of the following flags for selecting the session type:

    P_DEFAULT
            let the operating system choose the session type

    P_FULLSCREEN
            start a full-screen session

    P_WINDOWED
            start a windowed session

    These flags (which can be used with P_SESSION and P_PM) control
    the initial appearance of the window:

    P_MINIMIZE
            minimize the window

    P_MAXIMIZE
            maximize the window

    Additionally, you can use the following flags with P_SESSION and
    P_PM:

    P_BACKGROUND
            start the session in the background

    P_FOREGROUND
            start the session in the foreground.  This works only if
            the calling session is in the foreground.  P_FOREGROUND is
            the default

    P_NOCLOSE
            don't close the window automatically when the process ends
            (ignored for P_PM)

    P_UNRELATED
            create an independent session.  SIGCHLD won't be raised
            when the session terminates.  wait() and waitpid() cannot
            be used on that session.  spawn*() returns zero (instead
            of a process ID) on success.

    Additional flags are available for P_DEBUG, which can be added by
    using the | operator:

    P_NOSESSION
            don't run debuggee in a separate session.  The same effect
            can be achieved with the -E emx option.

    P_DEBUGDESC
            enable debugging of descendant processes of the debuggee;
            see ptrace() for details.  P_DEBUGDESC cannot be used if
            _UF_PTRACE_STANDARD is in effect, see _uflags() for
            details.

    When the new process terminates, SIGCHLD is sent to the process
    which started that process.  You should use wait() or waitpid() to
    get the return code of the process.  If you don't retrieve the
    return code for asynchronous child processes, the return codes
    fill up memory.  All this does not apply to P_WAIT, P_OVERLAY and
    P_DETACH.

  Return value:

    These functions return the return value of the child process
    (P_WAIT), or the process ID of the child process (P_NOWAIT,
    P_DEBUG, P_SESSION and P_PM), or zero (P_UNRELATED) if successful.
    On error they return -1.

  Restrictions:

    The command line length is restricted to 126 characters when
    running DOS programs.  DOS programs can only be run in P_WAIT or
    P_NOWAIT mode.  P_NOWAIT runs processes synchronously under DOS.
    The termination status of only one process will be kept for wait()
    under DOS.  The default extension is .exe; if you want to run a
    .com file, explicitly add .com.  Currently, DOS seems to crash if
    you try to spawn a .com file without using emx option -p, see
    `Using emx options'.  (The machine crashes on the second attempt.)
    With the system call library sys.lib (-Zsys), only modes P_WAIT,
    P_NOWAIT and P_OVERLAY are currently available.

  See also: exit(), ptrace(), system(), wait()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char **_splitargs (char *string, int *count);

    Parse the string pointed to by STRING like a command line and
    build a vector of pointers to the arguments.  The vector is
    terminated by a NULL pointer.  The number of arguments is stored
    to the variable pointed to by COUNT unless COUNT is NULL.  The
    string pointed to by STRING is modified by _splitargs(), the
    pointers in the resulting vector point into the string pointed to
    by STRING.  _splitargs() allocates the vector using malloc().  If
    you no longer need the vector, use free() to deallocate it.  On
    error, _splitargs() sets errno and returns NULL.

    Arguments in the string pointed to by STRING are separated by
    whitespace (one or more blanks, tabs and linefeeds).  Whitespace
    at the start of the string is skipped.  To include blanks, tabs or
    linefeeds in an argument, the argument must be quoted using double
    quotation marks.  To remove the special meaning of a double quote,
    precede it with a backslash.  To remove the special meaning of a
    backslash in front of a double quote, precede the backslash with a
    backslash.  The backslash character doesn't have a special meaning
    unless it precedes a double quote or any number of backslashes
    followed by a double quote.

    In other words: If there are n backslashes (\) immediately
    preceding a double quote character ("), floor(n/2) backslashes are
    put into the argument.  If n is odd, the double quote character is
    put into the argument.  If n is even (including zero), the double
    quote character is used for quoting, that is, spaces are not
    treated as argument delimiters until the next `quoting' double
    quote character (ie, a double quote character immediately preceded
    by an even number (including zero) of backslashes) is found.
    Backslashes not preceding a quote character are always read as
    backslashes.

  Return value:

    See above.

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

void _splitpath (const char *src, char *drive, char *dir, char *fname,
                 char *ext);

    Split the path name pointed to by SRC into its components.  The
    drive name (including the colon) is stored to the array pointed to
    by DRIVE.  The directory (including the final slash or backslash)
    is copied to the array pointed to by DIR, the file name without
    extension is copied to the array pointed to by FNAME, the
    extension (including the dot) is copied to the array pointed to by
    EXT.  The arrays should be of size _MAX_DRIVE, _MAX_DIR,
    _MAX_FNAME and _MAX_EXT, respectively.  These constants include
    the terminating null characters.  If one of the pointers (except
    for SRC) is NULL, that component is not stored.

    _splitpath() properly handles DBCS characters.

  See also: _fngetdrive(), _getext(), _getname(), _makepath(),
            _nls_init()

  Example:

    char drive[_MAX_DRIVE], dir[_MAX_DIR];
    char fname[_MAX_FNAME], ext[_MAX_EXT];
    char *path = "c:/files/more/test.file.c";
    
    _splitpath (path, drive, dir, fname, ext);

    Results of the example:

        drive = "c:"
        dir   = "/files/more/"
        fname = "test.file"
        ext   = ".c"

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int sprintf (char *buffer, const char *format, ...);

    Formatted output to the string pointed to by BUFFER.  The string
    must be big enough to hold the output.  See printf() for details.

  Return value:

    On success, sprintf() returns the number of characters copied to
    BUFFER (excluding the terminating null character).  On error,
    sprintf() returns EOF.

  See also: gcvt(), _itoa(), _mfopen(), printf(), sscanf(), snprintf()

------------------------------------------------------------------------------
#include <math.h>                                                    [C90 C9X]

double sqrt (double x);
long double sqrtl (long double x);

    Compute the square root of X.

    sqrtl() uses the long double format.

  Return value:

    sqrt() returns the square root of X.  If X is negative, a NaN is
    returned and errno set to EDOM.

  See also: cbrt(), pow()

------------------------------------------------------------------------------
#include <sys/builtin.h>                                               [VAC++]

unsigned short _srotl (unsigned short value, int shift);
unsigned short _srotr (unsigned short value, int shift);

    _srotl() returns VALUE (16 bits) rotated left by SHIFT bits.  If
    SHIFT is 1, bit 14 is returned as bit 15, bit 13 is returned as
    bit 14, and so on, bit 0 is returned as bit 1, and bit 15 is
    returned as bit 0.

    _srotr() returns VALUE (16 bits) rotated right by SHIFT bits.  If
    SHIFT is 1, bit 1 is returned as bit 0, bit 2 is returned as bit
    1, and so on, bit 7 is returned as bit 6, and bit 0 is returned as
    bit 7.

    SHIFT should be 0 through 15.

    These functions are implemented as inline functions.

  See also: _crotl(), _crotr(), _lrotl(), _lrotr()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int sscanf (const char *buffer, const char *format, ...);

    Parse the string pointed to by BUFFER according to the format
    string pointed to by FORMAT.  For each field in the format string
    there must be a pointer to the location receiving the value.  The
    pointers are passed after the FORMAT argument.

  Return value:

    If successful, sscanf() returns the number of fields converted.
    On error, sscanf() returns EOF.

  See also: scanf(), sprintf(), strptime()

  Example:

    char inp[512];
    int year, month, day;
    ...
    if (fgets (inp, sizeof (inp), stdin) != NULL
        && sscanf (inp, "%d/%d/%d", &year, &month, &day) == 3)
      {
        ...
      }

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]
#include <sys/types.h>
#include <sys/stat.h>

int stat (const char *name, struct stat *buffer);

    Retrieve information about a file or directory.  NAME is a pointer
    to the name of the file or directory.  stat() will put the data
    into the structure pointed to by BUFFER:

        struct stat
        {
          dev_t   st_dev;       /* Device number */
          ino_t   st_ino;       /* Inode number */
          mode_t  st_mode;      /* Protection mode, S_IREAD etc. */
          nlink_t st_nlink;     /* Number of links -- always 1 */
          uid_t   st_uid;       /* User ID of owner -- always 0 (root) */
          gid_t   st_gid;       /* Group ID of owner -- always 0 (root) */
          dev_t   st_rdev;      /* Always 0 */
          off_t   st_size;      /* Size of file */
          time_t  st_atime;     /* Time of last access */
          time_t  st_mtime;     /* Time of last modification */
          time_t  st_ctime;     /* Time of creation */
          long    st_attr;      /* File attributes (OS/2 and DOS style) */
          long    st_reserved;  /* Currently not used */
        };

  Return value:

    0       success

    -1      error (errno is set)

  Restrictions:

    st_dev and st_rdev are set to zero.  Each call to stat() returns a
    different value for st_ino.

  See also: fstat()

------------------------------------------------------------------------------
#include <float.h>                                                        [PC]

unsigned _status87 (void);

    Return the coprocessor status word.

  Return value:

    See above.

  See also: _clear87(), _control87()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strcat (char *string1, const char *string2);

    Append the null-terminated string pointed to by STRING2 to the
    null-terminated array pointed to by STRING1.  The objects must not
    overlap.

  Return value:

    strcat() returns STRING1.

  See also: strcpy()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strchr (const char *string, int c);

    Return a pointer to the first occurrence of the character C in the
    null-terminated string pointed to by STRING.  If there is no
    character C in that string, NULL is returned.  If C is the null
    character (0), a pointer to the terminating null character of that
    string is returned.

  Return value:

    See above.

  See also: index(), memchr(), strrchr(), strstr()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

int strcmp (const char *string1, const char *string2);

    Compare the null-terminated strings pointed to by STRING1 and
    STRING2.  If the string pointed to by STRING1 is less than the
    string pointed to by STRING2, a negative value is returned.  If
    the string pointed to by STRING1 is equal to the string pointed to
    by STRING2, zero is returned.  If the string pointed to by STRING1
    is greater than the string pointed to by STRING2, a positive value
    is returned.

  Return value:

    <0      1st string < 2nd string

    =0      1st string = 2nd string

    >0      1st string > 2nd string

  See also: memcmp(), stricmp(), strncmp()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

int strcoll (const char *string1, const char *string2);

    Compare the null-terminated strings pointed to by STRING1 and
    STRING2 according to the LC_COLLATE category of the current
    locale.  If the string pointed to by STRING1 is less than the
    string pointed to by STRING2, a negative value is returned.  If
    the string pointed to by STRING1 is equal to the string pointed to
    by STRING2, zero is returned.  If the string pointed to by STRING1
    is greater than the string pointed to by STRING2, a positive value
    is returned.

  Return value:

    <0      1st string < 2nd string

    =0      1st string = 2nd string

    >0      1st string > 2nd string

  Restrictions:

    Currently, locale is ignored: strcoll() is equivalent to strcmp().

  See also: setlocale(), strcmp()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strcpy (char *string1, const char *string2);

    Copy the null-terminated string pointed to by STRING2 to the array
    pointed to by STRING1.  The objects must not overlap.

  Return value:

    strcpy() returns STRING1.

  See also: memccpy(), memcpy(), strcat(), strncpy()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

size_t strcspn (const char *string1, const char *string2);

    Return the length of the initial substring of the string pointed
    to by STRING1 which consists of characters not in the string
    pointed to by STRING2.  That is, the index of the first character
    in the string pointed to by STRING1 which also occurs in the
    string pointed to by STRING2 is returned.  If all characters of
    the string pointed to by STRING1 are not in the string pointed to
    by STRING2, the length of the string pointed to by STRING1 is
    returned.

  Return value:

    See above.

  See also: strpbrk(), strspn()

------------------------------------------------------------------------------
#include <string.h>                                                     [UNIX]

char *strdup (const char *string);

    Creates a duplicate of the string pointed to by STRING by using
    malloc() to allocate storage and copying the string pointed to by
    STRING.

  Return value:

    strdup() returns a pointer to the new string.  If there is not
    enough memory, strdup() returns NULL.

  See also: malloc(), strcpy()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strerror (int errnum);

    Return a pointer to a an error message according to the error
    number ERRNUM.  You must not write to the string returned by
    strerror().  The string may get changed by the next call to
    strerror().

  Return value:

    See above.

  See also: errno, perror(), sys_errlist

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

size_t strftime (char *string, size_t size, const char *format,
                 const struct tm *t);

    Format time.  The output string is written to the array of SIZE
    characters pointed to by STRING, including the terminating null
    character.  Like sprintf(), strftime() copies the string pointed
    to by FORMAT to the array pointed to by STRING, replacing format
    specifications with formatted data from T.  Ordinary characters
    are copied unmodified.  The following format specifications are
    available:

    %%      percent sign

    %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 date and time

    %d      day of month (01-31)

    %D      date, this is equivalent to %m/%d/%y

    %e      day of month ( 1-31), blank padded

    %h      locale's abbreviated month name

    %H      hour (00-23)

    %I      hour (01-12)

    %j      day of year (001-366)

    %m      month (01-12)

    %M      minute (00-59)

    %n      newline character

    %p      locale's equivalent to AM or PM, as appropriate

    %r      time in AM/PM notation, this is equivalent to %I:%M:%S %p

    %S      second (00-59)

    %t      TAB character

    %T      time, this is equivalent to %H:%M:%S

    %U      week number of the year, the first day of the week is
            Sunday (00-53)

    %w      weekday, the first day of the week is Sunday (0-6)

    %W      week number of the year, the first day of the week is
            Monday (00-53)

    %x      locale's date representation

    %X      locale's time representation

    %y      year without century (00-99)

    %Y      year with century (1970-2106)

    %Z      timezone name (taken from the timezone variable, as the
            timezone isn't provided by T) or no characters if no time
            zone is determinable

    If % is followed by a character not listed above, the results are
    undefined.

  Return value:

    On success, strftime() returns the number of characters copied to
    the array pointed to by STRING, excluding the terminating null
    character.  On failure (SIZE exceeded), strftime() returns 0.

  See also: asctime(), setlocale(), sprintf(), strptime(), tzset()

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

int stricmp (const char *string1, const char *string2);

    Compare the strings pointed to by STRING1 and STRING2, ignoring
    letter case.  If the strings are equal, 0 is returned.  Otherwise,
    a positive value is returned if the string pointed to by STRING1
    is greater than the string pointed to by STRING2 (after conversion
    to lower case).  A negative value is returned if the string
    pointed to by STRING1 is less than the string pointed to by
    STRING2 (after conversion to lower case).  The strings are not
    modified.

  Return value:

    <0      1st string < 2nd string

    =0      1st string = 2nd string

    >0      1st string > 2nd string

  See also: strcmp(), tolower()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

size_t strlen (const char *string);

    Compute the length (number of characters) of the string pointed to
    by STRING.  The length does not include the terminating null
    character.

  Return value:

    strlen() returns the length of the string pointed to by STRING,
    that is, the number of characters preceding the terminating null
    character.

  See also: strchr()

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

char *strlwr (char *string);

    Convert the string pointed to by STRING to lower case.  The
    characters 'A' through 'Z' are mapped to the characters 'a'
    through 'z'.  All other characters are not changed.

  Return value:

    strlwr() returns STRING.

  See also: _fnlwr(), strupr()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strncat (char *string1, const char *string2, size_t count);

    Append the null-terminated string pointed to by STRING2 to the
    null-terminated string pointed to by STRING1.  At most COUNT
    characters of the string pointed to by STRING2 are appended to the
    string pointed to by STRING1.  strncat() terminates the new string
    pointed to by STRING1 with a null character.

  Return value:

    strncat() returns STRING1.

  See also: strcat(), strncpy()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

int strncmp (const char *string1, const char *string2, size_t count);

    Compare the null-terminated strings pointed to by STRING1 and
    STRING2.  At most the first COUNT characters are compared.  If the
    string pointed to by STRING1 is less than the string pointed to by
    STRING2, a negative value is returned.  If the string pointed to
    by STRING1 is equal to the string pointed to by STRING2, zero is
    returned.  If the string pointed to by STRING1 is greater than the
    string pointed to by STRING2, a positive value is returned.

  Return value:

    <0      1st string < 2nd string

    =0      1st string = 2nd string

    >0      1st string > 2nd string

  See also: memcmp(), strcmp(), strnicmp()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strncpy (char *string1, const char *string2, size_t count);

    Copy the null-terminated string pointed to by STRING2 to the array
    pointed to by STRING1.  The objects must not overlap.  At most the
    first COUNT characters of the string pointed to by STRING2 are
    copied.  If the string pointed to by STRING2 is shorter than COUNT
    characters, the string pointed to by STRING1 will be padded with
    null characters to COUNT characters.  If the length of the string
    pointed to by STRING2 is equal to or greater than COUNT, a
    terminating null character will not be appended.

  Return value:

    strncpy() returns STRING1.

  See also: strcpy(), strncat()

------------------------------------------------------------------------------
#include <string.h>                                                      [emx]

char *_strncpy (char *string1, const char *string2, size_t size);

    Copy the null-terminated string pointed to by STRING2 to the array
    pointed to by STRING1.  The objects must not overlap.  At most
    SIZE characters, including the terminating null character, are
    copied to the array pointed to by STRING1.  A terminating null
    character is always appended, even if the string pointed to by
    STRING2 is too long.

  Return value:

    _strncpy() returns STRING1.

  See also: strcpy(), strncpy()

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

int strnicmp (const char *string1, const char *string2, size_t count);

    Compare the null-terminated strings pointed to by STRING1 and
    STRING2 ignoring letter case.  At most the first COUNT characters
    are compared.  If the string pointed to by STRING1 is equal to the
    string pointed to by STRING2, zero is returned.  If the string
    pointed to by STRING1 is less than the string pointed to by
    STRING2 (after conversion to lower case), a negative value is
    returned.  If the string pointed to by STRING1 is greater than the
    string pointed to by STRING2 (after conversion to lower case), a
    positive value is returned.  The strings are not modified.

  Return value:

    <0      1st string < 2nd string

    =0      1st string = 2nd string

    >0      1st string > 2nd string

  See also: memicmp(), strcmp(), strncmp(), tolower()

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

char *strnset (char *string, int c, size_t count);

    Set, at most, the first COUNT characters of the string pointed to
    by STRING to the character C.  If the length of the string pointed
    to by STRING is less than COUNT, strnset() stops at the
    terminating null character.

  Return value:

    strnset() returns STRING.

  See also: memset(), strset()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strpbrk (const char *string1, const char *string2);

    Return a pointer to the first occurrence in the string pointed to
    by STRING1 of a character of the string pointed to by STRING2.
    The terminating null character is not included in the search.  If
    no character of the string pointed to by STRING2 can be found in
    the string pointed to by STRING1, NULL is returned.

  Return value:

    See above.

  See also: strchr(), strcspn()

------------------------------------------------------------------------------
#include <time.h>                                                       [UNIX]

char *strptime (const char *buffer, const char *format, struct tm *t);

    Parse a time specification in the input string pointed to by
    BUFFER according to the format string pointed to by FORMAT,
    updating the structure pointed to by T.

    Whitespace (any number of spaces) in the format string matches
    whitespace (any number of spaces, including zero) in the input
    string.  All other characters except for % are compared to the
    input.  Parsing ends (with an error being indicated) when a
    mismatch is encountered.  %% in the format string matches % in the
    input string.  A % which is not followed by another % or the end
    of the string starts a field specification.  The field in the
    input is interpreted according to the field specification.  For
    all field types, whitespace is ignored at the start of a field.
    Field specifications matching numbers skip leading zeros.  Case is
    ignored when comparing strings.  The field width is not
    restricted, that is, as many characters as possible are matched.
    The following field specifications are available:

    %%      percent sign (see above)

    %a      locale's abbreviated weekday name, tm_wday

    %A      locale's full weekday name, update tm_wday

    %b      locale's abbreviated month name, update tm_mon.  %h is a
            synonym for %b

    %B      locale's full month name, update tm_mon

    %c      locale's date and time, update tm_year, tm_mon, tm_mday,
            tm_hour, tm_min, and tm_sec

    %C      date and time, equivalent to %x %X, update tm_year,
            tm_mon, tm_mday, tm_hour, tm_min, and tm_sec

    %d      day of month (1-31), update tm_mday

    %D      date, this is equivalent to %m/%d/%y, update tm_year,
            tm_mon, and tm_mday

    %e      day of month (1-31), update tm_mday

    %H      hour (0-23), update tm_hour (%k is a synonym for %H)

    %I      hour (1-12), update tm_hour (%l is a synonym for %I)

    %j      day of year (1-366), update tm_yday

    %m      month (1-12), update tm_mon

    %M      minute (0-59), update tm_min

    %n      newline character

    %p      locale's equivalent to AM or PM, as appropriate (for use
            with %I), update tm_hour

    %r      time in AM/PM notation, this is equivalent to %I:%M:%S %p,
            update tm_hour, tm_min, and tm_sec

    %R      hour and minutes, equivalent to %H:%M, update tm_hour and
            tm_min

    %S      second (0-59), update tm_sec

    %t      TAB character

    %T      time, equivalent to %H:%M:%S, update tm_hour, tm_min,
            tm_sec

    %U      week number of the year, the first day of the week is
            Sunday (0-53), currently ignored

    %w      weekday, the first day of the week is Sunday (0-6), update
            tm_wday

    %W      week number of the year, the first day of the week is
            Monday (0-53), currently ignored

    %x      locale's date representation, update tm_year, tm_mon, and
            tm_mday

    %X      locale's time representation, update tm_hour, tm_min, and
            tm_sec

    %y      year without century (0-99, mapping to 2000-2069,
            1970-1999), update tm_year

    %Y      year with century (1970-2106), update tm_year

    If % is followed by a character not listed above, the results are
    undefined.

  Restrictions:

    Case is currently not ignored for non-ASCII characters.  %p must
    currently come after %I in the format string.

    As behavior of other implementations of strptime() is quite
    varying, this implementation of strptime() does not behave like
    most other implementations of strptime().  strptime() is not
    portable.

  Return value:

    If successful, strptime() returns a pointer to the character
    following the last character parsed.  On error, strptime() returns
    NULL.

  See also: setlocale(), sscanf(), strftime()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strrchr (const char *string, int c);

    Return a pointer to the last occurrence of the character C in the
    null-terminated string pointed to by STRING.  If there is no
    character C in that string, NULL is returned.  If C is the null
    character (0), a pointer to the terminating null character of that
    string is returned.

  Return value:

    See above.

  See also: _memrchr(), rindex(), strchr()

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

char *strrev (char *string);

    Reverse the order of the characters in the string pointed to by
    STRING.  The terminating null character remains in place.

  Return value:

    strrev() returns STRING.

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

char *strset (char *string, int c);

    Replace all the characters of the string pointed to by STRING with
    the character C.  The terminating null character is not changed.

  Return value:

    strset() returns STRING.

  See also: memset(), strnset()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

size_t strspn (const char *string1, const char *string2);

    Return the length of the initial substring of the string pointed
    to by STRING1 which consists entirely of characters in the string
    pointed to by STRING2.  That is, the index of the first character
    in the string pointed to by STRING1 which does not occur in the
    string pointed to by STRING2 is returned.  If all characters in
    the string pointed to by STRING1 also occur in the string pointed
    to by STRING2, the length of the string pointed to by STRING1 is
    returned.

  Return value:

    See above.

  See also: strcspn(), strpbrk()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strstr (const char *string1, const char *string2);

    Return a pointer to the first occurrence of the string pointed to
    by STRING2 in the string pointed to by STRING1.  If the length of
    the string pointed to by STRING2 is zero, STRING1 is returned.  If
    the string pointed to by STRING2 is not a substring of the string
    pointed to by STRING1, NULL is returned.

  Return value:

    See above.

  See also: strchr()

------------------------------------------------------------------------------
#include <stdlib.h>                                                  [C90 C9X]

double strtod (const char *string, char **end_ptr);
float strtof (const char *string, char **end_ptr);
long double strtold (const char *string, char **end_ptr);

    strtod() converts a character string to a double.  Leading white
    space is skipped.  strtod() stops at the first character that
    cannot be converted.  The string pointed to by STRING is expected
    to have one of the following forms:

        [<whitespace>] [+|-] [<digits>] [.<digits>] [[d|D|e|E]
        [+|-] <digits>]
        [<whitespace>] [+|-] INF
        [<whitespace>] [+|-] INFINITY
        [<whitespace>] [+|-] NAN
        [<whitespace>] [+|-] NAN(...)

    The decimal point character of the current locale is used.  Letter
    case is ignored for INF, INFINITY, and NAN.  Digits, letters, and
    the underscore character can occur in the parentheses following
    `NAN'.

    If END_PTR is not NULL and the conversion has been performed, a
    pointer to the first character which cannot be converted is stored
    to the object pointed to by END_PTR.  If END_PTR is not NULL and
    no conversion has been performed, STRING is stored to the object
    pointed to by END_PTR.

    If no conversion could be performed, strtod() doesn't change errno
    and returns 0.0 (you can examine the pointer stored to the object
    pointed to by END_PTR to recognize this case).  On overflow,
    strtod() sets errno to ERANGE and returns HUGE_VAL or -HUGE_VAL,
    depending on the sign of the number.  On underflow, strtod() sets
    errno to ERANGE and returns 0.0.

    The strtold() function proposed for C9X uses the long double
    format.  On overflow, strtold() returns HUGE_VALL or -HUGE_VALL,
    depending on the sign of the number.

    The strtof() function proposed for C9X uses the float format.  On
    overflow, strtof() returns HUGE_VALF or -HUGE_VALF, depending on
    the sign of the number.

  Return value:

    strtod(), strtof(), and strtold() return the converted value.  If
    no number is recognized, strtod(), strtof(), and strtold() return
    0.0.  On overflow, strtod() returns HUGE_VAL or -HUGE_VAL.  On
    overflow, strtof() returns HUGE_VALF or -HUGE_VALF.  On overflow,
    strtold() returns HUGE_VALL or -HUGE_VALL.  On underflow,
    strtod(), strtof(), and strtold() return 0.0.

  See also: atof(), setlocale(), sscanf(), strtol()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

char *strtok (char *string1, const char *string2);

    Return a pointer to the next token in the string pointed to by
    STRING1.  The characters of the string pointed to by STRING2 are
    the set of delimiting characters.  Tokens in the string pointed to
    by STRING1 are separated by one or more characters from the string
    pointed to by STRING2.

    The first call to strtok() for STRING1 skips leading delimiters
    and returns a pointer to the first token.  To get the next token
    of the string pointed to by STRING1, call strtok() with a NULL
    argument for STRING1.  STRING2, a pointer the set of delimiters,
    may be different on subsequent calls.

    strtok() modifies the string pointed to by STRING1 by inserting
    null characters for terminating tokens.  Thus, the pointer
    returned by strtok() points to a null-terminated token.

    If there are no more tokens, NULL is returned.

  Return value:

    See above.

  See also: strpbrk()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

long strtol (const char *string, char **end_ptr, int radix);

    Convert a character string to a signed long integer.  The string
    pointed to by STRING should have the following format:

        [<whitespace>] [+|-] [|0|0x|0X] <digits>

    Leading white space (as defined by isspace()) is skipped.  RADIX
    is the number base used for conversion.  It must either be between
    2 and 36 or be zero.

    If RADIX is 0, the number base is derived from the format of the
    number: If the number starts with 0x, base 16 is used.  If the
    number starts with 0 (not followed by x), base 8 is used.  If the
    number does not start with 0, base 10 is used.

    strtol() stops at the first character that cannot be converted.
    If END_PTR is not NULL and the conversion has been performed, a
    pointer to the first character which cannot be converted is stored
    to the object pointed to by END_PTR.  If END_PTR is not NULL and
    no conversion has been performed, STRING is stored to the object
    pointed to by END_PTR.

    strtol() doesn't change errno and returns 0 if no conversion could
    be performed (you can examine the pointer stored to the object
    pointed to by END_PTR to recognize this case).  On overflow,
    strtol() sets errno to ERANGE and returns LONG_MIN or LONG_MAX
    (depending on the sign character).  If RADIX is out of range,
    strtol() sets errno to EDOM and returns 0.

  Return value:

    strtol() returns the converted value.  If no number is recognized
    or if RADIX is invalid, strtol() returns 0.  On overflow, strtol()
    returns LONG_MIN or LONG_MAX.

  See also: atol(), isspace(), _ltoa(), _strtoll(), strtoul(),
            sscanf()

  Example:

    int read_long (char **ptr, long *dst)
    {
      char *p;
      long n;
    
      errno = 0;
      n = strtol (*ptr, &p, 0);
      if (errno != 0 || p == *ptr)
        return 0;                   /* Failure */
      *dst = n; *ptr = p;
      return 1;                     /* Success */
    }

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

long long _strtoll (const char *string, char **end_ptr, int radix);

    Convert a character string to a signed long long integer.  The
    string pointed to by STRING should have the following format:

        [<whitespace>] [+|-] [|0|0x|0X] <digits>

    Leading white space (as defined by isspace()) is skipped.  RADIX
    is the number base used for conversion.  It must either be between
    2 and 36 or be zero.

    If RADIX is 0, the number base is derived from the format of the
    number: If the number starts with 0x, base 16 is used.  If the
    number starts with 0 (not followed by x), base 8 is used.  If the
    number does not start with 0, base 10 is used.

    _strtoll() stops at the first character that cannot be converted.
    If END_PTR is not NULL and the conversion has been performed, a
    pointer to the first character which cannot be converted is stored
    to the object pointed to by END_PTR.  If END_PTR is not NULL and
    no conversion has been performed, STRING is stored to the object
    pointed to by END_PTR.

    _strtoll() doesn't change errno and returns 0 if no conversion
    could be performed (you can examine the pointer stored to the
    object pointed to by END_PTR to recognize this case).  On
    overflow, _strtoll() sets errno to ERANGE and returns
    LONG_LONG_MIN or LONG_LONG_MAX (depending on the sign character).
    If RADIX is out of range, _strtoll() sets errno to EDOM and
    returns 0.

  Return value:

    _strtoll() returns the converted value.  If no number is
    recognized or if RADIX is invalid, strtol() returns 0.  On
    overflow, _strtoll() returns LONG_LONG_MIN or LONG_LONG_MAX.

  See also: _atoll(), isspace(), _lltoa(), strtol(), _strtoull(),
            sscanf()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

unsigned long strtoul (const char *string, char **end_ptr, int radix);

    Convert a character string to an unsigned long integer.  The
    string pointed to by STRING should have the following format:

        [<whitespace>] [+|-] [|0|0x|0X] <digits>

    Leading white space (as defined by isspace()) is skipped.  RADIX
    is the number base used for conversion.  It must either be between
    2 and 36 or be zero.

    If RADIX is 0, the number base is derived from the format of the
    number: If the number starts with 0x, base 16 is used.  If the
    number starts with 0 (not followed by x), base 8 is used.  If the
    number does not start with 0, base 10 is used.

    strtoul() stops at the first character that cannot be converted.
    If END_PTR is not NULL and the conversion has been performed, a
    pointer to the first character which cannot be converted is stored
    to the object pointed to by END_PTR.  If END_PTR is not NULL and
    no conversion has been performed, STRING is stored to the object
    pointed to by END_PTR.

    strtoul() returns 0 if no conversion could be performed (errno
    will not be changed).  On overflow, strtoul() sets errno to ERANGE
    and returns ULONG_MAX.  If RADIX is out of range, strtoul() sets
    errno to EDOM and returns 0.

  Return value:

    strtoul() returns the converted value.  If no number is recognized
    or if RADIX is invalid, strtoul() returns 0.  On overflow,
    strtoul() returns ULONG_MAX.

  See also: isspace(), strtol(), _strtoull(), sscanf(), _ultoa()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

unsigned long long _strtoull (const char *string, char **end_ptr, int radix);

    Convert a character string to an unsigned long long integer.  The
    string pointed to by STRING should have the following format:

        [<whitespace>] [+|-] [|0|0x|0X] <digits>

    Leading white space (as defined by isspace()) is skipped.  RADIX
    is the number base used for conversion.  It must either be between
    2 and 36 or be zero.

    If RADIX is 0, the number base is derived from the format of the
    number: If the number starts with 0x, base 16 is used.  If the
    number starts with 0 (not followed by x), base 8 is used.  If the
    number does not start with 0, base 10 is used.

    _strtoull() stops at the first character that cannot be converted.
    If END_PTR is not NULL and the conversion has been performed, a
    pointer to the first character which cannot be converted is stored
    to the object pointed to by END_PTR.  If END_PTR is not NULL and
    no conversion has been performed, STRING is stored to the object
    pointed to by END_PTR.

    _strtoull() returns 0 if no conversion could be performed (errno
    will not be changed).  On overflow, _strtoull() sets errno to
    ERANGE and returns ULONG_LONG_MAX.  If RADIX is out of range,
    _strtoull() sets errno to EDOM and returns 0.

  Return value:

    _strtoull() returns the converted value.  If no number is
    recognized or if RADIX is invalid, _strtoull() returns 0.  On
    overflow, _strtoull() returns ULONG_LONG_MAX.

  See also: isspace(), _strtoll(), strtoul(), sscanf(), _ulltoa()

------------------------------------------------------------------------------
#include <string.h>                                                       [PC]

char *strupr (char *string);

    Convert the string pointed to by STRING to upper case.  The
    characters 'a' through 'z' are mapped to the characters 'A'
    through 'Z'.  All other characters are not changed.

  Return value:

    strupr() returns STRING.

  See also: strlwr()

------------------------------------------------------------------------------
#include <string.h>                                                      [C90]

size_t strxfrm (char *string1, const char *string2, size_t n);

    Transform the string pointed to by STRING2 according to the
    LC_COLLATE category of the current locale and copy the result to
    the array pointed to by STRING1.  After applying strxfrm(), you
    can use strcmp() for comparing the strings; applying strcmp() to
    strings transformed by strxfrm() is equivalent to calling
    strcoll() on the original strings.  At most N characters
    (including the terminating null character) are stored to the array
    pointed to by STRING1.  STRING1 can be NULL if N is zero.

  Return value:

    strxfrm() returns the number of characters in the transformed
    string (excluding the terminating null character), even if that
    number exceeds N.  If the return value is equal to or greater than
    N, the contents of the string pointed to by STRING1 are
    indeterminate.

  Restrictions:

    Currently, locale is ignored: strxfrm() copies the characters
    without modifications.

  See also: setlocale(), strcoll()

  Example:

    /* Transform a string, allocating memory with malloc(). */
    char *xfrm (const char *s)
    {
      size_t len = strxfrm (NULL, s, 0);
      char *t = malloc (len + 1);
      if (t != NULL)
        strxfrm (t, s, len + 1);
      return t;
    }

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [UNIX]

void swab (const void *src, void *dst, size_t n);

    Copy N bytes from SRC to DST, swapping each pair of adjacent
    bytes.  N must be even.

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

char _swchar (void);

    Retrieve the current switch character.  If the switch character
    has been changed to '-', _swchar() returns '-'.  Otherwise,
    _swchar() returns 0.  In this case, you should use the standard
    switch character '/'.

  Return value:

    See above.

  See also: getopt()

------------------------------------------------------------------------------
#include <unistd.h>                                                  [POSIX.1]

long sysconf (int name);

    Return the current value of the configurable system limit or
    option NAME.  NAME is one of the following constants:

    _SC_ARG_MAX
            corresponds to ARG_MAX (length of arguments and
            environment for exec*(), in bytes)

    _SC_CHILD_MAX
            corresponds to CHILD_MAX (number of simultaneous processes
            per real user ID)

    _SC_CLK_TCK
            number of clock ticks per second, for times()

    _SC_NGROUPS_MAX
            corresponds to NGROUPS_MAX (maximum number of simultaneous
            supplementary group IDs per process)

    _SC_OPEN_MAX
            corresponds to OPEN_MAX (number of files that one process
            can have open at one time)

    _SC_STREAM_MAX
            corresponds to STREAM_MAX (number of streams that one
            process can have open at one time)

    _SC_TZNAME_MAX
            corresponds to TZNAME_MAX (number of bytes supported for
            the name of a time zone)

    _SC_JOB_CONTROL
            corresponds to _POSIX_JOB_CONTROL (defined if the
            implementation supports job control -- emx doesn't)

    _SC_SAVED_IDS
            corresponds to _POSIX_SAVED_IDS (defined if each process
            has a saved set-user-ID and a saved set-group-ID -- not
            true for emx)

    _SC_VERSION
            corresponds to _POSIX_VERSION (the integer 199009L)

    See POSIX.1 for more details.

  Return value:

    If NAME is invalid, sysconf() sets errno to EINVAL and returns -1.
    If NAME is associated with functionality that is not supported by
    the system, sysconf() returns -1 and does not change errno.
    Otherwise, sysconf() returns the current value of the variable.

  Restrictions:

    sysconf() currently returns just the POSIX.1 minimum values.

  See also: fpathconf(), pathconf()

------------------------------------------------------------------------------
#include <stdlib.h>                                                    [emx *]

int _syserrno (void);

    Return the OS/2 or DOS error code for the last system call of the
    current thread.  If there was no error, 0 is returned.  If the
    last system call hasn't called an OS/2 or DOS function, 0 is
    returned.

  Return value:

    See above.

  Restrictions:

    _syserrno() is not implemented under DOS.  _syserrno() is not
    supported with the system call library sys.lib (-Zsys).

------------------------------------------------------------------------------
#include <process.h>                                                     [C90]

int system (const char *name);

    Execute a command by passing it to the command interpreter.  NAME
    is a pointer to a string containing the command name.  system()
    uses the COMSPEC environment variable for locating cmd.exe or
    command.com, respectively.  The COMSPEC environment variable can
    be overriden by setting the EMXSHELL environment variable.  The
    PATH environment variable is not used for locating cmd.exe.  If
    the argument is "", an interactive shell will be started.  If the
    argument is NULL, system() only checks whether cmd.exe or
    command.com, respectively, can be found.

    As command.com is used under DOS, the command line is restricted
    to about 123 characters.  If you don't need a command shell, use
    spawn*() instead of system().  It's a bad idea to run emx programs
    using system() -- not tested.  You must use the -p emx option when
    using system() under DOS, see `Using emx options'.

    The system() function passes the /c option to the command
    processor if COMSPEC (or EMXSHELL) points to cmd.exe, 4os2.exe,
    command.com or 4dos.com.  Otherwise, system() assumes that a
    Unix-like shell is to be used and passes the -c option.

  Return value:

    If system() fails, errno is set and -1 is returned.  If the
    argument is NULL and the command processor can be found, 0 is
    returned.  In all other cases, the return code of the command
    processor is returned.  The return code of the program run by the
    command processor is returned by cmd.exe but not by command.com.
    command.com always returns 0.

  See also: popen(), spawn*()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [OS/2]

void *_tcalloc (size_t elements, size_t size);

    Allocate a block of memory big enough for holding ELEMENTS
    elements of SIZE bytes each.  The block will not cross a 64 KByte
    boundary unless SIZE is greater than 65536.  If SIZE is greater
    than 65536, the block will be aligned on a 64 KByte boundary.
    _tcalloc() fills the block with zeros.  If there is an error,
    _tcalloc() returns NULL.

  Return value:

    _tcalloc() returns a pointer to a newly allocated block of memory.
    On error, _tcalloc() returns NULL.

  Restrictions:

    If you replace the emx malloc() implementation with a malloc()
    implementation (GNU malloc, for instance) that has not _tmalloc()
    etc. built in, you have to link with the tmalloc library
    (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
    etc.

  See also: calloc(), _tfree(), _tmalloc(), _utcalloc(), _utdefault()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int tcdrain (int handle);

    tcdrain() waits until all output written to the terminal
    associated with the file descriptor HANDLE has been transmitted.

  Return value:

    tcdrain() returns 0 if successful.  Otherwise, tcdrain() sets
    errno and returns -1.

  Errors:

    EBADF   HANDLE is not a valid open file descriptor.

    ENOTTY  HANDLE is not associated with a terminal.

  Implementation-defined behavior:

    tcdrain() currently does nothing and always succeeds.

  Restrictions:

    tcdrain() is not available with the system call library sys.lib
    (-Zsys).

  See also: tcflow(), tcflush(), tcsendbreak(), tcsetattr()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int tcflow (int handle, int action);

    tcflow() suspends or resumes transmission or reception of data on
    the terminal associated with the file descriptor HANDLE, depending
    on ACTION:

    TCIOFF  Transmit a VSTOP character to suspend input.

    TCION   Transmit a VSTART character to resume suspended input.

    TCOOFF  Suspend output.

    TCOON   Resume suspended output.

    See `General terminal interface' for details.

  Return value:

    tcflow() returns 0 if successful.  Otherwise, tcflow() sets errno
    and returns -1.

  Errors:

    EBADF   HANDLE is not a valid open file descriptor.

    ENOTTY  HANDLE is not associated with a terminal.

  Implementation-defined behavior:

    tcflow() currently does nothing and always succeeds.

  Restrictions:

    tcflow() is not available with the system call library sys.lib
    (-Zsys).

  See also: tcdrain(), tcflush(), tcsendbreak(), tcsetattr()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int tcflush (int handle, int queue);

    tcflush() flushes the input and/or output queues of the terminal
    associated with the file descriptor HANDLE, depending on QUEUE:

    TCIFLUSH
            Flush the input queue.

    TCOFLUSH
            Flush the output queue.

    TCIOFLUSH
            Flush the both the input and output queues.

  Return value:

    tcflush() returns 0 if successful.  Otherwise, tcflush() sets
    errno and returns -1.

  Errors:

    EBADF   HANDLE is not a valid open file descriptor.

    EINVAL  QUEUE is not valid.

    ENOTTY  HANDLE is not associated with a terminal.

  Implementation-defined behavior:

    tcflush() currently works on the keyboard, only.

  Restrictions:

    tcflush() is not available with the system call library sys.lib
    (-Zsys).

    Under DOS, the value of the HANDLE argument must be 0.

  See also: tcdrain(), tcflow(), tcsendbreak(), tcsetattr()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int tcgetattr (int handle, struct termios *ptermios);

    Store the parameters of the terminal associated with the file
    descriptor HANDLE to the object pointed to by PTERMIOS.

    See `General terminal interface' for details.

  Return value:

    tcgetattr() returns 0 if successful.  Otherwise, tcgetattr() sets
    errno and returns -1.

  Errors:

    EBADF   HANDLE is not a valid open file descriptor.

    ENOTTY  HANDLE is not associated with a terminal.

  Implementation-defined behavior:

    Currently, errno is set to ENOTTY instead of EBADF if HANDLE is
    out of range.

  Restrictions:

    tcgetattr() is not available with the system call library sys.lib
    (-Zsys).

    Under DOS, the value of the HANDLE argument must be 0.

  See also: cfgetispeed(), cfgetospeed(), tcsetattr()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int tcsendbreak (int handle, int duration);

    tcsendbreak() sends a `break' on an asynchronous line.  The
    duration of the `break' is controlled by DURATION in a
    not-yet-specified way.  If applied to a handle which is not
    associated with an asynchronous line, tcsendbreak() does nothing.

  Return value:

    tcsendbreak() returns 0 if successful.  Otherwise, tcsendbreak()
    sets errno and returns -1.

  Errors:

    EBADF   HANDLE is not a valid open file descriptor.

    ENOTTY  HANDLE is not associated with a terminal.

  Implementation-defined behavior:

    tcsendbreak() currently does nothing and always succeeds.

  Restrictions:

    tcsendbreak() is not available with the system call library
    sys.lib (-Zsys).

  See also: tcdrain(), tcflow(), tcflush(), tcsetattr()

------------------------------------------------------------------------------
#include <termios.h>                                               [POSIX.1 *]

int tcsetattr (int handle, int options, const struct termios *ptermios);

    Set the parameters of the terminal associated with the file
    descriptor HANDLE from the object pointed to by PTERMIOS.  OPTIONS
    must be one of the following symbols:

    TCSANOW
            The change is performed immediately.

    TCSADRAIN
            The change is performed after all output has been
            transmitted.

    TCSAFLUSH
            The change is performed after all output has been
            transmitted.  The input queue is flushed before performing
            the change.

    See `General terminal interface' for details.

  Return value:

    tcsetattr() returns 0 if successful.  Otherwise, tcsetattr() sets
    errno and returns -1.

  Errors:

    EBADF   HANDLE is not a valid open file descriptor.

    EINVAL  OPTIONS is not valid or an attempt was made to change an
            attribute to an unsupported value.

    ENOTTY  HANDLE is not associated with a terminal.

  Implementation-defined behavior:

    Currently, errno is set to ENOTTY instead of EBADF if HANDLE is
    out of range.

  Restrictions:

    tcsetattr() is not available with the system call library sys.lib
    (-Zsys).

    Under DOS, the value of the HANDLE argument must be 0.

  See also: cfsetispeed(), cfsetospeed(), tcdrain(), tcflush(),
            tcgetattr()

------------------------------------------------------------------------------
#include <io.h>                                                           [PC]

long tell (int handle);

    tell() returns the current position of the file pointer of HANDLE.
    If there is an error, tell() returns -1.

  Return value:

    See above.

  See also: lseek()

------------------------------------------------------------------------------
#include <stdio.h>                                                      [UNIX]

char *tempnam (const char *dir, const char *prefix);

    Generate a file name suitable for a temporary file without
    overwriting an existing file.  tempnam() returns a pointer to a
    string allocated by malloc().  If the TMP environment variable is
    set and the directory specified by TMP exists, that directory is
    used.  Otherwise, the DIR argument is used.  If DIR is NULL or the
    directory whose name is in the string pointed to by DIR does not
    exist, P_tmpdir as defined in <stdio.h> is used.  If even this
    fails, NULL is returned.  The name of the file will start with the
    string pointed to by PREFIX.  The string pointed to by PREFIX must
    not be longer than 5 characters.

  Return value:

    See above.

  See also: tmpnam()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [OS/2]

void _tfree (void *mem);

    Deallocate a block of memory allocated by _tmalloc(), _tcalloc()
    or _trealloc().  MEM points to the block of memory.  MEM must have
    been returned by _tmalloc(), _tcalloc() or _trealloc().  Do not
    use MEM after calling _tfree().  If MEM is NULL, _tfree() does
    nothing.

  Restrictions:

    If you replace the emx malloc() implementation with a malloc()
    implementation (GNU malloc), for instance) that has not _tmalloc()
    etc. built in, you have to link with the tmalloc library
    (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
    etc.

  See also: free(), _tcalloc(), _tmalloc(), _trealloc()

------------------------------------------------------------------------------
#include <malloc.h>                                                    [VAC++]

int _theapmin (void);

    The _theapmin() function returns unused memory of the tiled
    default heap to the operating system.  The heap is never made
    smaller than its initial size.  Calling _theapmin() is equivalent
    to calling _uheapmin() for the tiled default heap.

  Return value:

    0       success

    -1      error

  See also: brk(), _heapchk(), sbrk(), _heapmin(), _uheapmin(),
            _utdefault()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [OS/2]

void **_threadstore (void);

    The _threadstore() function returns the address of a pointer to
    thread-specific user-defined data.  Initially, that pointer is
    NULL.  To create thread-specific data, allocate a memory object
    (using malloc(), for instance) and assign the address of that
    memory object to the location returned by _threadstore():

        p = malloc (sizeof (struct user_data));
        *_threadstore() = p;

    To access a thread-specific variable, use _threadstore() to get
    the pointer to the memory object:

        x = (*_threadstore)->myvar;

  Return value:

    _threadstore() returns the address of a pointer located in the
    thread-specific data block of the emx C library.

  Restrictions:

    _threadstore() is available only in the multithread libraries
    (-Zmt, -Zmts, or -Zmtd).

  See also: _beginthread(), _gettid(), _threadid

------------------------------------------------------------------------------
#include <time.h>                                                        [C90]

time_t time (time_t *ptr);

    Return the number of seconds elapsed since 00:00:00 1-Jan-1970
    Coordinated Universal Time (UTC, GMT).  The system time is
    converted according to the local timezone.  If PTR is not NULL,
    the result is also stored to the variable pointed to by PTR.

  Return value:

    See above.

  See also: ftime(), gettimeofday(), gmtime(), localtime(),
            settimeofday()

------------------------------------------------------------------------------
#include <time.h>                                                       [UNIX]
#include <sys/times.h>
#include <sys/param.h>  /* for HZ */

long times (struct tms *buffer);

    Return the current time in CLK_TCK fractions of a second since
    00:00:00 1-Jan-1970 Coordinated Universal Time (UTC, GMT).  Also
    sets the tms_utime field of BUFFER to the number of HZ fractions
    of a second the process has been running.  The other fields are
    set to 0.

  Return value:

    times() returns the current time in CLK_TCK fractions of a second
    since 00:00 1-Jan-1970 UTC.

  Restrictions:

    The return value is unusable due to overflow.

  See also: clock(), time()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [OS/2]

void *_tmalloc (size_t size);

    Allocate a block of memory big enough for holding SIZE bytes.  The
    block will not cross a 64 KByte boundary unless SIZE is greater
    than 65536.  If SIZE is greater than 65536, the block will be
    aligned on a 64 KByte boundary.  Therefore, blocks allocated with
    _tmalloc() can be used with 16-bit functions.  If there is an
    error, _tmalloc() returns NULL.  If SIZE is 0, zero bytes of
    memory are allocated, the return value will be unequal NULL.  Use
    _tfree() to deallocate a block of memory allocated by _tmalloc().

    As _tmalloc() causes additional heap fragmentation, you should not
    use _tmalloc() unless you need an aligned block.

  Return value:

    _tmalloc() returns a pointer to a newly allocated block of memory.
    On error, _tmalloc() returns NULL.

  Restrictions:

    If you replace the emx malloc() implementation with a malloc()
    implementation (GNU malloc, for instance) that has not _tmalloc()
    etc. built in, you have to link with the tmalloc library
    (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
    etc.

  See also: malloc(), _tcalloc(), _tfree(), _trealloc(), _utdefault(),
            _utmalloc()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

FILE *tmpfile (void);

    Create and open a temporary file.  The file is opened in "w+b"
    mode.  The file will automatically be deleted when the stream is
    closed with fclose() or at program termination.

  Return value:

    On success, tmpfile() returns a pointer to the stream associated
    with the temporary file.  If the file cannot be created, tmpfile()
    returns NULL.

  Implementation-defined behavior:

    The name of the file is created as if tmpnam() were called.

    The temporary file will not be deleted if the program terminates
    abnormally.

  See also: fclose(), _rmtmp(), tmpnam()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

char *tmpnam (char *string);

    Create a unique file name and store it to the array pointed to by
    STRING.  tmpnam() generates a different file name each time it is
    called, up to TMP_MAX times.  If STRING is NULL, a static buffer
    is used which will be overwritten by subsequent calls.  If STRING
    is not NULL, it must point to an array of at least L_tmpnam
    characters.

  Return value:

    On success, tmpnam() returns a pointer to the new name.  On
    failure, tmpnam() returns NULL.

  Implementation-defined behavior:

    The file name is the concatenation of P_tmpdir and a sequence of
    digits.

  Hints:

    Use tmpfile() if you need a temporary file but don't need the name
    of that file.  Note that tmpnam() is subject to a race condition:
    other processes may use the same temporary file name before you
    have a chance to create the temporary file.

  See also: tempnam(), tmpfile(), mktemp()

------------------------------------------------------------------------------
#include <ctype.h>                                                       [C90]

int tolower (int c);
int toupper (int c);

    tolower() converts the character C to lower case, if it is an
    upper-case letter.  toupper() converts the character C to upper
    case, if it is a lower-case letter.

  Return value:

    If the argument of tolower() is a character for which isupper() is
    true and there is a corresponding character for which islower() is
    true, tolower() returns the corresponding character; otherwise
    tolower() returns the argument unchanged.

    If the argument of toupper() is a character for which islower() is
    true and there is a corresponding character for which isupper() is
    true, toupper() returns the corresponding character; otherwise
    toupper() returns the argument unchanged.

  Restrictions:

    Currently, locale is ignored.

  See also: setlocale(), stricmp(), strlwr(), strupr(), _tolower(),
            _toupper()

------------------------------------------------------------------------------
#include <ctype.h>                                                      [UNIX]

int _tolower (int c);
int _toupper (int c);

    _tolower() converts the upper-case character C to lower case; C
    must be in the range 'A' through 'Z'.  _toupper() converts the
    lower-case character C to upper case; C must be in the range 'a'
    through 'z'.

  Return value:

    See above.

  See also: tolower(), toupper()

------------------------------------------------------------------------------
#include <stdlib.h>                                                     [OS/2]

void *_trealloc (void *mem, size_t size);

    Reallocate the block of memory pointed to by MEM, making it big
    enough to hold SIZE bytes.  The block will not cross a 64 KByte
    boundary unless SIZE is greater than 65536.  If SIZE is greater
    than 65536, the block will be aligned on a 64 KByte boundary.  If
    MEM is NULL, a new block of memory is allocated.  Otherwise, MEM
    must be a pointer returned by _tcalloc(), _tmalloc() or
    _trealloc(); the size of MEM is adjusted.  If MEM is non-NULL and
    SIZE is zero, the block is freed and NULL is returned.  If MEM
    cannot be expanded in-place, it is moved.  A pointer to the new,
    resized block of memory is returned.  If there is not enough
    memory available, NULL is returned.

    MEM can also be a pointer to a block of memory freed by _tfree()
    as long as calloc(), malloc(), realloc(), _tcalloc(), _tmalloc()
    and _trealloc() have not been called since freeing the block.
    Using this feature is not recommended, it may get removed in
    future implementations of _trealloc().

  Return value:

    _trealloc() returns MEM (if the block could be resized without
    moving), a pointer to a newly allocated block of memory, or NULL
    (if there wasn't enough memory).

  Restrictions:

    If you replace the emx malloc() implementation with a malloc()
    implementation (GNU malloc, for instance) that has not _tmalloc()
    etc. built in, you have to link with the tmalloc library
    (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
    etc.

  See also: realloc(), _tmalloc(), _utdefault()

------------------------------------------------------------------------------
#include <math.h>                                                        [C9X]

double trunc (double x);
long double truncl (long double x);

    Return as floating-point number X chopped to an integer by
    truncating the fractional digits (rounding toward 0).

    truncl() uses the long double format.

  Return value:

    See above.

  See also: ceil(), floor(), modf(), rint()

------------------------------------------------------------------------------
#include <io.h>                                                          [BSD]

int truncate (char *name, long length);

    Truncate a file to at most LENGTH bytes.  NAME is a pointer to a
    string containing the name of the file.  If LENGTH is greater than
    the current length of the file, the length is not changed.

  Return value:

    0       success

    -1      error

  See also: chsize(), ftruncate()

------------------------------------------------------------------------------
#include <unistd.h>                                                  [POSIX.1]

char *ttyname (int handle);

    Return a pointer to a string containing the pathname of the device
    associated with file descriptor HANDLE.

    The pointer returned by ttyname() may point to a static buffer
    which is overwritten by each call of ttyname().

  Return value:

    If successful, ttyname() returns a pointer to a null-terminated
    string.  On error, ttyname() returns NULL.

  Restrictions:

    ttyname() is not implemented for DOS.  ttyname() is not available
    with the system call library sys.lib (-Zsys).

    ttyname() is implemented for the following devices only: /dev/con,
    /dev/nul, /dev/clock$, and the devices of Holger Veit's
    xf86sup.sys device driver.

  See also: fstat(), isatty()

------------------------------------------------------------------------------
#include <time.h>                                                  [C90 VAC++]

void tzset (void);

    Set timezone according to the TZ environment variable.  The
    following global variables are set by tzset(): daylight, timezone,
    tzname.  The value of TZ has the following format:

        <TZ1>[<OFF>,[<TZ2>[,<SM>,<SW>,<SD>,<ST>,<EM>,<EW>,<ED>,<ET>,<SHIFT>]]]

    <TZ1> is the three-letter name of the standard timezone.

    <OFF> is the offset to Coordinated Universal Time; positive values
    are to the west of the Prime Meridian, negative values are to the
    east of the Prime Meridian.  The offset can be specified as hours,
    hours and minutes, or hours, minutes, and seconds.  Hours,
    minutes, and seconds are separated by colons.  If <OFF> is not
    specified, an offset of 0 will be used (this may change in the
    future).

    <TZ2> is the three-letter name of the summer timezone (daylight
    saving time).  If <TZ2> is not specified, daylight saving time
    does not apply.  If <TZ2> is specified, daylight saving time does
    apply; the remainder of the TZ's value specifies when and how to
    change to and back from daylight saving time.  <SM> through <ST>
    define, in current local time, when to switch from standard time
    to daylight saving time, <EM> through <ET> define, in current
    local time, when to switch from daylight saving time to standard
    time.  (On the southern hemisphere, the end date precedes the
    start date.)  <SHIFT> is the amount of change in seconds.

    <SM> specifies the month (1 through 12) of the change.  <SW>
    specifies the week of the change; if this value is zero, <SD>
    specifies the day of month (1 through 31).  If <SW> is positive (1
    through 4), the change occurs on weekday <SD> (0=Sunday through
    6=Saturday) of the <SW>th week of the specified month.  The first
    week of a month starts on the first Sunday of the month.  If <SW>
    is negative (-1 through -4), the change occurs on weekday <SD>
    (0=Sunday through 6=Saturday) of the -<SW>th week of the specified
    month, counted from the end of the month (that is, -1 specifies
    the last week of the month).  The last week of a month starts on
    the last Sunday of the month.  <ST> specifies the time of the
    change, in seconds.  Note that <ST> is specified in local standard
    time and <ET> is specified in local daylight saving time.
    Example:

        CET-1CED,3,-1,0,7200,10,-1,0,10800,3600

    In this example, the name of the standard time zone is CET, the
    name of the summer time zone is CED.  Daylight saving time starts
    at 2:00 on the last Sunday of March and ends at 3:00 on the last
    Sunday of October.  Time changes by one hour in daylight saving
    time.

    If no characters follow <TZ2>, the rule
    `,4,1,0,3600,10,-1,0,7200,3600' will be used: Daylight saving time
    starts at 1:00 on the first Sunday of April and ends at 2:00 on
    the last Sunday of October.  Time changes by one hour in daylight
    saving time.

    If the value of TZ is invalid, tzset() does not have any effect.

  Implementation-defined behavior:

    If TZ is not set, Coordinated Universal Time will be used.

    The three-character limit for timezone names and the weird and
    US-based definition of `first week' and `last week' are required
    for compatibility with applications compiled with VAC++.

  Restrictions:

    After changing the value of TZ by modifying environ, you should
    call tzset().  That is not required when changing TZ with
    putenv().

  See also: environ, putenv()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

Heap_t _uaddmem (Heap_t h, void *memory, size_t size, int clean);

    _uaddmem() adds memory to the heap H.  MEMORY points to the memory
    area to be added, SIZE is the size of the memory area in bytes.
    CLEAN should be _BLOCK_CLEAN if the memory area has been
    initialized to zeros; CLEAN should be !_BLOCK_CLEAN if the memory
    area contains or may contain non-zero bytes.  If the heap is
    shared, MEMORY should point to shared memory.

    If the memory area added by _uaddmem() is adjacent to (the end of)
    one of the segments of the heap, that segment will be expanded.
    Otherwise, a new segment will be created and a number of bytes of
    the memory area will be used for storing control information.

  Hints:

    Add few large memory areas instead of many small memory areas to
    minimize the total overhead of the control information added to
    the segments.  Moreover, the size of the segments limits the size
    of the blocks which can be allocated from the heap.

    Memory allocated with DosAllocMem is initialized to zeros.

  Return value:

    _uaddmem() returns H if successful.  _uaddmem() returns NULL on
    error.

  See also: sbrk(), _ucreate(), _ucreate2(), _udestroy()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

void *_ucalloc (Heap_t h, size_t elements, size_t size);

    Allocate from the heap H a block of memory big enough for holding
    ELEMENTS elements of SIZE bytes each.  _ucalloc() fills the block
    with zeros.  If there is an error, _ucalloc() returns NULL.

  Implementation-defined behavior:

    If at least one argument is zero, _ucalloc() returns a non-NULL
    pointer if there's enough space left in the heap for a block of
    the minimum size.

  Return value:

    _ucalloc() returns a pointer to a newly allocated block of memory.
    On error, _ucalloc() returns NULL.

  See also: calloc(), free(), _msize(), _udefault(), _umalloc(),
            _utcalloc()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

Heap_t _ucreate (void *memory, size_t size, int clean, unsigned type,
                 void *(*alloc_fun)(Heap_t, size_t *, int *),
                 void (*release_fun)(Heap_t, void *, size_t));

    _ucreate() creates a heap in the memory area pointed to by MEMORY
    of size SIZE bytes.  SIZE must be at least _HEAP_MIN_SIZE.  CLEAN
    should be _BLOCK_CLEAN if the memory area has been initialized to
    zeros; CLEAN should be !_BLOCK_CLEAN if the memory area contains
    or may contain non-zero bytes.  TYPE specifies the type of the
    heap: _HEAP_REGULAR (regular, not tiled) or _HEAP_TILED.  All
    memory allocated from a tiled heap will be appropriately aligned
    (tiled) for 16-bit functions.  In addition to _HEAP_REGULAR or
    _HEAP_TILED, TYPE may include _HEAP_SHARED (using the | operator)
    if MEMORY points to shared memory.  If _HEAP_SHARED is set, the
    heap can be shared between processes.  The remaining two arguments
    are pointers to callback functions for allocating and releasing
    additional memory objects (segments) for the heap.  Any or all of
    these arguments may be NULL to indicate that no callback function
    is provided.  _ucreate() returns a pointer to the new heap or, on
    error, NULL.

    Before the new heap can be used, _uopen() must be called.  To
    destroy the heap, call _uclose() and _udestroy(), then deallocate
    the memory area pointed to by MEMORY if appropriate.  You can use
    the new heap as default heap by calling _udefault() or as tiled
    default heap by calling _utdefault().

    The function pointed to by ALLOC_FUN is called to allocate more
    memory for the heap.  See _ucreate2() for details.  If ALLOC_FUN
    is NULL, the size of the heap is fixed; if the initial size is
    exhausted, allocation will fail.

    The function pointed to by RELEASE_FUN is called to deallocate
    memory memory allocated by the function pointed to by ALLOC_FUN.
    See _ucreate2() for details.  If RELEASE_FUN is NULL, _udestroy()
    and _uheapmin() won't release memory.

    _ucreate2() is equivalent to _ucreate() with NULL passed for
    EXPAND_FUN and SHRINK_FUN.

  Return value:

    _ucreate() returns a pointer to the new heap if successful.
    _ucreate() returns NULL on error.

  See also: sbrk(), _ucreate2(), _udefault(), _udestroy(),
            _uheapchk(), _umalloc(), _uopen(), _utdefault()

  Example:

    #define INCL_DOSMEMMGR
    #include <os2.h>
    #include <umalloc.h>
    
    Heap_t create_shared_heap (const char *name, size_t size)
    {
      ULONG rc;
      void *mem;
      Heap_t h;
    
      rc = DosAllocSharedMem (&mem, name, size,
                              PAG_COMMIT | PAG_READ | PAG_WRITE);
      if (rc != 0)
        return NULL;
      h = _ucreate (mem, size, !_BLOCK_CLEAN, _HEAP_REGULAR | _HEAP_SHARED,
                    NULL, NULL);
      if (h == NULL)
        DosFreeMem (mem);
      return h;
    }

------------------------------------------------------------------------------
#include <umalloc.h>                                                     [emx]

Heap_t _ucreate2 (void *memory, size_t size, int clean, unsigned type,
                  void *(*alloc_fun)(Heap_t, size_t *, int *),
                  void (*release_fun)(Heap_t, void *, size_t),
                  int (*expand_fun)(Heap_t, void *, size_t, size_t *, int *),
                  void (*shrink_fun)(Heap_t, void *, size_t, size_t *));

    _ucreate2() creates a heap in the memory area pointed to by MEMORY
    of size SIZE bytes.  SIZE must be at least _HEAP_MIN_SIZE.  CLEAN
    should be _BLOCK_CLEAN if the memory area has been initialized to
    zeros; CLEAN should be !_BLOCK_CLEAN if the memory area contains
    or may contain non-zero bytes.  TYPE specifies the type of the
    heap: _HEAP_REGULAR (regular, not tiled) or _HEAP_TILED.  All
    memory allocated from a tiled heap will be appropriately aligned
    (tiled) for 16-bit functions.  In addition to _HEAP_REGULAR or
    _HEAP_TILED, TYPE may include _HEAP_SHARED (using the | operator)
    if MEMORY points to shared memory.  If _HEAP_SHARED is set, the
    heap can be shared between processes.  The remaining four
    arguments are pointers to callback functions for allocating,
    releasing, expanding, or shrinking additional memory objects
    (segments) for the heap.  Any or all of these arguments may be
    NULL to indicate that no callback function is provided.
    _ucreate2() returns a pointer to the new heap or, on error, NULL.

    Before the new heap can be used, _uopen() must be called.  To
    destroy the heap, call _uclose() and _udestroy(), then deallocate
    the memory area pointed to by MEMORY if appropriate.  You can use
    the new heap as default heap by calling _udefault() or as tiled
    default heap by calling _utdefault().  You can add more memory to
    a heap with _uaddmem().

    The function pointed to by ALLOC_FUN is called to allocate more
    memory for the heap:

        void *my_alloc (Heap_t H, size_t *PSIZE, int *PCLEAN);

    H points to the heap to be expanded.  Note that the heap is
    locked, so passing H to a heap-specific library function (except
    for _uheap_type()) will cause a deadlock.  If the heap is shared,
    the function shall allocate shared memory.  The function can call
    _uheap_type() to query the type of memory required.  PSIZE points
    to an object containing the desired size of the memory area to be
    allocated.  The function may allocate more memory than requested;
    it's recommended to allocate a multiple of 65536 bytes.  The
    function may also allocate less memory than requested; however, it
    must not do so twice in a row.  This can be used to fill gaps
    caused by non-contiguous memory allocation.  The function shall
    store to the object pointed to by PSIZE the actual number of bytes
    allocated.  Moreover, the function shall store _BLOCK_CLEAN or
    !_BLOCK_CLEAN to the object pointed to by PCLEAN depending on
    whether the memory area has been initialized to zeros or not,
    respectively.  The function shall return a pointer to the memory
    area it has allocated or NULL if the allocation request could not
    be satisfied.  If the function returns a pointer to a memory area
    adjacent to (the end of) another memory area of the heap, that
    memory area will be expanded, so that blocks spanning both memory
    areas can be allocated.

    If ALLOC_FUN is NULL, the size of the heap is fixed; if the
    initial size is exhausted, allocation will fail.  However, you can
    add more memory to a heap with _uaddmem().

    The function pointed to by RELEASE_FUN is called to deallocate
    memory memory allocated by the function pointed to by ALLOC_FUN:

        void my_release (Heap_t H, void *MEMORY, size_t SIZE);

    H points to the heap for which the memory area has been allocated.
    Note that the heap is locked, so passing H to a heap-specific
    library function will cause a deadlock.  MEMORY points to the
    memory area to be deallocated; the memory area has been allocated
    by the function pointed to by ALLOC_FUN.  SIZE is the size of the
    memory area, as reported by the function pointed to by ALLOC_FUN.

    If RELEASE_FUN is NULL, _udestroy() and _uheapmin() won't release
    memory.

    The function pointed to by EXPAND_FUN is called to expand a memory
    area of the heap:

        int my_expand (Heap_t H, void *BASE, size_t OLD_SIZE,
                       size_t *PNEW_SIZE, int *PCLEAN);

    H points to the heap to be expanded.  Note that the heap is
    locked, so passing H to a heap-specific library function will
    cause a deadlock.  BASE points to the memory area to expand; it
    points either to the initial memory area for the heap (passed as
    MEMORY to _ucreate() or _ucreate2()) or to a memory area allocated
    by the function pointed to by ALLOC_FUN.  The memory area
    currently has a size of OLD_SIZE bytes (as passed as SIZE to
    _ucreate() or _ucreate2() or as reported by the function pointed
    to by ALLOC_FUN or EXPAND_FUN).  PNEW_SIZE points to an object
    containing the size to which the memory area should be expanded.
    The function may expand the memory area more than requested; it's
    recommended to expand to a multiple of 65536 bytes.  Expanding the
    memory area less than requested is also possible, but not
    recommended.  The function shall store the actual new size of the
    memory area to the object pointed to by PNEW_SIZE.  Moreover, the
    function shall store _BLOCK_CLEAN or !_BLOCK_CLEAN to the object
    pointed to by PCLEAN depending on whether the additional memory
    has been initialized to zeros or not, respectively.  The function
    shall return a non-zero value if expansion succeeded, or 0 if if
    the expansion request could not be satisfied.

    If EXPAND_FUN is NULL, _expand() and realloc() won't attempt to
    expand the heap to expand in place the last block of a heap
    segment.  Instead, the function pointed to by ALLOC_FUN might be
    called to expand the heap non-contiguously.

    The function pointed to by SHRINK_FUN is called to shrink a memory
    area of the heap:

        void my_shrink (Heap_t H, void *MEMORY, size_t OLD_SIZE,
                        size_t *PNEW_SIZE);

    H points to the heap to be shrunk.  Note that the heap is locked,
    so passing H to a heap-specific library function will cause a
    deadlock.  MEMORY points to the memory area to shrunk; it points
    to a memory area allocated by the function pointed to by
    ALLOC_FUN.  Note that the initial memory area is never shrunk
    below its initial size.  The memory area currently has a size of
    OLD_SIZE bytes (as reported by the function pointed to by
    ALLOC_FUN or EXPAND_FUN).  PNEW_SIZE points to an object
    containing the size to which the memory area should be shrunk;
    that size might be 0.  The function may shrink the memory area
    less than requested; it's recommended to shrink to a multiple of
    65536 bytes.  The function shall store the actual new size of the
    memory area to the object pointed to by PNEW_SIZE.  If the memory
    area cannot be shrunk, the function shall store OLD_SIZE to the
    object pointed to by PNEW_SIZE.

    If SHRINK_FUN is NULL, _uheapmin() won't attempt to shrink memory
    areas; however, it will still try to deallocate memory areas if
    RELEASE_FUN is not NULL.

  Return value:

    _ucreate2() returns a pointer to the new heap if successful.
    _ucreate2() returns NULL on error.

  Implementation-defined behavior:

    If you need compatibility with VAC++, use _ucreate() instead of
    _ucreate2().  Note that VAC++ does not allow ALLOC_FUN to allocate
    less memory than requested.

  Hints:

    Memory allocated with DosAllocMem is initialized to zeros.

  See also: sbrk(), _ucreate(), _udefault(), _udestroy(), _uheapchk(),
            _uheap_type(), _umalloc(), _uopen(), _utdefault()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _uclose (Heap_t h);

    Close the heap H.  Heaps should be closed before destruction with
    _udestroy().  Shared heaps should be closed when they are no
    longer used; they should be closed by all processes before
    destruction with _udestroy().  After closing a heap, all attempts
    to access the heap will invoke undefined behavior.  _uclose()
    fails if H is the runtime heap (_RUNTIME_HEAP) or the tiled
    runtime heap.

  Return value:

    0       success

    -1      error

  See also: _ucreate(), _ucreate2(), _udestroy(), _uopen()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

Heap_t _udefault (Heap_t h);

    The _udefault() function selects the heap pointed to by H as the
    default heap of the current thread unless H is NULL.  All
    non-tiled memory allocation functions such as malloc() which don't
    take a pointer to a heap will use the heap pointed to by H if
    called in the same thread.  If H is NULL, _udefault() won't set
    the default heap.

    Initially, the runtime heap, _RUNTIME_HEAP, is used as default
    heap for all threads.  You can make _RUNTIME_HEAP again the
    default heap of the current thread by calling
    _udefault(_RUNTIME_HEAP).

  Return value:

    _udefault() returns a pointer to the previous default heap of the
    current thread.

  Hints:

    You can use _udefault() to assign a unique heap to each thread or
    to share the default heap between multiple processes.

    To obtain a pointer to the default heap of the current thread
    without selecting a new heap, call _udefault(NULL).

  See also: _mheap(), _ucreate(), _ucreate2(), _utdefault()

  Example:

    Heap_t *my_heap, old_heap;
    
    old_heap = _udefault (my_heap);
    /*...*/
    _udefault (old_heap);   /* Restore previous default heap */

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _udestroy (Heap_t h, int force);

    Destroy the heap H.  If there are any blocks of the heap in use
    (not freed) and FORCE is !_FORCE, _udestroy() fails.  If FORCE is
    _FORCE, the heap will be destroyed even if there are blocks in
    use.

    The function passed to the RELEASE_FUN argument (if not NULL) of
    _ucreate() and _ucreate2() is called to deallocate all segments
    added to the heap, that is, all memory assigned to the heap except
    for the initial memory area passed to _ucreate() or _ucreate2().

    _udestroy() fails if H is the runtime heap (_RUNTIME_HEAP) or the
    tiled runtime heap.  _uclose() should be called before
    _udestroy().  After destroying a heap, all attempts to access the
    heap will invoke undefined behavior.

  Return value:

    0       success

    -1      error

  See also: _uaddmem(), _uclose(), _ucreate(), _ucreate2(),
            _udefault(), _uheapmin()

------------------------------------------------------------------------------
#include <sys/uflags.h>                                                  [emx]

int _uflags (int mask, int new_bits);

    Set bits which control the behavior of the emx runtime library
    (emx.dll, emx.exe, or sys.lib).  Bits set in MASK are replaced
    with the matching bits of NEW_BITS:

        bits = ((bits & ~mask) | (new_bits & mask));

    If MASK is 0, the bits are not changed.  MASK should be one of the
    following symbols:

    _UF_SIG_MODEL
            Signal processing model

    _UF_SBRK_MODEL
            Memory allocation model for sbrk()

    _UF_PTRACE_MODEL
            Debugging model for ptrace()

    If MASK includes _UF_SIG_MODEL, exactly one of the following
    symbols should be used in NEW_BITS:

    _UF_SIG_EMX
            Select the emx signal processing model for signal() --
            this is the default setting

    _UF_SIG_SYSV
            Select the System V signal processing model for signal().
            The -Zsysv-signals option selects _UF_SIG_SYSV

    _UF_SIG_BSD
            Select the BSD and POSIX.1 signal processing model for
            signal().  The -Zbsd-signals option selects _UF_SIG_BSD

    If MASK includes _UF_SBRK_MODEL, exactly one of the following
    symbols should be used in NEW_BITS:

    _UF_SBRK_CONTIGUOUS
            sbrk() always allocates contiguous memory; the size of the
            heap is limited to the initial heap size.  This is the
            initial setting; however, the malloc() implementation of
            emx selects _UF_SBRK_ARBITRARY

    _UF_SBRK_MONOTONOUS
            sbrk() may allocate non-contiguous memory with increasing
            addresses; up to 16 memory objects can be used for the
            heap

    _UF_SBRK_ARBITRARY
            sbrk() may allocate non-contiguous memory with arbitrary
            addresses; up to 16 memory objects can be used for the
            heap.  The malloc() implementation of emx selects
            _UF_SBRK_ARBITRARY

    If MASK includes _UF_PTRACE_MODEL, exactly one of the following
    symbols should be used in NEW_BITS:

    _UF_PTRACE_STANDARD
            ptrace() doesn't report creation and termination of
            threads and loading and freeing of modules (DLLs);
            moreover, ptrace() doesn't support multiple threads.  This
            is the initial setting.

    _UF_PTRACE_NOTIFY
            ptrace() may report creation and termination of threads
            and loading and freeing of modules (DLLs); ptrace() does
            not support multiple threads.

    _UF_PTRACE_MULTITHREAD
            ptrace() may report creation and termination of threads
            and loading and freeing of modules (DLLs); moreover,
            ptrace() does support multiple threads; this model also
            modifies the return values of wait() and waitpid() for
            processes being under control of ptrace().

    To pass multiple values, use the | operator to combine the
    symbols.

    _uflags() should not be called by application programs.
    _UF_SBRK_MONOTONOUS and _UF_SBRK_ARBITRARY should not be selected
    unless all callers of sbrk() know how to cope with non-contiguous
    memory.

    The -Zsysv-signals and -Zbsd-signals options of GCC add startup
    code which calls _uflags().

  Return value:

    _uflags() returns the previous set of bits (ie, the set of bits
    which was in effect when _uflags() was called).

  Restrictions:

    Under DOS, memory is always contiguous, _UF_SBRK_MONOTONOUS and
    _UF_SBRK_ARBITRARY are ignored.  _UF_SIG_SYSV and _UF_SIG_BSD are
    not supported with the system call library sys.lib (-Zsys).  Under
    DOS, the _UF_PTRACE_MODEL settings are ignored.

  See also: brk(), sbrk(), sigaction(), signal(), ptrace(), ulimit(),
            wait()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _uheapchk (Heap_t h);

    _uheapchk() checks the heap pointed to by H and all its blocks for
    consistency.  Note that _uheapchk() may crash if the heap is
    corrupted.  _uheapchk() can help debugging programs which
    experience heap problems.

    Use _heapchk() to check the default heap and the tiled default
    heap.

  Return value:

    _uheapchk() returns one of the following values:

    _HEAPBADBEGIN
            The heap is corrupted.

    _HEAPBADNODE
            A block of the heap is damaged or the heap is corrupted.

    _HEAPEMPTY
            The heap has not been initialized.

    _HEAPOK
            The heap seems to be consistent.

  See also: _heapchk(), _uheapset(), _uheap_walk()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _uheapmin (Heap_t h);

    The _uheapmin() function returns unused memory of the heap H to
    the operating system.  The heap is never made smaller than its
    initial size.  The function passed to the RELEASE_FUN argument (if
    not NULL) of _ucreate() and _ucreate2() is called to deallocate
    segments of the heap which don't contain any allocated blocks.
    The function pased to the SHRINK_FUN argument (if not NULL) of
    _ucreate2() is called to shrink segments which have free space at
    the end (except for the initial memory area passed to
    _ucreate2()).

    You can use _heapmin() and _theapmin() to minimize the default
    regular heap and tiled default heap, respectively.

  Return value:

    0       success

    -1      error

  See also: brk(), _heapmin(), _uheapchk(), sbrk(), _theapmin(),
            _ucreate(), _ucreate2(), _ustats()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _uheapset (Heap_t h, unsigned fill);

    _uheapset() fills all bytes of all unused blocks of the heap
    pointed to by H with FILL.  Note that _uheapset() may crash if the
    heap is corrupted.  _uheapset() can help debugging programs which
    erroneously depend on the contents of dynamically allocated
    blocks.  _uheapchk() checks the heap more thoroughly than
    _heapset().

    Use _heapset() to fill the default heap and the tiled default
    heap.

  Return value:

    _uheapset() returns one of the following values:

    _HEAPBADBEGIN
            The heap is corrupted.

    _HEAPBADNODE
            A block of the heap is damaged or the heap is corrupted.

    _HEAPEMPTY
            The heap has not been initialized.

    _HEAPOK
            The heap seems to be consistent.

  See also: _heapset(), _uheapchk(), _uheap_walk()

------------------------------------------------------------------------------
#include <umalloc.h>                                                     [emx]

unsigned _uheap_type (Heap_t h);

    The _uheap_type() function returns the type of the heap H, as
    specified by the TYPE argument of _ucreate() and _ucreate2().

  Return value:

    The _uheap_type() function returns a combination of the
    _HEAP_REGULAR, _HEAP_TILED, and _HEAP_SHARED values.

  Hints:

    This function can be useful in allocation functions which are used
    for different heaps.

  See also: _uaddmem(), _ucreate(), _ucreate2()

------------------------------------------------------------------------------
#include <umalloc.h>                                                     [emx]

int _uheap_walk2 (Heap_t h,
                  int (*callback)(Heap_t, const void *, size_t, int, int,
                                  const char *, size_t, void *),
                  void *arg);

    Apply the function pointed to by CALLBACK to all free and used
    blocks of the heap H.  Note that the heap is locked, so using the
    heap in the callback function will cause a deadlock.  ARG will be
    passed on to the callback function.

        int my_walker (Heap_t H, const void *BLOCK, size_t SIZE, int FLAG,
                       int STATUS, const char *FNAME, size_t LINENO,
                       void *ARG);

    H points to the heap being examined, it's the same value as passed
    to _uheap_walk2().  BLOCK points to a block of SIZE bytes.  FLAG
    is either _USEDENTRY (for a used block) or _FREEENTRY (for a free
    block).  STATUS is one of the following values, describing the
    status of the block:

    _HEAPBADBEGIN
            The heap is corrupted.

    _HEAPBADNODE
            The block is damaged.

    _HEAPEMPTY
            The heap has not been initialized.

    _HEAPOK
            The heap seems to be consistent (_HEAPOK is 0).

    FNAME points to the file name of the source file in which the
    block has been allocated.  LINENO is the line number in which the
    block has been allocated.  FNAME is NULL if that information is
    not available, that is, if the object has not been allocated with
    a debugging heap function.  ARG is the same value as passed to
    _uheap_walk2().

  Return value:

    _uheap_walk2() returns the last status (see above for a list of
    values) unless the callback function returned a non-zero value.
    If the callback function returned a non-zero value, _uheap_walk2()
    returns that value.

  Restrictions:

    FNAME is current always NULL as there are no debugging heap
    functions.

  Implementation-defined behavior:

    If you need compatibility with VAC++, use _uheap_walk() instead of
    _uheap_walk2().

  Hints:

    Use an extra heap if you want to allocate memory in the callback
    function.

  See also: _heap_walk(), _uheap_walk()

------------------------------------------------------------------------------
#include <ulimit.h>                                                     [UNIX]

long ulimit (int request, ...);

    Get or set process limits.  The following REQUEST codes are
    implemented:

    UL_GFILLIM
            Return the maximum file size.  Always returns 1 << 21.

    UL_SFILLIM
            Set the maximum file size according to the second argument
            which is of type int.  Ignored.  Returns the second
            argument.

    UL_GMEMLIM
            Return the greatest possible break value.

    UL_NOFILES
            Return the number of files that can be open simultaneously
            per process.  Always returns 40.

    UL_OBJREST
            Return the number of bytes remaining in the current heap
            object.  Let N be the return value of ulimit(UL_OBJREST).
            If allocation of non-contiguous memory is disabled, up to
            N bytes can be allocated with brk() or sbrk().  Attempts
            to allocate more than N bytes will fail.  If allocation of
            non-contiguous memory has been enabled with _uflags(),
            requests for up to N bytes will yield contiguous memory;
            calling sbrk() with an argument greater than N will create
            a new heap object, leaving a gap between the previous heap
            object and the new one.

  Return value:

    See above.

  Implementation-defined behavior:

    UL_GFILLIM and UL_NOFILES return dummy values.  UL_SFILLIM is
    ignored.  UL_OBJREST is an emx extension.

  See also: brk(), sbrk(), _uflags()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

void *_umalloc (Heap_t h, size_t size);

    Allocate from the heap H a block of memory big enough for holding
    SIZE bytes.  If there is an error, _umalloc() returns NULL.  If
    SIZE is 0, zero bytes of memory are allocated, the return value
    will be unequal NULL.

  Return value:

    _umalloc() returns a pointer to a newly allocated block of memory.
    On error, _umalloc() returns NULL.

  Implementation-defined behavior:

    _umalloc(0) returns a non-NULL pointer if there's enough space
    left in the heap for a block of the minimum size.

  See also: free(), _msize(), realloc(), _ucalloc(), _umalloc(),
            _utmalloc()

------------------------------------------------------------------------------
#include <io.h>                                                         [UNIX]

int umask (int pmode);

    Set the file-permission mask of the current process to PMODE.
    Only the S_IWRITE bit is used.  Either specify S_IREAD|S_IWRITE or
    S_IREAD for PMODE.

  Return value:

    umask() returns the previous file-permission mask.

  Restrictions:

    The current file-permission mask is inherited by emx programs
    spawned under DOS.  Under OS/2, the file-permission mask is not
    yet inherited.  When spawning a non-emx program (such as
    command.com, see system()) which spawns an emx program, that
    program won't inherit the file-permission mask.

  See also: fopen(), open()

------------------------------------------------------------------------------
#include <sys/utsname.h>                                                [UNIX]

int uname (struct utsname *name);

    Store information identifying the current system to the structure
    pointed to by NAME.

  Return value:

    uname() always returns 0 (always successful).

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int ungetc (int c, FILE *stream);

    Push back the character C onto STREAM and clear the end-of-file
    indicator.  STREAM must be open for reading.  The next read
    operation on STREAM starts with C.  If C is EOF, nothing is done.
    Only one character can be pushed onto a stream.  fflush(),
    fseek(), fsetpos() and rewind() undo ungetc().  After a successful
    ungetc(), the value of the file pointer is undefined until the
    character has been read.

  Return value:

    On success, ungetc() returns the character C.  On failure,
    ungetc() returns EOF.

  See also: fgetc(), fflush()

------------------------------------------------------------------------------
#include <stdio.h>      /* use this */                                  [UNIX]
#include <io.h>         /* or this */

int unlink (const char *name);

    Delete a file.  NAME is a pointer to a string containing the name
    of the file to be deleted.  Under OS/2 and DOS, unlink() and
    remove() are equivalent.

  Return value:

    0       success

    -1      error

  Implementation-defined behavior:

    If the read-only attribute of the file is set, unlink() sets errno
    to EPERM and returns -1.

    If the file is open in any process, unlink() sets errno to EACCES
    and returns -1.

  See also: remove()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _uopen (Heap_t h);

    Open the heap H.  Before a heap created with _ucreate() or
    _ucreate2() can be used, it must be opened.  A shared heap must be
    opened by all processes which want to access the heap.  All
    attempts to access a heap before it has been opened will invoke
    undefined behavior.

    _uopen() fails if H is the runtime heap (_RUNTIME_HEAP) or the
    tiled runtime heap.

  Return value:

    0       success

    -1      error

  See also: _uclose(), _ucreate(), _ucreate2()

------------------------------------------------------------------------------
#include <umalloc.h>                                                   [VAC++]

int _ustats (Heap_t h, _HEAPSTATS *pstats);

    _ustats() computes statistics on the heap pointed to by H and
    fills in the structure pointed to by PSTATS.  The structure has
    the following members:

    _provided
            Total number of bytes provided by the heap, including used
            and free blocks, excluding overhead for control structures

    _used   Total number of bytes in used blocks

    _tiled  1 if the heap is tiled (_HEAP_TILED), 0 if the heap is not
            tiled

    _shared
            1 if the heap is shared (_HEAP_SHARED), 0 if the heap is
            not shared

    _max_free
            Number of bytes in the biggest free block

    _segments
            Number of segments

    _crates
            Number of blocks allocated internally for allocation of
            small user blocks

  Return value:

    _ustats() returns 0 if successful.  _ustats() returns a non-zero
    value on error.

  Implementation-defined behavior:

    The _segments and _crates members are an emx extension.

  Hints:

    Use _udefault() to obtain a pointer to the default heap if you
    want to apply _ustats() to the default heap.

  See also: _uaddmem(), _udefault(), _uheapmin(), _uheap_walk()

------------------------------------------------------------------------------
#include <umalloc.h>                                                     [emx]

void *_utcalloc (Heap_t h, size_t elements, size_t size);

    Allocate from the heap pointed to by H a block of memory big
    enough for holding ELEMENTS elements of SIZE bytes each.  The
    block will not cross a 64 KByte boundary unless SIZE is greater
    than 65536.  If SIZE is greater than 65536, the block will be
    aligned on a 64 KByte boundary.  _utcalloc() fills the block with
    zeros.  If there is an error, _utcalloc() returns NULL.

  Return value:

    _utcalloc() returns a pointer to a newly allocated block of
    memory.  On error, _utcalloc() returns NULL.

  See also: calloc(), free(), realloc(), _tcalloc(), _utmalloc()

------------------------------------------------------------------------------
#include <umalloc.h>                                                     [emx]

Heap_t _utdefault (Heap_t h);

    The _utdefault() function selects the heap pointed to by H as the
    tiled default heap of the current thread unless H is NULL.  All
    tiled memory allocation functions such as _tmalloc() which don't
    take a pointer to a heap will use the heap pointed to by H if
    called in the same thread.  If H is NULL, _utdefault() won't set
    the tiled default heap.

    Initially, the tiled runtime heap is used as tiled default heap
    for all threads.

  Return value:

    _utdefault() returns a pointer to the previous tiled default heap
    of the current thread.

  Hints:

    To obtain a pointer to the tiled default heap of the current
    thread without selecting a new heap, call _utdefault(NULL).

  See also: _mheap(), _ucreate(), _ucreate2(), _udefault()

------------------------------------------------------------------------------
#include <utime.h>                                                      [SysV]

int utime (const char *name, const struct utimbuf *times);

    Set the time stamp of a file to the access time and modification
    time in the structure pointed to by TIMES.  NAME points to a
    string containing the name of the file.  If TIMES is NULL, both
    the access time and the modification time are set to the current
    time.

    The utimbuf structure is defined as follows:

        struct utimbuf
        {
          time_t actime;
          time_t modtime;
        };

    actime is the time of the last access, modtime is the time of the
    last modification.

  Return value:

    0       success

    -1      error

  See also: stat(), utimes()

------------------------------------------------------------------------------
#include <sys/time.h>                                                    [BSD]

int utimes (const char *name, const struct timeval *tvp);

    Set the time stamp of a file to the access time in TVP[0] and the
    modification time in TVP[1].  NAME points to a string containing
    the file name.  If TVP is NULL, both the access time and the
    modification time are set to the current time.

    The timeval structure is defined as follows:

        struct timeval
        {
          long tv_sec;
          long tv_usec;
        };

    tv_sec and tv_usec are the number of seconds and microseconds,
    respectively, elapsed since 00:00:00 1-Jan-1970 UTC.

  Return value:

    0       success

    -1      error

  See also: stat(), utime()

------------------------------------------------------------------------------
#include <umalloc.h>                                                     [emx]

void *_utmalloc (Heap_t h, size_t size);

    Allocate from the heap pointed to by H a block of memory big
    enough for holding SIZE bytes.  The block will not cross a 64
    KByte boundary unless SIZE is greater than 65536.  If SIZE is
    greater than 65536, the block will be aligned on a 64 KByte
    boundary.  Therefore, blocks allocated with _utmalloc() can be
    used with 16-bit functions.  If there is an error, _utmalloc()
    returns NULL.  If SIZE is 0, zero bytes of memory are allocated,
    the return value will be unequal NULL.  Use free() to deallocate a
    block of memory allocated by _utmalloc().

    As _utmalloc() causes additional heap fragmentation, you should
    not use _utmalloc() unless you need an aligned block.

  Return value:

    _utmalloc() returns a pointer to a newly allocated block of
    memory.  On error, _utmalloc() returns NULL.

  See also: free(), realloc(), _tmalloc(), _umalloc(), _utcalloc()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_attrib (int a);

    Set the attributes (colors etc.) used by video library functions
    to A.  You can make A by using the binary OR operator and the
    F_whatever, B_whatever, INTENSITY and BLINK constants.

  See also: v_init(), v_putc()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_backsp (int count);

    Backspace the cursor.  The cursor is moved left by COUNT
    characters.  If the cursor leaves the screen at the left edge, it
    is moved to the end of the previous line.  The cursor cannot leave
    the screen at the top edge.

  See also: v_putc()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_clear (void);

    Clear the screen using the current attributes.

  See also: v_attrib(), v_clreol()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_clreol (void);

    Clear the line from the current cursor position to the end of the
    current line using the current attributes.

  See also: v_attrib(), v_clear()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_ctype (int start, int end);

    Set the cursor type.  START is the first row of the cursor, END is
    the last row of the cursor.  Both values are zero-based.  Use
    v_hardware() to determine the size of the character box.

    Note that cmd.exe resets the cursor type.

  See also: v_getctype(), v_hardware(), v_hidecursor()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_delline (int count);

    Delete COUNT lines at the current cursor position by moving up the
    lines below the current line.  The current attributes are used for
    filling lines becoming empty at the bottom of the screen.

  See also: v_attrib(), v_insline(), v_scroll()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_dimen (int *width, int *height);

    Store the screen width (columns) to WIDTH, the screen height
    (lines) to HEIGHT.

  See also: _scrsize()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/video.h>

int v_fclose (FILE *stream);

    Close a video file created by v_fopen().

  Return value:

    0       success

    -1      error

  See also: v_fopen()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/video.h>

FILE *v_fopen (void);

    Open a video file.  All output to a video file goes to the screen,
    using video library functions such as v_puts().  The stream
    returned by v_fopen() can be used with fprintf(), fputc() and
    fwrite().  On error, v_fopen() returns NULL.  Do not use fclose()
    on a stream created by v_fopen(), use v_fclose() instead.  Do not
    read from a stream created by v_fopen().

  Return value:

    See above.

  See also: _fassign(), fopen(), v_fclose(), v_printf()

  Example: See /emx/test/vftest.c

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

int v_getattr (void);

    Return the current attributes.

  Return value:

    See above.

  See also: v_attrib()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_getctype (int *start, int *end);

    Store the current cursor start and end rows to START and END.

  See also: v_ctype()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_getline (char *dst, int x, int y, int count);

    Copy COUNT character/attributes pairs from the screen at position
    (X,Y) to the array pointed to by DST.  2*COUNT bytes are copied.
    The cursor is not moved.

  See also: v_putline()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_getxy (int *x, int *y);

    Store the current cursor position to X (column) and Y (line).

  See also: v_gotoxy()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_gotoxy (int x, int y);

    Move the cursor to line Y, column X.  Both values are zero-based.
    Line 0 is the top line, column 0 is the left-most column.

  See also: v_getxy()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

int v_hardware (void);

    Get the display adapter type.

  Return value:

    V_MONOCHROME
            Monochrome display adapter

    V_COLOR_8
            Color display adapter, the character box height is 8 scan
            lines

    V_COLOR_12
            Color display adapter, the character box height is 12 scan
            lines

  See also: v_ctype()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_hidecursor (void);

    Turn off the cursor.  Use v_ctype() to turn the cursor on.

  See also: v_ctype()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

int v_init (void);

    Initialize video library.  You must call this function before
    calling any other video library function.  The attributes are set
    to F_WHITE|B_BLACK.

    General information about the video library: The video library
    implements text-mode output to the screen.  You have to link with
    -lvideo.  Under DOS, emx option -acm is required, see `Using emx
    options'.  See wm_init() for a higher-level interface.

  Return value:

    v_init() always returns 1.

  See also: v_attrib()

  Example: See /emx/test/video.c

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_insline (int count);

    Insert COUNT empty lines at the current cursor position by moving
    down the line at the current cursor position and all lines below
    that line.  The current attributes are used for filling the empty
    lines.

  See also: v_attrib(), v_delline(), v_scroll()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

int v_printf (const char *fmt, ...);

    Formatted output to the screen at the current cursor position.
    The cursor is moved.  See printf() for details on the format
    string pointed to by FMT.

  Return value:

    v_printf() returns the number of output characters.

  See also: v_attrib(), v_fopen(), v_putc(), v_puts(), v_vprintf()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_putc (char c);

    Display character C on the screen at the current cursor position,
    using the current attributes.  The cursor is moved.  If the cursor
    leaves the screen at the right edge, it will be moved to the start
    of the next line.  If C is '\n', the cursor is moved to the start
    of the next line.  If the cursor leaves the screen at the bottom
    edge, the screen is scrolled up.

  See also: v_attrib(), v_puts(), v_scrollup()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_putline (const char *src, int x, int y, int count);

    Copy COUNT character/attributes pairs from the array pointed to by
    SRC to the screen at position (X,Y).  2*COUNT bytes are copied.
    The cursor is not moved.

  See also: v_getline(), v_putmask(), v_putn()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_putm (const char *str, int len);

    Display LEN characters of the string pointed to by STR at the
    current cursor position using the current attributes.  The cursor
    is not moved.

  See also: v_putline(), v_putn(), v_puts()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_putmask (const char *src, const char *mask, int x, int y, int count);

    Copy COUNT character/attributes pairs from the array pointed to by
    SRC to the screen.  A character/attributes pair at SRC[2*i] and
    SRC[2*i+1], is copied only if MASK[i] is non-zero.  The cursor is
    not moved.

  See also: v_putline()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_putn (char c, int count);

    Display character C at the current cursor position using the
    current attributes.  COUNT is the number of times to display the
    character.  The cursor is not moved.

  See also: v_attrib(), v_putc()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_puts (const char *str);

    Display the string pointed to by STR at the current cursor
    position using the current attributes.  The '\n' character moves
    the cursor to the start of the next line.  Scrolling is performed
    when the cursor leaves the screen at the bottom edge.

  See also: v_attrib(), v_putc(), v_putm()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_scroll (int tl_x, int tl_y, int br_x, int br_y, int count, int flag);

    Scroll a rectangle of the screen by COUNT lines.  The top left
    character cell is at (TL_X,TL_Y), the bottom right character cell
    is at (BR_X,BR_Y).  If FLAG is V_SCROLL_UP, the rectangle is
    scrolled up, if FLAG is V_SCROLL_DOWN, the rectangle is scrolled
    down.  If FLAG is V_SCROLL_CLEAR, the rectangle is filled with
    blanks.  Lines becoming empty are filled with blanks using the
    current attributes.

  See also: v_attrib(), v_scrollup()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

void v_scrollup (void);

    Scroll screen up by one line.  The bottom line is filled with
    blanks, using the current attributes.

  See also: v_attrib(), v_putc()

------------------------------------------------------------------------------
#include <sys/video.h>                                                   [emx]

int v_vprintf (const char *fmt, va_list arg_ptr);

    Formatted output to the screen.  Instead of a list of arguments,
    this function takes a pointer to the list of arguments.  See
    v_printf() for details.

  Return value:

    v_vprintf() returns the number of output characters.

  See also: v_printf(), va_arg()

------------------------------------------------------------------------------
#include <stdarg.h>                                                      [C90]

type va_arg (va_list arg_ptr, type);
void va_end (va_list arg_ptr);
void va_start (va_list arg_ptr, type prev_arg);

    Access arguments of a function with variable number of arguments.
    You have to declare a variable of type va_list, for instance
    ARG_PTR.  Use

        va_start (ARG_PTR, PREV_ARG)

    where PREV_ARG is the argument preceding the variable arguments,
    to initialize ARG_PTR.  Use

        va_arg (ARG_PTR, TYPE)

    to get the next argument, which is of type TYPE.  Use

        va_end (ARG_PTR)

    when you no longer need ARG_PTR.

  Return value:

    See above.

  Restrictions:

    PREV_ARG should not be of type float unless there's a prototype
    for the function, TYPE should not be float.  Both problems are due
    to the fact that float is promoted to double.

  See also: vprintf()

  Example: See /emx/samples/stdarg.c

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

int vprintf (const char *format, va_list arg_ptr);
int vfprintf (FILE *stream, const char *format, va_list arg_ptr);
int vsprintf (char *buffer, const char *format, va_list arg_ptr);

    Formatted output to stdout, to the stream STREAM or to the string
    pointed to by BUFFER, respectively.  Instead of a list of
    arguments, these functions take a pointer to the list of
    arguments.  See printf() for details.

  Return value:

    vprintf(), vfprintf() and vsprintf() return the number of output
    characters.  On error, these functions return EOF.

  See also: printf(), va_arg(), vsnprintf()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]

int vscanf (const char *format, va_list arg_ptr);
int vfscanf (FILE *stream, const char *format, va_list arg_ptr);
int vsscanf (const char *buffer, const char *format, va_list arg_ptr);

    Parse input from stdin, STREAM or the string pointed to by BUFFER,
    respectively.  Instead of a list of arguments, these functions
    take a pointer to the list of arguments.  See scanf() for details.

  Return value:

    If successful, vscanf(), vfscanf() and vsscanf() return the number
    of fields converted.  On error, these functions return EOF.

  See also: scanf(), va_arg()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [BSD]

int vsnprintf (char *buffer, size_t n, const char *format, va_list arg_ptr);

    Formatted output to the string pointed to by BUFFER.  Up to N-1
    characters and a terminating null character will be written to
    BUFFER.  If formatting yields more than N-1 characters, output
    will be truncated.  The terminating null character will be put
    into BUFFER even if output is truncated.

    Instead of a list of arguments, this function takes a pointer to
    the list of arguments.  See printf() for details.

  Return value:

    On success, vsnprintf() returns the number of characters copied to
    BUFFER (excluding the terminating null character).  If the length
    of formatted output exceeds N-1 characters, vsnprintf() will
    return a value greater than or equal to N.  On error, vsnprintf()
    returns EOF.

  See also: printf(), snprintf(), va_arg(), vsprintf()

------------------------------------------------------------------------------
#include <sys/types.h>                                               [POSIX.1]
#include <sys/wait.h>

int wait (int *stat_loc);

    Obtain status information about a child process.  wait() suspends
    the process until status information for a child process is
    available or until a signal occurs.

    If status information is available, wait() returns immediately.
    This happens if a child process terminated before wait() is
    called, or if status information about a debuggee is available,
    that is, after calling ptrace() with requests PTRACE_RESUME or
    PTRACE_STEP.

    If there are no child processes, wait() returns immediately,
    setting errno to ECHILD and returning -1.  If STAT_LOC is not
    NULL, the return code and the termination status are stored to the
    location pointed to by STAT_LOC.

    You can use the following macros for determining the type of
    status (STAT_VAL is the value pointed to by STAT_LOC):

    WIFEXITED (STAT_VAL)

        This macro returns a non-zero value if the process for which
        STAT_VAL was returned terminated normally.

    WIFSIGNALED (STAT_VAL)

        This macro returns a non-zero value if the process for which
        STAT_VAL was returned terminated due to a signal which was not
        caught.

    WIFSTOPPED (STAT_VAL)

        This macro returns a non-zero value if the process for which
        STAT_VAL was returned is stopped.  This occurs only if the
        child process is being debugged.

    Depending on the type of status indicated by the above macros, you
    can use exactly one of the following macro to obtain additional
    information:

    WEXITSTATUS (STAT_VAL)

        If WIFEXITED(STAT_VAL) is non-zero, this macro returns the
        return code of the child process (passed to exit(), _exit(),
        or returned from main()).

    WTERMSIG (STAT_VAL)

        If WIFSIGNALED(STAT_VAL) is non-zero, this macro returns the
        number of the signal by which the child process was
        terminated.

    WSTOPSIG (STAT_VAL)

        If WIFSTOPPED(STAT_VAL) is non-zero, this macro returns the
        number of the signal by which the child process was stopped.

  Return value:

    wait() returns the process ID of the child process.  If
    _UF_PTRACE_MULTITHREAD has been set with _uflags(), the return
    value of wait() contains both the thread ID and the process ID;
    use the PTRACE_GETPID and PTRACE_GETTID macros of <sys/ptrace.h>
    to extract the process ID and the thread ID.  If an error occurs,
    wait() sets errno and returns -1.

  Restrictions:

    Under DOS, wait() is currently implemented only for processes
    being debugged and for synchronous processes started with
    P_NOWAIT; see ptrace() and spawn*().  Under DOS, the termination
    status of only one process is kept for wait().  If you run another
    process before calling wait(), the termination status will be
    overwritten.

    Under OS/2, wait() works only for processes started with spawn*()
    or exec*().  It does not work for processes started with
    DosExecPgm or DosStartSession.  If the processes found by wait()
    has been started as a session, only the return code is available,
    not the signal number.

    wait() is interrupted by signals which are ignored (SIG_IGN) and
    by signals which are blocked.

  See also: exit(), fork(), main(), ptrace(), sigaction(), signal(),
            sigprocmask(), spawn*(), _uflags(), waitpid()

  Example:

    int tc, pid;
    
    pid = wait (&tc);
    if (pid >= 0)
      {
        if (WIFEXITED (tc))
          printf ("Normal process termination, rc=%d\n", WEXITSTATUS (tc));
        else if (WIFSIGNALED (tc))
          printf ("Process terminated by signal %d\n", WTERMSIG (tc));
        else
          printf ("Process stopped by signal %d\n", WSTOPSIG (tc));
      }

------------------------------------------------------------------------------
#include <sys/hw.h>                                                    [emx *]

void _wait0 (unsigned port, unsigned mask);
void _wait1 (unsigned port, unsigned mask);
void _wait01 (unsigned port, unsigned mask);
void _wait10 (unsigned port, unsigned mask);

    The _wait0() and _wait1() functions wait for the bit indicated by
    MASK of the 8-bit hardware port PORT being 0 or 1, respectively.

    The _wait01() and _wait10() functions wait for a 0->1 or 1->0
    transition, respectively, of the bit indicated by MASK of the
    8-bit hardware port PORT.

    If there are multiple bits set in MASK, 0 means all bits cleared,
    1 means at least one bit set.

    You have to call _portaccess() first to enable access to a range
    of ports.  To make your program work under DOS, you have to use
    emx option -ai, see `Using emx options'.  Under OS/2, your program
    requires emxio.dll in a directory listed in LIBPATH.

    Note that these functions eat a lot of CPU time.

  See also: _portaccess(), _inp8()

------------------------------------------------------------------------------
#include <sys/types.h>                                               [POSIX.1]
#include <sys/wait.h>

int waitpid (int pid, int *stat_loc, int options);

    Wait until status information for the child process PID is
    available or until a signal occurs.  If PID is -1, waitpid() waits
    for any child process, as does wait().  If there is no child
    process with process ID PID (or if PID is -1 and there is no child
    process), errno is set to ESRCH and -1 is returned.  On success,
    the process ID is returned.  If STAT_LOC is not NULL, the return
    code and the termination status are stored to the location pointed
    to by STAT_LOC, see wait() for details.

    OPTIONS is the bitwise OR of zero or more of the following flags:

    WNOHANG
            Don't wait if no status information is currently
            available.  If WNOHANG is set, and there are any child
            processes matching PID, and no status available for any
            child process matching PID, 0 is returned.

    WUNTRACED
            Not implemented.

  Return value:

    -1      error or interrupted (errno set to ECHILD, EINVAL, or
            EINTR)

    >0      process ID.  If _UF_PTRACE_MULTITHREAD has been set with
            _uflags(), the return value of waitpid() contains both the
            thread ID and the process ID; use the PTRACE_GETPID and
            PTRACE_GETTID macros of <sys/ptrace.h> to extract the
            process ID and the thread ID

    0       WNOHANG is set in OPTIONS, and there are child processes
            matching PID, and no status available for any child
            process matching PID

  Restrictions:

    waitpid() is not implemented for negative values of PID.
    WUNTRACED in OPTIONS is ignored.  waitpid() is not implemented
    under DOS.  waitpid() is interrupted by signals which are ignored
    (SIG_IGN) and by signals which are blocked.

  See also: fork(), ptrace(), sigaction(), signal(), sigprocmask(),
            spawn*(), _uflags(), wait()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

void _wildcard (int *argcp, char ***argvp);

    Expand wildcards.  If you want wildcards on the command line to be
    expanded, call

        _wildcard (&argc, &argv);

    at the beginning of main().  Wildcard arguments enclosed in double
    quotes won't be expanded.  If the expansion of a wildcard argument
    is empty, the wildcard argument is kept unchanged.  Directories
    are included in the expansion.  Hidden and system files are
    omitted.

    _fnlwr() is used to convert file names to lower case on
    upper-case-only file systems.

    _wildcard() properly handles DBCS characters.

  See also: _envargs(), _fnexplode(), main(), _nls_init(), _response()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

size_t wcstombs (char *s, const wchar_t *pwcs, size_t n);

    Convert the zero-terminated sequence of wchar_t codes at PWCS to a
    multibyte character sequence beginning at S.  The multibyte
    character sequence starts in the initial shift state.  At most N
    bytes are stored.  S will be terminated with a null character if N
    is big enough.

    The shift state of wctomb() is not affected.

  Return value:

    wcstombs() returns the number of bytes stored to S (excluding the
    terminating null character) or (size_t_t)-1 if a code could not be
    counverted.

  See also: mbstowcs(), setlocale(), wctomb()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [C90]

int wctomb (char *s, wchar_t wchar);

    Convert the wchar_t code WCHAR to a multibyte character sequence
    pointed to by S.  At most MB_CUR_MAX bytes are stored.  If S is
    NULL, the shift state is reset to the initial state.  If WCHAR is
    zero, the shift state is the initial state after return from
    wctomb().

    In programs linked with the multithread libraries, each thread has
    its own shift state for wctomb().

  Return value:

    If S is NULL, wctomb() returns a non-zero value (if
    state-dependent encoding is used) or a zero value (if
    state-dependent encoding is not used).  If S is not NULL, wctomb()
    returns 0 (if WCHAR is zero), the number of bytes comprising the
    multibyte character stored to S (if conversion is successful), or
    -1 (if WCHAR could not be converted).

  See also: mbtowc(), setlocale(), wcstombs()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_attrib (wm_handle wh, int a);

    Set the default attributes of window WH to A.

  See also: wm_create(), wm_get_attrib(), wm_putc()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_attrib_all (wm_handle wh, int a);

    Change the attributes of all characters of window WH (except of
    the border) to A.  The character codes are not changed.

  See also: wm_attrib(), wm_clear(), wm_create()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_backsp (wm_handle wh, int count);

    Backspace the cursor of window WH.  The cursor is moved left by
    COUNT characters.  If the cursor leaves the window at the left
    edge, it is moved to the end of the previous line.  The cursor
    cannot leave the window at the top edge.

  See also: wm_putc()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_border (wm_handle wh, int bflag, int battr, const char *title,
                int tflag, int tattr);

    Change the border of window WH.  The border type is set to BFLAG:
    0 turns the border off, 1 uses a single line, 2 uses a double
    line, 3 and 4 use both single and double lines -- which is not
    recommended as most code pages do not contain the necessary
    symbols.  All other values are used as characters for drawing the
    border.  The attributes BATTR are used for drawing the border.
    The string pointed to by TITLE is displayed centered in the top
    line of the border.  If TFLAG is non-zero, vertical bars are used
    to separate the title text from the border.  The attributes TATTR
    are used for displaying the title text.

  See also: wm_create()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_bottom (wm_handle wh);

    Move window WH to the bottom of the window stack, that is, it will
    be moved below all other windows.

  See also: wm_top(), wm_up()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_chide (int flag);

    Set the cursor hide mode.  If FLAG is non-zero, the cursor is
    hidden if the current cursor position is hidden by another window.
    If FLAG is zero, the cursor is visible even if the cursor position
    is hidden by another window.  The initial value is non-zero.

  See also: wm_ctype(), wm_cursor()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_clear (wm_handle wh);

    Clear window WH by filling WH with blanks using the current
    attributes.

  See also: wm_attrib(), wm_attrib_all()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_close (wm_handle wh);

    Close the window WH.  After closing the window, it still exists
    but is not visible.

  See also: wm_open()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_close_all (void);

    Close all the windows.  wm_close_all() restores the original
    screen contents.

  See also: wm_close(), wm_open()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_clr_eol (wm_handle wh, int x, int y);

    Clear from position (X,Y) of window WH to the end of that line of
    that window by displaying blanks.  The current attributes are
    used.

  See also: wm_clear()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

wm_handle wm_create (int x0, int y0, int x1, int y1, int border, int battr,
                     int wattr);

    Create a window.  The upper left character of the window interior
    is at (X0,Y0), the bottom right character of the window interior
    is at (X1,Y1).  A window may be larger than the screen or
    partially or completely outside the screen.  BORDER specifies the
    border type: 0 doesn't draw a border, 1 uses a single line, 2 uses
    a double line, 3 and 4 use both single and double lines -- which
    is not recommended as most code pages do not contain the necessary
    symbols.  All other values are used as characters for drawing the
    border.  The attributes BATTR are used for drawing the border.
    The attributes for displaying text in the window are set to WATTR.
    After creating a window, it is invisible.  Use wm_open() to show
    the window.

  Return value:

    wm_create() returns the handle of the window if successful.
    Otherwise, NULL is returned.

  See also: wm_attrib(), wm_border(), wm_delete(), wm_open()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_ctype (wm_handle wh, int start, int end);

    Set the cursor type of window WH.  START is the first row of the
    cursor, END is the last row of the cursor.  Both values are
    zero-based.  The cursor type set by wm_ctype() is used for
    displaying the cursor if it is connected to window WH.  Use
    v_hardware() to determine the size of the character box.

  See also: v_hardware(), wm_chide(), wm_cursor()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_cursor (wm_handle wh);

    Connect the screen cursor with the cursor of window WH.  The
    cursor is displayed at the cursor position of window WH, using the
    cursor type of window WH.  If WH is NULL, the screen cursor is not
    connected to any window and is invisible.  Initially, the screen
    cursor is not connected to any window.

  See also: wm_chide(), wm_ctype(), wm_cvis()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_cvis (wm_handle wh, int flag);

    Set the cursor status of window WH.  If FLAG is non-zero, the
    cursor is enabled, if FLAG is zero, the cursor is disabled.

  See also: wm_chide(), wm_cursor()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_del_char (wm_handle wh, int x, int y, int count);

    Delete COUNT characters at position (X,Y) of window WH.
    Characters to the right of that position are moved left, the
    positions becoming vacant at the right edge of the window are
    filled with blanks using the current attributes.

  See also: wm_attrib(), wm_del_line(), wm_ins_char()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_del_line (wm_handle wh, int y, int count);

    Delete COUNT lines at line Y of window WH by moving up the lines
    below that line.  The current attributes are used for filling
    lines becoming empty at the bottom of the window.

  See also: wm_attrib(), wm_del_char(), wm_ins_line(), wm_scroll()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_delete (wm_handle wh);

    Destroy the window WH.  After calling wm_delete(), the window
    handle WH must no longer be used.  The window is not closed.

  See also: wm_close(), wm_create()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_dimen (wm_handle wh, int *width, int *height);

    Store the width of the window WH (columns) to WIDTH, the height
    (lines) to HEIGHT.

  See also: wm_create()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_down (wm_handle wh);

    Move window WH down the window stack, that is, it will be covered
    by an additional window unless WH is already the bottom window.

  See also: wm_bottom(), wm_top(), wm_up()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_exit (void);

    Quit the window manager and release all memory allocated by the
    window manager.  All window handles become invalid.  The windows
    are not closed.

  See also: wm_close(), wm_delete()

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/winmgr.h>

int wm_fclose (FILE *stream);

    Close a window manager file.

  Return value:

    0       success

    -1      error

  See also: wm_fopen()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

wm_handle wm_find (int x, int y);

    Find the window which is visible at position (X,Y) of the screen.

  Return value:

    wm_find() returns the window handle if such a window exists.
    Otherwise, wm_find() returns NULL.

------------------------------------------------------------------------------
#include <stdio.h>                                                       [emx]
#include <sys/winmgr.h>

FILE *wm_fopen (wm_handle wh);

    Open a window manager file.  All output to a video file goes to
    the window WH, using window manager library functions such as
    wm_puts().  The stream returned by wm_fopen() can be used with
    fprintf(), fputc() and fwrite().  On error, wm_fopen() returns
    NULL.  Do not use fclose() on a stream created by v_fopen(), use
    wm_fclose() instead.  Do not read from a stream created by
    wm_fopen().

  Return value:

    See above.

  See also: _fassign(), fopen(), wm_printf()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

int wm_get_attrib (wm_handle wh);

    Return the current attributes of window WH.

  Return value:

    See above.

  See also: wm_attrib()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

wm_handle wm_get_cursor (void);

    Get the window to which the screen cursor is connected.

  Return value:

    wm_get_cursor() returns the window handle of the window to which
    the screen cursor is connected.  If the cursor is not connected to
    any window, wm_get_cursor() returns NULL.

  See also: wm_cursor()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_get_pos (wm_handle wh, int *x, int *y);

    Store the screen coordinates of the upper left character of the
    interior of window WH to X and Y.

  See also: wm_create(), wm_move()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_getxy (wm_handle wh, int *x, int *y);
int wm_getx (wm_handle wh);
int wm_gety (wm_handle wh);

    wm_getxy() stores the cursor coordinates of window WH to X and Y.
    wm_getx() returns the horizontal position (column) of the cursor
    of window WH.  wm_gety() returns the vertical position (line) of
    the cursor of window WH.  The coordinates are zero-based and are
    relative to the upper left character of the interior of window WH.

  Return value:

    See above.

  See also: wm_gotoxy()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_gotoxy (wm_handle wh, int x, int y);

    Move the cursor of window WH to (X,Y).  The coordinates are
    zero-based and are relative to the upper left character of the
    interior of window WH.  If the screen cursor is connected to the
    cursor of window WH, the screen cursor is moved.

  See also: wm_cursor(), wm_getxy()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_ins_char (wm_handle wh, int x, int y, int count);

    Insert COUNT blank characters at position (X,Y) of window WH.
    Characters to the right of that position are moved right.  The
    current attributes are used for displaying the blank characters.

  See also: wm_attrib(), wm_del_char(), wm_ins_line()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_ins_line (wm_handle wh, int y, int count);

    Insert COUNT empty lines at line Y of window WH by moving down
    that line and all lines below that line.  The current attributes
    are used for filling the empty lines.

  See also: wm_attrib(), wm_del_line(), wm_scroll()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

int wm_init (int n);

    Initialize the window manager and allocate memory for N windows.
    You must call this function before calling any other window
    manager function.

    General information about window manager functions: The window
    manager functions implement text-mode output to windows on the
    screen.  You have to link with -lvideo.  Under DOS, emx option
    -acm is required, see `Using emx options'.

  Return value:

    1       success

    0       error

  See also: wm_exit()

  Example: See /emx/samples/wm_demo.c, /emx/samples/wm_hello.c

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_move (wm_handle wh, int x, int y);

    Move the window WH.  The upper left character of the interior of
    the window will be at screen coordinates (X,Y).

  See also: wm_get_pos()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_open (wm_handle wh);

    Open the window WH.  The window will be showed on the screen
    unless it is covered by other windows or outside the screen.

  See also: wm_close()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

int wm_printf (wm_handle wh, const char *fmt, ...);

    Formatted output to window WH at the current cursor position of
    that window.  The cursor is moved.  See printf() for details on
    the format string pointed to by FMT.

  Return value:

    wm_printf() returns the number of output characters.

  See also: wm_attrib(), wm_fopen(), wm_putc(), wm_puts(),
            wm_vprintf()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_puta_at (wm_handle wh, int x, int y, int a, int count);

    Change to A the attributes of COUNT characters at position (X,Y)
    of window WH.  All COUNT characters must be in one line of the
    window.

  See also: wm_attrib(), wm_putsa_at()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_putc (wm_handle wh, char c);

    Display character C in window WH at the current cursor position of
    that window, using the current attributes of that window.  The
    cursor of that window is moved.  If the cursor leaves the window
    at the right edge, it will be moved to the start of the next line.
    If C is '\n', the cursor is moved to the start of the next line.
    If the cursor leaves the window at the bottom edge, the window is
    scrolled up.

  See also: wm_attrib(), wm_putc_at(), wm_putca(), wm_scroll(),
            wm_wrap()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_putc_at (wm_handle wh, int x, int y, char c);

    Display character C at position (X,Y) of window WH using the
    current attributes of that window.  The cursor is not moved.

  See also: wm_attrib(), wm_gotoxy()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_putca (wm_handle wh, char c, int a);

    Display character C in window WH at the current cursor position of
    that window, using the attributes A.  The cursor of that window is
    moved.  If the cursor leaves the window at the right edge, it will
    be moved to the start of the next line.  If C is '\n', the cursor
    is moved to the start of the next line.  If the cursor leaves the
    window at the bottom edge, the window is scrolled up.

  See also: wm_putc(), wm_putca_at(), wm_scroll(), wm_wrap()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_putca_at (wm_handle wh, int x, int y, char c, int a);

    Display character C at position (X,Y) of window WH using the
    attributes A.  The cursor is not moved.

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_puts (wm_handle wh, const char *str);

    Display the string pointed to by STR in window WH at the current
    cursor position of that window using the current attributes of
    that window.  The '\n' character moves the cursor to the start of
    the next line.  Scrolling is performed when the cursor leaves the
    window at the bottom edge.

  See also: wm_attrib(), wm_putc(), wm_putsa(), wm_scroll(), wm_wrap()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_puts_at (wm_handle wh, int x, int y, const char *str);

    Display the string pointed to by STR in window WH at position
    (X,Y) using the current attributes of that window.  The '\n'
    character is not interpreted, the cursor is not moved.

  See also: wm_attrib(), wm_puts()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_putsa (wm_handle wh, const char *str, int len);

    Display LEN characters with attributes in window WH at the current
    cursor position of that window.  STR points to an array of
    character and attributes pairs.  There are 2*LEN bytes at STR.

  See also: wm_putca(), wm_puts(), wm_scroll(), wm_wrap()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_putsa_at (wm_handle wh, int x, int y, const char *str, int len);

    Display LEN characters with attributes in window WH at position
    (X,Y).  STR points to an array of character and attributes pairs.
    There are 2*LEN bytes at STR.

  See also: wm_putsa()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_scroll (wm_handle wh, int count);

    Scroll the interior of window WH up by one line.  The bottom line
    is filled with blanks, using the current attributes.

  See also: wm_attrib(), wm_del_line(), wm_ins_line(), wm_putc()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_top (wm_handle wh);

    Move window WH to the top of the window stack, that is, it will
    cover all other windows.

  See also: wm_bottom(), wm_down()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_up (wm_handle wh);

    Move window WH up the window stack, that is, it will cover an
    additional window unless WH is already the top window.

  See also: wm_bottom(), wm_down(), wm_top()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_update (wm_handle wh, int flag);

    Set the update mode of window WH.  If FLAG is non-zero (which is
    the default), the screen is updated immediately if window WH is
    changed.  If FLAG is zero, changes to window WH are done in memory
    only.  This can be done to improve speed.  Each call to
    wm_update() copies the window to the screen, regardless of the
    FLAG argument.

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

int wm_vprintf (wm_handle wh, const char *fmt, va_list arg_ptr);

    Formatted output to window WH.  Instead of a list of arguments,
    this function takes a pointer to the list of arguments.  See
    wm_printf() for details.

  Return value:

    wm_vprintf() returns the number of output characters.

  See also: wm_printf(), va_arg()

------------------------------------------------------------------------------
#include <sys/winmgr.h>                                                  [emx]

void wm_wrap (wm_handle wh, int wrap_flag);

    Set the end-of-line wrap mode of window WH.  If WRAP_FLAG is
    non-zero (which is the default), the cursor is moved to the next
    line if it reaches the end of a line.  If WRAP_FLAG is zero, the
    cursor stays at the end of the line.  wm_wrap() applies to
    wm_putc(), wm_puts(), wm_printf(), etc.

  See also: wm_putc()

------------------------------------------------------------------------------
#include <io.h>                                                      [POSIX.1]

int write (int handle, const void *buf, size_t nbyte);

    Write NBYTE characters from the buffer BUF to the file HANDLE.
    Writing 0 characters is allowed -- the request will be ignored.
    In text mode, newline characters are translated to CR/LF pairs.

  Return value:

    write() returns the number of characters written.  If there is an
    error, write() returns -1.  Text mode translation does not affect
    the return value.

  Errors:

    EAGAIN  The O_NONBLOCK (alias O_NDELAY) flag is set for HANDLE and
            the process would be suspended in the write operation.

    EBADF   The HANDLE argument is not a valid file descriptor.

    EINTR   The write operation was interrupted by a caught signal.

    EIO     An I/O error occured.  Use _syserrno() for getting the
            system error code.

    ENOSPC  There is no free space remaining on the device containing
            the file.

    EPIPE   An attempt is made to write to a pipe or named pipe that
            is not open for reading by any process.  A SIGPIPE signal
            is sent to the process.  This error is returned if the
            signal does not terminate the process.

  Restrictions:

    In binary mode, partial transfers to disk files (due to lack of
    disk space) do not occur.  In text mode, partial transfers may
    occur if the actual number of bytes (with newline translated to
    CR/LF) written exceeds 1024.

    PIPE_BUF is ignored: Write operations are atomic for any value of
    NBYTE in blocking mode; write operations may be non-atomic for any
    value of NBYTE in non-blocking mode.

    O_APPEND is subject to race conditions.

  See also: open(), setmode(), read(), sigaction(), signal()


9 Variable reference
====================

The variables are listed almost alphabetically.

------------------------------------------------------------------------------
#include <time.h>

int daylight;

    This variable is zero if standard time is in effect.  It is
    non-zero if daylight saving time is in effect.

  See also: timezone, tzname, tzset()

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

const unsigned int _emx_env;

    This variable contains bits describing the environment your
    program is running in:

    0x0001  Running under VCPI

    0x0002  Running under XMS

    0x0004  VDISK 3.3 detected

    0x0008  Running under DESQview

    0x0010  287 coprocessor present

    0x0020  387 coprocessor present

    0x0200  Running under OS/2 2.x

    0x0400  File names are truncated (-t option)

    0x0800  Data and stack executable (-ac option under DOS)

    0x1000  Running under RSX

    You should check the 0x0200 bit before calling an OS/2 API
    function.  You should check the 0x0400 bit when comparing file
    names.

  See also: _osmode

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

const unsigned int _emx_rev;

    This variable contains the emx revision index.  The revision index
    is a number that is incremented everytime a new emx revision is
    released.  When the emx version number changes, the revision index
    is not reset to zero.  If _emx_rev is zero, the revision index is
    not available because the emx version being in use is too old or
    the system call library is used.

  See also: _emx_vcmp, _emx_vprt

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

const unsigned int _emx_vcmp;

    This variable contains the emx version number, suitable for
    comparing.

  See also: _emx_rev, _emx_vprt

  Example:

    if (_emx_vcmp > 0x302e3861)             /* > 0.8a */
      {
        ...
      }

------------------------------------------------------------------------------
#include <stdlib.h>                                                      [emx]

const char _emx_vprt[5];

    This variable contains the emx version number, suitable for
    printing.

  See also: _emx_rev, _emx_vcmp

  Example:

    printf ("emx version: %s\n", _emx_vprt);

------------------------------------------------------------------------------
                                                                     [POSIX.1]
char **environ;

    A pointer to the current environment of the process.  environ
    points to an array of pointers to strings.  The array is
    terminated by a NULL pointer.  After changing the environment with
    putenv(), you should use this variable instead of the ENVP
    parameter of main().

  Implementation-defined behavior:

    environ is declared in <stdlib.h>.

  Restrictions:

    After changing the value of TZ, you should call tzset().

  See also: main(), putenv(), tzset()

------------------------------------------------------------------------------
#include <errno.h>  /* or this */                                        [C90]

int errno;

    When a library function call fails, errno is usually set to a
    positive value indicating the type of error.  On success, errno is
    usually not changed.  Note that no library function sets errno to
    zero.

  Implementation-defined behavior:

    The following errno values are supported:

        Name             Value  Description
        
        EPERM             1     Operation not permitted
        ENOENT            2     No such file or directory
        ESRCH             3     No such process
        EINTR             4     Interrupted system call
        EIO               5     I/O error
        ENXIO             6     No such device or address
        E2BIG             7     Arguments or environment too big
        ENOEXEC           8     Invalid executable file format
        EBADF             9     Bad file number
        ECHILD            10    No children
        EAGAIN            11    Resource temporarily unavailable
        ENOMEM            12    Not enough memory
        EACCES            13    Permission denied
        EFAULT            14    Bad address
        ENOLCK            15    No locks available
        EBUSY             16    Resource busy
        EEXIST            17    File exists
        EXDEV             18    Cross-device link
        ENODEV            19    No such device
        ENOTDIR           20    Not a directory
        EISDIR            21    Is a directory
        EINVAL            22    Invalid argument
        ENFILE            23    Too many open files in system
        EMFILE            24    Too many open files
        ENOTTY            25    Inappropriate ioctl
        EDEADLK           26    Resource deadlock avoided
        EFBIG             27    File too large
        ENOSPC            28    Disk full
        ESPIPE            29    Illegal seek
        EROFS             30    Read-only file system
        EMLINK            31    Too many links
        EPIPE             32    Broken pipe
        EDOM              33    Domain error
        ERANGE            34    Result too large
        ENOTEMPTY         35    Directory not empty
        EINPROGRESS       36    Operation now in progress
        ENOSYS            37    Function not implemented
        ENAMETOOLONG      38    File name too long
        EDESTADDRREQ      39    Destination address required
        EMSGSIZE          40    Message too long
        EPROTOTYPE        41    Protocol wrong type for socket
        ENOPROTOOPT       42    Option not supported by protocol
        EPROTONOSUPPORT   43    tocol not supported
        ESOCKTNOSUPPORT   44    ket type not supported
        EOPNOTSUPP        45    Operation not supported on socket
        EPFNOSUPPORT      46    Protocol family not supported
        EAFNOSUPPORT      47    Address family not supported by
                                protocol family
        EADDRINUSE        48    Address already in use
        EADDRNOTAVAIL     49    an't assigned requested address
        ENETDOWN          50    Network is down
        ENETUNREACH       51    Network is unreachable
        ENETRESET         52    Network dropped connection on reset
        ECONNABORTED      53    Software caused connection abort
        ECONNRESET        54    Connection reset by peer
        ENOBUFS           55    No buffer space available
        EISCONN           56    Socket is already connected
        ENOTCONN          57    Socket is not connected
        ESHUTDOWN         58    Can't send after socket shutdown
        ETOOMANYREFS      59    Too many references: can't splice
        ETIMEDOUT         60    Connection timed out
        ECONNREFUSED      61    Connection refused
        ELOOP             62    Too many levels of symbolic links
        ENOTSOCK          63    Socket operation on non-socket
        EHOSTDOWN         64    Host is down
        EHOSTUNREACH      65    No route to host
        EALREADY          66    Operation already in progress

    In multithread programs (-Zmt, -Zmts, or -Zmtd), errno is not a
    global variable; it is an lvalue that depends on the thread
    number; each thread has its own errno object.

    To create a library which can be linked to both single-thread and
    multithread programs, use the option

        -D__ST_MT__ERRNO

    on the GCC command line to define errno to call _errno().

  See also: _beginthread(), _errno(), _gettid(), perror(), strerror(),
            sys_errlist, _threadid, _threadstore()

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_xsize;
int g_ysize;
int g_colors;

    These variables describe the graphics mode selected by g_mode() or
    g_modeset().  g_xsize is the horizontal resolution (width),
    g_ysize is the vertical resolution (height), g_colors is the
    number of distinct colors that can be displayed at a time.

  See also: g_mode(), g_modeset()

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

const unsigned char _osminor;
const unsigned char _osmajor;

    These variables contain the minor and major version numbers of the
    operating system.  For DOS 3.30, _osmajor is 3 and _osminor is 30.
    For OS/2 2.0, _osmajor is 20, _osminor is 0.  For OS/2 2.1,
    _osmajor is 20, _osminor is 10.

  See also: _emx_env, _osmode

  Example:

    printf ("OS version: %d.%d\n", _osmajor, _osminor);

------------------------------------------------------------------------------
#include <stdlib.h>                                                       [PC]

const unsigned char _osmode;

    This variable contains DOS_MODE if your program is running under
    DOS or OS2_MODE if your program is running under OS/2.

  See also: _emx_env

------------------------------------------------------------------------------
#include <stdio.h>                                                       [C90]

FILE *stderr;
FILE *stdin;
FILE *stdout;

    stderr, stdin, and stdout are expressions of type `FILE *'
    pointing to the FILE objects associated with the standard error,
    standard input, and standard output streams, respectively.

  Hints:

    Note that stderr, stdin, and stdout need not be variables, that
    is, you cannot use them in initializers and you cannot assign to
    them.  Use freopen() to associate another stream with stderr,
    stdin, or stdout.

  See also: freopen()

------------------------------------------------------------------------------
#include <stdlib.h>

const char * const sys_errlist[];
const int sys_nerr;

    sys_errlist is an array of error messages indexed by errno values.
    sys_nerr is the number of elements in the sys_errlist array.

  See also: errno, perror(), strerror()

------------------------------------------------------------------------------
#include <stddef.h>                                                     [OS/2]

unsigned *_threadid;

    _threadid is an lvalue which points to the thread identification
    number of the current thread as contained in the TIB2 structure.
    _threadid must not be used under DOS.

  See also: _beginthread(), _gettid(), _threadstore()

------------------------------------------------------------------------------
#include <time.h>

long timezone;

    Seconds west of the Prime Meridian.  This variable is set by
    tzset().

  See also: daylight, tzname, tzset()

------------------------------------------------------------------------------
#include <time.h>

char *tzname[2];

    The first pointer points to the name of the local standard
    timezone.  The second pointer points to the name of the local
    summer timezone.  This variable is set by tzset().

  See also: daylight, timezone, tzset()


10 System calls
===============

System calls are documented in /emx/doc/system.doc.

All system calls are declared in <emx/syscalls.h>.  Interface routines
are in the emx.a and emx.lib libraries.  System call emulation
routines are in the sys.lib libraries.  Please do not use system calls
from application programs -- always use C library functions.  If you
need a system call, put a function into the library which issues the
system call.

Do not use INT 21H: the function numbers and the parameter passing
conventions are subject to change.  Similarities to DOS function
numbers are just coincidence and will probably disappear.  Moreover,
INT 21H, like any software interrupt, cannot be used under OS/2.  The
goal is to have Unix-like system calls.

--------------------------- END OF EMXLIB.DOC ------------------------------
