PCjs Machines

Home of the original IBM PC emulator for browsers.

Logo

MS C 6.0 Run-Time Library Reference

The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.

Microsoft  C - RUN-TIME LIBRARY REFERENCE








────────────────────────────────────────────────────────────────────────────
                Microsoft (R) C - RUN-TIME LIBRARY REFERENCE

                                FOR THE MS-DOS (R)
                                OPERATING SYSTEM
────────────────────────────────────────────────────────────────────────────


                            MICROSOFT CORPORATION








PUBLISHED BY
Microsoft Press
A Division of Microsoft Corporation
One Microsoft Way, Redmond, Washington 98052-6399

Copyright (C)  1990 by Microsoft Press

All rights reserved. No part of the contents of this book may be reproduced
or transmitted in any form or by any means without the written permission of
the publisher.

Library of Congress Cataloging-in-Publication Data

Microsoft C run-time library reference.

Includes  index.
1. C (Computer program language) 2. Microsoft C
(Computer program) 3. Macro instructions (Electronic
computers) I. Microsoft.
QA76.73.C15M52  1990         005.13'3         89-12240
ISBN 1-55615-225-6

Printed and bound in the United States of America.

1 2 3 4 5 6 7 8 9  HCHC 3 2 1 0 9

Distributed to the book trade in Canada by General Publishing Company, Ltd.

Distributed to the book trade outside the United States and Canada by
Penguin
Books  Ltd.

Penguin Books Ltd., Harmondsworth, Middlesex, England
Penguin Books Australia Ltd., Ringwood, Victoria, Australia
Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New Zealand

British Cataloging in Publication Data available.

                                            Sample
Writers:           Editors:                 Programs:
Phil Nelson        Amanda Clark             Bruce McKinney
Terry Ward         Moira Macdonald
                    Marjorie Manwaring
                    Bill Nolan

Microsoft, the Microsoft logo, MS-DOS, QuickC, and XENIX are
registered trademarks and Windows is a trademark of Microsoft Corporation.

AT&T and UNIX are registered trademarks of American Telephone
and Telegraph Company.

Hercules is a registered trademark of Hercules Computer
Technology.

IBM is a registered trademark of International Business
Machines Corporation.

Olivetti is a registered trademark of Ing. C. Olivetti.

Document No. 410840021-520-R00-1088
Part No. 04412




Table of Contents
────────────────────────────────────────────────────────────────────────────



Introduction
        About the C Run-Time Library
            ANSI C Compatibility
            OS/2 and XENIX(R) Programming
            Expanded Graphics Library
        About This Book
        Other Books of Interest
        Document Conventions


PART I  Overview
────────────────────────────────────────────────────────────────────────────


Chapter 1  Using C Library Routines

        1.1   Calling Library Routines
        1.2   Using Header Files
            1.2.1    Including Necessary Definitions
            1.2.2    Including Function Declarations
        1.3   File Names and Path Names
        1.4   Choosing Between Functions and Macros
        1.5   Stack Checking on Entry
        1.6   Handling Errors
        1.7   Operating-System Considerations
        1.8   Floating-Point Support
        1.9   Using Huge Arrays with Library Functions

Chapter 2  Run-Time Routines by Category

        2.1   Buffer Manipulation
        2.2   Character Classification and Conversion
        2.3   Data Conversion
        2.4   Directory Control
        2.5   File Handling
        2.6   Graphics
            2.6.1    Low-Level Graphics and Character-Font Functions
            2.6.2    Presentation-Graphics Functions
        2.7   Input and Output
            2.7.1    Text and Binary Modes
            2.7.2    Stream Routines
            2.7.3    Low-Level Routines
            2.7.4    Console and Port I/O
        2.8   Internationalization
        2.9   Math
        2.10  Memory Allocation
            2.10.1   Near and Far Heaps
            2.10.2   Based Heaps
        2.11  Process and Environment Control
        2.12  Searching and Sorting
        2.13  String Manipulation
        2.14  System Calls
            2.14.1   BIOS Interface
            2.14.2   DOS Interface
        2.15  Time
        2.16  Variable-Length Argument Lists

Chapter 3  Global Variables and Standard Types

        3.1   _amblksiz
        3.2   daylight, timezone, tzname
        3.3   _doserrno, errno, sys_errlist, sys_nerr
        3.4   _fmode
        3.5   _osmajor, _osminor, _osmode, _osversion
        3.6   environ
        3.7   _psp
        3.8   Standard Types


PART II  Run-Time Functions
────────────────────────────────────────────────────────────────────────────

        About the Run-Time Reference
            abort
            abs
            access
            acos Functions
            alloca
            _arc Functions
            asctime
            asin Functions
            assert
            atan Functions
            atexit
            atof, atoi, atol, _atold
            bdos
            _beginthread
            Bessel Functions
            _bfreeseg
            _bheapseg
            _bios_disk
            _bios_equiplist
            _bios_keybrd
            _bios_memsize
            _bios_printer
            _bios_serialcom
            _bios_timeofday
            bsearch
            cabs, cabsl
            calloc Functions
            ceil, ceill
            _cexit, _c_exit
            cgets
            _chain_intr
            chdir
            _chdrive
            chmod
            chsize
            _clear87
            clearerr
            _clearscreen
            clock
            close
            _control87
            cos Functions
            cprintf
            cputs
            creat
            cscanf
            ctime
            cwait
            dieeetomsbin, dmsbintoieee
            difftime
            _displaycursor
            div
            _dos_allocmem
            _dos_close
            _dos_creat Functions
            _dos_find Functions
            _dos_freemem
            _dos_getdate
            _dos_getdiskfree
            _dos_getdrive
            _dos_getfileattr
            _dos_getftime
            _dos_gettime
            _dos_getvect
            _dos_keep
            _dos_open
            _dos_read
            _dos_setblock
            _dos_setdate
            _dos_setdrive
            _dos_setfileattr
            _dos_setftime
            _dos_settime
            _dos_setvect
            _dos_write
            dosexterr
            dup, dup2
            ecvt
            _ellipse Functions
            _enable
            _endthread
            eof
            exec Functions
            exit, _exit
            exp, expl
            _expand Functions
            fabs, fabsl
            fclose, fcloseall
            fcvt
            fdopen
            feof
            ferror
            fflush
            fgetc, fgetchar
            fgetpos
            fgets
            fieeetomsbin, fmsbintoieee
            filelength
            fileno
            _floodfill, _floodfill_w
            floor, floorl
            flushall
            fmod, fmodl
            fopen
            FP_OFF, FP_SEG
            _fpreset
            fprintf
            fputc, fputchar
            fputs
            fread
            free Functions
            _freect
            freopen
            frexp, frexpl
            fscanf
            fseek
            fsetpos
            _fsopen
            fstat
            ftell
            ftime
            _fullpath
            fwrite
            gcvt
            _getactivepage
            _getarcinfo
            _getbkcolor
            getc, getchar
            getch, getche
            _getcolor
            _getcurrentposition Functions
            getcwd
            _getdcwd
            _getdrive
            getenv
            _getfillmask
            _getfontinfo
            _getgtextextent
            _getimage Functions
            _getlinestyle
            _getphyscoord
            getpid
            _getpixel Functions
            gets
            _gettextcolor
            _gettextcursor
            _gettextposition
            _gettextwindow
            _getvideoconfig
            _getviewcoord Functions
            _getvisualpage
            getw
            _getwindowcoord
            _getwritemode
            gmtime
            _grstatus
            halloc
            _hard Functions
            _heapadd Functions
            _heapchk Functions
            _heapmin Functions
            _heapset Functions
            _heapwalk Functions
            hfree
            hypot, hypotl
            _imagesize Functions
            inp, inpw
            int86
            int86x
            intdos
            intdosx
            is Functions
            isatty
            itoa
            kbhit
            labs
            ldexp, ldexpl
            ldiv
            lfind
            _lineto Functions
            localeconv
            localtime
            locking
            log Functions
            long double Functions
            longjmp
            _lrotl, _lrotr
            lsearch
            lseek
            ltoa
            _makepath
            malloc Functions
            matherr, _matherrl
            max
            _memavl
            memccpy, _fmemccpy
            memchr, _fmemchr
            memcmp, _fmemcmp
            memcpy, _fmemcpy
            memicmp, _fmemicmp
            _memmax
            memmove, _fmemmove
            memset, _fmemset
            min
            mkdir
            mktemp
            mktime
            modf, modfl
            movedata
            _moveto Functions
            _msize Functions
            onexit
            open
            _outgtext
            _outmem
            outp, outpw
            _outtext
            _pclose
            perror
            _pg_analyzechart Functions
            _pg_analyzepie
            _pg_analyzescatter Functions
            _pg_chart Functions
            _pg_chartscatter Functions
            _pg_chartpie
            _pg_defaultchart
            _pg_getchardef
            _pg_getpalette
            _pg_getstyleset
            _pg_hlabelchart
            _pg_initchart
            _pg_resetpalette
            _pg_resetstyleset
            _pg_setchardef
            _pg_setpalette
            _pg_setstyleset
            _pg_vlabelchart
            _pie Functions
            _pipe
            _polygon Functions
            _popen
            pow Functions
            printf
            putc, putchar
            putch
            putenv
            _putimage Functions
            puts
            putw
            qsort
            raise
            rand
            read
            realloc Functions
            _rectangle Functions
            _registerfonts
            _remapallpalette, _remappalette
            remove
            rename
            rewind
            rmdir
            rmtmp
            _rotl, _rotr
            scanf
            _scrolltextwindow
            _searchenv
            segread
            _selectpalette
            _setactivepage
            _setbkcolor
            setbuf
            _setcliprgn
            _setcolor
            _setfillmask
            _setfont
            _setgtextvector
            setjmp
            _setlinestyle
            setlocale
            setmode
            _setpixel Functions
            _settextcolor
            _settextcursor
            _settextposition
            _settextrows
            _settextwindow
            setvbuf
            _setvideomode
            _setvideomoderows
            _setvieworg
            _setviewport
            _setvisualpage
            _setwindow
            _setwritemode
            signal
            sin Functions
            sopen
            spawn Functions
            _splitpath
            sprintf
            sqrt, sqrtl
            srand
            sscanf
            stackavail
            stat
            _status87
            strcat, _fstrcat
            strchr, _fstrchr
            strcmp, _fstrcmp
            strcmpi
            strcoll
            strcpy, _fstrcpy
            strcspn, _fstrcspn
            _strdate
            strdup Functions
            strerror, _strerror
            strftime
            stricmp, _fstricmp
            strlen, _fstrlen
            strlwr, _fstrlwr
            strncat, _fstrncat
            strncmp, _fstrncmp
            strncpy, _fstrncpy
            strnicmp, _fstrnicmp
            strnset, _fstrnset
            strpbrk, _fstrpbrk
            strrchr, _fstrrchr
            strrev, _fstrrev
            strset, _fstrset
            strspn, _fstrspn
            strstr, _fstrstr
            _strtime
            strtod, strtol, _strtold, strtoul
            strtok, _fstrtok
            strupr, _fstrupr
            strxfrm
            swab
            system
            tan Functions
            tell
            tempnam, tmpnam
            time
            tmpfile
            toascii, tolower, toupper Functions
            tzset
            ultoa
            umask
            ungetc
            ungetch
            unlink
            _unregisterfonts
            utime
            va_arg, va_end, va_start
            vfprintf, vprintf, vsprintf
            wait
            _wrapon
            write

Index




Introduction
────────────────────────────────────────────────────────────────────────────

The Microsoft(R) C Run-Time Library is a set of over 500 ready-to-use
functions and macros designed for use in C programs. The run-time library
makes programming easier by providing


    ■   Fast and efficient routines to perform common programming tasks (such
        as string manipulation), sparing you the time and effort needed to
        write such routines

    ■   Reliable methods of performing operating-system functions (such as
        opening and closing files)


The C run-time library is important because it provides basic functions not
provided by the C language itself. These functions include input and output,
memory allocation, process control, graphics, and many others.

This book describes the Microsoft C run-time library routines included with
the Microsoft Professional Development System version 6.0. These comprise
all of the routines included with earlier versions of Microsoft C, as well
as many new routines.

────────────────────────────────────────────────────────────────────────────
NOTE

Microsoft documentation uses the term "OS/2" to refer to the OS/2
systems─Microsoft Operating System/2 (MS(R) OS/2) and IBM(R) OS/2.
Similarly, the term "DOS" refers to both the MS-DOS(R) and IBM Personal
Computer DOS operating systems. The name of a specific operating system is
used when it is necessary to note features that are unique to that system.
────────────────────────────────────────────────────────────────────────────


About the C Run-Time Library

The Microsoft C run-time library contains a number of new routines and
features which support American National Standards Institute (ANSI) C
compatibility, OS/2 and XENIX(R) programming, and sophisticated graphics
programming.

To ease the task of transporting programs from one operating system to
another, the description of each library routine includes compatibility
boxes, which show at a glance whether the routine is compatible with ANSI C,
MS-DOS, OS/2, UNIX(R), and XENIX. (In this book, references to XENIX systems
also encompass UNIX and other UNIX-like systems.)


ANSI C Compatibility

The C run-time library routines are designed for compatibility with the ANSI
C standard, which Microsoft C compilers support. The major innovation of
ANSI C is to permit argument-type lists in function prototypes
(declarations). Given the information in the function prototype, the
compiler can check later references to the function to make sure that the
references use the correct number and type of arguments and the correct
return value.

To take advantage of the compiler's type-checking ability, the include files
that accompany the C run-time library have been expanded. In addition to the
definitions and declarations required by library routines, the include files
now contain function declarations with argument-type lists. Several new
include files have also been added. The names of these files are chosen to
maximize compatibility with the ANSI C standard and with XENIX and UNIX
names.


OS/2 and XENIX(R) Programming

Microsoft C run-time library routines are designed to maintain maximum
compatibility between MS-DOS, OS/2, and XENIX or UNIX systems. The library
offers a number of operating-system interface routines that allow you to
take advantage of specific DOS and OS/2 features.

Most of the functions in the C library for DOS and OS/2 are compatible with
like-named routines in the C library for XENIX. For additional
compatibility, the math library functions have been extended to provide
exception handling in the same manner as the UNIX System V math functions.


Expanded Graphics Library

The Microsoft C run-time library now contains over one hundred graphics
routines. The core of this library consists of several dozen low-level
graphics routines, which allow your programs to select video modes, set
points, draw lines, change colors, and draw shapes such as rectangles and
ellipses. You can display real-valued data, such as floating-point values,
within windows of different sizes by using various coordinate systems.

Recent additions to the graphics library include presentation graphics and
fonts. The presentation-graphics library provides powerful tools for adding
presentation-quality graphics to your programs. These routines can display
data as a variety of graphs, including pie charts, bar and column charts,
line graphs, and scatter diagrams.

The fonts library allows your programs to display various styles and sizes
of text in graphics images or charts. You can use font-manipulation routines
with any graphics routines that display text, including presentation
graphics.


About This Book

This book assumes that you understand the C language and know how to compile
and link programs. If you have questions about these subjects, consult your
compiler documentation.

This book has two parts. Part 1, "Overview," introduces the Microsoft C
library. It describes general rules for using the library and summarizes the
main categories of library routines. Part 1 contains the following chapters:



    ■   Chapter 1, "Using C Library Routines," gives general rules for
        understanding and using C library routines and mentions special
        considerations that apply to certain routines. It is recommended that
        you read this chapter before using the run-time library; you may also
        want to turn to Chapter 1 when you have questions about library
        procedures.

    ■   Chapter 2, "Run-Time Routines by Category," lists the C library
        routines by category and discusses considerations that apply to each
        category. This chapter makes it easy to locate routines by task. Once
        you find the routine you want, turn to the reference page in Part 2
        for a detailed description.

    ■   Chapter 3, "Global Variables and Standard Types," describes variables
        and types that are used by library routines. Global variables and
        standard types are also described in the reference descriptions of the
        routines that use them.


Part 2, "Run-Time Functions," describes the library routines in alphabetical
order. Once you are familiar with the C library rules and procedures, you
will probably use this part most often.


Other Books of Interest

This book provides a guide to the C run-time library provided with the
Microsoft C Professional Development System version 6.0.

The following books cover a variety of topics that you may find useful. They
are listed only for your convenience. With the exception of its own
publications, Microsoft does not endorse these books or recommend them over
others on the same subject.


    ■   Barkakati, Nabajyoti. The Waite Group's Microsoft C Bible.
        Indianapolis, IN: Howard W. Sams, 1988.

        A topical guide to the Microsoft C run-time library. A similar volume
        is available for the Microsoft QuickC(R) product.

    ■   Campbell, Joe. C Programmer's Guide to Serial Communications.
        Indianapolis, IN: Howard W. Sams & Company, 1987.

        A comprehensive guide to the specialized area of serial communication
        programming in C.

    ■   Hansen, Augie. Proficient C: The Microsoft Guide to Intermediate &
        Advanced C Programming. Redmond, WA: Microsoft Press, 1987.

        An intermediate-level guide to C programming.

    ■   Harbison, Samuel P., and Guy L. Steele, Jr. C: A Reference Manual, 2d
        ed. Englewood Cliffs, NJ: Prentice Hall, 1987.

        A comprehensive guide to the C language and the standard library.

    ■   Kernighan, Brian W., and Dennis M. Ritchie. The C Programming
        Language, 2d ed. Englewood Cliffs, NJ: Prentice Hall, 1988.

        The first edition of this book is the classic definition of the C
        language. The second edition includes new information on the proposed
        ANSI C standard.

    ■   Lafore, Robert. Microsoft C Programming for the IBM. Indianapolis, IN:
        Howard W. Sams & Company, 1987.

        The first half of this book teaches C. The second half concentrates on
        specifics of the PC environment, such as BIOS calls, memory, and video
        displays.

    ■   Mark Williams Company. ANSI C: A Lexical Guide. Englewood Cliffs, NJ:
        Prentice Hall, 1988.

        A dictionary-style guide to the ANSI C standard.

    ■   Plauger, P. J., and Jim Brodie. Standard C. Redmond, WA: Microsoft
        Press, 1989.

        A quick reference guide to the ANSI C implementation by the secretary
        and chairman of the ANSI-authorized C Programming Language Standards
        Committee.

    ■   Plum, Thomas. Reliable Data Structures in C. Cardiff, NJ: Plum Hall,
        1985.

        An intermediate-level look at data structures using the C language.

    ■   Plum, Thomas, and Jim Brodie. Efficient C. Cardiff, NJ: Plum Hall,
        1985.

        A guide to techniques for increasing the efficiency of C programs.

    ■   Press, William H., Brian P. Flannery, Saul A. Teukolsky, and William
        T. Vetterling. Numerical Recipes in C: The Art of Scientific
        Computing. New York: Cambridge University Press, 1988.

        A comprehensive look at numerical techniques using the C language.

    ■   Schustack, Steve. Variations in C: Programming Techniques for
        Developing Efficient Professional Applications. Redmond, WA: Microsoft
        Press, 1985.

        An intermediate-level guide to developing business applications in C.

    ■   Ward, Robert. Debugging C. Indianapolis, IN: Que Corporation, 1986.

        An advanced guide to the theory and practice of debugging C programs.

    ■   Wilton, Richard. Programmer's Guide to PC and PS/2 Video
        Systems:Maximum Video Performance from the EGA, VGA, HGC, & MCGA.
        Redmond, WA: Microsoft Press, 1987.

        An advanced guide to all the PC and PS/2 video modes.



Document Conventions

This book uses the following document conventions :

Example                           Description
────────────────────────────────────────────────────────────────────────────
STDIO.H                           Uppercase letters indicate file names,
                                    segment names, registers, and terms used
                                    at the operating-system command level.

_far                              Boldface letters indicate C keywords,
                                    operators, language-specific characters,
                                    and library routines. Within discussions
                                    of syntax, bold type indicates that the
                                    text must be entered exactly as shown.

expression                        Words in italics indicate placeholders
                                    for information you must supply, such as
                                    a file name. Italics are also
                                    occasionally used for emphasis in the
                                    text.

[[option]]                        Items inside double square brackets are
                                    optional.

#pragma pack {1|2}                Braces and a vertical bar indicate a
                                    choice among two or more items. You must
                                    choose one of these items unless double
                                    square brackets surround the braces.

#include <io.h>                   This font is used for examples, user
                                    input, program output, and error
                                    messages in text.

CL options [[files...]]           Three dots following an item indicate
                                    that more items having the same form may
                                    appear.

while()                           A column of three dots tells you that
{                                 part of the example program has been
    .                              intentionally omitted.
    .
    .
}

CTRL+ENTER                        Small capital letters are used for the
                                    names of keys on the keyboard. When you
                                    see a plus sign (+) between two key
                                    names, you should hold down the first
                                    key while pressing the second.

                                    The carriage-return key, sometimes
                                    marked as a bent arrow on the keyboard,
                                    is called ENTER.

"argument"                        Quotation marks enclose a new term the
                                    first time it is defined in text.

"C string"                        Some C constructs, such as strings,
                                    require quotation marks. Quotation marks
                                    required by the language have the form "
                                    " and ' ' rather than " " and ' '.

Color Graphics Adapter (CGA)      The first time an acronym is used, it is
                                    often spelled out.






PART I  Overview
────────────────────────────────────────────────────────────────────────────

The first part of this book provides an overview of the run-time library
provided with the Microsoft C Professional Development System.

Chapter 1 is a general guide to the use of the run-time library routines.

Chapter 2 lists the routines by category.

Chapter 3 tells how to access global variables and types defined in the
run-time library.






Chapter 1  Using C Library Routines
────────────────────────────────────────────────────────────────────────────

This chapter provides basic information about how to use Microsoft C library
routines. It also describes some special rules, such as file- and path-name
conventions, that apply to particular routines. You should read this chapter
before you begin to use C library routines, and you may also want to refer
back to it if you have questions about library procedures.


1.1  Calling Library Routines

To use a C library routine, simply call it in your program, just as if it is
defined there. For instance, suppose you write the following program and
name it SAMPLE.C:

    #include <stdio.h>
    main()
    {
        printf( "Microsoft C" );
    }

The program prints  Microsoft C  by calling the printf routine, which is
part of the standard C library. Calling a library routine normally involves
two groups of files:


    1.  Header ("include") files that contain declarations and type
        definitions required by library routines

    2.  Library files that contain the library routines in compiled form


Header files and library files are both included with Microsoft C. Header
files are used when compiling, and library files are used when linking.

You include the necessary header files in your program source code with
#include directives. The description of each library routine in Part 2,
"Reference," tells you what header file the routine requires. Since printf
requires the STDIO.H header file, the SAMPLE.C program contains the
following line:

    #include <stdio.h>

This line causes the compiler to insert the contents of STDIO.H into the
source file SAMPLE.C.

After you compile the source file, you link the resulting object (.OBJ) file
with the appropriate library (.LIB) file to create an executable (.EXE)
file. Your object file contains the name of every routine that your program
calls, including library routines. If a routine is not defined in your
program, the linker searches for its code in a library file and includes
that code in the executable file.

Normally, the code for standard library routines is contained in the
"default library" that you create when installing Microsoft C. Since the
linker automatically searches the default library, you do not need to
specify that library's name when linking your program. The following command
links the example program with the default library:

    link sample,,,;

If you call a library routine that is not contained in the default library,
you must give the linker the name of the library file that contains the
routine. For instance, suppose your program uses a Microsoft C graphics
routine and you did not make GRAPHICS.LIB part of your default library when
installing Microsoft C. You would then link the program using a line like
the following:

    link sample,,, graphics.lib;

For more information about libraries and linking, consult the installation
documentation for your compiler.


1.2  Using Header Files

As stated in the previous section, you should include C header files when
using library routines. This section describes particular reasons why header
files are required.


1.2.1  Including Necessary Definitions

Many C library routines use constants, type definitions, or macros defined
in a header file. To use the routine, you must include the header file
containing the needed definition(s). The following list gives examples:

Definition                        Example
────────────────────────────────────────────────────────────────────────────
Macro                             If a library routine is implemented as a
                                    macro, the macro definition appears in a
                                    header file. For instance, the toupper
                                    macro is defined in the header file
                                    CTYPE.H.

Manifest constant                 Many library routines refer to constants
                                    that are defined in header files. For
                                    instance, the open routine uses
                                    constants such as O_CREAT, which is
                                    defined in the header file FCNTL.H.

Type definition                   Some library routines return a structure
                                    or take a structure as an argument. For
                                    example, stream input/output routines
                                    use a structure of type FILE, which is
                                    defined in STDIO.H.


1.2.2  Including Function Declarations

The Microsoft C header files also contain function declarations for every
function in the C library. These declarations are in the style recommended
by the ANSI C standard. Given these declarations, the compiler can perform
"type checking" on every reference to a library function, making sure that
you have used the correct return type and arguments. Function declarations
are sometimes called "prototypes," since the declaration serves as a
prototype or template for every subsequent reference to the function.

A function declaration lists the name of the function, its return type, and
the number and type of its arguments. For instance, below is the declaration
of the pow library function from the header file MATH.H:

    double pow( double x, double y );

The example declares that pow returns a value of type double and takes two
arguments of type double. Given this declaration, the compiler can check
every reference to pow in your program to ensure that the reference passes
two double arguments to pow and takes a return value of type double.

The compiler can perform type checking only for function references that
appear after the function declaration. Because of this, function
declarations normally appear near the beginning of the source file, prior to
any use of the functions they declare.

Function declarations are especially important for functions that return a
value of some type other than int, which is the default. For example, the
pow function returns a double value. If you do not declare such a function,
the compiler treats its return value as int, which can cause unexpected
results.

It is also a good practice to provide declarations for functions that you
write. If you do not want to type the declarations by hand, you can generate
them automatically by using the /Zg compiler option. This option causes the
compiler to generate ANSI-standard function declarations for every function
defined in the current source file. Redirect this output to a file, then
insert the file near the beginning of your source file.

Your program can contain more than one declaration of the same function, as
long as the declarations do not conflict. This is important if you have old
programs whose function declarations do not contain argument-type lists. For
instance, if your program contains the declaration

    char *calloc( );

you can later include the following declaration:

    char *calloc(unsigned, unsigned);

Because the two declarations are compatible, even though they are not
identical, no conflict occurs. The second declaration simply gives more
information about function arguments than the second. A conflict would
arise, however, if the declarations gave a different number of arguments or
gave arguments of different types.

Some library functions can take a variable number of arguments. For
instance, the printf function can take one argument or several. The compiler
can perform only limited type checking on such functions, a factor that
affects the following library functions:


    ■   In calls to cprintf, cscanf, printf, and scanf, only the first
        argument (the format string) is type checked.

    ■   In calls to fprintf, fscanf, sprintf, and sscanf, only the first two
        arguments (the file or buffer and the format string) are type checked.

    ■   In calls to open, only the first two arguments (the path name and the
        open flag) are type checked.

    ■   In calls to sopen, only the first three arguments (the path name, the
        open flag, and the sharing mode) are type checked.

    ■   In calls to execl, execle, execlp, and execlpe, only the first two
        arguments (the path name and the first argument pointer) are type
        checked.

    ■   In calls to spawnl, spawnle, spawnlp, and spawnlpe, only the first
        three arguments (the mode flag, the path name, and the first argument
        pointer) are type checked.



1.3  File Names and Path Names

Many library routines take strings representing paths and file names as
arguments. If you plan to transport your programs to the XENIX operating
system, you should remember that XENIX uses file- and path-name conventions
that are different from those used by DOS and OS/2. If you do not plan to
transport your programs to XENIX, you can skip this section.


Case Sensitivity

The DOS and OS/2 operating systems are not case sensitive (they do not
distinguish between uppercase and lowercase letters). Thus, SAMPLE.C and
Sample.C refer to the same file in DOS and OS/2. However, the XENIX
operating system is case sensitive. In XENIX, SAMPLE.C and Sample.C refer to
different files. To transport programs to XENIX, choose file and path names
that work correctly in XENIX, since either case works in DOS and OS/2. For
instance, the following directives are identical in DOS and OS/2, but only
the second works in XENIX:

    #include <STDIO.H>
    #include <stdio.h>


Subdirectory Conventions

Under XENIX, certain header files are normally placed in a subdirectory
named SYS. Microsoft C follows this convention to ease the process of
transporting programs to XENIX. If you do not plan to transport your
programs, you can place the SYS header files elsewhere.


Path-Name Delimiters

XENIX uses the slash (/) in path names, while DOS and OS/2 use the backslash
(\). To transport programs to XENIX, it is advantageous to use path-name
delimiters that are compatible with XENIX whenever possible.


1.4  Choosing Between Functions and Macros

This book uses the words "routine" and "function" interchangeably. However,
the term "routine" actually encompasses both functions and macros. Because
functions and macros have different properties, you should pay attention to
which form you are using. The descriptions in the reference section indicate
whether routines are implemented as functions or as macros.

Most routines in the Microsoft C library are functions. They consist of
compiled C code or assembled Microsoft Macro Assembler (MASM) code. However,
a few library routines are implemented as macros that behave like functions.
You can pass arguments to library macros and invoke them in the same way you
invoke functions.

The main benefit of using macros is faster execution time. A macro is
expanded (replaced by its definition) during preprocessing, creating in-line
code. Thus, macros do not have the overhead associated with function calls.
On the other hand, each use of a macro inserts the same code in your
program, whereas a function definition occurs only once regardless of how
many times it is called. Functions and macros thus offer a trade-off between
speed and size.

Apart from speed and size issues, macros and functions have some other
important differences:


    ■   Some macros treat arguments with side effects incorrectly when the
        macro evaluates its arguments more than once (see the example that
        follows this list). Not every macro has this effect. To determine if a
        macro handles side effects as desired, examine its definition in the
        appropriate header file.

    ■   A function name evaluates to an address, but a macro name does not.
        Thus, you cannot use a macro name in contexts requiring a function
        pointer. For instance, you can declare a pointer to a function, but
        you cannot declare a pointer to a macro.

    ■   You can declare functions, but you cannot declare macros. Thus, the
        compiler cannot perform type checking of macro arguments as it does of
        function arguments. However, the compiler can detect when you pass the
        wrong number of arguments to a macro.

    ■   You must always include the appropriate header file when using a
        library macro. Every library macro is defined with a #define directive
        in a header file. If you do not include the header file, the macro is
        undefined.


The following example demonstrates how some macros can produce unwanted side
effects. It uses the toupper routine from the standard C library.

    #include <ctype.h>

    int a = 'm';
    a = toupper(a++);

The example increments  a  when passing it as an argument to the toupper
routine, which is implemented as a macro. It is defined in CTYPE.H:

    #define toupper(c)  ( (islower(c)) ? _toupper(c) : (c) )

The definition uses the conditional operator (? :). The conditional
expression evaluates the argument  c  twice: once to check if it is
lowercase and again to create the result. This macro evaluates the argument
a++  twice, increasing  a  by 2 instead of 1. As a result, the value
operated on by islower differs from the value operated on by _toupper.

Like some other library routines, toupper is provided in both macro and
function versions. The header file CTYPE.H not only declares the toupper
function but also defines the toupper macro.

Choosing between the macro version and function version of such routines is
easy. If you wish to use the macro version, you can simply include the
header file that contains the macro definition. Because the macro definition
of the routine always appears after the function declaration, the macro
definition normally takes precedence. Thus, if your program includes CTYPE.H
and then calls toupper, the compiler uses the toupper macro:

    #include <ctype.h>

    int a = 'm';
    a = toupper(a);

You can force the compiler to use the function version of a routine by
enclosing the routine's name in parentheses:

    #include <ctype.h>

    int a = 'm';
    a = (toupper) (a);

Because the name toupper is not immediately followed by a left parenthesis,
the compiler cannot interpret it as a macro name. It must use the toupper
function.

A second way to do this is to "undefine" the macro definition with the
#undef directive:

    #include <ctype.h>
    #undef toupper

Since the macro definition no longer exists, subsequent references to
toupper use the function version.

A third way to make sure the compiler uses the function version is to
declare the function explicitly:

    #include <ctype.h>
    int toupper(int _c);

Since this function declaration appears after the macro definition in
CTYPE.H, it causes the compiler to use the toupper function.


1.5  Stack Checking on Entry

For certain library routines, the compiler performs stack checking on entry.
(The "stack" is a memory area used for temporary storage.) Upon entry to
such a routine, the stack is checked to determine if it has enough room for
the local variables used by that routine. If it does, space is allocated by
adjusting the stack pointer. Otherwise, a "stack overflow" run-time error
occurs. If stack checking is disabled, the compiler assumes there is enough
stack space; if there is not, you might overwrite memory locations in the
data segment and receive no warning.

Typically, stack checking is enabled only for functions with large
local-variable requirements (more than about 150 bytes), since there is
enough free space between the stack and data segments to handle functions
with smaller requirements. If the function is called many times, stack
checking slows execution slightly.

Stack checking is enabled for the following library functions:

execvp          printf          spawnvpe        system
execvpe         scanf           sprintf         vprintf
fprintf         spawnvp         sscanf          write
fscanf

1.6  Handling Errors

Many library routines return a value that indicates an error condition. To
avoid unexpected results, your code should always check such error values
and handle all of the possible error conditions. The description of each
library routine in the reference section lists the routine's return
value(s).

Some library functions do not have a set error return. These include
functions that return nothing and functions whose range of return values
makes it impossible to return a unique error value. To aid in error
handling, some functions in this category set the value of a global variable
named errno.

If the reference description of a routine states that it sets the errno
variable, you can use errno in two ways:


    1.  Compare errno to the values defined in the header file ERRNO.H.

    2.  Handle errno with the perror or strerror library routines. The perror
        routine prints a system error message to the standard error (stderr).
        The strerror routine stores the same information in a string for later
        use.


When you use errno, perror, and strerror, remember that the value of errno
reflects the error value for the last call that set errno. To avoid
confusion, you should always test the return value to verify that an error
actually occurred. Once you determine that an error has occurred, use errno
or perror immediately. Otherwise, the value of errno may be changed by
intervening calls.

Library math routines set errno by calling the matherr or _matherrl library
routines, which are described in the reference section. If you wish to
handle math errors differently from these routines, you can write your own
routine and name it matherr or _matherrl. Your routine must follow the rules
listed in the matherr reference description.

The ferror library routine allows you to check for errors in stream
input/output operations. This routine checks if an error indicator has been
set for a given stream. Closing or rewinding the stream automatically clears
the error indicator. You can also reset the error indicator by calling the
clearerr library routine.

The feof library routine tests for end-of-file on a given stream. An
end-of-file condition in low-level input and output can be detected with the
eof routine or when a read operation returns 0 as the number of bytes read.


The _grstatus library routine allows you to check for errors after calling
certain graphics library operations. See the reference page on the _grstatus
function for details.


1.7  Operating-System Considerations

The library routines listed in this section behave differently under
different operating system versions. For more information on an individual
routine, see the description of that routine in the reference section.

Routine                           Restrictions
────────────────────────────────────────────────────────────────────────────
locking                           These routines are effective only in
sopen                             OS/2 and in DOS versions 3.0 and later.
_fsopen

dosexterr                         The dosexterr routine provides error
                                    handling for system call 0x59 (get
                                    extended error) in DOS versions 3.0 and
                                    later.

dup                               The dup and dup2 routines can cause
dup2                              unexpected results in DOS versions
                                    earlier than 3.0. If you use dup or dup2
                                    to create a duplicate file handle for
                                    stdin, stdout, stderr, stdaux, or stdprn
                                    , calling the close function with one
                                    handle causes errors in later I/O
                                    operations that use the other handle.
                                    This anomaly does not occur in OS/2 or
                                    in DOS versions 3.0 and later.

exec                              When using the exec and spawn families
spawn                             of functions under DOS versions earlier
                                    than 3.0, the value of the arg0 argument
                                    (or argv[0] to the child process) is not
                                    available to the user; a null string (""
                                    ) is stored in that position instead. In
                                    OS/2, the arg0 argument contains the
                                    command name; in DOS versions 3.0 and
                                    later, it contains the complete command
                                    path.

Microsoft C defines global variables that indicate the version of the
current operating system. You can use these to determine the
operating-system version in which a program is executing. See Chapter 3,
"Global Variables and Standard Types," for more information.


1.8  Floating-Point Support

Microsoft math library routines require floating-point support to perform
calculations with real numbers (numbers that can contain fractions). This
support can be provided by the floating-point libraries that accompany your
compiler software or by an 8087, 80287, or 80387 coprocessor. The names of
the functions that require floating-point support are listed below:

acos            cos             fmod            modfl
acosl           cosl            fmodl           pow
asin            cosh            fmsbintoieee    powl
asinl           coshl           _fpreset        sin
atan            dieeetomsbin    frexp           sinl
atanl           difftime        frexpl          sinh
atan2           dmsbintoieee    gcvt            sinhl
atan2l          ecvt            hypot           sqrt
atof            exp             hypotl          sqrtl
_atold          expl            ldexp           _status87
bessel          fabs            ldexpl          strtod
cabs            fabsl           log             _strtold
cabsl           fcvt            logl            tan
ceil            fieeetomsbin    log10           tanl
ceill           floor           log10l          tanh
_clear87        floorl          modf            tanhl
_control87

Note that the bessel routine does not correspond to a single function, but
to twelve functions named j0, j1, jn, y0, y1, yn, _j0l, _j1l, _jnl, _y0l,
_y1l, and _ynl. Also note that the _clear87 and _control87 functions are not
available with the /FPa compiler option.

Also requiring floating-point support is the printf family of functions
(cprintf, fprintf, printf, sprintf, vfprintf, vprintf, and vsprintf). These
functions require support for floating-point input and output if used to
print floating-point values.

The C compiler tries to detect whether floating-point values are used in a
program so that supporting functions are loaded only if required. This
behavior saves a considerable amount of space for programs that do not
require floating-point support.

When you use a floating-point type specifier in the format string for a
printf or scanf call, make sure you specify floating-point values or
pointers to floating-point values in the argument list. These must
correspond to any floating-point

type specifiers in the format string. The presence of floating-point
arguments allows the compiler to detect that floating-point support code is
required. If a floating-point type specifier is used to print an integer
argument, for example, floating-point values will not be detected because
the compiler does not actually read the format string used in the printf and
scanf functions. For instance, the following program produces an error at
run time:

    main( ) /* This example causes an error */
    {
    long f = 10L;
    printf("%f", f);
    }

In the preceding example, the functions for floating-point support are not
loaded because


    ■   No floating-point arguments are given in the call to printf.

    ■   No floating-point values are used elsewhere in the program.


As a result, the following error occurs:

    Floating point not loaded

Here is a corrected version of the above call to printf in which the long
integer value is cast to double:

    main( ) /* This example works correctly */
    {
    long f = 10L;
    printf("%f", (double) f);
    }


1.9  Using Huge Arrays with Library Functions

In programs that use small, compact, medium, and large memory models,
Microsoft C allows you to use arrays exceeding the 64K (kilobyte) limit of
physical memory in these models by explicitly declaring the arrays as _huge.
However, generally, you cannot pass _huge data items as arguments to C
library functions. In the compact-model library used by compact-model
programs and in the large-model library used by both large-model and
huge-model programs, only the functions listed below use argument arithmetic
that works with _huge items:

bsearch         _fmemcmp        _fmemset        lsearch
fread           _fmemcpy        halloc          memccpy
fwrite          _fmemicmp       hfree           memchr
_fmemccpy       _fmemmove       lfind
_fmemchr

With this set of functions, you can read from, write to, search, sort, copy,
initialize, compare, or dynamically allocate and free _huge arrays; the
_huge array can be passed without difficulty to any of these functions in a
compact-, large-, or huge-model program. The model-independent routines in
the above list (those beginning with _f) are available in all memory models.


The memset, memcpy, and memcmplibrary routines are available in two
versions: as C functions and as intrinsic (in-line) code. The function
versions of these routines support huge pointers in compact and large memory
models, but the intrinsic versions do not support huge pointers. (The
function version of such routines generates a call to a library function,
whereas the intrinsic version inserts in-line code into your program. Your
compiler documentation explains how to select the intrinsic versions of
library routines.)




Chapter 2  Run-Time Routines by Category
────────────────────────────────────────────────────────────────────────────

Microsoft C library routines handle various kinds of tasks. If you know the
type of task you need done, but don't know exactly which routine to use, the
categorized lists of routines in this chapter can help.

The descriptions here are intended only to give you a brief overview of the
capabilities of the run-time library. For a complete description of the
behavior, syntax, and use of each routine, see Part 2, "Run-Time Functions."


The main categories of library routines are


    ■   Buffer manipulation

    ■   Character classification and conversion

    ■   Data conversion

    ■   Directory control

    ■   File handling

    ■   Graphics

    ■   Input and output

    ■   Internationalization

    ■   Math

    ■   Memory allocation

    ■   Process and environment control

    ■   Searching and sorting

    ■   String manipulation

    ■   System calls

    ■   Time

    ■   Variable-length argument lists



2.1  Buffer Manipulation

The buffer-manipulation routines are useful for working with areas of memory
on a character-by-character basis. A "buffer" is an array of characters,
similar to a character string. However, unlike strings, buffers are not
usually terminated with a null character ('\0'). Therefore, the
buffer-manipulation routines always take a length or count argument.
Function declarations for the buffermanipulation routines are given in the
include files MEMORY.H and STRING.H, with an exception being the swab
function, which appears in STDLIB.H.

Routines beginning with _f  are model independent; the _f  stands for far.
These routines are useful in writing mixed-model programs because they can
be called from any program, regardless of the memory model being used.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
memccpy,  _fmemccpy               Copy characters from one buffer to
                                    another until a given character or a
                                    given number of characters has been
                                    copied

memchr,  _fmemchr                 Return a pointer to the first
                                    occurrence, within a specified number of
                                    characters, of a given character in the
                                    buffer

memcmp,  _fmemcmp                 Compare a specified number of characters
                                    from two buffers

memcpy,  _fmemcpy                 Copy a specified number of characters
                                    from one buffer to another

memicmp, _fmemicmp                Compare a specified number of characters
                                    from two buffers without regard to the
                                    case of the letters (uppercase and
                                    lowercase treated as equivalent)

memmove,                          Copy a specified number of characters
_fmemmove                         from one buffer to another

memset,  _fmemset                 Use a given character to initialize a
                                    specified number of bytes in the buffer


swab                              Swaps bytes of data and stores them at
                                    the specified location

When the source and target areas overlap, only the memmove and _fmemmove
functions are guaranteed to copy the full source properly. (The memcpy and
_fmemcpy routines do not always copy the full source in such cases.)


2.2  Character Classification and Conversion

The character classification and conversion routines allow you to test
individual characters in a variety of ways and to convert between uppercase
and lowercase characters.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
isalnum                           Tests for alphanumeric character

isalpha                           Tests for alphabetic character

isascii                           Tests for ASCII character

iscntrl                           Tests for control character

isdigit                           Tests for decimal digit

isgraph                           Tests for printable character except
                                    space

islower                           Tests for lowercase character

isprint                           Tests for printable character

ispunct                           Tests for punctuation character

isspace                           Tests for white-space character

isupper                           Tests for uppercase character

isxdigit                          Tests for hexadecimal digit

toascii                           Converts character to ASCII code

tolower                           Tests character and converts to
                                    lowercase if uppercase

_tolower                          Converts character to lowercase
                                    (unconditional)

toupper                           Tests character and converts to
                                    uppercase if
                                    lowercase

_toupper                          Converts character to uppercase
                                    (unconditional)

The classification routines identify characters by finding them in a table
of classification codes. Using these routines to classify characters is
generally faster than writing a test expression such as the following:

    if ((c >= 0) || c <= 0x7f))

All of these routines are implemented in two versions: as functions and as
macros. The function prototypes and macro definitions appear in CTYPE.H.
Section 1.4, "Choosing Between Functions and Macros," explains how to choose
the appropriate version. The toupper and tolower functions are also declared
in the STDLIB.H header file.


2.3  Data Conversion

The data-conversion routines convert numbers to strings of ASCII characters
and vice versa. These routines are implemented as functions, all of which
are declared in the include file STDLIB.H. The atof function, which converts
a string to a floating-point value, is also declared in MATH.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
abs                               Finds absolute value of integer

atof                              Converts string to float

atoi                              Converts string to int

atol                              Converts string to long

_atold                            Converts string to long double

ecvt                              Converts double to string

fcvt                              Converts double to string

gcvt                              Converts double to string

itoa                              Converts int to string

labs                              Finds absolute value of long integer

ltoa                              Converts long to string

strtod                            Converts string to double

strtol                            Converts string to a long integer

_strtold                          Converts string to long double

strtoul                           Converts string to an unsigned long
                                    integer

ultoa                             Converts unsigned long to string


2.4  Directory Control

The directory-control routines let a program access, modify, and obtain
information about the directory structure. These routines are functions and
are declared in DIRECT.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
chdir                             Changes current working directory

_chdrive                          Changes current drive

getcwd                            Gets current working directory

_getdcwd                          Gets current working directory for the
                                    specified drive

_getdrive                         Gets the current disk drive

mkdir                             Makes a new directory

rmdir                             Removes a directory

_searchenv                        Searches for a given file on specified
                                    paths


2.5  File Handling

The file-handling routines let you create, manipulate, and delete files.
They also set and check file-access permissions.

File-handling routines work on a file designated by a path name or by a
"file handle," an integer assigned by the operating system that identifies
an open file. These routines modify or give information about the designated
file. Most of them are declared in the include file IO.H, with the
exceptions being the fstat and stat functions (declared in SYS\STAT.H), the
_fullpath routine (declared in DIRECT.H), and the remove and rename
functions (also declared in STDIO.H).

Routine                           Use
────────────────────────────────────────────────────────────────────────────
access                            Checks file-permission setting

chmod                             Changes file-permission setting

chsize                            Changes file size

filelength                        Gets file length

fstat                             Gets file-status information on handle

_fullpath                         Makes an absolute path name from a
                                    relative path name

isatty                            Checks for character device

locking                           Locks areas of file (available with OS/2
                                    and
                                    DOS versions 3.0 and later)

_makepath                         Merges path-name components into a
                                    single, full path name

mktemp                            Creates unique file name

remove                            Deletes file

rename                            Renames file

setmode                           Sets file-translation mode

_splitpath                        Splits a path name into component pieces

stat                              Gets file-status information on named
                                    file

umask                             Sets default-permission mask

unlink                            Deletes file

The access, chmod, _fullpath, _makepath, remove, rename, _splitpath, stat,
and unlink routines operate on files specified by a path name or file name.


The chsize, filelength, fstat, isatty, locking, and setmode routines work
with files designated by a file handle.

The mktemp and umask routines have functions that are slightly different
from the other routines. The mktemp routine creates a unique file name, and
the programmer can use mktemp to create unique file names that do not
conflict with the names of existing files. The umask routine sets the
default permission mask for any new files created in a program. The mask can
override the permission setting given in the open or creat call for the new
file.


2.6  Graphics

Microsoft C graphics routines offer a wide variety of graphics functions,
low-level graphics primitives, font functions, and presentation graphics
(displays such as graphs and pie charts).

Graphics functions are supplied in two libraries that must be explicitly
linked with your program. The GRAPHICS.LIB library provides support for
low-level graphics and character-font routines. The library PGCHART.LIB
supports presentation-graphics routines.


2.6.1  Low-Level Graphics and Character-Font Functions

The low-level graphics and font functions are declared in the include file
GRAPH.H.

The library can be divided into the eight categories listed below, which
correspond to the different tasks involved in creating and manipulating
graphic objects.

Most graphics routines work only in DOS. Two categories of routines
("configuring mode and environment" and "creating text output") work in OS/2
as well as DOS.

Category                          Task
────────────────────────────────────────────────────────────────────────────
Configuring mode and environment  Select the proper display mode for the
(OS/2 and DOS)                    hardware and establish memory areas for
                                    writing and displaying of images

Setting coordinates               Specify the logical origin and the
                                    active display area within the screen

Setting low-level graphics        Specify a palette mapping for low-level
palettes                          graphics routines

Setting attributes                Specify background and foreground
                                    colors, fill masks, and line styles for
                                    low-level graphics routines

Creating graphics                 Draw and fill figures
output

Creating text output (OS/2 and    Write text on the screen
DOS)

Transferring images               Store images in memory and retrieve them

Displaying fonts                  Display text in character fonts
                                    compatible with Microsoft Windows(tm)

The following sections explain each of these categories.


2.6.1.1  Configuring Mode and Environment

Routines that configure the mode and environment establish the graphics or
text mode of operation, determine the current graphics environment, and
control the display of the cursor.

All of the routines listed in this section are available in OS/2 as well as
DOS.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_clearscreen                      Erases the screen and fills it with the
                                    current background color

_getactivepage                    Gets the current active page number

_getbkcolor                       Returns the current background color

_getvideoconfig                   Obtains status of current graphics
                                    environment

_getvisualpage                    Gets the current visual page number

_grstatus                         Returns the status of the most recent
                                    graphics function call

_setactivepage                    Sets memory area for the active page for
                                    writing
                                    images

_setbkcolor                       Sets the current background color

_settextrows                      Sets the number of text rows

_setvideomode                     Selects an operating mode for the
                                    display screen

_setvideomoderows                 Sets the video mode and the number of
                                    rows for text operations

_setvisualpage                    Sets memory area for the current visual
                                    page


2.6.1.2  Setting Coordinates

The "set coordinates" routines set the current text or graphics position and
convert pixel coordinates between the various graphic coordinate systems.

The Microsoft C graphics functions recognize three sets of coordinates:


    1.  Fixed physical coordinates

    2.  View coordinates defined by the application

    3.  Window coordinates that can include floating-point values


The functions in this category establish window and view coordinate systems
and translate between physical, view, and window coordinate systems.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_getcurrentposition               Determines current position in view
                                    coordinates

_getcurrentposition_w             Determines current position in window
                                    coordinates

_getphyscoord                     Converts view coordinates to physical
                                    coordinates

_getviewcoord                     Converts physical coordinates to view
                                    coordinates

_getviewcoord_w                   Converts window coordinates to view
                                    coordinates

_getviewcoord_wxy                 Converts window coordinates in _wxycoord
                                    structure to view coordinates

_getwindowcoord                   Converts view coordinates to window
                                    coordinates

_setcliprgn                       Limits graphic output to a region of the
                                    screen

_setvieworg                       Positions the view-coordinate origin

_setviewport                      Limits graphics output to a region of
                                    the screen and positions the
                                    view-coordinate origin to the upper-left
                                    corner of that region

_setwindow                        Defines a floating-point window
                                    coordinate system

The default view coordinate system is identical to the physical screen
coordinate system. The physical origin (0, 0) is always in the upper-left
corner of the display. The x axis extends in the positive direction left to
right, while the y axis extends in the positive direction top to bottom.

The physical horizontal and vertical dimensions depend on the hardware
display configuration and the selected mode. These values are accessible at
run time by examining the numxpixels and numypixels fields of the
videoconfig structure returned by _getvideoconfig. (The _getvideoconfig
routine is listed in the previous section.)

The _setvieworg function allows you to move the viewport origin to a new
position relative to the physical screen.

Routines that refer to coordinates on the physical screen or viewport
require integer values. However, in real-world graphing applications, you
might wish to use floating-point values, such as stock prices or average
rainfall. The window coordinate system allows you to display graphics using
floating-point values instead of integers.

The _getcurrentposition and _getcurrentposition_w routines allow you to
determine the location of the current graphics-output point.

The _setcliprgn function defines a restricted active display area on the
screen. The _setviewport function does the same thing and also resets the
viewport origin to the upper-left corner of the restricted active display
area.

The physical coordinates of any view-coordinate point can be determined with
the _getphyscoord function, and the view coordinates of any physical point
can be determined with the _getviewcoord function.

The view coordinates of any window coordinate can be determined with the
_getviewcoord_w and _getviewcoord_wxy functions. The window coordinates of
any view coordinate can be determined with the _getwindowcoord function.

The _setwindow function defines the current viewport as a real-coordinate
window bound by the specified floating-point values.


2.6.1.3  Setting Low-Level Graphics Palettes

Use the low-level palette routines to select or remap color palettes.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_remapallpalette                  Changes all color indexes in the current
                                    palette

_remappalette                     Changes a single color index in the
                                    current palette

_selectpalette                    Selects a predefined palette

Some video modes support a "color palette," which is a table of the color
values that can be displayed together on the screen at any given time. A
"color value" is a long integer representing a color that can be displayed
on your system.

In CGA color graphics modes, you can use the _selectpalette routine to
choose one of several predefined palettes.

On EGA and VGA video systems, you can "remap" (change) the palette using the
_remappalette or _remapallpalette routines. For instance, the EGA _ERESCOLOR
mode offers a total of 64 color values, of which 16 can be displayed at a
time. In this mode, the palette contains 16 "color indices," or slots to
which you can assign color values.

The _remappalette routine changes a single color index to a specified color
value. The _remapallpalette routine changes all of the available palette
entries simultaneously.


2.6.1.4  Setting Attributes

The low-level output functions that draw lines, arcs, ellipses, and other
basic figures do not specify color or line-style information. Instead, the
low-level graphics functions rely on a set of attributes that are set
independently by the following functions:

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_getarcinfo                       Determines the endpoints in viewport
                                    coordinates of the most recently drawn
                                    arc or pie

_getcolor                         Gets the current color

_getfillmask                      Gets the current fill mask

_getlinestyle                     Gets the current line-style mask

_getwritemode                     Gets the current logical write mode

_setcolor                         Sets the current color

_setfillmask                      Sets the current fill mask

_setlinestyle                     Sets the current line-style mask

_setwritemode                     Sets logical write mode for line drawing

The _getcolor and _setcolor functions get or set the current color index for
graphics and font output. The _getbkcolor and _setbkcolor functions get or
set the current background color.

The _getfillmask and _setfillmask functions get or set the current fill
mask. The mask is an 8-by-8-bit template array, with each bit representing a
pixel. If a bit is 0, the pixel in memory is left untouched, as the mask is
transparent to that pixel. If a bit is 1, the pixel is assigned the current
color value. The template is repeated as necessary over the entire fill
area.

The _getlinestyle and _setlinestyle functions get or set the current line
style. The line style is determined by a 16-bit template buffer with each
bit corresponding to a pixel. If a bit is 1, the pixel is set to the current
color. If a bit is 0, the pixel is not changed. The template is repeated for
the length of the line.

The _getwritemode and _setwritemode functions get or set the logical write
mode for straight line drawing. The default mode, _GPSET, causes lines to be
drawn in the current graphics color. Other modes combine the current
graphics color and the original screen image using various logical
operations.


2.6.1.5  Creating Graphics Output

The graphics output functions use a set of specified coordinates and draw
various figures. They use the current or default attributes for line-style
mask, fill mask, write mode, background color, and foreground color.

The name of each function announces its task or the figure it draws, as the
following list indicates:

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_arc,  _arc_w,  _arc_wxy          Draw an arc

_ellipse,  _ellipse_w,            Draw an ellipse or circle
_ellipse_wxy

_floodfill,  _floodfill_w         Flood-fill an area of the screen with
                                    the current color

_getcurrentposition,              Obtain the current graphic-output
_getcurrentposition_w             position used by _lineto and _outgtext

_getpixel, _getpixel_w            Obtain a pixel's color

_lineto,  _lineto_w               Draw a line from the current graphic
                                    output position to a specified point

_moveto,  _moveto_w               Move the current graphic-output position
                                    to a specified point

_pie,  _pie_w,  _pie_wxy          Draw a pie-slice-shaped figure

_polygon,  _polygon_w,            Draw or scan-fill a polygon
_polygon_wxy

_rectangle,  _rectangle_w,        Draw or scan-fill a rectangle
_rectangle_wxy

_setpixel,  _setpixel_w           Set a pixel's color

Most of these routines are available in several forms, which are indicated
by their names. Output functions without a suffix use the view coordinate
system. Functions that end with _w take double values as arguments and use
the window coordinate system. Functions that end with _wxy use _wxycoord
structures to define the coordinates and use the window coordinate system.

Circular figures, such as arcs and ellipses, are centered within a "bounding
rectangle" specified by two points that define the diagonally opposed
corners of the rectangle. The center of the rectangle becomes the center of
the figure, and the rectangle's borders determine the size of the figure.


2.6.1.6  Creating Text Output

The next group of routines provides text output in both graphics and text
modes. Unlike the standard console I/O library routines, these functions
recognize text-window boundaries and use the current text color.

All of the routines listed in this section work in OS/2 as well as DOS.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_displaycursor                    Sets the cursor on or off upon exit from
                                    a graphics routine

_gettextcolor                     Obtains the current text color

_gettextcursor                    Returns the current cursor attribute
                                    (text modes only)

_gettextposition                  Obtains the current text-output position

_gettextwindow                    Gets the current text window boundaries

_outmem                           Prints text of a specified length from a
                                    memory
                                    buffer

_outtext                          Outputs a text string to the screen at
                                    the current text position

_scrolltextwindow                 Scrolls the current text window up or
                                    down

_settextcolor                     Sets the current text color

_settextcursor                    Sets the current cursor attribute (text
                                    modes only)

_settextposition                  Relocates the current text position

_settextwindow                    Defines the current text-display window

_wrapon                           Enables or disables line wrap

The _outtext and _outmem routines provide no formatting. If you want to
output integer or floating-point values, you must convert the values into a
string variable (using the sprintf function) before calling these routines.


The _outtext routine recognizes the \n (newline character) and \r (carriage
return) sequences. The _outmem routine treats these sequences as printable
graphics characters.


2.6.1.7  Transferring Images

The functions in this category transfer screen images between memory and the
display, using a buffer allocated by the application, or determine the size
in bytes of the buffer needed to store a given image.

The functions that end with _w or _wxy use window coordinates; the other
functions in this set use view coordinates.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_getimage,                        Store a screen image in memory
_getimage_w,
_getimage_wxy

_imagesize,                       Return the size (in bytes) of the buffer
_imagesize_w,                     needed to store the image
_imagesize_wxy

_putimage,                        Retrieve an image from memory and
_putimage_w                       display it

In some cases, the buffer needed to store an image with the _getimage
functions must be larger than 64K (65,535) bytes. Use the halloc routine to
allocate a buffer larger than 64K.


2.6.1.8  Displaying Fonts

The functions listed in this section control the display of font-based
characters on the screen.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_getfontinfo                      Obtains the current font characteristics

_getgtextextent                   Determines the width in pixels of
                                    specified text in the current font

_getgtextvector                   Gets orientation of font text output

_outgtext                         Outputs text in the current font to the
                                    screen at the specified pixel position

_registerfonts                    Initializes font library

_setfont                          Finds a single font that matches a
                                    specified set of characteristics and
                                    makes this font the current font for use
                                    by the _outgtext function

_setgtextvector                   Sets the current orientation for font
                                    text output

_unregisterfonts                  Frees memory allocated by _registerfonts


2.6.2  Presentation-Graphics Functions

The presentation-graphics functions are declared in the PGCHART.H include
file. The library can be divided into the three categories listed below,
corresponding to the different tasks involved in creating and manipulating
graphic objects:

Category                          Task
────────────────────────────────────────────────────────────────────────────
Displaying presentation graphics  Initialize video structures for
                                    presentation graphics and establishes
                                    the default chart type. Display
                                    presentation-graphics chart: bar,
                                    column, pie, scatter, or line chart.

Analyzing                         Analyze data (does not display chart).
presentation-graphics data

Manipulating                      Modify basic chart structures (e.g.,
presentation-graphics structures  palettes, cross-hatching styles).


2.6.2.1  Displaying Presentation Graphics

The functions listed in this section initialize the presentation-graphics
library and display the specified graph type.

Because the _pg_initchart routine initializes the presentation-graphics
library, it must be called before any other function in the
presentation-graphics library. The _pg_defaultchart function initializes the
variables in the chart environment.

The other routines in this category display the specified graph. The
single-series versions plot one set of data, and the multiseries versions
(those ending with an ms suffix) plot several sets of data in the same chart
style.

Presentation-graphics programs can display text in different font sizes by
taking advantage of font-based characters (see Section 2.6.1.8, "Displaying
Fonts.") Call the _registerfonts and _setfont routines to select a font
before calling the _pginitchart routine. Subsequent charts use the selected
font. You can later call the _unregisterfonts routine to restore the default
character font and free the memory previously allocated for fonts.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_pg_chart                         Displays a single-series bar, column, or
                                    line chart

_pg_chartms                       Displays a multiseries bar, column, or
                                    line chart

_pg_chartpie                      Displays a pie chart

_pg_chartscatter                  Displays a scatter diagram for a single
                                    series of data

_pg_chartscatterms                Displays a scatter diagram for more than
                                    one series of data

_pg_defaultchart                  Initializes all necessary variables in
                                    the chart environment for a specified
                                    chart type

_pg_initchart                     Initializes the presentation-graphics
                                    library


2.6.2.2  Analyzing Presentation-Graphics Charts

These routines calculate default values for the specified graph type but do
not display the chart. The single-series versions analyze one set of data,
and the multiseries versions analyze several sets of data in the same chart
style.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_pg_analyzechart                  Analyzes a single series of data for a
                                    bar, column, or line chart

_pg_analyzechartms                Analyzes a multiseries of data for a
                                    bar, column, or line chart

_pg_analyzepie                    Analyzes data for a pie chart

_pg_analyzescatter                Analyzes a single series of data for a
                                    scatter diagram

_pg_analyzescatterms              Analyzes a multiseries of data for a
                                    scatter diagram


2.6.2.3  Manipulating Presentation-Graphics Structures

These functions control low-level aspects of the presentation-graphics
package.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_pg_hlabelchart                   Writes text horizontally on the screen

_pg_vlabelchart                   Writes text vertically on the screen

_pg_getpalette                    Retrieves current colors, line styles,
                                    fill patterns, and plot characters for
                                    all presentation-graphics palettes

_pg_setpalette                    Sets current colors, line styles, fill
                                    patterns, and plot characters for all
                                    presentation-graphics palettes

_pg_resetpalette                  Sets current colors, line styles, fill
                                    patterns, and plot characters to the
                                    default values for the current screen
                                    mode

_pg_getstyleset                   Retrieves the contents of the current
                                    styleset

_pg_setstyleset                   Sets the contents of the current
                                    styleset

_pg_resetstyleset                 Resets the contents of the current
                                    styleset to the default value for the
                                    current screen mode

_pg_getchardef                    Retrieves the current 8-by-8-pixel bit
                                    map for a specified character

_pg_setchardef                    Sets the 8-by-8-pixel bit map for a
                                    specified
                                    character


2.7  Input and Output

The input and output (I/O) routines of the standard C library allow you to
read and write data to and from files and devices. In C, there are no
predefined file structures; all data items are treated as sequences of
bytes. The following three types of I/O functions are available:


    1.  Stream

    2.  Low-level

    3.  Console and port


The "stream" I/O functions treat data as a stream of individual characters.
By choosing among the many stream functions available, you can process data
in different sizes and formats, from single characters to large data
structures. Stream I/O also provides buffering, which can significantly
improve performance.

The "low-level" I/O routines do not perform buffering and formatting.
Instead, they invoke the operating system's input and output capabilities
directly. These routines let you access files and peripheral devices at a
more basic level than the stream functions.

The "console and port" I/O routines allow you to read or write directly to a
console (keyboard and screen) or an I/O port (such as a printer port). The
port I/O routines simply read and write data in bytes. With console I/O
routines, some additional options are available, such as detecting whether a
character has been typed at the console. You can also choose between echoing
characters to the screen as they are read or reading characters without
echoing.

The C library also provides a number of direct DOS I/O system call routines.
These are described in Section 2.14, "System Calls."

File I/O operations can be performed in two modes: text or binary. The
following section describes these modes and their use.

────────────────────────────────────────────────────────────────────────────
WARNING

Because stream routines are buffered and low-level routines are not, the two
types of routines are generally incompatible. You should use either stream
or low-level routines consistently for processing a given file.
────────────────────────────────────────────────────────────────────────────


2.7.1  Text and Binary Modes

Many C programs use data files for input and output. Under DOS and OS/2,
data files are normally processed in text mode. In this mode, each
carriage-return-line-feed (CR-LF) combination is translated into a single
line-feed character during input. During output, each line-feed character is
translated into a CR-LF combination.

Sometimes you may want to process a file without making those translations.
In these cases you use binary mode, which suppresses CR-LF translations.

You can control the file translation mode in the following ways:


    ■   To process a few selected files in binary mode, while retaining the
        default text mode for most files, you can specify binary mode when you
        open the selected files. The fopen routine opens a file in binary mode
        when you specify the letter b in the access-mode string for the file.
        The open routine opens a file in binary mode when you specify the
        O_BINARY flag in the oflag argument. For more information about fopen
        and open, see the reference description of each routine.

    ■   To process most or all files in binary mode, you can change the
        default mode to binary. The global variable _fmode controls the
        default translation mode, which is normally text. If you set _fmode to
        O_BINARY, the default mode is binary except for stdaux and stdprn,
        which are opened in binary mode by default.


You can change the value of _fmode in two ways:


    1.  Link with the file BINMODE.OBJ (supplied with Microsoft C). This
        changes the initial setting of _fmode to the O_BINARY flag, causing
        all files except stdin, stdout, and stderr to be opened in binary
        mode.

    2.  Change the value of _fmode directly by setting it to the O_BINARY flag
        in your program. This has the same effect as linking with BINMODE.OBJ.


You can still override the default mode (now binary) for a particular file
by opening it in text mode. Specify the letter t when using fopen, or
specify the O_TEXT flag when using open.

By default, the stdin, stdout, and stderr files are opened in text mode, and
the stdaux and stdprn files are opened in binary mode. The setmode routine
allows you to change these defaults or change the mode of a file after it
has been opened. See the reference description of setmode for details.


2.7.2  Stream Routines

Stream I/O functions handle data as a continuous stream of characters. To
use the stream functions, you must include the file STDIO.H in your program.
This file defines constants, types, and structures used in the stream
functions, and contains function declarations and macro definitions for the
stream  routines.

When a file is opened for I/O using the stream functions, the opened file is
associated with a structure of type FILE (defined in STDIO.H) containing
basic information about the file. A pointer to the FILE structure is
returned when the stream is opened. Subsequent operations use this pointer
(also called the "stream pointer," or just "stream") to refer to the file.

The stream functions provide for buffered, formatted, or unformatted input
and output. When a stream is buffered, data that is read from or written to
the stream is collected in an intermediate storage location called a
"buffer". In write operations, the output buffer's contents are written to
the appropriate final location when the buffer is full, the stream is
closed, or the program terminates normally. The buffer is said to be
"flushed" when this occurs. In read operations, a block of data is placed in
the input buffer read from the buffer; when the input buffer is empty, the
next block of data is transferred into the buffer.

Buffering produces efficient I/O because the system can transfer a large
block of data in a single operation rather than performing an I/O operation
each time a data item is read from or written to a stream. However, if a
program terminates abnormally, output buffers may not be flushed, resulting
in loss of data.

Some of the constants defined in STDIO.H may be useful in your program. The
manifest constant EOF is defined to be the value returned at end-of-file.
NULL is the null pointer. FILE is the structure that maintains information
about a stream. BUFSIZ defines the default size of stream buffers, in bytes.


Routine                           Use
────────────────────────────────────────────────────────────────────────────
clearerr                          Clears the error indicator for a stream

fclose                            Closes a stream

fcloseall                         Closes all open streams

fdopen                            Associates a stream with an open file
                                    handle

feof                              Tests for end-of-file on a stream

ferror                            Tests for error on a stream

fflush                            Flushes a stream

fgetc                             Reads a character from a stream
                                    (function version)

fgetchar                          Reads a character from stdin (function
                                    version)

fgetpos                           Gets the position indicator of a stream

fgets                             Reads a string from a stream

fileno                            Gets the file handle associated with a
                                    stream

flushall                          Flushes all streams

fopen                             Opens a stream

fprintf                           Writes formatted data to a stream

fputc                             Writes a character to a stream (function
                                    version)

fputchar                          Writes a character to stdout (function
                                    version)

fputs                             Writes a string to a stream

fread                             Reads unformatted data from a stream

freopen                           Reassigns a FILE pointer to a new file

fscanf                            Reads formatted data from a stream

fseek                             Moves file position to a given location

fsetpos                           Sets the position indicator of a stream

_fsopen                           Opens a stream with file sharing

ftell                             Gets current file position

fwrite                            Writes unformatted data items to a
                                    stream

getc                              Reads a character from a stream

getchar                           Reads a character from stdin

gets                              Reads a line from stdin

getw                              Reads a binary int item from a stream

printf                            Writes formatted data to stdout

putc                              Writes a character to a stream

putchar                           Writes a character to stdout

puts                              Writes a line to a stream

putw                              Writes a binary int item to a stream

rewind                            Moves file position to beginning of a
                                    stream

rmtmp                             Removes temporary files created by
                                    tmpfile

scanf                             Reads formatted data from stdin

setbuf                            Controls stream buffering

setvbuf                           Controls stream buffering and buffer
                                    size

sprintf                           Writes formatted data to a string

sscanf                            Reads formatted data from a string

tempnam                           Generates a temporary file name in given
                                    directory

tmpfile                           Creates a temporary file

tmpnam                            Generates a temporary file name

ungetc                            Places a character in the buffer

vfprintf                          Writes formatted data to a stream

vprintf                           Writes formatted data to stdout

vsprintf                          Writes formatted data to a string


2.7.2.1  Opening a Stream

A stream must be opened using the fdopen, fopen, freopen, or _fsopen
function before input and output can be performed on that stream. When
opening a stream, the named stream can be opened for reading, writing, or
both, and can be opened in either text or binary mode.

The fdopen, fopen, freopen, and _fsopen functions return a FILE pointer. You
normally assign the pointer value to a variable and use the variable to
refer to the opened stream. For instance, if your program contains the lines


    FILE *infile
    infile = fopen ("test.dat", "r");

you can use the FILE pointer variable  infile  to refer to the stream.


2.7.2.2  Using Predefined Stream Pointers

When a program begins execution, the C start-up code automatically opens
several streams: standard input, standard output, and standard error. By
default, the standard input, standard output, and standard error streams are
directed to the console (keyboard and screen). This means that when a
program expects input from the "standard input," it receives that input from
the console. Similarly, a program that writes to the "standard output"
prints its data to the console. Error messages generated by the library
routines are sent to the "standard error," meaning that error messages
appear on the user's console.

Under DOS, two additional streams are opened: standard auxiliary and
standard print. (These streams are not available in OS/2.) The assignment of
standard auxiliary and standard print depends on the machine configuration.
These streams usually refer to the first serial port and a printer port, but
those ports may not be available on some systems. Be sure to check your
machine configuration before using these streams.

You can refer to the standard streams with the following predefined stream
pointers:

Pointer                           Stream
────────────────────────────────────────────────────────────────────────────
stdin                             Standard input

stdout                            Standard output

stderr                            Standard error

stdaux                            Standard auxiliary (DOS only)

stdprn                            Standard print (DOS only)

You can use these pointers in any function that requires a stream pointer as
an argument. Some functions, such as getchar and putchar, are designed to
use stdin or stdout automatically. The pointers stdin, stdout, stderr,
stdaux, and stdprn are constants, not variables; do not try to assign them a
new stream pointer value.

DOS and OS/2 allow you to redirect a program's standard input and standard
output at the operating-system command level. OS/2 also allows you to
redirect a program's standard error. See your operating system user's manual
for a complete discussion of redirection.

Within your program, you can use freopen to redirect stdin, stdout, stderr,
stdaux, or stdprn so that it refers to a disk file or to a device. See the
reference description of freopen for more details.


2.7.2.3  Controlling Stream Buffering

As mentioned earlier, stream routines can use in-memory buffers to speed I/O
operations. Files opened using the stream routines are buffered by default,
except for stdaux and stdprn, which are normally unbuffered. The stdout and
stderr streams are flushed whenever they are full or (if you are writing to
a character device) after each library call.

By using the setbuf or setvbuf function, you can cause a stream to be
unbuffered, or you can associate a buffer with an unbuffered stream. Buffers
allocated by the system are not accessible to you, but buffers allocated
with setbuf or  setvbuf refer to arrays in your program and can be
manipulated. Buffers can be any size up to 32,767 bytes. This size is set by
the manifest constant BUFSIZ in STDIO.H if you use seftbuf; if you use
setvbuf, you can set the size of the buffer yourself. (See the descriptions
of setbuf and setvbuf in the reference section for more details.)

────────────────────────────────────────────────────────────────────────────
NOTE

These routines affect only buffers created by C library routines. They have
no effect on buffers created by the operating system.
────────────────────────────────────────────────────────────────────────────


2.7.2.4  Closing Streams

The fclose and fcloseall functions close a stream or streams. The fclose
routine closes a single specified stream; fcloseall closes all open streams
except stdin, stdout, stderr, stdaux, and stdprn. If your program does not
explicitly close a stream, the stream is automatically closed when the
program terminates. How-ever, it is a good practice to close a stream when
your program is finished with it, as the number of streams that can be open
at a given time is limited.


2.7.2.5  Reading and Writing Data

The stream functions allow you to transfer data in a variety of ways. You
can read and write binary data (a sequence of bytes), or specify reading and
writing by characters, lines, or more complicated formats.

Reading and writing operations on streams always begin at the current
position of the stream, known as the "file pointer" for the stream. The file
pointer is changed to reflect the new position after a read or write
operation takes place. For example, if you read a single character from a
stream, the file pointer is increased by one byte so that the next operation
begins with the first unread character. If a stream is opened for appending,
the file pointer is automatically positioned at the end of the file before
each write operation.

The fseek and fsetpos functions allow you to position the file pointer
anywhere in a file. The next operation occurs at the position you specified.
The rewind routine positions the file pointer at the beginning of the file.
Use the ftell or fgetpos routine to determine the current position of the
file pointer.

The feof macro detects an end-of-file condition on a stream. Once the
end-of-file indicator is set, it remains set until the file is closed, or
until clearerr, fseek, fsetpos, or rewind is called.

Streams associated with a character-oriented device (such as a console) do
not have file pointers. Data coming from or going to a console cannot be
accessed randomly. Routines that set or get the file-pointer position (such
as fseek, fgetpos, fsetpos, ftell, or rewind) have undefined results if used
on a stream associated with a character-oriented device.


2.7.2.6  Detecting Errors

When an error occurs in a stream operation, an error indicator for the
stream is set. You can use the ferror macro to test the error indicator and
determine whether an error has occurred. Once an error has occurred, the
error indicator for the stream remains set until the stream is closed, or
until you explicitly clear the error indicator by calling clearerr or
rewind.


2.7.3  Low-Level Routines

Low-level input and output calls do not buffer or format data. Declarations
for the low-level functions are given in the include files IO.H, FCNTL.H,
SYS\TYPES.H, and SYS\STAT.H. Unlike the stream functions, low-level
functions do not require the include file STDIO.H. However, some common
constants are defined in STDIO.H; for example, the end-of-file indicator
(EOF) may be useful. If your program requires these constants, you must
include STDIO.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
close                             Closes a file

creat                             Creates a file

dup                               Creates a second handle for a file

dup2                              Reassigns a handle to a file

eof                               Tests for end-of-file

lseek                             Repositions file pointer to a given
                                    location

open                              Opens a file

read                              Reads data from a file

sopen                             Opens a file for file sharing

tell                              Gets current file-pointer position

umask                             Sets default file-permission mask

write                             Writes data to a file


2.7.3.1  Opening a File

You must open a file before performing I/O functions on it. The open
function opens a file; it can also create the file when opening it. In OS/2
and DOS versions 3.0 and later, you can use sopen to open a file with
file-sharing attributes. The creat function can create and open a file.

The file can be opened for reading, writing, or both, and opened in either
text or binary mode (see Section 2.7.1, "Text and Binary Modes"). The
include file FCNTL.H must be included when opening a file, as it contains
definitions for flags used in open. In some cases, the files SYS\TYPES.H and
SYS\STAT.H must also be included; for more information, see the reference
description for the open function.

These functions return a file handle, which is normally assigned to an
integer variable. You use the variable to refer to the opened file.


2.7.3.2  Reading and Writing Data

Use the read and write routines to read and write to files. These operations
begin at the current position in the file. The current position is updated
each time a read or write operation occurs.

The lseek function allows you to place the file pointer anywhere in the
file. The next operation occurs at the position you specified. The tell
function indicates the current position of the file pointer. The eof routine
tests for the end of the file.

Low-level I/O routines set the errno variable when an error occurs. Chapter
3, "Global Variables and Standard Types," describes errno.

Character-oriented devices, such as the console, do not have file pointers.
The lseek and tell routines have undefined results if used on a handle
associated with a device.


2.7.3.3  Closing Files

The close function closes an open file. Open files are automatically closed
when a program terminates. However, it is a good practice to close a file
when your program is finished with it, as there is a limit to the number of
files that can be open at one time.


2.7.3.4  Using Predefined Handles

When a program begins execution, three files are automatically opened:
standard input, standard output, and standard error. In DOS, two additional
files are opened: standard auxiliary and standard print. (These files are
not available in OS/2.)

Low-level routines can access these files using the following predefined
handles:

Stream                            Handle
────────────────────────────────────────────────────────────────────────────
stdin                             0

stdout                            1

stderr                            2

stdaux (DOS only)                 3

stdprn (DOS only)                 4

You can use these file handles without previously opening the files. The
files are opened and the handles are assigned when the program starts.

The dup and dup2 functions allow you to assign multiple handles for the same
file. These functions are typically used to associate the predefined file
handles with different files.

In DOS and OS/2, you can redirect the standard input and standard output at
the operating-system command level. OS/2 also allows you to redirect the
standard error. See your operating system user's manual for a complete
discussion of redirection.


2.7.4  Console and Port I/O

The console and port I/O routines are implemented as functions and are
declared in the include file CONIO.H. These functions perform reading and
writing operations on your console or on the specified port. The cgets,
cscanf, getch, getche, and kbhit routines take input from the console, while
cprintf, cputs, putch, and ungetch write to the console. The input or output
of these functions can be redirected.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
cgets                             Reads a string from the console

cprintf                           Writes formatted data to the console

cputs                             Writes a string to the console

cscanf                            Reads formatted data from the console

getch                             Reads a character from the console

getche                            Reads a character from the console and
                                    echoes it

inp                               Reads one byte from the specified I/O
                                    port

inpw                              Reads a two-byte word from the specified
                                    I/O port

kbhit                             Checks for a keystroke at the console

outp                              Writes one byte to the specified I/O
                                    port

outpw                             Writes a two-byte word to the specified
                                    I/O port

putch                             Writes a character to the console

ungetch                           "Ungets" the last character read from
                                    the console so that it becomes the next
                                    character read

────────────────────────────────────────────────────────────────────────────
NOTE

Programs that need only run under DOS can also use a number of direct DOS
I/O system calls ( _dos_open, _dos_read, _dos_close, etc.) These are
described in detail in Section 2.14, "System Calls."
────────────────────────────────────────────────────────────────────────────

The console or port does not have to be opened or closed before I/O is
performed, so there are no open or close routines in this category. The port
I/O routines inp and outp read or write one byte at a time from the
specified port. The inpw and outpw routines read and write two-byte words,
respectively.

The console I/O routines allow reading and writing of strings (cgets and
cputs), formatted data (cscanf and cprintf), and characters. Several options
are available when reading and writing characters.

The putch routine writes a single character to the console. The getch and
getche routines read a single character from the console; getche echoes the
character back to the console, while getch does not. The ungetch routine
"ungets" the last character read; the next read operation on the console
begins with the "ungotten" character.

The kbhit routine determines whether a key has been struck at the console.
This routine allows you to test for keyboard input before you attempt to
read from the console.

────────────────────────────────────────────────────────────────────────────
NOTE

The console I/O routines are not compatible with stream or low-level library
routines and should not be used with them.
────────────────────────────────────────────────────────────────────────────


2.8  Internationalization

Internationalization routines are useful for creating different versions of
a program for international markets. These routines are declared in the
header file LOCALE.H, except for strftime, which is declared in TIME.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
localeconv                        Sets a structure with appropriate values
                                    for formatting numeric quantities

setlocale                         Selects the appropriate locale for the
                                    program

strcoll                           Compares strings using locale-specific
                                    information

strftime                          Formats a date and time string

strxfrm                           Transforms a string based on
                                    locale-specific
                                    information


2.9  Math

The math routines allow you to perform common mathematical calculations. All
math routines work with floating-point values and therefore require
floating-point support (see Section 1.8, "Floating-Point Support").


The math library provides two versions of some routines. The first version
of the routine supports double arguments and return values. The second
version supports an 80-bit data type, allowing the routine to take long
double arguments and return a long double value. The second version usually
has the same name with the suffix l. For instance, the acos routine supports
double arguments and return values, while acosl supports long double
arguments and return values.

Routines which support long double values are not available when you compile
with the /Fpa (alternate math) compiler option. The same is true of the
_clear 87, _control87, and _status87 routines.


Most math declarations are in the include file MATH.H. However, the
_clear87, _control87, _fpreset, and _status87 routines are defined in
FLOAT.H, the abs and labs functions are defined in MATH.H and STDLIB.H, and
the div and ldiv routines are declared in STDLIB.H.


Routine                           Use
────────────────────────────────────────────────────────────────────────────
acos, acosl                       Calculate the arccosine

asin, asinl                       Calculate the arcsine

atan, atanl                       Calculate the arctangent

atan2, atan2l                     Calculate the arctangent

bessel                            Calculates Bessel functions

cabs, cabsl                       Find the absolute value of a complex
                                    number

ceil, ceill                       Find the integer ceiling

_clear87                          Gets and clears the floating-point
                                    status word

_control87                        Gets the old floating-point control word
                                    and sets a new control-word value

cos, cosl                         Calculate the cosine

cosh, coshl                       Calculate the hyperbolic cosine

dieeetomsbin                      Converts IEEE double-precision number to
                                    Microsoft (MS) binary format

div                               Divides one integer by another,
                                    returning the quotient and remainder

dmsbintoieee                      Converts Microsoft binary
                                    double-precision number to IEEE format

exp, expl                         Calculate the exponential function

fabs, fabsl                       Find the absolute value

fieeetomsbin                      Converts IEEE single-precision number to
                                    Microsoft binary format

floor, floorl                     Find the largest integer less than or
                                    equal to the
                                    argument

fmod, fmodl                       Find the floating-point remainder

fmsbintoieee                      Converts Microsoft binary
                                    single-precision number to IEEE format

_fpreset                          Reinitializes the floating-point-math
                                    package

frexp, frexpl                     Calculate an exponential value

hypot, hypotl                     Calculate the hypotenuse of right
                                    triangle

ldexp, ldexpl                     Calculate the product of the argument
                                    and 2exp

ldiv                              Divides one long integer by another,
                                    returning the quotient and remainder

log, logl                         Calculate the natural logarithm

log10, log10l                     Calculate the base-10 logarithm

_lrotl,  _lrotr                   Shift an unsigned long int item left (
                                    _lrotl) or right ( _lrotr)

matherr,  _matherrl               Handle math errors

max, min                          Return the larger or smaller of two
                                    values

modf, modfl                       Break down the argument into integer and
                                    fractional parts

pow, powl                         Calculate a value raised to a power

rand                              Gets a pseudorandom number

_rotl,  _rotr                     Shift an unsigned int item left ( _rotl)
                                    or right
                                    ( _rotr)

sin, sinl                         Calculate the sine

sinh, sinhl                       Calculate the hyperbolic sine

sqrt, sqrtl                       Find the square root

srand                             Initializes a pseudorandom series

_status87                         Gets the floating-point status word

tan, tanl                         Calculate the tangent

tanh, tanhl                       Calculate the hyperbolic tangent

The bessel routine does not correspond to a single function, but to twelve
functions named j0, j1, jn, y0, y1, yn,  _j0l,  _j1l,  _jnl,  _y0l,  _y1l,
and  _ynl.

The matherr and _matherrl routines are invoked by the math functions when
errors occur. The matherr routine handles functions that return a double
value and _matherrl handles routines that return a long double.

These routines are defined in the library, but you can redefine them for
different error-handling. The user-defined function, if given, must follow
the rules given in the reference description of matherr and _matherrl.

You are not required to supply a definition for the matherr routines. If no
definition is present, the default error returns for each routine are used.
The reference description of each routine describes that routine's error
returns.


2.10  Memory Allocation

The memory-allocation routines allow you to allocate, free, and reallocate
blocks of memory. Memory-allocation routines are declared in the include
file MALLOC.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
alloca                            Allocates a block of memory from the
                                    program's stack

_bfreeseg                         Frees a based heap

_bheapseg                         Allocates a based heap

calloc,  _bcalloc,  _fcalloc,     Allocate storage for an array
_ncalloc

_expand,  _bexpand,  _fexpand,    Expand or shrink a block of memory
_nexpand                          without moving its location

free,  _bfree,  _ffree,  _nfree   Free an allocated block

_freect                           Returns approximate number of items of
                                    given size that could be allocated in
                                    the near heap

halloc                            Allocates storage for huge array

_heapadd,  _bheapadd              Add memory to a heap

_heapchk,  _bheapchk,  _fheapchk  Check a heap for consistency
, _nheapchk

_heapmin,  _bheapmin,             Release unused memory in a heap
_fheapmin,  _nheapmin

_heapset,  _bheapset,  _fheapset  Fill free heap entries with a specified
, _nheapset                       value

_heapwalk,  _bheapwalk,           Return information about each entry in a
_fheapwalk, _nheapwalk            heap

hfree                             Frees a block allocated by halloc

malloc,  _bmalloc,  _fmalloc,     Allocate a block of memory
_nmalloc

_memavl                           Returns approximate number of bytes
                                    available for allocation in the near
                                    heap

_memmax                           Returns size of largest contiguous free
                                    block in the near heap

_msize,  _bmsize,  _fmsize,       Return size of an allocated block
_nmsize

realloc,  _brealloc,  _frealloc,  Reallocate a block to a new size
_nrealloc

stackavail                        Returns size of stack space available
                                    for allocation with alloca

Some memory-management routines, such as malloc, are available in different
versions that begin with _b, _f, or _n. These variations are described in
the following section.

The malloc and free routines allocate and free memory space, respectively,
while a program runs. The malloc routine allocates memory from the "heap,"
which is a pool of memory not otherwise used by your program. In tiny-,
small-, and medium-model programs, the heap consists of unused memory in
your program's default data segment. In compact-, large-, and huge-model
programs, it is unused memory outside the default data segment.

The malloc and free routines satisfy the memory-allocation requirements of
most programs. More specialized memory-management routines are discussed
below.

The realloc and _expand routines can expand or shrink an allocated memory
block. They behave differently in cases in which there is not enough room to
expand the block in its current location. In this case, realloc moves the
block as needed, but _expand does not.

The calloc routine allocates memory for an array and initializes every byte
in the allocated block to 0.

The halloc routine is similar to calloc, except that it can allocate memory
for a huge array (one that exceeds 64K in size). This routine is useful when
you need a very large data object, or if you need to return allocated memory
to the operating system for subsequent calls to the spawn family of
functions.


2.10.1  Near and Far Heaps

As mentioned in the previous section, heap memory can reside inside or
outside your program's default data segment, depending on what memory model
your program uses. When it lies inside the default data segment, the heap is
called the "near heap," since it can be accessed with near pointers. The
"far heap" is memory that spans one or more segments outside the default
data segment. The far heap can be accessed only with far pointers.

In various memory models, malloc automatically allocates memory from the
near heap or far heap, as appropriate. The C library also includes near and
far versions of malloc, free, and other memory-management routines, which
allow you to specify the near and far heaps explicitly. These have the same
names as standard memory routines, but are preceded by _n (for near) or _f
(for far).

For instance, the _nmalloc routine always allocates memory from the near
heap and returns a near pointer, no matter which memory model your program
uses. Use _nfree to release memory allocated with _nmalloc.

Similarly, _fmalloc always allocates memory from the far heap and returns a
far pointer, regardless of memory model. Use the _ffree routine to release
memory allocated with _fmalloc.


2.10.2  Based Heaps

You can also allocate memory from a "based heap," which is a single segment
that lies outside the default data segment. Based-heap routines generally
use the same names as standard memory routines, but begin with _b. For
instance, _bmalloc allocates a memory block from the based heap and _bfree
frees the block.

Based heaps offer the following advantages:


    ■   Localized data. Based heaps allow you to group related data in a
        single segment. This can simplify the management of related data. In
        OS/2, based heaps can also minimize the risk of general protection
        faults and improve performance.

    ■   Faster pointer arithmetic. Although the based heap lies in the far
        data segment, pointers to its data items are the same size as near
        pointers. Thus, pointer arithmetic on items in a based heap is faster
        than pointer arithmetic on items in the far heap.


The _bheapseg routine allocates a based heap segment, from which you can
then allocate blocks of memory. You can call _bheapseg more than once to
allocate as many based-heap segments as needed (within the confines of
available memory).

The _bfreeseg routine frees a based-heap segment. This routine frees every
block in the based-heap segment, whether or not you previously freed the
blocks individually.

────────────────────────────────────────────────────────────────────────────
NOTE
Near- , far- , and based-heap calls are not ANSI compatible and will make
your program less portable.
────────────────────────────────────────────────────────────────────────────


2.11  Process and Environment Control

The process-control routines allow you to start, stop, and manage processes
from within a program. Environment-control routines allow you to get and
change information about the operating-system environment.

A "process" is a program being executed by the operating system. It consists
of the program's code and data, plus information about the process, such as
the number of open files. Whenever you execute a program at the
operating-system level, you start a process.

All process-control functions except signal are declared in the include file
PROCESS.H. The signal function is declared in SIGNAL.H. The abort, exit, and
system functions are also declared in the STDLIB.H include file. The
environment-control routines (getenv and putenv) are declared in STDLIB.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
abort                             Aborts a process without flushing
                                    buffers or calling functions registered
                                    by atexit and onexit

assert                            Tests for logic error

atexit                            Schedules routines for execution at
                                    program
                                    termination

_beginthread                      Creates an execution thread (OS/2 only)

_cexit                            Performs the exit termination procedures
                                    (such as flushing buffers) and returns
                                    control to the calling program

_c_exit                           Performs the _exit termination
                                    procedures and returns control to the
                                    calling program

cwait                             Suspends the calling process until a
                                    specified child process terminates (OS/2
                                    only)

_endthread                        Terminates an execution thread (OS/2
                                    only)

execl                             Executes child process with argument
                                    list

execle                            Executes child process with argument
                                    list and given environment

execlp                            Executes child process using PATH
                                    variable and argument list

execlpe                           Executes child process using PATH
                                    variable, given environment, and
                                    argument list

execv                             Executes child process with argument
                                    array

execve                            Executes child process with argument
                                    array and given environment

execvp                            Executes child process using PATH
                                    variable and argument array

execvpe                           Executes child process using PATH
                                    variable, given environment, and
                                    argument array

exit                              Calls functions registered by atexit and
                                    onexit, then flushes all buffers and
                                    closes all open files before terminating
                                    the process

_exit                             Terminates process without processing
                                    atexit or onexit functions or flushing
                                    buffers

getenv                            Gets the value of an environment
                                    variable

getpid                            Gets process ID number

longjmp                           Restores a saved stack environment

onexit                            Schedules routines for execution at
                                    program
                                    termination

_pclose                           Waits for a child command and closes a
                                    pipe on the associated stream

perror                            Prints error message

_pipe                             Creates a pipe

_popen                            Creates a pipe and asynchronously
                                    executes a child copy of the command
                                    processor

putenv                            Adds or changes the value of an
                                    environment
                                    variable

raise                             Sends a signal to the calling process

setjmp                            Saves a stack environment

signal                            Handles an interrupt signal

spawnl                            Executes child process with argument
                                    list

spawnle                           Executes child process with argument
                                    list and given environment

spawnlp                           Executes child process using PATH
                                    variable and argument list

spawnlpe                          Executes child process using PATH
                                    variable, given environment, and
                                    argument list

spawnv                            Executes child process with argument
                                    array

spawnve                           Executes child process with argument
                                    array and given environment

spawnvp                           Executes child process using PATH
                                    variable and argument array

spawnvpe                          Executes child process using PATH
                                    variable, given environment, and
                                    argument array

system                            Executes an operating system command

wait                              Suspends the calling process until any
                                    of the caller's immediate child
                                    processes terminate (OS/2 only)

The atexit and onexit routines create a list of functions to be executed
when the calling program terminates. The only difference between the two is
that atexit is part of the ANSI standard. The onexit function is offered for
compatibility with previous versions of Microsoft C.

The _exit routine terminates a process immediately, whereas exit terminates
the process only after flushing buffers and calling any functions previously
registered by atexit and onexit. The _cexit and _c_exit routines are
identical to exit and _exit, respectively, except that they return control
to the calling program without terminating the process.

The setjmp and longjmp routines save and restore a stack environment. These
allow you to execute a nonlocal goto.

The exec and spawn routines start a new process called the "child" process.
The difference between the exec and spawn routines is that the spawn
routines are capable of returning control from the child process to its
caller (the "parent" process). Both the parent process and the child process
are present in memory (unless P_OVERLAY is specified). In the exec routines,
the child process overlays the parent process, so returning control to the
parent process is impossible (unless an error occurs when attempting to
start execution of the child process).

There are eight forms each of the spawn and exec routines (see Table 2.1).
The differences among the forms involve the method of locating the file to
be executed as the child process, the method for passing arguments to the
child process, and the method of setting the environment.

Passing an argument list means that the arguments to the child process are
listed separately in the exec or spawn call. Passing an argument array means
that the arguments are stored in an array, and a pointer to the array is
passed to the child process. The argument-list method is typically used when
the number of arguments is constant or is known at compile time. The
argument-array method is useful when the number of arguments must be
determined at run time.

Several process-control routines take advantage of the multitasking
capability of OS/2. The _beginthread and _endthread routines create and
terminate execution threads. The cwait and wait routines suspend the calling
process until one child process terminates. The _pipe, _popen, and _pclose
routines create and manipulate pipes, which link processes for sequential
execution.

Table 2.1  Forms of the spawn and exec Routines

╓┌───────────────────┌──────────────────┌────────────────────┌───────────────►
                                        Argument-Passing
Routines            Locating the File  Convention           Environment
                                                            Settings
─────────────────────────────────────────────────────────────────────────────
execl, spawnl       Do not use PATH    Argument list        Inherited from
                                                            parent

execle, spawnle     Do not use PATH    Argument list        Pointer to
                                                            environment table
                                                            for child process
                                                            passed as last
                                                            argument

execlp, spawnlp     Use PATH           Argument list        Inherited from
                                                            parent
                                        Argument-Passing
Routines            Locating the File  Convention           Environment
                                                            Settings
                                                            parent

execlpe, spawnlpe   Use PATH           Argument list        Pointer to
                                                            environment table
                                                            for child process
                                                            passed as last
                                                            argument

execv, spawnv       Do not use PATH    Argument array       Inherited from
                                                            parent

execve, spawnve     Do not use PATH    Argument array       Pointer to
                                                            environment table
                                                            for child process
                                                            passed as last
                                                            argument

execvp, spawnvp     Use PATH           Argument array       Inherited from
                                        Argument-Passing
Routines            Locating the File  Convention           Environment
                                                            Settings
execvp, spawnvp     Use PATH           Argument array       Inherited from
                                                            parent

execvpe, spawnvpe   Use PATH           Argument array       Pointer to
                                                            environment table
                                                            for child process
                                                            passed as last
                                                            argument

─────────────────────────────────────────────────────────────────────────────



The assert macro is typically used to test for logic errors. It prints a
message when a given "assertion" fails to hold true. Defining the identifier
NDEBUG to any value causes occurrences of assert to be removed from the
source file, thus allowing you to turn off assertion checking without
modifying the source file.


2.12  Searching and Sorting

Search and sort routines provide binary-search, linear-search, and
quick-sort capabilities. They are all declared in SEARCH.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
bsearch                           Performs binary search

lfind                             Performs linear search for given value

lsearch                           Performs linear search for given value,
                                    which is added to array if not found

qsort                             Performs quick sort


2.13  String Manipulation

The string functions are declared in the include file STRING.H. They allow
you to compare strings, copy them, search for strings and characters, and
perform various other operations.


Routines beginning with _f are model-independent versions of the
corresponding routines and are useful in mixed-model programs. These
routines can be called from any point in the program, regardless of which
model is being used.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
strcat,   _fstrcat                Append one string to another

strchr,  _fstrchr                 Find first occurrence of a given
                                    character in a string

strcmp,  _fstrcmp                 Compare two strings

strcpy,  _fstrcpy                 Copy one string to another

strcspn,  _fstrcspn               Find first occurrence of a character
                                    from a given character set in a string

strdup,  _fstrdup, _nstrdup       Duplicate a string

strerror                          Maps an error number to a message string

_strerror                         Maps a user-defined error message to a
                                    string

stricmp,  _fstricmp               Compare two strings without regard to
                                    case

strlen,  _fstrlen                 Find length of string

strlwr,  _fstrlwr                 Convert string to lowercase

strncat,  _fstrncat               Append characters of a string

strncmp,  _fstrncmp               Compare characters of two strings

strncpy,  _fstrncpy               Copy characters of one string to another

strnicmp,  _fstrnicmp             Compare characters of two strings
                                    without regard
                                    to case

strnset,  _fstrnset               Set characters of a string to a given
                                    character

strpbrk,  _fstrpbrk               Find first occurrence of a character
                                    from one string in another

strrchr,  _fstrrchr               Find last occurrence of a given
                                    character in string

strrev,  _fstrrev                 Reverse string

strset,  _fstrset                 Set all characters of a string to a
                                    given character

strspn,  _fstrspn                 Find first substring from a given
                                    character set in a string

strstr,  _fstrstr                 Find first occurrence of a given string
                                    in another string

strtok,  _fstrtok                 Find next token in a string

strupr,  _fstrupr                 Convert a string to uppercase

All string functions work on null-terminated character strings. When working
with character arrays that do not end with a null character, you can use the
buffer-manipulation routines, described in Section 2.1.


2.14  System Calls

The following routines give access to IBM-PC BIOS interrupts and DOS system
calls. Except for the FP_OFF, FP_SEG, and segread routines, these routines
are for DOS application programs only; they do not work under OS/2.


2.14.1  BIOS Interface

The functions in this category provide direct access to the BIOS interrupt
services. They are all declared in BIOS.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
_bios_disk                        Issues service requests for both hard
                                    and floppy disks, using INT 0x13

_bios_equiplist                   Performs an equipment check, using INT
                                    0x11

_bios_keybrd                      Provides access to keyboard services,
                                    using
                                    INT 0x16

_bios_memsize                     Obtains information about available
                                    memory, using INT 0x12

_bios_printer                     Performs printer output services, using
                                    INT 0x17

_bios_serialcom                   Performs serial communications tasks,
                                    using
                                    INT 0x14

_bios_timeofday                   Provides access to system clock, using
                                    INT 0x1A

────────────────────────────────────────────────────────────────────────────
NOTE
BIOS routines are hardware dependent. Some of them may not work as expected
on machines whose hardware differs from the IBM PC.
────────────────────────────────────────────────────────────────────────────


2.14.2  DOS Interface

These routines are implemented as functions and declared in DOS.H.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
bdos                              Invokes DOS system call; uses only DX
                                    and AL registers

_chain_intr                       Chains one interrupt handler to another

_disable                          Disables interrupts

_dos_allocmem                     Allocates a block of memory, using DOS
                                    system call 0x48

_dos_close                        Closes a file, using DOS system call
                                    0x3E

_dos_creat                        Creates a new file and erases any
                                    existing file having the same name,
                                    using DOS system call 0x3C

_dos_creatnew                     Creates a new file and returns an error
                                    if a file having the same name exists,
                                    using DOS system
                                    call 0x5B

_dos_findfirst                    Finds first occurrence of a given file,
                                    using DOS system call 0x4E

_dos_findnext                     Finds subsequent occurrences of a given
                                    file, using DOS system call 0x4F

_dos_freemem                      Frees a block of memory, using DOS
                                    system
                                    call 0x49

_dos_getdate                      Gets the system date, using DOS system
                                    call 0x2A

_dos_getdiskfree                  Gets information on a disk volume, using
                                    DOS system call 0x36

_dos_getdrive                     Gets the current default drive, using
                                    DOS system call 0x19

_dos_getfileattr                  Gets current attributes of a file or
                                    directory, using DOS system call 0x43

_dos_getftime                     Gets the date and time a file was last
                                    written, using DOS system call 0x57

_dos_gettime                      Gets the current system time, using DOS
                                    system
                                    call 0x2C

_dos_getvect                      Gets the current value of a specified
                                    interrupt vector, using DOS system call
                                    0x35

_dos_keep                         Installs terminate-and-stay-resident
                                    (TSR) programs using DOS system call
                                    0x31

_dos_open                         Opens an existing file, using DOS system
                                    call 0x3D

_dos_read                         Reads a file, using DOS system call 0x3F


_dos_setblock                     Changes the size of a previously
                                    allocated block, using DOS system call
                                    0x4A

_dos_setdate                      Sets the current system date, using DOS
                                    system
                                    call 0x2B

_dos_setdrive                     Sets the default disk drive, using DOS
                                    system
                                    call 0x0E

_dos_setfileattr                  Sets the current attributes of a file,
                                    using DOS system call 0x43

_dos_setftime                     Sets the date and time that the
                                    specified file was last written, using
                                    DOS system call 0x57

_dos_settime                      Sets the system time, using DOS system
                                    call 0x2D

_dos_setvect                      Sets a new value for the specified
                                    interrupt vector, using DOS system call
                                    0x25

_dos_write                        Sends output to a file, using DOS system
                                    call 0x40

dosexterr                         Obtains in-depth error information from
                                    DOS system call 0x59

_enable                           Enables interrupts

FP_OFF                            Returns offset portion of a far pointer
                                    (OS/2
                                    and DOS)

FP_SEG                            Returns segment portion of a far pointer
                                    (OS/2
                                    and DOS)

_harderr                          Establishes a hardware error handler

_hardresume                       Returns to DOS after a hardware error

_hardretn                         Returns to the application after a
                                    hardware error

int86                             Invokes DOS interrupts

int86x                            Invokes DOS interrupts with segment
                                    register values

intdos                            Invokes DOS system call using registers
                                    other than DX and AL

intdosx                           Invokes DOS system call using registers
                                    other than DX and AL with segment
                                    register values

segread                           Returns current values of segment
                                    registers (OS/2 and DOS)

The _harderr routine is used to define a hardware-error interrupt handler.
The _hardresume and _hardretn routines are used within a hardware error
handler to define the return from the error.

The dosexterr function obtains and stores the error information returned by
DOS system call 0x59 (extended error handling). This function is provided
for use with DOS versions 3.0 and later.

The bdos routine is useful for invoking DOS calls that use either or both of
the DX (DH/DL) and AL registers for arguments. However, bdos should not be
used to invoke system calls that return an error code in AX if the carry
flag is set; since your program cannot detect whether the carry flag is set,
it cannot determine whether the value in AX is a legitimate value or an
error value. In this case, the intdos routine should be used instead, since
it allows the program to detect whether the carry flag is set. The intdos
routine can also be used to invoke DOS calls that use registers other than
DX and AL.

The intdosx routine is similar to the intdos routine, but is used when ES is
required by the system call, when DS must contain a value other than the
default data segment (for instance, when a far pointer is used), or when
making the system call in a large-model program. When calling intdosx, give
an argument that specifies the segment values to be used in the call.

The int86 routine can be used to invoke any interrupt. The int86x routine is
similar; however, like the intdosx routine, it is designed to work with
large-model programs and far items, as described in the preceding paragraph.


The FP_OFF and FP_SEG routines allow easy access to the segment and offset
portions of a far pointer value. FP_OFF and FP_SEG are implemented as macros
and defined in DOS.H. You can use these macros in OS/2 as well as DOS.

The segread routine returns the current values of the segment registers.
This routine is typically used with the intdosx and int86x routines to
obtain the correct segment values.

The _chain_intr routine is useful for chaining interrupt handlers together.
The _enable routine enables interrupts, while the _disable routine disables
interrupts.

The routines prefixed with  _dos_  are all direct system interfaces that use
the system calls noted above. More detailed information on these system
calls can be found in the MS-DOS Encyclopedia (Duncan, ed.; Redmond, WA:
Microsoft Press, 1988)or the Programmer's PC Sourcebook (Hogan; Redmond, WA:
Microsoft Press, 1988).

────────────────────────────────────────────────────────────────────────────
NOTE

The DOS interface I/O routines are generally incompatible with console,
low-level, and stream I/O routines. Do not mix different types of I/O
routines in the same source file.
────────────────────────────────────────────────────────────────────────────


2.15  Time

The time functions allow you to obtain the current time, then convert and
store it according to your particular needs. The current time is always
taken from the system time.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
asctime                           Converts time from type struct tm to a
                                    character string

clock                             Returns the elapsed CPU time for a
                                    process

ctime                             Converts time from a long integer to a
                                    character string

difftime                          Computes the difference between two
                                    times

ftime                             Puts current system time in variable of
                                    type
                                    struct tm

gmtime                            Converts time from integer to struct tm

localtime                         Converts time from integer to struct tm
                                    with local correction

mktime                            Converts time to a calendar value

_strdate                          Returns the current system date as a
                                    string

strftime                          Formats a date and time string

_strtime                          Returns the current system time as a
                                    string

time                              Gets current system time as a long
                                    integer

tzset                             Sets external time variables from the
                                    environment time variable

utime                             Sets file-modification time

The time and ftime functions return the current time as the number of
seconds elapsed since midnight Universal Coordinated Time (UTC) on January
1, 1970. This value can be converted, adjusted, and stored in a variety of
ways by using the asctime, ctime, gmtime, localtime, and mktime functions.
The utime function sets the modification time for a specified file, using
either the current time or a time value stored in a structure.

The clock function returns the elapsed CPU time for the calling process.

The ftime function requires two files: SYS\TYPES.H and SYS\TIMEB.H. It is
declared in SYS\TIMEB.H. The utime function also requires two include files:
SYS\TYPES.H and SYS\UTIME.H. It is declared in SYS\UTIME.H. The remainder of
the time functions are declared in the include file TIME.H.

When you want to use ftime or localtime to make adjustments for local time,
you must define an environment variable named TZ. Section 3.2, which
describes the global variables daylight, timezone, and tzname, includes a
discussion of the TZ variable. TZ is also described on the tzset reference
page in Part 2 of this book.

The _strdate and _strtime routines return strings containing the current
date and time, respectively, in the DOS and OS/2 date and time format rather
than in the XENIX-style formats.

The stfrtime function is useful for creating international versions of a
program. See Section 2.8, "Internationalization."


2.16  Variable-Length Argument Lists

The va_arg, va_end, and va_start routines are macros that provide a portable
way to access the arguments to a function when the function takes a variable
number of arguments. Two versions of the macros are available: the macros
defined in the VARARG.H include file, which are compatible with the UNIX
System V definition, and the macros defined in STDARG.H, which conform to
the ANSI C standard.

Routine                           Use
────────────────────────────────────────────────────────────────────────────
va_arg                            Retrieves argument from list

va_end                            Resets pointer

va_start                          Sets pointer to beginning of argument
                                    list

For more information on the differences between the two versions and for an
explanation of how to use the macros, see their descriptions in Part 2 of
this book.






Chapter 3  Global Variables and Standard Types
────────────────────────────────────────────────────────────────────────────

The Microsoft C Run-Time Library contains definitions for a number of
variables and standard types used by library routines. You can access these
variables and types by including in your program the files in which they are
declared, or by giving appropriate declarations in your program, as shown in
the following sections.


3.1  _amblksiz

The _amblksiz variable controls memory heap granularity.

It is declared in the MALLOC.H include file as follows:

    extern unsigned int _amblksiz;

The _amblksiz variable controls the amount of memory used in the heap for
dynamic memory allocation.

Memory space is always requested from the operating system in blocks
containing _amblksiz bytes. The first time a program calls a
memory-allocation function such as malloc, the operating system allocates a
block of heap memory. The size of this block is defined by _amblksiz, which
has a default value of 8K (8,192 bytes).

Later memory requests are satisfied from the original block. When that block
is exhausted, another block of _amblksiz bytes is allocated. If your C
program allocates a block larger than _amblksiz, multiple blocks that are
each of size _amblksiz are allocated until the request is satisfied.

To change the size of the default memory block, assign the desired size to
the _amblksiz variable, as in the following example:

    _amblksiz = 2048;

The heap allocator always rounds the operating-system request to the nearest
power of 2 greater than or equal to _amblksiz. The above statement allocates
memory in multiples of 2K (2,048 bytes).

Fewer system calls are required if you set _amblksiz to a large value, but
your program may use more memory than needed. If program speed is important,
set _amblksiz to a large value. If size is important, set _amblksiz to a
smaller value.

Note that adjusting the value of _amblksiz affects allocation in the near,
far, and based heaps. The value of _amblksiz has no effect on huge memory
blocks (those allocated with halloc and similar functions).


3.2  daylight, timezone, tzname

The daylight, timezone, and tzname variables are global timezone variables
used in time functions.

They are declared in the TIME.H include files as follows:

    extern int daylight;

    extern long timezone;

    extern char *tzname [2];

Some time and date routines use the daylight, timezone, and tzname variables
to make local-time adjustments. Whenever a program calls the ftime,
localtime, or tzset function, the value of daylight, timezone, and tzname is
determined from the value of the TZ environment variable. If you do not
explicitly set the value of TZ, the default value of PST8PDT is used. The
following list shows each variable and its value:

Variable                          Value
────────────────────────────────────────────────────────────────────────────
daylight                          Nonzero if a daylight-saving-time zone
                                    (DST) is specified in TZ; otherwise
                                    zero. Default value is one.

timezone                          Difference in seconds between Greenwich
                                    mean time and the local time. Default
                                    value is 28,800.

tzname[0]                         Three-letter time zone name derived from
                                    the TZ environment variable. Default
                                    value is "PST" (Pacific standard time).

tzname[1]                         Three-letter daylight-saving-time zone
                                    name derived from the TZ environment
                                    variable. Default value is PDT. If the
                                    DST zone is omitted from TZ, tzname[1]
                                    is an empty string.


3.3  _doserrno, errno, sys_errlist, sys_nerr

The _doserrno, errno, sys_errlist, and sys_nerr variables contain error
codes, and are used by the perror and _strerror routines to print error
information.

These variables are declared in the STDLIB.H include file. Manifest
constants for the errno variables are declared in the ERRNO.H include file.
The declarations are as follows:

    extern int _doserrno;

    extern int errno;

    extern char *sys_errlist[ ];

    extern int sys_nerr;

The errno variable is set to an integer value to reflect the type of error
that has occurred in a system-level call. Each errno value is associated
with an error message, which can be printed with the perror routine or
stored in a string with the strerror routine.

Note that only some routines set the errno variable. If a routine sets
errno, the description of the routine in the reference section says so
explicitly.

The value of errno reflects the error value for the last call that set
errno. However, this value is not necessarily reset by later successful
calls. To avoid confusion, test for errors immediately after a call.

The include file ERRNO.H contains the definitions of the errno values.
However, not all of the definitions given in ERRNO.H are used in DOS and
OS/2. Some of the values in ERRNO.H are present to maintain compatibility
with XENIX and UNIX operating systems.

The errno values in DOS and OS/2 are a subset of the values for errno in
XENIX systems. Thus, the errno value is not necessarily the same as the
actual error code returned by a DOS or OS/2 system call. To access the
actual DOS and OS/2 error code, use the _doserrno variable, which contains
this value.

In general, you should use _doserrno only for error detection in operations
involving input and output, since the errno values for input and output
errors have DOS and OS/2 error-code equivalents. In other cases, the value
of _doserrno is undefined.

The syserrlist variable is an array; the perror and strerror routines use it
to process error information. The sys_nerr variable tells how many elements
the sys_errlist array contains.

Table 3.1 gives the errno values for DOS and OS/2, the system error message
for each value, and the value of each constant. Note that only the ERANGE
and EDOM constants are specified in the ANSI standard.

Table   3.1 errno Values and Their Meanings

╓┌───────────┌──────────────────────────────────────────────────────────┌────►
Constant    Meaning                                                    Value
─────────────────────────────────────────────────────────────────────────────
E2BIG       Argument list too long                                     7
Constant    Meaning                                                    Value
─────────────────────────────────────────────────────────────────────────────
E2BIG       Argument list too long                                     7

EACCES      Permission denied                                          13

EBADF       Bad file number                                            9

EDEADLOCK   Resource deadlock would occur                              36

EDOM        Math argument                                              33

EEXIST      File exists                                                17

EINVAL      Invalid argument                                           22

EMFILE      Too many open files                                        24

ENOENT      No such file or directory                                  2

ENOEXEC     Exec format error                                          8
Constant    Meaning                                                    Value
─────────────────────────────────────────────────────────────────────────────
ENOEXEC     Exec format error                                          8

ENOMEM      Not enough memory                                          12

ENOSPC      No space left on device                                    28

ERANGE      Result too large                                           34

EXDEV       Cross-device link                                          18

─────────────────────────────────────────────────────────────────────────────




3.4  _fmode

The _fmode variable controls the default file-translation mode.

It is declared in the STDLIB.H include file as follows:

    extern int _fmode;

By default, the value of _fmode is O_TEXT, causing files to be translated in
text mode (unless specifically opened or set to binary mode). When _fmode is
set to O_BINARY, the default mode is binary. You can set _fmode to the flag
O_BINARY by linking with BINMODE.OBJ or by assigning it the O_BINARY value.



3.5  _osmajor, _osminor, _osmode, _osversion

The _osmajor, _osminor, _osmode, and _osversion variables specify the
version number of the operating system or the current mode of operation.

They are declared in the STDLIB.H include file as follows:

    extern unsigned char _osmajor;

    extern unsigned char _osminor;

    extern unsigned char _osmode;

    extern unsigned char _osversion;

The _osmajor, _osminor, and _osversion variables specify the version number
of DOS or OS/2 currently in use. The _osmajor variable holds the "major"
version number and the _osminor variable stores the "minor" version number.
Thus, under DOS version 3.20, _osmajor is 3 and _osminor is 20. The
_osversion variable holds both values; its low byte contains the major
version number and its high byte the minor version number.

These variables are useful for creating programs that run in different
versions of DOS and OS/2. For example, you can test the _osmajor variable
before making a call to sopen; if the major version number is earlier (less)
than 3, open should be used instead of sopen.

The _osmode variable indicates whether the program is in OS/2 protected mode
or in real mode (DOS or OS/2 real mode). An _osmode value of DOS_MODE
indicates real mode operation and a value of OS2_MODE indicates protected
operation.


3.6  environ

The environ variable is a pointer to the strings in the process environment.


It is declared in the STDLIB.H include file as follows:

    extern char *environ [ ];

The environ variable provides access to memory areas containing
process-specific information.

The environ variable is an array of pointers to the strings that constitute
the process environment. The environment consists of one or more entries of
the form

NAME=string

where NAME is the name of an environment variable and string is the value of
that variable. The string may be empty. The initial environment settings are
taken from the operating-system environment at the time of program
execution.

The getenv and putenv routines use the environ variable to access and modify
the environment table. When putenv is called to add or delete environment
settings, the environment table changes size; its location in memory may
also change, depending on the program's memory requirements. The environ
variable is adjusted in these cases and always points to the correct table
location.


3.7  _psp

The _psp variable contains the segment address of the program segment prefix
(PSP) for the process.

It is declared in the STDLIB.H include file as follows:

    extern unsigned int _psp;

The PSP contains execution information about the process, such as a copy of
the command line that invoked the process and the return address on process
termination or interrupt. The _psp variable can be used to form a long
pointer to the PSP, where _psp is the segment value and 0 is the offset
value.

Note that the _psp variable is supported only in DOS.


3.8  Standard Types

A number of library routines use values whose types are defined in include
files. In the following list, these types are described, and the include
file defining each type is given.

Standard Type                     Description
────────────────────────────────────────────────────────────────────────────
clock_t                           The clock_t type, defined in TIME.H,
                                    stores time values. It is used by the
                                    clock function.

complex                           The complex structure, defined in
                                    MATH.H, stores the real and imaginary
                                    parts of complex numbers. It is used by
                                    the cabs function.

diskfree_t                        The diskfree_t structure, defined in
                                    DOS.H, stores disk information used by
                                    the _dos_getdiskfree routine.

diskinfo_t                        The diskinfo_t structure, defined in
                                    BIOS.H, records information about disk
                                    drives returned by the _bios_disk
                                    routine.

div_t, ldiv_t                     The div_t and ldiv_t structures, defined
                                    in STDLIB.H, store the values returned
                                    by the div and ldiv functions,
                                    respectively.

dosdate_t                         The dosdate_t structure, defined in
                                    DOS.H, records the current system date
                                    used in the _dos_getdate and
                                    _dos_setdate routines.

dostime_t                         The dostime_t structure, defined in
                                    DOS.H, records the current system time
                                    used in the _dos_gettime and
                                    _dos_settime routines.

DOSERROR                          The DOSERROR structure, defined in
                                    DOS.H, stores values returned by DOS
                                    system call 59H (available under DOS
                                    versions 3.0 and later).

exception                         The exception structure, defined in
                                    MATH.H, stores error information for
                                    math routines. It is used by the matherr
                                    routine.

FILE                              The FILE structure, defined in STDIO.H,
                                    is the structure used in all stream
                                    input and output operations. The fields
                                    of the FILE structure store information
                                    about the current state of the stream.

find_t                            The find_t structure, defined in DOS.H,
                                    stores file-attribute information
                                    returned by the _dos_findfirst and
                                    _dos_findnext routines.

fpos_t                            The fgetpos and fsetpos functions use
                                    the fpos_t object type, defined in
                                    STDIO.H, to record all the information
                                    necessary to uniquely specify every
                                    position within the file.

jmp_buf                           The jmp_buf type, defined in SETJMP.H,
                                    is an array type rather than a structure
                                    type. A buffer of this type is used by
                                    the setjmp and longjmp routines to save
                                    and restore the program
                                    environment.

lconv                             The lconv type is a structure containing
                                    formatting rules for numeric values in
                                    different countries. It is defined in
                                    LOCALE.H.

onexit_t                          The onexit routine is declared as an
                                    onexit_t pointer type, which is defined
                                    in STDLIB.H.

ptrdiff_t                         The ptrdiff_t type is used for the
                                    signed integral result of the
                                    subtraction of two pointers.

REGS                              The REGS union, defined in DOS.H, stores
                                    byte and word register values to be
                                    passed to and returned from calls to the
                                    DOS interface functions.

sig_atomic_t                      The sig_atomic_t type, defined in
                                    SIGNAL.H, is the integral type of an
                                    object that can be modified as an atomic
                                    entity, even in the presence of
                                    asynchronous interrupts. It is used in
                                    conjunction with the signal routine.

size_t                            The size_t type, defined in STDDEF.H and
                                    several other include files, is the
                                    unsigned integral result of the sizeof
                                    operator.

SREGS                             The SREGS structure, defined in DOS.H,
                                    stores the values of the ES, CS, SS, and
                                    DS registers. This structure is used by
                                    the DOS interface functions that require
                                    segment register values (int86x, intdosx
                                    , and segread).

stat                              The stat structure, defined in
                                    SYS\STAT.H, contains file-status
                                    information returned by the stat and
                                    fstat routines.

time_t                            The time_t type, defined in TIME.H,
                                    represents time values in the mktime and
                                    time routines.

timeb                             The timeb structure, defined in
                                    SYS\TIMEB.H, is used by the ftime
                                    routine to store the current system
                                    time.

tm                                The tm structure, defined in TIME.H, is
                                    used by the asctime, gmtime, and
                                    localtime functions to store and
                                    retrieve time information.

utimbuf                           The utimbuf structure, defined in
                                    SYS\UTIME.H, stores file access and
                                    modification times used by the utime
                                    function to change file-modification
                                    dates.

va_list                           The va_list array type, defined in
                                    STDARG.H, is used to hold information
                                    needed by the va_arg macro and the
                                    va_end routine. The called function
                                    declares a variable of type va_list,
                                    which may be passed as an argument to
                                    another function.






PART II  Run-Time Functions
────────────────────────────────────────────────────────────────────────────

The second part of this book is the reference section. It describes, in
alphabetical order, each function of the run-time library provided with the
Microsoft C Professional Development System.

Each reference entry gives syntax, return values, and other useful
information about the library functions. Information on compatibility is
supplied to assist you in writing portable programs.


About the Run-Time Reference

The following pages describe, in alphabetical order, the more than 400
functions in the Microsoft run-time library. In some cases, related routines
are clustered in the same description. For example, the based, near, and far
versions of _heapwalk are in the same discussion, as are the regular and
long double versions of the math functions, such as acos and atan.
Differences are noted where appropriate. Refer to Chapter 2, "Run-Time
Routines by Category," or to the index to locate any function that does not
appear in the expected position within the alphabetical reference.

The discussion of each function (or group of functions) is divided into the
following sections:


    ■   Description. Summarizes the routine's effect, names the include
        file(s) containing its declaration, illustrates the syntax, and
        briefly describes the arguments.

    ■   Remarks. Gives a more detailed description of the routine and how it
        is used.

    ■   Return Value. Describes the value returned by the routine.

    ■   Compatibility. Tells whether the routine is compatible with ANSI C,
        MS-DOS, OS/2, UNIX, and XENIX.

    ■   See Also. Names related routines.

    ■   Example. Gives a complete program showing the use of the routine.






abort
────────────────────────────────────────────────────────────────────────────


Description

Aborts the current process and returns an error code.

#include <process.h>              Required only for function declarations;
#include <stdlib.h>               use either PROCESS.H or STDLIB.H

    void abort( void );


Remarks

The abort function prints the message

    abnormal program termination

to stderr, then calls raise(SIGABRT). The action taken in response to the
SIGABRT signal depends on what action has been defined for that signal in a
prior call to the signal function. The default SIGABRT action is for the
calling process to terminate with exit code 3, returning control to the
parent process or operating system.

The abort function does not flush stream buffers or do atexit/onexit
processing.


Return Value

The abort function does not return control to the caller. Rather, it
terminates the process and, by default, returns an exit code of 3 to the
parent process.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX


In multithread libraries, the abort function does not call raise(SIGABRT).
Instead, it simply terminates the process with exit code 3.


See Also

exec functions, exit, _exit, raise, signal, spawn functions


Example

    /* ABORT.C:  This tries to open a file and aborts if the attempt fails. */

    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {

        FILE *stream;

        if( (stream = fopen( "NOSUCHF.ILE", "r" )) == NULL )
        {
        perror( "Couldn't open file" );
        abort();
        }
        else
        fclose( stream );
    }


Output



    Couldn't open file: No such file or directory

    abnormal program termination






abs
────────────────────────────────────────────────────────────────────────────


Description

Calculates the absolute value.

#include <stdlib.h>               Required only for function declarations;
#include <math.h>                 use either STDLIB.H or MATH.H

    int abs( int n );

n                                 Integer value


Remarks

The abs function returns the absolute value of its integer argument n.


Return Value

The abs function returns the absolute value of its argument. There is no
error return.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

cabs, fabs, labs


Example

    /* ABS.C: This program computes and displays the absolute values of
    * several numbers.
    */

    #include <stdio.h>
    #include <math.h>
    #include <stdlib.h>

    void main()
    {
        int    ix = -4, iy;
        long   lx = -41567L, ly;
        double dx = -3.141593, dy;

        iy = abs( ix );
        printf( "The absolute value of %d is %d\n", ix, iy);

        ly = labs( lx );
        printf( "The absolute value of %ld is %ld\n", lx, ly);

        dy = fabs( dx );
        printf( "The absolute value of %f is %f\n", dx, dy );
    }


Output



    The absolute value of -4 is 4
    The absolute value of -41567 is 41567
    The absolute value of -3.141593 is 3.141593





access
────────────────────────────────────────────────────────────────────────────


Description

Determines file-access permission.

#include <io.h>                   Required only for function declarations

#include <errno.h>                Required for definition of errno
                                    constants

    int access( char *pathname, int mode );

pathname                          File or directory path name

mode                              Permission setting


Remarks

With files, the access function determines whether the specified file exists
and can be accessed in mode. The possible mode values and their meanings in
the access call are as follows:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
00                                Check for existence only

02                                Check for write permission

04                                Check for read permission

06                                Check for read and write permission

With directories, access determines only whether the specified directory
exists; under DOS and OS/2, all directories have read and write access.


Return Value

The access function returns the value 0 if the file has the given mode. A
return value of -1 indicates that the named file does not exist or is not
accessible in the given mode, and errno is set to one of the following
values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Access denied: the file's permission
                                    setting does not allow the specified
                                    access.

ENOENT                            File or path name not found.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

chmod, fstat, open, stat


Example

    /* ACCESS.C: This example uses access to check the file named "data"
    * to see if it exists and if writing is allowed.
    */

    #include <io.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        /* Check for existence */
        if( (access( "access.c", 0 )) != -1 )
        {
        printf( "File exists\n" );

        /* Check for write permission */
        if( (access( "access.c", 2 )) != -1 )
            printf( "File has write permission\n" );
        }
    }


Output



    File exists
    File has write permission





acos Functions
────────────────────────────────────────────────────────────────────────────


Description

Calculate the arccosine.

#include <math.h>

#include <errno.h>                Required for definition of errno
                                    constant

    double acos( double x );

    long double acosl( long double x );

x                                 Value whose arccosine is to be
                                    calculated


Remarks

The acos functions return the arccosine of x in the range 0 to π radians.
The value of x must be between -1 and 1. The acosl function is the 80-bit
counterpart, which uses an 80-bit, 10-byte coprocessor form of arguments and
return values. See the reference page on the long double functions for more
details on this data type.


Return Value

The acos functions return the arccosine result. If x is less than -1 or
greater than 1, the function sets errno to EDOM, prints a DOMAIN error
message to stderr, and returns 0. Error handling can be modified with the
matherr (or _matherrl) routine.


Compatibility

acos

    ANSI   DOS   OS/2   UNIX   XENIX


acosl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

asin functions, atan functions, cos functions, matherr, sin functions, tan
functions


Example

    /* ASINCOS.C: This program prompts for a value in the range -1 to 1.
    * Input values outside this range will produce DOMAIN error messages.
    * If a valid value is entered, the program prints the arcsine and the
    * arccosine of that value.
    */

    #include <math.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <errno.h>

    void main()
    {
        double x, y;

        printf( "Enter a real number between -1 and 1: " );
        scanf( "%lf", &x );
        y = asin( x );
        printf( "Arcsine of %f = %f\n", x, y );
        y = acos( x );
        printf( "Arccosine of %f = %f\n", x, y );
    }


Output



    Enter a real number between -1 and 1: .32696
    Arcsine of 0.326960 = 0.333085
    Arccosine of 0.326960 = 1.237711





alloca
────────────────────────────────────────────────────────────────────────────


Description

Allocates memory on the stack.

#include <malloc.h>               Required only for function declarations

    void *alloca( size_t size );

size                              Bytes to be allocated from stack


Remarks

The alloca routine allocates size bytes from the program's stack. The
allocated space is automatically freed when the calling function is exited.


When you compile with optimization on (either by default or by using one of
the /O options), the stack pointer may not be restored properly in functions
that have no local variables and that also reference the alloca function.
The following program demonstrates the problem:

    /* Compile with CL /Lp /AM /Ox /Fc */
    #include <malloc.h>

    void main( void )
    {
        func( 10 );
    }
    void func( register int i )
    {
        alloca( i );
    }

To ensure that the stack pointer is properly restored, make sure that any
function referencing alloca declares at least one local variable.

The pointer value returned by alloca should never be passed as an argument
to free, nor should alloca be used in an expression that is an argument to a
function.


Return Value

The alloca routine returns a void pointer to the allocated space, which is
guaranteed to be suitably aligned for storage of any type of object. To get
a pointer to a type other than char, use a type cast on the return value.
The return value is NULL if the space cannot be allocated.


Compatibility

▼ ANSI   DOS   OS/2   UNIX  ▼ XENIX



See Also

calloc functions, malloc functions, realloc functions


Example

    /* ALLOCA.C: This program checks the stack space available before
    * and after using the alloca function to allocate space on the stack.
    */

    #include <malloc.h>
    #include <stdio.h>

    void main()
    {
        char *buffer;

        printf( "Bytes available on stack: %u\n", stackavail() );

        /* Allocate memory for string. */
        buffer = alloca( 120 * sizeof( char ) );
        printf( "Enter a string: " );
        gets( buffer );
        printf( "You entered: %s\n", buffer );

        printf( "Bytes available on stack: %u\n", stackavail() );
    }


Output



    Bytes available on stack: 2028
    Enter a string: How much stack space will this string take?
    You entered: How much stack space will this string take?
    Bytes available on stack: 1902





_arc Functions
────────────────────────────────────────────────────────────────────────────


Description

Draw elliptical arcs.

    #include <graph.h>

    short _far _arc( short x1, short y1, short x2, short y2, short x3,
    short y3, short x4, short y4 );

    short _far _arc_w( double x1, double y1, double x2, double y2, double x3,
    double y3, double x4, double y4 );

    short _far _arc_wxy( struct _wxycoord _far *pwxy1,
    struct _wxycoord _far *pwxy2,
    struct _wxycoord _far *pwxy3, struct _wxycoord _far *pwxy4);

x1, y1                            Upper-left corner of bounding rectangle

x2, y2                            Lower-right corner of bounding rectangle

x3, y3                            Second point of start vector (center of
                                    bounding rectangle is first point)

x4, y4                            Second point of end vector (center of
                                    bounding rectangle is first point)

pwxy1                             Upper-left corner of bounding rectangle

pwxy2                             Lower-right corner of bounding rectangle

pwxy3                             Second point of start vector (center of
                                    bounding rectangle is first point)

pwxy4                             Second point of end vector (center of
                                    bounding rectangle is first point)


Remarks

The _arc functions draw elliptical arcs. The center of the arc is the center
of the bounding rectangle, which is defined by points (x1, y1) and (x2, y2)
for _arc and _arc_w and by points pwxy1 and pwxy2 for _arc_wxy. The arc
starts where it intersects an imaginary line extending from the center of
the arc through (x3, y3) for _arc and _arc_w and through pwxy3 for _arc_wxy.
It is drawn counterclockwise about the center of the arc, ending where it
intersects an imaginary line extending from the center of the arc through
(x4, y4) for _arc  and _arc_w and through pwxy4 for _arc_wxy.

The _arc routine uses the view coordinate system. The _arc_w and _arc_wxy
functions use the real-valued window coordinate system.

In each case, the arc is drawn using the current color. Since an arc does
not define a closed area, it is not filled.


Return Value

These functions return a nonzero value if the arc is successfully drawn;
otherwise, they return 0.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_ellipse functions,  _lineto functions,  _pie functions,  _rectangle
functions,  _setcolor


Example

    /* ARC.C: This program draws a simple arc. */

    #include <graph.h>
    #include <stdlib.h>
    #include <conio.h>

    void main()
    {
        short x, y;
        struct xycoord xystart, xyend, xyfill;

        /* Find a valid graphics mode */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        /* Draw arcs         */
        x = 100; y = 100;
        _arc( x - 60, y - 60, x, y, x - 30, y - 60, x - 60, y - 30 );
        _arc( x + 60, y + 60, x, y, x,      y + 30, x + 30, y );

        /* Get endpoints of second arc and enclose the figure, then fill it. */
        _getarcinfo( &xystart, &xyend, &xyfill );
        _moveto( xystart.xcoord, xystart.ycoord );
        _lineto( xyend.xcoord,   xyend.ycoord );
        _floodfill( xyfill.xcoord, xyfill.ycoord, _getcolor() );

        getch();
        _setvideomode( _DEFAULTMODE );
    }





asctime
────────────────────────────────────────────────────────────────────────────


Description

Converts a tm time structure to a character string.

    #include <time.h>

    char *asctime( const struct tm *timeptr );

timeptr                           Time/date structure


Remarks

The asctime function converts a time stored as a structure to a character
string. The timeptr value is usually obtained from a call to gmtime or
localtime, both of which return a pointer to a tm structure, defined in
TIME.H. (See gmtime for a complete description of the tm structure fields.)


The tm structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
int tm_sec                        Seconds after the minute (0 -59)

int tm_min                        Minutes after the hour (0 -59)

int tm_hour                       Hours since midnight (0 -23)

int tm_mday                       Day of the month (0 -31)

int tm_mon                        Months since January (0 -11)

int tm_year                       Years since 1900

int tm_wday                       Days since Sunday (0 - 6)

int tm_yday                       Days since January 1 (0 -365)

int tm_isdst                      Daylight-saving-time flag

The string result produced by asctime contains exactly 26 characters and has
the form of the following example:

    Wed Jan 02 02:03:55 1980\n\0

A 24-hour clock is used. All fields have a constant width. The newline
character (\n) and the null character ('\0') occupy the last two positions
of the string. The asctime function uses a single statically allocated
buffer to hold the return string. Each call to this routine destroys the
result of the previous call.


Return Value

The asctime function returns a pointer to the character string result. There
is no error return.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

ctime, ftime, gmtime, localtime, time, tzset


Example

    /* ASCTIME.C: This program places the system time in the long integer
    aclock,
    * translates it into the structure newtime and then converts it to
    * string form for output, using the asctime function.
    */

    #include <time.h>
    #include <stdio.h>

    struct tm *newtime;
    time_t aclock;

    void main()
    {
        time( &aclock );                    /* Get time in seconds */

        newtime = localtime( &aclock );     /* Convert time to struct tm form
*/

        /* Print local time as a string */
        printf( "The current date and time are: %s\n", asctime( newtime ) );
    }


Output



    The current date and time are: Thu Jun 15 06:57:59 1989





asin Functions
────────────────────────────────────────────────────────────────────────────


Description

Calculate the arcsine.

    #include <math.h>

    #include <errno.h>

    double asin( double x );

    long double asinl( long double x );

x                                 Value whose arcsine is to be calculated


Remarks

The asin functions calculate the arcsine of x in the range -π/2 to π/2
radians. The value of x must be between -1 and 1. The asinl function is the
80-bit counterpart, which uses an 80-bit, 10-byte coprocessor form of
arguments and return values. See the reference page on the long double
functions for more details on this data type.


Return Value

The asin functions return the arcsine result. If x is less than -1 or
greater than 1, asin sets errno to EDOM, prints a DOMAIN error message to
stderr, and returns 0.

Error handling can be modified by using the matherr (or _matherrl) routine.



Compatibility

asin

    ANSI   DOS   OS/2   UNIX   XENIX


asinl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

acos functions, atan functions, cos functions, matherr, sin functions, tan
functions


Example

    /* ASINCOS.C: This program prompts for a value in the range -1 to 1.
    * Input values outside this range will produce DOMAIN error messages.
    * If a valid value is entered, the program prints the arcsine and the
    * arccosine of that value.
    */

    #include <math.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <errno.h>

    void main()
    {
        double x, y;

        printf( "Enter a real number between -1 and 1: " );
        scanf( "%lf", &x );
        y = asin( x );
        printf( "Arcsine of %f = %f\n", x, y );
        y = acos( x );
        printf( "Arccosine of %f = %f\n", x, y );
    }


Output



    Enter a real number between -1 and 1: .32696
    Arcsine of 0.326960 = 0.333085
    Arccosine of 0.326960 = 1.237711





assert
────────────────────────────────────────────────────────────────────────────


Description

Prints an error message and aborts the program.

#include <assert.h>

#include <stdio.h>

    void assert( int expression );

expression                        C expression specifying assertion being
                                    tested


Remarks

The assert routine prints a diagnostic message and calls the abort routine
if expression is false (0). The diagnostic message has the form

    Assertion failed: expression, file filename, line linenumber

where filename is the name of the source file and linenumber is the line
number of the assertion that failed in the source file. No action is taken
if expression is true (nonzero).

The assert routine is typically used in program development to identify
program logic errors. The given expression should be chosen so that it holds
true only if the program is operating as intended. After a program has been
debugged, the special "no debug" identifier NDEBUG can be used to remove
assert calls from the program. If NDEBUG is defined (by any value) with a /D
command-line option or with a #define directive, the C preprocessor removes
all assert calls from the program source.

The assert routine is implemented as a macro.


Return Value

None.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

abort, raise, signal


Example

    /* ASSERT.C: In this program, the analyze_string function uses the
    * assert function to test several conditions related to string and
    * length. If any of the conditions fails, the program prints a
    * message indicating what caused the failure.
    */

    #include <stdio.h>
    #include <assert.h>
    #include <string.h>

    void analyze_string( char *string );   /* Prototype */

    void main()
    {
        char  test1[] = "abc", *test2 = NULL, test3[] = "";

        printf ( "Analyzing string '%s'\n", test1 );
        analyze_string( test1 );
        printf ( "Analyzing string '%s'\n", test2 );
        analyze_string( test2 );
        printf ( "Analyzing string '%s'\n", test3 );
        analyze_string( test3 );
    }

    /* Tests a string to see if it is NULL, empty, or longer than 0 characters
*/
    void analyze_string( char * string )
    {
        assert( string != NULL );        /* Cannot be NULL */
        assert( *string != '\0' );       /* Cannot be empty */
        assert( strlen( string ) > 2 );  /* Length must be greater than 2 */
    }


Output



    Analyzing string 'abc'
    Analyzing string '(null)'
    Assertion failed: string != NULL, file assert.c, line 28

    abnormal program termination





atan Functions
────────────────────────────────────────────────────────────────────────────


Description

Calculate the arctangent of x (atan and atanl) and the arctangent of y/x
(atan2 and atan2l).

    #include <math.h>

    double atan( double x );

    double atan2( double y, double x );

    long double atanl( long double x );

    long double atan2l( long double y, long double x );

x, y                              Any number


Remarks

The atan family of functions calculates the arctangent of x, and the atan2
family of functions calculates the arctangent of y/x. The atan group returns
a value in the range -π/2 to π/2 radians, and the atan2 group returns a
value in the range -π toπ radians. The atan2 functions use the signs of both
arguments to determine the quadrant of the return value.


Return Value

The atan family of functions returns the arctangent result. If both
arguments of atan2 or atan2l are 0, the function sets errno to EDOM, prints
a DOMAIN error message to stderr, and returns 0.

Error handling can be modified by using the matherr (or _matherrl) routine.



Compatibility

atan, atan2

    ANSI   DOS   OS/2   UNIX   XENIX


atanl, atan2l

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

acos functions, asin functions, cos functions, matherr, sin functions, tan
functions


Example

    /* ATAN.C: This program calculates the arctangent of 1 and -1. */

    #include <math.h>
    #include <stdio.h>
    #include <errno.h>

    void main()
    {
        double x1, x2, y;

        printf( "Enter a real number: " );
        scanf( "%lf", &x1 );
        y = atan( x1 );
        printf( "Arctangent of %f: %f\n", x1, y );
        printf( "Enter a second real number: " );
        scanf( "%lf", &x2 );
        y = atan2( x1, x2 );
        printf( "Arctangent of %f / %f: %f\n", x1, x2, y );
    }


Output



    Enter a real number: -862.42
    Arctangent of -862.420000: -1.569637
    Enter a second real number: 78.5149
    Arctangent of -862.420000 / 78.514900: -1.480006





atexit
────────────────────────────────────────────────────────────────────────────


Description

Processes the specified function at exit.

#include <stdlib.h>               Required only for function declarations

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

func                              Function to be called


Remarks

The atexit function is passed the address of a function (func) to be called
when the program terminates normally. Successive calls to atexit create a
register of functions that are executed in LIFO (last-in-first-out) order.
No more than 32 functions can be registered with atexit or onexit. The
functions passed to atexit cannot take parameters.

All routines passed to atexit should have the _loadds attribute if used in
multithread dynamic-link libraries.


Return Value

The atexit function returns 0 if it is successful, or a nonzero value if an
error occurs (e.g., if there are already 32 exit functions defined).


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX


Use the ANSI-standard atexit function (rather than the similar onexit
function) whenever ANSI portability is desired.

In the OS/2 environment, the atexit function calls the OS/2 function
DosExitList.


See Also

abort, exit, _exit, onexit


Example

    /* ATEXIT.C: This program pushes four functions onto the stack of
    functions
    * to be executed when atexit is called. When the program exits, these
    * programs are executed on a "last in, first out" basis.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void fn1( void ), fn2( void ), fn3( void ), fn4( void );

    void main()
    {
        atexit( fn1 );
        atexit( fn2 );
        atexit( fn3 );
        atexit( fn4 );
        printf( "This is executed first.\n" );
    }

    void fn1()
    {
        printf( "next.\n" );
    }

    void fn2()
    {
        printf( "executed " );
    }

    void fn3()
    {
        printf( "is " );
    }

    void fn4()
    {
        printf( "This " );
    }


Output



    This is executed first.
    This is executed next.





atof, atoi, atol, _atold
────────────────────────────────────────────────────────────────────────────


Description

Convert strings to double (atof), long double (_atold) integer (atoi), or
long (atol).

#include <math.h>                 atof, _atold

#include <stdlib.h>               atof, _atold, atoi, atol

    double atof( const char *string );

    long double _atold( const char *string );

    int atoi( const char *string );

    long atol( const char *string );

string                            String to be converted


Remarks

These functions convert a character string to a double-precision
floating-point value (atof), an integer value (atoi), a long integer value
(atol), or a long double value (_atold). The input string is a sequence of
characters that can be interpreted as a numerical value of the specified
type.

The string size that can be handled by the atof or _atold function is
limited to 100 characters.

The function stops reading the input string at the first character that it
cannot recognize as part of a number. This character may be the null
character ('\0') terminating the string.

The atof and _atold functions expect string to have the following form:

    [[whitespace]] [[{sign}]] [[ IK0digits]] [[.digits]]
    [[{d| D | e | E}[[sign]digits]]

A whitespace consists of space and/or tab characters, which are ignored;
sign is either plus (+) or minus (-); and digits are one or more decimal
digits. If no digits appear before the decimal point, at least one must
appear after the decimal point. The decimal digits may be followed by an
exponent, which consists of an introductory letter (d, D, e, or E) and an
optionally signed decimal integer.

The atoi and atol functions do not recognize decimal points or exponents.
The string argument for these functions has the form

    [[whitespace]] [[sign]]digits

where whitespace, sign, and digits are exactly as described above for atof.



Return Value

Each function returns the double, long double, int, or long value produced
by interpreting the input characters as a number. The return value is 0 (for
atoi), 0L (for atol), and 0.0 (for atof and _atold) if the input cannot be
converted to a value of that type. The return value is undefined in case of
overflow.


Compatibility

atof, atoi, atol

    ANSI   DOS   OS/2   UNIX   XENIX


_atold

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

ecvt, fcvt, gcvt


Example

    /* ATOF.C: This program shows how numbers stored as strings can be
    * converted to numeric values using the atof, atoi, and atol functions.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        char *s; double x; int i; long l;

        s = "  -2309.12E-15";    /* Test of atof */
        x = atof( s );
        printf( "atof test:  ASCII string: %s\tfloat:     %e\n", s, x );

        s = "7.8912654773d210";  /* Test of atof */
        x = atof( s );
        printf( "atof test:  ASCII string: %s\tfloat:     %e\n", s, x );

        s = "  -9885 pigs";      /* Test of atoi */
        i = atoi( s );
        printf( "atoi test:  ASCII string: %s\t\tinteger: %d\n", s, i );

        s = "98854 dollars";     /* Test of atol */
        l = atol( s );
        printf( "atol test:  ASCII string: %s\t\tlong:    %ld\n", s, l );
    }


Output



    atof test:  ASCII string:   -2309.12E-15        float:     -2.309120e-012
    atof test:  ASCII string: 7.8912654773d210      float:     7.891265e+210
    atoi test:  ASCII string:   -9885 pigs          integer: -9885
    atol test:  ASCII string: 98854 dollars         long:    98854





bdos
────────────────────────────────────────────────────────────────────────────


Description

Invokes the DOS system call.

#include <dos.h>

    int bdos( int dosfunc, unsigned int dosdx, unsigned int dosal );

dosfunc                           Function number

dosdx                             DX register value

dosal                             AL register value


Remarks

The bdos function invokes the DOS system call specified by dosfunc after
placing the values specified by dosdx and dosal in the DX and AL registers,
respectively. The bdos function executes an INT 21H instruction to invoke
the system call. When the system call is complete, bdos returns the contents
of the AX register.

The bdos function is intended to be used to invoke DOS system calls that
either take no arguments or take arguments only in the DX (DH, DL) and/or AL
registers.

Do not use the bdos function to call interrupts that modify the DS register.
Instead, use the intdosx or int86x function. The intdosx and int86x
functions load the DS and ES registers from the segregs parameter and also
store the DS and ES registers into segregs after the function call.

This call should not be used to invoke system calls that indicate errors by
setting the carry flag. Since C programs do not have access to this flag,
your program cannot determine whether the return value is an error code. The
intdos function should be used in these cases.


Return Value

The bdos function returns the value of the AX register after the system call
has completed.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

intdos, intdosx


Example

    /* BDOS.C: This example calls DOS function 0x9 (display string)
    * to display a $-terminated string.
    */

    #include <dos.h>

    /* Function 0x09 assumes that DS will contain segment of the string.
    * This will be true for all memory models if the string is declared near.
    */
    char _near str[] = "Hello world!\r\n$";

    void main()
    {
        /* Offset of string must be in DX, segment in DS. AL is not needed,
        * so 0 is used.
        */
        bdos( 0x09, (int)str, 0 );
    }


Output



    Hello world!





_beginthread
────────────────────────────────────────────────────────────────────────────


Description

Begins thread in OS/2 process.

#include <process.h>              Multithread version of PROCESS.H

#include <stddef.h>               Declaration of threadid variable

    int _far  _beginthread( void( _far *start_address )( void _far * ),
    void  _far *stack_bottom, unsigned stack_size, void  _far *arglist );

start_address                     Starting address

stack_bottom                      Address of the thread stack

stack_size                        Stack size for thread

arglist                           Argument list for thread


Remarks

The _beginthread function creates a thread that begins execution of a far
routine at start_address. When the thread returns from that far routine, it
is terminated automatically. The user can also terminate the thread by
calling _endthread.

The address of the thread stack is given by stack_bottom. If stack_bottom is
set to NULL, the run-time library code will allocate and deallocate the
thread stack as needed. Since the _beginthread function can determine the
current status of all thread IDs, it can free the old stack and allocate a
new stack whenever a thread is reused.

If it is not NULL, the stack_bottom argument must specify a word address,
and the stack must be at least as long as specified by the stack_size
argument. Usually this memory is either a global array or memory returned by
malloc or _fmalloc.

The stack_size argument must be even and nonzero.

If you are writing multithread programs that make C run-time calls from
child threads, be sure to allocate a sufficiently large stack. For example,
the C function printf requires more than 500 bytes of stack space. To be
safe, allocate at least 2,048 bytes for a thread's stack. (If your child
thread makes no run-time calls, stack space is generally not a problem.)

As a general rule, you should have 2K of stack space free when calling any
API (Applications Program Interface) routine (e.g., OS/2 system calls).

The arglist is a parameter, the size of a far pointer, to be passed to the
newly created thread. Typically it is the address of a data item, such as a
character string, to be passed to the new thread. The arglist may be NULL if
not needed, but _beginthread should be provided with some value to pass to
the child thread.

All threads will be terminated if any thread calls abort, exit, _exit, or
DosExit. A good practice in multithread programming is to make the first
thread the main thread and wait until other threads have terminated before
exiting the program.

The OS/2 function DosCreateThread should not be called directly to create
threads. The _beginthread function performs initialization procedures
required to call other C run-time library functions safely.


Return Value

The function returns the thread identification number of the new thread, if
successful. A return value of -1 indicates an error, and errno is set to one
of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EAGAIN                            Too many threads

EINVAL                            Invalid argument, "bad stack"


Compatibility

▼ ANSI  ▼ DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_endthread


Example

    /* BEGTHRD.C illustrates multiple threads using functions:
    *      _beginthread            _endthread
    *
    * Also the global variable:
    *      _threadid
    *
    * This program requires the multithread library. For example, compile
    * with the following command line:
    *      CL /MT THREADS.C
    */

    #define INCL_NOCOMMON
    #define INCL_NOPM
    #define INCL_DOSPROCESS
    #define INCL_VIO
    #include <os2.h>
    #include <process.h>    /* _beginthread, _endthread */
    #include <stddef.h>     /* _threadid                */
    #include <stdlib.h>
    #include <conio.h>

    void Bounce( int c );       /* Prototypes */
    void CheckKey( void *dummy );

    /* GetRandom returns a random integer between min and max. */
    #define GetRandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) +
(min))

    #define STACK_SIZE   4096

    BOOL repeat = TRUE;         /* Global repeat flag and video variable */
    VIOMODEINFO vmi = { sizeof( VIOMODEINFO ) };

    void main()
    {
        PCHAR   stack;
        CHAR    ch = 'A';

        /* Get display screen's text row and column information. */
        VioGetMode( &vmi, 0 );

        /* Launch CheckKey thread to check for terminating keystroke. */
        _beginthread( CheckKey, NULL, STACK_SIZE, NULL );

        /* Loop until CheckKey terminates program. */
        while( repeat )
        {
            /* On first loops, launch character threads. */
            _beginthread( Bounce, NULL, STACK_SIZE, (void *)ch++ );

            /* Wait one second between loops. */
            DosSleep( 1000L );
        }
    }

    /* CheckKey - Thread to wait for a keystroke, then clear repeat flag. */
    void CheckKey( void *dummy )
    {
        getch();
        repeat = 0;      /* _endthread implied */
    }

    /* Bounce - Thread to create and control a colored letter that moves
    * around on the screen.
    *
    * Params: ch - the letter to be moved
    */
    void Bounce( int ch )
    {
        /* Generate letter and color attribute from thread argument. */
        char      blankcell[2] = { 0x20, 0x07 };
        char      blockcell[2] = { ch , (ch % 16) + 1 };
        int       xold, xcur, yold, ycur;
        BOOL      first = TRUE;

    /* Seed random number generator and get initial location. */
        srand( *_threadid );
        xcur = GetRandom( 0, vmi.col - 1 );
        ycur = GetRandom( 0, vmi.row - 1 );
        while( repeat )
        {
            /* Pause between loops. */
            DosSleep( 100L );

            /* Blank out our old position on the screen, and draw new letter.
*/
            if( first )
                first = FALSE;
            else
                VioWrtCellStr( blankcell, 2, yold, xold, 0 );
            VioWrtCellStr( blockcell, 2, ycur, xcur, 0 );

            /* Increment the coordinate for next placement of the block. */
            xold = xcur;
            yold = ycur;
            xcur += GetRandom( -1, 1 );
            ycur += GetRandom( -1, 1 );

            /* Correct placement (and beep) if about to go off the screen. */
            if( xcur < 0 )
                xcur = 1;
            else if( xcur == vmi.col )
                xcur = vmi.col - 2;
            else if( ycur < 0 )
                ycur = 1;
            else if( ycur == vmi.row )
                ycur = vmi.row - 2;

            /* If not at screen border, continue, otherwise beep. */
            else
                continue;
            DosBeep( (ch - 'A') * 100, 175 );
        }
        /* _endthread given (but not really needed) to terminate. */
        _endthread();
    }





Bessel Functions
────────────────────────────────────────────────────────────────────────────


Description


Compute the Bessel function.

#include <math.h>

    double j0( double x );

    double j1( double x );

    double jn( int n, double x );

    double y0( double x );

    double y1( double x );

    double yn( int n, double x );

    long double _j0l( long double x );

    long double _jnl( int n, long double x );

    long double _j1l( long double x );

    long double _y0l( long double x );

    long double _y1l( long double x );

    long double _ynl( int n, long double x );

x                                 Floating-point value

n                                 Integer order


Remarks

The j0, j1, and jn routines return Bessel functions of the first kind─orders
0, 1, and n, respectively.

The y0, y1, and yn routines return Bessel functions of the second
kind─orders 0, 1, and n, respectively. The argument x must be positive.

The long double versions of these functions are the 80-bit counterparts and
use the 80-bit, 10-byte coprocessor form of arguments and return values. See
the reference page on the long double functions for more details on this
data type.

The Bessel functions are explained more fully in most mathematics reference
books, such as the Handbook of Mathematical Functions (Abramowitz and
Stegun; Washington: U.S. Government Printing Office, 1964). These functions
are commonly used in the mathematics of electromagnetic wave theory.


Return Value

These functions return the result of a Bessel function of x.

For y0, y1, or yn, if x is negative, the routine sets errno to EDOM, prints
a DOMAIN error message to stderr, and returns -HUGE_VAL.

Error handling can be modified by using the matherr (or _matherrl) routine.



Compatibility

j0, j1, jn, y0, y1, yn

▼ ANSI   DOS   OS/2   UNIX   XENIX


_j0l,  _j1l,  _jnl,  _y0l,  _y1l,  _ynl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

matherr


Example

    /* BESSEL.C: This program illustrates Bessel functions, including:
    *      j0          j1          jn          y0          y1          yn
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = 2.387;
        int n = 3, c;

        printf( "Bessel functions for x = %f:\n", x );
        printf( "  Kind\t\tOrder\t\Function\tResult\n\n" );
        printf( "  First\t\t0\tj0( x )\t\t%f\n", j0( x ) );
        printf( "  First\t\t1\tj1( x )\t\t%f\n", j1( x ) );
        for( c = 2; c < 5; c++ )
            printf( "  First\t\t%d\tjn( n, x )\t%f\n", c, jn( c, x ) );

        printf( "  Second\t0\ty0( x )\t\t%f\n", y0( x ) );
        printf( "  Second\t1\ty1( x )\t\t%f\n", y1( x ) );
        for( c = 2; c < 5; c++ )
            printf( "  Second\t%d\tyn( n, x )\t%f\n", c, yn( c, x ) );
    }


Output



    Bessel functions for x = 2.387000:
    Kind          Order   Function        Result

    First         0       j0( x )         0.009288
    First         1       j1( x )         0.522941
    First         2       jn( n, x )      0.428870
    First         3       jn( n, x )      0.195734
    First         4       jn( n, x )      0.063131
    Second        0       y0( x )         0.511681
    Second        1       y1( x )         0.094374
    Second        2       yn( n, x )      -0.432608
    Second        3       yn( n, x )      -0.819314
    Second        4       yn( n, x )      -1.626833





_bfreeseg
────────────────────────────────────────────────────────────────────────────


Description

Frees a specified based heap.

#include <malloc.h>               Required only for function declarations

    int _bfreeseg( _segment seg );

seg                               Segment selected


Remarks

The _bfreeseg function frees a based heap. The seg argument is a based heap
returned by an earlier call to _bheapseg. It specifies the based heap to be
freed.

The number of bytes freed is the number of bytes specified when the block
was allocated. After the call, the freed heap is again available for
allocation.


Return Value

The _bfreeseg function returns 0 if successful and -1 in the case of an
error.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_bheapseg, calloc functions, free functions, malloc functions, realloc
functions


Example

    /* BHEAPSEG.C: This program C illustrates dynamic allocation of based
    * memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree.
    */

    #include <stdio.h>
    #include <malloc.h>
    #include <stdlib.h>
    #include <string.h>

    void main()
    {
        _segment seg;
        char _based( seg ) *outstr, _based( seg ) *instr;
        char _based( seg ) *pout,   _based( seg ) *pin;
        char tmpstr[80];
        int  len;

        printf( "Enter a string: " );
        gets( tmpstr );

        /* Request a based heap. Use based so that memory won't be taken from
        * near heap.
        */
        if( (seg = _bheapseg( 1000 )) == _NULLSEG )
            exit( 1 );

        /* Allocate based memory for two strings. */
        len = strlen( tmpstr );
        if( ((instr  = _bmalloc( seg, len + 1 )) == _NULLOFF) ||
            ((outstr = _bmalloc( seg, len + 1 )) == _NULLOFF) )
            exit( 1 );

        /* Copy a lowercased string to dynamic memory. The based memory is
        * far when addressed as a whole.
        */
        _fstrlwr( _fstrcpy( (char _far *)instr, (char _far *)tmpstr ) );

        /* Copy input string to output string in reversed order. When reading
        * and writing individual characters from a based heap, the compiler
will
        * try to process them as near, thus speeding up the processing.
        */
        for( pin = instr + len - 1, pout = outstr;
                    pout < outstr + len; pin--, pout++ )
            *pout = *pin;
        *pout = '\0';

        /* Display strings. Again strings as a whole are far. */
        printf( "Input:  %Fs\n", (char _far *)instr );
        printf( "Output: %Fs\n", (char _far *)outstr );

        /* Free blocks and release based heap. */
        _bfree( seg, instr );
        _bfree( seg, outstr );
        _bfreeseg( seg );
    }


Output



    Enter a string: Was I god
    Input:  was i god
    Output: dog i saw





_bheapseg
────────────────────────────────────────────────────────────────────────────


Description

Allocates a based heap.

#include <malloc.h>               Required only for function declarations

    _segment _bheapseg( size_t size );

size                              Segment size to allocate


Remarks

The _bheapseg function allocates a based-heap segment of at least size
bytes. (The block may be larger than size bytes because of space required
for alignment and for maintenance information.)

The heap code will try to enlarge the heap as necessary. If the original
block of memory is depleted (e.g., by calls to _bmalloc and _brealloc), the
run-time code will try to enlarge the heap as necessary.

The value returned by _bheapseg is the identifier of the based-heap segment.
This value should be saved and used in subsequent calls to other based-heap
functions.

The _bheapseg function can be called repeatedly. For each call, the C
library will allocate a new based-heap segment.


Return Value

The _bheapseg function returns the newly allocated segment selector that the
user must save for use in subsequent based-heap functions. A return value of
-1 indicates failure.

Always check the return from the _bheapseg function (especially when it is
used in real mode), even if the amount of memory requested is small.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

calloc functions, free functions, malloc functions, realloc functions


Example

    /* BHEAPSEG.C: This program C illustrates dynamic allocation of based
    * memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree.
    */

    #include <stdio.h>
    #include <malloc.h>
    #include <stdlib.h>
    #include <string.h>

    void main()
    {
        _segment seg;
        char _based( seg ) *outstr, _based( seg ) *instr;
        char _based( seg ) *pout,   _based( seg ) *pin;
        char tmpstr[80];
        int  len;

        printf( "Enter a string: " );
        gets( tmpstr );

        /* Request a based heap. Use based so that memory won't be taken from
        * near heap.
        */
        if( (seg = _bheapseg( 1000 )) == _NULLSEG )
            exit( 1 );

        /* Allocate based memory for two strings. */
        len = strlen( tmpstr );
        if( ((instr  = _bmalloc( seg, len + 1 )) == _NULLOFF) ||
            ((outstr = _bmalloc( seg, len + 1 )) == _NULLOFF) )
            exit( 1 );

        /* Copy a lowercased string to dynamic memory. The based memory is
        * far when addressed as a whole.
        */
        _fstrlwr( _fstrcpy( (char _far *)instr, (char _far *)tmpstr ) );

        /* Copy input string to output string in reversed order. When reading
        * and writing individual characters from a based heap, the compiler
will
        * try to process them as near, thus speeding up the processing.
        */
        for( pin = instr + len - 1, pout = outstr;
                    pout < outstr + len; pin--, pout++ )
            *pout = *pin;
        *pout = '\0';

        /* Display strings. Again, strings as a whole are far. */
        printf( "Input:  %Fs\n", (char _far *)instr );
        printf( "Output: %Fs\n", (char _far *)outstr );

        /* Free blocks and release based heap. */
        _bfree( seg, instr );
        _bfree( seg, outstr );
        _bfreeseg( seg );
    }


Output



    Enter a string: Was I god
    Input:  was i god
    Output: dog i saw





_bios_disk
────────────────────────────────────────────────────────────────────────────


Description

Calls BIOS disk services using system call INT 0x13.

#include <bios.h>

    unsigned _bios_disk( unsigned service, struct diskinfo_t  *diskinfo );

service                           Disk function desired

diskinfo                          Disk parameters


Remarks

The _bios_disk routine uses system call INT 0x13 to provide several
disk-access functions. The service parameter selects the function desired,
while the diskinfo structure provides the necessary parameters. Note that
the low-level disk operations allowed by the _bios_disk routine are very
dangerous to use because they allow direct manipulation of the disk.

The diskinfo structure provides the following parameters:

Element                           Description
────────────────────────────────────────────────────────────────────────────
unsigned drive                    Drive number

unsigned head                     Head number

unsigned track                    Track number

unsigned sector                   Starting sector number

unsigned nsectors                 Number of sectors to read, write, or
                                    compare

void far *buffer                  Memory location to write to, read from,
                                    or compare

The service argument can be set to one of the following manifest constants:


Constant                          Function
────────────────────────────────────────────────────────────────────────────
_DISK_FORMAT                      Formats the track specified by diskinfo.
                                    The head and track fields indicate the
                                    track to format. Only one track can be
                                    formatted in a single call. The buffer
                                    field points to a set of sector markers.
                                    The format of the markers depends on the
                                    type of disk drive; see a technical
                                    reference to the PC BIOS to determine
                                    the marker format. There is no return
                                    value.

_DISK_READ                        Reads one or more disk sectors into
                                    memory. This service uses all fields of
                                    the structure pointed to by diskinfo, as
                                    defined earlier in this section. If no
                                    error occurs, the function returns 0 in
                                    the high-order byte and the number of
                                    sectors read in the low-order byte. If
                                    there is an error, the high-order byte
                                    will contain a set of status flags. If
                                    there is an error, the high-order byte
                                    will contain a set of status flags, as
                                    defined under _DISK_READ. Status is
                                    returned in the 8 high-order bits of the
                                    return value, as listed below:

                                    Bits          Meaning
────────────────────────────────────────────────────────────────────────────
                                    0x01**        Invalid request or a bad
                                    command

                                    0x02**        Address mark not found

                                    0x04**        Sector not found

                                    0x05**        Reset failed

                                    0x07**        Drive parameter activity
                                    failed

                                    0x09**        Direct Memory Access (DMA)
                                    overrun

                                    0x0A**        Bad sector flag detected

                                    0x10**        Data read (ECC) error

                                    0x11**        Corrected data read (ECC)
                                    error

                                    0x20**        Controller failure

                                    0x40**        Seek error

                                    0x80**        Disk timed out or failed
                                    to respond

                                    0xAA**        Drive not ready

                                    0xBB**        Undefined error

                                    0xCC**        Write fault on drive

                                    0xE0**        Status error

_DISK_RESET                       Forces the disk controller to do a hard
                                    reset, preparing for floppy-disk I/O.
                                    This is useful after an error occurs in
                                    another operation, such as a read. If
                                    this service is specified, the
                                    diskinfo argument is ignored.

_DISK_STATUS                      Obtains the status of the last disk
                                    operation. If this service is specified,
                                    the diskinfo argument is ignored.

_DISK_VERIFY                      Checks the disk to be sure the specified
                                    sectors exist and can be read. It also
                                    runs a CRC (cyclic redundancy check)
                                    test. This service uses all fields
                                    (except buffer) of the structure pointed
                                    to by diskinfo, as defined earlier in
                                    this section. If no error occurs, the
                                    function returns 0 in the high-order
                                    byte and the number of sectors compared
                                    in the low-order byte. If there is an
                                    error, the high-order byte will contain
                                    a set of status flags, as defined under
                                    _DISK_READ (above).

_DISK_WRITE                       Writes data from memory to one or more
                                    disk sectors. This service uses all
                                    fields of the structure pointed to by
                                    diskinfo, as defined earlier in this
                                    section. If no error occurs, the
                                    function returns 0 in the high-order
                                    byte and the number of sectors written
                                    in the low-order byte. If there is an
                                    error, the high-order byte will contain
                                    a set of status flags, as defined under
                                    _DISK_READ (above).


Return Value

The _bios_disk function returns the value in the AX register after the BIOS
interrupt.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BDISK.C: This program first attempts to verify a disk by using an
    * invalid disk head number. After printing the return value error code,
    * the program verifies the disk by using a valid disk head code.
    */

    #include <conio.h>
    #include <stdio.h>
    #include <bios.h>

    void main()
    {
        unsigned status = 0;
        struct diskinfo_t disk_info;

        disk_info.drive    = 0;
        disk_info.head     = 10;   /* Invalid head number */
        disk_info.track    = 1;
        disk_info.sector   = 2;
        disk_info.nsectors = 8;

    printf( "Insert disk in drive A: and press any key\n" );
        getch();
        status = _bios_disk( _DISK_VERIFY, &disk_info );
        printf( "Return value: 0x%.4x\n", status );
        if( status & 0xff00 )      /* Error if high byte is 0 */
        printf( "Seek error\n" );
        else
        printf( "No seek error\n" );

        printf( "Press any key\n" );
        getch();
        disk_info.head = 0;        /* Valid head number */
        status = _bios_disk( _DISK_VERIFY, &disk_info );
        printf( "Return value: 0x%.4x\n", status );
        if( status & 0xff00 )      /* Error if high byte is 0 */
        printf( "Seek error\n" );
        else
        printf( "No seek error\n" );
    }


Output



    Insert disk in drive A: and press any key
    Return value: 0x0400
    Seek error
    Press any key
    Return value: 0x0008
    No seek error





_bios_equiplist
────────────────────────────────────────────────────────────────────────────


Description

Calls BIOS equipment-list service, using system call INT 0x11.

#include <bios.h>

    unsigned _bios_equiplist( void );


Remarks

The _bios_equiplist routine uses system call INT 0x11 to determine what
hardware and peripherals are currently installed on the machine.


Return Value

The function returns a set of bits indicating what is installed, as defined
below:

Bits                              Meaning
────────────────────────────────────────────────────────────────────────────
0                                 Any disk drive installed if true

1                                 True (1) if math coprocessor installed

2 -3                              System RAM in 16K blocks (16-64K)

4 -5                              Initial video mode

6 -7                              Number of floppy-disk drives installed
                                    (00 = 1,  01 = 2, etc.)

8                                 False (0) if and only if a Direct Memory
                                    Access (DMA) chip is installed

9 -11                             Number of RS232 serial ports installed

12                                True (1) if and only if a game adapter
                                    is installed

13                                True (1) if and only if an internal
                                    modem is installed

14 -15                            Number of printers installed


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BEQUIPLI.C: This program checks for the presence of diskettes. */

    #include <bios.h>
    #include <stdio.h>

    void main()
    {
        unsigned equipment;

        equipment = _bios_equiplist();
        printf( "Equipment bits: 0x%.4x\n", equipment );
        if( equipment & 0x1000 )      /* Check for game adapter bit */
        printf( "Game adapter installed\n" );
        else
        printf( "No game adapter installed\n" );
    }


Output



    Equipment bits: 0x4061
    No game adapter installed





_bios_keybrd
────────────────────────────────────────────────────────────────────────────


Description

Calls BIOS keyboard services, using INT 0x16.

#include <bios.h>

    unsigned _bios_keybrd( unsigned service );

service                           Keyboard function desired


Remarks

The _bios_keybrd routine uses system call INT 0x16 to access the keyboard
services. The service argument can be any of the following manifest
constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_KEYBRD_READ,                     Reads the next character from the
_NKEYBRD_READ                     keyboard. If no character has been
                                    typed, the call will wait for one. If
                                    the low-order byte of the return value
                                    is nonzero, the call contains the ASCII
                                    value of the character typed. The
                                    high-order byte contains the keyboard
                                    scan code for the character. The
                                    _NKEYBRD_READ constant is used with
                                    enhanced keyboards to obtain the scan
                                    codes for function keys F11 and F12 and
                                    the cursor control keys.

_KEYBRD_READY,                    Checks whether a keystroke is waiting to
_NKEYBRD_READY                    be read and, if so, reads it. The return
                                    value is 0 if no keystroke is waiting,
                                    or it is the character waiting to be
                                    read, in the same format as the
                                    _KEYBRD_READ or  _NKEYBRD_READY return.
                                    This service does not remove the waiting
                                    character from the input buffer, as does
                                    the _KEYBRD_READ or _NKEYBRD_READ
                                    service.  The _NKEYBRD_READY constant is
                                    used with enhanced keyboards to obtain
                                    the scan codes for function keys F11 and
                                    F12 and the cursor control keys.

_KEYBRD_SHIFTSTATUS,              Returns the current SHIFT-key status.
_NKEYBRD_SHIFTSTATUS              Only the low-order byte of the return
                                    value is affected. The
                                    _NKEYBRD_SHIFTSTATUS constant is used to
                                    get a full 16-bit status value. Any
                                    combination of the following bits may be
                                    set:

                                    Bit         Meaning if True
────────────────────────────────────────────────────────────────────────────
                                    00H         Rightmost SHIFT key pressed

                                    01H         Leftmost SHIFT key pressed

                                    02H         Either CTRL key pressed

                                    3H          Either ALT key pressed

                                    04H         SCROLL LOCK on

                                    05H         NUM LOCK on

                                    06H         CAPS LOCK on

                                    07H         In insert mode (INS)

                                    08H         Left CTRL key pressed

                                    09H         Left ALT key pressed

                                    0AH         Right CTRL key pressed

                                    0BH         Right ALT key pressed

                                    0CH         SCROLL LOCK key pressed

                                    0DH         NUM LOCK key pressed

                                    0EH         CAPS LOCK key pressed

                                    0FH         SYS REQ key pressed


Return Value

With the ...READ and ...SHIFTSTATUS arguments, the _bios_keybrd function
returns the contents of the AX register after the BIOS call.

With the ...READY argument, _bios_keybrd returns 0 if there is no key. If
there is a key, _bios_keybrd returns the key waiting to be read (i.e. the
same value as _KEYBRD_READ).

With the ...READ and the ...READY arguments, the _bios_keybrd function
returns -1 if CTRL+BREAK has been pressed and is the next keystroke to be
read.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BKEYBRD.C: This program prints a message on the screen until the
    * right SHIFT key is pressed.
    */

    #include <bios.h>
    #include <stdio.h>

    void main()
    {
        while( !(_bios_keybrd( _KEYBRD_SHIFTSTATUS ) & 0001) )
        printf( "Use the right SHIFT key to stop this message\n" );
        printf( "Right SHIFT key pressed\n" );
    }


Output



    Use the right SHIFT key to stop this message
    Use the right SHIFT key to stop this message
    Use the right SHIFT key to stop this message
    Use the right SHIFT key to stop this message
    Right SHIFT key pressed





_bios_memsize
────────────────────────────────────────────────────────────────────────────


Description

Calls the BIOS memory-size service, using system call INT 0x12.

#include <bios.h>

    unsigned _bios_memsize( void );


Remarks

The _bios_memsize routine uses system call INT 0x12 to determine the total
amount of main memory installed.


Return Value

The routine returns the total amount of installed memory in 1K blocks. The
maximum return value is 640, representing 640K of main memory.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BMEMSIZE.C: This program displays the amount of memory installed. */

    #include <bios.h>
    #include <stdio.h>

    void main()
    {
        unsigned memory;

        memory = _bios_memsize();
        printf ( "The amount of memory installed is: %dK\n", memory );
    }


Output



    The amount of memory installed is: 639K





_bios_printer
────────────────────────────────────────────────────────────────────────────


Description

Calls BIOS printer services using system call INT 0x17.

#include <bios.h>

    unsigned _bios_printer( unsigned service, unsigned printer, unsigned data
    );

service                           Printer function desired

printer                           Target printer port

data                              Output data


Remarks

The _bios_printer routine uses system call INT 0x17 to perform printer
output services for parallel printers. The printer argument specifies the
affected printer, where 0 is LPT1, 1 is LPT2, and so forth.

Some printers do not support the full set of signals. As a result, the "Out
of Paper" condition, for example, may not be returned to your program.

The service argument can be any of the following manifest constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_PRINTER_INIT                     Initializes the selected printer. The
                                    data argument is ignored. The return
                                    value is the low-order status byte
                                    defined below.

_PRINTER_STATUS                   Returns the printer status in the
                                    low-order status byte defined below. The
                                    data argument is ignored.

_PRINTER_WRITE                    Sends the low-order byte of data to the
                                    printer specified by printer. The
                                    low-order byte of the return value
                                    indicates the printer status after the
                                    operation, as defined below:

                                    Bit      Meaning if True
────────────────────────────────────────────────────────────────────────────
                                    0         Printer timed out

                                    1         Not used

                                    2         Not used

                                    3         I/O error

                                    4         Printer selected

                                    5         Out of paper

                                    6         Acknowledge

                                    7         Printer not busy




Return Value

The _bios_printer function returns the value in the AX register after the
BIOS interrupt.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BPRINTER.C: This program checks the status of the printer attached to
    * LPT1 when it is off line, then initializes the printer.
    */

    #include <bios.h>
    #include <conio.h>
    #include <stdio.h>

    #define LPT1 0

    void main()
    {
        unsigned status;

        printf ( "Place printer off line and press any key\n" );
        getch();

        status = _bios_printer( _PRINTER_STATUS, LPT1, 0 );
        printf( "Status with printer off line: 0x%.4x\n\n", status );
        printf( "Put the printer on line and then\n" );
        printf( "Press any key to initialize printer\n" );
        getch();

        status = _bios_printer( _PRINTER_INIT, LPT1, 0 );
        printf( "Status after printer initialized: 0x%.4x\n", status );
    }


Output



    Place printer off line and press any key
    Status with printer off line: 0x0018

    Put the printer on line and then
    Press any key to initialize printer
    Status after printer initialized: 0x0090





_bios_serialcom
────────────────────────────────────────────────────────────────────────────


Description

Calls BIOS communications services, using system call INT 0x14.

#include <bios.h>

    unsigned _bios_serialcom( unsigned service, unsigned serial_port, unsigned
    data );

service                           Communications service

serial_port                       Serial port to use

data                              Port configuration bits


Remarks

The _bios_serialcom routine uses system call INT 0x14 to provide serial
communications services. The serial_port argument is set to 0 for COM1, to 1
for COM2, and so on.

The _bios_serialcom routine may not be able to establish reliable
communications at baud rates in excess of 1,200 baud ( _COM_1200) due to the
overhead associated with servicing computer interrupts. Faster data
communication rates are possible with more direct programming of serial-port
controllers. See C Programmer's Guide to Serial Communications for more
details on serial-communications programming in C.

The service argument can be set to one of the following manifest constants:


Constant                          Service
────────────────────────────────────────────────────────────────────────────
_COM_INIT                         Sets the port to the parameters
                                    specified in the data argument

_COM_SEND                         Transmits the data characters over the
                                    selected serial port

_COM_RECEIVE                      Accepts an input character from the
                                    selected serial port

_COM_STATUS                       Returns the current status of the
                                    selected serial port

The data argument is ignored if service is set to _COM_RECEIVE or
_COM_STATUS. The data argument for _COM_INIT is created by combining (with
the OR operator) one or more of the following constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_COM_CHR7                         7 data bits

_COM_CHR8                         8 data bits

_COM_STOP1                        1 stop bit

_COM_STOP2                        2 stop bits

_COM_NOPARITY                     No parity

_COM_EVENPARITY                   Even parity

_COM_ODDPARITY                    Odd parity

_COM_110                          110 baud

_COM_150                          150 baud

_COM_300                          300 baud

_COM_600                          600 baud

_COM_1200                         1,200 baud

_COM_2400                         2,400 baud

_COM_4800                         4,800 baud

_COM_9600                         9,600 baud

The default value of data is 1 stop bit, no parity, and 110 baud.


Return Value

The function returns a 16-bit integer whose high-order byte contains status
bits. The meaning of the low-order byte varies, depending on the service
value. The high-order bits have the following meanings:

Bit                               Meaning if Set
────────────────────────────────────────────────────────────────────────────
15                                Timed out

14                                Transmission-shift register empty

13                                Transmission-hold register empty

12                                Break detected

11                                Framing error

10                                Parity error

9                                 Overrun error

8                                 Data ready

When service is _COM_SEND, bit 15 will be set if data could not be sent.

When service is _COM_RECEIVE, the byte read will be returned in the
low-order bits if the call is successful. If an error occurs, any of the
bits 9, 10, 11, or 15 will be set.

When service is _COM_INIT or _COM_STATUS, the low-order bits are defined as
follows:

Bit                               Meaning if Set
────────────────────────────────────────────────────────────────────────────
7                                 Receive-line signal detected

6                                 Ring indicator

5                                 Data set ready

4                                 Clear to send

3                                 Change in receive-line signal detected

2                                 Trailing-edge ring indicator

1                                 Change in data-set-ready status

0                                 Change in clear-to-send status

Note that this function works only with IBM personal computers and true
compatibles.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BSERIALC.C: This program checks the status of serial port COM1. */

    #include <bios.h>
    #include <stdio.h>

    void main()
    {
        unsigned com1_status;

        com1_status =  _bios_serialcom( _COM_STATUS, 0, 0 );
        printf ( "COM1 status: 0x%.4x\n", com1_status );
    }


Output



    COM1 status: 0x6000





_bios_timeofday
────────────────────────────────────────────────────────────────────────────


Description

Calls BIOS time and date services, using system call INT 0x1A.

#include <bios.h>

    unsigned _bios_timeofday( unsigned service, long *timeval );

service                           Time function desired

timeval                           Clock count


Remarks

The _bios_timeofday routine uses system call INT 0x1A to get or set the
clock count. The service argument can be either of the following manifest
constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_TIME_GETCLOCK                    Copies the current value of the clock
                                    count to the location pointed to by
                                    timeval. If midnight has not passed
                                    since the last time the system clock was
                                    read or set, the function returns 0;
                                    otherwise, the function returns 1.

_TIME_SETCLOCK                    Sets the current value of the system
                                    clock to the value in the location
                                    pointed to by timeval. There is no
                                    return value.


Return Value

The _bios_timeofday function returns the value in the AX register after the
BIOS interrupt.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* BTIMEOFD.C: This program gets the current system clock count before and
    after
    * a "do-nothing" loop and displays the difference.
    */

    #include <bios.h>
    #include <stdio.h>

    void main()
    {
        long i, begin_tick, end_tick;

        _bios_timeofday( _TIME_GETCLOCK, &begin_tick );
        printf( "Beginning tick count: %lu\n", begin_tick );
        for( i = 1; i <= 900000; i++ )
        ;
        _bios_timeofday( _TIME_GETCLOCK, &end_tick );
        printf( "Ending tick count:    %lu\n", end_tick );
        printf( "Elapsed ticks:        %lu\n", end_tick - begin_tick );
    }


Output



    Beginning tick count: 1114255
    Ending tick count:    1114287
    Elapsed ticks:        32





bsearch
────────────────────────────────────────────────────────────────────────────


Description

Performs binary search of a sorted array.

#include <stdlib.h>               Required for ANSI compatibility

#include <search.h>               Required only for function declarations

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

key                               Object to search for

base                              Pointer to base of search data

num                               Number of elements

width                             Width of elements

compare                           Function that compares two elements:
                                    elem1 and elem2

elem1                             Pointer to the key for the search

elem2                             Pointer to the array element to be
                                    compared with the key


Remarks

The bsearch function performs a binary search of a sorted array of num
elements, each of width bytes in size. The base value is a pointer to the
base of the array to be searched, and key is the value being sought.

The compare argument is a pointer to a user-supplied routine that compares
two array elements and returns a value specifying their relationship. The
bsearch function calls the compare routine one or more times during the
search, passing pointers to two array elements on each call. The routine
compares the elements, then returns one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
< 0                               elem1 less than elem2

= 0                               elem1 identical to elem2

> 0                               elem1 greater than elem2

If the array you are searching is not in ascending sort order, bsearch does
not work properly. If the array contains duplicate records with identical
keys, there is no way to predict which of the duplicate records will be
located by bsearch.


Return Value

The bsearch function returns a pointer to the first occurrence of key in the
array pointed to by base. If key is not found, the function returns NULL.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

lfind, lsearch, qsort


Example

    /* BSEARCH.C: This program reads the command-line arguments, sorting them
    * with qsort, and then uses bsearch to find the word "cat."
    */

    #include <search.h>
    #include <string.h>
    #include <stdio.h>

    int compare( char **arg1, char **arg2 );  /* Declare a function for
compare */

    void main( int argc, char **argv )
    {

        char **result;
        char *key = "cat";
        int i;

        /* Sort using Quicksort algorithm: */
        qsort( (char *)argv, argc, sizeof( char * ), compare );

        for( i = 0; i < argc; ++i )        /* Output sorted list */
        printf( "%s ", argv[i] );

        /*  Find the word "cat" using a binary search algorithm: */
        result = (char **)bsearch( (char *) &key, (char *)argv, argc,
                                sizeof( char * ), compare );
        if( result )
        printf( "\n%s found at %Fp\n", *result, result );
        else
        printf( "\nCat not found!\n" );
    }

    int compare( char **arg1, char **arg2 )
    {
        /* Compare all of both strings: */
        return strcmpi( *arg1, *arg2 );
    }


Output



    [C:\LIBREF] bsearch dog pig horse cat human rat cow goat
    bsearch cat cow dog goat horse human pig rat
    cat found at 0292:0FD0





cabs, cabsl
────────────────────────────────────────────────────────────────────────────


Description

Calculate absolute value of a complex number.

    #include <math.h>

    double cabs( struct complex z );

    long double cabsl( struct _complexl z );

z                                 Complex number


Remarks

The cabs and cabsl functions calculate the absolute value of a complex
number, which must be a structure of type complex (or _complexl). The
structure z is composed of a real component x and an imaginary component y.
A call to one of the cabs routines is equivalent to the following:


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

The cabsl function is the 80-bit counterpart and it uses the 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.


Return Value

On overflow, these functions call matherr or _matherrl, return HUGE_VAL, and
set errno to ERANGE.


Compatibility

    cabs

▼ ANSI   DOS   OS/2   UNIX   XENIX


    cabsl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

abs, fabs, labs


Example

    /* CABS.C: Using cabs, this program calculates the absolute value of
    * a complex number.
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        struct complex number = { 3.0, 4.0 };
        double d;

        d = cabs( number );
        printf( "The absolute value of %f + %fi is %f\n",
                number.x, number.y, d );
    }


Output



    The absolute value of 3.000000 + 4.000000i is 5.000000





calloc Functions
────────────────────────────────────────────────────────────────────────────


Description

Allocate an array in memory with elements initialized to 0.

#include <stdlib.h>               For ANSI compatibility (calloc only)

#include <malloc.h>               Required only for function declarations

    void *calloc( size_t num, size_t size );

    void _based( void ) *_bcalloc( _segment seg, size_t num, size_t size );

    void _far *_fcalloc( size_t num, size_t size );

    void _near *_ncalloc( size_t num, size_t size );

num                               Number of elements

size                              Length in bytes of each element

seg                               Segment selector


Remarks

The calloc family of functions allocates storage space for an array of num
elements, each of length size bytes. Each element is initialized to 0.

In large data models (compact-, large-, and huge-model programs), calloc
maps to  _fcalloc. In small data models (tiny-, small-, and medium-model
programs), calloc maps to _ncalloc.

The various calloc functions allocate storage space in the data segments
shown in the list below:

Function                          Data Segment
────────────────────────────────────────────────────────────────────────────
calloc                            Depends on data model of program

_bcalloc                          Based heap, specified by seg segment
                                    selector

_fcalloc                          Far heap (outside default data segment)

_ncalloc                          Near heap (inside default data segment)


Return Value

The calloc functions return a pointer to the allocated space. The storage
space pointed to by the return value is guaranteed to be suitably aligned
for storage of any type of object. To get a pointer to a type other than
void, use a type cast on the return value.

The _fcalloc and _ncalloc functions return NULL if there is insufficient
memory available or if num or size is 0. The _bcalloc function returns
_NULLOFF in this case.


Compatibility

    calloc

    ANSI   DOS   OS/2   UNIX   XENIX


_bcalloc, _fcalloc, _ncalloc

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

free functions, halloc, hfree, malloc functions, realloc functions


Example

    /* CALLOC.C: This program uses calloc to allocate space for 40 long
    integers.
    * It initializes each element to zero.
    */

    #include <stdio.h>
    #include <malloc.h>

    void main()
    {
        long *buffer;

        buffer = (long *)calloc( 40, sizeof( long ) );
        if( buffer != NULL )
        printf( "Allocated 40 long integers\n" );
        else
        printf( "Can't allocate memory\n" );
        free( buffer );
    }


Output



    Allocated 40 long integers





ceil, ceill
────────────────────────────────────────────────────────────────────────────


Description

Calculate the ceiling of a value.

    #include <math.h>

    double ceil( double x );

    long double ceill( long double x );

x                                 Floating-point value


Remarks

The ceil and ceill functions return a double (or long double) value
representing the smallest integer that is greater than or equal to x.

The ceill function is the 80-bit counterpart and it uses the 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.


Return Value

These functions return the double or long double result. There is no error
return.


Compatibility

    ceil

    ANSI   DOS   OS/2   UNIX   XENIX


    ceill

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

floor, fmod


Example

    /* FLOOR.C: This example displays the largest integers less than or equal
    * to the floating-point values 2.8 and -2.8. It then shows the smallest
    * integers greater than or equal to 2.8 and -2.8.
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double y;

        y = floor( 2.8 );
        printf( "The floor of 2.8 is %f\n", y );
        y = floor( -2.8 );
        printf( "The floor of -2.8 is %f\n", y );

        y = ceil( 2.8 );
        printf( "The ceil of 2.8 is %f\n", y );
        y = ceil( -2.8 );
        printf( "The ceil of -2.8 is %f\n", y );
    }


Output



    The floor of 2.8 is 2.000000
    The floor of -2.8 is -3.000000
    The ceil of 2.8 is 3.000000
    The ceil of -2.8 is -2.000000





_cexit, _c_exit
────────────────────────────────────────────────────────────────────────────


Description

Perform clean-up operations and return without terminating the process.

    #include <process.h>

    void _cexit( void );

    void _c_exit( void );


Remarks

The _cexit function calls, in LIFO ("last in, first out") order, the
functions registered by atexit and onexit. Then the _cexit function flushes
all I/O buffers and closes all open files before returning.

The _c_exit function returns to the calling process without processing
atexit or onexit functions or flushing stream buffers.

The behavior of the exit, _exit, _cexit, and _c_exit functions is described
in the following list:

Function                          Action
────────────────────────────────────────────────────────────────────────────
exit                              Performs complete C library termination
                                    procedures, terminates the process, and
                                    exits with the supplied status code

_exit                             Performs "quick" C library termination
                                    procedures, terminates the process, and
                                    exits with the supplied status code

_cexit                            Performs complete C library termination
                                    procedures and returns to caller, but
                                    does not terminate the process

_c_exit                           Performs "quick" C library termination
                                    procedures and returns to caller, but
                                    does not terminate the process


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

abort, atexit, exec functions, exit, onexit, spawn functions, system





cgets
────────────────────────────────────────────────────────────────────────────


Description

Gets a character string from the console.

#include <conio.h>                Required only for function declarations

    char *cgets( char *buffer );

buffer                            Storage location for data


Remarks

The cgets function reads a string of characters directly from the console
and stores the string and its length in the location pointed to by buffer.
The buffer argument must be a pointer to a character array. The first
element of the array, buffer[0], must contain the maximum length (in
characters) of the string to be read. The array must contain enough elements
to hold the string, a terminating null character ('\0'), and two additional
bytes.

The cgets function continues to read characters until a
carriage-return-line-feed (CR-LF) combination is read, or the specified
number of characters is read. The string is stored starting at str[2]. If a
CR-LF combination is read, it is replaced with a null character ('\0')
before being stored. The cgets function then stores the actual length of the
string in the second array element, buffer[1].

Because all DOS editing keys are active when you call cgets, pressing F3
repeats the last entry.


Return Value

The cgets function returns a pointer to the start of the string, at
buffer[2]. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

getch, getche


Example

    /* CGETS.C: This program creates a buffer and initializes the first byte
    * to the size of the buffer - 2. Next, the program accepts an input
string
    * using cgets and displays the size and text of that string.
    */

    #include <conio.h>
    #include <stdio.h>

    void main()
    {
        char buffer[82] = { 80 };  /* Maximum characters in first byte */
        char *result;

        printf( "Input line of text, followed by carriage return:\n");
        result = cgets( buffer );  /* Input a line of text */
        printf( "\nLine length = %d\nText = %s\n", buffer[1], result );
    }


Output



    Input line of text, followed by carriage return:
    This is some text
    Line length = 17
    Text = This is some text





_chain_intr
────────────────────────────────────────────────────────────────────────────


Description

Chains an interrupt from one handler to another.

    #include <dos.h>

    void _chain_intr( void( _interrupt _far *target )());

target                            Target interrupt routine


Remarks

The _chain_intr routine passes control from one interrupt handler to
another. The stack and the registers of the first routine are passed to the
second, allowing the second routine to return as if it had been called
directly.

The _chain_intr routine is generally used when a user-defined interrupt
handler begins processing, then chains to the original interrupt handler to
finish processing.

Chaining is one of two techniques, listed below, that can be used to
transfer control from a new interrupt routine to an old one:


    1.  Call _chain_intr with the interrupt routine as an argument. Do this if
        your routine is finished and you want the second interrupt routine to
        terminate the interrupt call.

        void _interrupt new_int( unsigned _es, unsigned _ds,
            unsigned _di, unsigned _si,... )
        {
            ++_di;                  /* Initial processing here  */
            _chain_intr( old_int ); /* New DI passed to old_int */
            --_di;                  /* This is never executed   */
        }


    2.  Call the interrupt routine (after casting it to an interrupt function
        if necessary). Do this if you need to do further processing after the
        second interrupt routine finishes.

        void _interrupt new_int( unsigned _es, unsigned _ds,
            unsigned _di, unsigned _si,... )
        {
            ++_di;                   /* Initial processing here  */
            (*old_int)();            /* New DI passed to old_int */
            _asm mov _di, di         /* Put real DI from old_int */
                                    /*   into _di for return    */
        }



Note that the real registers set by the old interrupt function are not
automatically set to the pseudoregisters of the new routine.

Use the _chain_intr function when you do not want to replace the default
interrupt handler, but you do need to see its input. An example is a TSR
(terminate-and-stay-resident) program that checks all keyboard input for a
particular "hot key" sequence.

The _chain_intr function should be used only with C functions that have been
declared with type _interrupt. The _interrupt declaration ensures that the
procedure's entry/exit sequence is appropriate for an interrupt handler.


Return Value

The _chain_intr function does not return to the caller.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getvect,  _dos_keep,  _dos_setvect





chdir
────────────────────────────────────────────────────────────────────────────


Description

Changes the current working directory.

#include <direct.h>               Required only for function declarations

#include <errno.h>                Required for errno constants

    int chdir( char *dirname );

dirname                           Path name of new working directory


Remarks

The chdir function changes the current working directory to the directory
specified by  dirname. The dirname argument must refer to an existing
directory.

This function can change the current working directory on any drive; it
cannot be used to change the default drive itself. For example, if A: is the
default drive and \BIN is the current working directory, the following call
changes the current working directory for drive C:

    chdir("c:\\temp");

Notice that you must place two backslashes ( \\ ) in a C string in order to
represent a single backslash ( \ ); the backslash is the escape character
for C strings and therefore requires special handling.

This function call has no apparent immediate effect. However, when the
_chdrive function is called to change the default drive to C:, the current
working directory becomes C:\TEMP.

In OS/2 protected mode, the current working directory is local to a process
rather than system-wide. When a process terminates, the current working
directory is restored to its original value. Under DOS, the new directory
set by the program becomes the new current working directory.


Return Value

The chdir function returns a value of 0 if the working directory is
successfully changed. A return value of -1 indicates an error, in which case
errno is set to ENOENT, indicating that the specified path name could not be
found.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

_dos_setdrive, mkdir, rmdir, system


Example

    /* CHGDIR.C: This program uses the chdir function to verify that a
    * given directory exists. Under real mode that directory also becomes
    * the current directory. Under protected mode, it is only the default
    * directory for the current process.
    */

    #include <direct.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main( int argc, char *argv[] )
    {
        if( chdir( argv[1] )   )
        printf( "Unable to locate the directory: %s\n", argv[1] );
        else
        system( "dir *.c" );
    }


Output



    [C:\LIBREF] chgdir \tmp

    The volume label in drive C is OS2.
    Directory of C:\TMP

    DUP      C        232   4-18-89  11:18a
    TEST     C        713   4-07-88   2:49p
        2 File(s)   14155776 bytes free





_chdrive
────────────────────────────────────────────────────────────────────────────


Description

Changes the current working drive.

#include <direct.h>               Required only for function declarations

    int _chdrive( int drive );

drive                             Number of new working drive


Remarks

The _chdrive function changes the current working drive to the drive
specified by drive. The drive argument uses an integer to specify the new
working drive (1=A, 2=B, etc.).

This function changes only the working drive; the chdir function changes the
working directory.

In OS/2 protected mode, the working drive is local to a process rather than
system-wide. When a process terminates, the working drive is restored to its
original value. Under DOS, the new drive set by the program becomes the new
working drive.


Return Value

The _chdrive function returns a value of 0 if the working drive is
successfully changed. A return value of -1 indicates an error.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

chdir,  _dos_setdrive,  _fullpath,  _getcwd,  _getdrive, mkdir, rmdir,
system


Example

    /* GETDRIVE.C illustrates drive functions including:
    *      _getdrive       _chdrive        _getdcwd
    */

    #include <stdio.h>
    #include <conio.h>
    #include <direct.h>
    #include <stdlib.h>

    void main()
    {
        int ch, drive, curdrive;
        static char path[_MAX_PATH];

        /* Save current drive. */
        curdrive = _getdrive();

        printf( "Available drives are: \n" );

        /* If we can switch to the drive, it exists. */
        for( drive = 1; drive <= 26; drive++ )
        if( !_chdrive( drive ) )
            printf( "%c: ", drive + 'A' - 1 );

        while( 1 )
        {
        printf( "\nType drive letter to check or ESC to quit: " );
        ch = getch();
        if( ch == 27 )
            break;
        if( isalpha( ch ) )
            putch( ch );
        if( _getdcwd( toupper( ch ) - 'A' + 1, path, _MAX_PATH ) != NULL )
            printf( "\nCurrent directory on that drive is %s\n", path );
        }

        /* Restore original drive. This is only necessary for DOS. Under OS/2
        * the current drive of the calling process is always restored.
        */
        _chdrive( curdrive );
        printf( "\n" );
    }


Output



    Available drives are:
    A: B: C:
    Type drive letter to check or ESC to quit: q
    Type drive letter to check or ESC to quit: a
    Current directory on that drive is A:\

    Type drive letter to check or ESC to quit: c
    Current directory on that drive is C:\LIBREF

    Type drive letter to check or ESC to quit:





chmod
────────────────────────────────────────────────────────────────────────────


Description

Changes the file-permission settings.

#include <sys\types.h>

#include <sys\stat.h>

#include <errno.h>

#include <io.h>                   Required only for function declarations

    int chmod( char *filename, int pmode );

filename                          Path name of existing file

pmode                             Permission setting for file


Remarks

The chmod function changes the permission setting of the file specified by
filename. The permission setting controls read and write access to the file.
The constant expression pmode contains one or both of the manifest constants
S_IWRITE and S_IREAD, defined in SYS\STAT.H. Any other values for pmode are
ignored. When both constants are given, they are joined with the bitwise-OR
operator ( | ). The meaning of the pmode argument is as follows:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
S_IWRITE                          Writing permitted

S_IREAD                           Reading permitted

S_IREAD |  S_IWRITE               Reading and writing permitted

If write permission is not given, the file is read-only. Under DOS and OS/2,
all files are readable; it is not possible to give write-only permission.
Thus the modes S_IWRITE and S_IREAD  |  S_IWRITE are equivalent.


Return Value

The chmod function returns the value 0 if the permission setting is
successfully changed. A return value of -1 indicates an error; in this case,
errno is set to ENOENT, indicating that the specified file could not be
found.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

access, creat, fstat, open, stat


Example

    /* CHMOD.C: This program uses chmod to change the mode of a file to
    * read-only. It then attempts to modify the file.
    */

    #include <sys\types.h>
    #include <sys\stat.h>
    #include <io.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        /* Make file read-only: */
        if( chmod( "CHMOD.C", S_IREAD ) == -1 )
        perror( "File not found\n" );
        else
        printf( "Mode changed to read-only\n" );
        system( "echo /* End of file */ >> CHMOD.C" );

        /* Change back to read/write: */
        if( chmod( "CHMOD.C", S_IWRITE ) == -1 )
        perror( "File not found\n" );
        else
        printf( "Mode changed to read/write\n" );
    }


Output



    Mode changed to read-only
    Access denied
    Mode changed to read/write





chsize
────────────────────────────────────────────────────────────────────────────


Description

Changes the file size.

#include <io.h>                   Required only for function declarations

#include <errno.h>

    int chsize( int handle, long size );

handle                            Handle referring to open file

size                              New length of file in bytes


Remarks

The chsize function extends or truncates the file associated with handle to
the length specified by size. The file must be open in a mode that permits
writing. Null characters ('\0') are appended if the file is extended. If the
file is truncated, all data from the end of the shortened file to the
original length of the file is lost.

In DOS, the directory update is done when a file is closed. Consequently,
while a program is running, requests to determine the amount of free disk
space may receive inaccurate results.


Return Value

The chsize function returns the value 0 if the file size is successfully
changed. A return value of -1 indicates an error, and errno is set to one of
the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Specified file is locked against access
                                    (OS/2 and DOS versions 3.0 and later
                                    only).

EBADF                             Specified file is read-only or an
                                    invalid file handle.

ENOSPC                            No space is left on device.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

close, creat, open


Example

    /* CHSIZE.C: This program uses filelength to report the size of a
    * file before and after modifying it with chsize.
    */

    #include <io.h>
    #include <fcntl.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <stdio.h>

    void main()
    {
        int fh, result;
        unsigned int nbytes = BUFSIZ;

        /* Open a file */
        if( (fh = open( "data", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 )
        {
        printf( "File length before: %ld\n", filelength( fh ) );
        if( chsize( fh, 329678 ) == 0 )
            printf( "Size successfully changed\n" );
        else
            printf( "Problem in changing the size\n" );
        printf( "File length after:  %ld\n", filelength( fh ) );
        close( fh );
        }
    }


Output



    File length before: 0
    Size successfully changed
    File length after:  329678





_clear87
────────────────────────────────────────────────────────────────────────────


Description

Gets and clears the floating-point status word.

    #include <float.h>

    unsigned int _clear87( void );


Remarks

The _clear87 function gets and clears the floating-point status word. The
floating-point status word is a combination of the 8087/80287 status word
and other conditions detected by the 8087/80287 exception handler, such as
floating-point stack overflow and underflow.


Return Value

The bits in the value returned indicate the floating-point status. See the
FLOAT.H include file for a complete definition of the bits returned by
_clear87.

Many of the math library functions modify the 8087/80287 status word, with
unpredictable results. Return values from _clear87 and _status87 become more
reliable as fewer floating-point operations are performed between known
states of the floating-point status word.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_control87, _status87


Example

    /* CLEAR87.C: This program creates various floating-point problems,
    * then uses _clear87 to report on these problems.
    */

    #include <stdio.h>
    #include <float.h>

    void main()
    {
        double a = 1e-40, b;
        float x, y;

        printf( "Status: %.4x - clear\n", _clear87()  );

        /* Store into y is inexact and underflows: */
        y = a;
        printf( "Status: %.4x - inexact, underflow\n", _clear87() );

    /* y is denormal: */
        b = y;
        printf( "Status: %.4x - denormal\n", _clear87() );
    }


Output



    Status: 0000 - clear
    Status: 0030 - inexact, underflow
    Status: 0002 - denormal





clearerr
────────────────────────────────────────────────────────────────────────────


Description

Resets the error indicator for a stream.

    #include <stdio.h>

    void clearerr( FILE *stream );

stream                            Pointer to FILE structure


Remarks

The clearerr function resets the error indicator and end-of-file indicator
for stream. Error indicators are not automatically cleared; once the error
indicator for a specified stream is set, operations on that stream continue
to return an error value until clearerr, fseek, fsetpos, or rewind is
called.


Return Value

None.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

eof, feof, ferror, perror


Example

    /* CLEARERR.C: This program creates an error on the standard input
    * stream, then clears it so that future reads won't fail.
    */

    #include <stdio.h>

    void main()
    {
        int c;

        /* Create an error by writing to standard input. */
        putc( 'c', stdin );
        if( ferror( stdin ) )
        {
        perror( "Write error" );
        clearerr( stdin );
        }

    /* See if read causes an error. */
        printf( "Will input cause an error? " );
        c = getc( stdin );
        if( ferror( stdin ) )
        {
        perror( "Read error" );
        clearerr( stdin );
        }
    }


Output



    Write error: Error 0
    Will input cause an error? n





_clearscreen
────────────────────────────────────────────────────────────────────────────


Description

Clears the specified area of the screen.

    #include <graph.h>

    void _far _clearscreen( short area );

area                              Target area


Remarks

The _clearscreen function erases the target area, filling it with the
current background color. The area parameter can be one of the following
manifest constants (defined in GRAPH.H):

Constant                          Action
────────────────────────────────────────────────────────────────────────────
_GCLEARSCREEN                     Clears and fills the entire screen

_GVIEWPORT                        Clears and fills only within the current
                                    view port

_GWINDOW                          Clears and fills only within the current
                                    text window


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_getbkcolor,  _setbkcolor


Example

    /* CLRSCRN.C */
    #include <conio.h>
    #include <graph.h>
    #include <stdlib.h>

    void main()
    {
        short xhalf, yhalf, xquar, yquar;
        struct videoconfig vc;

    /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _getvideoconfig( &vc );

        xhalf = vc.numxpixels / 2;
        yhalf = vc.numypixels / 2;
        xquar = xhalf / 2;
        yquar = yhalf / 2;

        _setviewport( 0, 0, xhalf - 1, yhalf - 1 );
        _rectangle( _GBORDER, 0,  0, xhalf - 1, yhalf - 1 );
        _ellipse( _GFILLINTERIOR, xquar / 4, yquar / 4,
                            xhalf - (xquar / 4), yhalf - (yquar / 4) );
        getch();
        _clearscreen( _GVIEWPORT );

        getch();
        _setvideomode( _DEFAULTMODE );
    }





clock
────────────────────────────────────────────────────────────────────────────


Description

Calculates the time used by the calling process.

    #include <time.h>

    clock_t clock( void );


Remarks

The clock function tells how much processor time has been used by the
calling process. The time in seconds is approximated by dividing the clock
return value by the value of the CLOCKS_PER_SEC constant.

In other words, the clock function returns the number of processor timer
ticks that have elapsed. A timer tick is approximately equal to
1/CLOCKS_PER_SEC seconds.


Return Value

The clock function returns the product of the time in seconds and the value
of the CLOCKS_PER_SEC constant. If the processor time is not available, the
function returns the value -1, cast as clock_t.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX


In both DOS and OS/2, clock returns the time elapsed since the process
started. This may not be equal to the actual processor time used by the
process.

In previous versions of Microsoft C, the CLOCKS_PER_SEC constant was called
CLK_TCK.


See Also

difftime, time


Example

    /* CLOCK.C: This example prompts for how long the program is to run and
    * then continuously displays the elapsed time for that period.
    */

    #include <stdio.h>
    #include <stdlib.h>
    #include <time.h>

    void sleep( clock_t wait );

    void main()
    {
        long    i = 600000L;
        clock_t start, finish;
        double  duration;

        /* Delay for a specified time. */
        printf( "Delay for three seconds\n" );
        sleep( (clock_t)3 * CLOCKS_PER_SEC );
        printf( "Done!\n" );

        /* Measure the duration of an event. */
        printf( "Time to do %ld empty loops is ", i );
        start = clock();
        while( i-- )
        ;
        finish = clock();
        duration = (double)(finish - start) / CLOCKS_PER_SEC;
        printf( "%2.1f seconds\n", duration );
    }

    /* Pauses for a specified number of microseconds. */
    void sleep( clock_t wait )
    {
        clock_t goal;

        goal = wait + clock();
        while( goal > clock() )
            ;
    }


Output



    Delay for five seconds
    Done!
    Time to do 900000 empty loops is 2.0 seconds





close
────────────────────────────────────────────────────────────────────────────


Description

Closes a file.

#include <io.h>                   Required only for function declarations

#include <errno.h>

    int close( int handle );

handle                            Handle referring to open file


Remarks

The close function closes the file associated with handle.


Return Value

The close function returns 0 if the file was successfully closed. A return
value of -1 indicates an error, and errno is set to EBADF, indicating an
invalid file-handle argument.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

chsize, creat, dup, dup2, open, unlink


Example

    /* OPEN.C: This program uses open to open a file named OPEN.C for input
    * and a file named OPEN.OUT for output. The files are then closed.
    */

    #include <fcntl.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <io.h>
    #include <stdio.h>

    void main()
    {
        int fh1, fh2;
        fh1 = open( "OPEN.C", O_RDONLY );
        if( fh1 == -1 )
        perror( "open failed on input file" );
        else
        {
        printf( "open succeeded on input file\n" );
        close( fh1 );
        }

    fh2 = open( "OPEN.OUT", O_WRONLY | O_CREAT, S_IREAD | S_IWRITE );
        if( fh2 == -1 )
        perror( "open failed on output file" );
        else
        {
        printf( "open succeeded on output file\n" );
        close( fh2 );
        }
    }


Output



    open succeeded on input file
    open succeeded on output file





_control87
────────────────────────────────────────────────────────────────────────────


Description

Gets and sets the floating-point control word.

    #include <float.h>

    unsigned int _control87( unsigned int new, unsigned int mask );

new                               New control-word bit values

mask                              Mask for new control-word bits to set


Remarks

The _control87 function gets and sets the floating-point control word. The
floating-point control word allows the program to change the precision,
rounding, and infinity modes in the floating-point-math package.
Floating-point exceptions can also be masked or unmasked using the
_control87 function.

If the value for mask is equal to 0, then _control87 gets the floating-point
control word. If mask is nonzero, then a new value for the control word is
set in the following manner: for any bit that is on (equal to 1) in mask,
the corresponding bit in new is used to update the control word. To put it
another way,

    fpcntrl = ((fpcntrl & ~mask) | (new & mask))

where  fpcntrl  is the floating-point control word.

The possible values for the mask constant (mask) and new control values
(new) are shown in Table R.1.

Table   R.1 Hex Values

╓┌────────────┌──────────┌────────────────┌──────────────────────────────────╖
Mask         Hex Value  Constant         Hex Value
────────────────────────────────────────────────────────────────────────────
MCW_EM       0x003F
(Interrupt
exception)

                        EM_INVALID       0x0001

                        EM_DENORMAL      0x0002

                        EM_ZERODIVIDE    0x0004

                        EM_OVERFLOW      0x0008

                        EM_UNDERFLOW     0x0010

                        EM_INEXACT       0x0020



MCW_IC       0x1000
Mask         Hex Value  Constant         Hex Value
────────────────────────────────────────────────────────────────────────────
MCW_IC       0x1000
(Infinity
control)

                        IC_AFFINE        0x1000

                        IC_PROJECTIVE    0x0000



MCW_RC       0x0C00
(Rounding
control)

                        RC_CHOP          0x0C00

                        RC_UP            0x0800

                        RC_DOWN          0x0400
Mask         Hex Value  Constant         Hex Value
────────────────────────────────────────────────────────────────────────────
                        RC_DOWN          0x0400

                        RC_NEAR          0x0000



MCW_PC       0x0300
(Precision
control)

                        PC_24 (24 bits)  0x0000

                        PC_53 (53 bits)  0x0200

                        PC_64 (64 bits)  0x0300

────────────────────────────────────────────────────────────────────────────




Return Value

The bits in the value returned indicate the floating-point control state.
See the FLOAT.H include file for a complete definition of the bits returned
by _control87.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_clear87,  _status87


Example

    /* CNTRL87.C: This program uses _control87 to output the control word,
    * set the precision to 24 bits, and reset the status to the default.
    */

    #include <stdio.h>
    #include <float.h>

    void main()
    {
        double a = 0.1;

        /* Show original control word and do calculation. */
        printf( "Original: 0x%.4x\n", _control87( 0, 0 ) );
        printf( "%1.1f * %1.1f = %.15e\n", a, a, a * a );

        /* Set precision to 24 bits and recalculate. */
        printf( "24-bit:   0x%.4x\n", _control87( PC_24, MCW_PC ) );
        printf( "%1.1f * %1.1f = %.15e\n", a, a, a * a );

        /* Restore to default and recalculate. */
        printf( "Default:  0x%.4x\n", _control87( CW_DEFAULT, 0xffff ) );
        printf( "%1.1f * %1.1f = %.15e\n", a, a, a * a );
    }


Output



    Original: 0x1332
    0.1 * 0.1 = 1.000000000000000e-002
    24-bit:   0x1332
    0.1 * 0.1 = 9.999999776482582e-003
    Default:  0x1032
    0.1 * 0.1 = 1.000000000000000e-002





cos Functions
────────────────────────────────────────────────────────────────────────────


Description

Calculate the cosine (cos and cosl) or hyperbolic cosine (cosh and coshl).

    #include <math.h>

    double cos( double x );

    double cosh( double x );

    long double cosl( long double x );

    long double coshl( long double x );

x                                 Angle in radians


Remarks

The cos and cosh functions return the cosine and hyperbolic cosine,
respectively, of x.

The cosl and coshl functions are the 80-bit counterparts and use the 80-bit,
10-byte coprocessor form of arguments and return values. See the reference
page on the long double functions for more details on this data type.


Return Value

If x is large, a partial loss of significance in the result may occur in a
call to cos, in which case the function generates a PLOSS error. If x is so
large that significance is completely lost, cos prints a TLOSS message to
stderr and returns 0. In both cases, errno is set to ERANGE.

If the result is too large in a cosh call, the function returns HUGE_VAL and
sets errno to ERANGE.


Compatibility

cos, cosh

    ANSI   DOS   OS/2   UNIX   XENIX


cosl, coshl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

acos functions, asin functions, atan functions, matherr, sin functions, tan
functions


Example

    /* SINCOS.C: This program displays the sine, hyperbolic sine, cosine,
    * and hyperbolic cosine of pi / 2.
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double pi = 3.1415926535;
        double x, y;

        x = pi / 2;
        y = sin( x );
        printf( "sin( %f ) = %f\n", x, y );
        y = sinh( x );
        printf( "sinh( %f ) = %f\n",x, y );
        y = cos( x );
        printf( "cos( %f ) = %f\n", x, y );
        y = cosh( x );
        printf( "cosh( %f ) = %f\n",x, y );
    }


Output



    sin( 1.570796 ) = 1.000000
    sinh( 1.570796 ) = 2.301299
    cos( 1.570796 ) = 0.000000
    cosh( 1.570796 ) = 2.509178





cprintf
────────────────────────────────────────────────────────────────────────────


Description

Formats and prints to the console.

#include <conio.h>                Required only for function declarations

    int cprintf( char *format [[, argument]] ... );

format                            Format control string

argument                          Optional arguments


Remarks

The cprintf function formats and prints a series of characters and values
directly to the console, using the putch function to output characters. Each
argument (if any) is converted and output according to the corresponding
format specification in format. The format has the same form and function as
the format argument for the printf function; see printf for a description of
the format and arguments.

Note that unlike the fprintf, printf, and sprintf functions, cprintf does
not translate line-feed characters into carriage-return-line-feed
combinations on output.


Return Value

The cprintf function returns the number of characters printed.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

cscanf, fprintf, printf, sprintf, vprintf


Example

    /* CPRINTF.C: This program displays some variables to the console. */

    #include <conio.h>

    void main()
    {
        int      i = -16, h = 29;
        unsigned u = 62511;
        char     c = 'A';
        char     s[] = "Test";

    /* Note that console output does not translate \n as
        * standard output does. Use \r\n instead.
        */
        cprintf( "%d  %.4x  %u  %c %s\r\n", i, h, u, c, s );

    }


Output



    -16  001d  62511  A Test





cputs
────────────────────────────────────────────────────────────────────────────


Description

Puts a string to the console.

#include <conio.h>                Required only for function declarations

    int cputs( char *string );

string                            Output string


Remarks

The cputs function writes the null-terminated string pointed to by string
directly to the console. Note that a carriage-return-line-feed (CR-LF)
combination is not automatically appended to the string.


Return Value

If successful, cputs returns a 0. If the function fails, it returns a
nonzero value.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

putch


Example

    /* CPUTS.C: This program first displays a string to the console. */

    #include <conio.h>

    void main()
    {
        /* String to print at console. Note the \r (return) character. */
        char *buffer = "Hello world (courtesy of cputs)!\r\n";

        cputs( buffer );
    }


Output



    Hello world (courtesy of cputs)!





creat
────────────────────────────────────────────────────────────────────────────


Description

Creates a new file.

#include <sys\types.h>

#include <sys\stat.h>

#include <errno.h>

#include <io.h>                   Required only for function declarations

    int creat( char *filename, int pmode );

filename                          Path name of new file

pmode                             Permission setting


Remarks

The creat function either creates a new file or opens and truncates an
existing file. If the file specified by filename does not exist, a new file
is created with the given permission setting and is opened for writing. If
the file already exists and its permission setting allows writing, creat
truncates the file to length 0, destroying the previous contents, and opens
it for writing.

The permission setting, pmode, applies to newly created files only. The new
file receives the specified permission setting after it is closed for the
first time. The integer expression pmode contains one or both of the
manifest constants S_IWRITE and S_IREAD, defined in SYS\STAT.H. When both of
the constants are given, they are joined with the bitwise-OR operator ( | ).
The pmode argument is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
S_IWRITE                          Writing permitted

S_IREAD                           Reading permitted

S_IREAD | S_IWRITE                Reading and writing permitted

If write permission is not given, the file is read-only. Under DOS and OS/2,
it is not possible to give write-only permission. Thus, the S_IWRITE and
S_IREAD | S_IWRITE modes are equivalent. Under DOS versions 3.0 and later,
files opened using creat are always opened in compatibility mode (see
sopen).

The creat function applies the current file-permission mask to pmode before
setting the permissions (see umask).

Note that the creat routine is provided primarily for compatibility with
previous libraries. A call to open with O_CREAT and O_TRUNC in the oflag
argument is equivalent to creat and is preferable for new code.


Return Value

If successful, creat returns a handle for the created file. Otherwise, it
returns -1 and sets errno to one of the following constants:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Path name specifies an existing
                                    read-only file or specifies a directory
                                    instead of a file

EMFILE                            No more handles available (too many open
                                    files)

ENOENT                            Path name not found


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

chmod, chsize, close, dup, dup2, open, sopen, umask


Example

    /* CREAT.C: This program uses creat to create the file (or truncate the
    * existing file) named data and open it for writing.
    */

    #include <sys\types.h>
    #include <sys\stat.h>
    #include <io.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        int fh;

        fh = creat( "data", S_IREAD | S_IWRITE );
        if( fh == -1 )
        perror( "Couldn't create data file" );
        else
        {
        printf( "Created data file.\n" );
        close( fh );
        }
    }


Output



    Created data file.





cscanf
────────────────────────────────────────────────────────────────────────────


Description

Reads formatted data from the console.

#include <conio.h>                Required only for function declarations

    int cscanf( char *format [[, argument]] ... );

format                            Format-control string

argument                          Optional arguments


Remarks

The cscanf function reads data directly from the console into the locations
given by argument. The getche function is used to read characters. Each
optional argument must be a pointer to a variable with a type that
corresponds to a type specifier in format. The format controls the
interpretation of the input fields and has the same form and function as the
format argument for the scanf function; see scanf for a description of
format.

While cscanf normally echoes the input character, it will not do so if the
last call was to ungetch.


Return Value

The cscanf function returns the number of fields that were successfully
converted and assigned. The return value does not include fields that were
read but not assigned.

The return value is EOF for an attempt to read at end-of-file. This may
occur when keyboard input is redirected at the operating system command-line
level. A return value of 0 means that no fields were assigned.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

cprintf, fscanf, scanf, sscanf


Example

    /* CSCANF.C: This program prompts for a string and uses cscanf to read
    * in the response. Then cscanf returns the number of items matched,
    * and the program displays that number.
    */

    #include <stdio.h>
    #include <conio.h>

    void main()
    {
        int   result, i[3];

        cprintf( "Enter three integers: ");
        result = cscanf( "%i %i %i", &i[0], &i[1], &i[2] );
        cprintf( "\r\nYou entered " );
        while( result-- )
        cprintf( "%i ", i[result] );
        cprintf( "\r\n" );

    }


Output



    Enter three integers: 34 43 987k
    You entered 987 43 34





ctime
────────────────────────────────────────────────────────────────────────────


Description

Converts a time stored as a time_t value to a character string.

#include <time.h>                 Required only for function declarations

    char *ctime( const time_t *timer );

timer                             Pointer to stored time


Remarks

The ctime function converts a time stored as a time_t value to a character
string. The timer value is usually obtained from a call to time, which
returns the number of seconds elapsed since 00:00:00 Greenwich mean time,
January 1, 1970.

The string result produced by ctime contains exactly 26 characters and has
the form of the following example:

    Wed Jan 02 02:03:55 1980\n\0

A 24-hour clock is used. All fields have a constant width. The newline
character (\n) and the null character ('\0') occupy the last two positions
of the string.

Calls to the ctime function modify the single statically allocated buffer
used by the gmtime and the localtime functions. Each call to one of these
routines destroys the result of the previous call. The ctime function also
shares a static buffer with the asctime function. Thus, a call to ctime
destroys the results of any previous call to asctime, localtime, or gmtime.



Return Value

The ctime function returns a pointer to the character string result. If time
represents a date before 1980, ctime returns NULL.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

asctime, ftime, gmtime, localtime, time


Example

    /* ASCTIME.C: This program places the system time in the long integer
    aclock,
    * translates it into the structure newtime and then converts it to
    * string form for output, using the asctime function.
    */

    #include <time.h>
    #include <stdio.h>

    struct tm *newtime;
    time_t aclock;

    void main()
    {
        time( &aclock );                    /* Get time in seconds. */

        newtime = localtime( &aclock );     /* Convert time to struct tm form.
*/

        /* Print local time as a string. */
        printf( "The current date and time are: %s\n", asctime( newtime ) );
    }


Output



    The current date and time are: Thu Jun 15 06:57:59 1989





cwait
────────────────────────────────────────────────────────────────────────────


Description

Waits until the child process terminates.

    #include <process.h>

    int cwait( int *termstat, int procid, int action );

termstat                          Address for termination status code

procid                            Process ID of child

action                            Action code


Remarks

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

If not NULL, termstat points to a buffer where cwait will place the
termination-status word and the return code of the terminated child process.


The termination-status word indicates whether or not the child process
terminated normally by calling the OS/2 DosExit function. (Programs that
terminate with exit or by "falling off the end of main" use DosExit
internally.) If the process did terminate normally, the low-order and
high-order bytes of the termination-status word are as follows:

Byte                              Contents
────────────────────────────────────────────────────────────────────────────
High order                        Contains the low-order byte of the
                                    result code that the child code passed
                                    to DosExit. The DosExit function is
                                    called if the child process called exit
                                    or _exit, returned from main, or reached
                                    the end of main. The low-order byte of
                                    the result code is either the low-order
                                    byte of the argument to _exit or exit,
                                    the low-order byte of the return value
                                    from main, or a random value if the
                                    child process reached the end of main.

Low order                         0 (normal termination).

If the child process terminates without calling DosExit, the high-order and
low-order bytes of the termination-status word are as follows:

Byte                              Contents
────────────────────────────────────────────────────────────────────────────
High order                        0

Low order                         Termination code from DosCWait:

                                    Code        Meaning
────────────────────────────────────────────────────────────────────────────
                                    1           Hard-error abort

                                    2           Trap operation

                                    3           SIGTERM signal not
                                                intercepted

The procid argument specifies which child-process termination to wait for.
This value is returned by the call to the spawn function that started the
child process. If the specified child process terminates before cwait is
called, the function returns immediately.

The action argument specifies when the parent process resumes execution, as
shown in the following list:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
WAIT_CHILD                        The parent process waits until the
                                    specified child process has ended.

WAIT_GRANDCHILD                   The parent process waits until the
                                    specified child process and all child
                                    processes of that child process have
                                    ended.

The WAIT_CHILD and WAIT_GRANDCHILD action codes are defined in PROCESS.H.


Return Value

If the cwait function returns after normal termination of the child process,
it returns the child's process ID.

If the cwait function returns after abnormal termination of the child
process, it returns -1 and sets errno to EINTR.

Otherwise, the cwait function returns -1 immediately and sets errno to one
of the following error codes:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
ECHILD                            No child process exists, or invalid
                                    process ID

EINVAL                            Invalid action code


Compatibility

▼ ANSI  ▼ DOS   OS/2  ▼ UNIX  ▼ XENIX


Note that the OS/2 DosExit function allows programs to return a 16-bit
result code. However, the wait and cwait functions return only the low-order
byte of that result code.


See Also

exit, _exit, spawn functions, wait


Example

    /* CWAIT.C: This program launches several child processes and waits
    * for a specified process to finish.
    */

    #define INCL_NOPM
    #define INCL_NOCOMMON
    #define INCL_DOSPROCESS
    #include <os2.h>        /* DosSleep */
    #include <process.h>    /* cwait    */
    #include <stdlib.h>
    #include <stdio.h>
    #include <time.h>

    /* Macro to get a random integer within a specified range */
    #define getrandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) +
(min))

    struct  CHILD
    {
        int     pid;
        char    name[10];
    } child[4] = { { 0, "Ann" }, { 0, "Beth"  }, { 0, "Carl" }, { 0, "Dave" }
};

    void main( int argc, char *argv[] )
    {
        int     termstat, pid, c, tmp;

        srand( (unsigned)time( NULL ) );               /* Seed randomizer */
        /* If no arguments, this is the parent. */
        if( argc == 1 )
        {
            /* Spawn children in numeric order. */
            for( c = 0; c < 4; c++ )
                child[c].pid = spawnl( P_NOWAIT, argv[0], argv[0],
                                        child[c].name, NULL );

    /* Wait for randomly specified child, and respond when done. */
            c = getrandom( 0, 3 );
            printf( "Come here, %s\n", child[c].name );
            cwait( &termstat, child[c].pid, WAIT_CHILD );
            printf( "Thank you, %s\n", child[c].name );
        }

        /* If there are arguments, this must be a child. */
        else
        {
            /* Delay for a period determined by process number. */
            DosSleep( (argv[1][0] - 'A' + 1) * 1000L );
            printf( "Hi, dad. It's %s.\n", argv[1] );
        }
    }


Output



    Come here, Carl
    Hi, dad. It's Ann.
    Hi, dad. It's Beth.
    Hi, dad. It's Carl.
    Thank you, Carl
    Hi, dad. It's Dave.





dieeetomsbin, dmsbintoieee
────────────────────────────────────────────────────────────────────────────


Description

Convert between IEEE double value and Microsoft (MS) binary double value.

    #include <math.h>

    int dieeetomsbin( double *src8, double *dst8 );

    int dmsbintoieee( double *src8, double *dst8 );

src8                              Buffer containing value to convert

dst8                              Buffer to store converted value


Remarks

The dieeetomsbin routine converts a double-precision number in IEEE
(Institute of Electrical and Electronic Engineers) format to Microsoft (MS)
binary format. The routine dmsbintoieee converts a double-precision number
in MS binary format to IEEE format.

These routines allow C programs (which store floating-point numbers in the
IEEE format) to use numeric data in random-access data files created with
those versions of Microsoft BASIC that store floating-point numbers in MS
binary format, and vice versa.

The argument src8 is a pointer to the double value to be converted. The
result is stored at the location given by dst8.

These routines do not handle IEEE NANs ("not a number") and infinities. IEEE
denormals are treated as 0 in the conversions.


Return Value

These functions return 0 if the conversion is successful and 1 if the
conversion causes an overflow.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fieeetomsbin, fmsbintoieee





difftime
────────────────────────────────────────────────────────────────────────────


Description

Finds the difference between two times.

#include <time.h>                 Required only for function declarations

    double difftime( time_t timer1, time_t timer0 );

timer0                            Beginning time

timer1                            Ending time


Remarks

The difftime function computes the difference between the supplied time
values, timer0 and timer1.


Return Value

The difftime function returns, in seconds, the elapsed time from timer0 to
timer1. The value returned is a double-precision number.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

time


Example

    /* DIFFTIME.C: This program calculates the amount of time needed to
    * do a floating-point multiply 50000 times.
    */

    #include <stdio.h>
    #include <stdlib.h>
    #include <time.h>

    void main()
    {
        time_t   start, finish;
        unsigned loop;
        double   result, elapsed_time;

        printf( "This program will do a floating point multiply 50000 times\n"
);
        printf( "Working...\n" );

        time( &start );
        for( loop = 0; loop < 50000L; loop++ )
        result = 3.63 * 5.27;
        time( &finish );

    elapsed_time = difftime( finish, start );
        printf( "\nProgram takes %6.2f seconds.\n", elapsed_time );
    }


Output



    This program will do a floating point multiply 50000 times
    Working...

    Program takes   4.00 seconds.





_displaycursor
────────────────────────────────────────────────────────────────────────────


Description

Sets the cursor toggle for graphics functions.

    #include <graph.h>

    short _far _displaycursor( short toggle );

toggle                            Cursor state


Remarks

Upon entry into each graphic routine, the screen cursor is turned off. The
_displaycursor function determines whether the cursor will be turned back on
when programs exit graphic routines. If toggle is set to _GCURSORON, the
cursor will be restored on exit. If toggle is set to _GCURSOROFF, the cursor
will be left off.


Return Value

The function returns the previous value of toggle. There is no error return.



Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_gettextcursor, _settextcursor


Example

    /* DISCURS.C: This program changes the cursor shape using _gettextcursor
    * and _settextcursor, and hides the cursor using _displaycursor.
    */

    #include <conio.h>
    #include <graph.h>

    void main()
    {
        short oldcursor;
        short newcursor = 0x007;        /* Full block cursor */

        /* Save old cursor shape and make sure cursor is on */
        oldcursor = _gettextcursor();
        _clearscreen( _GCLEARSCREEN );
        _displaycursor( _GCURSORON );
        _outtext( "\nOld cursor shape: " );
        getch();

        /* Change cursor shape */
        _outtext( "\nNew cursor shape: " );
        _settextcursor( newcursor );
        getch();

    /* Restore original cursor shape */
        _outtext( "\n" );
        _settextcursor( oldcursor );
    }





div
────────────────────────────────────────────────────────────────────────────


Description

Computes the quotient and the remainder of two integer values.

    #include <stdlib.h>

    div_t div( int numer, int denom );

numer                             Numerator

denom                             Denominator


Remarks

The div function divides numer by denom, computing the quotient and the
remainder. The div_t structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
int quot                          Quotient

int rem                           Remainder

The sign of the quotient is the same as that of the mathematical quotient.
Its absolute value is the largest integer that is less than the absolute
value of the mathematical quotient. If the denominator is 0, the program
will terminate with an error message.


Return Value

The div function returns a structure of type div_t, comprising both the
quotient and the remainder. The structure is defined in STDLIB.H.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

ldiv


Example

    /* DIV.C: This example takes two integers as command-line arguments and
    * displays the results of the integer division. This program accepts
    * two arguments on the command line following the program name, then
    * calls div to divide the first argument by the second. Finally,
    * it prints the structure members quot and rem.
    */

    #include <stdlib.h>
    #include <stdio.h>
    #include <math.h>

    void main( int argc, char *argv[] )
    {
        int x,y;
        div_t div_result;

        x = atoi( argv[1] );
        y = atoi( argv[2] );

        printf( "x is %d, y is %d\n", x, y );
        div_result = div( x, y );
        printf( "The quotient is %d, and the remainder is %d\n",
                div_result.quot, div_result.rem );
    }


Output



    [C:\LIBREF] div 876 13
    x is 876, y is 13
    The quotient is 67, and the remainder is 5





_dos_allocmem
────────────────────────────────────────────────────────────────────────────


Description

Allocates a block of memory, using DOS service 0x48.

    #include <dos.h>

    #include <errno.h>

    unsigned _dos_allocmem( unsigned size, unsigned *seg );

size                              Block size to allocate

seg                               Return buffer for segment descriptor


Remarks

The _dos_allocmem function uses DOS service 0x48 to allocate a block of
memory size paragraphs long. (A paragraph is 16 bytes.) Allocated blocks are
always paragraph aligned. The segment descriptor for the initial segment of
the new block is returned in the word that seg points to. If the request
cannot be satisfied, the maximum possible size (in paragraphs) is returned
in this word instead.


Return Value

If successful, the _dos_allocmem returns 0. Otherwise, it returns the DOS
error code and sets errno to ENOMEM, indicating insufficient memory or
invalid arena (memory area) headers.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

alloca, calloc functions, _dos_freemem, _dos_setblock, halloc, malloc
functions


Example

    /* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases
    * the allocation to 40 paragraphs, and then frees the memory space.
    */

    #include <dos.h>
    #include <stdio.h>

    void main()
    {
        unsigned segment;
        unsigned maxsize;

    /* Allocate 20 paragraphs */
        if( _dos_allocmem( 20, &segment ) != 0 )
        printf( "allocation failed\n" );
        else
        printf( "allocation successful\n" );

        /* Increase allocation to 40 paragraphs */
        if( _dos_setblock( 40, segment, &maxsize ) != 0 )
        printf( "allocation increase failed\n" );
        else
        printf( "allocation increase successful\n" );

        /* free memory */
        if( _dos_freemem( segment ) != 0 )
        printf( "free memory failed\n" );
        else
        printf( "free memory successful\n" );
    }


Output



    allocation successful
    allocation increase successful
    free memory successful





_dos_close
────────────────────────────────────────────────────────────────────────────


Description

Closes a file using system call INT 0x3E.

#include <dos.h>

#include <errno.h>

    unsigned _dos_close( int handle );

handle                            Target file handle


Remarks

The _dos_close function uses system call 0x3E to close the file indicated by
handle. The file's handle argument is returned by the call that created or
last opened the file.


Return Value

The function returns 0 if successful. Otherwise, it returns the DOS error
code and sets errno to EBADF, indicating an invalid file handle.

Do not use the DOS interface I/O routines with the console, low-level, or
stream I/O routines.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

close, creat,  _dos_creat functions,  _dos_open,  _dos_read,  _dos_write,
dup, open


Example

    /* DOPEN.C: This program uses DOS I/O functions to open and close a file.
    */

    #include <fcntl.h>
    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        int fh;

        /* Open file with _dos_open function */
        if( _dos_open( "data1", O_RDONLY, &fh ) != 0 )
        perror( "Open failed on input file\n" );
        else
        printf( "Open succeeded on input file\n" );

    /* Close file with _dos_close function */
        if( _dos_close( fh ) != 0 )
        perror( "Close failed\n" );
        else
        printf( "File successfully closed\n" );
    }


Output



    Open succeeded on input file
    File successfully closed





_dos_creat Functions
────────────────────────────────────────────────────────────────────────────


Description

Create a new file.

#include <dos.h>

#include <errno.h>

    unsigned _dos_creat( char *filename, unsigned attrib, int *handle );

    unsigned _dos_creatnew( char *filename, unsigned attrib, int *handle );

filename                          File path name

attrib                            File attributes

handle                            Handle return buffer


Remarks

The _dos_creat and _dos_creatnew routines create and open a new file named
filename; this new file has the access attributes specified in the attrib
argument. The new file's handle is copied into the integer location pointed
to by handle. The file is opened for both read and write access. If file
sharing is installed, the file is opened in compatibility mode.

The _dos_creat routine uses system call INT 0x3C, and the _dos_creatnew
routine uses system call INT 0x5B. If the file already exists, _dos_creat
erases its contents and leaves its attributes unchanged; however, the
_dos_creatnew routine fails if the file already exists.


Return Value

If successful, both routines return 0. Otherwise, they return the DOS error
code and set errno to one of the following values:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Access denied because the directory is
                                    full or, for _dos_creat only, the file
                                    exists and cannot be overwritten

EEXIST                            File already exists (_dos_creatnew only)

EMFILE                            Too many open file handles

ENOENT                            Path or file not found


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* DCREAT.C: This program creates a file using the _dos_creat function.
    The
    * program cannot create a new file using the _dos_creatnew function
    * because it already exists.
    */

    #include <stdio.h>
    #include <stdlib.h>
    #include <dos.h>

    void main()
    {
        int fh1, fh2;
        int result;

        if( _dos_creat( "data", _A_NORMAL, &fh1 ) != 0 )
        printf( "Couldn't create data file\n" );
        else
        {
        printf( "Created data file.\n" );

        /* If _dos_creat is successful, the _dos_creatnew call
            * will fail since the file exists
            */
        if( _dos_creatnew( "data", _A_RDONLY, &fh2 ) != 0 )
            printf( "Couldn't create data file\n" );
        else
        {
            printf( "Created data file.\n" );
            _dos_close( fh2 );
        }
        _dos_close( fh1 );
        }
    }


Output



    Created data file.
    Couldn't create data file





_dos_find Functions
────────────────────────────────────────────────────────────────────────────


Description

Find the file with the specified attributes or find the next file with the
specified attributes.

    #include <dos.h>

    #include <errno.h>

    unsigned _dos_findfirst( char *filename, unsigned attrib, struct find_t
    *fileinfo );

    unsigned _dos_findnext( struct find_t *fileinfo );

filename                          Target file name

attrib                            Target attributes

fileinfo                          File-information buffer


Remarks

The _dos_findfirst routine uses system call INT 0x4E to return information
about the first instance of a file whose name and attributes match filename
and attrib.

The filename argument may use wildcards (* and ?). The attrib argument can
be any of the following manifest constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_A_ARCH                           Archive. Set whenever the file is
                                    changed, and cleared by the DOS BACKUP
                                    command.

_A_HIDDEN                         Hidden file. Cannot be found with the
                                    DOS DIR command. Returns information
                                    about normal files as well as about
                                    files with this attribute.

_A_NORMAL                         Normal. File can be read or written
                                    without restriction.

_A_RDONLY                         Read-only. File cannot be opened for
                                    writing, and a file with the same name
                                    cannot be created. Returns information
                                    about normal files as well as about
                                    files with this attribute.

_A_SUBDIR                         Subdirectory. Returns information about
                                    normal files as well as about files with
                                    this attribute.

_A_SYSTEM                         System file. Cannot be found with the
                                    DOS DIR command. Returns information
                                    about normal files as well as about
                                    files with this attribute.

_A_VOLID                          Volume ID. Only one file can have this
                                    attribute, and it must be in the root
                                    directory.

Multiple constants can be combined (with the OR operator), using the
vertical-bar ( | ) character.

If the attributes argument to either of these functions is _A_RDONLY,
_A_HIDDEN, _A_SYSTEM, or _A_SUBDIR, the function also returns any normal
attribute files that match the filename argument. That is, a normal file
does not have a read-only, hidden, system, or directory attribute.

Information is returned in a find_t structure, defined in DOS.H. The find_t
structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
char reserved[21]                 Reserved for use by DOS

char attrib                       Attribute byte for matched path

unsigned wr_time                  Time of last write to file

unsigned wr_date                  Date of last write to file

long size                         Length of file in bytes

char name[13]                     Null-terminated name of matched
                                    file/directory, without
                                    the path

The formats for the wr_time and wr_date elements are in DOS format and are
not usable by any other C run-time function. The time format is shown below:


Bits                              Contents
────────────────────────────────────────────────────────────────────────────
0 - 4                             Number of 2-second increments (0 - 29)

5 -10                             Minutes (0 - 59)

11-15                             Hours (0 - 23)

The date format is shown below:

Bits                              Contents
────────────────────────────────────────────────────────────────────────────
0 - 4                             Day of month (1-31)

5 - 8                             Month (1-12)

9 -15                             Year (relative to 1980)

Do not alter the contents of the buffer between a call to _dos_findfirst and
a subsequent call to the _dos_findnext function. Also, the buffer should not
be altered between calls to _dos_findnext.

The _dos_findnext routine uses system call 0x4F to find the next name, if
any, that matches the filename and attrib arguments specified in a prior
call to _dos_findfirst. The fileinfo argument must point to a structure
initialized by a previous call to _dos_findfirst. The contents of the
structure will be altered as described above if a match is found.


Return Value

If successful, both functions return 0. Otherwise, they return the DOS error
code and set errno to ENOENT, indicating that  filename could not be
matched.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



Example

    /* DFIND.C: This program finds and prints all files in the current
    directory with
    * the .c extension.
    */

    #include <stdio.h>
    #include <dos.h>

    main()
    {
        struct find_t  c_file;

        /* find first .c file in current directory */
        _dos_findfirst( "*.c", _A_NORMAL, &c_file );

        printf( "Listing of .c files\n\n" );
        printf( "File: %s is %ld bytes\n", c_file.name, c_file.size );

        /* find the rest of the .c files */
        while( _dos_findnext( &c_file ) == 0 )
        printf( "File: %s is %ld bytes\n", c_file.name, c_file.size );
    }


Output



    Listing of .c files

    File: CHDIR.C is 524 bytes
    File: SIGFP.C is 2674 bytes
    File: MAX.C is 258 bytes
    File: CGETS.C is 577 bytes
    File: FWRITE.C is 1123 bytes





_dos_freemem
────────────────────────────────────────────────────────────────────────────


Description

Releases a block of memory (INT 0x49).

    #include <dos.h>

    #include <errno.h>

    unsigned _dos_freemem( unsigned seg );

seg                               Block to be released


Remarks

The _dos_freemem function uses system call 0x49 to release a block of memory
previously allocated by _dos_allocmem. The seg argument is a value returned
by a previous call to _dos_allocmem. The freed memory may no longer be used
by the application program.


Return Value

If successful, _dos_freemem returns 0. Otherwise, it returns the DOS error
code and sets errno to ENOMEM, indicating a bad segment value (one that does
not correspond to a segment returned by a previous _dos_allocmem call) or
invalid arena headers.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_allocmem,  _dos_setblock, free functions


Example

    /* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases
    * the allocation to 40 paragraphs, and then frees the memory space.
    */

    #include <dos.h>
    #include <stdio.h>

    void main()
    {
        unsigned segment;
        unsigned maxsize;

        /* Allocate 20 paragraphs */
        if( _dos_allocmem( 20, &segment ) != 0 )
        printf( "allocation failed\n" );
        else
        printf( "allocation successful\n" );

    /* Increase allocation to 40 paragraphs */
        if( _dos_setblock( 40, segment, &maxsize ) != 0 )
        printf( "allocation increase failed\n" );
        else
        printf( "allocation increase successful\n" );

        /* Free memory */
        if( _dos_freemem( segment ) != 0 )
        printf( "free memory failed\n" );
        else
        printf( "free memory successful\n" );
    }


Output



    allocation successful
    allocation increase successful
    free memory successful





_dos_getdate
────────────────────────────────────────────────────────────────────────────


Description

Gets current system date using system call INT 0x2A.

    #include <dos.h>

    void _dos_getdate( struct dosdate_t *date );

date                              Current system date


Remarks

The _dos_getdate routine uses system call 0x2A to obtain the current system
date. The date is returned in a dosdate_t structure, defined in DOS.H.

The dosdate_t structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
unsigned char day                 1-31

unsigned char month               1-12

unsigned int year                 1980 - 2099

unsigned char dayofweek           0 - 6 (0 = Sunday)


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_gettime,  _dos_setdate,  _dos_settime, gmtime, localtime, mktime,
_strdate, _strtime, time


Example

    /* DGTIME.C: This program gets and displays current date and time values.
    */

    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        struct dosdate_t date;
        struct dostime_t time;

    /* Get current date and time values */

        _dos_getdate( &date );
        _dos_gettime( &time );

        printf( "Today's date is %d-%d-%d\n", date.month, date.day, date.year
);
        printf( "The time is %02d:%02d\n", time.hour, time.minute );
    }


Output



    Today's date is 6-15-1989
    The time is 18:07





_dos_getdiskfree
────────────────────────────────────────────────────────────────────────────


Description

Gets disk information using system call INT 0x36.

    #include <dos.h>

    #include <errno.h>

    unsigned _dos_getdiskfree( unsigned drive, struct diskfree_t *diskspace );

drive                             Drive number (default is 0)

diskspace                         Buffer to hold disk information


Remarks

The _dos_getdiskfree routine uses system call 0x36 to obtain information on
the disk drive specified by drive. The default drive is 0, drive A is 1,
drive B is 2, and so on. Information is returned in the diskfree_t structure
(defined in DOS.H) pointed to by diskspace.

The struct diskfree_t structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
unsigned total_clusters           Total clusters on disk

unsigned avail_clusters           Available clusters on disk

unsigned sectors_per_cluster      Sectors per cluster

unsigned bytes_per_sector         Bytes per sector


Return Value

If successful, the function returns 0. Otherwise, it returns a nonzero value
and sets errno to EINVAL, indicating that an invalid drive was specified.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getdrive, _dos_setdrive


Example

    /* DGDISKFR.C: This program displays information about the default disk
    drive. */

    #include <stdio.h>
    #include <dos.h>

    main()
    {
        struct diskfree_t drive;

        /* Get information on default disk drive 0 */

        _dos_getdiskfree( 0, &drive );
        printf( "total clusters: %d\n", drive.total_clusters );
        printf( "available clusters: %d\n", drive.avail_clusters );
        printf( "sectors per cluster: %d\n", drive.sectors_per_cluster );
        printf( "bytes per sector: %d\n", drive.bytes_per_sector );
    }


Output



    total clusters: 9013
    available clusters: 6030
    sectors per cluster: 4
    bytes per sector: 512





_dos_getdrive
────────────────────────────────────────────────────────────────────────────


Description

Gets the current disk drive using system call INT 0x19.

    #include <dos.h>

    void _dos_getdrive( unsigned *drive );

drive                             Current-drive return buffer


Remarks

The _dos_getdrive routine uses system call 0x19 to obtain the current disk
drive. The current drive is returned in the word that drive points to: 1 =
drive A, 2 = drive B, and so on.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getdiskfree,  _dos_setdrive,  _getdrive


Example

    /* DGDRIVE.C: This program prints the letter of the current drive,
    * changes the default drive to A, then returns the number of disk drives.
    */

    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        unsigned olddrive, newdrive;
        unsigned number_of_drives;

        /* Print current default drive information */
        _dos_getdrive( &olddrive );
        printf( "The current drive is: %c\n", 'A' + olddrive1 );

        /* Set default drive to be drive A */
        printf( "Changing default drive to A\n");
        _dos_setdrive( 1, &number_of_drives );

        /* Get new default drive information and total number of drives */
        _dos_getdrive( &newdrive );
        printf( "The current drive is: %c\n", 'A' + newdrive1 );
        printf( "Number of logical drives: %d\n", number_of_drives );

    /* Restore default drive */
        _dos_setdrive( olddrive, &number_of_drives );
    }


Output



    The current drive is: C
    Changing default drive to A
    The current drive is: A
    Number of logical drives: 26





_dos_getfileattr
────────────────────────────────────────────────────────────────────────────


Description

Gets the current attributes of a file or directory, using system call INT
0x43.

    #include <dos.h>

    #include <errno.h>

    unsigned _dos_getfileattr( char *pathname, unsigned *attrib );

pathname                          Full path of target file/directory

attrib                            Word to store attributes in


Remarks

The _dos_getfileattr routine uses system call 0x43 to obtain the current
attributes of the file or directory pointed to by pathname . The attributes
are copied to the low-order byte of the attrib word. Attributes are
represented by manifest constants, as described below:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_A_ARCH                           Archive. Set whenever the file is
                                    changed, or cleared by the DOS BACKUP
                                    command.

_A_HIDDEN                         Hidden file. Cannot be found by a
                                    directory search.

_A_NORMAL                         Normal. File can be read or written
                                    without restriction.

_A_RDONLY                         Read-only. File cannot be opened for a
                                    write, and a file with the same name
                                    cannot be created.

_A_SUBDIR                         Subdirectory.

_A_SYSTEM                         System file. Cannot be found by a
                                    directory search.

_A_VOLID                          Volume ID. Only one file can have this
                                    attribute, and it must be in the root
                                    directory.




Return Value

If successful, the function returns 0. Otherwise, it returns the DOS error
code and sets errno to ENOENT, indicating that the target file or directory
could be found.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

access, chmod, _dos_setfileattr, umask


Example

    /* DGFILEAT.C: This program creates a file with the specified attributes,
    * then prints this information before changing the file attributes back
    * to normal.
    */

    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        unsigned oldattrib, newattrib;
        int fh;

        /* Get and display file attribute */
        _dos_getfileattr( "DGFILEAT.C", &oldattrib );
        printf( "Attribute: 0x%.4x\n", oldattrib );
        if( ( oldattrib & _A_RDONLY ) != 0 )
        printf( "Read only file\n" );
        else
        printf( "Not a read only file.\n" );

        /* Reset file attribute to normal file */
        _dos_setfileattr( "DGFILEAT.C", _A_RDONLY );
        _dos_getfileattr( "DGFILEAT.C", &newattrib );
        printf( "Attribute: 0x%.4x\n", newattrib );

        /* Restore file attribute */
        _dos_setfileattr( "DGFILEAT.C", oldattrib );
        _dos_getfileattr( "DGFILEAT.C", &newattrib );
        printf( "Attribute: 0x%.4x\n", newattrib );
    }


Output



    Attribute: 0x0020
    Not a read only file.
    Attribute: 0x0001
    Attribute: 0x0020





_dos_getftime
────────────────────────────────────────────────────────────────────────────


Description

Gets the date and time a file was last written, using system call INT 0x57.


    #include <dos.h>

    #include <errno.h>

    unsigned _dos_getftime( int handle, unsigned *date, unsigned *time );

handle                            Target file

date                              Date-return buffer

time                              Time-return buffer


Remarks

The _dos_getftime routine uses system call 0x57 to get the date and time
that the specified file was last written. The file must have been opened
with a call to _dos_open or _dos_creat prior to calling _dos_getftime. The
date and time are returned in the words pointed to by date and time. The
values appear in the DOS date and time format:

Time Bits                         Meaning
────────────────────────────────────────────────────────────────────────────
0 - 4                             Number of 2-second increments (0 -29)

5 -10                             Minutes (0 -59)

11-15                             Hours (0 -23)

Date Bits                         Meaning
────────────────────────────────────────────────────────────────────────────
0 - 4                             Day (1-31)

5 - 8                             Month (1-12)

9 -15                             Year (1980 -2099)


Return Value

If successful, the function returns 0. Otherwise, it returns the DOS error
code and sets errno to EBADF, indicating that an invalid file handle was
passed.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_setftime, fstat, stat


Example

    /* DGFTIME.C: This program displays and modifies the date and time
    * fields of a file.
    */

    #include <fcntl.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <dos.h>

    void main()
    {
                                    /* FEDC BA98 7654 3210          */
        unsigned new_date = 0x184f;   /* 0001 1000 0100 1111  2/15/92 */
        unsigned new_time = 0x48e0;   /* 0100 1000 1110 0000  9:07 AM */
        unsigned old_date, old_time;

        int fh;

        /* Open file with _dos_open function */
        if( _dos_open( "dgftime.obj", O_RDONLY, &fh ) != 0 )
        exit( 1 );

        /* Get file date and time */
        _dos_getftime( fh, &old_date, &old_time );
        printf( "Old date field: 0x%.4x\n", old_date );
        printf( "Old time field: 0x%.4x\n", old_time );
        system( "dir dgftime.obj" );

        /* Modify file date and time */
        if( !_dos_setftime( fh, new_date, new_time ) )
        {
        _dos_getftime( fh, &new_date, &new_time );
        printf( "New date field: 0x%.4x\n", new_date );
        printf( "New time field: 0x%.4x\n", new_time );
        system( "dir dgftime.obj" );

        /* Restore date and time */
        _dos_setftime( fh, old_date, old_time );
        }
        _dos_close( fh );
    }


Output



    Old date field: 0x12cf
    Old time field: 0x94bb

    Volume in drive C is OS2
    Directory of  C:\LIBREF

    DGFTIME  OBJ     3923   6-15-89   6:37p
            1 File(s)  13676544 bytes free

    New date field: 0x184f
    New time field: 0x48e0

    Volume in drive C is OS2
    Directory of  C:\LIBREF

    DGFTIME  OBJ     3923   2-15-92   9:07a
            1 File(s)  13676544 bytes free





_dos_gettime
────────────────────────────────────────────────────────────────────────────


Description

Gets the current system time, using system call INT 0x2C.

    #include <dos.h>

    void _dos_gettime( struct dostime_t *time );

time                              Current system time


Remarks

The _dos_gettime routine uses system call 0x2C to obtain the current system
time. The time is returned in a dostime_t structure, defined in DOS.H.

The dostime_t structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
unsigned char hour                0 -23

unsigned char minute              0 -59

unsigned char second              0 -59

unsigned char hsecond             1/100 second; 0 -99


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getdate,  _dos_setdate,  _dos_settime, gmtime, localtime,  _strtime


Example

    /* DGTIME.C: This program gets and displays current date and time values.
    */

    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        struct dosdate_t date;
        struct dostime_t time;

    /* Get current date and time values */

        _dos_getdate( &date );
        _dos_gettime( &time );

        printf( "Today's date is %d-%d-%d\n", date.month, date.day, date.year
);
        printf( "The time is %02d:%02d\n", time.hour, time.minute );
    }


Output



    Today's date is 6-15-1989
    The time is 18:07





_dos_getvect
────────────────────────────────────────────────────────────────────────────


Description

Gets the current value of the interrupt vector, using system call INT 0x35.


    #include <dos.h>

    void ( _interrupt _far *_dos_getvect( unsigned intnum))();

intnum                            Target interrupt vector


Remarks

The _dos_getvect routine uses system call INT 0x35 to get the current value
of the interrupt vector specified by intnum.

This routine is typically used in conjunction with the _dos_setvect
function. To replace an interrupt vector, first save the current vector of
the interrupt using _dos_getvect. Then set the vector to your own interrupt
routine with _dos_setvect. The saved vector can later be restored, if
necessary, using _dos_setvect. The user-defined routine may also need the
original vector in order to call that vector or chain to it with
_chain_intr.


Return Value

The function returns a far pointer for the intnum interrupt to the current
handler, if there is one.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_chain_intr,  _dos_keep,  _dos_setvect





_dos_keep
────────────────────────────────────────────────────────────────────────────


Description

Installs TSR (terminate-and-stay-resident) programs in memory, using system
call INT 0x31.

    #include <dos.h>

    void _dos_keep( unsigned retcode, unsigned memsize );

retcode                           Exit status code

memsize                           Allocated resident memory (in 16-byte
                                    paragraphs)


Remarks

The _dos_keep routine installs TSRs (terminate-and-stay-resident programs)
in memory, using system call INT 0x31.

The routine first exits the calling process, leaving it in memory. It then
returns the low-order byte of retcode to the parent of the calling process.
Before returning execution to the parent process, _dos_keep sets the
allocated memory for the now-resident process to memsize 16-byte paragraphs.
Any excess memory is returned to the system.

The _dos_keep function calls the same internal routines called by exit. It
therefore takes the following actions:


    ■   Calls atexit and onexit if defined.

    ■   Flushes all file buffers.

    ■   Restores interrupt vectors replaced by the C start-up code. The
        primary one is interrupt 0 (divide by zero). If the emulator math
        library is used and there is no coprocessor, interrupts 0x34 through
        0x3D are restored. If there is a coprocessor, interrupt 2 is restored.


The _dos_keep function does not automatically close files; you should do
this specifically unless you want files opened by the TSR installation code
to remain open for the TSR.

Do not use the emulator math library in TSRs unless you are familiar with
the C start-up code and the coprocessor. Use the alternate math package (not
supplied with Microsoft QuickC) if the TSR must do floating-point math.

Do not run programs that use _dos_keep from inside the Microsoft
Programmer's WorkBench environment, since doing so causes subsequent memory
problems. The _dos_keep function terminates the program when executed in the
Programmer's WorkBench environment.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_cexit,  _chain_intr,  _dos_getvect,  _dos_setvect,  _exit





_dos_open
────────────────────────────────────────────────────────────────────────────


Description

Opens a file, using system call INT 0x3D.

#include <dos.h>

#include <errno.h>

#include <fcntl.h>                Access mode constants

#include <share.h>                Sharing mode constants

    unsigned _dos_open( char *filename, unsigned mode, int *handle );

filename                          Path to an existing file

mode                              Permissions

handle                            Pointer to integer


Remarks

The _dos_open routine uses system call INT 0x3D to open the existing file
pointed to by filename. The handle for the opened file is copied into the
integer pointed to by handle. The mode argument specifies the file's access,
sharing, and inheritance modes by combining (with the OR operator) manifest
constants from the three groups shown below. At most, one access mode and
one sharing mode can be specified at a time.

╓┌─────────────┌────────────────────────────────┌────────────────────────────►
Constant      Mode                             Meaning
─────────────────────────────────────────────────────────────────────────────
O_RDONLY      Access                           Read-only
Constant      Mode                             Meaning
─────────────────────────────────────────────────────────────────────────────
O_RDONLY      Access                           Read-only

O_WRONLY      Access                           Write-only

O_RDWR        Access                           Both read and write

SH_COMPAT     Sharing                          Compatibility

SH_DENYRW     Sharing                          Deny reading and writing

SH_DENYWR     Sharing                          Deny writing

SH_DENYRD     Sharing                          Deny reading

SH_DENYNO     Sharing                          Deny neither

O_NOINHERIT   Inheritance by the child         File is not inherited
                process

Constant      Mode                             Meaning
─────────────────────────────────────────────────────────────────────────────



Do not use the DOS interface I/O routines in conjunction with the console,
low-level, or stream I/O routines.


Return Value

If successful, the function returns 0. Otherwise, it returns the DOS error
code and sets errno to one of the following manifest constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Access denied (possible reasons include
                                    specifying a directory or volume ID for
                                    filename, or opening a read-only file
                                    for write access)

EINVAL                            Sharing mode specified when file sharing
                                    not installed, or
                                    access-mode value is invalid

EMFILE                            Too many open file handles

ENOENT                            Path or file not found


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_close,  _dos_read,  _dos_write


Example

    /* DOPEN.C: This program uses DOS I/O functions to open and close a file.
    */

    #include <fcntl.h>
    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        int fh;

        /* Open file with _dos_open function */
        if( _dos_open( "data1", O_RDONLY, &fh ) != 0 )
        perror( "Open failed on input file\n" );
        else
        printf( "Open succeeded on input file\n" );

        /* Close file with _dos_close function */
        if( _dos_close( fh ) != 0 )
        perror( "Close failed\n" );
        else
        printf( "File successfully closed\n" );
    }


Output



    Open succeeded on input file
    File successfully closed





_dos_read
────────────────────────────────────────────────────────────────────────────


Description

Reads data from a file, using system call INT 0x3F.

    #include <dos.h>

    unsigned _dos_read( int handle, void _far *buffer, unsigned count,
    unsigned *numread );

handle                            File to read

buffer                            Buffer to write to

count                             Number of bytes to read

numread                           Number of bytes actually read


Remarks

The _dos_read routine uses system call INT 0x3F to read count bytes of data
from the file specified by handle. The routine then copies the data to the
buffer pointed to by buffer. The integer pointed to by numread will show the
number of bytes actually read, which may be less than the number requested
in count. If the number of bytes actually read is 0, it means the routine
tried to read at end-of-file.

Do not use the DOS interface I/O routines in conjunction with the console,
low-level, or stream I/O routines.


Return Value

If successful, the function returns 0. Otherwise, it returns the DOS error
code and sets errno to one of the following constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Access denied (handle is not open for
                                    read access)

EBADF                             File handle is invalid


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_close,  _dos_open,  _dos_write, read


Example

    /* DREAD.C: This program uses the DOS I/O operations to read the contents
    * of a file.
    */

    #include <fcntl.h>
    #include <stdlib.h>
    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        int fh;
        char buffer[50];
        unsigned number_read;

        /* Open file with _dos_open function */
        if( _dos_open( "dread.c", O_RDONLY, &fh ) != 0 )
        perror( "Open failed on input file\n" );
        else
        printf( "Open succeeded on input file\n" );

        /* Read data with _dos_read function */
        _dos_read( fh, buffer, 50, &number_read );
        printf( "First 40 characters are: %.40s\n\n", buffer );

        /* Close file with _dos_close function */
        _dos_close( fh );
    }


Output



    Open succeeded on input file
    First 40 characters are: /* DREAD.C: This program uses the DOS I/





_dos_setblock
────────────────────────────────────────────────────────────────────────────


Description

Changes the size of a memory segment, using system call INT 0x4A.

    #include <dos.h>

    unsigned _dos_setblock( unsigned size, unsigned seg, unsigned *maxsize );

size                              New segment size

seg                               Target segment

maxsize                           Maximum-size buffer


Remarks

The _dos_setblock routine uses system call INT 0x4A to change the size of
seg, previously allocated by _dos_allocmem, to size paragraphs. If the
request cannot be satisfied, the maximum possible segment size is copied to
the buffer pointed to by maxsize.


Return Value

The function returns 0 if successful. If the call fails, it returns the DOS
error code and sets errno to ENOMEM, indicating a bad segment value was
passed. A bad segment value is one that does not correspond to a segment
returned from a previous _dos_allocmem call, or one that contains invalid
arena headers.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_allocmem,  _dos_freemem, realloc functions


Example

    /* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases
    * the allocation to 40 paragraphs, and then frees the memory space.
    */

    #include <dos.h>
    #include <stdio.h>

    void main()
    {
        unsigned segment;
        unsigned maxsize;

    /* Allocate 20 paragraphs */
        if( _dos_allocmem( 20, &segment ) != 0 )
        printf( "allocation failed\n" );
        else
        printf( "allocation successful\n" );

        /* Increase allocation to 40 paragraphs */
        if( _dos_setblock( 40, segment, &maxsize ) != 0 )
        printf( "allocation increase failed\n" );
        else
        printf( "allocation increase successful\n" );

        /* Free memory */
        if( _dos_freemem( segment ) != 0 )
        printf( "free memory failed\n" );
        else
        printf( "free memory successful\n" );
    }


Output



    allocation successful
    allocation increase successful
    free memory successful





_dos_setdate
────────────────────────────────────────────────────────────────────────────


Description

Sets the current system date, using system call INT 0x2B.

    #include <dos.h>

    unsigned _dos_setdate( struct dosdate_t *date );

date                              New system date


Remarks

The _dos_setdate routine uses system call INT 0x2B to set the current system
date. The date is stored in the dosdate_t structure pointed to by date,
defined in DOS.H. The dosdate_t structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
unsigned char day                 1 -31

unsigned char month               1 -12

unsigned int year                 1980 - 2099

unsigned char dayofweek           0 - 6 (0 = Sunday)


Return Value

If successful, the function returns 0. Otherwise, it returns a nonzero value
and sets errno to EINVAL, indicating an invalid date was specified.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_gettime,  _dos_setdate,  _dos_settime, gmtime, localtime, mktime,
_strdate, _strtime, time


Example

    /* DSTIME.C: This program changes the time and date values and displays
    the
    * new date and time values.
    */

    #include <dos.h>
    #include <conio.h>
    #include <stdio.h>
    #include <time.h>

    void main()
    {
        struct dosdate_t olddate, newdate = { { 4 }, { 7 }, { 1984 } };
        struct dostime_t oldtime, newtime = { { 3 }, { 45 }, { 30 }, { 0 } };
        char   datebuf[40], timebuf[40];

        /* Get current date and time values */
        _dos_getdate( &olddate );
        _dos_gettime( &oldtime );
        printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );

        /* Modify date and time structures */
        _dos_setdate( &newdate );
        _dos_settime( &newtime );
        printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );

        /* Restore old date and time */
        _dos_setdate( &olddate );
        _dos_settime( &oldtime );
    }


Output



    06/15/89    18:26:09
    07/04/84    03:45:30





_dos_setdrive
────────────────────────────────────────────────────────────────────────────


Description

Sets the default drive, using system call INT 0x0E.

    #include <dos.h>

    void _dos_setdrive( unsigned drive, unsigned *numdrives );

drive                             New default drive

numdrives                         Total drives available


Remarks

The _dos_setdrive routine uses system call INT 0x0E to set the current
default drive to the drive argument: 1 = drive A, 2 = drive B, and so on.
The numdrives argument indicates the total number of drives in the system.
If this value is 4, for example, it does not mean the drives are designated
A, B, C, and D; it means only that four drives are in the system.


Return Value

There is no return value. If an invalid drive number is passed, the function
fails without indication. Use the _dos_getdrive routine to verify whether
the desired drive has been set.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getdiskfree,  _dos_getdrive


Example

    /* DGDRIVE.C: This program prints the letter of the current drive,
    * changes the default drive to A, then returns the number of disk drives.
    */

    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        unsigned olddrive, newdrive;
        unsigned number_of_drives;

        /* Print current default drive information */
        _dos_getdrive( &olddrive );
        printf( "The current drive is: %c\n", 'A' + olddrive1 );

        /* Set default drive to be drive A */
        printf( "Changing default drive to A\n");
        _dos_setdrive( 1, &number_of_drives );

        /* Get new default drive information and total number of drives */
        _dos_getdrive( &newdrive );
        printf( "The current drive is: %c\n", 'A' + newdrive1 );
        printf( "Number of logical drives: %d\n", number_of_drives );

        /* Restore default drive */
        _dos_setdrive( olddrive, &number_of_drives );
    }


Output



    The current drive is: C
    Changing default drive to A
    The current drive is: A
    Number of logical drives: 26





_dos_setfileattr
────────────────────────────────────────────────────────────────────────────


Description

Sets the attributes of the file or directory, using system call INT 0x43.

    #include <dos.h>

    unsigned _dos_setfileattr( char *pathname, unsigned attrib );

pathname                          Full path of target file/directory

attrib                            New attributes


Remarks

The _dos_setfileattr routine uses system call INT 0x43 to set the attributes
of the file or directory pointed to by pathname. The actual attributes are
contained in the low-order byte of the attrib word. Attributes are
represented by manifest constants, as described below:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_A_ARCH                           Archive. Set whenever the file is
                                    changed, or cleared by the DOS BACKUP
                                    command.

_A_HIDDEN                         Hidden file. Cannot be found by a
                                    directory search.

_A_NORMAL                         Normal. File can be read or written to
                                    without restriction.

_A_RDONLY                         Read-only. File cannot be opened for
                                    writing, and a file with the same name
                                    cannot be created.

_A_SUBDIR                         Subdirectory.

_A_SYSTEM                         System file. Cannot be found by a
                                    directory search.

_A_VOLID                          Volume ID. Only one file can have this
                                    attribute, and it must be in the root
                                    directory.


Return Value

The function returns 0 if successful. Otherwise, it returns the DOS error
code and sets errno to one of the following:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Access denied; cannot change the volume
                                    ID or the
                                    subdirectory.

ENOENT                            No file or directory matching the target
                                    was found.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getfileattr


Example

    /* DGFILEAT.C: This program creates a file with the specified attributes,
    * then prints this information before changing the file attributes back
    * to normal.
    */

    #include <stdio.h>
    #include <dos.h>

    void main()
    {
        unsigned oldattrib, newattrib;
        int fh;

        /* Get and display file attribute */
        _dos_getfileattr( "DGFILEAT.C", &oldattrib );
        printf( "Attribute: 0x%.4x\n", oldattrib );
        if( ( oldattrib & _A_RDONLY ) != 0 )
        printf( "Read only file\n" );
        else
        printf( "Not a read only file.\n" );

        /* Reset file attribute to normal file */
        _dos_setfileattr( "DGFILEAT.C", _A_RDONLY );
        _dos_getfileattr( "DGFILEAT.C", &newattrib );
        printf( "Attribute: 0x%.4x\n", newattrib );

        /* Restore file attribute */
        _dos_setfileattr( "DGFILEAT.C", oldattrib );
        _dos_getfileattr( "DGFILEAT.C", &newattrib );
        printf( "Attribute: 0x%.4x\n", newattrib );
    }


Output



    Attribute: 0x0020
    Not a read only file.
    Attribute: 0x0001
    Attribute: 0x0020





_dos_setftime
────────────────────────────────────────────────────────────────────────────


Description

Sets the date and time for a file, using system call INT 0x57.

    #include <dos.h>

    unsigned _dos_setftime( int handle, unsigned date, unsigned time );

handle                            Target file

date                              Date of last write

time                              Time of last write


Remarks

The _dos_setftime routine uses system call INT 0x57 to set the date and time
at which the file identified by handle was last written to. These values
appear in the DOS date and time format, described in the following lists:

Time Bits                         Meaning
────────────────────────────────────────────────────────────────────────────
0 - 4                             Number of two-second increments (0 -29)

5 - 10                            Minutes (0 -59)

11-15                             Hours (0 -23)

Date Bits                         Meaning
────────────────────────────────────────────────────────────────────────────
0 - 4                             Day (1-31)

5 -8                              Month (1-12)

9 -15                             Year since 1980 (for example, 1989 is
                                    stored as 9)


Return Value

If successful, the function returns 0. Otherwise, it returns the DOS error
code and sets errno to EBADF, indicating that an invalid file handle was
passed.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getftime, fstat, stat


Example

    /* DGFTIME.C: This program displays and modifies the date and time
    * fields of a file.
    */

    #include <fcntl.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <dos.h>

    void main()
    {
                                    /* FEDC BA98 7654 3210          */
        unsigned new_date = 0x184f;   /* 0001 1000 0100 1111  2/15/92 */
        unsigned new_time = 0x48e0;   /* 0100 1000 1110 0000  9:07 AM */
        unsigned old_date, old_time;

        int fh;

        /* Open file with _dos_open function */
        if( _dos_open( "dgftime.obj", O_RDONLY, &fh ) != 0 )
        exit( 1 );

        /* Get file date and time */
        _dos_getftime( fh, &old_date, &old_time );
        printf( "Old date field: 0x%.4x\n", old_date );
        printf( "Old time field: 0x%.4x\n", old_time );
        system( "dir dgftime.obj" );

        /* Modify file date and time */
        if( !_dos_setftime( fh, new_date, new_time ) )
        {
        _dos_getftime( fh, &new_date, &new_time );
        printf( "New date field: 0x%.4x\n", new_date );
        printf( "New time field: 0x%.4x\n", new_time );
        system( "dir dgftime.obj" );

        /* Restore date and time */
        _dos_setftime( fh, old_date, old_time );
        }
        _dos_close( fh );
    }


Output



    Old date field: 0x12cf
    Old time field: 0x94bb

    Volume in drive C is OS2
    Directory of  C:\LIBREF

    DGFTIME  OBJ     3923   6-15-89   6:37p
            1 File(s)  13676544 bytes free

    New date field: 0x184f
    New time field: 0x48e0

    Volume in drive C is OS2
    Directory of  C:\LIBREF

    DGFTIME  OBJ     3923   2-15-92   9:07a
            1 File(s)  13676544 bytes free





_dos_settime
────────────────────────────────────────────────────────────────────────────


Description

Sets the current system time, using system call INT 0x2D.

    #include <dos.h>

    unsigned _dos_settime( struct dostime_t *time );

time                              New system time


Remarks

The _dos_settime routine uses system call INT 0x2D to set the current system
time to the value stored in the dostime_t structure that time points to, as
defined in DOS.H. The dostime_t structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
unsigned char hour                0 -23

unsigned char minute              0 -59

unsigned char second              0 -59

unsigned char hsecond             Hundredths of a second; 0 -99


Return Value

If successful, the function returns 0. Otherwise, it returns a nonzero value
and sets errno to EINVAL, indicating an invalid time was specified.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_getdate,  _dos_gettime,  _dos_setdate, gmtime, localtime, mktime,
_strdate,  _strtime


Example

    /* DSTIME.C: This program changes the time and date values and displays
    the
    * new date and time values.
    */

    #include <dos.h>
    #include <conio.h>
    #include <stdio.h>
    #include <time.h>

    void main()
    {
        struct dosdate_t olddate, newdate = { { 4 }, { 7 }, { 1984 } };
        struct dostime_t oldtime, newtime = { { 3 }, { 45 }, { 30 }, { 0 } };
        char   datebuf[40], timebuf[40];

        /* Get current date and time values */
        _dos_getdate( &olddate );
        _dos_gettime( &oldtime );
        printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );

        /* Modify date and time structures */
        _dos_setdate( &newdate );
        _dos_settime( &newtime );
        printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );

        /* Restore old date and time */
        _dos_setdate( &olddate );
        _dos_settime( &oldtime );
    }


Output



    06/15/89    18:26:09
    07/04/84    03:45:30





_dos_setvect
────────────────────────────────────────────────────────────────────────────


Description

Sets the current value of the interrupt vector, using system call INT 0x25.


    #include <dos.h>

    void _dos_setvect( unsigned intnum, void( _interrupt _far *handler)( ));

intnum                            Target-interrupt vector

handler                           Interrupt handler for which to assign
                                    intnum


Remarks

The _dos_setvect routine uses system call INT 0x25 to set the current value
of the interrupt vector intnum to the function pointed to by handler.
Subsequently, whenever the intnum interrupt is generated, the handler
routine will be called. If handler is a C function, it must have been
previously declared with the interrupt attribute. Otherwise, you must make
sure that the function satisfies the requirements for an interrupt-handling
routine. For example, if handler is an assembler function, it must be a far
routine that returns with an IRET instead of a RET.

The interrupt attribute indicates that the function is an interrupt handler.
The compiler generates appropriate entry and exit sequences for the
interrupt-handling function, including saving and restoring all registers
and executing an IRET instruction to return.

The _dos_setvect routine is generally used with the _dos_getvect function.
To replace an interrupt vector, first save the current vector of the
interrupt using _dos_getvect. Then set the vector to your own interrupt
routine with _dos_setvect. The saved vector can later be restored, if
necessary, using _dos_setvect. The user-defined routine may also need the
original vector in order to call it or to chain to it with _chain_intr.


Registers and Interrupt Functions

When you call an interrupt function, the DS register is initialized to the C
data segment. This allows you to access global variables from within an
interrupt function.

In addition, all registers except SS are saved on the stack. You can access
these registers within the function if you declare a function parameter list
containing a formal parameter for each saved register. The following example
illustrates such a declaration:

    void _interrupt _far int_handler( unsigned _es, unsigned _ds,
                                    unsigned _di, unsigned _si,
                                    unsigned _bp, unsigned _sp,
                                    unsigned _bx, unsigned _dx,
                                    unsigned _cx, unsigned _ax,
                                    unsigned _ip, unsigned _cs,
                                    unsigned _flags )
    {
    .
    .
    .
    }

The formal parameters must appear in the opposite order from which they are
pushed onto the stack. You can omit parameters from the end of the list in a
declaration, but not from the beginning. For example, if your handler needs
to use only DI and SI, you must still provide ES and DS, but not necessarily
BX or DX.

You can pass additional arguments if your interrupt handler will be called
directly from C rather than by an INT instruction. To do this, you must
declare all register parameters and then declare your parameter at the end
of the list.

The compiler always saves and restores registers in the same, fixed order.
Thus, no matter what names you use in the formal parameter list, the first
parameter in the list refers to ES, the second refers to DS, and so on. If
your interrupt routines will use in-line assembler, you should distinguish
the parameter names so that they will not be the same as the real register
names.

If you change any of the register parameters of an interrupt function while
the function is executing, the corresponding register contains the changed
value when the function returns. For example:

    void _interrupt _far int_handler( unsigned _es, unsigned _ds,
                                    unsigned _di, unsigned _si )
    {
        _di = -1;
    }

This code causes the DI register to contain -1 when the handler function
returns. It is not a good idea to modify the values of the parameters
representing the IP and CS registers in interrupt functions. If you must
modify a particular flag (such as the carry flag for certain DOS and BIOS
interrupt routines), use the OR operator ( | ) so that other bits in the
flag register are not changed.

When an interrupt function is called by an INT instruction, the
interrupt-enable flag is cleared. If your interrupt function needs to do
significant processing, you should use the _enable function to set the
interrupt flag so that interrupts can be handled.


Precautions for Interrupt Functions

Since DOS is not reentrant (a DOS interrupt cannot be called from inside a
DOS interrupt), it is usually not safe to call from inside an interrupt
function any standard library function that calls DOS INT 21H. Similar
precautions apply to many BIOS functions. Functions that rely on INT 21H
calls include I/O functions and the _dos family of functions. Functions that
rely on the machine's BIOS include graphics functions and the _bios family
of functions. It is usually safe to use functions that do not rely on INT
21H or BIOS, such as string-handling functions. Before using a standard
library function in an interrupt function, be sure that you are familiar
with the action of the library function.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_chain_intr,  _dos_getvect,  _dos_keep





_dos_write
────────────────────────────────────────────────────────────────────────────


Description

Writes a buffer to a file, using system call INT 0x40.

    #include <dos.h>

    unsigned _dos_write( int handle, void _far *buffer, unsigned count,
    unsigned *numwrt );

handle                            File to write to

buffer                            Buffer to write from

count                             Number of bytes to write

numwrt                            Number of bytes actually written


Remarks

The _dos_write routine uses system call INT 0x40 to write data to the file
that handle references; count bytes of data from the buffer to which buffer
points are written to the file. The integer pointed to by numwrt will be the
number of bytes actually written, which may be less than the number
requested.

Do not use the DOS interface routines with the console, low-level, or stream
I/O routines.


Return Value

If successful, the function returns 0. Otherwise, it returns the DOS error
code and sets errno to one of the following manifest constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Access denied (handle references a file
                                    not open for write
                                    access)

EBADF                             Invalid file handle


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_dos_close,  _dos_open,  _dos_read, write


Example

    /* DWRITE.C: This program uses DOS I/O functions to write to a file. */

    #include <fcntl.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <dos.h>

    void main()
    {
        char out_buffer[] = "Hello";
        int  fh;
        unsigned n_written;

        /* Open file with _dos_creat function */
        if( _dos_creat( "data", _A_NORMAL, &fh ) == 0 )
        {
        /* Write data with _dos_write function */
        _dos_write( fh, out_buffer, 5, &n_written );
        printf( "Number of characters written: %d\n", n_written );

        _dos_close( fh );
        printf( "Contents of file are:\n" );
        system( "type data" );
        }
    }


Output



    Number of characters written: 5
    Contents of file are:
    Hello





dosexterr
────────────────────────────────────────────────────────────────────────────


Description

Gets register values returned by INT 0x59.

    #include <dos.h>

    int dosexterr( struct DOSERROR *errorinfo );

errorinfo                         Extended DOS error information


Remarks

The dosexterr function obtains the extended error information returned by
the DOS system call INT 0x59 and stores the values in the structure pointed
to by errorinfo. This function is useful when making system calls under DOS
versions 3.0 or later, which offer extended error handling.

The structure type DOSERROR is defined in DOS.H. The DOSERROR structure
contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
int exterror                      AX register contents

char class                        BH register contents

char action                       BL register contents

char locus                        CH register contents

Giving a NULL pointer argument causes dosexterr to return the value in AX
without filling in the structure fields. See MS-DOS Encyclopedia  (Duncan,
ed.; Redmond, WA: Microsoft Press, 1988) or Programmer's PC Sourcebook
(Hogan; Redmond, WA: Microsoft Press, 1988) for more information on the
register contents.


Return Value

The dosexterr function returns the value in the AX register (identical to
the value in the exterror structure field).


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX


The dosexterr function should be used only under DOS versions 3.0 or later.



See Also

perror


Example

    /* DOSEXERR.C: This program tries to open the file test.dat. If the
    * attempted open operation fails, the program uses dosexterr to display
    * extended error information.
    */

    #include <dos.h>
    #include <io.h>
    #include <fcntl.h>
    #include <stdio.h>

    void main()
    {
        struct DOSERROR doserror;
        int fd;

        /* Attempt to open a non-existent file */
        if( (fd = open( "NOSUCHF.ILE", O_RDONLY )) == -1 )
        {
        dosexterr( &doserror );
        printf( "Error: %d  Class: %d  Action: %d  Locus: %d\n",
                doserror.exterror, doserror.class,
                doserror.action,   doserror.locus );
        }
        else
        {
        printf( "Open succeeded so no extended information printed\n" );
        close( fd );
        }
    }


Output



    Error: 2  Class: 8  Action: 3  Locus: 2





dup, dup2
────────────────────────────────────────────────────────────────────────────


Description

Create a second handle for an open file (dup), or reassign a file handle
(dup2).

#include <io.h                    Required only for function declarations

    int dup( int handle );

    int dup2( int handle1, int handle2 );

handle, handle1                   Handle referring to open file

handle2                           Any handle value


Remarks

The dup and dup2 functions cause a second file handle to be associated with
a currently open file. Operations on the file can be carried out using
either file handle. The type of access allowed for the file is unaffected by
the creation of a new handle.

The dup function returns the next available file handle for the given file.
The dup2 function forces handle2 to refer to the same file as handle1. If
handle2 is associated with an open file at the time of the call, that file
is closed.


Return Value

The dup function returns a new file handle. The dup2 function returns 0 to
indicate success. Both functions return -1 if an error occurs and set errno
to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EBADF                             Invalid file handle

EMFILE                            No more file handles available (too many
                                    open files)


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

close, creat, open


Example

    /* DUP.C: This program uses the variable old to save the original stdout.
    * It then opens a new file named new and forces stdout to refer
    * to it. Finally, it restores stdout to its original state.
    */

    #include <io.h>
    #include <stdlib.h>
    #include <stdio.h>
    void main()
    {
        int old;
        FILE *new;

        old = dup( 1 );   /* "old" now refers to "stdout" */
                        /* Note:  file handle 1 == "stdout" */
        if( old == -1 )
        {
        perror( "dup( 1 ) failure" );
        exit( 1 );
        }
        write( old, "This goes to stdout first\r\n", 27 );
        if( ( new = fopen( "data", "w" ) ) == NULL )
        {
        puts( "Can't open file 'data'\n" );
        exit( 1 );
        }

        /* stdout now refers to file "data" */
        if( -1 == dup2( fileno( new ), 1 ) )
        {
        perror( "Can't dup2 stdout" );
        exit( 1 );
        }
        puts( "This goes to file 'data'\r\n" );

        /* Flush stdout stream buffer so it goes to correct file */
        fflush( stdout );
        fclose( new );

        /* Restore original stdout */
        dup2( old, 1 );
        puts( "This goes to stdout\n" );
        puts( "The file 'data' contains:" );
        system( "type data" );
    }


Output



    This goes to stdout first
    This goes to stdout

    The file 'data' contains:
    This goes to file 'data'





ecvt
────────────────────────────────────────────────────────────────────────────


Description

Converts a double number to a string.

#include <stdlib.h>               Required only for function declarations

    char *ecvt( double value, int count, int *dec, int *sign );

value                             Number to be converted

count                             Number of digits stored

dec                               Stored decimal-point position

sign                              Sign of converted number


Remarks

The ecvt function converts a floating-point number to a character string.
The value argument is the floating-point number to be converted. The ecvt
function stores up to count digits of value as a string and appends a null
character ('\0'). If the number of digits in value exceeds count, the
low-order digit is rounded. If there are fewer than count digits, the string
is padded with zeros.

Only digits are stored in the string. The position of the decimal point and
the sign of value can be obtained from dec and sign after the call. The dec
argument points to an integer value giving the position of the decimal point
with respect to the beginning of the string. A 0 or negative integer value
indicates that the decimal point lies to the left of the first digit. The
sign argument points to an integer indicating the sign of the converted
number. If the integer value is 0, the number is positive. Otherwise, the
number is negative.

The ecvt and fcvt functions use a single statically allocated buffer for the
conversion. Each call to one of these routines destroys the result of the
previous call.


Return Value

The ecvt function returns a pointer to the string of digits. There is no
error return.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

atof, atoi, atol, fcvt, gcvt


Example

    /* ECVT.C: This program uses ecvt to convert a floating-point
    * number to a character string.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        int     decimal, sign;
        char    *buffer;
        int     precision = 10;
        double  source = 3.1415926535;

        buffer = ecvt( source, precision, &decimal, &sign );
        printf( "source: %2.10f   buffer: '%s'  decimal: %d   sign: %d\n",
                source, buffer, decimal, sign );
    }


Output



    source: 3.1415926535   buffer: '3141592654'  decimal: 1   sign: 0





_ellipse Functions
────────────────────────────────────────────────────────────────────────────


Description

Draw ellipses.

    #include <graph.h>

    short _far _ellipse( short control, short x1, short y1, short x2, short y2
    );

    short _far _ellipse_w( short control, double wx1, double wy1, double wx2,
    double wy2 );

    short _far _ellipse_wxy( short control, struct _wxycoord _far *pwxy1,
    struct _wxycoord _far *pwxy2 );

control                           Fill flag

x1, y1                            Upper-left corner of bounding rectangle

x2, y2                            Lower-right corner of bounding rectangle

wx1, wy1                          Upper-left corner of bounding rectangle

wx2, wy2                          Lower-right corner of bounding rectangle

pwxy1                             Upper-left corner of bounding rectangle

pwxy2                             Lower-right corner of bounding rectangle


Remarks

The _ellipse functions draw ellipses or circles. The borders are drawn in
the current color. In the _ellipse function, the center of the ellipse is
the center of the bounding rectangle defined by the view-coordinate points
(x1, y1) and (x2, y2).

In the _ellipse_w function, the center of the ellipse is the center of the
bounding rectangle defined by the window-coordinate points (wx1, wy1) and
(wx2, wy2).

In the _ellipse_wxy function, the center of the ellipse is the center of the
bounding rectangle defined by the window-coordinate pairs (pwxy1) and
(pwxy2).

If the bounding-rectangle arguments define a point or a vertical or
horizontal line, no figure is drawn.

The control argument can be one of the following manifest constants:

Constant                          Action
────────────────────────────────────────────────────────────────────────────
_GFILLINTERIOR                    Fills the ellipse using the current fill
                                    mask

_GBORDER                          Does not fill the ellipse

The control option given by _GFILLINTERIOR is equivalent to a subsequent
call to the _floodfill function, using the center of the ellipse as the
starting point and the current color (set by _setcolor) as the boundary
color.


Return Value

The _ellipse functions return a nonzero value if the ellipse is drawn
successfully; otherwise, they return 0.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_arc functions,  _floodfill,  _grstatus,  _lineto functions,  _pie
functions, _polygon functions,  _rectangle functions,  _setcolor,
_setfillmask


Example

    /* ELLIPSE.C: This program draws a simple ellipse. */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void main()
    {
        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _ellipse( _GFILLINTERIOR, 80, 50, 240, 150 );

        /* Strike any key to clear screen. */
        getch();
        _setvideomode( _DEFAULTMODE );
    }





_enable
────────────────────────────────────────────────────────────────────────────


Description

Enables interrupts.

    #include <dos.h>

    void _enable( void );


Remarks

The _enable routine enables interrupts by executing an 8086 STI machine
instruction.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_disable





_endthread
────────────────────────────────────────────────────────────────────────────


Description

Terminates an OS/2 thread.

#include <process.h>              Multithread version of PROCESS.H

    void _far _endthread( void );


Description

The _endthread function terminates a thread created by _beginthread.

Because threads terminate automatically, the _endthread function is normally
not required. It is used to terminate a thread conditionally.

The OS/2 function DosExit should not be used to terminate threads created by
the _beginthread function. If DosExit is used, the results are
unpredictable.


Return Value

None.


Compatibility

▼ ANSI  ▼ DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_beginthread


Example

See the example for _beginthread.





eof
────────────────────────────────────────────────────────────────────────────


Description

Tests for end-of-file.

#include <io.h>                   Required only for function declarations

    int eof( int handle );

handle                            Handle referring to open file


Remarks

The eof function determines whether the end of the file associated with
handle has been reached.


Return Value

The eof function returns the value 1 if the current position is end-of-file,
or 0 if it is not. A return value of -1 indicates an error; in this case,
errno is set to EBADF, indicating an invalid file handle.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

clearerr, feof, ferror, perror


Example

    /* EOF.C: This program reads data from a file ten bytes at a time
    * until the end of the file is reached or an error is encountered.
    */

    #include <io.h>
    #include <fcntl.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        int  fh, count, total = 0;
        char buf[10];

        if( (fh = open( "eof.c", O_RDONLY )) == - 1 )
        exit( 1 );

    /* Cycle until end of file reached: */
        while( !eof( fh ) )
        {
        /* Attempt to read in 10 bytes: */
        if( (count = read( fh, buf, 10 )) == -1 )
        {
            perror( "Read error" );
            break;
        }

        /* Total up actual bytes read */
        total += count;
        }
        printf( "Number of bytes read = %d\n", total );
        close( fh );
    }


Output



    Number of bytes read = 715





exec Functions
────────────────────────────────────────────────────────────────────────────


Description

Load and execute new child processes.

#include <process.h>              Required only for function declarations

    int execl( char *cmdname, char *arg0, ... char *argn, NULL );

    int execle( char *cmdname, char *arg0, ... char *argn, NULL,
    char **envp );

    int execlp( char *cmdname, char *arg0, ... char *argn, NULL  );

    int execlpe( char *cmdname, char *arg0, ... char *argn, NULL,
    char **envp  );

    int execv( char *cmdname, char **argv );

    int execve( char *cmdname, char **argv, char **envp );

    int execvp( char *cmdname, char **argv );

    int execvpe( char *cmdname, char **argv, char **envp );

cmdname                           Path name of file to be executed

arg0, ... argn                    List of pointers to arguments

argv                              Array of pointers to arguments

envp                              Array of pointers to environment
                                    settings


Remarks

The exec functions load and execute new child processes. When the call is
successful in DOS, the child process is placed in the memory previously
occupied by the calling process. Under OS/2, calling an exec function is
equivalent to calling the corresponding function with the P_NOWAITO argument
specified, followed by a call to the exit function. Sufficient memory must
be available for loading and executing the child process.

All of the exec functions use the same operating system function. The
letter(s) at the end of the function name determine the specific variation,
as shown in the following list:

Letter                            Variation
────────────────────────────────────────────────────────────────────────────
e                                 An array of pointers to environment
                                    arguments is explicitly passed to the
                                    child process.

l                                 Command-line arguments are passed
                                    individually to the exec function.

p                                 Uses the PATH environment variable to
                                    find the file to be
                                    executed.

v                                 Command-line arguments are passed to the
                                    exec function as an array of pointers.

The cmdname argument specifies the file to be executed as the child process.
It can specify a full path (from the root), a partial path (from the current
working directory), or just a file name. If cmdname does not have a
file-name extension or does not end with a period (.), the exec function
searches for the named file; if the search is unsuccessful, it tries the
same base name, first with the extension .COM, then with the extension .EXE.
If cmdname has an extension, only that extension is used in the search. If
cmdname ends with a period, the exec calls search for cmdname with no
extension. The execlp, execlpe, execvp, and execvpe routines search for
cmdname (using the same procedures) in the directories specified by the PATH
environment variable.

If cmdname contains a drive specifier or any slashes (i.e., if it is a
relative path name), the exec call searches only for the specified file and
no path searching is done.

Arguments are passed to the new process by giving one or more pointers to
character strings as arguments in the exec call. These character strings
form the argument list for the child process. The combined length of the
strings forming the argument list for the new process must not exceed 128
bytes (in real mode only). The terminating null character ('\0') for each
string is not included in the count, but space characters (inserted
automatically to separate the arguments) are counted.

The argument pointers can be passed as separate arguments (execl, execle,
execlp, and execlpe) or as an array of pointers (execv, execve, execvp, and
execvpe). At least one argument, arg0, must be passed to the child process;
this argument is argv[0] of the child process. Usually, this argument is a
copy of the cmdname argument. (A different value will not produce an error.)
Under versions of DOS earlier than 3.0, the passed value of arg0 is not
available for use in the child process. However, under OS/2 and under DOS
versions 3.0 and later, cmdname is available as arg0.

The execl, execle, execlp, and execlpe calls are typically used when the
number of arguments is known in advance. The argument arg0 is usually a
pointer to cmdname. The arguments arg1 through argn point to the character
strings forming the new argument list. A null pointer must follow argn to
mark the end of the argument list.

The execv, execve, execvp, and execvpe calls are useful when the number of
arguments to the new process is variable. Pointers to the arguments are
passed as an array, argv. The argument argv[0] is usually a pointer to
cmdname. The arguments argv[1] through argv[n] point to the character
strings forming the new argument list. The argument argv[n+1] must be a NULL
pointer to mark the end of the argument list.

Files that are open when an exec call is made remain open in the new
process. In the execl, execlp, execv, and execvp calls, the child process
inherits the environment of the parent. The execle, execlpe, execve, and
execvpe calls allow the user to alter the environment for the child process
by passing a list of environment settings through the envp argument. The
argument envp is an array of character pointers, each element of which
(except for the final element) points to a null-terminated string defining
an environment variable. Such a string usually has the form

NAME=value

where NAME is the name of an environment variable and value is the string
value to which that variable is set. (Note that value is not enclosed in
double quotation marks.) The final element of the envp array should be NULL.
When envp itself is NULL, the child process inherits the environment
settings of the parent process.

A program executed with one of the exec family of functions is always loaded
into memory as if the "maximum allocation" field in the program's .EXE file
header is set to the default value of 0FFFFH. You can use the EXEMOD utility
to change the maximum allocation field of a program; however, such a program
invoked with one of the exec functions may behave differently from a program
invoked directly from the operating-system command line or with one of the
spawn functions.

The exec calls do not preserve the translation modes of open files. If the
child process must use files inherited from the parent, the setmode routine
should be used to set the translation mode of these files to the desired
mode.

You must explicitly flush (using fflush or flushall) or close any stream
prior to the exec function call.

Signal settings are not preserved in child processes that are created by
calls to exec routines. The signal settings are reset to the default in the
child process.


Return Value

The exec functions do not normally return to the calling process. If an exec
function returns, an error has occurred and the return value is -1. The
errno variable is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
E2BIG                             The argument list exceeds 128 bytes, or
                                    the space required for the environment
                                    information exceeds 32K.

EACCES                            The specified file has a locking or
                                    sharing violation
                                    (OS/2, and DOS versions 3.0 or later).

EMFILE                            Too many files open (the specified file
                                    must be opened to determine whether it
                                    is executable).

ENOENT                            File or path name not found.

ENOEXEC                           The specified file is not executable or
                                    has an invalid
                                    executable-file format.

ENOMEM                            Not enough memory is available to
                                    execute the child process; or the
                                    available memory has been corrupted; or
                                    an invalid block exists, indicating that
                                    the parent process was not allocated
                                    properly.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX


Because of differences in DOS versions 2.0 and 2.1, child processes
generated by the exec family of functions (or by the equivalent spawn
functions with the P_OVERLAY argument) may cause fatal system errors when
they exit. If you are running DOS 2.0 or 2.1, you must upgrade to DOS
version 3.0 or later to use these functions.

Bound programs cannot use the exec family of functions in real mode.


See Also

abort, atexit, exit, _exit, onexit, spawn functions, system


Example

    /* EXEC.C: This program accepts a number in the range 1 through 8 from the
    * command line. Based on the number it receives, it executes one of the
    * eight different procedures that spawn the process named child. For
    * some of these procedures, the child.exe file must be in the same
    * directory; for others, it need only be in the same path.
    */

    #include <stdio.h>
    #include <process.h>

    char *my_env[] = {
                "THIS=environment will be",
                "PASSED=to child.exe by the",
                "EXECLE=and",
                "EXECLPE=and",
                "EXECVE=and",
                "EXECVPE=functions",
                NULL
                };

    void main( int argc, char *argv[] )
    {
        char *args[4];
        int result;

        args[0] = "child";     /* Set up parameters to send */
        args[1] = "execv??";
        args[2] = "two";
        args[3] = NULL;

    switch( argv[1][0] )   /* Based on first letter of argument */
        {
        case '1':
            execl( argv[2], argv[2], "execl", "two", NULL );
            break;
        case '2':
            execle( argv[2], argv[2], "execle", "two", NULL, my_env );
            break;
        case '3':
            execlp( argv[2], argv[2], "execlp", "two", NULL );
            break;
        case '4':
            execlpe( argv[2], argv[2], "execlpe", "two", NULL, my_env );
            break;
        case '5':
            execv( argv[2], args );
            break;
        case '6':
            execve( argv[2], args, my_env );
            break;
        case '7':
            execvp( argv[2], args );
            break;
        case '8':
            execvpe( argv[2], args, my_env );
            break;
        default:
            printf( "SYNTAX: EXEC <1-8> <childprogram>\n" );
            exit( 1 );
        }
        printf( "Process was not spawned.\n" );
        printf( "Program 'child' was not found." );
    }





exit, _exit
────────────────────────────────────────────────────────────────────────────


Description

Terminate the calling process after cleanup (exit) or immediately ( _exit).


#include <process.h>              Required only for function declarations

#include <stdlib.h>               Use either PROCESS.H or STDLIB.H

    void exit( int status );

    void _exit( int status );

status                            Exit status


Remarks

The exit and _exit functions terminate the calling process. The exit
function first calls, in LIFO (last-in-first-out) order, the functions
registered by atexit and onexit, then flushes all file buffers before
terminating the process. The _exit function terminates the process without
processing atexit or onexit functions or flushing stream buffers. The status
value is typically set to 0 to indicate a normal exit and set to some other
value to indicate an error.

Although the exit and _exit calls do not return a value, the low-order byte
of status is made available to the waiting parent process, if one exists,
after the calling process exits. The status value is available to the
operating-system batch command ERRORLEVEL.

The behavior of the exit, _exit, _cexit, and _c_exit functions is as
follows:

Function                          Action
────────────────────────────────────────────────────────────────────────────
exit                              Performs complete C library termination
                                    procedures, terminates the process, and
                                    exits with the supplied status code.

_exit                             Performs "quick" C library termination
                                    procedures, terminates the process, and
                                    exits with the supplied status code.

_cexit                            Performs complete C library termination
                                    procedures and returns to caller, but
                                    does not terminate the process.

_c_exit                           Performs "quick" C library termination
                                    procedures and returns to caller, but
                                    does not terminate the process.


Return Value

None.


Compatibility

exit

    ANSI   DOS   OS/2   UNIX   XENIX


_exit

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

abort, atexit, _cexit, exec functions, onexit, spawn functions, system


Example

    /* EXITER.C: This program prompts the user for a yes or no and returns
    * a DOS error code of 1 if the user answers Y or y; otherwise it
    * returns 0. The error code could be tested in a batch file.
    */

    #include <conio.h>
    #include <stdlib.h>

    void main()
    {
        char  ch;

        cputs( "Yes or no? " );
        ch = getch();
        cputs( "\r\n" );
        if( toupper( ch ) == 'Y' )
        exit( 1 );
        else
        exit( 0 );
    }





exp, expl
────────────────────────────────────────────────────────────────────────────


Description

Calculate the exponential.

    #include <math.h>

    double exp( double x );

    long double expl( long double x );

x                                 Floating-point value


Remarks

The exp and expl functions return the exponential function of their
floating-point arguments (x).

The expl function is the 80-bit counterpart; it uses an 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.


Return Value

These functions return ex. The functions return HUGE_VAL on overflow and set
errno to ERANGE; on underflow, they return 0 but do not set errno.


Compatibility

exp

    ANSI   DOS   OS/2   UNIX   XENIX


expl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

log functions


Example

    /* EXP.C */
    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = 2.302585093, y;

        y = exp( x );
        printf( "exp( %f ) = %f\n", x, y );
    }


Output



    exp( 2.302585 ) = 10.000000





_expand Functions
────────────────────────────────────────────────────────────────────────────


Description

Changes the size of a memory block.

#include <malloc.h>               Required only for function declarations

    void *_expand( void *memblock, size_t size );

    void _based( void ) *_bexpand( _segment seg, void _based( void )
    *memblock,
    size_t size );

    void _far *_fexpand( void _far *memblock, size_t size );

    void _near *_nexpand( void _near *memblock, size_t size );

memblock                          Pointer to previously allocated memory
                                    block

size                              New size in bytes

seg                               Value of base segment


Remarks

The _expand family of functions changes the size of a previously allocated
memory block by attempting to expand or contract the block without moving
its location in the heap. The memblock argument points to the beginning of
the block. The size argument gives the new size of the block, in bytes. The
contents of the block are unchanged up to the shorter of the new and old
sizes.

The memblock argument can also point to a block that has been freed, as long
as there has been no intervening call to calloc, _expand, malloc, or
realloc. If memblock points to a freed block, the block remains free after a
call to one of the _expand functions.

The seg argument is the segment address of the _based heap.

In large data models (compact-, large-, and huge-model programs), _expand
maps to _fexpand. In small data models ( tiny-, small-, and medium-model
programs), expand maps to _nexpand.

The various _expand functions change the size of the storage block in the
data segments shown in the list below:

Function                          Data Segment
────────────────────────────────────────────────────────────────────────────
_expand                           Depends on data model of program

_bexpand                          Based heap specified by seg, or in all
                                    based heaps if seg
                                    is zero

_fexpand                          Far heap (outside default data segment)

_nexpand                          Near heap (inside default data segment)


Return Value

The _expand family of functions returns a void pointer to the reallocated
memory block. Unlike realloc, _expand cannot move a block to change its
size. This means the memblock argument to _expand is the same as the return
value if there is sufficient memory available to expand the block without
moving it.

With the exception of the _bexpand function, these functions return NULL if
there is insufficient memory available to expand the block to the given size
without moving it. The _bexpand function returns _NULLOFF if insufficient
memory is available. The item pointed to by memblock will have been expanded
as much as possible in its current location.

The storage space pointed to by the return value is guaranteed to be
suitably aligned for storage of any type of object. The new size of the item
can be checked with the _msize function. To get a pointer to a type other
than void, use a type cast on the return value.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

calloc functions, free functions, malloc functions, _msize functions,
realloc functions


Example

    /* EXPAND.C */
    #include <stdio.h>
    #include <malloc.h>
    #include <stdlib.h>

    void main()
    {
        char *bufchar;

        printf( "Allocate a 512 element buffer\n" );
        if( (bufchar = (char *)calloc( 512, sizeof( char ) )) == NULL )
        exit( 1 );
        printf( "Allocated %d bytes at %Fp\n",
            _msize( bufchar ), (void _far *)bufchar );

        if( (bufchar = (char *)_expand( bufchar, 1024 )) == NULL )
        printf( "Can't expand" );
        else
        printf( "Expanded block to %d bytes at %Fp\n",
                _msize( bufchar ), (void _far *)bufchar );

        /* Free memory */
        free( bufchar );
        exit( 0 );
    }


Output



    Allocate a 512 element buffer
    Allocated 512 bytes at 0067:142A
    Expanded block to 1024 bytes at 0067:142A





fabs, fabsl
────────────────────────────────────────────────────────────────────────────


Description

Calculate the absolute value of their floating-point arguments.

    #include <math.h>

    double fabs( double x );

    long double fabsl( long double x );

x                                 Floating-point value


Remarks

The fabs and fabsl functions calculate the absolute value of their
floating-point arguments.

The fabsl function is the 80-bit counterpart; it uses an 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.


Return Value

These functions return the absolute value of their arguments. There is no
error return.


Compatibility

fabs

    ANSI   DOS   OS/2   UNIX   XENIX


fabsl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

abs, cabs, labs


Example

    /* ABS.C: This program computes and displays the absolute values of
    * several numbers.
    */

    #include <stdio.h>
    #include <math.h>
    #include <stdlib.h>

    void main()
    {
        int    ix = -4, iy;
        long   lx = -41567L, ly;
        double dx = -3.141593, dy;

        iy = abs( ix );
        printf( "The absolute value of %d is %d\n", ix, iy);

        ly = labs( lx );
        printf( "The absolute value of %ld is %ld\n", lx, ly);

        dy = fabs( dx );
        printf( "The absolute value of %f is %f\n", dx, dy );
    }


Output



    The absolute value of -4 is 4
    The absolute value of -41567 is 41567
    The absolute value of -3.141593 is 3.141593





fclose, fcloseall
────────────────────────────────────────────────────────────────────────────


Description

Closes a stream (fclose) or closes all open streams (fcloseall).

    #include <stdio.h>

    int fclose( FILE *stream );

    int fcloseall( void );

stream                            Pointer to FILE structure


Remarks

The fclose function closes stream. The fcloseall function closes all open
streams except stdin, stdout, stderr (and in DOS, stdaux and stdprn). It
also closes and deletes any temporary files created by tmpfile.

In both functions, all buffers associated with the stream are flushed prior
to closing. System-allocated buffers are released when the stream is closed.
Buffers assigned by the user with setbuf and setvbuf are not automatically
released.


Return Value

The fclose function returns 0 if the stream is successfully closed. The
fcloseall function returns the total number of streams closed. Both
functions return EOF to indicate an error.


Compatibility

fclose

    ANSI   DOS   OS/2   UNIX   XENIX


fcloseall

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

close, fdopen, fflush, fopen, freopen


Example

    /* FOPEN.C: This program opens files named "data" and "data2". It uses
    * fclose to close "data" and fcloseall to close all remaining files.
    */

    #include <stdio.h>

    FILE *stream, *stream2;

    void main()
    {
        int numclosed;

        /* Open for read (will fail if 'data does not exist) */
        if( (stream  = fopen( "data", "r" )) == NULL )
        printf( "The file 'data' was not opened\n" );
        else
        printf( "The file 'data' was opened\n" );

        /* Open for write */
        if( (stream2 = fopen( "data2", "w+" )) == NULL )
        printf( "The file 'data2' was not opened\n" );
        else
        printf( "The file 'data2' was opened\n" );

        /* Close stream */
        if( fclose( stream ) )
        printf( "The file 'data' was not closed\n" );

        /* All other files are closed: */
        numclosed = fcloseall( );
        printf( "Number of files closed by fcloseall: %u\n", numclosed );
    }


Output



    The file 'data' was opened
    The file 'data2' was opened
    Number of files closed by fcloseall: 1





fcvt
────────────────────────────────────────────────────────────────────────────


Description

Converts a floating-point number to a string.

#include <stdlib.h>               Required only for function declarations

    char *fcvt( double value, int count, int *dec, int *sign );

value                             Number to be converted

count                             Number of digits after decimal point

dec                               Pointer to stored decimal-point position

sign                              Pointer to stored sign indicator


Remarks

The fcvt function converts a floating-point number to a null-terminated
character string. The value argument is the floating-point number to be
converted. The fcvt function stores the digits of value as a string and
appends a null character ('\0'). The count argument specifies the number of
digits to be stored after the decimal point. Excess digits are rounded off
to count places. If there are fewer than count digits of precision, the
string is padded with zeros.

Only digits are stored in the string. The position of the decimal point and
the sign of value can be obtained from dec and sign after the call. The dec
argument points to an integer value; this integer value gives the position
of the decimal point with respect to the beginning of the string. A zero or
negative integer value indicates that the decimal point lies to the left of
the first digit. The argument sign points to an integer indicating the sign
of value. The integer is set to 0 if value is positive and is set to a
nonzero number if value is negative.

The ecvt and fcvt functions use a single statically allocated buffer for the
conversion. Each call to one of these routines destroys the results of the
previous call.


Return Value

The fcvt function returns a pointer to the string of digits. There is no
error return.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

atof, atoi, atol, ecvt, gcvt


Example

    /* FCVT.C: This program converts the constant 3.1415926535 to a string and
    * sets the pointer *buffer to point to that string.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        int  decimal, sign;
        char *buffer;
        double source = 3.1415926535;

        buffer = fcvt( source, 7, &decimal, &sign );
        printf( "source: %2.10f   buffer: '%s'   decimal: %d   sign: %d\n",
                source, buffer, decimal, sign );
    }


Output



    source: 3.1415926535   buffer: '31415927'   decimal: 1   sign: 0





fdopen
────────────────────────────────────────────────────────────────────────────


Description

Opens a stream using a handle.

    #include <stdio.h>

    FILE *fdopen( int handle, char *mode );

handle                            Handle referring to open file

mode                              Type of access permitted


Remarks

The fdopen function associates an input/output stream with the file
identified by handle, thus allowing a file opened for "low-level" I/O to be
buffered and formatted. (See Section 2.7, "Input and Output," for an
explanation of stream I/O and low-level I/O.) The mode character string
specifies the type of access requested for the file, as shown below. The
following list gives the mode string used in the fopen and fdopen functions
and the corresponding oflag arguments used in the open and sopen functions.
A complete description of the mode string argument is given in the remarks
section of the fopen function.

Type String                       Equivalent Value for open/sopen
────────────────────────────────────────────────────────────────────────────
"r"                               O_RDONLY

"w"                               O_WRONLY (usually O_WRONLY | O_CREAT |
                                    O_TRUNC)

"a"                               O_WRONLY | O_APPEND (usually O_WRONLY |
                                    O_CREAT | O_APPEND)

"r+"                              O_RDWR

"w+"                              O_RDWR (usually O_RDWR | O_CREAT |
                                    O_TRUNC)

"a+"                              O_RDWR | O_APPEND (usually O_RDWR |
                                    O_APPEND | O_CREAT )

In addition to the values listed above, one of the following characters can
be included in the mode string to specify the translation mode for newlines.
These characters correspond to the constants used in the open and sopen
functions, as shown below:

Mode                              Equivalent Value for open/sopen
────────────────────────────────────────────────────────────────────────────
t                                 O_TEXT

b                                 O_BINARY

If t or b is not given in the mode string, the translation mode is defined
by the default-mode variable _fmode.

The t option is not part of the ANSI standard for fopen and fpopen, but is
instead a Microsoft extension and should not be used where ANSI portability
is desired.


Return Value

The fdopen function returns a pointer to the open stream. A null pointer
value indicates an error.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

dup, dup2, fclose, fcloseall, fopen, freopen, open


Example

    /* FDOPEN.C: This program opens a file using low-level I/O, then uses
    * fdopen to switch to stream access. It counts the lines in the file.
    */

    #include <stdlib.h>
    #include <stdio.h>
    #include <fcntl.h>
    #include <io.h>

    void main()
    {
        FILE *stream;
        int  fh, count = 0;
        char inbuf[128];

        /* Open a file handle. */
        if( (fh = open( "fdopen.c", O_RDONLY )) == -1 )
        exit( 1 );

        /* Change handle access to stream access. */
        if( (stream = fdopen( fh, "r" )) == NULL )
        exit( 1 );

        while( fgets( inbuf, 128, stream ) != NULL )
        count++;

    /* After fdopen, close with fclose, not close. */
        fclose( stream );

        printf( "Lines in file: %d\n", count );
    }


Output



    Lines in file: 31





feof
────────────────────────────────────────────────────────────────────────────


Description

Tests for end-of-file on a stream.

    #include <stdio.h>

    int feof( FILE *stream );

stream                            Pointer to FILE structure


Remarks

The feof routine (implemented as a macro) determines whether the end of
stream has been reached. Once the end of the file is reached, read
operations return an end-of-file indicator until the stream is closed or
until rewind, fsetpos, fseek, or clearerr is called against it.


Return Value

The feof function returns a nonzero value after the first read operation
that attempts to read past the end of the file. It returns 0 if the current
position is not end-of-file. There is no error return.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

clearerr, eof, ferror, perror


Example

    /* FEOF.C: This program uses feof to indicate when it reaches the end
    * of the file FEOF.C. It also checks for errors with ferror.
    */

    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        int  count, total = 0;
        char buffer[100];
        FILE *stream;

        if( (stream = fopen( "feof.c", "r" )) == NULL )
        exit( 1 );

    /* Cycle until end of file reached: */
        while( !feof( stream ) )
        {
        /* Attempt to read in 10 bytes: */
        count = fread( buffer, sizeof( char ), 100, stream );
        if( ferror( stream ) )
        {
            perror( "Read error" );
            break;
        }

        /* Total up actual bytes read */
        total += count;
        }
        printf( "Number of bytes read = %d\n", total );
        fclose( stream );
    }


Output



    Number of bytes read = 697





ferror
────────────────────────────────────────────────────────────────────────────


Description

Tests for an error on a stream.

    #include <stdio.h>

    int ferror( FILE *stream );

stream                            Pointer to FILE structure


Remarks

The ferror routine (implemented as a macro) tests for a reading or writing
error on the file associated with stream. If an error has occurred, the
error indicator for the stream remains set until the stream is closed or
rewound, or until clearerr is called against it.


Return Value

If no error has occurred on stream, ferror returns 0. Otherwise, it returns
a nonzero value.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

clearerr, eof, feof, fopen, perror


Example

    /* FEOF.C: This program uses feof to indicate when it reaches the end
    * of the file FEOF.C. It also checks for errors with ferror.
    */

    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        int  count, total = 0;
        char buffer[100];
        FILE *stream;

        if( (stream = fopen( "feof.c", "r" )) == NULL )
        exit( 1 );

    /* Cycle until end of file reached: */
        while( !feof( stream ) )
        {
        /* Attempt to read in 10 bytes: */
        count = fread( buffer, sizeof( char ), 100, stream );
        if( ferror( stream ) )
        {
            perror( "Read error" );
            break;
        }

        /* Total up actual bytes read */
        total += count;
        }
        printf( "Number of bytes read = %d\n", total );
        fclose( stream );
    }


Output



    Number of bytes read = 697





fflush
────────────────────────────────────────────────────────────────────────────


Description

Flushes a stream.

    #include <stdio.h>

    int fflush( FILE *stream );

stream                            Pointer to FILE structure


Remarks

If the file associated with stream is open for output, fflush writes to that
file the contents of the buffer associated with the stream. If the stream is
open for input, fflush clears the contents of the buffer. The fflush
function negates the effect of any prior call to ungetc against stream.

Buffers are automatically flushed when they are full, when the stream is
closed, or when a program terminates normally without closing the stream.

The stream remains open after the call. The fflush function has no effect on
an unbuffered stream.


Return Value

The fflush function returns the value 0 if the buffer was successfully
flushed. The value 0 is also returned in cases in which the specified stream
has no buffer or is open for reading only. A return value of EOF indicates
an error.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fclose, flushall, setbuf


Example

    /* FFLUSH.C */
    #include <stdio.h>
    #include <conio.h>

    void main()
    {
        int integer;
        char string[81];

    /* Read each word as a string. */
        printf( "Enter a sentence of four words with scanf: " );
        for( integer = 0; integer < 4; integer++ )
        {
        scanf( "%s", string );
        printf( "%s\n", string );
        }

        /* You must flush the input buffer before using gets. */
        fflush( stdin );
        printf( "Enter the same sentence with gets: " );
        gets( string );
        printf( "%s\n", string );
    }


Output



    Enter a sentence of four words with scanf: This is a test
    This
    is
    a
    test
    Enter the same sentence with gets: This is a test
    This is a test





fgetc, fgetchar
────────────────────────────────────────────────────────────────────────────


Description

Read a character from a stream (fgetc) or stdin (fgetchar).

    #include <stdio.h>

    int fgetc( FILE *stream );

    int fgetchar( void );

stream                            Pointer to FILE structure


Remarks

The fgetc function reads a single character from the current position of the
file associated with stream. The character is converted and returned as an
int. The function then increments the associated file pointer (if any) to
point to the next character. The fgetchar function is equivalent to
fgetc(stdin).

The fgetc and fgetchar routines are identical to getc and getchar, but they
are functions rather than macros.


Return Value

The fgetc and fgetchar functions return the character read. They return EOF
to indicate an error or end-of-file. Use feof or ferror to distinguish
between an error and an end-of-file condition.


Compatibility

fgetc

    ANSI   DOS   OS/2   UNIX   XENIX


fgetchar

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fputc, fputchar, getc, getchar


Example

    /* FGETC.C: This program uses getc to read the first 80 input characters
    * (or until the end of input) and place them into a string named buffer.
    */

    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        FILE *stream;
        char buffer[81];
        int  i, ch;

        /* Open file to read line from: */
        if( (stream = fopen( "fgetc.c", "r" )) == NULL )
        exit( 0 );

        /* Read in first 80 characters and place them in "buffer": */
        ch = fgetc( stream );
        for( i=0; (i < 80 ) && ( feof( stream ) == 0 ); i++ )
        {
        buffer[i] = ch;
        ch = fgetc( stream );
        }
        /* Add null to end string */
        buffer[i] = '\0';
        printf( "%s\n", buffer );
        fclose( stream );
    }


Output



    /* FGETC.C: This program uses getc to read the first 80 input characters
    /* (or







fgetpos
────────────────────────────────────────────────────────────────────────────


Description

Gets a stream's file-position indicator.

    #include <stdio.h>

    int fgetpos( FILE *stream, fpos_t *pos );

stream                            Target stream

pos                               Position-indicator storage


Remarks

The fgetpos function gets the current value of the stream argument's
file-position indicator and stores it in the object pointed to by pos. The
fsetpos function can later use information stored in pos to reset the stream
argument's pointer to its position at the time fgetpos was called.

The pos value is stored in an internal format and is intended for use only
by the fgetpos and fsetpos functions.


Return Value

If successful, the fgetpos function returns 0. On failure, it returns a
nonzero value and sets errno to one of the following manifest constants
(defined in STDIO.H):

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EBADF                             The specified stream is not a valid file
                                    handle or is not
                                    accessible.

EINVAL                            The stream value is invalid.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fsetpos


Example

    /* FGETPOS.C: This program opens a file and reads bytes at several
    * different locations.
    */

    #include <stdio.h>

    void main()
    {
        FILE   *stream;
        fpos_t pos;
        int    val;
        char   buffer[20];

        if( (stream = fopen( "fgetpos.c", "rb" )) == NULL )
        printf( "Trouble opening file\n" );
        else
        {
        /* Read some data and then check the position. */
        fread( buffer, sizeof( char ), 10, stream );
        if( fgetpos( stream, &pos ) != 0 )
            perror( "fgetpos error" );
        else
        {
            fread( buffer, sizeof( char ), 10, stream );
            printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );
        }

        /* Set a new position and read more data */
        pos = 140;
        if( fsetpos( stream, &pos ) != 0 )
            perror( "fsetpos error" );

        fread( buffer, sizeof( char ), 10, stream );
            printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );

        fclose( stream );
        }
    }


Output



    10 bytes at byte 10: .C: This p
    10 bytes at byte 140:   FILE   *





fgets
────────────────────────────────────────────────────────────────────────────


Description

Gets a string from a stream.

    #include <stdio.h>

    char *fgets( char *string, int n, FILE *stream );

string                            Storage location for data

n                                 Number of characters stored

stream                            Pointer to FILE structure


Remarks

The fgets function reads a string from the input stream argument and stores
it in string. Characters are read from the current stream position up to and
including the first newline character ('\n'), up to the end of the stream,
or until the number of characters read is equal to n - 1, whichever comes
first. The result is stored in string, and a null character ('\0') is
appended. The newline character, if read, is included in the string. If n is
equal to 1, string is empty (""). The fgets function is similar to the gets
function; however, gets replaces the newline character with NULL.


Return Value

If successful, the fgets function returns string. It returns NULL to
indicate either an error or end-of-file condition. Use feof or ferror to
determine whether an error occurred.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fputs, gets, puts


Example

    /* FGETS.C: This program uses fgets to display a line from a file on the
    * screen.
    */

    #include <stdio.h>

    FILE *stream;

    void main()
    {
        char line[100], *result;

    if( (stream = fopen( "fgets.c", "r" )) != NULL )
        {
        if( fgets( line, 100, stream ) == NULL)
            printf( "fgets error\n" );
        else
            printf( "%s", line);
        fclose( stream );
        }
    }


Output



    /* FGETS.C: This program uses fgets to display a line from a file on the





fieeetomsbin, fmsbintoieee
────────────────────────────────────────────────────────────────────────────


Description

Convert floating-point numbers between IEEE and Microsoft binary formats.

    #include <math.h>

    int fieeetomsbin( float *src4,  float *dst4 );

    int fmsbintoieee(  float *src4,  float *dst4 );

scr4                              Value to be converted

dst4                              Converted value


Remarks

The fieeetomsbin routine converts a single-precision floating-point number
in IEEE (Institute of Electrical and Electronic Engineers) format to
Microsoft (MS) binary format.

The fmsbintoieee routine converts a floating-point number in Microsoft
binary format to IEEE format.

These routines allow C programs (which store floating-point numbers in the
IEEE format) to use numeric data in random-access data files created with
Microsoft BASIC (which stores floating-point numbers in the Microsoft binary
format), and vice versa.

The argument src4 points to the float value to be converted. The result is
stored at the location given by dst4.

These routines do not handle IEEE NANs ("not a number") and infinities. IEEE
denormals are treated as 0 in the conversions.


Return Value

These functions return 0 if the conversion is successful and 1 if the
conversion causes an overflow.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

dieeetomsbin, dmsbintoieee





filelength
────────────────────────────────────────────────────────────────────────────


Description

Gets the length of a file.

#include <io.h>                   Required only for function declarations

    long filelength( int handle );

handle                            Target file handle


Remarks

The filelength function returns the length, in bytes, of the target file
associated with handle.


Return Value

The filelength function returns the file length in bytes. A return value of
-1L indicates an error, and an invalid handle sets errno to EBADF.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

chsize, fileno, fstat, stat


Example

    /* CHSIZE.C: This program uses filelength to report the size of a
    * file before and after modifying it with chsize.
    */

    #include <io.h>
    #include <fcntl.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <stdio.h>

    void main()
    {
        int fh, result;
        unsigned int nbytes = BUFSIZ;

    /* Open a file */
        if( (fh = open( "data", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 )
        {
        printf( "File length before: %ld\n", filelength( fh ) );
        if( chsize( fh, 329678 ) == 0 )
            printf( "Size successfully changed\n" );
        else
            printf( "Problem in changing the size\n" );
        printf( "File length after:  %ld\n", filelength( fh ) );
        close( fh );
        }
    }


Output



    File length before: 0
    Size successfully changed
    File length after:  329678





fileno
────────────────────────────────────────────────────────────────────────────


Description

Gets the file handle associated with a stream.

    #include <stdio.h>

    int fileno( FILE *stream );

stream                            Pointer to FILE structure


Remarks

The fileno routine returns the file handle currently associated with stream.
This routine is implemented as a macro.


Return Value

The fileno routine returns the file handle. There is no error return. The
result is undefined if stream does not specify an open file.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

fdopen, filelength, fopen, freopen


Example

    /* FILENO.C: This program uses fileno to obtain the file handle for
    * some standard C streams.
    */

    #include <stdio.h>

    void main()
    {
        printf( "The file handle for stdin is %d\n", fileno( stdin ) );
        printf( "The file handle for stdout is %d\n", fileno( stdout ) );
        printf( "The file handle for stderr is %d\n", fileno( stderr ) );
    }


Output



    The file handle for stdin is 0
    The file handle for stdout is 1
    The file handle for stderr is 2





_floodfill, _floodfill_w
────────────────────────────────────────────────────────────────────────────


Description

Fill an area of a display using the current color and fill mask

    #include <graph.h>

    short _far _floodfill( short x, short y, short boundary );

    short _far _floodfill_w( double wx, double wy, short boundary );

x, y                              Start point

wx, wy                            Start point

boundary                          Boundary color of area to be filled


Remarks

The functions in the _floodfill family fill an area of the display, using
the current color and fill mask. The _floodfill routine begins filling at
the view-coordinate point (x, y). The _floodfill_w routine begins filling at
the window-coordinate point (wx, wy).

If this point lies inside the figure, the interior is filled; if it lies
outside the figure, the background is filled. The point must be inside or
outside the figure to be filled, not on the figure boundary itself. Filling
occurs in all directions, stopping at the color of boundary.


Return Value

The _floodfill functions return a nonzero value if the fill is successful.
It returns 0 if the fill could not be completed, the starting point lies on
the boundary color, or the start point lies outside the clipping region.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_ellipse functions,  _getcolor,  _getfillmask,  _grstatus,  _pie functions,
_setfillmask, _setcliprgn,  _setcolor


Example

    /* FLOODFIL.C: This program draws a series of nested rectangles in
    * different colors, constantly changing the background color.
    */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void main()
    {
        int loop;
        int xvar, yvar;

        /* find a valid graphics mode */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );

        for( xvar = 163, loop = 0; xvar < 320; loop++, xvar += 3 )
        {
        _setcolor( loop % 16 );
        yvar = xvar * 5 / 8;
        _rectangle( _GBORDER, 320-xvar, 200-yvar, xvar, yvar );
        _setcolor( rand() % 16 );
        _floodfill( 0, 0, loop % 16 );
        }
        getch();
        _setvideomode( _DEFAULTMODE );
    }





floor, floorl
────────────────────────────────────────────────────────────────────────────


Description

Calculate the floor of a value.

    #include <math.h>

    double floor( double x );

    long double floorl( long double x );

x                                 Floating-point value


Remarks

The floor and floorl functions return a floating-point value representing
the largest integer that is less than or equal to x.

The floorl function is the 80-bit counterpart, and it uses the 80-bit,
10-byte coprocessor form of arguments and return values. See the reference
page on the long double functions for more details on this data type.


Return Value

These functions return the floating-point result. There is no error return.



Compatibility

floor

    ANSI   DOS   OS/2   UNIX   XENIX


floorl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

ceil, fmod


Example

    /* FLOOR.C: This example displays the largest integers less than or equal
    * to the floating-point values 2.8 and -2.8. It then shows the smallest
    * integers greater than or equal to 2.8 and -2.8.
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double y;

        y = floor( 2.8 );
        printf( "The floor of 2.8 is %f\n", y );
        y = floor( -2.8 );
        printf( "The floor of -2.8 is %f\n", y );

        y = ceil( 2.8 );
        printf( "The ceil of 2.8 is %f\n", y );
        y = ceil( -2.8 );
        printf( "The ceil of -2.8 is %f\n", y );
    }


Output



    The floor of 2.8 is 2.000000
    The floor of -2.8 is -3.000000
    The ceil of 2.8 is 3.000000
    The ceil of -2.8 is -2.000000





flushall
────────────────────────────────────────────────────────────────────────────


Description

Flushes all streams; clears all buffers.

    #include <stdio.h>

    int flushall( void );


Remarks

The flushall function writes to its associated files the contents of all
buffers associated with open output streams. All buffers associated with
open input streams are cleared of their current contents. The next read
operation (if there is one) then reads new data from the input files into
the buffers.

Buffers are automatically flushed when they are full, when streams are
closed, or when a program terminates normally without closing streams.

All streams remain open after the call to flushall.


Return Value

The flushall function returns the number of open streams (input and output).
There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fflush


Example

    /* FLUSHALL.C: This program uses flushall to flush all open buffers. */

    #include <stdio.h>

    void main()
    {
        int numflushed;

        numflushed = flushall();
        printf( "There were %d streams flushed\n", numflushed );
    }


Output



    There were 3 streams flushed





fmod, fmodl
────────────────────────────────────────────────────────────────────────────


Description

Calculates the floating-point remainder.

    #include <math.h>

    double fmod( double x, double y );

    long double fmodl( long double x, long double y );

x, y                              Floating-point values


Remarks

The fmod and fmodl functions calculate the floating-point remainder f of x /
y  such that x = i * y + f, where i is an integer,  f  has the same sign as
x, and the absolute value of  f  is less than the absolute value of y.

The fmodl function is the 80-bit counterpart; it uses the 80-bit, 10-byte
coprocessor form of arguments and return values. See the discussion of the
long double functions for more details on this data type.


Return Value

These functions return the floating-point remainder. If y is 0, the function
returns 0.


Compatibility

fmod

    ANSI   DOS   OS/2   UNIX   XENIX


fmodl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

ceil, fabs, floor


Example

    /* FMOD.C: This program displays a floating-point remainder. */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = -10.0, y = 3.0, z;

        z = fmod( x, y );
        printf( "The remainder of %.2f / %.2f is %f\n", x, y, z );
    }


Output



    The remainder of -10.00 / 3.00 is -1.000000





fopen
────────────────────────────────────────────────────────────────────────────


Description

Opens a file.

    #include <stdio.h>

    FILE *fopen( const char *filename, const char *mode );

filename                          Path name of file

mode                              Type of access permitted


Remarks

The fopen function opens the file specified by filename. The character
string mode specifies the type of access requested for the file, as follows:


Type                              Description
────────────────────────────────────────────────────────────────────────────
"r"                               Opens for reading. If the file does not
                                    exist or cannot be found, the fopen call
                                    will fail.

"w"                               Opens an empty file for writing. If the
                                    given file exists, its contents are
                                    destroyed.

"a"                               Opens for writing at the end of the file
                                    (appending); creates the file first if
                                    it doesn't exist.

"r+"                              Opens for both reading and writing. (The
                                    file must exist.)

"w+"                              Opens an empty file for both reading and
                                    writing. If the given file exists, its
                                    contents are destroyed.

"a+"                              Opens for reading and appending; creates
                                    the file first if it doesn't exist.

When a file is opened with the "a" or "a+" access type, all write operations
occur at the end of the file. Although the file pointer can be repositioned
using fseek or rewind, the file pointer is always moved back to the end of
the file before any write operation is carried out. Thus, existing data
cannot be overwritten.

When the "r+", "w+", or "a+" access type is specified, both reading and
writing are allowed (the file is said to be open for "update"). However,
when you switch between reading and writing, there must be an intervening
fsetpos, fseek, or rewind operation. The current position can be specified
for the fsetpos or fseek operation, if desired.

In addition to the values listed above, one of the following characters can
be included in mode to specify the translation mode for newline characters:


Mode                              Meaning
────────────────────────────────────────────────────────────────────────────
t                                 Open in text (translated) mode. In this
                                    mode, carriage-return-line-feed (CR-LF)
                                    combinations are translated into single
                                    line feeds (LF) on input and LF
                                    characters are translated to CR-LF
                                    combinations on output. Also, CTRL+Z is
                                    interpreted as an end-of-file character
                                    on input. In files opened for reading or
                                    for reading/writing, fopen checks for a
                                    CTRL+Z at the end of the file and
                                    removes it, if possible. This is done
                                    because using the fseek and ftell
                                    functions to move within a file that
                                    ends with a CTRL+Z may cause fseek to
                                    behave improperly near the end of the
                                    file.

b                                 Open in binary (untranslated) mode; the
                                    above translations are suppressed.

If t or b is not given in mode, the translation mode is defined by the
default-mode variable _fmode. If t or b is prefixed to the argument, the
function will fail and return NULL.

See Section 2.7, "Input and Output," for a discussion of text and binary
modes.


Return Value

The fopen function returns a pointer to the open file. A null pointer value
indicates an error.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX


Note that the t option is not part of the ANSI standard for fopen; it is a
Microsoft extension and should not be used where ANSI portability is
desired.


See Also

fclose, fcloseall, fdopen, ferror, fileno, freopen, open, setmode


Example

    /* FOPEN.C: This program opens files named "data" and "data2". It uses
    * fclose to close "data" and fcloseall to close all remaining files.
    */

    #include <stdio.h>

    FILE *stream, *stream2;

    void main()
    {
        int numclosed;

        /* Open for read (will fail if 'data' does not exist) */
        if( (stream  = fopen( "data", "r" )) == NULL )
        printf( "The file 'data' was not opened\n" );
        else
        printf( "The file 'data' was opened\n" );

        /* Open for write */
        if( (stream2 = fopen( "data2", "w+" )) == NULL )
        printf( "The file 'data2' was not opened\n" );
        else
        printf( "The file 'data2' was opened\n" );

        /* Close stream */
        if( fclose( stream ) )
        printf( "The file 'data' was not closed\n" );

        /* All other files are closed: */
        numclosed = fcloseall( );
        printf( "Number of files closed by fcloseall: %u\n", numclosed );
    }


Output



    The file 'data' was opened
    The file 'data2' was opened
    Number of files closed by fcloseall: 1





FP_OFF, FP_SEG
────────────────────────────────────────────────────────────────────────────


Description

Get or set a far-pointer offset (FP_OFF) or a far-pointer segment (FP_SEG).


    #include <dos.h>

    unsigned FP_OFF( void _far *address );

    unsigned FP_SEG( void _far *address );

address                           Far pointer to memory address


Remarks

The FP_OFF and FP_SEG macros can be used to set or get the offset and
segment, respectively, of the far pointer at address.


Return Value

The FP_OFF macro returns an offset. The FP_SEG macro returns a segment
address.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



Example

    /* FP_SEG.C: This program uses FP_SEG and FP_OFF to obtain
    * the segment and offset of the long pointer p.
    */

    #include <dos.h>
    #include <malloc.h>
    #include <stdio.h>


    void main()
    {
        void _far *p;
        unsigned int seg_val;
        unsigned int off_val;

        p = _fmalloc( 100 );        /* Points pointer at something */

        seg_val = FP_SEG( p );      /* Gets address pointed to */
        off_val = FP_OFF( p );

        printf( "Segment is %.4X; Offset is %.4X\n", seg_val, off_val );
    }


Output



    Segment is 00C7; Offset is 0016





_fpreset
────────────────────────────────────────────────────────────────────────────


Description

Resets the floating-point package.

    #include <float.h>

    void _fpreset( void );


Remarks

The _fpreset function reinitializes the floating-point-math package. This
function is usually used in conjunction with signal, system, or the exec or
spawn functions.

If a program traps floating-point error signals (SIGFPE) with signal, it can
safely recover from floating-point errors by invoking _fpreset and using
longjmp.

In DOS versions prior to 3.0, a child process executed by exec, spawn, or
system may affect the floating-point state of the parent process if an 8087
or 80287 coprocessor is used. If you are using either coprocessor, the
following precautions are recommended:


    ■   The exec, spawn, and system functions should not be called during the
        evaluation of a floating-point expression.

    ■   The _fpreset function should be called after these routines if there
        is a possibility of the child process performing any floating-point
        operations.



Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

exec functions, signal, spawn functions


Example

    /* FPRESET.C: This program uses signal to set up a routine for handling
    * floating-point errors.
    */

    #include <stdio.h>
    #include <signal.h>
    #include <setjmp.h>
    #include <stdlib.h>
    #include <float.h>
    #include <math.h>
    #include <string.h>

    jmp_buf mark;                       /* Address for long jump to jump to */
    int  fperr;                         /* Global error number */

    void fphandler( int sig, int num ); /* Prototypes */
    void fpcheck( void );

    void main()
    {
        double n1, n2, r;
        int jmpret;

        /* Set up floating point error handler. */
        if( signal( SIGFPE, fphandler ) == SIG_ERR )
        {
            fprintf( stderr, "Couldn't set SIGFPE\n" );
            abort();
        }

        /* Save stack environment for return in case of error. First time
        * through, jmpret is 0, so true conditional is executed. If an
        * error occurs, jmpret will be set to -1 and false conditional
        * will be executed.
        */
        jmpret = setjmp( mark );
        if( jmpret == 0 )
        {
            printf( "Test for invalid operation - " );
            printf( "enter two numbers: " );
            scanf( "%lf %lf", &n1, &n2 );

            r = n1 / n2;
            /* This won't be reached if error occurs. */
            printf( "\n\n%4.3g / %4.3g = %4.3g\n", n1, n2, r );

            r = n1 * n2;
            /* This won't be reached if error occurs. */
            printf( "\n\n%4.3g * %4.3g = %4.3g\n", n1, n2, r );
        }
        else
            fpcheck();
    }

    /* Handles SIGFPE (floating point error) interrupt. */
    void fphandler( int sig, int num )
    {
        /* Set global for outside check since we don't want to do I/O in the
        * handler.
        */
        fperr = num;

        /* Initialize floating-point package. */
        _fpreset();

        /* Restore calling environment and jump back to setjmp. Return -1
        * so that setjmp will return false for conditional test.
        */
        longjmp( mark, -1 );
    }

    void fpcheck()
    {
        char fpstr[30];

        switch( fperr )
        {
            case FPE_INVALID:
                strcpy( fpstr, "Invalid number" );
                break;

            case FPE_OVERFLOW:
                strcpy( fpstr, "Overflow" );
                break;

            case FPE_UNDERFLOW:
                strcpy( fpstr, "Underflow" );
                break;

            case FPE_ZERODIVIDE:
                strcpy( fpstr, "Divide by zero" );
                break;

            default:
                strcpy( fpstr, "Other floating point error" );
                break;
        }
        printf( "Error %d: %s\n", fperr, fpstr );
    }


Output



    Test for invalid operation - enter two numbers: 5 0
    Error 131: Divide by zero





fprintf
────────────────────────────────────────────────────────────────────────────


Description

Prints formatted data to a stream.

    #include <stdio.h>

    int fprintf( FILE *stream, const char *format [[, argument]]... );

stream                            Pointer to FILE structure

format                            Format-control string

argument                          Optional arguments


Remarks

The fprintf function formats and prints a series of characters and values to
the output stream. Each argument (if any) is converted and output according
to the corresponding format specification in format.

The format argument has the same form and function that it does for the
printf function; see the Remarks section for the printf function for more
information on format and argument.


Return Value

The fprintf function returns the number of characters printed, or a negative
value in the case of an output error.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

cprintf, fscanf, printf, sprintf


Example

    /* FPRINTF.C: This program uses fprintf to format various data and
    * print them to the file named FPRINTF.OUT. It then displays
    * FPRINTF.OUT on the screen using the system function to invoke
    * the DOS TYPE command.
    */

    #include <stdio.h>
    #include <process.h>

    FILE *stream;

    void main()
    {
        int    i = 10;
        double fp = 1.5;
        char   s[] = "this is a string";
        char   c = '\n';

        stream = fopen( "fprintf.out", "w" );
        fprintf( stream, "%s%c", s, c );
        fprintf( stream, "%d\n", i );
        fprintf( stream, "%f\n", fp );
        fclose( stream );
        system( "type fprintf.out" );
    }


Output



    this is a string
    10
    1.500000





fputc, fputchar
────────────────────────────────────────────────────────────────────────────


Description

Write a character to a stream (fputc) or to stdout (fputchar).

    #include <stdio.h>

    int fputc( int c, FILE *stream );

    int fputchar( int c );

c                                 Character to be written

stream                            Pointer to FILE structure


Remarks

The fputc function writes the single character c to the output stream at the
current position. The fputchar function is equivalent to fputc(c, stdout).

The fputc and fputchar routines are similar to putc and putchar, but are
functions rather than macros.


Return Value

The fputc and fputchar functions return the character written. A return
value of EOF indicates an error.


Compatibility

fputc

    ANSI   DOS   OS/2   UNIX   XENIX


fputchar

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fgetc, fgetchar, putc, putchar


Example

    /* FPUTC.C: This program uses fputc and fputchar to send a character
    * array to stdout.
    */

    #include <stdio.h>

    void main()
    {
        char strptr1[] = "This is a test of fputc!!\n";
        char strptr2[] = "This is a test of fputchar!!\n";
        char *p;

        /* Print line to stream using fputc. */
        p = strptr1;
        while( (*p != '\0') && fputc( *(p++), stdout ) != EOF )
        ;

        /* Print line to stream using fputchar. */
        p = strptr2;
        while( (*p != '\0') && fputchar( *(p++) ) != EOF )
        ;
    }


Output



    This is a test of fputc!!
    This is a test of fputchar!!





fputs
────────────────────────────────────────────────────────────────────────────


Description

Writes a string to a stream.

    #include <stdio.h>

    int fputs( const char *string, FILE *stream );

string                            String to be output

stream                            Pointer to FILE structure


Remarks

The fputs function copies string to the output stream at the current
position. The terminating null character ('\0') is not copied.


Return Value

The fputs function returns a nonnegative value if it is successful. If an
error occurs, it returns EOF.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fgets, gets, puts


Example

    /* FPUTS.C: This program uses fputs to write a single line to the
    * stdout stream.
    */

    #include <stdio.h>

    void main()
    {
        fputs( "Hello world from fputs.\n", stdout );
    }


Output



    Hello world from fputs.





fread
────────────────────────────────────────────────────────────────────────────


Description

Reads data from a stream.

    #include <stdio.h>

    size_t fread( void *buffer, size_t size, size_t count, FILE *stream );

buffer                            Storage location for data

size                              Item size in bytes

count                             Maximum number of items to be read

stream                            Pointer to FILE structure


Remarks

The fread function reads up to count items of size bytes from the input
stream and stores them in buffer. The file pointer associated with stream
(if there is one) is increased by the number of bytes actually read.

If the given stream is opened in text mode, carriage-return-line-feed pairs
are replaced with single line-feed characters. The replacement has no effect
on the file pointer or the return value.

The file-pointer position is indeterminate if an error occurs. The value of
a partially read item cannot be determined.


Return Value

The fread function returns the number of full items actually read, which may
be less than count if an error occurs or if the file end is encountered
before reaching count.

The feof or ferror function should be used to distinguish a read error from
an end-of-file condition. If size or count is 0, fread returns 0 and the
buffer contents are unchanged.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fwrite, read


Example

    /* FREAD.C: This program opens a file named FREAD.OUT and writes 25
    * characters to the file. It then tries to open FREAD.OUT and
    * read in 25 characters. If the attempt succeeds, the program
    * displays the number of actual items read.
    */

    #include <stdio.h>

    void main()
    {
        FILE *stream;
        char list[30];
        int  i, numread, numwritten;

        /* Open file in text mode: */
        if( (stream = fopen( "fread.out", "w+t" )) != NULL )
        {
        for ( i = 0; i < 25; i++ )
            list[i] = 'z' - i;
        /* Write 25 characters to stream */
        numwritten = fwrite( list, sizeof( char ), 25, stream );
        printf( "Wrote %d items\n", numwritten );
        fclose( stream );
        }
        else
        printf( "Problem opening the file\n" );

        if( (stream = fopen( "fread.out", "r+t" )) != NULL )
        {
        /* Attempt to read in 25 characters */
        numread = fread( list, sizeof( char ), 25, stream );
        printf( "Number of items read = %d\n", numread );
        printf( "Contents of buffer = %.25s\n", list );
        fclose( stream );
        }
        else
        printf( "Was not able to open the file\n" );
    }


Output



    Wrote 25 items
    Number of items read = 25
    Contents of buffer = zyxwvutsrqponmlkjihgfedcb





free Functions
────────────────────────────────────────────────────────────────────────────


Description

Deallocate a memory block.

#include <stdlib.h>               For ANSI compatibility (free only)

#include <malloc.h>               Required only for function declarations

    void free( void *memblock );

    void _bfree( _segment seg, void _based( void ) *memblock );

    void _ffree( void _far *memblock );

    void _nfree( void _near *memblock );

memblock                          Allocated memory block

seg                               Based-heap segment selector


Remarks

The free family of functions deallocates a memory block. The argument
memblock points to a memory block previously allocated through a call to
calloc, malloc, or realloc. The number of bytes freed is the number of bytes
specified when the block was allocated (or reallocated, in the case of
realloc). After the call, the freed block is available for allocation.

The seg argument specifies the based heap containing the memory block to be
freed by the _bfree function.

Attempting to free an invalid pointer may affect subsequent allocation and
cause errors. An invalid pointer is one not allocated with the appropriate
call.

The following restrictions apply to use of the free, _bfree, _ffree, and
_nfree functions:

Blocks allocated with:            Should be freed with:
────────────────────────────────────────────────────────────────────────────
calloc, malloc, realloc           free

_bcalloc, _bmalloc, _brealloc     _bfree

_fcalloc, _fmalloc, _frealloc     _ffree

_ncalloc, _nmalloc, _nrealloc     _nfree

A NULL pointer argument is ignored.

In large data models (compact-, large-, and huge-model programs), free maps
to _ffree. In small data models (tiny-, small-, and medium-model programs),
free maps to _nfree.

The various free functions deallocate a memory block in the segments shown
in the list below:

Function                          Data Segment
────────────────────────────────────────────────────────────────────────────
free                              Depends on data model of program

_bfree                            Based heap specified by seg value

_ffree                            Far heap (outside default data segment)

_nfree                            Near heap (inside default data segment)


Return Value

None.


Compatibility

free

    ANSI   DOS   OS/2   UNIX   XENIX


_bfree, _ffree, _nfree

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

calloc functions, malloc functions, realloc functions


Example

    /* MALLOC.C: This program allocates memory with malloc, then frees
    * the memory with free.
    */

    #include <stdlib.h>         /* Definition of _MAX_PATH */
    #include <stdio.h>
    #include <malloc.h>

    void main()
    {
        char *string;

        /* Allocate space for a path name */
        string = malloc( _MAX_PATH );
        if( string == NULL )
        printf( "Insufficient memory available\n" );
        else
        printf( "Memory space allocated for path name\n" );
        free( string );
        printf( "Memory freed\n" );
    }


Output



    Memory space allocated for path name
    Memory freed





_freect
────────────────────────────────────────────────────────────────────────────


Description

Returns the amount of memory available for memory allocation.

#include <malloc.h>               Required only for function declarations

    unsigned int _freect( size_t size );

size                              Item size in bytes


Remarks

The _freect function tells you how much memory is available for dynamic
memory allocation in the near heap. It does so by returning the approximate
number of times your program can call _nmalloc (or malloc in small data
models) to allocate an item size bytes long in the near heap (default data
segment).


Return Value

The _freect function returns the number of calls as an unsigned integer.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

calloc functions, _expand functions, malloc functions, _memavl, _msize
functions,  realloc functions


Example

    /* FREECT.C: This program determines how much free space is available for
    * integers in the default data segment. Then it allocates space for
    * 1,000 integers and checks the space again, using _freect.
    */

    #include <malloc.h>
    #include <stdio.h>

    void main()
    {
        int i;

        /* First report on the free space: */
        printf( "Integers (approximate) available on heap: %u\n\n",
                _freect( sizeof( int ) ) );

        /* Allocate space for 1000 integers: */
        for( i = 0; i < 1000; ++i )
        malloc( sizeof( int ) );

    /* Report again on the free space: */
        printf( "After allocating space for 1000 integers:\n" );
        printf( "Integers (approximate) available on heap: %u\n\n",
                _freect( sizeof( int ) ) );

    }


Output



    Integers (approximate) available on heap: 15212

    After allocating space for 1000 integers:
    Integers (approximate) available on heap: 14084





freopen
────────────────────────────────────────────────────────────────────────────


Description

Reassigns a file pointer.

    #include <stdio.h>

    FILE *freopen( const char *filename, const char *mode, FILE *stream );

filename                          Path name of new file

mode                              Type of access permitted

stream                            Pointer to FILE structure


Remarks

The freopen function closes the file currently associated with stream and
reassigns stream to the file specified by filename. The freopen function is
typically used to redirect the pre-opened files stdin, stdout, and stderr to
files specified by the user. The new file associated with stream is opened
with mode, which is a character string specifying the type of access
requested for the file, as follows:

Type                              Description
────────────────────────────────────────────────────────────────────────────
"r"                               Opens for reading. If the file does not
                                    exist or cannot be found, the freopen
                                    call fails.

"w"                               Opens an empty file for writing. If the
                                    given file exists, its contents are
                                    destroyed.

"a"                               Opens for writing at the end of the file
                                    (appending); creates the file first if
                                    it does not exist.

"r+"                              Opens for both reading and writing. (The
                                    file must exist.)

"w+"                              Opens an empty file for both reading and
                                    writing. If the given file exists, its
                                    contents are destroyed.

"a+"                              Opens for reading and appending; creates
                                    the file first if it does not exist.

Use the "w" and "w+" types with care, as they can destroy existing files.

When a file is opened with the "a" or "a+" access type, all write operations
take place at the end of the file. Although the file pointer can be
repositioned using fseek or rewind, the file pointer is always moved back to
the end of the file before any write operation is carried out. Thus,
existing data cannot be overwritten.

When the "r+", "w+", or "a+" access type is specified, both reading and
writing are allowed (the file is said to be open for "update"). However,
when you switch between reading and writing, there must be an intervening
fsetpos, fseek, or rewind operation. The current position can be specified
for the fsetpos or fseek operation, if desired.

In addition to the values listed above, one of the following characters may
be included in the mode string to specify the translation mode for newlines.


Mode                              Meaning
────────────────────────────────────────────────────────────────────────────
t                                 Open in text (translated) mode;
                                    carriage-return-line-feed
                                    (CR-LF) combinations are translated into
                                    single line-feed (LF) characters on
                                    input; LF characters are translated to
                                    CR-LF combinations on output. Also,
                                    CTRL+Z is interpreted as an end-of-file
                                    character on input. In files opened for
                                    reading, or writing and reading, the
                                    run-time library checks for a CTRL+Z at
                                    the end of the file and removes it, if
                                    possible. This is done because using the
                                    fseek and ftell functions to move within
                                    a file may cause fseek to behave
                                    improperly near the end of the file.

b                                 Open in binary (untranslated) mode; the
                                    above translations are suppressed.

If t or b is not given in the mode string, the translation mode is defined
by the default mode variable _fmode.

See Section 2.7, "Input and Output," for a discussion of text and binary
modes.


Return Value

The freopen function returns a pointer to the newly opened file. If an error
occurs, the original file is closed and the function returns a NULL pointer
value.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX


The t option is not part of the ANSI standard for freopen; it is a Microsoft
extension that should not be used where ANSI portability is desired.


See Also

fclose, fcloseall, fdopen, fileno, fopen, open, setmode


Example

    /* FREOPEN.C: This program reassigns stdaux to the file
    * named FREOPEN.OUT and writes a line to that file.
    */

    #include <stdio.h>
    #include <stdlib.h>

    FILE *stream;

    void main()
    {

        /* Reassign "stdaux" to "freopen.out": */
        stream = freopen( "freopen.out", "w", stdaux );

        if( stream == NULL )
        fprintf( stdout, "error on freopen\n" );
        else
        {
        fprintf( stream, "This will go to the file 'freopen.out'\n" );
        fprintf( stdout, "successfully reassigned\n" );
        fclose( stream );
        }
        system( "type freopen.out" );
    }


Output



    successfully reassigned
    This will go to the file 'freopen.out'





frexp, frexpl
────────────────────────────────────────────────────────────────────────────


Description

Get the mantissa and exponent of a floating-point number.

    #include <math.h>

    double frexp( double x, int *expptr );

    long double frexpl( long double x, int *expptr );

x                                 Floating-point value

expptr                            Pointer to stored integer exponent


Remarks

The frexp and frexpl functions break down the floating-point value (x) into
a mantissa (m) and an exponent (n), such that the absolute value of m is
greater than or equal to 0.5 and less than 1.0, and x = m*2n. The integer
exponent n is stored at the location pointed to by expptr.

The frexpl function is the 80-bit counterpart and uses an 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.


Return Value

These functions return the mantissa. If x is 0, the function returns 0 for
both the mantissa and the exponent. There is no error return.


Compatibility

frexp

    ANSI   DOS   OS/2   UNIX   XENIX


frexpl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

ldexp functions, modf


Example

    /* FREXP.C: This program calculates frexp( 16.4, &n ), then displays y
    * and n.
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x, y;
        int n;

        x = 16.4;
        y = frexp( x, &n );
        printf( "frexp( %f, &n ) = %f, n = %d\n", x, y, n );
    }


Output



    frexp( 16.400000, &n ) = 0.512500, n = 5





fscanf
────────────────────────────────────────────────────────────────────────────


Description

Reads formatted data from a stream.

    #include <stdio.h>

    int fscanf( FILE *stream, const char *format [[, argument]]...  )

stream                            Pointer to FILE structure

format                            Format-control string

argument                          Optional arguments


Remarks

The fscanf function reads data from the current position of stream into the
locations given by argument (if any). Each argument must be a pointer to a
variable with a type that corresponds to a type specifier in format. The
format controls the interpretation of the input fields and has the same form
and function as the format argument for the scanf function; see scanf for a
description of format.


Return Value

The fscanf function returns the number of fields that were successfully
converted and assigned. The return value does not include fields that were
read but not assigned.

The return value is EOF for an error or end-of-file on stream before the
first conversion. A return value of 0 means that no fields were assigned.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

cscanf, fprintf, scanf, sscanf


Example

    /* FSCANF.C: This program writes formatted data to a file. It
    * then uses fscanf to read the various data back from the file.
    */

    #include <stdio.h>

    FILE *stream;

    void main()
    {
        long l;
        float fp;
        char s[81];
        char c;
        int result;

        stream = fopen( "fscanf.out", "w+" );
        if( stream == NULL )
        printf( "The file fscanf.out was not opened\n" );
        else
        {
        fprintf( stream, "%s %ld %f%c", "a-string", 65000, 3.14159, 'x' );

        /* Set pointer to beginning of file: */
        fseek( stream, 0L, SEEK_SET );

        /* Read data back from file: */
        fscanf( stream, "%s", s );
        fscanf( stream, "%ld", &l );
        fscanf( stream, "%f", &fp );
        fscanf( stream, "%c", &c );

        /* Output data read: */
        printf( "%s\n", s );
        printf( "%ld\n", l );
        printf( "%f\n", fp );
        printf( "%c\n", c );

        fclose( stream );
        }
    }


Output



    a-string
    65000
    3.141590
    x





fseek
────────────────────────────────────────────────────────────────────────────


Description

Moves the file pointer to a specified location.

    #include <stdio.h>

    int fseek( FILE *stream, long offset, int origin );

stream                            Pointer to FILE structure

offset                            Number of bytes from origin

origin                            Initial position


Remarks

The fseek function moves the file pointer (if any) associated with stream to
a new location that is offset bytes from origin. The next operation on the
stream takes place at the new location. On a stream open for update, the
next operation can be either a read or a write.

The argument origin must be one of the following constants defined in
STDIO.H:

Origin                            Definition
────────────────────────────────────────────────────────────────────────────
SEEK_CUR                          Current position of file pointer

SEEK_END                          End of file

SEEK_SET                          Beginning of file

The fseek function can be used to reposition the pointer anywhere in a file.
The pointer can also be positioned beyond the end of the file. However, an
attempt to position the pointer in front of the beginning of the file causes
an error.

The fseek function clears the end-of-file indicator and negates the effect
of any prior ungetc calls against stream.

When a file is opened for appending data, the current file position is
determined by the last I/O operation, not by where the next write would
occur. If no I/O operation has yet occurred on a file opened for appending,
the file position is the start of the file.

For streams opened in text mode, fseek has limited use because
carriage-return-line-feed translations can cause fseek to produce unexpected
results. The only fseek operations guaranteed to work on streams opened in
text mode are the following:


    ■   Seeking with an offset of 0 relative to any of the origin values

    ■   Seeking from the beginning of the file with an offset value returned
        from a call to ftell



Return Value

If successful, fseek returns 0. Otherwise, it returns a nonzero value. On
devices incapable of seeking, the return value is undefined.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

ftell, lseek, rewind


Example

    /* FSEEK.C: This program opens the file FSEEK.OUT and
    * moves the pointer to the file's beginning.
    */

    #include <stdio.h>

    void main()
    {
        FILE *stream;
        char line[81];
        int  result;

        stream = fopen( "fseek.out", "w+" );
        if( stream == NULL )
        printf( "The file fseek.out was not opened\n" );
        else
        {
        fprintf( stream, "The fseek begins here: "
                            "This is the file 'fseek.out'.\n" );
        result = fseek( stream, 23L, SEEK_SET);
        if( result )
            perror( "Fseek failed" );
        else
        {
            printf( "File pointer is set to middle of first line.\n" );
            fgets( line, 80, stream );
            printf( "%s", line );
        }
        fclose( stream );
        }
    }


Output



    File pointer is set to middle of first line.
    This is the file 'fseek.out'.





fsetpos
────────────────────────────────────────────────────────────────────────────


Description

Sets the stream-position indicator.

    #include <stdio.h>

    int fsetpos( FILE *stream, const fpos_t *pos ) ;

stream                            Target stream

pos                               Position-indicator storage


Remarks

The fsetpos function sets the file-position indicator for stream to the
value of pos, which is obtained in a prior call to fgetpos against stream.

The function clears the end-of-file indicator and undoes any effects of the
ungetc function on stream. After calling fsetpos, the next operation on
stream may be either input or output.


Return Value

If successful, the fsetpos function returns 0. On failure, the function
returns a nonzero value and sets errno to one of the following manifest
constants (defined in ERRNO.H):

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
EBADF                             The object that stream points to is not
                                    a valid file handle, or the file is not
                                    accessible.

EINVAL                            An invalid stream value was passed.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fgetpos


Example

    /* FGETPOS.C: This program opens a file and reads bytes at several
    * different locations.
    */

    #include <stdio.h>

    void main()
    {
        FILE   *stream;
        fpos_t pos;
        int    val;
        char   buffer[20];

        if( (stream = fopen( "fgetpos.c", "rb" )) == NULL )
        printf( "Trouble opening file\n" );
        else
        {
        /* Read some data and then check the position. */
        fread( buffer, sizeof( char ), 10, stream );
        if( fgetpos( stream, &pos ) != 0 )
            perror( "fgetpos error" );
        else
        {
            fread( buffer, sizeof( char ), 10, stream );
            printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );
        }

        /* Set a new position and read more data. */
        pos = 140;
        if( fsetpos( stream, &pos ) != 0 )
            perror( "fsetpos error" );

        fread( buffer, sizeof( char ), 10, stream );
            printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );

        fclose( stream );
        }
    }


Output



    10 bytes at byte 10: .C: This p
    10 bytes at byte 140:   FILE   *





_fsopen
────────────────────────────────────────────────────────────────────────────


Description

Opens a stream with file sharing.

#include <stdio.h>

#include <share.h>                shflag constants

    FILE *_fsopen( const char *filename, const char *mode, int shflag );

filename                          File name to open

mode                              Type of access permitted

shflag                            Type of sharing allowed


Remarks

The _fsopen function opens the file specified by filename as a stream and
prepares the file for subsequent shared reading or writing, as defined by
the mode and shflag arguments.

The character string mode specifies the type of access requested for the
file, as follows:

Type                              Description
────────────────────────────────────────────────────────────────────────────
"r"                               Opens for reading. If the file does not
                                    exist or cannot be found, the _fsopen
                                    call will fail.

"w"                               Opens an empty file for writing. If the
                                    given file exists, its contents are
                                    destroyed.

"a"                               Opens for writing at the end of the file
                                    (appending); creates the file first if
                                    it does not exist.

"r+"                              Opens for both reading and writing. (The
                                    file must exist.)

"w+"                              Opens an empty file for both reading and
                                    writing. If the given file exists, its
                                    contents are destroyed.

"a+"                              Opens for reading and appending; creates
                                    the file first if it does not exist.

Use the "w" and "w+" types with care, as they can destroy existing files.

When a file is opened with the "a" or "a+" access type, all write operations
occur at the end of the file. Although the file pointer can be repositioned
using fseek or rewind, the file pointer is always moved back to the end of
the file before any write operation is carried out. Thus, existing data
cannot be overwritten.

When the "r+", "w+", or "a+"  access type is specified, both reading and
writing are allowed (the file is said to be open for "update"). However,
when switching between reading and writing, there must be an intervening
fsetpos, fseek, or rewind operation. The current position can be specified
for the fsetpos or fseek operation, if desired.

In addition to the values listed above, one of the following characters can
be included in mode to specify the translation mode for newlines:

Mode                              Meaning
────────────────────────────────────────────────────────────────────────────
t                                 Open in text (translated) mode. In this
                                    mode, carriage-return-line-feed (CR-LF)
                                    combinations are translated into single
                                    line feeds (LF) on input and LF
                                    characters are translated to CR-LF
                                    combinations on output. Also, CTRL+Z is
                                    interpreted as an end-of-file character
                                    on input. In files opened for reading or
                                    reading/writing, _fsopen checks for a
                                    CTRL+Z at the end of the file and
                                    removes it, if possible. This is done
                                    because using the fseek and ftell
                                    functions to move within a file that
                                    ends with a CTRL+Z may cause fseek to
                                    behave improperly near the end of the
                                    file.

b                                 Open in binary (untranslated) mode; the
                                    above translations are suppressed.

If t or b is not given in mode, the translation mode is defined by the
default-mode variable _fmode. If t or b is prefixed to the argument, the
function will fail and will return NULL.

See Section 2.7, "Input and Output," for a discussion of text and binary
modes.

The argument shflag is a constant expression consisting of one of the
following manifest constants, defined in SHARE.H.  If SHARE.COM ─or
SHARE.EXE for some versions of DOS─ is not installed, DOS ignores the
sharing mode. (See your system documentation for detailed information about
sharing modes.)

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
SH_COMPAT                         Sets compatibility mode (not available
                                    in OS/2)

SH_DENYNO                         Permits read and write access

SH_DENYRD                         Denies read access to file

SH_DENYRW                         Denies read and write access to file

SH_DENYWR                         Denies write access to file

The _fsopen function should be used only under OS/2 and DOS versions 3.0 and
later. Under earlier versions of DOS, the shflag argument is ignored.


Return Value

The _fsopen function returns a pointer to the stream. A NULL pointer value
indicates an error.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

fclose, fcloseall, fdopen, ferror, fileno, fopen, freopen, open, setmode,
sopen


Example

    /* FSOPEN.C: This program opens files named "data" and "data2". It uses
    * fclose to close "data" and fcloseall to close all remaining files.
    */

    #include <stdio.h>
    #include <share.h>

    FILE *stream;

    void main()
    {
        FILE *stream;

        /* Open output file for writing. Using _fsopen allows us to ensure
        * that no one else writes to the file while we are writing to it.
        */
        if( (stream = _fsopen( "outfile", "wt", SH_DENYWR )) != NULL )
        {
        fprintf( stream, "No one else in the network can write "
                            "to this file until we are done.\n" );
        fclose( stream );
        }
        /* Now others can write to the file while we read it. */
        system( "type outfile" );
    }


Output



    No one else in the network can write to this file until we are done.





fstat
────────────────────────────────────────────────────────────────────────────


Description

Gets information about an open file.

    #include <sys\types.h>

    #include <sys\stat.h>

    int fstat( int handle, struct stat *buffer );

handle                            Handle of open file

buffer                            Pointer to structure to store results


Remarks

The fstat function obtains information about the open file associated with
handle and stores it in the structure pointed to by buffer. The structure,
whose type stat is defined in SYS\STAT.H, contains the following fields:


Field                             Value
────────────────────────────────────────────────────────────────────────────
st_atime                          Time of last modification of file (same
                                    as st_mtime and st_ctime).

st_ctime                          Time of last modification of file (same
                                    as st_atime and st_mtime).

st_dev                            Either the drive number of the disk
                                    containing the file, or handle in the
                                    case of a device (same as st_rdev).

st_mode                           Bit mask for file-mode information. The
                                    S_IFCHR bit is set if
                                    handle refers to a device. The S_IFREG
                                    bit is set if handle refers to an
                                    ordinary file. The read/write bits are
                                    set according to the file's permission
                                    mode. (S_IFCHR and other constants are
                                    defined in SYS\ STAT.H.)

st_mtime                          Time of last modification of file (same
                                    as st_atime and st_ctime).

st_nlink                          Always 1.

st_rdev                           Either the drive number of the disk
                                    containing the file, or handle in the
                                    case of a device (same as st_dev).

st_size                           Size of the file in bytes.

If handle refers to a device, the size and time fields in the stat structure
are not meaningful.


Return Value

The fstat function returns the value 0 if the file-status information is
obtained. A return value of -1 indicates an error; in this case, errno is
set to EBADF, indicating an invalid file handle.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX


In OS/2, the st_dev field does not contain meaningful information. In fact,
it is set to zero. OS/2 provides no way to recover the host drive from just
the open file handle.


See Also

access, chmod, filelength, stat


Example

    /* FSTAT.C: This program uses fstat to report the size of a file
    * named FSTAT.OUT.
    */

    #include <io.h>
    #include <fcntl.h>
    #include <time.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>

    void main()
    {
        struct stat buf;
        int fh, result;
        char buffer[] = "A line to output";

        if( (fh = open( "fstat.out", O_CREAT | O_WRONLY | O_TRUNC )) == -1 )
        exit( 1 );
        write( fh, buffer, strlen( buffer ) );

        /* Get data associated with "fh": */

        result = fstat( fh, &buf );

    /* Check if statistics are valid: */
        if( result != 0 )
        printf( "Bad file handle\n" );
        else
        {
        printf( "File size     : %ld\n", buf.st_size );
        printf( "Drive number  : %d\n", buf.st_dev );
        printf( "Time modified : %s", ctime( &buf.st_atime ) );
        }
        close( fh );
    }


Output



    File size     : 16
    Drive number  : 0
    Time modified : Thu Jun 15 21:38:46 1989





ftell
────────────────────────────────────────────────────────────────────────────


Description

Gets the current position of a file pointer.

    #include <stdio.h>

    long ftell( FILE *stream );

stream                            Target FILE structure


Remarks

The ftell function gets the current position of the file pointer (if any)
associated with stream. The position is expressed as an offset relative to
the beginning of the stream.

Note that when a file is opened for appending data, the current file
position is determined by the last I/O operation, not by where the next
write would occur. For example, if a file is opened for an append and the
last operation was a read, the file position is the point where the next
read operation would start, not where the next write would start. (When a
file is opened for appending, the file position is moved to end-of-file
before any write operation.) If no I/O operation has yet occurred on a file
opened for appending, the file position is the beginning of the file.


Return Value

The ftell function returns the current file position. The value returned by
ftell may not reflect the physical byte offset for streams opened in text
mode, since text mode causes carriage-return-line-feed translation. Use
ftell in conjunction with the fseek function to return to file locations
correctly. On error, the function returns -1L and errno is set to one of the
following constants, defined in ERRNO.H:

Constant                          Description
────────────────────────────────────────────────────────────────────────────
EBADF                             Bad file number. The stream argument is
                                    not a valid file-handle value or does
                                    not refer to an open file.

EINVAL                            Invalid argument. An invalid stream
                                    argument was passed to the function.

On devices incapable of seeking (such as terminals and printers), or when
stream does not refer to an open file, the return value is undefined.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fgetpos, fseek, lseek, tell


Example

    /* FTELL.C: This program opens a file named FTELL.C for reading and
    * tries to read 100 characters. It then uses ftell to determine the
    * position of the file pointer and displays this position.
    */

    #include <stdio.h>

    FILE *stream;

    void main()
    {
        long position;
        char list[100];

        if( (stream = fopen( "ftell.c", "rb" )) != NULL )
        {
        /* Move the pointer by reading data: */
        fread( list, sizeof( char ), 100, stream );

        /* Get position after read: */
        position = ftell( stream );
        printf( "Position after trying to read 100 bytes: %ld\n", position
);
        fclose( stream );
        }
    }


Output



    Position after trying to read 100 bytes: 100





ftime
────────────────────────────────────────────────────────────────────────────


Description

Gets the current time.

    #include <sys\types.h>

    #include <sys\timeb.h>

    void ftime( struct timeb *timeptr );

timeptr                           Pointer to structure defined in
                                    SYS\TIMEB.H


Remarks

The ftime function gets the current time and stores it in the structure
pointed to by timeptr. The timeb structure is defined in SYS\TIMEB.H. It
contains four fields (dstflag, millitm, time, and timezone), which have the
following values:

Field                             Value
────────────────────────────────────────────────────────────────────────────
dstflag                           Nonzero if daylight saving time is
                                    currently in effect for the local time
                                    zone. (See tzset for an explanation of
                                    how daylight saving time is determined.)

millitm                           Fraction of a second in milliseconds.
                                    The last digit is always 0 since millitm
                                    is incremented to the nearest
                                    one-hundredth of a second.

time                              Time in seconds since 00:00:00 Greenwich
                                    mean time, January 1, 1970.

timezone                          Difference in minutes, moving westward,
                                    between Greenwich mean time and local
                                    time. The value of timezone is set from
                                    the value of the global variable
                                    timezone (see tzset).


Return Value

The ftime function gives values to the fields in the structure pointed to by
timeptr. It does not return a value.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

asctime, ctime, gmtime, localtime, time, tzset


Example

    /* FTIME.C: This program uses ftime to obtain the current time
    * and then stores this time in timebuffer.
    */

    #include <stdio.h>
    #include <sys\timeb.h>
    #include <time.h>

    void main()
    {

        struct timeb timebuffer;
        char *timeline;

        ftime( &timebuffer );
        timeline = ctime( & ( timebuffer.time ) );

        printf( "The time is %.19s.%hu %s",
                timeline, timebuffer.millitm, &timeline[20] );
    }


Output



    The time is Thu Jun 15 21:40:34.870 1989





_fullpath
────────────────────────────────────────────────────────────────────────────


Description

Makes an absolute path name from a relative path name.

    #include <stdlib.h>

    char *_fullpath( char *buffer, const char *pathname, size_t maxlen );

buffer                            Full path-name buffer

pathname                          Relative path name

maxlen                            Length of the buffer pointed to by
                                    buffer


Remarks

The _fullpath routine converts the partial path stored in pathname to a
fully qualified path that is stored in buffer. Unlike _makepath, the
_fullpath routine can be used with .\ and ..\ in the path.

If the length of the fully qualified path is greater than the value of
maxlen, then NULL is returned; otherwise, the address of buffer is returned.


If the buffer is NULL, _fullpath will allocate a buffer of MAX_PATH size and
the maxlen argument is ignored.

If the pathname argument specifies a disk drive, the current directory of
this drive is combined with the path. If the drive is not valid, _fullpath
returns NULL.


Return Value

The _fullpath function returns a pointer to the buffer containing the
absolute path (buffer). If there is an error, _fullpath returns NULL.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

getcwd,  _getdcwd,  _makepath,  _splitpath


Example

    /* FULLPATH.C: This program demonstrates how _fullpath creates a full
    * path from a partial path.
    */

    #include <stdio.h>
    #include <conio.h>
    #include <stdlib.h>
    #include <direct.h>

    char full[_MAX_PATH], part[_MAX_PATH];

    void main()
    {
        while( 1 )
        {
            printf( "Enter partial path or ENTER to quit: " );
            gets( part );
            if( part[0] == 0 )
                break;

            if( _fullpath( full, part, _MAX_PATH ) != NULL )
                printf( "Full path is: %s\n", full );
            else
                printf( "Invalid path\n" );
        }
    }


Output



    Enter partial path or ENTER to quit: ..
    Full path is: C:\
    Enter partial path or ENTER to quit: ..\include
    Full path is: C:\include
    Enter partial path or ENTER to quit: p:
    Full path is: P:\
    Enter partial path or ENTER to quit: fullpath.c
    Full path is: C:\LIBREF\fullpath.c
    Enter partial path or ENTER to quit:





fwrite
────────────────────────────────────────────────────────────────────────────


Description

Writes data to a stream.

    #include <stdio.h>

    size_t fwrite( const void *buffer, size_t size, size_t count, FILE *stream
    );

buffer                            Pointer to data to be written

size                              Item size in bytes

count                             Maximum number of items to be written

stream                            Pointer to FILE structure


Remarks

The fwrite function writes up to count items, of length size each, from
buffer to the output stream. The file pointer associated with stream (if
there is one) is incremented by the number of bytes actually written.

If stream is opened in text mode, each carriage return is replaced with a
carriage-return-line-feed pair. The replacement has no effect on the return
value.


Return Value

The fwrite function returns the number of full items actually written, which
may be less than count if an error occurs. Also, if an error occurs, the
file-position indicator cannot be determined.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fread, write


Example

    /* FREAD.C: This program opens a file named FREAD.OUT and writes 25
    * characters to the file. It then tries to open FREAD.OUT and
    * read in 25 characters. If the attempt succeeds, the program
    * displays the number of actual items read.
    */

    #include <stdio.h>



    void main()
    {
        FILE *stream;
        char list[30];
        int  i, numread, numwritten;

        /* Open file in text mode: */
        if( (stream = fopen( "fread.out", "w+t" )) != NULL )
        {
        for ( i = 0; i < 25; i++ )
            list[i] = 'z' - i;
        /* Write 25 characters to stream */
        numwritten = fwrite( list, sizeof( char ), 25, stream );
        printf( "Wrote %d items\n", numwritten );
        fclose( stream );
        }
        else
        printf( "Problem opening the file\n" );

        if( (stream = fopen( "fread.out", "r+t" )) != NULL )
        {
        /* Attempt to read in 25 characters */
        numread = fread( list, sizeof( char ), 25, stream );
        printf( "Number of items read = %d\n", numread );
        printf( "Contents of buffer = %.25s\n", list );
        fclose( stream );
        }
        else
        printf( "Was not able to open the file\n" );
    }


Output



    Wrote 25 items
    Number of items read = 25
    Contents of buffer = zyxwvutsrqponmlkjihgfedcb





gcvt
────────────────────────────────────────────────────────────────────────────


Description

Converts a floating-point value to a string, which it stores in a buffer.

#include <stdlib.h>               Required only for function declarations

    char *gcvt( double value, int digits, char *buffer );

value                             Value to be converted

digits                            Number of significant digits stored

buffer                            Storage location for result


Remarks

The gcvt function converts a floating-point value to a character string and
stores the string in buffer. The buffer should be large enough to
accommodate the converted value plus a terminating null character ('\0'),
which is appended automatically. There is no provision for overflow.

The gcvt function attempts to produce digits significant digits in decimal
format. If this is not possible, it produces digits significant digits in
exponential format. Trailing zeros may be suppressed in the conversion.


Return Value

The gcvt function returns a pointer to the string of digits. There is no
error return.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

atof, atoi, atol, ecvt, fcvt


Example

    /* GCVT.C: This program converts -3.1415e5 to its string representation.
    */

    #include <stdlib.h>
    #include <stdio.h>


    void main()
    {
        char buffer[50];
        double source = -3.1415e5;

        gcvt( source, 7, buffer );
        printf( "source: %f  buffer: '%s'\n", source, buffer );
    }


Output



    source: -314150.000000  buffer: '-314150.'





_getactivepage
────────────────────────────────────────────────────────────────────────────


Description

Gets the current active page number.

    #include <graph.h>

    short _far _getactivepage( void );


Remarks

The _getactivepage function returns the number of the current active page.


Return Value

The function returns the number of the current active page. All hardware
combinations support at least one page (page number 0). In OS/2, only page 0
is valid.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getactivepage,  _getvideoconfig,  _getvisualpage,  _grstatus,
_setactivepage, _setvideomode,  _setvisualpage


Example

    /* PAGE.C illustrates video page functions including:
    *      _getactivepage  _getvisualpage  _setactivepage  _setvisualpage
    */

    #include <conio.h>
    #include <graph.h>
    #include <stdlib.h>

    void main()
    {
        short  oldvpage, oldapage, page, row, col, line;
        struct videoconfig vc;
        char   buf[80];

        _getvideoconfig( &vc );
        if( vc.numvideopages < 4 )
            exit( 1 );              /* Fail for OS/2 or monochrome. */
        oldapage  = _getactivepage();
        oldvpage  = _getvisualpage();
        _displaycursor( _GCURSOROFF );


    /* Draw arrows in different place on each page. */
        for( page = 1; page < 4; page++ )
        {
        _setactivepage( page );
        _settextposition( 12, 16 * page );
        _outtext( ">>>>>>>>" );
        }

        while( !kbhit() )
        /* Cycle through pages 1 to 3 to show moving image. */
        for( page = 1; page < 4; page++ )
            _setvisualpage( page );
        getch();

        /* Restore original page (normally 0) to restore screen. */
        _setactivepage( oldapage );
        _setvisualpage( oldvpage );
        _displaycursor( _GCURSORON );
    }





_getarcinfo
────────────────────────────────────────────────────────────────────────────


Description

Determines the endpoints in viewport coordinates of the most recently drawn
arc or pie.

    #include  <graph.h>

    short _far _getarcinfo( struct xycoord _far *start, struct xycoord _far
    *end,
    struct xycoord _far *fillpoint );

start                             Starting point of arc

end                               Ending point of arc

fillpoint                         Point at which pie fill will begin


Remarks

The _getarcinfo function determines the endpoints in viewport coordinates of
the most recently drawn arc or pie.

If successful, the _getarcinfo function updates the start and end xycoord
structures to contain the endpoints (in viewport coordinates) of the arc
drawn by the most recent call to one of the _arc or _pie functions.

In addition, fillpoint specifies a point from which a pie can be filled.
This is useful for filling a pie in a color different from the border color.
After a call to _getarcinfo, change colors using the _setcolor function. Use
the color, along with the coordinates in fillpoint, as arguments for the
floodfill function.


Return Value

The _getarcinfo function returns a nonzero value if successful. If neither
the _arc nor the _pie function has been successfully called since the last
time the screen was cleared or a new graphics mode or viewport was selected,
the _getarcinfo function returns 0.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_arc functions,  _floodfill,  _getvideoconfig,  _grstatus,  _pie functions


Example

See the example for _arc.





_getbkcolor
────────────────────────────────────────────────────────────────────────────


Description

Gets the current background color.

    #include <graph.h>

    long _far _getbkcolor( void );


Remarks

The _getbkcolor function returns the current background color. The default
is 0.

In a color text mode such as _TEXTC80, _setbkcolor accepts, and _getbkcolor
returns, a color index. For example, _setbkcolor(2L) sets the background
color to color index 2. The actual color displayed depends on the palette
mapping for color index 2. The default for color index 2 is green in a color
text mode.

In a color graphics mode such as _ERESCOLOR, _setbkcolor accepts and
_getbkcolor returns a color value (as used in _remappalette). The value for
the simplest background colors is given by the manifest constants defined in
the GRAPH.H include file. For example, _setbkcolor( _GREEN) sets the
background color in a graphics mode to green. These manifest constants are
provided as a convenience in defining and manipulating the most common
colors. In general, the actual range of colors is much greater.

In most cases, whenever an argument is long, it refers to a color value, and
whenever it is short, it refers to a color index. The two exceptions are
_setbkcolor and _getbkcolor, described above. For a more complete discussion
of colors, see _remappalette.


Return Value

The function returns the current background color value. There is no error
return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_remappalette,  _setbkcolor


Example

See the example for _getcolor.





getc, getchar
────────────────────────────────────────────────────────────────────────────


Description

Reads a character from a stream (getc), or gets a character from stdin
(getchar).

    #include <stdio.h>

    int getc( FILE *stream );

    int getchar( void );

stream                            Current stream


Remarks

The getc macro reads a single character from the stream position and
increments the associated file pointer (if there is one) to point to the
next character. The getchar macro is identical to getc(stdin).

The getc and getchar routines are similar to fgetc and fgetchar,
respectively, but are macros rather than functions.


Return Value

The getc and getchar macros return the character read. A return value of EOF
indicates an error or end-of-file condition. Use ferror or feof to determine
whether an error or end-of-file occurred.


Compatibility

getc

    ANSI   DOS   OS/2   UNIX   XENIX


getchar

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fgetc, fgetchar, getch, getche, putc, putchar, ungetc


Example

    /* GETC.C: This program uses getchar to read a single line of input
    * from stdin, places this input in buffer, then terminates the
    * string before printing it to the screen.
    */

    #include <stdio.h>


    void main()
    {
        char buffer[81];
        int i, ch;

        printf( "Enter a line: " );

        /* Read in single line from "stdin": */
        for( i = 0; (i < 80) &&  ((ch = getchar()) != EOF) && (ch != '\n'); i++
)
        buffer[i] = ch;

        /* Terminate string with null character: */
        buffer[i] = '\0';
        printf( "%s\n", buffer );
    }


Output



    Enter a line: This is a line of text.
    This is a line of text.





getch, getche
────────────────────────────────────────────────────────────────────────────


Description

Get a character from the console without echo (getch) or with echo (getche).




#include <conio.h>                Required only for function declarations

    int getch( void );

    int getche( void );


Remarks

The getch function reads a single character from the console without
echoing. The getche function reads a single character from the console and
echoes the character read. Neither function can be used to read CTRL+C.

When reading a function key or cursor-moving key, the getch and getche
functions must be called twice; the first call returns 0 or 0xE0, and the
second call returns the actual key code.


Return Value

The getch function returns the character read. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

cgets, getchar, ungetch


Example

    /* GETCH.C: This program reads characters from the keyboard until it
    * receives a 'Y' or 'y'.
    */

    #include <conio.h>
    #include <ctype.h>


    void main()
    {
        int ch;

        cputs( "Type 'Y' when finished typing keys: " );
        do
        {
        ch = getch();
        ch = toupper( ch );
        } while( ch != 'Y' );

        putch( ch );
        putch( '\r' );    /* Carriage return */
        putch( '\n' );    /* Line feed       */
    }


Output



    Type 'Y' when finished typing keys: Y





_getcolor
────────────────────────────────────────────────────────────────────────────


Description

Gets the current color.

    #include <graph.h>

    short _far _getcolor( void );


Remarks

The _getcolor function returns the current graphics color index. The default
is the highest legal value of the current palette.


Return Value

The _getcolor function returns the current color index.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_setcolor


Example

    /* OUTTXT.C: This example illustrates text output functions:
    *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
    *    _settextcolor   _setbkcolor   _settextposition
    */

    #include <conio.h>
    #include <stdio.h>
    #include <graph.h>

    char buffer [80];

    void main()
    {

        /* Save original foreground, background, and text position. */
        short blink, fgd, oldfgd;
        long  bgd, oldbgd;
        struct rccoord oldpos;

        /* Save original foreground, background, and text position. */
        oldfgd = _gettextcolor();
        oldbgd = _getbkcolor();
        oldpos = _gettextposition();
        _clearscreen( _GCLEARSCREEN );


    /* First time no blink, second time blinking. */
        for( blink = 0; blink <= 16; blink += 16 )
        {
        /* Loop through 8 background colors. */
        for( bgd = 0; bgd < 8; bgd++ )
        {
            _setbkcolor( bgd );
            _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
            _settextcolor( 7 );
            sprintf(buffer, "Back: %d Fore:", bgd );
            _outtext( buffer );

            /* Loop through 16 foreground colors. */
            for( fgd = 0; fgd < 16; fgd++ )
            {
                _settextcolor( fgd + blink );
                sprintf( buffer, " %2d ", fgd + blink );
                _outtext( buffer );
            }
        }
        }
        getch();

        /* Restore original foreground, background, and text position. */
        _settextcolor( oldfgd );
        _setbkcolor( oldbgd );
        _clearscreen( _GCLEARSCREEN );
        _settextposition( oldpos.row, oldpos.col );
    }





_getcurrentposition Functions
────────────────────────────────────────────────────────────────────────────


Description

Get the current position and return it as a structure.

    #include <graph.h>

    struct xycoord _far _getcurrentposition( void );

    struct _wxycoord _far _getcurrentposition_w( void );


Remarks

The _getcurrentposition functions return the coordinates of the current
graphics output position. The _getcurrentposition function returns the
position as an xycoord structure, defined in GRAPH.H.

The xycoord structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
short xcoord                      x coordinate

short ycoord                      y coordinate

The _getcurrentposition_w function returns the position as an _wxycoord
structure, defined in GRAPH.H.

The _wxycoord structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
double wx                         window x coordinate

double wy                         window y coordinate

The current position can be changed by the _lineto, _moveto, and _outgtext
functions.

The default position, set by _setvideomode, _setvideomoderows, or
_setviewport, is the center of the viewport.

Only graphics output starts at the current position; these functions do not
affect text output, which begins at the current text position. (See
_settextposition for more information.)


Return Value

The _getcurrentposition function returns the coordinates of the current
graphics output position. There is no error return.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_grstatus,  _lineto functions,  _moveto functions,  _outgtext


Example

    /* GCURPOS.C: This program sets a random current location, then gets that
    * location with _getcurrentposition.
    */

    #include <stdio.h>
    #include <stdlib.h>
    #include <conio.h>
    #include <graph.h>

    char   buffer[255];

    void main()
    {
        struct videoconfig vc;
        struct xycoord position;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );
        _getvideoconfig( &vc );

        /* Move to random location and report that location. */
        _moveto( rand() % vc.numxpixels, rand() % vc.numypixels );
        position = _getcurrentposition();
        sprintf( buffer, "x = %d, y = %d", position.xcoord, position.ycoord );
        _settextposition( 1, 1 );
        _outtext( buffer );

        getch();
        _setvideomode( _DEFAULTMODE );
    }





getcwd
────────────────────────────────────────────────────────────────────────────


Description

Gets the current working directory.

#include <direct.h>               Required only for function declarations

    char *getcwd( char *buffer, int maxlen );

buffer                            Storage location for path name

maxlen                            Maximum length of path name


Remarks

The getcwd function gets the full path name of the current working directory
and stores it at buffer. The integer argument maxlen specifies the maximum
length for the path name. An error occurs if the length of the path name
(including the terminating null character) exceeds maxlen.

The buffer argument can be NULL; a buffer of at least size maxlen (more only
if necessary) will automatically be allocated, using malloc, to store the
path name. This buffer can later be freed by calling free and passing it the
getcwd return value (a pointer to the allocated buffer).


Return Value

The getcwd function returns a pointer to buffer. A NULL return value
indicates an error, and errno is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
ENOMEM                            Insufficient memory to allocate maxlen
                                    bytes (when a NULL argument is given as
                                    buffer)

ERANGE                            Path name longer than maxlen characters


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

chdir, mkdir, rmdir


Example

    /* This program places the name of the current directory in the buffer
    * array, then displays the name of the current directory on the screen.
    * Specifying a length of _MAX_DIR leaves room for the longest legal
    * directory name.
    */

    #include <direct.h>
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        char buffer[_MAX_DIR];

        /* Get the current working directory: */
        if( getcwd( buffer, _MAX_DIR ) == NULL )
        perror( "getcwd error" );
        else
        printf( "%s\n", buffer );
    }


Output



    C:\LIBREF





_getdcwd
────────────────────────────────────────────────────────────────────────────


Description

Gets full path name of current working directory, including disk drive.

#include <direct.h>               Required only for function declarations

    char *_getdcwd( int drive, char *buffer, int maxlen );

drive                             Disk drive

buffer                            Storage location for path name

maxlen                            Maximum length of path name


Remarks

The _getdcwd function gets the full path name of the current working
directory, including disk drive specification, and stores it at buffer. The
argument maxlen specifies the maximum length for the path name. An error
occurs if the length of the path name (including the terminating null
character) exceeds maxlen.

The drive argument specifies the drive (0 = default drive, 1=A, 2=B, etc.).
The buffer argument can be NULL; a buffer of at least size maxlen (more only
if necessary) will automatically be allocated, using malloc, to store the
path name. This buffer can later be freed by calling free and passing it the
_getdcwd return value (a pointer to the allocated buffer).


Return Value

The _getdcwd function returns buffer. A NULL return value indicates an
error, and errno is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
ENOMEM                            Insufficient memory to allocate maxlen
                                    bytes (when a NULL argument is given as
                                    buffer)

ERANGE                            Path name longer than maxlen characters


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

chdir, getcwd, _getdrive, mkdir, rmdir


Example

    /* GETDRIVE.C illustrates drive functions including:
    *      _getdrive       _chdrive        _getdcwd
    */

    #include <stdio.h>
    #include <conio.h>
    #include <direct.h>
    #include <stdlib.h>

    void main()
    {
        int ch, drive, curdrive;
        static char path[_MAX_PATH];

        /* Save current drive. */
        curdrive = _getdrive();

        printf( "Available drives are: \n" );

        /* If we can switch to the drive, it exists. */
        for( drive = 1; drive <= 26; drive++ )
        if( !_chdrive( drive ) )
            printf( "%c: ", drive + 'A' - 1 );

        while( 1 )
        {
        printf( "\nType drive letter to check or ESC to quit: " );
        ch = getch();
        if( ch == 27 )
            break;
        if( isalpha( ch ) )
            putch( ch );
        if( _getdcwd( toupper( ch ) - 'A' + 1, path, _MAX_PATH ) != NULL )
            printf( "\nCurrent directory on that drive is %s\n", path );
        }

        /* Restore original drive. This is only necessary for DOS. Under OS/2
        * the current drive of the calling process is always restored.
        */
        _chdrive( curdrive );
        printf( "\n" );
    }


Output



    Available drives are:
    A: B: C:
    Type drive letter to check or ESC to quit: q
    Type drive letter to check or ESC to quit: a
    Current directory on that drive is A:\

    Type drive letter to check or ESC to quit: c
    Current directory on that drive is C:\LIBREF

    Type drive letter to check or ESC to quit:





_getdrive
────────────────────────────────────────────────────────────────────────────


Description

Gets the current disk drive.

    #include <direct.h>

    int _getdrive( void );


Remarks

The _getdrive function returns the current working drive (1=A, 2=B, etc.).


Return Value

The return value is stated above. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_chdrive,  _dos_getdrive,  _dos_setdrive,  _getcwd,  _getdcwd


Example

See the example for _getdcwd.





getenv
────────────────────────────────────────────────────────────────────────────


Description

Gets a value from the environment table.

#include <stdlib.h>               Required only for function declarations

    char *getenv( const char *varname );

varname                           Name of environment variable


Remarks

The getenv function searches the list of environment variables for an entry
corresponding to varname. Environment variables define the environment in
which a process executes. (For example, the LIB environment variable defines
the default search path for libraries to be linked with a program.) Because
the getenv function is case sensitive, the varname variable should match the
case of the environment variable.

The getenv function returns a pointer to an entry in the environment table.
It is, however, only safe to retrieve the value of the environment variable
using the returned pointer. To modify the value of an environmental
variable, use the putenv function.

The getenv and putenv functions use the copy of the environment contained in
the global variable environ to access the environment. Programs that use the
envp argument to main and the putenv function may retrieve invalid
information. The safest programming practice is to use getenv and putenv.


Return Value

The getenv function returns a pointer to the environment table entry
containing the current string value of varname. The return value is NULL if
the given variable is not currently defined.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX


The getenv function operates only on the data structures accessible to the
run-time library and not on the environment "segment" created for a process
by DOS or OS/2.


See Also

putenv


Example

    /* GETENV.C: This program uses getenv to retrieve the LIB environment
    * variable and then uses putenv to change it to a new value.
    */

    #include <stdlib.h>
    #include <stdio.h>

    main()
    {
        char *libvar;

        /* Get the value of the LIB environment variable. */
        libvar = getenv( "LIB" );
        if( libvar != NULL )
        printf( "Original LIB variable is: %s\n", libvar );

        /* Attempt to change path. Note that this only affects the environment
        * variable of the current process. The command processor's environment
        * is not changed.
        */
        putenv( "LIB=c:\\mylib;c:\\yourlib" );

        /* Get new value. */
        libvar = getenv( "LIB" );
        if( libvar != NULL )
        printf( "New LIB variable is: %s\n", libvar );

    }


Output



    Original LIB variable is: C:\LIB
    New LIB variable is: c:\mylib;c:\yourlib





_getfillmask
────────────────────────────────────────────────────────────────────────────


Description

Gets the current fill mask for some graphics routines.

    #include <graph.h>

    unsigned char _far * _far _getfillmask( unsigned char _far *mask );

mask                              Mask array


Remarks

Some graphics routines (_ellipse, _floodfill, _pie, _polygon, and
_rectangle) can fill part or all of the screen with the current color or
background color. The fill mask controls the pattern used for filling.

The _getfillmask function returns the current fill mask. The mask is an
8-by-8-bit array, in which each bit represents a pixel. If the bit is 1, the
corresponding pixel is set to the current color; if the bit is 0, the pixel
is left unchanged. The mask is repeated over the entire fill area. If no
fill mask is set, or if mask is NULL, a solid (unpatterned) fill is
performed using the current color.


Return Value

If no mask is set, the function returns NULL.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_ellipse functions,  _floodfill,  _pie functions,  _polygon functions,
_rectangle functions, _setfillmask


Example

    /* GFILLMSK.C: This program illustrates _getfillmask and _setfillmask. */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>


    void ellipsemask( short x1, short y1, short x2, short y2, char _far
    *newmask );

    unsigned char mask1[8] = { 0x43, 0x23, 0x7c, 0xf7, 0x8a, 0x4d, 0x78, 0x39
};
    unsigned char mask2[8] = { 0x18, 0xad, 0xc0, 0x79, 0xf6, 0xc4, 0xa8, 0x23
};
    char oldmask[8];

    void main()
    {
        int loop;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        /* Set first fill mask and draw rectangle. */
        _setfillmask( mask1 );
        _rectangle( _GFILLINTERIOR, 20, 20, 100, 100 );
        getch();

        /* Call routine that saves and restores mask. */
        ellipsemask( 60, 60, 150, 150, mask2 );
        getch();

        /* Back to original mask. */
        _rectangle( _GFILLINTERIOR, 120, 120, 190, 190 );
        getch();

        _setvideomode( _DEFAULTMODE );
    }

    /* Draw an ellipse with a specified fill mask. */
    void ellipsemask( short x1, short y1, short x2, short y2, char _far
*newmask )
    {
        unsigned char savemask[8];

        _getfillmask( savemask );                    /* Save mask         */
        _setfillmask( newmask );                     /* Set new mask      */
        _ellipse( _GFILLINTERIOR, x1, y1, x2, y2 );  /* Use new mask      */
        _setfillmask( savemask );                    /* Restore original  */
    }





_getfontinfo
────────────────────────────────────────────────────────────────────────────


Description

Gets the current font characteristics.

    #include <graph.h>

    short _far _getfontinfo( struct _fontinfo _far *fontbuffer );

fontbuffer                        Buffer to hold font information


Remarks

The _getfontinfo function gets the current font characteristics and stores
them in a _fontinfo structure, defined in GRAPH.H.

The _fontinfo structure contains the following elements:

Element                           Contents
────────────────────────────────────────────────────────────────────────────
int type                          Specifies vector (1) or bit-mapped (0)
                                    font

int ascent                        Specifies pixel distance from top to
                                    baseline

int pixwidth                      Specifies the character width in pixels;
                                    0 indicates a proportional font

int pixheight                     Specifies the character height in pixels

int avgwidth                      Specifies the average character width in
                                    pixels

char filename [81]                Specifies the file name, including the
                                    path

char facename [32]                Specifies the font name


Return Value

The _getfontinfo function returns a negative number if a font has not been
registered or loaded.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getgtextextent,  _outgtext,  _registerfonts,  _setfont,  _setgtextvector,
_unregisterfonts


Example

See the example for _outgtext.





_getgtextextent
────────────────────────────────────────────────────────────────────────────


Description

Gets the width in pixels of font-based text.

    #include <graph.h>

    short _far _getgtextextent( unsigned char _far *text );

text                              Text to be analyzed


Remarks

The _getgtextextent function returns the width in pixels that would be
required to print the text string using _outgtext with the current font.

This function is particularly useful for determining the size of text that
uses proportionally spaced fonts.


Return Value

The _getgtextextent function returns the width in pixels. It returns -1 if a
font has not been registered.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getfontinfo,  _outgtext,  _registerfonts,  _setfont,  _unregisterfonts


Example

See the example for _outgtext.





_getimage Functions
────────────────────────────────────────────────────────────────────────────


Description

Store images in buffers.

    #include <graph.h>

    void _far _getimage( short x1, short y1, short x2, short y2, char _huge
    *image );

    void _far _getimage_w( double wx1, double wy1, double wx2, double wy2,
    char _huge *image );

    void _far _getimage_wxy( struct_wxycoord _far *pwxy1,
    struct_wxycoord _far *pwxy2, char _huge *image );

x1, y1                            Upper-left corner of bounding rectangle

x2, y2                            Lower-right corner of bounding rectangle

wx1, wy1                          Upper-left corner of bounding rectangle

wx2, wy2                          Lower-right corner of bounding rectangle

pwxy1                             Upper-left corner of bounding rectangle

pwxy2                             Lower-right corner of bounding rectangle

image                             Storage buffer for screen image


Remarks

The _getimage functions store the screen image defined by a specified
bounding rectangle into the buffer pointed to by image.

The _getimage function defines the bounding rectangle with the view
coordinates (x1, y1) and (x2, y2).

The _getimage_w function defines the bounding rectangle with the window
coordinates (wx1, wy1) and (wx2, wy2).

The _getimage_wxy function defines the bounding rectangle with the
window-coordinate pairs pwxy1 and pwxy2.

The buffer must be large enough to hold the image. You can determine the
size by calling the appropriate _imagesize function at run time, or by using
the formula described on the _imagesize reference page.


Return Value

None. Use _grstatus to check success.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_grstatus,  _imagesize functions,  _putimage functions


Example

    /* GIMAGE.C: This example illustrates animation routines including:
    *          _imagesize     _getimage     _putimage
    */

    #include <conio.h>
    #include <stddef.h>
    #include <stdlib.h>
    #include <malloc.h>
    #include <graph.h>

    short action[5]  = { _GPSET,   _GPRESET, _GXOR,    _GOR,     _GAND     };
    char *descrip[5] = {  "PSET  ", "PRESET", "XOR   ", "OR    ", "AND   " };

    void exitfree( char _huge *buffer );

    void main()
    {
        char  _huge *buffer;   /* Far pointer (with _fmalloc) could be used.
*/
        long  imsize;
        short i, x, y = 30;

        if( !_setvideomode( _MAXRESMODE ) )
            exit( 1 );

        /* Measure the image to be drawn and allocate memory for it. */
        imsize = (size_t)_imagesize( -16, -16, +16, +16 );
        buffer = halloc( imsize, sizeof( char ) );
        if ( buffer == (char _far *)NULL )
            exit( 1 );

        _setcolor( 3 );
        for ( i = 0; i < 5; i++ )
        {
            /* Draw ellipse at new position and get a copy of it. */
            x = 50; y += 40;
            _ellipse( _GFILLINTERIOR, x - 15, y - 15, x + 15, y + 15 );
            _getimage( x - 16, y - 16, x + 16, y + 16, buffer );
            if( _grstatus() )
                exitfree( buffer );        /* Quit on error
*/


    /* Display action type and copy a row of ellipses with that type. */
            _settextposition( 1, 1 );
            _outtext( descrip[i] );
            while( x < 260 )
            {
                x += 5;
                _putimage( x - 16, y - 16, buffer, action[i] );
                if( _grstatus() < 0 )      /* Ignore warnings, quit on errors.
*/
                    exitfree( buffer );
            }
            getch();
        }
        exitfree( buffer );
    }

    void exitfree( char _huge *buffer )
    {
        hfree( buffer );
        exit( !_setvideomode( _DEFAULTMODE ) );
    }





_getlinestyle
────────────────────────────────────────────────────────────────────────────


Description

Gets the current line style.

    #include <graph.h>

    unsigned short _far _getlinestyle( void );


Remarks

Some graphics routines ( _lineto, _polygon, and _rectangle) output straight
lines to the screen. The type of line can be controlled with the current
line-style mask.

The _getlinestyle function returns the current line-style mask. The mask is
a 16-bit array in which each bit represents a pixel in the line being drawn.
If the bit is 1, the corresponding pixel is set to the color of the line
(the current color). If the bit is 0, the corresponding pixel is left
unchanged. The mask is repeated over the length of the line. The default
mask is 0xFFFF (a solid line).


Return Value

If no mask has been set, _getlinestyle returns the default mask.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_lineto functions,  _polygon functions,  _rectangle functions,
_setlinestyle, _setwritemode


Example

    /* GLINESTY.C: This program illustrates _setlinestyle and _getlinestyle.
    */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void zigzag( short x1, short y1, short size );

    void main()
    {

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );

        /* Set line style and draw rectangle. */
        _setlinestyle( 0x4d );
        _rectangle( _GBORDER, 10, 10, 60, 60 );
        getch();


        /* Draw figure with function that changes and restores line style. */
        zigzag( 100, 100, 90 );
        getch();

        /* Original style reused. */
        _rectangle( _GBORDER, 190, 190, 130, 130 );
        getch();

        _setvideomode( _DEFAULTMODE );
    }

    /* Draw box with changing line styles. Restore original style. */
    void zigzag( short x1, short y1, short size )
    {
        short x, y, oldcolor;
        unsigned short oldstyle;
        unsigned short style[16] = { 0x0001, 0x0003, 0x0007, 0x000f,
                                    0x001f, 0x003f, 0x007f, 0x00ff,
                                    0x01ff, 0x03ff, 0x07ff, 0x0fff,
                                    0x1fff, 0x3fff, 0x7fff, 0xffff };

        oldcolor = _getcolor();
        oldstyle = _getlinestyle();            /* Save old line style.
*/
        for( x = 3, y = 3; x < size; x += 3, y += 3 )
        {
        _setcolor( x % 16 );
        _setlinestyle( style[x % 16] );     /* Set and use new line styles
*/
        _rectangle( _GBORDER, x1 - x, y1 - y, x1 + x, y1 + y );
        }
        _setlinestyle( oldstyle );             /* Restore old line style.
*/
        _setcolor( oldcolor );
    }





_getphyscoord
────────────────────────────────────────────────────────────────────────────


Description

Gets physical coordinates.

    #include <graph.h>

    struct xycoord _far _getphyscoord( short x, short y );

x, y                              View coordinates to translate


Remarks

The _getphyscoord function translates the view coordinates (x, y) to
physical coordinates and returns them in an xycoord structure, defined in
GRAPH.H.

The xycoord structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
short xcoord                      x coordinate

short ycoord                      y coordinate


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getviewcoord functions,  _grstatus,  _setvieworg,  _setviewport


Example

See the example for _setwindow.





getpid
────────────────────────────────────────────────────────────────────────────


Description

Gets the process identification.

#include <process.h>              Required only for function declarations

    int getpid( void );


Remarks

The getpid function returns the process ID, an integer that uniquely
identifies the calling process.


Return Value

The getpid function returns the process ID. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

mktemp


Example

    /* GETPID.C: This program uses getpid to obtain the process ID and
    * then prints the ID.
    */

    #include <stdio.h>
    #include <process.h>

    void main( )
    {
        /* If run from DOS, shows different ID for DOS than for DOS shell.
        * If execed or spawned, shows ID of parent.
        */
        printf( "\nProcess id of parent: %d\n", getpid() );
    }


Output




    Process id of parent: 828





_getpixel Functions
────────────────────────────────────────────────────────────────────────────


Description

Get pixel values.

    #include <graph.h>

    short _far _getpixel( short x, short y );

    short _far _getpixel_w( double wx, double wy );

x, y                              Pixel position

wx, wy                            Pixel position


Remarks

The functions in the _getpixel family return the pixel value (a color index)
at a specified location. The _getpixel function uses the view coordinate (x,
y). The _getpixel_w function uses the window coordinate (wx, wy). The range
of possible pixel values is determined by the current video mode. The color
translation of pixel values is determined by the current palette.


Return Value

If successful, the function returns the color index. If the function fails
(for example, the point lies outside the clipping region, or the program is
in a text mode), it returns -1.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getvideoconfig,  _grstatus,  _remapallpalette,  _remappalette,
_selectpalette,  _setpixel functions,  _setvideomode


Example

    /* GPIXEL.C: This program assigns different colors to randomly
    * selected pixels.
    */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void main()
    {
        short xvar, yvar;
        struct videoconfig vc;


    /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );
        _getvideoconfig( &vc );

        /* Draw filled ellipse to turn on certain pixels. */
        _ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6,
                                vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5
                                                );

        /* Draw random pixels in random colors... */
        while( !kbhit() )
        {
        /* ...but only if they are already on (inside the ellipse). */
        xvar = rand() % vc.numxpixels;
        yvar = rand() % vc.numypixels;
        if( _getpixel( xvar, yvar ) != 0 )
        {
            _setcolor( rand() % 16 );
            _setpixel( xvar, yvar );
        }
        }

        getch();          /* Throw away the keystroke. */
        _setvideomode( _DEFAULTMODE );
    }





gets
────────────────────────────────────────────────────────────────────────────


Description

Gets a line from the stdin stream.

    #include <stdio.h>

    char *gets( char *buffer );

buffer                            Storage location for input string


Remarks

The gets function reads a line from the standard input stream stdin and
stores it in buffer. The line consists of all characters up to and including
the first newline character (\n). The gets function then replaces the
newline character with a null character ('\0') before returning the line. In
contrast, the fgets function retains the newline character.


Return Value

If successful, the gets function returns its argument. A NULL pointer
indicates an error or end-of-file condition. Use ferror or feof to determine
which one has occurred.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fgets, fputs, puts


Example

    /* GETS.C */

    #include <stdio.h>

    void main()
    {
        char line[81];

        printf( "Input a string: " );
        gets( line );
        printf( "The line entered was: %s\n", line );
    }


Output



    Input a string: This is a string
    The line entered was: This is a string





_gettextcolor
────────────────────────────────────────────────────────────────────────────


Description

Gets the current text color.

    #include <graph.h>

    short _far _gettextcolor( void );


Remarks

The _gettextcolor function returns the color index of the current text
color. The text color is set by the _settextcolor function and affects text
output with the _outtext and _outmem functions only. The _setcolor function
sets the color for font text output using the  _outgtext function.

The default is 7 in test modes; it is the highest legal color index of the
current palette in graphics modes.


Return Value

The _gettextcolor function returns the color index of the current text
color.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_getvideoconfig,  _remappalette,  _selectpalette,  _setcolor,  _settextcolor



Example

See the example for _gettextposition.





_gettextcursor
────────────────────────────────────────────────────────────────────────────


Description

Gets the current cursor attribute.

    #include <graph.h>

    short _far _gettextcursor( void );


Remarks

The _gettextcursor function returns the current cursor attribute (i.e., the
shape). This function works only in text video modes.


Return Value

The function returns the current cursor attribute, or -1 if an error occurs
(such as a call to the function in a graphics mode).


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_displaycursor,  _grstatus,  _settextcursor


Example

See the example for _settextcursor.





_gettextposition
────────────────────────────────────────────────────────────────────────────


Description

Gets the current text position.

    #include <graph.h>

    struct rccoord _far _gettextposition( void );


Remarks

The _gettextposition function returns the current text position as an
rccoord structure, defined in GRAPH.H.

The rccoord structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
short row                         Row coordinate

short col                         Column coordinate


Remarks

The text position given by the coordinates (1,1) is defined as the
upper-left corner of the text window.

Text output from the _outtext and _outmem functions begins at the current
text position. Font text is not affected by the current text position. Font
text output begins at the current graphics output position, which is a
separate position.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_getcurrentposition functions,  _moveto functions,  _outmem,  _outtext,
_settextposition,  _settextwindow,  _wrapon


Example

    /* OUTTXT.C: This example illustrates text output functions:
    *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
    *    _settextcolor   _setbkcolor   _settextposition
    */

    #include <conio.h>
    #include <stdio.h>
    #include <graph.h>

    char buffer [80];

    void main()
    {

        /* Save original foreground, background, and text position. */
        short blink, fgd, oldfgd;
        long  bgd, oldbgd;
        struct rccoord oldpos;

        /* Save original foreground, background, and text position. */
        oldfgd = _gettextcolor();
        oldbgd = _getbkcolor();
        oldpos = _gettextposition();
        _clearscreen( _GCLEARSCREEN );

        /* First time no blink, second time blinking. */
        for( blink = 0; blink <= 16; blink += 16 )
        {
        /* Loop through 8 background colors. */
        for( bgd = 0; bgd < 8; bgd++ )
        {
            _setbkcolor( bgd );
            _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
            _settextcolor( 7 );
            sprintf(buffer, "Back: %d Fore:", bgd );
            _outtext( buffer );

            /* Loop through 16 foreground colors. */
            for( fgd = 0; fgd < 16; fgd++ )
            {
                _settextcolor( fgd + blink );
                sprintf( buffer, " %2d ", fgd + blink );
                _outtext( buffer );
            }
        }
        }
        getch();

        /* Restore original foreground, background, and text position. */
        _settextcolor( oldfgd );
        _setbkcolor( oldbgd );
        _clearscreen( _GCLEARSCREEN );
        _settextposition( oldpos.row, oldpos.col );
    }





_gettextwindow
────────────────────────────────────────────────────────────────────────────


Description

Gets the boundaries of the current text window.

    #include <graph.h>

    void _far _gettextwindow( short _far *r1, short _far *c1, short _far *r2,
    short _far *c2 );

r1                                Top row of current text window

c1                                Leftmost column of current text window

r2                                Bottom row of current text window

c2                                Rightmost column of current text window


Remarks

The _gettextwindow function finds the boundaries of the current text window.
The text window is the region of the screen to which output from the
_outtext and _outmem functions is limited. By default, this is the entire
screen, unless it has been redefined by the _settextwindow function.

The window defined by _settextwindow has no effect on output from the
_outgtext function. Text displayed with _outgtext is limited to the current
viewport.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_gettextposition,  _outmem,  _outtext,  _scrolltextwindow,
_settextposition, _settextwindow,  _wrapon


Example

See the example for _scrolltextwindow.





_getvideoconfig
────────────────────────────────────────────────────────────────────────────


Description

Gets graphics video configuration information.

    #include <graph.h>

    struct videoconfig _far * _far _getvideoconfig( struct videoconfig _far
    *config );

config                            Configuration information


Remarks

The _getvideoconfig function returns the current graphics environment
configuration in a videoconfig structure, defined in GRAPH.H.

The values returned reflect the currently active video adapter and monitor,
as well as the current video mode.

The videoconfig structure contains the following members, each of which is
of type short:

Member                            Contents
────────────────────────────────────────────────────────────────────────────
adapter                           Active display adapter

bitsperpixel                      Number of bits per pixel

memory                            Adapter video memory in kilobytes

mode                              Current video mode

monitor                           Active display monitor

numcolors                         Number of color indices

numtextcols                       Number of text columns available

numtextrows                       Number of text rows available

numvideopages                     Number of available video pages

numxpixels                        Number of pixels on the x axis

numypixels                        Number of pixels on the y axis



The values for the adapter member of the videoconfig structure are given by
the manifest constants shown in the list below. For any applicable adapter (
_CGA, _EGA, or _VGA), the corresponding Olivetti(R) adapter ( _OCGA, _OEGA,
or _OVGA) represents a superset of graphics capabilities.

Adapter Constant                  Meaning
────────────────────────────────────────────────────────────────────────────
_CGA                              Color Graphics Adapter

_EGA                              Enhanced Graphics Adapter

_HGC                              Hercules(R) Graphics Card

_MCGA                             Multicolor Graphics Array

_MDPA                             Monochrome Display Printer Adapter

_OCGA                             Olivetti (AT&T(R)) Color Graphics
                                    Adapter

_OEGA                             Olivetti (AT&T) Enhanced Graphics
                                    Adapter

_OVGA                             Olivetti (AT&T) Video Graphics Array

_VGA                              Video Graphics Array

The values for the monitor member of the videoconfig structure are given by
the manifest constants listed below:

Monitor Constant                  Meaning
────────────────────────────────────────────────────────────────────────────
_ANALOG                           Analog monochrome and color

_ANALOGCOLOR                      Analog color only

_ANALOGMONO                       Analog monochrome only

_COLOR                            Color (or enhanced monitor emulating a
                                    color monitor)

_ENHCOLOR                         Enhanced color

_MONO                             Monochrome monitor

In every text mode, including monochrome, the _getvideoconfig function
returns the value 32 for the number of available colors. The value 32
indicates the range of values (0 -31) accepted by the _settextcolor
function. This includes 16 normal colors (0 -15) and 16 blinking colors (16
-31). Blinking is selected by adding 16 to the normal color index. Because
monochrome text mode has fewer unique display attributes, some color indices
are redundant. However, because blinking is selected in the same manner,
monochrome text mode has the same range (0 -31) as other text modes.


Return Value

The _getvideoconfig function returns the video configuration information in
a structure, as noted above. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_setvideomode,  _setvideomoderows


Example

    /* GVIDCFG.C: This program displays information about the current
    * video configuration.
    */

    #include <stdio.h>
    #include <graph.h>

    void main()
    {
        struct videoconfig vc;
        short  c;
        char   b[500];                        /* Buffer for string */

        _getvideoconfig( &vc );

        /* Write all information to a string, then output string. */
        c  = sprintf( b,     "X pixels:     %d\n", vc.numxpixels );
        c += sprintf( b + c, "Y pixels:     %d\n", vc.numypixels );
        c += sprintf( b + c, "Text columns: %d\n", vc.numtextcols );
        c += sprintf( b + c, "Text rows:    %d\n", vc.numtextrows );
        c += sprintf( b + c, "Colors:       %d\n", vc.numcolors );
        c += sprintf( b + c, "Bits/pixel:   %d\n", vc.bitsperpixel );
        c += sprintf( b + c, "Video pages:  %d\n", vc.numvideopages );
        c += sprintf( b + c, "Mode:         %d\n", vc.mode );
        c += sprintf( b + c, "Adapter:      %d\n", vc.adapter );
        c += sprintf( b + c, "Monitor:      %d\n", vc.monitor );
        c += sprintf( b + c, "Memory:       %d\n", vc.memory );
        _outtext( b );
    }


Output



    X pixels:     0
    Y pixels:     0
    Text columns: 80
    Text rows:    25
    Colors:       32
    Bits/pixel:   0
    Video pages:  1
    Mode:         3
    Adapter:      8
    Monitor:      24
    Memory:       256





_getviewcoord Functions
────────────────────────────────────────────────────────────────────────────


Description

Translate coordinates to view coordinates.

    #include <graph.h>

    struct xycoord _far _getviewcoord( short x, short y );

    struct xycoord _far _getviewcoord_w( double wx, double wy );

    struct xycoord _far _getviewcoord_wxy( struct _wxycoord _far *pwxy1 );

x, y                              Physical point to translate

wx, wy                            Window point to translate

pwxy1                             Window point to translate


Remarks

The _getviewcoord routines translate the specified coordinates (x, y) from
one coordinate system to view coordinates and then return them in an xycoord
structure, defined in GRAPH.H. The xycoord structure contains the following
elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
short xcoord                      x coordinate

short ycoord                      y coordinate

The various _getviewcoord routines translate in the following manner:

Routine                           Translation
────────────────────────────────────────────────────────────────────────────
_getviewcoord                     Physical coordinates (x, y) to view
                                    coordinates

_getviewcoord_w                   Window coordinates (wx, wy) to view
                                    coordinates

_getviewcoord_wxy                 Window coordinates structure (pwxy1) to
                                    view coordinates

────────────────────────────────────────────────────────────────────────────
C 5.1 Version Difference
In Microsoft C version 5.1, the function _getviewcoord was called
_getlogcoord.
────────────────────────────────────────────────────────────────────────────


Return Value

The _getviewcoord function returns the coordinates as noted above. There is
no error  return.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getphyscoord,  _getwindowcoord,  _grstatus


Example

See the example for _setwindow.





_getvisualpage
────────────────────────────────────────────────────────────────────────────


Description

Gets the current visual page number.

    #include <graph.h>

    short _far _getvisualpage( void );


Remarks

The _getvisualpage function returns the current visual page number.


Return Value

The function returns the number of the current visual page. All hardware
combinations support at least one page (page number 0). In OS/2, only page 0
is available.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_getactivepage,  _gettextcolor,  _gettextposition,  _outtext,
_setactivepage, _settextcolor,  _settextposition,  _settextwindow,
_setvideomode, _setvisualpage,  _wrapon


Example

See the example for _getactivepage.





getw
────────────────────────────────────────────────────────────────────────────


Description

Gets an integer from a stream.

    #include <stdio.h>

    int getw( FILE *stream );

stream                            Pointer to FILE structure


Remarks

The getw function reads the next binary value of type int from the file
associated with stream and increments the associated file pointer (if there
is one) to point to the next unread character. The getw function does not
assume any special alignment of items in the stream.


Return Value

The getw function returns the integer value read. A return value of EOF may
indicate an error or end-of-file. However, since the EOF value is also a
legitimate integer value, feof or ferror should be used to verify an
end-of-file or error condition.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX


The getw function is provided primarily for compatibility with previous
libraries. Note that portability problems may occur with getw, since the
size of the int type and the ordering of bytes within the int type differ
across systems.


See Also

putw


Example

    /* GETW.C: This program uses getw to read a word from a stream,
    * then performs an error check.
    */

    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {

        FILE *stream;
        int i;


    if( (stream = fopen( "getw.c", "rb" )) == NULL )
        printf( "Couldn't open file\n" );
        else
        {
        /* Read a word from the stream: */
        i = getw( stream );

        /* If there is an error... */
        if( ferror( stream ) )
        {
            printf( "getw failed\n" );
            clearerr( stream );
        }
        else
            printf( "First data word in file: 0x%.4x\n", i );
        fclose( stream );
        }
    }


Output



    First data word in file: 0x2a2f





_getwindowcoord
────────────────────────────────────────────────────────────────────────────


Description

Translates view coordinates to window coordinates.

    #include <graph.h>

    struct _wxycoord _far _getwindowcoord( short x, short y );

x, y                              Physical point to translate


Remarks

The _getwindowcoord function translates the view coordinates (x, y) to
window coordinates and returns them in the _wxycoord structure, defined in
GRAPH.H.

The _wxycoord structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
double wx                         x coordinate

double wy                         y coordinate


Return Value

The function returns the coordinates in the _wxycoord structure. There is no
error return.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getphyscoord,  _getviewcoord functions,  _moveto functions,  _setwindow


Example

See the example for _setwindow.





_getwritemode
────────────────────────────────────────────────────────────────────────────


Description

Gets the current logical mode for line drawing.

    #include  <graph.h>

    short _far _getwritemode( void );


Remarks

The _getwritemode function returns the current logical write mode, which is
used when drawing lines with the _lineto, _polygon, and _rectangle
functions.

The default value is _GPSET, which causes lines to be drawn in the current
graphics color. The other possible return values are _GXOR, _GAND, _GOR, and
_GPRESET. See _putimage for more details on these manifest constants.


Return Value

The _getwritemode function returns the current logical write mode, or -1 if
not in graphics mode.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_grstatus,  _lineto functions,  _putimage functions,  _rectangle functions,
_setcolor,  _setlinestyle,  _setwritemode


Example

    /* GWRMODE.C: This program illustrates _getwritemode and _setwritemode. */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    short wmodes[5]  = { _GPSET,   _GPRESET, _GXOR,    _GOR,     _GAND    };
    char *wmstr[5]   = { "PSET  ", "PRESET", "XOR   ", "OR    ", "AND   " };

    void box( short x, short y, short size, short writemode, short fillmode );

    void main()
    {
        short i, x, y;


    /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );

        x = y = 70;
        box( x, y, 50, _GPSET, _GFILLINTERIOR );
        _setcolor( 2 );
        box( x, y, 40, _GPSET, _GFILLINTERIOR );
        for( i = 0; i < 5; i++ )
        {
        _settextposition( 1, 1 );
        _outtext( wmstr[i] );
        box( x += 12, y += 12, 50, wmodes[i], _GBORDER );
        getch();
        }
        _setvideomode( _DEFAULTMODE );
    }

    void box( short x, short y, short size, short writemode, short fillmode )
    {
        short wm, side;

        wm = _getwritemode();           /* Save write mode and set new. */
        _setwritemode( writemode );
        _rectangle( fillmode, x - size, y - size, x + size, y + size );
        _setwritemode( wm );            /* Restore original write mode. */
    }





gmtime
────────────────────────────────────────────────────────────────────────────


Description

Converts a time value to a structure.

    #include <time.h>

    struct tm *gmtime( const time_t *timer );

timer                             Pointer to stored time


Remarks

The gmtime function converts the timer value to a structure. The timer
argument represents the seconds elapsed since 00:00:00, January 1, 1970,
Greenwich mean time. This value is usually obtained from a call to the timer
function.

The gmtime function breaks down the timer value and stores it in a structure
of type tm, defined in TIME.H. (See asctime for a description of the
structure members.) The structure result reflects Greenwich mean time, not
local time.

The fields of the structure type tm store the following values, each of
which is an int:

Field                             Value Stored
────────────────────────────────────────────────────────────────────────────
tm_sec                            Seconds

tm_min                            Minutes

tm_hour                           Hours (0-24)

tm_mday                           Day of month (1-31)

tm_mon                            Month (0-11; January = 0)

tm_year                           Year (current year minus 1900)

tm_wday                           Day of week (0-6; Sunday = 0)

tm_yday                           Day of year (0-365; January 1 = 0)

tm_isdst                          Always 0 for gmtime

The gmtime, mktime, and localtime functions use a single statically
allocated structure to hold the result. Each call to one of these routines
destroys the result of any previous call.

DOS and OS/2 do not accommodate dates prior to 1980. If timer represents a
date prior to 1980, gmtime returns NULL.


Return Value

The gmtime function returns a pointer to the structure result. There is no
error return.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

asctime, ctime, ftime, localtime, time


Example

    /* GMTIME.C: This program uses gmtime to convert a long-integer
    * representation of Greenwich mean time to a structure named newtime,
    * then uses asctime to convert this structure to an output string.
    */

    #include <time.h>
    #include <stdio.h>

    void main()
    {
        struct tm *newtime;
        long ltime;

        time( &ltime );

        /* Obtain Greenwich mean time: */
        newtime = gmtime( &ltime );
        printf( "Greenwich mean time is %s\n", asctime( newtime ) );
    }


Output



    Greenwich mean time is Fri Jun 16 16:37:53 1989





_grstatus
────────────────────────────────────────────────────────────────────────────


Description

Returns the status of the most recent graphics function call.

    #include  <graph.h>

    short _far _grstatus( void );


Remarks

The _grstatus function returns the status of the most recently used graphics
function. The _grstatus function can be used immediately following a call to
a graphics routine to determine if errors or warnings were generated. Return
values less than 0 are errors, and values greater than 0 are warnings.

The following manifest constants are defined in the GRAPH.H header file for
use with the _grstatus function:

╓┌──────┌──────────────────────┌─────────────────────────────────────────────►
Value  Constant               Meaning
─────────────────────────────────────────────────────────────────────────────
0      _GROK                  Success

Value  Constant               Meaning
─────────────────────────────────────────────────────────────────────────────

-1     _GRERROR               Graphics error

-2     _GRMODENOTSUPPORTED    Requested video mode not supported

-3     _GRNOTINPROPERMODE     Requested routine only works in certain video
                                modes

-4     _GRINVALIDPARAMETER    One or more parameters invalid

-5     _GRFONTFILENOTFOUND    No matching font file found

-6     _GRINVALIDFONTFILE     One or more font files invalid

-7     _GRCORRUPTEDFONTFILE   One or more font files inconsistent

-8     _GRINSUFFICIENTMEMORY  Not enough memory to allocate buffer or to
                                complete a _floodfill operation

Value  Constant               Meaning
─────────────────────────────────────────────────────────────────────────────

-9     _GRINVALIDIMAGEBUFFER  Image buffer data inconsistent

1      _GRMOOUTPUT            No action taken

2      _GRCLIPPED             Output was clipped to viewport

3      _GRPARAMETERALTERED    One or more input parameters was altered to be
                                within range, or pairs of parameters were
                                interchanged to be in the proper order

─────────────────────────────────────────────────────────────────────────────



After a graphics call, use an if statement to compare the return value of
_grstatus to _GROK. For example:

    if( _grstatus < _GROK )
        /*handle graphics error*/ ;

The functions listed below cannot cause errors, and they all set _grstatus
to GROK:

╓┌────────────────┌─────────────────┌────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
_displaycursor   _gettextposition  _outmem

_getactivepage   _gettextwindow    _outtext

_getgtextvector  _getvideoconfig   _unregisterfonts

_gettextcolor    _getvisualpage    _wrapon



    See the list below for the graphics functions that affect _grstatus. The
list shows error or warning messages that can be set by the graphics
function. In addition to the error codes listed, all of these functions can
produce the _GRERROR error code.

╓┌───────────────────────────────────┌───────────────────────────────────────►
Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────
_arc functions                      _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER

_clearscreen                        _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER

_ellipse functions                  _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER,
                                    _GRINSUFFICIENTMEMORY

_getarcinfo                         _GRNOTINPROPERMODE

_getcurrentposition                 _GRNOTINPROPERMODE
functions

_getfontinfo                        ( _GRERROR only)
Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────
_getfontinfo                        ( _GRERROR only)

_getgtextextent                     ( _GRERROR only)

_getgtextvector                     _GRPARAMETERALTERED

_getimage                           _GRNOTINPROPERMODE

_getphyscoord                       _GRNOTINPROPERMODE

_getpixel                           _GRNOTINPROPERMODE

_gettextcursor                      _GRNOTINPROPERMODE

_getviewcoord functions             _GRNOTINPROPERMODE

Continued on next page

Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────

_getwindowcoord                     _GRNOTINPROPERMODE

_getwritemode                       _GRNOTINPROPERMODE

_imagesize functions                _GRNOTINPROPERMODE

_lineto functions                   _GRNOTINPROPERMODE


_moveto functions                   _GRNOTINPROPERMODE

_outgtext                           _GRNOTINPROPERMODE


_pie functions                      _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER,
                                    _GRINSUFFICIENTMEMORY
Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────
                                    _GRINSUFFICIENTMEMORY

_polygon functions                  _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER,
                                    _GRINSUFFICIENTMEMORY

_putimage functions                 _GRERROR,
                                    _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER,
                                    _GRINVALIDIMAGEBUFFER

_rectangle functions                _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER,
                                    _GRINSUFFICIENTMEMORY

_registerfonts                      _GRCORRUPTEDFONTFILE,
                                    _GRFONTFILENOTFOUND,
                                    _GRINSUFFICIENTMEMORY,
Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────
                                    _GRINSUFFICIENTMEMORY,
                                    _GRINVALIDFONTFILE

_scrolltextwindow

_selectpalette                      _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER

_setactivepage                      _GRINVALIDPARAMETER

_setbkcolor                         _GRINVALIDPARAMETER

_setcliprgn                         _GRNOTINPROPERMODE

_setcolor                           _GRNOTINPROPERMODE

_setfont                            _GRERROR,
                                    _GRFONTFILENOTFOUND,
Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────
                                    _GRFONTFILENOTFOUND,
                                    _GRINSUFFICIENTMEMORY,
                                    _GRPARAMETERALTERED

Continued on next page

_setgtextvector                     _GRPARAMETERALTERED

_settextcolor

_settextcursor                      _GRNOTINPROPERMODE

_settextposition

_settextrows                        _GRINVALIDPARAMETER

_settextwindow

Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────

_setvideomode                       _GRERROR,
                                    _GRMODENOTSUPPORTED,
                                    _GRINVALIDPARAMETER

_setvideomoderows                   _GRERROR,
                                    _GRMODENOTSUPPORTED,
                                    _GRINVALIDPARAMETER

_setvieworg                         _GRNOTINPROPERMODE

_setviewport                        _GRNOTINPROPERMODE

_setvisualpage                      _GRINVALIDPARAMETER

_setwindow                          _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER

Function                            Possible _grstatus
G                                   Error Codes
─────────────────────────────────────────────────────────────────────────────

_setwritemode                       _GRNOTINPROPERMODE,
                                    _GRINVALIDPARAMETER

─────────────────────────────────────────────────────────────────────────────




Return Value

The _grstatus function returns the status of the most recently used graphics
function.


See Also

_arc functions,  _ellipse functions,  _floodfill,  _lineto functions,  _pie
functions, _remapallpalette,  _setactivepage,  _setbkcolor,  _setcolor,
_setpixel functions, _settextcolor,  _settextcursor,  _setvisualpage,
_setwindow,  _setwritemode


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX






halloc
────────────────────────────────────────────────────────────────────────────


Description

Allocates a huge memory block.

#include <malloc.h>               Required only for function declarations

    void _huge *halloc( long num, size_t size );

num                               Number of elements

size                              Length in bytes of each element


Remarks

The halloc function allocates a huge array from the operating system
consisting of num elements, each of which is size bytes long. Each element
is initialized to 0. If the size of the array is greater than 128K (131,072
bytes), the size of an array element must then be a power of 2.


Return Value

The halloc function returns a void huge pointer to the allocated space,
which is guaranteed to be suitably aligned for storage of any type of
object. To get a pointer to a type other than void huge, use a type cast on
the return value. If the request cannot be satisfied, the return value is
NULL.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

calloc functions, free functions, hfree, malloc functions


Example

    /* HALLOC.C: This program uses halloc to allocate space for 30,000 long
    * integers, then uses hfree to deallocate the memory.
    */

    #include <stdio.h>
    #include <stdlib.h>
    #include <malloc.h>

    void main()
    {
        long _huge *hbuf;

    /* Allocate huge buffer */
        hbuf = (long _huge *)halloc( 30000L, sizeof( long ) );
        if ( hbuf == NULL )
        printf( "Insufficient memory available\n" );
        else
        printf( "Memory successfully allocated\n" );

        /* Free huge buffer */
        hfree( hbuf );
    }


Output



    Memory successfully allocated





_hard Functions
────────────────────────────────────────────────────────────────────────────


Description

Handle critical error conditions.

    #include <dos.h>

    void _harderr( void( _far *handler )());

    void _hardresume( int result );

    void _hardretn( int error );

handler ( )                       New INT 0x24 handler

result                            Handler return parameter

error                             Error to return from


Remarks

These three functions are used to handle critical error conditions that use
DOS interrupt 0x24. The _harderr function installs a new critical-error
handler for interrupt 0x24.

The _hardresume and _hardreturn functions control how the program will
return from the new critical-error handler installed by _harderr. The
_hardresume function returns to DOS from a user-installed critical-error
handler, and the _hardreturn function returns directly to the application
program from a user-installed critical-error handler.

The _harderr function does not directly install the handler pointed to by
handler; instead, _harderr installs a handler that calls the function
referenced by handler. The handler calls the function with the following
parameters:

    handler(unsigned deverror, unsigned errcode, unsigned far *devhdr);


The deverror argument is the device error code. It contains the AX register
value passed by DOS to the INT 0x24 handler. The errcode argument is the DI
register value that DOS passes to the handler. The low-order byte of errcode
can be one of the following values:

Code                              Meaning
────────────────────────────────────────────────────────────────────────────
0                                 Attempt to write to a write-protected
                                    disk

1                                 Unknown unit

2                                 Drive not ready

3                                 Unknown command

4                                 Cyclic-redundancy-check error in data

5                                 Bad drive-request structure length

6                                 Seek error

7                                 Unknown media type

8                                 Sector not found

9                                 Printer out of paper

10                                Write fault

11                                Read fault

12                                General failure

The devhdr argument is a far pointer to a device header that contains
descriptive information about the device on which the error occurred. The
user-defined handler must not change the information in the device-header
control block.


Errors on Disk Devices

If the error occurred on a disk device, the high-order bit (bit 15) of the
deverror argument will be set to 0, and the deverror argument will indicate
the following:

Bit                               Meaning
────────────────────────────────────────────────────────────────────────────
15                                Disk error if false (0).

14                                Not used.

13                                "Ignore" response not allowed if false
                                    (0).

12                                "Retry" response not allowed if false
                                    (0).

11                                "Fail" response not allowed if false
                                    (0). Note that DOS changes "fail" to
                                    "abort".

10, 9

                                    Code      Location
────────────────────────────────────────────────────────────────────────────
                                    00          DOS

                                    01          File allocation table

                                    10          Directory

                                    11          Data area


8                                 Read error if false; write error if
                                    true.

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


Errors on Other Devices

If the error occurs on a device other than a disk drive, the high-order bit
(bit 15) of the deverror argument is 1. The attribute word located at offset
4 in the device-header block indicates the type of device that had the
error. If bit 15 of the attribute word is 0, the error is a bad memory image
of the file allocation table. If the bit is 1, the error occurred on a
character device and bits 0-3 of the attribute word indicate the type of
device, as shown in the following list:

Bit                               Meaning
────────────────────────────────────────────────────────────────────────────
0                                 Current standard input

1                                 Current standard output

2                                 Current null device

3                                 Current clock device


Restrictions on Handler Functions

The user-defined handler function can issue only system calls 0x01 through
0x0C, or 0x59. Thus, many of the standard C run-time functions (such as
stream I/O and low-level I/O) cannot be used in a hardware error handler.
Function 0x59 can be used to obtain further information about the error that
occurred.


Using _hardresume and _harderr

If the handler returns, it can do so -
    1.  From the return statement

    2.  From the _hardresume function

    3.  From the _hardretn function



If the handler returns from _hardresume or from a return statement, the
handler returns to DOS.

The _hardresume function should be called only from within the user-defined
hardware error-handler function. The result supplied to _hardresume must be
one of the following constants:

Constant                          Action
────────────────────────────────────────────────────────────────────────────
_HARDERR_ABORT                    Abort the program by issuing INT 0x23

_HARDERR_FAIL                     Fail the system call that is in progress
                                    (this is not supported on DOS 2. x)

_HARDERR_IGNORE                   Ignore the error

_HARDERR_RETRY                    Retry the operation

The _hardretn function allows the user-defined hardware error handler to
return directly to the application program rather than returning to DOS. The
application resumes at the point just after the failing I/O function
request. The _hardretn function should be called only from within a
user-defined hardware error-handler function.

The error parameter of _hardretn should be a DOS error code, as opposed to
the XENIX-style error code that is available in errno. Refer to MS-DOS
Encyclopedia (Duncan, ed.; Redmond, Wa.: Microsoft Press, 1988) or
Programmer's PC Sourcebook (Hogan; Redmond, Wa.: Microsoft Press, 1988) for
information about the DOS error codes that may be returned by a given DOS
function call.

If the failing I/O function request is an INT 0x21 function greater than or
equal to function 0x38, _hardretn will then return to the application with
the carry flag set and the AX register set to the _hardretn error parameter.
If the failing INT 0x21 function request is less than function 0x38 and the
function can return an error, the AL register will be set to 0xFF on return
to the application. If the failing INT 0x21 does not have a way of returning
an error condition (which is true of certain INT 0x21 functions below 0x38),
the error parameter of _hardretn is not used, and no error code is returned
to the application.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_chain_intr,  _dos_getvect,  _dos_setvect





_heapadd Functions
────────────────────────────────────────────────────────────────────────────


Description

Add memory to the heap (_heapadd) or to the based heap (_bheapadd).

#include <malloc.h>               Required only for function declarations

    int _heapadd( void _far *memblock, size_t size );

    int _bheapadd( _segment seg, void _based (void) *memblock, size_t size );

seg                               Based-heap segment selector

buffer                            Pointer to heap memory

size                              Size in bytes of memory to add


Remarks

The _heapadd and _bheapadd functions add an unused piece of memory to the
heap. The _bheapadd function adds the memory to the based heap specified by
seg. The _heapadd function looks at the segment value and, if it is DGROUP,
adds the memory to the near heap. Otherwise, _heapadd adds the memory to the
far heap.


Return Value

These functions return 0 if successful, or -1 if an error occurred.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

free functions, halloc, hfree, malloc functions, realloc functions


Example

    /* HEAPMIN.C: This program illustrates heap management using
    * _heapadd and _heapmin.
    */

    #include <stdio.h>
    #include <conio.h>
    #include <process.h>
    #include <malloc.h>

    void heapdump( char *msg );     /* Prototype */

    char s1[] = { "Here are some strings that we use at first, then don't\n"
};
    char s2[] = { "need any more. We'll give their space to the heap.\n" };

    void main()
    {
        int *p[3], i;

        printf( "%s%s", s1, s2 );
        heapdump( "Initial heap" );

        /* Give space of used strings to heap. */
        _heapadd( s1, sizeof( s1 ) );
        _heapadd( s2, sizeof( s2 ) );
        heapdump( "After adding used strings" );

        /* Allocate some blocks. Some may use string blocks from _heapadd. */
        for( i = 0; i < 2; i++ )
            if( (p[i] = (int *)calloc( 10 * (i + 1), sizeof( int ) )) == NULL
)
            {
                --i;
                break;
            }
        heapdump( "After allocating memory" );

        /* Free some of the blocks. */
        free( p[1] );
        free( p[2] );
        heapdump( "After freeing memory" );

        /* Minimize heap. */
        _heapmin();
        heapdump( "After compacting heap" );
    }

    /* Walk through heap entries, displaying information about each block. */
    void heapdump( char *msg )
    {
        struct _heapinfo hi;

        printf( "%s\n", msg );
        hi._pentry = NULL;
        while( _heapwalk( &hi ) == _HEAPOK )
            printf( "\t%s block at %Fp of size %u\t\n",
                    hi._useflag == _USEDENTRY ? "USED" : "FREE",
                    hi._pentry,
                    hi._size );
        getch();
    }


Output



    Here are some strings that we use at first, then don't
    need any more. We'll give their space to the heap.
    Initial heap
        USED block at 2D39:0E9C of size 364
        USED block at 2D39:100A of size 36
        USED block at 2D39:1030 of size 512
        FREE block at 2D39:1232 of size 460
    After adding used strings
        FREE block at 2D39:0044 of size 52
        FREE block at 2D39:007A of size 50
        USED block at 2D39:00AE of size 3564
        USED block at 2D39:0E9C of size 364
        USED block at 2D39:100A of size 36
        USED block at 2D39:1030 of size 512
        FREE block at 2D39:1232 of size 460
    After allocating memory
        USED block at 2D39:0044 of size 20
        USED block at 2D39:005A of size 40
        FREE block at 2D39:0084 of size 40
        USED block at 2D39:00AE of size 3564
        USED block at 2D39:0E9C of size 364
        USED block at 2D39:100A of size 36
        USED block at 2D39:1030 of size 512
        FREE block at 2D39:1232 of size 460
    After freeing memory
        USED block at 2D39:0044 of size 20
        FREE block at 2D39:005A of size 40
        FREE block at 2D39:0084 of size 40
        USED block at 2D39:00AE of size 3564
        USED block at 2D39:0E9C of size 364
        USED block at 2D39:100A of size 36
        USED block at 2D39:1030 of size 512
        FREE block at 2D39:1232 of size 460
    After compacting heap
        USED block at 2D39:0044 of size 20
        FREE block at 2D39:005A of size 82
        USED block at 2D39:00AE of size 3564
        USED block at 2D39:0E9C of size 364
        USED block at 2D39:100A of size 36
        USED block at 2D39:1030 of size 512
        FREE block at 2D39:1232 of size 12





_heapchk Functions
────────────────────────────────────────────────────────────────────────────


Description

Run consistency checks on the heap.

    #include <malloc.h>

    int _heapchk( void );

    int _bheapchk( _segment seg );

    int _fheapchk( void );

    int _nheapchk( void );

seg                               Specified base heap


Remarks

The _heapchk routines help to debug heap-related problems by checking for
minimal consistency of the heap.

Each function checks a particular heap, as listed below:

Function                          Heap Checked
────────────────────────────────────────────────────────────────────────────
_heapchk                          Depends on data model of program

_bheapchk                         Based heap specified by seg value

_fheapchk                         Far heap (outside the default data
                                    segment)

_nheapchk                         Near heap (inside the default data
                                    segment)

In large data models (that is, compact-, large-, and huge-model programs),
_heapchk maps to _fheapchk. In small data models (tiny-, small-, and
medium-model programs), _heapchk maps to _nheapchk.


Return Value

All four routines return an integer value that is one of the following
manifest constants (defined in MALLOC.H):

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_HEAPBADBEGIN                     Initial header information cannot be
                                    found, or it is bad

_HEAPBADNODE                      Bad node has been found, or the heap is
                                    damaged

_HEAPEMPTY                        Heap has not been initialized

_HEAPOK                           Heap appears to be consistent


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_heapset functions,  _heapwalk functions


Example

    /* HEAPCHK.C: This program checks the heap for consistency
    * and prints an appropriate message.
    */

    #include <malloc.h>
    #include <stdio.h>

    void main()
    {
        int  heapstatus;
        char *buffer;

        /* Allocate and deallocate some memory */
        if( (buffer = (char *)malloc( 100 )) != NULL )
        free( buffer );

        /* Check heap status */
        heapstatus = _heapchk();
        switch( heapstatus )
        {
        case _HEAPOK:
            printf(" OK - heap is fine\n" );
            break;
        case _HEAPEMPTY:
            printf(" OK - heap is empty\n" );
            break;
        case _HEAPBADBEGIN:
            printf( "ERROR - bad start of heap\n" );
            break;
        case _HEAPBADNODE:
            printf( "ERROR - bad node in heap\n" );
            break;
        }
    }


Output



    OK - heap is fine





_heapmin Functions
────────────────────────────────────────────────────────────────────────────


Description

Release unused heap memory to the operating system.

    #include <malloc.h>

    int _heapmin( void );

    int _bheapmin( _segment seg )

    int _fheapmin( void );

    int _nheapmin( void );

seg                               Specified based-heap selector


Remarks

The _heapmin functions minimize the heap by releasing unused heap memory to
the operating system.

The various _heapmin functions release unused memory in these heaps:

Function                          Heap Minimized
────────────────────────────────────────────────────────────────────────────
_heapmin                          Depends on data model of program

_bheapmin                         Based heap specified by seg value;
                                    _NULLSEG specifies all based heaps

_fheapmin                         Far heap (outside default data segment)

_nheapmin                         Near heap (inside default data segment)

In large data models (that is, compact-, large-, and huge-model programs),
_heapmin maps to _fheapmin. In small data models (tiny-, small-, and
medium-model programs), _heapmin maps to _nheapmin.

Based-heap segments are never freed (i.e., unlinked from the based heap list
and released back to the operating system) by the _bheapmin function. The
_bfreeseg function is used for that purpose.


Return Value

The _heapmin functions return 0 if the function completed successfully, or
-1 in the case of an error.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_bfreeseg, free functions, malloc functions





_heapset Functions
────────────────────────────────────────────────────────────────────────────


Description

Check heaps for minimal consistency and set the free entries to a specified
value.

    #include <malloc.h>

    int _heapset( unsigned int fill );

    int _bheapset( _segment seg, unsigned int fill );

    int _fheapset( unsigned int fill );

    int _nheapset( unsigned int fill );

fill                              Fill character

seg                               Specified based-heap segment selector


Remarks

The _heapset family of routines helps debug heap-related problems in
programs by showing free memory locations or nodes unintentionally
overwritten.

The _heapset routines first check for minimal consistency on the heap in a
manner identical to that of the _heapchk functions. After the consistency
check, the _heapset functions set each byte of the heap's free entries to
the fill value. This known value shows which memory locations of the heap
contain free nodes and which locations contain data that were
unintentionally written to freed memory.

The various _heapset functions check and fill these heaps:

Function                          Heap Filled
────────────────────────────────────────────────────────────────────────────
_heapset                          Depends on data model of program

_bheapset                         Based heap specified by seg value;
                                    _NULLSEG specifies all based heaps

_fheapset                         Far heap (outside default data segment)

_nheapset                         Near heap (inside default data segment)

In large data models (that is, compact-, large-, and huge-model programs),
_heapset maps to _fheapset. In small data models (tiny-, small-, and
medium-model programs), _heapset maps to _nheapset.


Return Value

All four routines return an int whose value is one of the following manifest
constants (defined in MALLOC.H):

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_HEAPBADBEGIN                     Initial header information cannot be
                                    found, or it is invalid

_HEAPBADNODE                      Bad node has been found, or the heap is
                                    damaged

_HEAPEMPTY                        Heap has not been initialized

_HEAPOK                           Heap appears to be consistent




Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_heapchk functions,  _heapwalk functions


Example

    /* HEAPSET.C: This program checks the heap and fills in free entries
    * with the character 'Z'.
    */

    #include <malloc.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        int heapstatus;
        char *buffer;

    if( (buffer = malloc( 1 )) == NULL )   /* Make sure heap is initialized */
        exit( 0 );
        heapstatus = _heapset( 'Z' );          /* Fill in free entries */
        switch( heapstatus )
        {
        case _HEAPOK:
            printf( "OK - heap is fine\n" );
            break;
        case _HEAPEMPTY:
            printf( "OK - heap is empty\n" );
            break;
        case _HEAPBADBEGIN:
            printf( "ERROR - bad start of heap\n" );
            break;
        case _HEAPBADNODE:
            printf( "ERROR - bad node in heap\n" );
            break;
        }
        free( buffer );
    }


Output



    OK - heap is fine





_heapwalk Functions
────────────────────────────────────────────────────────────────────────────


Description

Traverse the heap and return information about the next entry.

    include <malloc.h>

    int _heapwalk( _HEAPINFO *entryinfo );

    int _bheapwalk( _segment seg, _HEAPINFO *entryinfo );

    int _fheapwalk( _HEAPINFO *entryinfo );

    int _nheapwalk(_HEAPINFO *entryinfo);

entryinfo                         Buffer to contain heap information

seg                               Based-heap segment selector


Remarks

The _heapwalk family of routines helps debug heap-related problems in
programs.

The _heapwalk routines walk through the heap, traversing one entry per call,
and return a pointer to a _heapinfo structure that contains information
about the next heap entry. The _heapinfo structure, defined in MALLOC.H,
contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
int far *_pentry                  Heap entry pointer

size_t  _size                     Size of heap entry

int _useflag                      Entry "in use" flag

A call to _heapwalk that returns _HEAPOK stores the size of the entry in the
_size field and sets the _useflag field to either _FREEENTRY or _USEDENTRY
(both are constants defined in MALLOC.H). To obtain this information about
the first entry in the heap, pass the _heapwalk routine a pointer to a
_heapinfo structure whose _pentry field is NULL.

The various _heapwalk functions walk through and gather information on these
heaps:

Function                          Heap Walked
────────────────────────────────────────────────────────────────────────────
_heapwalk                         Depends on data model of program

_bheapwalk                        Based heap specified by seg value;
                                    _NULLSEG specifies all based heaps

_fheapwalk                        Far heap (outside default data segment)

_nheapwalk                        Near heap (inside default data segment)

In large data models (that is, compact-, large-, and huge-model programs),
_heapwalk maps to _fheapwalk. In small data models (tiny-, small-, and
medium-model programs), _heapwalk maps to _nheapwalk.


Return Value

All three routines return one of the following manifest constants (defined
in MALLOC.H):

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_HEAPBADBEGIN                     The initial header information cannot be
                                    found, or it is invalid.

_HEAPBADNODE                      A bad node has been found, or the heap
                                    is damaged.

_HEAPBADPTR                       The _pentry field of the _heapinfo
                                    structure does not contain a valid
                                    pointer into the heap.

_HEAPEND                          The end of the heap has been reached
                                    successfully.

_HEAPEMPTY                        The heap has not been initialized.

_HEAPOK                           No errors so far; the _heapinfo
                                    structure contains information about the
                                    next entry.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_heapchk functions,  _heapset functions


Example

    /* HEAPWALK.C: This program "walks" the heap, starting at the beginning
    * (_pentry = NULL). It prints out each heap entry's use, location,
    * and size. It also prints out information about the overall state
    * of the heap as soon as _heapwalk returns a value other than _HEAPOK.
    */

    #include <stdio.h>
    #include <malloc.h>

    void heapdump( void );

    void main()
    {
        char *buffer;

        heapdump();
        if( (buffer = malloc( 59 )) != NULL )
        {
        heapdump();
        free( buffer );
        }
        heapdump();
    }

    void heapdump( void )
    {
        struct _heapinfo hinfo;
        int heapstatus;

        hinfo._pentry = NULL;
        while( ( heapstatus = _heapwalk( &hinfo ) ) == _HEAPOK )
        {
        printf( "%6s block at %Fp of size %4.4X\n",
            ( hinfo._useflag == _USEDENTRY ? "USED" : "FREE" ),
            hinfo._pentry, hinfo._size );
        }

        switch( heapstatus )
        {
        case _HEAPEMPTY:
            printf( "OK - empty heap\n" );
            break;
        case _HEAPEND:
            printf( "OK - end of heap\n" );
            break;
        case _HEAPBADPTR:
            printf( "ERROR - bad pointer to heap\n" );
            break;
        case _HEAPBADBEGIN:
            printf( "ERROR - bad start of heap\n" );
            break;
        case _HEAPBADNODE:
            printf( "ERROR - bad node in heap\n" );
            break;
        }
    }


Output



    USED block at 0067:103E of size 000E
    USED block at 0067:104E of size 01F4
    USED block at 0067:1244 of size 0026
    USED block at 0067:126C of size 0200
    FREE block at 0067:146E of size 0B90
    OK - end of heap
    USED block at 0067:103E of size 000E
    USED block at 0067:104E of size 01F4
    USED block at 0067:1244 of size 0026
    USED block at 0067:126C of size 0200
    USED block at 0067:146E of size 003C
    FREE block at 0067:14AC of size 0B52
    OK - end of heap
    USED block at 0067:103E of size 000E
    USED block at 0067:104E of size 01F4
    USED block at 0067:1244 of size 0026
    USED block at 0067:126C of size 0200
    FREE block at 0067:146E of size 003C
    FREE block at 0067:14AC of size 0B52
    OK - end of heap





hfree
────────────────────────────────────────────────────────────────────────────


Description

Frees a huge memory block.

#include <malloc.h>               Required only for function declarations

    void hfree( void _huge *memblock );

memblock                          Pointer to allocated memory block


Remarks

The hfree function deallocates a memory block; the freed memory is returned
to the operating system. The memblock argument points to a memory block
previously allocated through a call to halloc. The number of bytes freed is
the number of bytes specified when the block was allocated.

Note that attempting to free an invalid memblock argument (one not allocated
with halloc) may affect subsequent allocation and cause errors.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

halloc


Example

    /* HALLOC.C: This program uses halloc to allocate space for 30,000 long
    * integers, then uses hfree to deallocate the memory.
    */

    #include <stdio.h>
    #include <stdlib.h>
    #include <malloc.h>

    void main()
    {
        long _huge *hbuf;

        /* Allocate huge buffer */
        hbuf = (long _huge *)halloc( 30000L, sizeof( long ) );
        if ( hbuf == NULL )
        printf( "Insufficient memory available\n" );
        else
        printf( "Memory successfully allocated\n" );

    /* Free huge buffer */
        hfree( hbuf );
    }


Output



    Memory successfully allocated





hypot, hypotl
────────────────────────────────────────────────────────────────────────────


Description

Calculate the hypotenuse.

    #include <math.h>

    double hypot( double x, double y );

    long double hypotl( long double x, long double y );

x, y                              Floating-point values


Remarks

The hypot and hypotl functions calculate the length of the hypotenuse of a
right triangle, given the length of the two sides x and y (or xl and yl). A
call to hypot is equivalent to the following:

    sqrt(x*x + y*y);


The hypotl function uses the 80-bit, 10-byte coprocessor form of arguments
and return values. See the reference page on the long double functions for
more details on this data type.


Return Value

The functions return the length of the hypotenuse. If an overflow results,
the functions return HUGE_VAL and set errno to ERANGE.


Compatibility

hypot

▼ ANSI   DOS   OS/2   UNIX   XENIX


hypotl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

cabs


Example

    /* HYPOT.C: This program prints the hypotenuse of a right triangle. */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = 3.0, y = 4.0;

        printf( "If a right triangle has sides %2.1f and %2.1f, "
                "its hypotenuse is %2.1f\n", x, y, hypot( x, y ) );
    }


Output



    If a right triangle has sides 3.0 and 4.0, its hypotenuse is 5.0





_imagesize Functions
────────────────────────────────────────────────────────────────────────────


Description

Get amount of memory required to store graphics images.

    #include <graph.h>

    long _far _imagesize( short x1, short y1, short x2, short y2 );

    long _far _imagesize_w( double wx1, double wy1, double wx2, double wy2 );

    long _far _imagesize_wxy( struct _wxycoord _far *pwxy1,
    struct _wxycoord _far *pwxy2 );

x1, y1                            Upper-left corner of bounding rectangle

x2, y2                            Lower-right corner of bounding rectangle

wx1, wy1                          Upper-left corner of bounding rectangle

wx2, wy2                          Lower-right corner of bounding rectangle

pwxy1                             Upper-left corner of bounding rectangle

pwxy2                             Lower-right corner of bounding rectangle


Remarks

The functions in the _imagesize family return the number of bytes needed to
store the image defined by the bounding rectangle and specified by the
coordinates given in the function call.

The _imagesize function defines the bounding rectangle in terms of
view-coordinate points (x1, y1) and (x2, y2).

The _imagesize_w function defines the bounding rectangle in terms of
window-coordinate points (x1, y1) and (x2, y2).

The _imagesize_wxy function defines the bounding rectangle in terms of the
window-coordinate pairs pwxy1 and pwxy2.

The number of bytes needed to store the image is determined by the following
formula:

    xwid = abs(x1-x2)+1;
    ywid = abs(y1-y2)+1;
    size = 4+((long)((xwid*bits_per_pixel+7)/8)*(long)ywid);

A call to _getvideoconfig stores the  bits_per_pixel  information in the
bitsperpixel field of a videoconfig structure.


Return Value

The function returns the storage size of the image in bytes. There is no
error return.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getimage functions,  _getvideoconfig,  _putimage functions


Example

See the example for _getimage.





inp, inpw
────────────────────────────────────────────────────────────────────────────


Description

Input a byte (inp) or a word (inpw) from a port.

#include <conio.h>                Required only for function declarations

    int inp( unsigned port );

    unsigned inpw( unsigned port );

port                              Port number


Remarks

The inp and inpw functions read a byte and a word, respectively, from the
specified input port. The input value can be any unsigned integer in the
range 0 - 65,535.

To use inp and inpw in OS/2 protected mode, you must use a .DEF file to
declare the IOSEG segment that the run-time library uses to perform
input/output on the port. In addition, the intrinsic (/Oi) versions of these
functions do not work unless you put the code in a segment that is marked
with the IOPL keyword in the .DEF file.

Because you cannot do IOPL from a regular code segment, the run-time library
declares a separate code segment called _IOSEG. In order to use inp, inpw,
outp, or outpw in any of the protected-mode run-time libraries (?LIBCP,
LLIBCDLL, LLIBCMT, or CDLLOBJS-based DLL), you must have a .DEF file
containing this line:

    SEGMENTS _IOSEG CLASS 'IOSEG_CODE' IOPL


Return Value

The functions return the byte or word read from port. There is no error
return.


Compatibility

▼ ANSI   DOS   OS2  ▼ UNIX  ▼ XENIX



See Also

outp, outpw


Example

See the example for outp.





int86
────────────────────────────────────────────────────────────────────────────


Description

Executes the 8086 interrupt.

    #include <dos.h>

    int int86( int intnum, union REGS *inregs, union REGS *outregs );

intnum                            Interrupt number

inregs                            Register values on call

outregs                           Register values on return


Remarks

The int86 function executes the 8086-processor-family interrupt specified by
the interrupt number intnum. Before executing the interrupt, int86 copies
the contents of inregs to the corresponding registers. After the interrupt
returns, the function copies the current register values to outregs. It also
copies the status of the system carry flag to the cflag field in the outregs
argument. The inregs and outregs arguments are unions of type REGS. The
union type is defined in the include file DOS.H.

Do not use the int86 function to call interrupts that modify the DS
register. Instead, use the int86x function. The int86x function loads the DS
and ES registers from the segregs parameter and also stores the DS and ES
registers into segregs after the function call.

The REGS type is defined in the include file DOS.H.


Return Value

The return value is the value in the AX register after the interrupt
returns. If the cflag field in outregs is nonzero, an error has occurred; in
such cases, the _doserrno variable is also set to the corresponding error
code.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

bdos, int86x, intdos, intdosx


Example

    /* INT86.C: This program uses int86 to call the BIOS video service
    * (INT 10H) to get information about the cursor.
    */

    #include <dos.h>
    #include <stdio.h>

    void main()
    {
        union REGS inregs, outregs;

        /* Set up to get cursor information. */
        inregs.h.ah = 3;       /* Get Cursor Position function */
        inregs.h.bh = 0;       /* Page 0 */

        /* Execute video interrupt: */
        int86( 0x10, &inregs, &outregs );

        /* Display results. */
        printf( "Cursor position\n\tRow: %d\n\tColumn: %d\n",
                outregs.h.dh, outregs.h.dl );
        printf( "Cursor shape\n\tStart: %d\n\tEnd: %d\n",
                outregs.h.ch, outregs.h.cl );
    }


Output



    Cursor position
            Row: 2
            Column: 0
    Cursor shape
            Start: 6
            End: 7





int86x
────────────────────────────────────────────────────────────────────────────


Description

Executes the 8086 interrupt; accepts segment-register values.

    #include <dos.h>

    int int86x( int intnum, union REGS *inregs, union REGS *outregs,
    struct SREGS *segregs );

intnum                            Interrupt number

inregs                            Register values on call

outregs                           Register values on return

segregs                           Segment-register values on call


Remarks

The int86x function executes the 8086-processor-family interrupt specified
by the interrupt number intnum. Unlike the int86 function, int86x accepts
segment-register values in segregs, enabling programs that use large-model
data segments or far pointers to specify which segment or pointer should be
used during the system call.

Before executing the specified interrupt, int86x copies the contents of
inregs and segregs to the corresponding registers. Only the DS and ES
register values in segregs are used. After the interrupt returns, the
function copies the current register values to outregs, cop-ies the current
ES and DS values to segregs, and restores DS. It also copies the status of
the system carry flag to the cflag field in outregs.

The REGS and SREGS types are defined in the include file DOS.H.

Segment values for the segregs argument can be obtained by using either the
segread function or the FP_SEG macro.


Return Value

The return value is the value in the AX register after the interrupt
returns. If the cflag field in outregs is nonzero, an error has occurred; in
such cases, the _doserrno variable is also set to the corresponding error
code.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

bdos, FP_SEG, int86, intdos, intdosx, segread


Example

    /* INT86X.C: In this program, int86x executes an INT 21H instruction
    * to invoke DOS system call 43H (change file attributes). The program
    * uses int86x because the file, which is referenced with a far pointer,
    * may be in a segment other than the default data segment. Thus, the
    * program must explicitly set the DS register with the SREGS structure.
    */

    #include <signal.h>
    #include <dos.h>
    #include <stdio.h>
    #include <process.h>

    char _far *filename = "int86x.c";

    void main()
    {
        union  REGS inregs, outregs;
        struct SREGS segregs;
        int    result;

        inregs.h.ah = 0x43;      /* DOS function to change attributes    */
        inregs.h.al = 0;         /* Subfunction 0 to get attributes)     */
        inregs.x.dx = FP_OFF( filename );   /* DS:DX points to file name */
        segregs.ds  = FP_SEG( filename );
        result = int86x( 0x21, &inregs, &outregs, &segregs );
        if( outregs.x.cflag )
        printf( "Can't get file attributes; error no. %d\n", result);
        else
        printf( "Attribs = 0x%.4x\n", outregs.x.cx );
    }


Output



    Attribs = 0x0020





intdos
────────────────────────────────────────────────────────────────────────────


Description

Executes the DOS system call.

    #include <dos.h>

    int intdos( union REGS *inregs, union REGS *outregs );

inregs                            Register values on call

outregs                           Register values on return


Remarks

The intdos function invokes the DOS system call specified by register values
defined in inregs and returns the effect of the system call in outregs. The
inregs and outregs arguments are unions of type REGS. The REGS type is
defined in the include file DOS.H.

To invoke a system call, intdos executes an INT 21H instruction. Before
executing the instruction, the function copies the contents of inregs to the
corresponding registers. After the INT instruction returns, intdos copies
the current register values to outregs. It also copies the status of the
system carry flag to the cflag field in outregs. A nonzero cflag field
indicates the flag was set by the system call and also indicates an error
condition.

The intdos function is used to invoke DOS system calls that take arguments
for input or output in registers other than DX (DH/DL) and AL. The intdos
function is also used to invoke system calls that indicate errors by setting
the carry flag. Under any other conditions, the bdos function can be used.

Do not use the intdos function to call interrupts that modify the DS
register. Instead, use the intdosx or int86x function.


Return Value

The intdos function returns the value of the AX register after the system
call is completed. If the cflag field in outregs is nonzero, an error has
occurred and _doserrno is also set to the corresponding error code.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

bdos, intdosx


Example

    /* INTDOS.C: This program uses intdos to invoke DOS system call 2AH
    * (gets the current date).
    */

    #include <dos.h>
    #include <stdio.h>

    void main()
    {
        union REGS inregs, outregs;

        inregs.h.ah = 0x2a;           /* DOS Get Date function: */
        intdos( &inregs, &outregs );
        printf( "Date: %d/%d/%d\n", outregs.h.dh, outregs.h.dl, outregs.x.cx );
    }


Output



    Date: 6/16/1989





intdosx
────────────────────────────────────────────────────────────────────────────


Description

Executes the DOS system call; accepts segment-register values.

    #include <dos.h>

    int intdosx( union REGS *inregs, union REGS *outregs, struct SREGS
    *segregs );

inregs                            Register values on call

outregs                           Register values on return

segregs                           Segment-register values on call


Remarks

The intdosx function invokes the DOS system call specified by register
values defined in inregs and returns the results of the system call in
outregs. Unlike the intdos function, intdosx accepts segment-register values
in segregs, enabling programs that use large-model data segments or far
pointers to specify which segment or pointer should be used during the
system call. The REGS and SREGS types are defined in the include file DOS.H.


To invoke a system call, intdosx executes an INT 21H instruction. Before
executing the instruction, the function copies the contents of inregs and
segregs to the corresponding registers. Only the DS and ES register values
in segregs are used. After the INT instruction returns, intdosx copies the
current register values to outregs and restores DS. It also copies the
status of the system carry flag to the cflag field in outregs. A nonzero
cflag field indicates the flag was set by the system call and also indicates
an error condition.

The intdosx function is used to invoke DOS system calls that take an
argument in the ES register or that take a DS register value different from
the default data segment.

Segment values for the segregs argument can be obtained by using either the
segread function or the FP_SEG macro.


Return Value

The intdosx function returns the value of the AX register after the system
call is completed. If the cflag field in outregs is nonzero, an error has
occurred; in such cases, _doserrno is also set to the corresponding error
code.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

bdos, FP_SEG, intdos, segread


Example

    /* INTDOSX.C */
    #include <dos.h>
    #include <stdio.h>

    char _far *buffer = "Dollar-sign terminated string\n\r\n\r$";

    void main()
    {
        union  REGS inregs, outregs;
        struct SREGS segregs;

        /* Print a $-terminated string on the screen using DOS function 0x09.
*/
        inregs.h.ah = 0x9;
        inregs.x.dx = FP_OFF( buffer );
        segregs.ds  = FP_SEG( buffer );
        intdosx( &inregs, &outregs, &segregs );
    }


Output



    Dollar-sign terminated string





is Functions
────────────────────────────────────────────────────────────────────────────


Description


Test characters for specified conditions.

    #include <ctype.h>

    int isalnum( int c );

    int isalpha( int c );

    int isascii( 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 );

c                                 Integer to be tested


Remarks

Each function in the is family tests a given integer value, returning a
nonzero value if the integer satisfies the test condition and 0 if it does
not. The ASCII character set is assumed.

The is functions and their test conditions are listed below:

Function                          Test Condition
────────────────────────────────────────────────────────────────────────────
isalnum                           Alphanumeric ('A'-'Z', 'a'-'z', or
                                    '0'-'9')

isalpha                           Letter ('A'-'Z' or 'a'-'z')

isascii                           ASCII character (0x00 - 0x7F)

iscntrl                           Control character (0x00 - 0x1F or 0x7F)

isdigit                           Digit ('0'-'9')

isgraph                           Printable character except space (' ')

islower                           Lowercase letter ('a'-'z')

isprint                           Printable character (0x20 - 0x7E)

ispunct                           Punctuation character

isspace                           White-space character (0x09 - 0x0D or
                                    0x20)

isupper                           Uppercase letter ('A'-'Z')

isxdigit                          Hexadecimal digit ('A'-'F','a'-'f', or
                                    '0'-'9')

The isascii routine produces meaningful results for all integer values.
However, the remaining routines produce a defined result only for integer
values corresponding to the ASCII character set (that is, only where isascii
holds true) or for the non-ASCII value EOF (defined in STDIO.H).

These routines are implemented both as functions and as macros. For details
on choosing a function or a macro implementation, see Section 1.4, "Choosing
Between Functions and Macros."


Return Value

These routines return a nonzero value if the integer satisfies the test
condition and 0 if it does not.


Compatibility

isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, ispunct,
isspace, isupper, isxdigit

    ANSI   DOS   OS/2   UNIX   XENIX


isascii

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

toascii, tolower, toupper functions


Example

    /* ISFAM.C: This program tests all characters between 0x0 and 0x7F,
    * then displays each character with abbreviations for the character-type
    * codes that apply.
    */

    #include <stdio.h>
    #include <ctype.h>

    void main()
    {
        int ch;
        for( ch = 0; ch <= 0x7F; ch++ )
        {
        printf( "%.2x ", ch );
        printf( " %c", isprint( ch )  ? ch   : '\0' );
        printf( "%4s", isalnum( ch )  ? "AN" : "" );
        printf( "%3s", isalpha( ch )  ? "A"  : "" );
        printf( "%3s", isascii( ch )  ? "AS" : "" );
        printf( "%3s", iscntrl( ch )  ? "C"  : "" );
        printf( "%3s", isdigit( ch )  ? "D"  : "" );
        printf( "%3s", isgraph( ch )  ? "G"  : "" );
        printf( "%3s", islower( ch )  ? "L"  : "" );
        printf( "%3s", ispunct( ch )  ? "PU" : "" );
        printf( "%3s", isspace( ch )  ? "S"  : "" );
        printf( "%3s", isprint( ch )  ? "PR" : "" );
        printf( "%3s", isupper( ch )  ? "U"  : "" );
        printf( "%3s", isxdigit( ch ) ? "X"  : "" );
        printf( "\n" );
        }
    }


Output



    00          AS  C
    01          AS  C
    02          AS  C
    .
    .
    .
    38  8  AN    AS     D  G          PR     X
    39  9  AN    AS     D  G          PR     X
    3a  :        AS        G    PU    PR
    3b  ;        AS        G    PU    PR
    3c  <        AS        G    PU    PR
    3d  =        AS        G    PU    PR
    3e  >        AS        G    PU    PR
    3f  ?        AS        G    PU    PR
    40  @        AS        G    PU    PR
    41  A  AN  A AS        G          PR  U  X
    42  B  AN  A AS        G          PR  U  X
    .
    .
    .





isatty
────────────────────────────────────────────────────────────────────────────


Description

Checks for a character device.

#include <io.h>                   Required only for function declarations

    int isatty( int handle );

handle                            Handle referring to device to be tested


Remarks

The isatty function determines whether handle is associated with a character
device (a terminal, console, printer, or serial port).


Return Value

The isatty function returns a nonzero value if the device is a character
device. Otherwise, the return value is 0.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



Example

    /* ISATTY.C: This program checks to see whether stdout has been
    * redirected to a file.
    */

    #include <stdio.h>
    #include <io.h>

    void main()
    {
        if( isatty( fileno( stdout ) ) )
        printf( "stdout has not been redirected to a file\n" );
        else
        printf( "stdout has been redirected to a file\n");
    }


Output



    stdout has not been redirected to a file





itoa
────────────────────────────────────────────────────────────────────────────


Description

Converts an integer to a string.

#include <stdlib.h>               Required only for function declarations

    char *itoa( int value, char *string, int radix );

value                             Number to be converted

string                            String result

radix                             Base of value


Remarks

The itoa function converts the digits of the given value argument to a
null-terminated character string and stores the result (up to 17 bytes) in
string. The radix argument specifies the base of value; it must be in the
range 2-36. If radix equals 10 and value is negative, the first character of
the stored string is the minus sign (-).


Return Value

The itoa function returns a pointer to string. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

ltoa, ultoa


Example

    /* ITOA.C: This program converts integers of various sizes to strings
    * in various radixes.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        char buffer[20];
        int  i = 3445;
        long l = -344115L;
        unsigned long ul = 1234567890UL;

    itoa( i, buffer, 10 );
        printf( "String of integer %d (radix 10): %s\n", i, buffer );
        itoa( i, buffer, 16 );
        printf( "String of integer %d (radix 16): 0x%s\n", i, buffer );
        itoa( i, buffer, 2  );
        printf( "String of integer %d (radix 2): %s\n", i, buffer );

        ltoa( l, buffer, 16 );
        printf( "String of long int %ld (radix 16): 0x%s\n", l, buffer );

        ultoa( ul, buffer, 16 );
        printf( "String of unsigned long %lu (radix 16): 0x%s\n", ul, buffer );
    }


Output



    String of integer 3445 (radix 10): 3445
    String of integer 3445 (radix 16): 0xd75
    String of integer 3445 (radix 2): 110101110101
    String of long int -344115 (radix 16): 0xfffabfcd
    String of unsigned long 1234567890 (radix 16): 0x499602d2





kbhit
────────────────────────────────────────────────────────────────────────────


Description

Checks the console for keyboard input.

#include <conio.h>                Required only for function declarations

    int kbhit( void );


Remarks

The kbhit function checks the console for a recent keystroke. If the
function returns a nonzero value, a keystroke is waiting in the buffer. The
program can then call getch or getche to get the keystroke.


Return Value

The kbhit function returns a nonzero value if a key has been pressed.
Otherwise, it re-turns 0.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



Example

    /* KBHIT.C: This program loops until the user presses a key.
    * If kbhit returns nonzero, a keystroke is waiting in the buffer.
    * The program can call getch or getche to get the keystroke.
    */

    #include <conio.h>
    #include <stdio.h>

    void main()
    {
        /* Display message until key is pressed. */
        while( !kbhit() )
        cputs( "Hit me!! " );

        /* Use getch to throw key away. */
        printf( "\nKey struck was '%c'\n", getch() );
        getch();
    }


Output



    Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!!
    Key struck was 'k'





labs
────────────────────────────────────────────────────────────────────────────


Description

Calculates the absolute value of a long integer.

#include <stdlib.h>               Required only for function declarations

#include <math.h>

    long labs( long n );

n                                 Long-integer value


Remarks

The labs function produces the absolute value of its long-integer argument
n.


Return Value

The labs function returns the absolute value of its argument. There is no
error return.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

abs, cabs, fabs


Example

    /* ABS.C: This program computes and displays the absolute values of
    * several numbers.
    */

    #include <stdio.h>
    #include <math.h>
    #include <stdlib.h>

    void main()
    {
        int    ix = -4, iy;
        long   lx = -41567L, ly;
        double dx = -3.141593, dy;

        iy = abs( ix );
        printf( "The absolute value of %d is %d\n", ix, iy);

        ly = labs( lx );
        printf( "The absolute value of %ld is %ld\n", lx, ly);

        dy = fabs( dx );
        printf( "The absolute value of %f is %f\n", dx, dy );
    }


Output



    The absolute value of -4 is 4
    The absolute value of -41567 is 41567
    The absolute value of -3.141593 is 3.141593





ldexp, ldexpl
────────────────────────────────────────────────────────────────────────────


Description

Compute a real number from the mantissa and exponent.

    #include <math.h>

    double ldexp( double x, int exp );

    long double ldexpl( long double x, int exp );

x                                 Floating-point value

exp                               Integer exponent


Remarks

The ldexp and ldexpl functions calculate the value of x * 2exp.


Return Value

The ldexp and ldexpl functions return x * 2exp. If an overflow results, the
functions return ± HUGE_VAL (depending on the sign of x) and set errno to
ERANGE.

The ldexpl function uses the 80-bit, 10-byte coprocessor form of arguments
and return values. See the reference page on the long double functions for
more details on this data type.


Compatibility

ldexp

    ANSI   DOS   OS/2   UNIX   XENIX


ldexpl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

frexp, modf


Example

    /* LDEXP.C */
    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = 4.0, y;
        int p = 3;

        y = ldexp( x, p );
        printf( "%2.1f times two to the power of %d is %2.1f\n", x, p, y );
    }


Output



    4.0 times two to the power of 3 is 32.0





ldiv
────────────────────────────────────────────────────────────────────────────


Description

Computes the quotient and remainder of a long integer.

    #include <stdlib.h>

    ldiv_t ldiv ( long int numer, long int denom );

numer                             Numerator

denom                             Denominator


Remarks

The ldiv function divides numer by denom, computing the quotient and the
remainder. The sign of the quotient is the same as that of the mathematical
quotient. Its absolute value is the largest integer that is less than the
absolute value of the mathematical quotient. If the denominator is 0, the
program will terminate with an error message.

The ldiv function is similar to the div function, with the difference being
that the arguments and the members of the returned structure are all of type
long int.

The ldiv_t structure, defined in STDLIB.H, contains the following elements:


Element                           Description
────────────────────────────────────────────────────────────────────────────
long int quot                     Quotient

long int rem                      Remainder


Return Value

The ldiv function returns a structure of type ldiv_t, comprising both the
quotient and the remainder.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

div


Example

    /* LDIV.C: This program takes two long integers as command-line
    * arguments and displays the results of the integer division.
    */

    #include <stdlib.h>
    #include <math.h>
    #include <stdio.h>

    void main()
    {
        long x = 5149627, y = 234879;
        ldiv_t div_result;

        div_result = ldiv( x, y );
        printf( "For %ld / %ld, the quotient is %ld, and the remainder is
%ld\n",
                x, y, div_result.quot, div_result.rem );
    }


Output



    For 5149627 / 234879, the quotient is 21, and the remainder is 217168





lfind
────────────────────────────────────────────────────────────────────────────


Description

Performs a linear search for the specified key.

#include <search.h>               Required only for function declarations

    char *lfind( const void *key, const void *base, unsigned int *num,
    unsigned int width,
    int ( *compare )( const void *elem1, const void *elem2 ) );

key                               Object to search for

base                              Pointer to base of search data

num                               Number of array elements

width                             Width of array elements

compare( )                        Pointer to comparison routine

elem1                             Pointer to the key for the search

elem2                             Pointer to the array element to be
                                    compared with the key


Remarks

The lfind function performs a linear search for the value key in an array of
num elements; each element is width bytes in size. (Unlike bsearch, lfind
does not require the array to be sorted.) The base argument is a pointer to
the base of the array to be searched.

The compare argument is a pointer to a user-supplied routine that compares
two array elements and then returns a value specifying their relationship.
The lfind function calls the compare routine one or more times during the
search, passing pointers to two array elements on each call. This routine
must compare the elements, then return one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
Nonzero                           Elements are different

0                                 Elements are identical


Return Value

If the key is found, lfind returns a pointer to the element of the array at
base that matches key. If the key is not found, lfind returns NULL.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

bsearch, lsearch, qsort


Example

    /* LFIND.C: This program uses lfind to search for the word "hello"
    * in the command-line arguments.
    */

    #include <search.h>
    #include <string.h>
    #include <stdio.h>

    int compare( char **arg1, char **arg2 );

    void main( int argc, char **argv )
    {
        char **result;
        char *key = "hello";

        result = (char **)lfind( (char *)&key, (char *)argv,
                                &argc, sizeof( char * ), compare );
        if( result )
        printf( "%s found\n", *result );
        else
        printf( "hello not found!\n" );
    }

    int compare(char ** arg1, char **arg2 )
    {
        return( strcmpi( *arg1, *arg2 ) );
    }


Output






    [C:\LIBREF] lfind What if I said Hello world
    Hello found





_lineto Functions
────────────────────────────────────────────────────────────────────────────


Description

Draw lines to specified points.

    #include <graph.h>

    short _far _lineto( short x, short y );

    short _far _lineto_w( double wx, double wy );

x, y                              End point

wx, wy                            End point


Remarks

The functions in the _lineto family draw a line from the current graphics
position up to and including the destination point. The destination point
for the _lineto function is given by the view-coordinate point (x, y). The
destination point for the _lineto_w function is given by the
window-coordinate point (wx, wy).

The line is drawn using the current color, logical write mode, and line
style. If no error occurs, _lineto sets the current graphics position to the
view-coordinate point (x, y); _lineto_w sets the current position to the
window-coordinate point (wx, wy).

If you use _floodfill to fill in a closed figure drawn with _lineto calls,
the figure must be drawn with a solid line-style pattern.


Return Value

The _lineto and _lineto_w routines return a nonzero value if anything is
drawn; otherwise, they return 0.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getcurrentposition functions,  _moveto functions,  _setlinestyle


Example

    /* MOVETO.C: This program draws line segments of different colors. */

    #include <graph.h>
    #include <stdlib.h>
    #include <conio.h>

    void main()
    {
        short x, y, xinc, yinc, color = 1;
        struct videoconfig v;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );
        _getvideoconfig( &v );
        xinc = v.numxpixels / 50;
        yinc = v.numypixels / 50;

        for( x = 0, y = v.numypixels - 1; x < v.numxpixels; x += xinc, y -=
yinc )
        {
        _setcolor( color++ % 16 );
        _moveto( x, 0 );
        _lineto( 0, y );
        }
        getch();

        _setvideomode( _DEFAULTMODE );
    }





localeconv
────────────────────────────────────────────────────────────────────────────


Description

Gets detailed information on locale settings.

    #include <locale.h>

    struct lconv *localeconv( void );


Remarks

The localeconv function gets detailed information on the locale-specific
settings for numeric formatting of the program's current locale. This
information is stored in a structure of type lconv.

The lconv structure, defined in LOCALE.H, contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
char *decimal_point               Decimal-point character for nonmonetary
                                    quantities.

char *thousands_sep               Character used to separate groups of
                                    digits to the left of the decimal point
                                    for non-monetary quantities.

char *grouping                    Size of each group of digits in
                                    non-monetary quantities.

char *int_curr_symbol             International currency symbol for the
                                    current locale. The first three
                                    characters specify the alphabetic
                                    international currency symbol as defined
                                    in the ISO 4217 Codes for the
                                    Representation of Currency and Funds
                                    standard. The fourth character
                                    (immediately preceding the null
                                    character) is used to separate the
                                    international currency symbol from the
                                    monetary quantity.

char *currency_symbol             Local currency symbol for the current
                                    locale.

char *mon_decimal_point           Decimal-point character for monetary
                                    quantities.

char *mon_thousands_sep           Separator for groups of digits to the
                                    left of the decimal place in monetary
                                    quantities.

char *mon_grouping                Size of each group of digits in monetary
                                    quantities.

char *positive_sign               String denoting sign for nonnegative
                                    monetary quantities.

char *negative_sign               String denoting sign for negative
                                    monetary
                                    quantities.

char int_frac_digits              Number of digits to the right of the
                                    decimal point in internationally
                                    formatted
                                    monetary quantities.

char frac_digits                  Number of digits to the right of the
                                    decimal point in formatted monetary
                                    quantities.

char p_cs_precedes                Set to 1 if the currency symbol precedes
                                    the value for a nonnegative formatted
                                    monetary quantity. Set to 0 if the
                                    symbol follows the value.

char p_sep_by_space               Set to 1 if the currency symbol is
                                    separated by a space from the value for
                                    a non-negative formatted monetary
                                    quantity. Set to 0 if there is no space
                                    separation.

char n_cs_precedes                Set to 1 if the currency symbol precedes
                                    the value for a negative formatted
                                    monetary quantity. Set to 0 if the
                                    symbol succeeds the value.

char n_sep_by_space               Set to 1 if the currency symbol is
                                    separated by a space from the value for
                                    a negative formatted monetary quantity.
                                    Set to 0 if there is no space
                                    separation.

char p_sign_posn                  Position of positive sign in nonnegative
                                    formatted monetary quantities.

char n_sign_posn                  Position of positive sign in negative
                                    formatted monetary quantities.

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

Value                             Interpretation
────────────────────────────────────────────────────────────────────────────
CHAR_MAX                          No further grouping is to be performed.

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

n                                 The integer value n is the number of
                                    digits that make up the current group.
                                    The next element is examined to
                                    determine the size of the next group of
                                    digits before the current group.

The values for p_sign_posn and n_sign_posn are interpreted according to the
following rules:

Value                             Interpretation
────────────────────────────────────────────────────────────────────────────
0                                 Parentheses surround the quantity and
                                    currency symbol

1                                 Sign string precedes the quantity and
                                    currency symbol

2                                 Sign string follows the quantity and
                                    currency symbol

3                                 Sign string immediately precedes the
                                    currency symbol

4                                 Sign string immediately follows the
                                    currency symbol


Return Value

The localeconv function returns a pointer to a structure of lconv type.
Calls to the setlocale function with category values of LC_ALL, LC_MONETARY,
or LC_NUMERIC will overwrite the contents of the structure.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

setlocale, strcoll, strftime, strxfrm





localtime
────────────────────────────────────────────────────────────────────────────


Description

Converts a time value and corrects for the local time zone.

    #include <time.h>

    struct tm *localtime( const time_t *timer );

timer                             Pointer to stored time


Remarks

The localtime function converts a time stored as a time_t value and stores
the result in a structure of type tm. The long value timer represents the
seconds elapsed since 00:00:00, January 1, 1970, Greenwich mean time; this
value is usually obtained from the time function.

The fields of the structure type tm store the following values:

Element                           Value Stored
────────────────────────────────────────────────────────────────────────────
int tm_sec                        Seconds

int tm_min                        Minutes

int tm_hour                       Hours (0 -24)

int tm_mday                       Day of month (1-31)

int tm_mon                        Month (0 -11; January = 0)

int tm_year                       Year (current year minus 1900)

int tm_wday                       Day of week (0 - 6; Sunday = 0)

int tm_yday                       Day of year (0 -365; January 1 = 0)

int tm_isdst                      Nonzero if daylight saving time is in
                                    effect, otherwise 0

Note that the gmtime, mktime, and localtime functions use a single
statically allocated tm structure for the conversion. Each call to one of
these routines destroys the result of the previous call.

The localtime function makes corrections for the local time zone if the user
first sets the environment variable TZ. When TZ is set, three other
environment variables (timezone, daylight, and tzname) are automatically set
as well. See tzset for a description of these variables.

The TZ variable is not part of the ANSI standard definition of localtime but
is a Microsoft extension.


Return Value

The localtime function returns a pointer to the structure result. DOS and
OS/2 do not accommodate dates prior to 1980. If the value in timer
represents a date prior to January 1, 1980, the function returns NULL.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

asctime, ctime, ftime, gmtime, time, tzset


Example

    /* LOCALTIM.C: This program uses time to get the current time and
    * then uses localtime to convert this time to a structure representing
    * the local time. The program converts the result from a 24-hour clock
    * to a 12-hour clock and determines the proper extension (AM or PM).
    */

    #include <stdio.h>
    #include <string.h>
    #include <time.h>

    void main()
    {
        struct tm *newtime;
        char  am_pm[] = "AM";
        time_t long_time;

        time( &long_time );                 /* Get time as long integer. */
        newtime = localtime( &long_time );  /* Convert to local time. */

        if( newtime->tm_hour < 12 )         /* Set up extension. */
        strcpy( am_pm, "AM" );
        if( newtime->tm_hour > 12 )         /* Convert from 24-hour */
        newtime->tm_hour -=12;           /*   to 12-hour clock.  */

        printf( "%.19s %s\n", asctime( newtime ), am_pm );
    }


Output



    Fri Jun 16 06:27:02 AM





locking
────────────────────────────────────────────────────────────────────────────


Description

Locks or unlocks bytes of a file.

    #include <sys\locking.h>

#include <io.h>                   Required only for function declarations

    int locking( int handle, int mode, long nbytes );

handle                            File handle

mode                              File-locking mode

nbytes                            Number of bytes to lock


Remarks

The locking function locks or unlocks nbytes bytes of the file specified by
handle. Locking bytes in a file prevents access to those bytes by other
processes. All locking or unlocking begins at the current position of the
file pointer and proceeds for the next nbytes bytes. It is possible to lock
bytes past the end of the file.

The mode argument specifies the locking action to be performed. It must be
one of the following manifest constants:

Constant                          Action
────────────────────────────────────────────────────────────────────────────
LK_LOCK                           Locks the specified bytes. If the bytes
                                    cannot be locked, immediately tries
                                    again after 1 second. If, after 10
                                    attempts, the bytes cannot be locked,
                                    returns an error.

LK_NBLCK                          Locks the specified bytes. If bytes
                                    cannot be locked, returns an error.

LK_NBRLCK                         Same as LK_NBLCK.

LK_RLCK                           Same as LK_LOCK.

LK_UNLCK                          Unlocks the specified bytes. (The bytes
                                    must have been previously locked.)

More than one region of a file can be locked, but no overlapping regions are
allowed.

When a region of a file is being unlocked, it must correspond to a region
that was previously locked. The locking function does not merge adjacent
regions; if two locked regions are adjacent, each region must be unlocked
separately.

Regions should be locked only briefly and should be unlocked before closing
a file or exiting the program.

The locking function should be used only under OS/2 or under DOS versions
3.0 and later; it has no effect under earlier versions of DOS. Also, file
sharing must be loaded to use the locking function. Note that under DOS
versions 3.0 and 3.1, the files locked by parent processes may become
unlocked when child processes exit.


Return Value

The locking function returns 0 if successful. A return value of -1 indicates
failure, and errno is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Locking violation (file already locked
                                    or unlocked).

EBADF                             Invalid file handle.

EDEADLOCK                         Locking violation. This is returned when
                                    the LK_LOCK or LK_RLCK flag is specified
                                    and the file cannot be locked after 10
                                    attempts.

EINVAL                            An invalid argument was given to the
                                    function.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

creat, open


Example

    /* LOCKING.C: This program opens a file with sharing. It locks some
    * bytes before reading them, then unlocks them. Note that the program
    * works correctly only if the following conditions are met:
    *     - The file exists
    *     - The program is run under OS/2, under DOS 3.0 or later
    *       with file sharing installed (SHARE.COM or SHARE.EXE), or
    *       if a Microsoft Networks compatible network is running
    */

    #include <io.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <sys\locking.h>
    #include <share.h>
    #include <fcntl.h>
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        int  fh, numread;
        long pos, result;
        char buffer[40];

        /* Quit if can't open file or DOS version doesn't support sharing. */
        fh = sopen( "locking.c", O_RDWR, SH_DENYNO, S_IREAD | S_IWRITE );
        if( (fh == -1) || (_osmajor < 3) )
        exit( 1 );

        /* Lock some bytes and read them. Then unlock. */
        if( locking( fh, LK_NBLCK, 30L ) != -1 )
        {
        printf( "No one can change these bytes while I'm reading them\n" );
        numread = read( fh, buffer, 30 );
        printf( "%d bytes read: %.30s\n", numread, buffer );
        locking( fh, LK_UNLCK, 30L );
        printf( "Now I'm done. Do what you will with them\n" );
        }
        else
        perror( "Locking failed\n" );

        close( fh );
    }


Output



    No one can change these bytes while I'm reading them
    30 bytes read: /* LOCKING.C: This program ope
    Now I'm done. Do what you will with them





log Functions
────────────────────────────────────────────────────────────────────────────


Description

Calculate logarithms.

    #include <math.h>

    double log( double x );

    double log10( double x );

    long double logl( long double x );

    long double log10l( long double x );

x                                 Value whose logarithm is to be found


Remarks

The log and log10 functions calculate the natural logarithm and the base-10
logarithm, respectively, of x. The logl and log10l functions are the 80-bit
counterparts and use the 80-bit, 10-byte coprocessor form of arguments and
return values. See the reference page on the long double functions for more
details on this data type.


Return Value

The log functions return the logarithm of the argument x. If x is negative,
the functions print a DOMAIN error message to stderr, return the value
-HUGE_VAL, and set errno to EDOM. If x is 0, the functions print a SING
error message to stderr, return the value -HUGE_VAL, and set errno to
ERANGE.

Error handling can be modified by using the matherr or _matherrl routine.


Compatibility

log, log10

    ANSI   DOS   OS/2   UNIX   XENIX


logl, log10l

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

exp, matherr, pow functions


Example

    /* LOG.C: This program uses log and log10 to calculate the natural
    * logarithm and the base-10 logarithm of 9,000.
    */

    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = 9000.0;
        double y;

        y = log( x );
        printf( "log( %.2f ) = %f\n", x, y );
        y = log10( x );
        printf( "log10( %.2f ) = %f\n", x, y );
    }


Output



    log( 9000.00 ) = 9.104980
    log10( 9000.00 ) = 3.954243





long double Functions
────────────────────────────────────────────────────────────────────────────

The 8087 family of numeric coprocessor chips supports the 80-bit precision
floating-point data type. In Microsoft C, version 6.0, the long double
functions, whose names end with l, map the C long double type into this
80-bit, 10-byte form. Unlike the regular floating-point functions (such as
acos), which return values of type double, these long double functions (such
as acosl) return values of type long double. The long double functions also
return their values on the coprocessor stack for all calling conventions.

The long double type is also supported by the addition of the "L" prefix for
a floating-point format specification in the printf and scanf family of
functions.

The long double versions are described on the reference pages for their
regular counterparts. These are the regular C run-time math functions with
corresponding long double equivalents:

Regular Function                  Long Double Form
────────────────────────────────────────────────────────────────────────────
acos                              acosl

asin                              asinl

atan                              atanl

atan2                             atan2l

atof                              _atold

cabs                              cabsl

ceil                              ceill

cos                               cosl

cosh                              coshl

exp                               expl

fabs                              fabsl

floor                             floorl

fmod                              fmodl

frexp                             frexpl

hypot                             hypotl

ldexp                             ldexpl

log                               logl

log10                             log10l

matherr                           _matherrl

modf                              modfl

pow                               powl

sin                               sinl

sinh                              sinhl

sqrt                              sqrtl

tan                               tanl

tanh                              tanhl





longjmp
────────────────────────────────────────────────────────────────────────────


Description

Restores stack environment and execution locale.

    #include <setjmp.h>

    void longjmp( jmp_buf env, int value );

env                               Variable in which environment is stored

value                             Value to be returned to setjmp call


Remarks

The longjmp function restores a stack environment and execution locale
previously saved in env by setjmp. The setjmp and longjmp functions provide
a way to execute a nonlocal goto; they are typically used to pass execution
control to error handling or recovery code in a previously called routine
without using the normal call and return conventions.

A call to setjmp causes the current stack environment to be saved in env. A
subsequent call to longjmp restores the saved environment and returns
control to the point immediately following the corresponding setjmp call.
Execution resumes as if value had just been returned by the setjmp call. The
values of all variables (except register variables) that are accessible to
the routine receiving control contain the values they had when longjmp was
called. The values of register variables are unpredictable.

The longjmp function must be called before the function that called setjmp
returns. If longjmp is called after the function calling setjmp returns,
unpredictable program behavior results.

The value returned by setjmp must be nonzero. If value is passed as 0, the
value 1 is substituted in the actual return.

Observe the following three restrictions when using longjmp:


    1.  Do not assume that the values of the register variables will remain
        the same. The values of register variables in the routine calling
        setjmp may not be restored to the proper values after longjmp is
        executed.

    2.  Do not use longjmp to transfer control from within one overlay to
        within another. The overlay manager keeps the overlay in memory after
        a call to longjmp.

    3.  Do not use longjmp to transfer control out of an interrupt-handling
        routine unless the interrupt is caused by a floating-point exception.
        In this case, a program may return from an interrupt handler via
        longjmp if it first reinitializes the floating-point math package by
        calling _fpreset.



Return Value

None.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

setjmp


Example

See the example for _fpreset.





_lrotl, _lrotr
────────────────────────────────────────────────────────────────────────────


Description

Rotate bits to the left (_lrotl) or right (_lrotr).

    #include <stdlib.h>

    unsigned long _lrotl( unsigned long value, int shift );

    unsigned long _lrotr( unsigned long value, int shift );

value                             Value to be rotated

shift                             Number of bits to shift


Remarks

The _lrotl and _lrotr functions rotate value by shift bits. The _lrotl
function rotates the value left. The _lrotr function rotates the value
right. Both functions "wrap" bits rotated off one end of value to the other
end.


Return Value

Both functions return the rotated value. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_rotl,  _rotr


Example

    /* LROT.C */
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        unsigned long val = 0x0fac35791;

        printf( "0x%8.8lx rotated left eight times is 0x%8.8lx\n",
                val, _lrotl( val, 8 ) );
        printf( "0x%8.8lx rotated right four times is 0x%8.8lx\n",
                val, _lrotr( val, 4 ) );
    }


Output



    0xfac35791 rotated left eight times is 0xc35791fa
    0xfac35791 rotated right four times is 0x1fac3579





lsearch
────────────────────────────────────────────────────────────────────────────


Description

Performs a linear search for a value; adds to end of list if not found.

#include <search.h>               Required only for function declarations

    char *lsearch( const void *key, const void *base, unsigned int *num,
    unsigned int width, int ( *compare )( const void *elem1, const void *elem2
) );

key                               Object to search for

base                              Pointer to base of search data

num                               Number of elements

width                             Width of elements

compare                           Pointer to comparison routine

elem1                             Pointer to the key for the search

elem2                             Pointer to the array element to be
                                    compared with the key


Remarks

The lsearch function performs a linear search for the value key in an array
of num elements, each of width bytes in size. (Unlike bsearch, lsearch does
not require the array to be sorted.) The base argument is a pointer to the
base of the array to be searched.

If key is not found, lsearch adds it to the end of the array.

The compare argument is a pointer to a user-supplied routine that compares
two array elements and returns a value specifying their relationship. The
lsearch function calls the compare routine one or more times during the
search, passing pointers to two array elements on each call. This routine
must compare the elements, then return one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
Nonzero                           Elements are different

0                                 Elements are identical


Return Value

If the key is found, lsearch returns a pointer to the element of the array
at base that matches key. If the key is not found, lsearch returns a pointer
to the newly added item at the end of the array.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

bsearch, lfind


Example

See the example for lfind.





lseek
────────────────────────────────────────────────────────────────────────────


Description

Moves a file pointer to the specified location.

#include <io.h>                   Required only for function declarations

#include <stdio.h>

    long lseek( int handle, long offset, int origin );

handle                            Handle referring to open file

offset                            Number of bytes from origin

origin                            Initial position


Remarks

The lseek function moves the file pointer associated with handle to a new
location that is offset bytes from origin. The next operation on the file
occurs at the new location. The origin argument must be one of the following
constants, which are defined in STDIO.H:

Origin                            Definition
────────────────────────────────────────────────────────────────────────────
SEEK_SET                          Beginning of file

SEEK_CUR                          Current position of file pointer

SEEK_END                          End of file

The lseek function can be used to reposition the pointer anywhere in a file.
The pointer can also be positioned beyond the end of the file. However, an
attempt to position the pointer before the beginning of the file causes an
error.


Return Value

The lseek function returns the offset, in bytes, of the new position from
the beginning of the file. The function returns -1L to indicate an error and
sets errno to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EBADF                             Invalid file handle

EINVAL                            Invalid value for origin, or position
                                    specified by offset is before the
                                    beginning of the file

On devices incapable of seeking (such as terminals and printers), the return
value is undefined.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

fseek, tell


Example

    /* LSEEK.C: This program first opens a file named LSEEK.C.
    * It then uses lseek to find the beginning of the file,
    * to find the current position in the file, and to find
    * the end of the file.
    */

    #include <io.h>
    #include <fcntl.h>
    #include <stdlib.h>
    #include <stdio.h>


    void main()
    {
        int fh;
        long pos;               /* Position of file pointer */
        char buffer[10];

        fh = open( "lseek.c", O_RDONLY );

        /* Seek the beginning of the file: */
        pos = lseek( fh, 0L, SEEK_SET );
        if( pos == -1L )
        perror( "lseek to beginning failed" );
        else
        printf( "Position for beginning of file seek = %ld\n", pos );

        /* Move file pointer a little */
        read( fh, buffer, 10 );

        /* Find current position: */
        pos = lseek( fh, 0L, SEEK_CUR );
        if( pos == -1L )
        perror( "lseek to current position failed" );
        else
        printf( "Position for current position seek = %ld\n", pos );


    /* Set the end of the file: */
        pos = lseek( fh, 0L, SEEK_END );
        if( pos == -1L )
        perror( "lseek to end failed" );
        else
        printf( "Position for end of file seek = %ld\n", pos );

        close( fh );
    }


Output



    Position for beginning of file seek = 0
    Position for current position seek = 10
    Position for end of file seek = 1183





ltoa
────────────────────────────────────────────────────────────────────────────


Description

Converts a long integer to a string.

#include <stdlib.h>               Required only for function declarations

    char *ltoa( long value, char *string, int radix );

value                             Number to be converted

string                            String result

radix                             Base of value


Remarks

The ltoa function converts the digits of value to a null-terminated
character string and stores the result (up to 33 bytes) in string. The radix
argument specifies the base of value, which must be in the range 2-36. If
radix equals 10 and value is negative, the first character of the stored
string is the minus sign (-).


Return Value

The ltoa function returns a pointer to string. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

itoa, ultoa


Example

    /* ITOA.C: This program converts integers of various sizes to strings
    * in various radixes.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        char buffer[20];
        int  i = 3445;
        long l = -344115L;
        unsigned long ul = 1234567890UL;


    itoa( i, buffer, 10 );
        printf( "String of integer %d (radix 10): %s\n", i, buffer );
        itoa( i, buffer, 16 );
        printf( "String of integer %d (radix 16): 0x%s\n", i, buffer );
        itoa( i, buffer, 2  );
        printf( "String of integer %d (radix 2): %s\n", i, buffer );

        ltoa( l, buffer, 16 );
        printf( "String of long int %ld (radix 16): 0x%s\n", l, buffer );

        ultoa( ul, buffer, 16 );
        printf( "String of unsigned long %lu (radix 16): 0x%s\n", ul, buffer );
    }


Output



    String of integer 3445 (radix 10): 3445
    String of integer 3445 (radix 16): 0xd75
    String of integer 3445 (radix 2): 110101110101
    String of long int -344115 (radix 16): 0xfffabfcd
    String of unsigned long 1234567890 (radix 16): 0x499602d2





_makepath
────────────────────────────────────────────────────────────────────────────


Description

Creates a single path name.

    #include <stdlib.h>

    void _makepath( char *path, char *drive, char *dir, char *fname, char *ext
    );

path                              Full path-name buffer

drive                             Drive letter

dir                               Directory path

fname                             File name

ext                               File extension


Remarks

The _makepath routine creates a single path name, composed of a drive
letter, directory path, file name, and file-name extension. The path
argument should point to an empty buffer large enough to hold the complete
path name. The constant _MAX_PATH, defined in STDLIB.H, specifies the
maximum size path that the _makepath function can handle. The other
arguments point to buffers containing the path-name elements:

Buffer                            Description
────────────────────────────────────────────────────────────────────────────
drive                             The drive argument contains a letter (A,
                                    B, etc.) corresponding to the desired
                                    drive and an optional trailing colon.
                                    The _makepath routine will insert the
                                    colon automatically in the composite
                                    path name if it is missing. If drive is
                                    a null character or an empty string, no
                                    drive letter and colon will appear in
                                    the composite path string.

dir                               The dir argument contains the path of
                                    directories, not including the drive
                                    designator or the actual file name. The
                                    trailing slash is optional, and either
                                    forward slashes ( / ) or backslashes ( \
                                    ) or both may be used in a single dir
                                    argument. If a trailing slash ( / or \ )
                                    is not specified, it will be inserted
                                    automatically. If dir is a null
                                    character or an empty string, no slash
                                    is inserted in the composite path
                                    string.

fname                             The fname argument contains the base
                                    file name without any extensions. If
                                    fname is NULL or points to an empty
                                    string, no file name is inserted in the
                                    composite path string.

ext                               The ext argument contains the actual
                                    file-name extension, with or without a
                                    leading period (.). The _makepath
                                    routine will insert the period
                                    automatically if it does not appear in
                                    ext. If ext is a null character or an
                                    empty string, no period is inserted in
                                    the composite path string.

There are no size limits on any of the above four fields. However, the
composite path must be no larger than the _MAX_PATH constant. The _MAX_PATH
limit permits a path name much larger than any of the current versions of
DOS or OS/2 will handle.


Return Value

None.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

_fullpath,  _splitpath


Example

    /* MAKEPATH.C */
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        char path_buffer[_MAX_PATH];
        char drive[_MAX_DRIVE];
        char dir[_MAX_DIR];
        char fname[_MAX_FNAME];
        char ext[_MAX_EXT];

        _makepath( path_buffer, "c", "\\c60\\clibref\\", "makepath", "c" );
        printf( "Path created with _makepath: %s\n\n", path_buffer );
        _splitpath( path_buffer, drive, dir, fname, ext );
        printf( "Path extracted with _splitpath:\n" );
        printf( "  Drive: %s\n", drive );
        printf( "  Dir: %s\n", dir );
        printf( "  Filename: %s\n", fname );
        printf( "  Ext: %s\n", ext );
    }


Output



    Path created with _makepath: c:\c60\clibref\makepath.c

    Path extracted with _splitpath:
    Drive: c:
    Dir: \c60\clibref\
    Filename: makepath
    Ext: .c

♀



malloc Functions
────────────────────────────────────────────────────────────────────────────


Description

Allocate memory blocks.



#include <stdlib.h>               For ANSI compatibility (malloc only)

#include <malloc.h>               Required only for function declarations

    void *malloc( size_t size );

    void _based(void) *_bmalloc( _segment seg, size_t size );

    void _far *_fmalloc( size_t size );

    void _near *_nmalloc( size_t size );

size                              Bytes to allocate

seg                               Based heap segment selector


Remarks

Functions in the malloc family allocate a memory block of at least size
bytes. The block may be larger than size bytes because of space required for
alignment and maintenance information. If size is 0, each of these functions
allocates a zero-length item in the heap and returns a valid pointer to that
item.

The storage space pointed to by the return value is guaranteed to be
suitably aligned for storage of any type of object. To get a pointer to a
type other than void, use a type cast on the return value.

In large data models (compact-, large-, and huge-model programs), malloc
maps to _fmalloc. In small data models (tiny-, small-, and medium-model
programs), malloc maps to _nmalloc.

The _fmalloc function allocates a memory block of at least size bytes in the
far heap, which is outside the default data segment. The return value is a
far pointer to void.

The _bmalloc function allocates a memory block of at least size bytes in the
based heap segment specified by the segment selector seg.

The malloc functions allocate memory in the heap segment specified below.

Function                          Heap Segment
────────────────────────────────────────────────────────────────────────────
malloc                            Depends on data model of program

_bmalloc                          Based heap segment specified by seg
                                    value

_fmalloc                          Far heap (outside default data segment)

_nmalloc                          Near heap (within default data segment)

If you are creating programs to run in both real mode and protected mode,
you should probably bind with APILMR.OBJ as well as API.LIB and OS2.LIB.
This is necessary if a program will use the _nmalloc function.

The functions listed below call the malloc family of routines. In addition,
the C start-up code uses malloc to allocate storage for the environ/envp and
argv strings and arrays.

The following routines call malloc:

╓┌─────────┌─────────┌───────────────────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
calloc    fseek     _searchenv

────────────────────────────────────────────────────────────────────────────

execv     fsetpos   spawnv

execve    fullpath  spawnve

execvp    fwrite    spawnvp

execvpe   getc      spawnvpe

execl     getchar   spawnl

execle    getcwd    spawnle

execlp    _getcwd   spawnlp

execlpe   gets      spawnlpe

fgetc     getw      strdup

fgetchar  _popen    system
────────────────────────────────────────────────────────────────────────────
fgetchar  _popen    system

fgets     printf    scanf

fprint    putc      setvbuf

fputc     putchar   tempnam

fputchar  putenv    ungetc

fputs     puts      vfprintf

fread     putw      vprintf

fscanf



The following routines call malloc only in the multithread run-time
libraries (LLIBCMT, LLIBCDLL, CDLLOBJS), not in the regular run-time
libraries:

╓┌─────────────┌──────────┌──────────────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
asctime       localtime  _strerrpr

_beginthread  mktime     tmpfile

ctime         sterror    tmpnam

gmtime



The following routines call _nmalloc:

────────────────────────────────────────────────────────────────────────────
_nrealloc

_ncalloc

_nstrdup

realloc (in small data models)


The following routines call _fmalloc:

────────────────────────────────────────────────────────────────────────────
_frealloc

_fcalloc

_fstrdup

realloc (in large data models)


────────────────────────────────────────────────────────────────────────────
C5.1 Differences
In Microsoft C version 5.1, the _fmalloc function would retry allocating
within the default data segment (i.e., in the near heap) if sufficient
memory was not available outside the default data segment. Version 6.0
returns NULL under these conditions.
In version 5.1, the start-up code used malloc only if wild-card expansion
was used.

The _freect, _memavl, and _memmax functions called malloc in version 5.1 but
do not do so in version 6.0.
────────────────────────────────────────────────────────────────────────────


Return Value

The malloc function returns a void pointer to the allocated space. The
_nmalloc function returns a ( void _near * ) and _fmalloc returns a ( void
_far * ). The _bmalloc function returns a ( void _based( void ) * ).

The _malloc, _fmalloc and _nmalloc functions return NULL if there is
insufficient memory available. The _bmalloc function returns _NULLOFF if
there is insufficient memory available.

Always check the return from the malloc function, even if the amount of
memory requested is small.


Compatibility

malloc

    ANSI   DOS    OS/2    UNIX    XENIX


_bmalloc, _fmalloc, _nmalloc

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

calloc functions, free functions, realloc functions


Example

    /* MALLOC.C: This program allocates memory with malloc, then frees
    * the memory with free.
    */

    #include <stdlib.h>         /* Definition of _MAX_PATH */
    #include <stdio.h>
    #include <malloc.h>

    void main()
    {
        char *string;

        /* Allocate space for a path name */
        string = malloc( _MAX_PATH );
        if( string == NULL )
        printf( "Insufficient memory available\n" );
        else
        printf( "Memory space allocated for pathname\n" );
        free( string );
        printf( "Memory freed\n" );
    }


Output



    Memory space allocated for pathname
    Memory freed





matherr, _matherrl
────────────────────────────────────────────────────────────────────────────


Description

Handle math errors.

    #include <math.h>

    int matherr( struct exception *except );

    int _matherrl( struct _exceptionl *except );

except                            Pointer to structure containing error
                                    information


Remarks

The matherr functions process errors generated by the functions of the math
library. The math functions call the appropriate matherr routine whenever an
error is detected. The _matherrl function uses the 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.

The user can provide a different definition of the matherr or _matherrl
function to carry out special error handling.

When an error occurs in a math routine, matherr is called with a pointer to
an exception type structure (defined in MATH.H) as an argument.

The exception structure contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
int type                          Exception type

char *name                        Name of function where error occurred

double arg1, arg2                 First and second (if any) argument to
                                    function

double retval                     Value to be returned by function

The type specifies the type of math error. It is one of the following
values, defined in MATH.H:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
DOMAIN                            Argument domain error

SING                              Argument singularity

OVERFLOW                          Overflow range error

PLOSS                             Partial loss of significance

TLOSS                             Total loss of significance

UNDERFLOW                         Underflow range error

The structure member name is a pointer to a null-terminated string
containing the name of the function that caused the error. The structure
members arg1 and arg2 specify the values that caused the error. (If only one
argument is given, it is stored in arg1.)

The default return value for the given error is retval. If you change the
return value, remember that the return value must specify whether an error
actually occurred. If the matherr function returns 0, an error message is
displayed and errno is set to an appropriate error value. If matherr returns
a nonzero value, no error message is displayed, and errno remains unchanged.



Return Value

The matherr functions should return 0 to indicate an error, and a nonzero
value to indicate successful corrective action.


Compatibility

matherr

▼ ANSI   DOS    OS/2    UNIX    XENIX


_matherrl

▼ ANSI   DOS   OS/2   ▼ UNIX   ▼ XENIX



See Also

acos functions, asin functions, atan functions, bessel functions, cabs, cos
functions, exp, hypot, log functions, pow, sin functions, sqrt, tan
functions


Example

    /* MATHERR.C: To use matherr, you must turn off the Extended Dictionary
    * flag within the Microsoft Programmer's WorkBench environment, or use
the
    * /NOE linker option outside the environment. For example:
    *      CL matherr.c /link /NOE
    */

    #include <math.h>
    #include <string.h>
    #include <stdio.h>

    void main()
    {
        /* Do several math operations that cause errors. The matherr
        * routine handles DOMAIN errors, but lets the system handle
        * other errors normally.
        */
        printf( "log( -2.0 ) = %e\n", log( -2.0 ) );
        printf( "log10( -5.0 ) = %e\n", log10( -5.0 ) );
        printf( "log( 0.0 ) = %e\n", log( 0.0 ) );
    }

    /* Handle several math errors caused by passing a negative argument
    * to log or log10 (DOMAIN errors). When this happens, matherr returns
    * the natural or base-10 logarithm of the absolute value of the
    * argument and suppresses the usual error message.
    */
    int matherr( struct exception *except )
    {
        /* Handle DOMAIN errors for log or log10. */
        if( except->type == DOMAIN )
        {
            if( strcmp( except->name, "log" ) == 0 )
            {
                except->retval = log( -(except->arg1) );
                printf( "Special: using absolute value: %s: DOMAIN error\n",
                        except->name );
                return 1;
            }
            else if( strcmp( except->name, "log10" ) == 0 )
            {
                except->retval = log10( -(except->arg1) );
                printf( "Special: using absolute value: %s: DOMAIN error\n",
                        except->name );
                return 1;
            }
        }
        else
        {
            printf( "Normal: " );
            return 0;    /* Else use the default actions */
        }
    }


Output



    Special: using absolute value: log: DOMAIN error
    log( -2.0 ) = 6.931472e-001
    Special: using absolute value: log10: DOMAIN error
    log10( -5.0 ) = 6.989700e-001
    Normal: log: SING error
    log( 0.0 ) = -1.797693e+308





max
────────────────────────────────────────────────────────────────────────────


Description

Returns the larger of two values.

    #include <stdlib.h>

    type max( type a, type b );

type                              Any numeric data type

a, b                              Values of any numeric type to be
                                    compared


Remarks

The max macro compares two values and returns the value of the larger one.
The arguments can be of any numeric data type, signed or unsigned. Both
arguments and the return value must be of the same data type.


Return Value

The macro returns the larger of the two arguments.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

min


Example

    /* MINMAX.C */
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        int a = 10;
        int b = 21;

        printf( "The larger of %d and %d is %d\n",  a, b, max( a, b ) );
        printf( "The smaller of %d and %d is %d\n", a, b, min( a, b ) );
    }


Output



    The larger of 10 and 21 is 21
    The smaller of 10 and 21 is 10





_memavl
────────────────────────────────────────────────────────────────────────────


Description

Returns the size of memory available.

    #include <malloc.h> Required only for function declarations

    size_t _memavl( void );


Remarks

The _memavl function returns the approximate size, in bytes, of the memory
available for dynamic memory allocation in the near heap (default data
segment). The _memavl function can be used with calloc, malloc, or realloc
in tiny, small, and medium memory models and with _ncalloc, _nmalloc or
_nrealloc in any memory model.

The number returned by the _memavl function may not be the number of
contiguous bytes. Consequently, a call to malloc requesting allocation of
the size returned by _memavl may not succeed. Use the _memmax function to
find the size of the largest available contiguous block of memory.


Return Value

The _memavl function returns the size in bytes as an unsigned integer.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

calloc functions,  _freect, malloc functions,  _memmax, realloc functions


Example

    /* MEMAVL.C: This program uses _memavl to determine the amount of
    * memory available for dynamic allocation. It then uses malloc to
    * allocate space for 5,000 long integers and uses _memavl again to
    * determine the new amount of available memory.
    */

    #include <malloc.h>
    #include <stdio.h>

    void main()
    {
        long *longptr;

        printf( "Memory available before _nmalloc = %u\n", _memavl() );
        if( (longptr = _nmalloc( 5000 * sizeof( long ) )) != NULL )
        {
        printf( "Memory available after _nmalloc = %u\n", _memavl() );
        _nfree( longptr );
        }
    }


Output



    Memory available before _nmalloc = 60906
    Memory available after _nmalloc = 40390





memccpy, _fmemccpy
────────────────────────────────────────────────────────────────────────────


Description

Copy characters from a buffer.

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H or MEMORY.H

    void *memccpy( void *dest, void *src, int c, unsigned int count );

    void _far * _far _fmemccpy( void _far *dest, void _far *src, int c,
    unsigned int count );

dest                              Pointer to destination

src                               Pointer to source

c                                 Last character to copy

count                             Number of characters


Remarks

The memccpy and _fmemccpy functions copy 0 or more bytes of src to dest,
halting when the character c has been copied or when count bytes have been
copied, whichever comes first.

The _fmemccpy function is a model-independent (large-model) form of the
memccpy function. It can be called from any point in any program.


Return Value

If the character c is copied, memccpy or _fmemccpy returns a pointer (or far
pointer) to the byte in dest that immediately follows the character. If c is
not copied, memccpy returns NULL.


Compatibility

memccpy

▼ ANSI    DOS    OS/2  ▼ UNIX   ▼ XENIX


_fmemccpy

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

memchr, memcmp, memcpy, memset


Example

    /* MEMCCPY.C */
    #include <memory.h>
    #include <stdio.h>
    #include <string.h>

    char string1[60] = "The quick brown dog jumps over the lazy fox";

    void main()
    {
        char buffer[61];
        char *pdest;

        printf( "Function:\tmemccpy 60 characters or to character 's'\n" );
        printf( "Source:\t\t%s\n", string1 );
        pdest = memccpy( buffer, string1, 's', 60 );
        *pdest = '\0';
        printf( "Result:\t\t%s\n", buffer );
        printf( "Length:\t\t%d characters\n\n", strlen( buffer ) );
    }


Output



    Function:       memccpy 60 characters or to character 's'
    Source:         The quick brown dog jumps over the lazy fox
    Result:         The quick brown dog jumps
    Length:         25 characters





memchr, _fmemchr
────────────────────────────────────────────────────────────────────────────


Description

Find characters in a buffer.

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H (for ANSI
                                    compatibility) or MEMORY.H

    void *memchr( const void *buf, int c, size_t count );

    void _far * _far _fmemchr( const void _far *buf, int c, size_t count );

buf                               Pointer to buffer

c                                 Character to look for

count                             Number of characters


Remarks

The memchr and _fmemchr functions look for the first occurrence of c in the
first count bytes of buf. They stop when they find c or when they have
checked the first count bytes.

The _fmemchr function is a model-independent (large-model) form of the
memchr function. It can be called from any point in any program.


Return Value

If successful, memchr or _fmemchr returns a pointer (or a far pointer) to
the first location of c in buf. Otherwise, they return NULL.


Compatibility

memchr

    ANSI    DOS    OS/2    UNIX    XENIX


_fmemchr

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

memccpy, memcmp, memcpy, memset, strchr


Example

    /* MEMCHR.C */
    #include <memory.h>
    #include <stdio.h>

    int  ch = 'r';
    char str[] =    "lazy";
    char string[] = "The quick brown dog jumps over the lazy fox";
    char fmt1[] =   "         1         2         3         4         5";
    char fmt2[] =   "12345678901234567890123456789012345678901234567890";

    void main()
    {
        char *pdest;
        int result;

        printf( "String to be searched:\n\t\t%s\n", string );
        printf( "\t\t%s\n\t\t%s\n\n", fmt1, fmt2 );

        printf( "Search char:\t%c\n", ch );
        pdest = memchr( string, ch, sizeof( string ) );
        result = pdest - string + 1;
        if( pdest != NULL )
        printf( "Result:\t\t%c found at position %d\n\n", ch, result );
        else
        printf( "Result:\t\t%c not found\n" );
    }


Output



    String to be searched:
                    The quick brown dog jumps over the lazy fox
                            1         2         3         4         5
                    12345678901234567890123456789012345678901234567890

    Search char:    r
    Result:         r found at position 12





memcmp, _fmemcmp
────────────────────────────────────────────────────────────────────────────


Description

Compare characters in two buffers.

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H (for ANSI
                                    compatibility) or MEMORY.H

    int memcmp( const void *buf1, const void *buf2, size_t count );

    int _far _fmemcmp( const void _far *buf1, const void _far *buf2, size_t
    count );

buf1                              First buffer

buf2                              Second buffer

count                             Number of characters


Remarks

The memcmp and _fmemcmp functions compare the first count bytes of buf1 and
buf2 and return a value indicating their relationship, as follows:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
< 0                               buf1 less than buf2

= 0                               buf1 identical to buf2

> 0                               buf1 greater than buf2

The _fmemcmp function is a model-independent (large-model) form of the
memcmp function. It can be called from any point in program.

There is a semantic difference between the function version of memcmp and
its intrinsic version. The function version supports huge pointers in
compact-, large-, and huge-model programs, but the intrinsic version does
not.


Return Value

The memcmp function returns an integer value, as described above.


Compatibility

memcmp

    ANSI    DOS    OS/2    UNIX    XENIX


_fmemcmp

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

memccpy, memchr, memcpy, memset, strcmp, strncmp


Example

    /* MEMCMP.C: This program uses memcmp to compare the strings named
    * first and second. If the first 19 bytes of the strings are
    * equal, the program considers the strings to be equal.
    */

    #include <string.h>
    #include <stdio.h>

    void main()
    {
        char first[]  = "12345678901234567890";
        char second[] = "12345678901234567891";
        int result;

        printf( "Compare '%.19s' to '%.19s':\n", first, second );
        result = memcmp( first, second, 19 );
        if( result < 0 )
        printf( "First is less than second.\n" );
        else if( result == 0 )
        printf( "First is equal to second.\n" );
        else if( result > 0 )
        printf( "First is greater than second.\n" );
        printf( "Compare '%.20s' to '%.20s':\n", first, second );
        result = memcmp( first, second, 20 );
        if( result < 0 )
        printf( "First is less than second.\n" );
        else if( result == 0 )
        printf( "First is equal to second.\n" );
        else if( result > 0 )
        printf( "First is greater than second.\n" );
    }


Output



    Compare '1234567890123456789' to '1234567890123456789':
    First is equal to second.
    Compare '12345678901234567890' to '12345678901234567891':
    First is less than second.





memcpy, _fmemcpy
────────────────────────────────────────────────────────────────────────────


Description

Copy characters between buffers.

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H (for ANSI
                                    compatibility) or MEMORY.H

    void *memcpy( void *dest, const void *src, size_t count );

    void _far  * _far _fmemcpy( void _far *dest, const void _far *src, size_t
    count );

dest                              New buffer

src                               Buffer to copy from

count                             Number of characters to copy


Remarks

The memcpy and _fmemcpy functions copy count bytes of src to dest. If the
source and destination overlap, these functions do not ensure that the
original source bytes in the overlapping region are copied before being
overwritten. Use memmove to handle overlapping regions.

The _fmemcpy function is a model-independent (large-model) form of the
memcpy function. It can be called from any point in any program.

There is a semantic difference between the function version of memcpy and
its intrinsic version. The function version supports huge pointers in
compact-, large-, and huge-model programs, but the intrinsic version does
not.


Return Value

The memcpy and _fmemcpy functions return a pointer to dest.


Compatibility

memcpy

    ANSI    DOS    OS/2    UNIX    XENIX


_fmemcpy

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

memccpy, memchr, memcmp, memmove, memset, strcpy, strncpy


Example

    /* MEMCPY.C. Illustrate overlapping copy: memmove handles it
    * correctly; memcpy does not.
    */
    #include <memory.h>
    #include <string.h>
    #include <stdio.h>

    char string1[60] = "The quick brown dog jumps over the lazy fox";
    char string2[60] = "The quick brown fox jumps over the lazy dog";
    /*                           1         2         3         4         5
    *                  12345678901234567890123456789012345678901234567890
    */
    void main()
    {
        printf( "Function:\tmemcpy without overlap\n" );
        printf( "Source:\t\t%s\n", string1 + 40 );
        printf( "Destination:\t%s\n", string1 + 16 );
        memcpy( string1 + 16, string1 + 40, 3 );
        printf( "Result:\t\t%s\n", string1 );
        printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );

        /* Restore string1 to original contents */
        memcpy( string1 + 16, string2 + 40, 3 );

        printf( "Function:\tmemmove with overlap\n" );
        printf( "Source:\t\t%s\n", string2 + 4 );
        printf( "Destination:\t%s\n", string2 + 10 );
        memmove( string2 + 10, string2 + 4, 40 );
        printf( "Result:\t\t%s\n", string2 );
        printf( "Length:\t\t%d characters\n\n", strlen( string2 ) );

        printf( "Function:\tmemcpy with overlap\n" );
        printf( "Source:\t\t%s\n", string1 + 4 );
        printf( "Destination:\t%s\n", string1 + 10 );
        memcpy( string1 + 10, string1 + 4, 40 );
        printf( "Result:\t\t%s\n", string1 );
        printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );

    }


Output



    Function:       memcpy without overlap
    Source:         fox
    Destination:    dog jumps over the lazy fox
    Result:         The quick brown fox jumps over the lazy fox
    Length:         43 characters

    Function:       memmove with overlap
    Source:         quick brown fox jumps over the lazy dog
    Destination:    brown fox jumps over the lazy dog
    Result:         The quick quick brown fox jumps over the lazy dog
    Length:         49 characters

    Function:       memcpy with overlap
    Source:         quick brown dog jumps over the lazy fox
    Destination:    brown dog jumps over the lazy fox
    Result:         The quick quick quick quick quick quick quick quic
    Length:         50 characters





memicmp, _fmemicmp
────────────────────────────────────────────────────────────────────────────


Description

Compare characters in two buffers (case-insensitive).

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H or MEMORY.H

    int memicmp( void *buf1, void *buf2, unsigned int count );

    int _far _fmemicmp( void _far *buf1, void _far *buf2, unsigned int count
    );

buf1                              First buffer

buf2                              Second buffer

count                             Number of characters


Remarks

The memicmp and _fmemicmp functions compare the first count characters of
the two buffers buf1 and buf2 byte-by-byte. The comparison is made without
regard to the case of letters in the two buffers; that is, uppercase and
lowercase letters are considered equivalent. The memicmp and _fmemicmp
functions return a value indicating the relationship of the two buffers, as
follows:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
< 0                               buf1 less than buf2

= 0                               buf1 identical to buf2

> 0                               buf1 greater than buf2

The _fmemicmp function is a model-independent (large-model) form of the
memicmp function. It can be called from any point in any program.


Return Value

The memicmp and _fmemicmp functions return an integer value, as described
above.


Compatibility

memicmp

▼ ANSI    DOS    OS/2    UNIX    XENIX


_fmemicmp

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

memccpy, memchr, memcmp, memcpy, memset, stricmp, strnicmp


Example

    /* MEMICMP.C: This program uses memicmp to compare the first
    * 29 letters of the strings named first and second without
    * regard to the case of the letters.
    */

    #include <memory.h>
    #include <stdio.h>
    #include <string.h>

    void main()
    {
        int result;
        char first[]  = "Those Who Will Not Learn from History";
        char second[] = "THOSE WHO WILL NOT LEARN FROM their mistakes";
        /* Note that the 29th character is right here ^ */

        printf( "Compare '%.29s' to '%.29s'\n", first, second );
        result = memicmp( first, second, 29 );
        if( result < 0 )
        printf( "First is less than second.\n" );
        else if( result == 0 )
        printf( "First is equal to second.\n" );
        else if( result > 0 )
        printf( "First is greater than second.\n" );
    }


Output



    Compare 'Those Who Will Not Learn from' to 'THOSE WHO WILL NOT LEARN FROM'
    First is equal to second.





_memmax
────────────────────────────────────────────────────────────────────────────


Description

Finds the size of the largest contiguous memory block.

    #include <malloc.h>

    size_t _memmax( void );


Remarks

The _memmax function returns the size (in bytes) of the largest contiguous
block of memory that can be allocated from the near heap (i.e., the default
data segment). Calling _nmalloc with the value returned by the _memmax
function will succeed as long as _memmax returns a nonzero value.


Return Value

The function returns the block size, if successful. Otherwise, it returns 0,
indicating that nothing more can be allocated from the near heap.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

malloc functions, msize functions


Example

    /* MEMMAX.C: This program uses _memmax and _nmalloc to allocate
    * the largest block of memory available in the near heap.
    */

    #include <stddef.h>
    #include <malloc.h>
    #include <stdio.h>

    void main()
    {
        size_t contig;
        char *p;

    /* Determine contiguous memory size */
        contig = _memmax();
        printf( "Largest block of available memory is %u bytes long\n", contig
);
        if( contig )
        {
        p = _nmalloc( contig * sizeof( int ) );
        if( p == NULL )
            printf( "Error with malloc (should never occur)\n" );
        else
        {
            printf( "Maximum allocation succeeded\n" );
            free( p );
        }
        }
        else
        printf( "Near heap is already full\n" );
    }


Output



    Largest block of available memory is 60844 bytes long
    Maximum allocation succeeded





memmove, _fmemmove
────────────────────────────────────────────────────────────────────────────


Description

Move one buffer to another.

    #include <string.h>

    void *memmove( void *dest, const void *src, size_t count );

    void _far * _far _fmemmove( void _far *dest, const void _far *src, size_t
    count );

dest                              Destination object

src                               Source object

count                             Number of characters to copy


Remarks

The memmove and _fmemmove functions copy count characters from the source
(src) to the destination (dest). If some regions of the source area and the
destination overlap, the memmove and _fmemmove functions ensure that the
original source bytes in the overlapping region are copied before being
overwritten.

The _fmemmove function is a model-independent (large-model) form of the
memmove function. It can be called from any point in any program.


Return Value

The memmove and _fmemmove functions return the value of dest.


Compatibility

memmove

    ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX


_fmemmove

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

memccpy, memcpy, strccpy, strncpy


Example

    /* MEMCPY.C. Illustrate overlapping copy: memmove handles it
    * correctly; memcpy does not.
    */
    #include <memory.h>
    #include <string.h>
    #include <stdio.h>

    char string1[60] = "The quick brown dog jumps over the lazy fox";
    char string2[60] = "The quick brown fox jumps over the lazy dog";
    /*                           1         2         3         4         5
    *                  12345678901234567890123456789012345678901234567890
    */
    void main()
    {
        printf( "Function:\tmemcpy without overlap\n" );
        printf( "Source:\t\t%s\n", string1 + 40 );
        printf( "Destination:\t%s\n", string1 + 16 );
        memcpy( string1 + 16, string1 + 40, 3 );
        printf( "Result:\t\t%s\n", string1 );
        printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );

        /* Restore string1 to original contents */
        memcpy( string1 + 16, string2 + 40, 3 );

        printf( "Function:\tmemmove with overlap\n" );
        printf( "Source:\t\t%s\n", string2 + 4 );
        printf( "Destination:\t%s\n", string2 + 10 );
        memmove( string2 + 10, string2 + 4, 40 );
        printf( "Result:\t\t%s\n", string2 );
        printf( "Length:\t\t%d characters\n\n", strlen( string2 ) );

        printf( "Function:\tmemcpy with overlap\n" );
        printf( "Source:\t\t%s\n", string1 + 4 );
        printf( "Destination:\t%s\n", string1 + 10 );
        memcpy( string1 + 10, string1 + 4, 40 );
        printf( "Result:\t\t%s\n", string1 );
        printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );

    }


Output



    Function:       memcpy without overlap
    Source:         fox
    Destination:    dog jumps over the lazy fox
    Result:         The quick brown fox jumps over the lazy fox
    Length:         43 characters

    Function:       memmove with overlap
    Source:         quick brown fox jumps over the lazy dog
    Destination:    brown fox jumps over the lazy dog
    Result:         The quick quick brown fox jumps over the lazy dog
    Length:         49 characters

    Function:       memcpy with overlap
    Source:         quick brown dog jumps over the lazy fox
    Destination:    brown dog jumps over the lazy fox
    Result:         The quick quick quick quick quick quick quick quic
    Length:         50 characters





memset, _fmemset
────────────────────────────────────────────────────────────────────────────


Description

Set buffers to a specified character.

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H (for ANSI
                                    compatibility) or MEMORY.H

    void *memset( void *dest, int c, size_t count );

    void _far * _far _fmemset( void _far *dest, int c, size_t count );

dest                              Pointer to destination

c                                 Character to set

count                             Number of characters


Remarks

The memset and _fmemset functions set the first count bytes of dest to the
character c.

The _fmemset function is a model-independent (large-model) form of the
memset function. It can be called from any point in any program.

There is a semantic difference between the function version of memset and
its intrinsic version. The function version supports huge pointers in
compact-, large-, and huge-model programs, but the intrinsic version does
not.


Return Value

The memset and _fmemset functions return a pointer to dest.


Compatibility

memset

    ANSI    DOS    OS/2    UNIX    XENIX


_fmemset

▼ ANSI    DOS    OS/2  ▼ UNIX   ▼ XENIX



See Also

memccpy, memchr, memcmp, memcpy, strnset


Example

    /* MEMSET.C: This program uses memset to set the first four bytes
    * of buffer to "*".
    */

    #include <memory.h>
    #include <stdio.h>

    void main()
    {
        char buffer[] = "This is a test of the memset function";

        printf( "Before: %s\n", buffer );
        memset( buffer, '*', 4 );
        printf( "After:  %s\n", buffer );
    }


Output



    Before: This is a test of the memset function
    After:  **** is a test of the memset function





min
────────────────────────────────────────────────────────────────────────────


Description

Returns the smaller of two values.

    #include <stdlib.h>

    type min( type a, type b );

type                              Any numeric data type

a, b                              Values of any numeric type to be
                                    compared


Remarks

The min macro compares two values and returns the value of the smaller one.
The arguments can be of any numeric data type, signed or unsigned. Both
arguments and the return value must be of the same data type.


Return Value

The macro returns the smaller of the two arguments.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

max


Example

    /* MINMAX.C */
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        int a = 10;
        int b = 21;

        printf( "The larger of %d and %d is %d\n",  a, b, max( a, b ) );
        printf( "The smaller of %d and %d is %d\n", a, b, min( a, b ) );
    }


Output



    The larger of 10 and 21 is 21
    The smaller of 10 and 21 is 10





mkdir
────────────────────────────────────────────────────────────────────────────


Description

Creates a new directory.

#include <direct.h>               Required only for function declarations

    int mkdir( char *dirname );

dirname                           Path name for new directory


Remarks

The mkdir function creates a new directory with the specified dirname. Only
one directory can be created at a time, so only the last component of
dirname can name a new directory.

The mkdir function does not do any translation of path-name delimiters. Both
DOS and OS/ 2 accept either " \" or "/ "  internally as valid delimiters
within path names.


Return Value

The mkdir function returns the value 0 if the new directory was created. A
return value of -1 indicates an error, and errno is set to one of the
following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Directory not created. The given name is
                                    the name of an
                                    existing file, directory, or device.

ENOENT                            Path name not found.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

chdir, rmdir


Example

    /* MAKEDIR.C */
    #include <direct.h>
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        int result;

        if( mkdir( "\\testtmp" ) == 0 )
        {
        printf( "Directory '\\testtmp' was successfully created\n" );
        system( "dir \\testtmp" );
        if( rmdir( "\\testtmp" ) == 0 )
            printf( "Directory '\\testtmp' was successfully removed\n"  );
        else
            printf( "Problem removing directory '\\testtmp'\n" );
        }
        else
        printf( "Problem creating directory '\\testtmp'\n" );
    }


Output



    Directory '\testtmp' was successfully created

    The volume label in drive C is OS2.
    Directory of C:\TESTTMP

    .            <DIR>      6-19-89  11:20a
    ..           <DIR>      6-19-89  11:20a
        2 File(s)   12730368 bytes free
    Directory '\testtmp' was successfully removed





mktemp
────────────────────────────────────────────────────────────────────────────


Description

Creates a unique file name.

#include <io.h>                   Required only for function declarations

    char *mktemp( char *template );

template                          File-name pattern


Remarks

The mktemp function creates a unique file name by modifying the given
template argument. The template argument has the form:

baseXXXXXX

where base is the part of the new file name that you supply, and the X's are
placeholders for the part supplied by mktemp; mktemp preserves base and
replaces the six trailing X's with an alphanumeric character followed by a
five-digit value. The five-digit value is a unique number identifying the
calling process. The alphanumeric character is 0 ('0') the first time mktemp
is called with a given template.

In subsequent calls from the same process with copies of the same template,
mktemp checks to see if previously returned names have been used to create
files. If no file exists for a given name, mktemp returns that name. If
files exist for all previously returned names, mktemp creates a new name by
replacing the alphanumeric character in the name with the next available
lowercase letter. For example, if the first name returned is  t012345  and
this name is used to create a file, the next name returned will be  ta12345.
When creating new names, mktemp uses, in order, '0' and then the lowercase
letters 'a' through 'z'.

Note that the original template is modified by the first call to mktemp. If
you then call the mktemp function again with the same template (i.e., the
original one), you will get an error.

The mktemp function generates unique file names but does not create or open
files.


Return Value

The mktemp function returns a pointer to the modified template. The return
value is NULL if the template argument is badly formed or no more unique
names can be created from the given template.


Compatibility

▼ ANSI    DOS    OS/2    UNIX    XENIX



See Also

fopen, getpid, open, tempnam, tmpfile


Example

    /* MKTEMP.C: The program uses mktemp to create five unique file names.
    * It opens each file name to ensure that the next name is unique.
    */

    #include <io.h>
    #include <string.h>
    #include <stdio.h>

    char *template = "fnXXXXXX";
    char *result;
    char names[5][9];

    void main()
    {
        int i;
        FILE *fp;

        for( i = 0; i < 5; i++ )
        {
        strcpy( names[i], template );

        /* Attempt to find a unique file name: */
        result = mktemp( names[i] );
        if( result == NULL )
            printf( "Problem creating the template" );
        else
        {
            if( (fp = fopen( result, "w" )) != NULL )
                printf( "Unique file name is %s\n", result );
            else
                printf( "Cannot open %s\n", result );
            fclose( fp );
        }
        }
    }


Output



    Unique file name is fn000686
    Unique file name is fna00686
    Unique file name is fnb00686
    Unique file name is fnc00686
    Unique file name is fnd00686





mktime
────────────────────────────────────────────────────────────────────────────


Description

Converts the local time to a calendar value.

    #include <time.h>

    time_t mktime( struct tm *timeptr );

timeptr                           Pointer to time structure


Remarks

The mktime function converts the supplied time structure (possibly
incomplete) pointed to by timeptr into a fully defined structure with
"normalized" values and then converts it to a time_t calendar time value.
The structure for the tm is described in the reference page for asctime.

The converted time has the same encoding as the values returned by the time
function. The original values of the tm_wday and tm_yday components of the
timeptr structure are ignored, and the original values of the other
components are not restricted to their normal ranges.

If successful, mktime sets the values of tm_wday and tm_yday appropriately,
and sets the other components to represent the specified calendar time, but
with their values forced to the normal ranges; the final value of tm_mday is
not set until tm_mon and tm_year are determined.

DOS and OS/2 do not accommodate dates prior to 1980. If timeptr references a
date before January 1, 1980, mktime returns -1.

Note that the gmtime and localtime functions use a single statically
allocated buffer for the conversion. If you supply this buffer to mktime,
the previous contents will be destroyed.


Return Value

The mktime function returns the specified calendar time encoded as a value
of type time_t. If the calendar time cannot be represented, the function
returns the value -1 cast as type time_t.


Compatibility

    ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

asctime, gmtime, localtime, time


Example

    /* MKTIME.C: The example takes a number of days as input and returns
    * the time, the current date, and the specified number of days.
    */

    #include <time.h>
    #include <stdio.h>

    void main()
    {
        struct tm when;
        time_t now, result;
        int    days;

        time( &now );
        when = *localtime( &now );
        printf( "Current time is %s\n", asctime( &when ) );
        printf( "How many days to look ahead: " );
        scanf( "%d", &days );

        when.tm_mday = when.tm_mday + days;
        if( (result = mktime( &when )) != (time_t)-1 )
        printf( "In %d days the time will be %s\n",
                days, asctime( &when ) );
        else
        perror( "mktime failed" );
    }


Output



    Current time is Mon Jun 19 11:45:20 1989

    How many days to look ahead: 23
    In 23 days the time will be Wed Jul 12 11:45:20 1989





modf, modfl
────────────────────────────────────────────────────────────────────────────


Description

Split a floating-point value into a mantissa and an exponent.

    #include <math.h>

    double modf( double x, double *intptr );

    long double modfl( long double x, long double *intptr );

x                                 Floating-point value

intptr                            Pointer to stored integer portion


Remarks

The modf functions break down the floating-point value x into fractional and
integer parts, each of which has the same sign as x. The signed fractional
portion of x is returned. The integer portion is stored as a floating-point
value at  intptr.

The modfl function uses the 80-bit, 10-byte coprocessor form of arguments
and return values. See the reference page on the long double functions for
more details on this data type.


Return Value

The modf and modfl functions return the signed fractional portion of x.
There is no error return.


Compatibility

modf

    ANSI    DOS    OS/2    UNIX    XENIX


modfl

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

frexp, ldexp


Example

    /* MODF.C */
    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x, y, n;

        x = -14.87654321;       /* Divide x into its fractional */
        y = modf( x, &n );      /* and integer parts            */

        printf( "For %f, the fraction is %f and the integer is %.f\n", x, y, n
);
    }


Output



    For -14.876543, the fraction is -0.876543 and the integer is -14





movedata
────────────────────────────────────────────────────────────────────────────


Description

Moves characters to another segment.

#include <memory.h>               Required only for function declarations

#include <string.h>               Use either STRING.H (for ANSI
                                    compatibility) or MEMORY.H

    void movedata( unsigned int srcseg, unsigned int srcoff, unsigned int
    destseg,
    unsigned int destoff, unsigned int count );

srcseg                            Segment address of source

srcoff                            Segment offset of source

destseg                           Segment address of destination

destoff                           Segment offset of destination

count                             Number of bytes


Remarks

The movedata function copies count bytes from the source address specified
by srcseg:srcoff to the destination address specified by destseg:destoff.

The movedata function was intended to move far data in small-data-model
programs. The newer model-independent _fmemcpy and _fmemmove functions
should be used instead of the movedata function. In large-data-model
programs, the memcpy and memmove functions can also be used.

Segment values for the srcseg and destseg arguments can be obtained by using
either the segread function or the FP_SEG macro.

The movedata function does not handle all cases of overlapping moves
correctly. These occur when part of the destination is the same memory area
as part of the source. The memmove function correctly handles overlapping
moves.


Return Value

None.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

FP_OFF, FP_SEG, memcpy, memmove, segread


Example

    /* MOVEDATA.C */
    #include <memory.h>
    #include <stdio.h>
    #include <string.h>
    #include <dos.h>
    #include <malloc.h>

    char _far *src = "This is a test.";

    void main()
    {
        char _far *dest;

        if( (dest = _fmalloc( 80 )) != NULL )
        {
        movedata( FP_SEG( src ),  FP_OFF( src ),
                    FP_SEG( dest ), FP_OFF( dest ), _fstrlen( src ) + 1 );
        printf( "The source data at %Fp is '%Fs'\n", src, src );
        printf( "The destination data at %Fp is '%Fs'\n", dest, dest );
        _ffree( dest );
        }
    }


Output



    The source data at 2D0A:02B8 is 'This is a test.'
    The destination data at 3D0B:0016 is 'This is a test.'





_moveto Functions
────────────────────────────────────────────────────────────────────────────


Description

Move current graphics positions.

    #include <graph.h>

    struct xycoord _far _moveto( short x, short y );

    struct _wxycoord _far _moveto_w( double wx, double wy );

x, y                              View-coordinate point

wx, wy                            Window-coordinate point


Remarks

The _moveto functions move the current position to the specified point. The
_moveto function uses the view-coordinate point (x, y) as the current
position. The _moveto_w function uses the window-coordinate point (wx, wy)
as the current position. No drawing takes place.


Return Value

The function returns the coordinates of the previous position. The _moveto
function returns the coordinates in an xycoord structure. The xycoord
structure, defined in GRAPH.H, contains the following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
short xcoord                      x coordinate

short ycoord                      y coordinate

The _moveto_w function returns the coordinates in an _wxycoord structure,
defined in GRAPH.H. The _wxycoord structure contains the following elements:


Element                           Description
────────────────────────────────────────────────────────────────────────────
double wx                         x window coordinate

double wy                         y window coordinate


Compatibility

▼ ANSI    DOS   ▼ OS/2   ▼ UNIX   ▼ XENIX



See Also

_lineto functions


Example

    /* MOVETO.C: This program draws line segments of different colors. */

    #include <graph.h>
    #include <stdlib.h>
    #include <conio.h>

    void main()
    {
        short x, y, xinc, yinc, color = 1;
        struct videoconfig v;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );
        _getvideoconfig( &v );
        xinc = v.numxpixels / 50;
        yinc = v.numypixels / 50;

        for( x = 0, y = v.numypixels - 1; x < v.numxpixels; x += xinc, y -=
yinc )
        {
        _setcolor( color++ % 16 );
        _moveto( x, 0 );
        _lineto( 0, y );
        }
        getch();

        _setvideomode( _DEFAULTMODE );
    }






_msize Functions
────────────────────────────────────────────────────────────────────────────


Description

Return the size of a memory block allocated in the heap.

#include <malloc.h>               Required only for function declarations

    size_t  _msize( void *memblock );

    size_t _bmsize( _segment seg, void _based( void ) *memblock );

    size_t _fmsize( void _far *memblock );

    size_t _nmsize( void _near *memblock );

memblock                          Pointer to memory block

seg                               Based-heap segment selector


Remarks

The _msize family of functions returns the size, in bytes, of the memory
block allocated by a call to the appropriate version of the calloc, malloc,
or realloc functions.

In large data models (compact-, large-, and huge-model programs), _msize
maps to _fmsize. In small data models (tiny-, small-, and medium-model
programs), _msize maps to _nmsize.

The _nmsize function returns the size (in bytes) of the memory block
allocated by a call to _nmalloc, and the _fmsize function returns the size
(in bytes) of the memory block allocated by a call to _fmalloc or _frealloc.
The _bmsize function returns the size of a block allocated in segment seg by
a call to _bmalloc, _bcalloc, or _brealloc.

The location of the memory block is indicated below:

Function                          Data Segment
────────────────────────────────────────────────────────────────────────────
_msize                            Depends on data model of program

_bmsize                           Based heap segment specified by seg
                                    value

_fmsize                           Far heap segment (outside default data
                                    segment)

_nmsize                           Default data segment (inside near heap)


Return Value

All four functions return the size (in bytes) as an unsigned integer.


Compatibility

▼ ANSI    DOS    OS/2   ▼ UNIX   ▼ XENIX



See Also

calloc functions,  _expand functions, malloc functions, realloc functions


Example

    /* REALLOC.C: This program allocates a block of memory for buffer
    * and then uses _msize to display the size of that block. Next, it
    * uses realloc to expand the amount of memory used by buffer
    * and then calls _msize again to display the new amount of
    * memory allocated to buffer.
    */

    #include <stdio.h>
    #include <malloc.h>
    #include <stdlib.h>

    void main()
    {
        long *buffer;
        size_t size;

        if( (buffer = (long *)malloc( 1000 * sizeof( long ) )) == NULL )
        exit( 1 );

        size = _msize( buffer );
        printf( "Size of block after malloc of 1000 longs: %u\n", size );

        /* Reallocate and show new size: */
        if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) ==
NULL )
        exit( 1 );
        size = _msize( buffer );
        printf( "Size of block after realloc of 1000 more longs: %u\n", size );

        free( buffer );
    }


Output



    Size of block after malloc of 1000 longs: 4000
    Size of block after realloc of 1000 more longs: 8000





onexit
────────────────────────────────────────────────────────────────────────────


Description

Registers a routine to be called at exit time.

    #include <stdlib.h>

    onexit_t onexit( onexit_t func );

func                              Pointer to function to be called at exit


Remarks

The onexit function is passed the address of a function (func) to be called
when the program terminates normally. Successive calls to onexit create a
register of functions that is executed in LIFO (last-in-first-out) order. No
more than 32 functions can be registered with onexit; onexit returns the
value NULL if the number of functions exceeds 32. The functions passed to
onexit cannot take parameters.

The onexit function is not part of the ANSI definition, but is instead a
Microsoft extension. The ANSI-standard atexit function does the same thing
as onexit, and should be used instead of onexit when ANSI portability is
desired.

All routines passed to onexit should have the _loadds attribute if used in
multithread dynamic-link libraries.


Return Value

The onexit function returns a pointer to the function if successful and
returns NULL if there is no space left to store the function pointer.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

exit


Example

    /* ONEXIT.C */
    #include <stdlib.h>
    #include <stdio.h>

    /* Prototypes */
    void fn1( void ), fn2( void ), fn3( void ),  fn4( void );

    void main()
    {
        onexit( fn1 );
        onexit( fn2 );
        onexit( fn3 );
        onexit( fn4 );
        printf( "This is executed first.\n" );
    }

    void fn1()
    {
        printf( "next.\n" );
    }

    void fn2()
    {
        printf( "executed " );
    }

    void fn3()
    {
        printf( "is " );
    }

    void fn4()
    {
        printf( "This " );
    }


Output



    This is executed first.
    This is executed next.





open
────────────────────────────────────────────────────────────────────────────


Description

Opens a file.

#include <fcntl.h>

#include <sys\types.h>

#include <sys\stat.h>

#include <io.h>                   Required only for function declarations

    int open( char *filename, int oflag [[, int pmode]] );

filename                          File name

oflag                             Type of operations allowed

pmode                             Permission mode


Remarks

The open function opens the file specified by filename and prepares the file
for subsequent reading or writing, as defined by oflag. The oflag argument
is an integer expression formed from one or more of the manifest constants
defined in FCNTL.H (listed below). When two or more manifest constants are
used to form the oflag argument, the constants are combined with the
bitwise-OR operator ( | ). See Section 2.5, "File Handling," for a
discussion of binary and text modes.

The FCNTL.H file defines the following manifest constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
O_APPEND                          Repositions the file pointer to the end
                                    of the file before every write
                                    operation.

O_BINARY                          Opens file in binary (untranslated)
                                    mode.

O_CREAT                           Creates and opens a new file for
                                    writing; this has no effect if the file
                                    specified by filename exists.

O_EXCL                            Returns an error value if the file
                                    specified by filename exists. Only
                                    applies when used with O_CREAT.

O_RDONLY                          Opens file for reading only; if this
                                    flag is given, neither O_RDWR nor
                                    O_WRONLY can be given.

O_RDWR                            Opens file for both reading and writing;
                                    if this flag is given, neither O_RDONLY
                                    nor O_WRONLY can be given.

O_TEXT                            Opens file in text (translated) mode.

O_TRUNC                           Opens and truncates an existing file to
                                    zero length; the file must have write
                                    permission. The contents of the file are
                                    destroyed. If this flag is given, you
                                    cannot specify O_RDONLY.

O_WRONLY                          Opens file for writing only; if this
                                    flag is given, neither O_RDONLY nor
                                    O_RDWR can be given.

────────────────────────────────────────────────────────────────────────────
WARNING

Use the O_TRUNC flag with care, as it destroys the complete contents of an
existing file.
────────────────────────────────────────────────────────────────────────────

Either O_RDONLY, O_RDWR, or O_WRONLY must be given to specify the access
mode. There is no default value for the access mode.

The pmode argument is required only when O_CREAT is specified. If the file
exists, pmode is ignored. Otherwise, pmode specifies the file's permission
settings, which are set when the new file is closed for the first time. The
pmode is an integer expression containing one or both of the manifest
constants S_IWRITE and S_IREAD, defined in SYS\STAT.H. When both constants
are given, they are joined with the bitwise-OR operator ( | ). The meaning
of the pmode argument is as follows:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
S_IWRITE                          Writing permitted

S_IREAD                           Reading permitted

S_IREAD |  S_IWRITE               Reading and writing permitted

If write permission is not given, the file is read-only. Under DOS and OS/2,
all files are readable; it is not possible to give write-only permission.
Thus the modes S_IWRITE and S_IREAD | S_IWRITE are equivalent.

The open function applies the current file-permission mask to pmode before
setting the permissions (see umask).

The filename argument used in the open function is affected by the DOS
APPEND command.

Note that under DOS versions 3.0 and later, a problem occurs when SHARE is
installed and a new file is opened with oflag set to O_CREAT | O_RDONLY or
O_CREAT | O _WRONLY and pmode set to S_IREAD. Under these conditions, the
operating system prematurely closes the file during system calls made within
open. This problem does not occur under OS/2.

To work around the problem, open the file with the pmode argument set to
S_IWRITE. Then close the file and use chmod to change the access mode back
to S_IREAD. Another work-around is to open the file with pmode set to
S_IREAD and oflag set to O_CREAT | O_RDWR.


Return Value

The open function returns a file handle for the opened file. A return value
of -1 indicates an error, and errno is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Given path name is a directory; or an
                                    attempt was made to open a read-only
                                    file for writing; or a sharing violation
                                    occurred (the file's sharing mode does
                                    not allow the specified operations).

EEXIST                            The O_CREAT and O_EXCL flags are
                                    specified, but the named file already
                                    exists.

EINVAL                            An invalid oflag or pmode argument was
                                    given.

EMFILE                            No more file handles available (too many
                                    open files).

ENOENT                            File or path name not found.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

access, chmod, close, creat, dup, dup2, fopen, sopen, umask


Example

    /* OPEN.C: This program uses open to open a file named OPEN.C for input
    * and a file named OPEN.OUT for output. The files are then closed.
    */

    #include <fcntl.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <io.h>
    #include <stdio.h>

    void main()
    {
        int fh1, fh2;

    fh1 = open( "OPEN.C", O_RDONLY );
        if( fh1 == -1 )
        perror( "open failed on input file" );
        else
        {
        printf( "open succeeded on input file\n" );
        close( fh1 );
        }

        fh2 = open( "OPEN.OUT", O_WRONLY | O_CREAT, S_IREAD | S_IWRITE );
        if( fh2 == -1 )
        perror( "open failed on output file" );
        else
        {
        printf( "open succeeded on output file\n" );
        close( fh2 );
        }
    }


Output



    open succeeded on input file
    open succeeded on output file





_outgtext
────────────────────────────────────────────────────────────────────────────


Description

Prints font-based text in graphics mode.

    #include <graph.h>

    void _far_outgtext( unsigned char_far *text );

text                              Text string to output


Remarks

The _outgtext function outputs on the screen the null-terminated string that
text points to. The text is output using the current font at the current
graphics position and in the current color.

No formatting is provided, in contrast to the standard console I/O library
routines such as printf.

After it outputs the text, _outgtext updates the current graphics position.


The _outgtext function operates only in graphics video modes (e.g.,
_MRES4COLOR). Because it is a graphics function, the color of text is set by
the _setcolor function, not by the _settextcolor function.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_moveto functions,  _setcolor,  _setfont


Example

    /* OUTGTXT.C illustrates font output using functions:
    *   _registerfonts        _setfont            _outgtext
    *   _unregisterfonts      _getfontinfo        _getgtextextent
    *   _setgtextvector
    */

    #include <conio.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <graph.h>

    #define NFONTS 6

    unsigned char *face[NFONTS] =
    {
        "Courier", "Helvetica", "Times Roman", "Modern", "Script", "Roman"
    };
    unsigned char *options[NFONTS] =
    {
        "courier", "helv", "tms rmn", "modern", "script", "roman"
    };

    void main()
    {
        unsigned char list[20];
        char fondir[_MAX_PATH];
        struct videoconfig vc;
        struct _fontinfo fi;
        short fontnum, x, y;

        /* Read header info from all .FON files in current or given directory.
*/
        if( _registerfonts( "*.FON" ) <= 0 )
        {
            _outtext( "Enter full path where .FON files are located: " );
            gets( fondir );
            strcat( fondir, "\\*.FON" );
            if( _registerfonts( fondir ) <= 0 )
            {
                _outtext( "Error: can't register fonts" );
                exit( 1 );
            }
        }

        /* Set highest available graphics mode and get configuration. */
        if( !_setvideomode( _MAXRESMODE ) )
            exit( 1 );
        _getvideoconfig( &vc );

        /* Display each font name centered on screen. */
        for( fontnum = 0; fontnum < NFONTS; fontnum++ )
        {
            /* Build options string. */
            strcat( strcat( strcpy( list, "t'" ), options[fontnum] ), "'");
            strcat( list, "h30w24b" );

            _clearscreen( _GCLEARSCREEN );
            if( _setfont( list ) >= 0 )
            {

    /* Use length of text and height of font to center text. */
                x = (vc.numxpixels / 2) - (_getgtextextent( face[fontnum] ) /
2);
                y = (vc.numypixels / 2) + (_getgtextextent( face[fontnum] ) /
2);
                if( _getfontinfo( &fi ) )
                {
                    _outtext( "Error: Can't get font information" );
                    break;
                }
                _moveto( x, y );
                if( vc.numcolors > 2 )
                    _setcolor( fontnum + 2 );

                /* Rotate and display text. */
                _setgtextvector( 1, 0 );
                _outgtext( face[fontnum] );
                _setgtextvector( 0, 1 );
                _outgtext( face[fontnum] );
                _setgtextvector( -1, 0 );
                _outgtext( face[fontnum] );
                _setgtextvector( 0, -1 );
                _outgtext( face[fontnum] );
            }
            else
            {
                _outtext( "Error: Can't set font: " );
                _outtext( list );
            }
            getch();
        }
        _unregisterfonts();
        _setvideomode( _DEFAULTMODE );
    }





_outmem
────────────────────────────────────────────────────────────────────────────


Description

Prints text of a specified length in graphics mode.

    #include <graph.h>

    void _far_outmem( unsigned char_far *text, short length );

text                              Text string to output

length                            Length of string to output


Remarks

The _outmem function outputs the string that text points to. The length
argument specifies the number of characters to output.

Unlike _outtext, the _outmem function prints all characters literally,
including ASCII 10, 13, and 0 as the equivalent graphics characters. No
formatting is provided. Text is printed using the current text color,
starting at the current text position.

To output text using special fonts, you must use the _outgtext function.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_outtext,  _settextcolor,  _settextposition,  _settextwindow


Example

    /* OUTMEM.C illustrates:
    *    _outmem
    */

    #include <stdio.h>
    #include <graph.h>

    void main()
    {
        int  i, len;
        char tmp[10];

    _clearscreen( _GCLEARSCREEN );
        for( i = 0; i < 256; i++ )
        {
            _settextposition( (i % 24) + 1, (i / 24) * 7 );
            len = sprintf( tmp, "%3d %c", i, i );
            _outmem( tmp, len );
        }
        _settextposition( 24, 1 );
    }





outp, outpw
────────────────────────────────────────────────────────────────────────────


Description

Outputs a byte (outp) or a word (outpw) at a port.

    #include <conio.h>    Required only for function declarations

    int outp( unsigned port, int databyte );

    unsigned outpw( unsigned port, unsigned dataword );

port                              Port number

databyte                          Output value

dataword                          Output value


Remarks

The outp and outpw functions write a byte and a word, respectively, to the
specified output port. The port argument can be any unsigned integer in the
range 0 - 65,535; byte  can be any integer in the range 0 - 255; and
dataword can be any value in the range 0 - 65,535.

Both outp and outpw are supported in OS/2. You must use a .DEF file to
declare the IOSEG segment the run-time library uses to perform input/output
on the port. In addition, the intrinsic (/Oi) versions of these functions do
not work unless you put the code in a segment that is marked with the IOPL
keyword in the .DEF file.

You cannot do IOPL from a regular code segment, so the run-time library has
declared a separate code segment called _IOSEG. In order to use inp, inpw,
outp, or outp in any of the protected mode run-time libraries (?LIBCP,
LLIBCDLL, LLIBCMT, or CDLLOBJS-based DLL), you must have a .DEF file with
this line in it:

    SEGMENTS _IOSEG CLASS 'IOSEG_CODE' IOPL


Return Value

The functions return the data output. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

inp, inpw


Example

    /* OUTP.C: This program uses inp and outp to make sound of variable tone
    * and duration.
    */

    #include <conio.h>
    #include <stdio.h>
    #include <time.h>

    void Beep( unsigned duration, unsigned frequency ); /* Prototypes */
    void Sleep( clock_t wait );

    void main ()
    {
        Beep( 698, 700 );
        Beep( 523, 500 );
    }

    /* Sounds the speaker for a time specified in microseconds by duration
    * at a pitch specified in hertz by frequency.
    */
    void Beep( unsigned frequency, unsigned duration )
    {
        int control;

        /* If frequency is 0, Beep doesn't try to make a sound. */
        if( frequency )
        {
            /* 75 is about the shortest reliable duration of a sound. */
            if( duration < 75 )
                duration = 75;

            /* Prepare timer by sending 10111100 to port 43. */
            outp( 0x43, 0xb6 );

            /* Divide input frequency by timer ticks per second and
            * write (byte by byte) to timer.
            */
            frequency = (unsigned)(1193180L / frequency);
            outp( 0x42, (char)frequency );
            outp( 0x42, (char)(frequency >> 8) );

            /* Save speaker control byte. */
            control = inp( 0x61 );

            /* Turn on the speaker (with bits 0 and 1). */
            outp( 0x61, control | 0x3 );
        }

        Sleep( (clock_t)duration );

        /* Turn speaker back on if necessary. */
        if( frequency )
            outp( 0x61, control );
    }

    /* Pauses for a specified number of microseconds. */
    void Sleep( clock_t wait )
    {
        clock_t goal;

        goal = wait + clock();
        while( goal > clock() )
            ;
    }





_outtext
────────────────────────────────────────────────────────────────────────────


Description

Prints text in graphics mode.

    #include <graph.h>

    void _far _outtext( unsigned char _far *text );

text                              Text string to output


Remarks

The _outtext function outputs the null-terminated string that text points
to. No formatting is provided, in contrast to the standard console I/O
library routines such as printf. This function will work in any screen mode.


Text output begins at the current text position.

To output text using special fonts, you must use the _outgtext function.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_outmem, _settextcolor, _settextposition, _settextwindow


Example

    /* OUTTXT.C: This example illustrates text output functions:
    *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
    *    _settextcolor   _setbkcolor   _settextposition
    */

    #include <conio.h>
    #include <stdio.h>
    #include <graph.h>

    char buffer [80];

    void main()
    {

        /* Save original foreground, background, and text position */
        short blink, fgd, oldfgd;
        long  bgd, oldbgd;
        struct rccoord oldpos;

    /* Save original foreground, background, and text position. */
        oldfgd = _gettextcolor();
        oldbgd = _getbkcolor();
        oldpos = _gettextposition();
        _clearscreen( _GCLEARSCREEN );

        /* First time no blink, second time blinking. */
        for( blink = 0; blink <= 16; blink += 16 )
        {
        /* Loop through 8 background colors. */
        for( bgd = 0; bgd < 8; bgd++ )
        {
            _setbkcolor( bgd );
            _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
            _settextcolor( 7 );
            sprintf(buffer, "Back: %d Fore:", bgd );
            _outtext( buffer );

            /* Loop through 16 foreground colors. */
            for( fgd = 0; fgd < 16; fgd++ )
            {
                _settextcolor( fgd + blink );
                sprintf( buffer, " %2d ", fgd + blink );
                _outtext( buffer );
            }
        }
        }
        getch();

        /* Restore original foreground, background, and text position. */
        _settextcolor( oldfgd );
        _setbkcolor( oldbgd );
        _clearscreen( _GCLEARSCREEN );
        _settextposition( oldpos.row, oldpos.col );
    }





_pclose
────────────────────────────────────────────────────────────────────────────


Description

Waits for a child command and closes the stream on the associated pipe.

#include <stdio.h>                Function declaration

    int _pclose( FILE *stream );

stream                            File stream returned by previous call to
                                    _popen


Remarks

The _pclose function waits for a child command and closes the stream on the
associated pipe. The argument stream is the return value from a previous
call to _popen. The _pclose function looks up the process ID of the child
command started by the associated _popen call, closes the stream, executes a
cwait call on the child command, and returns the exit status of the child
command. See _pipe for a general discussion of pipes in OS/2.


Return Value

The _pclose function returns the exit status of the child command. The
format of the return value is the same as that for cwait, with the exception
that the low-order and high-order bytes are swapped. If an error occurs, -1
is returned.


Compatibility

▼ ANSI  ▼ DOS   OS/2   UNIX   XENIXA similar function (pclose) is
available in the XENIX and UNIX operating environments.



See Also

cwait,  _pipe,  _popen


Example

See the example for _popen.





perror
────────────────────────────────────────────────────────────────────────────


Description

Prints an error message.

#include <stdio.h>                Required only for function declarations

    void perror( const char *string );

string                            String message to print


Remarks

The perror function prints an error message to stderr. The string argument
is printed first, followed by a colon, then by the system error message for
the last library call that produced the error, and finally by a newline
character. If string is a null pointer or a pointer to a null string, perror
prints only the system error message.

The actual error number is stored in the variable errno (defined in
ERRNO.H). The system error messages are accessed through the variable
sys_errlist, which is an array of messages ordered by error number. The
perror function prints the appropriate error message by using the errno
value as an index to sys_errlist. The value of the variable sys_nerr is
defined as the maximum number of elements in the sys_errlist array.

To produce accurate results, perror should be called immediately after a
library routine returns with an error. Otherwise, the errno value may be
overwritten by subsequent calls.

Under DOS and OS/2, some of the errno values listed in ERRNO.H are not used.
These additional errno values are reserved for UNIX and XENIX use. See
Section 3.3, "_doserrno, errno, sys_errlist, sys_nerr," for a list of errno
values used on DOS and OS/2 and the corresponding error messages. The perror
function prints an empty string for any errno value not used under the
operating system.


Return Value

None.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

clearerr, ferror, strerror


Example

    /* PERROR.C: This program attempts to open a file named NOSUCHF.ILE.
    * Since this file probably doesn't exist, an error message is displayed.
    * The same message is created using perror, strerror, and _strerror.
    */

    #include <fcntl.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <io.h>
    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    void main()
    {
        int  fh;

        if( (fh = open( "NOSUCHF.ILE", O_RDONLY )) == -1 )
        {
        /* Three ways to create error message: */
        perror( "perror says open failed" );
        printf( "strerror says open failed: %s\n", strerror( errno ) );
        printf( _strerror( "_strerror says open failed" ) );
        }
        else
        {
        printf( "open succeeded on input file\n" );
        close( fh );
        }
    }


Output



    perror says open failed: No such file or directory
    strerror says open failed: No such file or directory
    _strerror says open failed: No such file or directory







_pg_analyzechart Functions
────────────────────────────────────────────────────────────────────────────


Description

Analyze a series of data.

    #include <pgchart.h>

    short _far _pg_analyzechart( chartenv _far *env, char _far * _far
    *categories,
    float _far *values, short n );

    short _far _pg_analyzechartms( chartenv _far *env, char _far * _far
    *categories,
    float _far *values, short nseries, short n, short arraydim,
    char _far * _far *serieslabels );

env                               Chart environment variable

categories                        Array of category variables

values                            Array of data values

nseries                           Number of series to chart

n                                 Number of data values to chart

arraydim                          Row dimension of data array

serieslabels                      Array of labels for series


Remarks

The _pg_analyzechart routines analyze a single or multiple series of data
without actually displaying the presentation-graphic image.

The _pg_analyzechart function fills the chart environment with default
values for a single-series bar, column, or line chart, depending on the type
specified by the call to the _pg_defaultchart function. The variables
calculated by _pg_analyzechart reflect the data given in the arguments
categories and values. All arguments are the same as those used with the
_pg_chart function.

The _pg_analyzechartms function fills the chart environment with default
values for a multiseries bar, column, or line chart, depending on which type
is specified in the _pg_defaultchart function. The variables calculated by
_pg_analyzechartms reflect the data given in the arguments categories and
values. All arguments are the same as those used with the _pg_chartms
function.

Boolean flags in the chart environment, such as AUTOSCALE and LEGEND, should
be set to TRUE before calling either _pg_analyzechart function. This will
ensure that the function will calculate all defaults.

For a discussion of the chart environment and related topics, see Section
2.6.2, "Presentation-Graphics Functions."


Return Value

The _pg_analyzechart and _pg_analyzechartms functions return 0 if there were
no errors. A nonzero value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_chart functions,  _pg_defaultchart,  _pg_initchart


Example

    /* PGACHART.C: This example illustrates presentation-graphics
    * analyze functions.
    * The example uses
    *      _pg_analyzechartms
    * The same principles apply for
    *      _pg_analyzepie        _pg_analyzechart
    *      _pg_analyzescatter    _pg_analyzescatterms
    */

    #include <conio.h>
    #include <string.h>
    #include <stdlib.h>
    #include <graph.h>
    #include <pgchart.h>

    #define FALSE  0
    #define TRUE   1

    /* Note data declared as a single-dimension array. The multiseries
    * chart functions expect only one dimension. See _pg_chartms
    * example for alternate method using multidimension array.
    */
    #define TEAMS  4
    #define MONTHS 3
    float _far values[TEAMS * MONTHS] = { .435,   .522,   .671,
                                        .533,   .431,   .590,
                                        .723,   .624,   .488,
                                        .329,   .226,   .401   };
    char _far *months[MONTHS] =         { "May",  "June", "July" };
    char _far *teams[TEAMS] = { "Reds", "Sox", "Cubs", "Mets" };

    void main()
    {
        chartenv env;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _pg_initchart();                    /* Initialize chart system.   */
        /* Default multiseries bar chart */
        _pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS );
        strcpy( env.maintitle.title, "Little League Records - Default" );
        _pg_chartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams );
        getch();
        _clearscreen( _GCLEARSCREEN );

        /* Analyze multiseries bar chart with autoscale. This sets all
        * default scale values. We want y axis values to be automatic.
        */
        _pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS );
        strcpy( env.maintitle.title, "Little League Records - Customized" );
        env.xaxis.autoscale = TRUE;
        _pg_analyzechartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams
);

        /* Now customize some of the x axis values. Then draw the chart.  */
        env.xaxis.autoscale = FALSE;
        env.xaxis.scalemax = 1.0;           /* Make scale show 0.0 to 1.0.   */
        env.xaxis.ticinterval = 0.2;        /* Don't make scale too crowded. */
        env.xaxis.ticdecimals = 3;          /* Show three decimals.          */
        strcpy( env.xaxis.scaletitle.title, "Win/Loss Percentage" );
        _pg_chartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams );
        getch();

        _setvideomode( _DEFAULTMODE );
    }





_pg_analyzepie
────────────────────────────────────────────────────────────────────────────


Description

Analyzes a single series of data for a pie chart.

    #include <pgchart.h>

    short _far _pg_analyzepie( chartenv _far *env, char _far * _far
    *categories,
    float _far *values, short _far *explode, short n );

env                               Chart environment variable

categories                        Array of category variables

values                            Array of data values

explode                           Array of explode flags

n                                 Number of data values to chart


Remarks

The _pg_analyzepie function analyzes a single series of data without
actually displaying the graphic image.

The _pg_analyzepie function fills the chart environment for a pie chart
using the data contained in the array values. All arguments are the same as
those used in the _pg_chartpie function.

For a discussion of the chart environment and related topics, see Section
2.6.2, "Presentation-Graphics Functions."


Return Value

The _pg_analyzepie function returns 0 if there were no errors. A nonzero
value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_chartpie,  _pg_defaultchart,  _pg_initchart


Example

See the example for _pg_analyzechart.





_pg_analyzescatter Functions
────────────────────────────────────────────────────────────────────────────


Description

Analyze a series of data for a scatter chart.

    #include <pgchart.h>

    short _far _pg_analyzescatter( chartenv _far *env, float _far *xvalues,
    float _far *yvalues, short n );

    short _far _pg_analyzescatterms( chartenv _far *env, float _far *xvalues,
    float _far *yvalues, short nseries, short n, short rowdim,
    char _far * _far *serieslabels );

env                               Chart environment structure

xvalues                           Array of x-axis data values

yvalues                           Array of y-axis data values

n                                 Number of data values to chart

nseries                           Number of series to chart

rowdim                            Row dimension of data array

serieslabels                      Array of labels for series


Remarks

The _pg_analyzescatter set of routines analyzes a single or multiple series
of data without actually displaying the graphic image.

The _pg_analyzescatter function fills the chart environment for a
single-series scatter diagram. The variables calculated by this function
reflect the data given in the arguments xvalues and yvalues. All arguments
are the same as those used in the _pg_chartscatter function.

The _pg_analyzescatterms function fills the chart environment for a
multiseries scatter diagram. The variables calculated by
_pg_analyzescatterms reflect the data given in the arguments xvalues and
yvalues. All arguments are the same as those used in the function
_pg_chartscatterms.

Boolean flags in the chart environment, such as AUTOSCALE and LEGEND, should
be set to TRUE before calling _pg_analyzescatterms; this ensures that the
function will calculate all defaults.

For a discussion of the chart environment and related topics, see Section
2.6.2, "Presentation-Graphics Functions."


Return Value

The _pg_analyzescatter and _pg_analyzescatterms functions return 0 if there
were no errors. A nonzero value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_chartscatter functions,  _pg_defaultchart,  _pg_initchart


Example

See the example for _pg_analyzechart.





_pg_chart Functions
────────────────────────────────────────────────────────────────────────────


Description

Display single-series or multiseries charts.

    #include <pgchart.h>

    short _far _pg_chart( chartenv _far *env, char _far * _far *categories,
    float _far *values, short n );

    short _far _pg_chartms( chartenv _far *env, char _far * _far *categories,
    float _far *values, short nseries, short n, short arraydim,
    char _far * _far *serieslabels );

env                               Chart environment variable

categories                        Array of category variables

values                            Array of data values

n                                 Number of data values to chart

nseries                           Number of series to chart

arraydim                          Row dimension of data array

serieslabels                      Array of labels for series


Remarks

The _pg_chart function displays a single-series bar, column, or line chart,
depending on the type specified in the chart environment variable (env).

The _pg_chartms function displays a multiseries bar, column, or line chart,
depending on the type specified in the chart environment. All the series
must contain the same number of data points, specified by the argument n.

The array values is a two-dimensional array containing all value data for
every series to be plotted on the chart. Each column of values represents a
single series. The parameter rowdim is the integer value used to dimension
rows in the array declaration for values.

For example, the following code fragment declares the identifier  values  to
be a twodimensional floating-point array with 20 rows and 10 columns:

    #define ARRAYDIM 20
    float values [ARRAYDIM][10];
    short rowdim = ARRAYDIM;

Note that the number of columns in the values array cannot exceed 10, the
maximum number of data series on a single chart. Note also that  rowdim
must be greater than or equal to the argument n, and the column dimension in
the array declaration must be greater than or equal to the argument nseries.
If n and nseries are set to values less than the full dimensional size of
the values array, only part of the data contained in values will be plotted.


The array serieslabels holds the labels used in the chart legend to identify
each series.

For a discussion of the chart environment and related topics, see Section
2.6.2, "Presentation-Graphics Functions."


Return Value

The _pg_chart and _pg_chartms functions return 0 if there were no errors. A
nonzero value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_analyzechart functions,  _pg_defaultchart,  _pg_initchart


Example

    /* PGCHART.C: This example illustrates presentation-graphics support
    * routines and single-series chart routines, including
    *    _pg_initchart   _pg_defaultchart   _pg_chart   _pg_chartpie
    */

    #include <conio.h>
    #include <graph.h>
    #include <string.h>
    #include <stdlib.h>
    #include <pgchart.h>

    #define COUNTRIES 5
    float _far value[COUNTRIES] =    { 42.5,    14.3,    35.2,   21.3,   32.6
};
    char _far *category[COUNTRIES] = { "USSR",  "France","USA",  "UK",
"Other" };
    short _far explode[COUNTRIES] =  { 0,       1,        0,      1,     0
};

    void main()
    {
        chartenv env;
        short mode = _VRES16COLOR;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _pg_initchart();                    /* Initialize chart system. */

        /* Single-series bar chart */
        _pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS );
        strcpy( env.maintitle.title, "Widget Production" );
        _pg_chart( &env, category, value, COUNTRIES );
        getch();
        _clearscreen( _GCLEARSCREEN );

        /* Single-series column chart */
        _pg_defaultchart( &env, _PG_COLUMNCHART, _PG_PLAINBARS );
        strcpy( env.maintitle.title, "Widget Production" );
        _pg_chart( &env, category, value, COUNTRIES );
        getch();
        _clearscreen( _GCLEARSCREEN );

        /* Pie chart */
        _pg_defaultchart( &env, _PG_PIECHART, _PG_PERCENT );
        strcpy( env.maintitle.title, "Widget Production" );
        _pg_chartpie( &env, category, value, explode, COUNTRIES );
        getch();

        _setvideomode( _DEFAULTMODE );
    }





_pg_chartscatter Functions
────────────────────────────────────────────────────────────────────────────


Description

Display scatter charts.

    #include <pgchart.h>

    short _far _pg_chartscatter( chartenv _far *env, float _far *xvalues,
    float _far *yvalues, short n );

    short _far _pg_chartscatterms( chartenv _far *env, float _far *xvalues,
    float _far *yvalues, short nseries, short n, short rowdim,
    char _far * _far *serieslabels );

env                               Chart environment structure

xvalues                           Array of x-axis data values

yvalues                           Array of y-axis data values

n                                 Number of data values to chart

nseries                           Number of series to chart

rowdim                            Row dimension of data array

serieslabels                      Array of labels for series


Remarks

The _pg_chartscatter function displays a scatter diagram for a single series
of data.

The _pg_chartscatterms function displays a scatter diagram for more than one
series of data.

The arguments xvalues and yvalues are two-dimensional arrays containing data
for the x axis and y axis, respectively. Columns for each array hold data
for individual series; thus the first columns of xvalues and yvalues contain
plot data for the first series, the second columns contain plot data for the
second series, and so forth.

The n, rowdim, nseries, and serieslabels arguments fulfill the same purposes
as those used in the _pg_chartms function. See _pg_chartms for an
explanation of these arguments.

For a discussion of the chart environment and related topics, see Section
2.6.2, "Presentation-Graphics Functions."


Return Value

The _pg_chartscatter and _pg_chartscatterms functions return 0 if there were
no errors. A nonzero value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

    _pg_analyzescatter functions,  _pg_defaultchart,  _pg_initchart


Example

See the example for _pg_chart.





_pg_chartpie
────────────────────────────────────────────────────────────────────────────


Description

Displays a pie chart.

    #include <pgchart.h>

    short _far _pg_chartpie( chartenv _far *env, char _far * _far *categories,

    float _far *values, short _far *explode, short n );

env                               Chart environment structure

categories                        Array of category labels

values                            Array of data values

explode                           Array of explode flags

n                                 Number of data values to chart


Remarks

The _pg_chartpie function displays a pie chart for the data contained in the
array values. Pie charts are formed from a single series of data─there is no
multiseries version of pie charts as there is for other chart types.

The array explode must be dimensioned so that its length is greater than or
equal to the  argument n. All entries in explode are either 0 or 1. If an
entry is 1, the corresponding pie slice is displayed slightly removed from
the rest of the pie.

For example, if the explode array is initialized as

    short explode[5] = {0, 1, 0, 0, 0};

the pie slice corresponding to the second entry of the categories array will
be displayed "exploded" from the other four slices.

For a discussion of the chart environment and related topics, see Section
2.6.2, "Presentation-Graphics Functions."


Return Value

The _pg_chartpie function returns 0 if there were no errors. A nonzero value
indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

    _pg_analyzepie,  _pg_defaultchart,  _pg_initchart


Example

See the example for _pg_chart.





_pg_defaultchart
────────────────────────────────────────────────────────────────────────────


Description

Initializes the chart environment.

    #include <pgchart.h>

    short _far _pg_defaultchart( chartenv _far *env, short charttype, short
    chartstyle );

env                               Chart environment structure

charttype                         Chart type

chartstyle                        Chart style


Remarks

The _pg_defaultchart function initializes all necessary variables in the
chart environment for the chart type by the variable charttype.

All title fields in the environment structure are blanked. Titles should be
set in the proper fields after calling _pg_defaultchart.

The charttype variable can be set to one of the following manifest
constants:

Chart Type                        Description
────────────────────────────────────────────────────────────────────────────
_PG_BARCHART                      Bar chart

_PG_COLUMNCHART                   Column chart

_PG_LINECHART                     Line chart

_PG_PIECHART                      Pie chart

_PG_SCATTERCHART                  Scatter chart

The chartstyle variable specifies the style of the chart with either the
number "1" or the number "2." Each of the five types of
presentation-graphics charts can appear in two different chart styles, as
described below:

╓┌───────────┌───────────────────┌───────────────────────────────────────────╖
Chart Type  Chart Style 1       Chart Style  2
────────────────────────────────────────────────────────────────────────────
Bar         Side by side        Stacked

Column      Side by side        Stacked

Line        Points with lines   Points only

Pie         Percent             No percent

Chart Type  Chart Style 1       Chart Style  2
────────────────────────────────────────────────────────────────────────────

Scatter     Points with lines   Points only



In a pie chart, the pieces are "exploded" according to the explode array
argument in the _pg_chartpie function. In the "percent" format, percentages
are printed next to each slice. Bar and column charts have only one style
when displaying a single series of data. The styles "side by side" and
"stacked" are applicable only when more than one series appear on the same
chart. The first style arranges the bars or columns for the different series
side by side, showing relative heights or lengths. The stacked style
emphasizes relative sizes between bars and columns.


Return Value

The _pg_defaultchart function returns 0 if there were no errors. A nonzero
value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_getchardef,  _pg_getpalette,  _pg_getstyleset,  _pg_hlabelchart,
_pg_initchart,  _pg_resetpalette,  _pg_resetstyleset,  _pg_setchardef,
_pg_setpalette,  _pg_setstyleset, _pg_vlabelchart


Example

See the example for _pg_chart.





_pg_getchardef
────────────────────────────────────────────────────────────────────────────


Description

Gets the pixel bit map for the specified character.

    #include <pgchart.h>

    short _far _pg_getchardef( short charnum, unsigned char _far *chardef  );

charnum                           ASCII number of character

chardef                           Pointer to 8-by-8 bit map array


Remarks

The _pg_getchardef function retrieves the current 8-by-8 pixel bit map for
the character having the ASCII number charnum. The bit map is stored in the
chardef array.


Return Value

The _pg_getchardef function returns 0 if there were no errors. A nonzero
value indicates an error.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_initchart,  _pg_setchardef





_pg_getpalette
────────────────────────────────────────────────────────────────────────────


Description

Gets palette colors, line styles, and patterns.

    #include <pgchart.h>

    short _far _pg_getpalette( paletteentry _far *palette );

palette                           Pointer to first palette structure in
                                    array


Remarks

The _pg_getpalette function retrieves palette colors, line styles, fill
patterns, and plot characters for all palettes. The pointer palette points
to an array of palette structures that will contain the desired palette
values.

The palette used by the presentation-graphics routines is independent of the
palette used by the low-level graphics routines.


Return Value

The function _pg_getpalette returns 0 if there were no errors, and it
returns the value _BADSCREENMODE if current palettes have not been
initialized by a previous call to _pg_setpalette.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_initchart,  _pg_resetpalette,  _pg_setpalette


Example

    /* PGGPAL.C: This example illustrates presentation-graphics palettes
    * and the routines that modify them, including
    *    _pg_getpalette    _pg_resetpalette    _pg_setstyleset
    *    _pg_getstyleset   _pg_resetstyleset   _pg_vlabelchart
    *    _pg_hlabelchart   _pg_setpalette
    */
    #include <conio.h>
    #include <string.h>
    #include <stdlib.h>
    #include <graph.h>
    #include <pgchart.h>

    #define TEAMS  2
    #define MONTHS 3
    float _far values[TEAMS][MONTHS] = { { .435,   .522,   .671  },
                                        { .533,   .431,   .401  } };
    char _far *months[MONTHS] =          { "May", "June", "July" };
    char _far *teams[TEAMS] = { "Cubs", "Reds" };

    fillmap fill1 = { 0x99, 0x33, 0x66, 0xcc, 0x99, 0x33, 0x66, 0xcc };
    fillmap fill2 = { 0x99, 0xcc, 0x66, 0x33, 0x99, 0xcc, 0x66, 0x33 };
    styleset styles;
    palettetype pal;

    void main()
    {
        chartenv env;
        short mode = _VRES16COLOR;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _pg_initchart();                         /* Initialize chart system.
        */

        /* Modify global set of line styles used for borders, grids, and
        * data connectors. Note that this change is used before
        * _pg_defaultchart, which will use the style set.
        */
        _pg_getstyleset( styles );               /* Get styles and modify
        */
        styles[1] = 0x5555;                      /*   style 1 (used for
        */
        _pg_setstyleset( styles );               /*   borders)─then set new.
        */

        _pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS );

        /* Modify palette for data lines, colors, fill patterns, and
        * characters. Note that the line styles are set in the palette, not
        * in the style set, so that only data connectors will be affected.
        */
        _pg_getpalette( pal );                   /* Get default palette.
        */
        pal[1].plotchar = 16;                    /* Set to ASCII 16 and 17.
        */
        pal[2].plotchar = 17;
        memcpy( pal[1].fill, fill1, 8 );         /* Copy fill masks to
        palette.*/
        memcpy( pal[2].fill, fill2, 8 );
        pal[1].color = 3;                        /* Change palette colors.
        */
        pal[2].color = 4;
        pal[1].style = 0xfcfc;                   /* Change palette line
        styles.*/
        pal[2].style = 0x0303;
        _pg_setpalette( pal );                   /* Put modified palette.
        */

    /* Multiseries bar chart */
        strcpy( env.maintitle.title, "Little League Records - Customized" );
        _pg_chartms( &env, months, (float _far *)values,
                TEAMS, MONTHS, MONTHS, teams );
        getch();
        _clearscreen( _GCLEARSCREEN );

        /* Multiseries line chart */
        _pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE );
        strcpy( env.maintitle.title, "Little League Records - Customized" );
        _pg_chartms( &env, months, (float _far *)values,
                    TEAMS, MONTHS, MONTHS, teams );

        /* Print labels. */
        _pg_hlabelchart( &env, (short)(env.chartwindow.x2 * .75),
                            (short)(env.chartwindow.y2 * .10),
                            12, "Up and up!" );
        _pg_vlabelchart( &env, (short)(env.chartwindow.x2 * .75),
                            (short)(env.chartwindow.y2 * .45),
                            13, "Sliding down!" );
        getch();
        _clearscreen( _GCLEARSCREEN );

        _pg_resetpalette();                     /* Restore default palette
*/
        _pg_resetstyleset();                    /*   and style set.
*/

        /* Multiseries bar chart */
        _pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS );
        strcpy( env.maintitle.title, "Little League Records - Default" );
        _pg_chartms( &env, months, (float _far *)values,
                    TEAMS, MONTHS, MONTHS, teams );
        getch();
        _clearscreen( _GCLEARSCREEN );

        /* Multiseries line chart */
        _pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE );
        strcpy( env.maintitle.title, "Little League Records - Default" );
        _pg_chartms( &env, months, (float _far *)values,
                    TEAMS, MONTHS, MONTHS, teams );
        getch();

        _setvideomode( _DEFAULTMODE );
    }





_pg_getstyleset
────────────────────────────────────────────────────────────────────────────


Description

Gets the current styleset.

    #include <pgchart.h>

    void _far _pg_getstyleset( unsigned short _far *styleset );

styleset                          Pointer to current styleset


Remarks

The _pg_getstyleset function retrieves the contents of the current styleset.



Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_initchart,  _pg_resetstyleset,  _pg_setstyleset


Example

See the example for _pg_getpalette.





_pg_hlabelchart
────────────────────────────────────────────────────────────────────────────


Description

Writes text horizontally on the screen.

    #include <pgchart.h>

    short _far _pg_hlabelchart( chartenv _far *env, short x, short y, short
    color,
    char _far *label );

env                               Chart environment structure

x                                 x-coordinate for text

y                                 Pixel y-coordinate for text

color                             Color code for text

label                             Label text


Remarks

The _pg_hlabelchart function writes text horizontally on the screen. The
arguments x and y are pixel coordinates for the beginning location of text
relative to the upper-left corner of the chart window.


Return Value

The _pg_hlabelchart functions return 0 if there were no errors. A nonzero
value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_initchart,  _pg_vlabelchart


Example

See the example for _pg_getpalette.





_pg_initchart
────────────────────────────────────────────────────────────────────────────


Description

Initializes presentation graphics.

    #include <pgchart.h>

    short _far _pg_initchart( void );


Remarks

The _pg_initchart function initializes the presentation-graphics package. It
initializes the color and style pools, resets the chartline styleset, builds
default palette modes, and reads the presentation-graphics font definition
from the disk. This function is required in all programs that use
presentation graphics. The _pg_initchart function must be called before any
of the other functions in the presentation-graphics library.

The _pg_initchart function assumes a valid graphics mode has been
established. Therefore, it must be called only after a successful call to
the library function _setvideomode.


Return Value

The _pg_initchart functions return 0 if there were no errors. A nonzero
value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_getchardef,  _pg_getpalette,  _pg_getstyleset,
_pg_hlabelchart,  _pg_resetpalette,  _resetstyleset,  _pg_setchardef,
_pg_setpalette,  _pg_setstyleset,  _pg_vlabelchart,  _setvideomode


Example

See the example for _pg_chart.





_pg_resetpalette
────────────────────────────────────────────────────────────────────────────


Description

Resets palette colors, line styles, and patterns to default values.

    #include <pgchart.h>

    short _far _pg_resetpalette( void );


Remarks

The _pg_resetpalette function sets the palette colors, line styles, fill
patterns, and plot characters for the palette to the default for the current
screen mode.

The palette used by the presentation-graphics routines is independent of the
palette used by the low-level graphics routines.


Return Value

The _pg_resetpalette function returns 0 if there were no errors. If the
screen mode is not valid, the value _BADSCREENMODE is returned.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_getpalette,   _pg_initchart,  _pg_setpalette


Example

See the example for _pg_getpalette.





_pg_resetstyleset
────────────────────────────────────────────────────────────────────────────


Description

Resets styleset to default values.

    #include <pgchart.h>

    void _far _pg_resetstyleset( void );


Remarks

The _pg_resetstyleset function reinitializes the styleset to the default
values for the current screen mode.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_getstyleset,  _pg_initchart,  _pg_setstyleset


Example

See the example for _pg_getpalette.





_pg_setchardef
────────────────────────────────────────────────────────────────────────────


Description

Sets the pixel bit map for the specified character.

    #include <pgchart.h>

    short _far _pg_setchardef( short charnum, unsigned char _far *chardef  );

charnum                           ASCII number of character

chardef                           Pointer to an 8-by-8 bit map array for
                                    the character


Remarks

The _pg_setchardef function sets the 8-by-8 pixel bit map for the character
with the ASCII number charnum. The bit map is stored in the chardef array.


Return Value

The _pg_setchardef function returns 0 if there was no error. A nonzero value
indicates an error.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_getchardef,  _pg_initchart





_pg_setpalette
────────────────────────────────────────────────────────────────────────────


Description

Sets palette colors, line styles, and patterns.

    #include <pgchart.h>

    short _far _pg_setpalette( paletteentry _far *palette );

palette                           Pointer to first palette structure in
                                    array


Remarks

The _pg_setpalette function sets palette colors, line styles, fill patterns,
and plot characters for all palettes. The pointer palette points to an array
of palette structures that contain the desired palette values.

The palette used by the presentation-graphics routines is independent of the
palette used by the low-level graphics routines.


Return Value

The _pg_setpalette function returns 0 if there were no errors. If the new
palettes are not valid, the value _BADSCREENMODE is returned.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_getpalette,  _pg_initchart,  _pg_resetpalette


Example

See the example for _pg_getpalette.





_pg_setstyleset
────────────────────────────────────────────────────────────────────────────


Description

Sets the current styleset.

    #include <pgchart.h>

    void _far _pg_setstyleset( unsigned short _far *styleset );

styleset                          Pointer to new styleset


Remarks

The _pg_setstyleset function sets the current styleset.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_getstyleset,  _pg_initchart,  _pg_resetstyleset


Example

See the example for _pg_getpalette.





_pg_vlabelchart
────────────────────────────────────────────────────────────────────────────


Description

Writes text vertically on the screen.

    #include <pgchart.h>

    short _far _pg_vlabelchart( chartenv _far *env, short x, short y, short
    color,
    char _far *label );

env                               Chart environment structure

x                                 Pixel x coordinate for text

y                                 Pixel y coordinate for text

color                             Color code for text

label                             Label text




Remarks

The _pg_vlabelchart function writes text vertically on the screen. The
arguments x and y are pixel coordinates for the beginning location of text
relative to the upper-left corner of the chart window.


Return Value

The _pg_vlabelchart function returns 0 if there were no errors. A nonzero
value indicates a failure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_pg_defaultchart,  _pg_hlabelchart,  _pg_initchart


Example

See the example for _pg_getpalette.





_pie Functions
────────────────────────────────────────────────────────────────────────────


Description

Draw wedge-shaped figures.

    #include <graph.h>

    short _far _pie( short control, short x1, short y1, short x2, short y2,
    short x3, short y3, short x4, short y4 );

    short _far _pie_w( short control, double x1, double y1, double x2, double
    y2,
    double x3, double y3, double x4, double y4 );

    short _far _pie_wxy( short control, struct _wxycoord _far *pwxy1,
    struct _wxycoord _far *pwxy2, struct _wxycoord _far *pwxy3,
    struct _wxycoord _far*pwxy4 );

control                           Fill-control constant

x1, y1                            Upper-left corner of bounding rectangle

x2, y2                            Lower-right corner of bounding rectangle

x3, y3                            Start vector

x4, y4                            End vector

pwxy1                             Upper-left corner of bounding rectangle

pwxy2                             Lower-right corner of bounding rectangle

pwxy3                             Start vector

pwxy4                             End vector


Remarks

The _pie functions draw a pie-shaped wedge by drawing an elliptical arc
whose center and two endpoints are joined by lines.

The _pie function uses the view coordinate system. The center of the arc is
the center of the bounding rectangle specified by the view coordinate points
(x1, y1) and (x2, y2). The arc starts where it intersects the vector defined
by (x3, y3) and ends where it intersects the vector (x4, y4).

The _pie_wxy and _pie_w functions use the window coordinate system. The
center of the arc is the center of the bounding rectangle specified by the
window coordinate pairs pwxy1 and pwxy2 for _pie_wxy, and by the points (x1,
y1) and (x2, y2) for _pie_w. The arc starts where it intersects the vector
defined by pwxy3 or (x3, y3) and ends where it intersects the vector defined
by pwxy4 or (x4, y4).

The _wxycoord structure is defined in GRAPH.H and contains the following
elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
double wx                         Window x coordinate

double wy                         Window y coordinate

The wedge is drawn using the current color moving in a counterclockwise
direction. The control parameter can be one of the following manifest
constants:

Constant                          Action
────────────────────────────────────────────────────────────────────────────
_GFILLINTERIOR                    Fills the figure using the current color
                                    and fill mask

_GBORDER                          Does not fill the figure

The control option given by _GFILLINTERIOR is equivalent to a subsequent
call to the _floodfill function using the approximate center of the arc as
the starting point and the current color (set by _setcolor) as the boundary
color.


Return Value

These functions return a nonzero value if successful; otherwise, they return
0.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_arc functions,  _ellipse functions,  _floodfill,  _getcolor,  _lineto
functions, _rectangle functions,  _setcolor,  _setfillmask


Example

    /* PIE.C: This program draws a pie-shaped figure. */

    #include <stdlib.h>
    #include <conio.h>
    #include <graph.h>

    void main()
    {
        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _pie( _GBORDER, 80, 50, 240, 150, 240, 12, 0, 150 );
        getch();

        _setvideomode( _DEFAULTMODE );
    }





_pipe
────────────────────────────────────────────────────────────────────────────


Description

Creates a pipe for reading and writing.

#include <fcntl.h>                For O_BINARY and O_TEXT definitions

#include <errno.h>                errno definitions

#include <io.h>                   Prototype declaration

    int _pipe( int *phandles, unsigned int psize, int textmode );

phandles[2]                       Array to hold read and write handles

psize                             Amount of memory to reserve

textmode                          File mode


Remarks

A pipe is an artificial file-like I/O channel that a program can create and
use to pass information to other programs. A pipe is similar to a file in
that it has a file pointer or a file descriptor, or both, and can be read
from or written to using the input and output functions of the standard
library. Unlike a file, a pipe does not represent a specific file or device.
Instead, a pipe represents temporary storage in memory that is independent
of the program's own memory and is controlled entirely by the operating
system.

Pipes may be used to pass information between programs. For example, the
command processor in OS/2 creates a pipe when executing a command such as

    PROGRAM1 | PROGRAM2

The standard output handle of PROGRAM1 is attached to the pipe's write
handle. The standard input handle of PROGRAM2 is attached to the pipe's read
handle. This eliminates the need for creating temporary files to pass
information to other programs.

The _pipe function creates a pipe. This function is similar to open but
opens the pipe for both reading and writing, returning two file handles
instead of one. The program can either use both sides of the pipe or close
the one it does not need. This function typically opens a pipe in
preparation for linking it to a child process.

The _pipe function opens a pipe and returns two handles to the pipe in the
phandles argument. The element phandles[0] contains the read handle, and the
element phandles[1] contains the write handle. Pipe file handles are used in
the same way as other file handles. (The low-level input and output
functions read and write can read from and write to a pipe.)

The psize argument specifies the amount of memory, in bytes, to reserve for
the pipe.

The textmode argument specifies the translation mode for the pipe. The
manifest constant O_TEXT specifies a text translation, and the constant
O_BINARY specifies binary translation. (See fopen for a description of text
and binary modes.) If the textmode argument is 0, the _pipe function uses
the default translation mode specified by the default-mode variable _fmode.


In multithread programs, no locking is performed. The handles returned are
newly opened and should not be referenced by any thread until after the
_pipe call is complete.

Under OS/2, a pipe is destroyed when all its handles have been closed. (If
all read handles on the pipe have been closed, writing to the pipe will
cause an error.) All read and write operations on the pipe wait until there
is enough data or enough buffer space to complete the I/O request.


Return Value

The _pipe function returns 0 if successful. A return value of -1 indicates
an error, and errno is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EMFILE                            No more file handles available (too many
                                    open files)

ENFILE                            System file table overflow


Compatibility

▼ ANSI  ▼ DOS   OS/2   UNIX   XENIX


A similar function (pipe) is available in the XENIX and UNIX operating
environments.


See Also

cwait,  _pclose,  _popen


Example

    /* PIPE.C: This program uses _pipe to pass streams of text to
    * child processes.
    */

    #include <stdlib.h>
    #include <stdio.h>
    #include <io.h>
    #include <fcntl.h>
    #include <process.h>            /* _pipe */
    #include <math.h>

    enum PIPES { READ, WRITE };     /* Constants 0 and 1 for READ and WRITE */
    #define NUMPROBLEM 8

    void main( int argc, char *argv[] )
    {
        int     hpipe[2];
        char    hstr[20];
        int     termstat, pid, problem, c;

        /* If no arguments, this is the parent. */
        if( argc == 1 )
        {
            /* Open a sets of pipes. */
            if( _pipe( hpipe, 256, O_BINARY ) == -1 )
                exit( 1 );

            /* Convert pipe read handle to string and pass as argument to
            * spawned child. Program spawns itself (argv[0]).
            */
            itoa( hpipe[READ],  hstr,  10 );
            if( spawnl( P_NOWAIT, argv[0], argv[0], hstr, NULL )  == -1 )
                printf( "Spawn failed" );

            /* Put problem in write pipe. Since child is running
simultaneously,
            * first solutions may be done before last problem is given.
            */
            for( problem = 1000; problem <= NUMPROBLEM * 1000; problem += 1000
)
            {
                printf( "Son, what is the square root of %d?\n", problem );
                write( hpipe[WRITE], (char *)&problem, sizeof( int ) );
            }

            /* Wait until child is done processing. */
            wait( &termstat );
            if( termstat & 0xff )
                printf( "Child failed\n" );

            close( hpipe[READ] );
            close( hpipe[WRITE] );
        }

    /* If there is an argument, this must be the child. */
        else
        {
            /* Convert passed string handle to integer handle. */
            hpipe[READ] = atoi( argv[1] );

            /* Read problem from pipe and calculate solution. */
            for( c = 0; c < NUMPROBLEM; c++ )
            {
                read( hpipe[READ], (char *)&problem, sizeof( int ) );
                printf( "Dad, the square root of %d is %3.2f.\n",
                        problem, sqrt( (double)problem ) );;
            }
        }
    }


Output



    Son, what is the square root of 1000?
    Dad, the square root of 1000 is 31.62.
    Son, what is the square root of 2000?
    Son, what is the square root of 3000?
    Dad, the square root of 2000 is 44.72.
    Son, what is the square root of 4000?
    Dad, the square root of 3000 is 54.77.
    Son, what is the square root of 5000?
    Dad, the square root of 4000 is 63.25.
    Son, what is the square root of 6000?
    Dad, the square root of 5000 is 70.71.
    Son, what is the square root of 7000?
    Dad, the square root of 6000 is 77.46.
    Son, what is the square root of 8000?
    Dad, the square root of 7000 is 83.67.
    Dad, the square root of 8000 is 89.44.





_polygon Functions
────────────────────────────────────────────────────────────────────────────


Description

Draw polygon shapes.

    #include <graph.h>

    short _far _polygon( short control, struct xycoord _far *points, short
    numpoints );

    short _far _polygon_w( short control, double _far *points, short numpoints
    );

    short _far _polygon_wxy( short control, struct _wxycoord _far *points,
    short numpoints );

control                           Fill flag

points                            Pointer to an array of structures
                                    defining the polygon

numpoints                         Number of points


Remarks

The _polygon functions draw polygons. The border of the polygon is drawn in
the current color and line style. The _polygon routine uses the view
coordinate system (expressed in xycoord structures), and the _polygon_wxy
and _polygon_w routines use real-valued window coordinates (expressed in
_wxycoord structures and in pairs of double-precision floating-point values,
respectively).

The argument points is an array of xycoord or _wxycoord structures or pairs
of doubles, each of which specifies one of the polygon's vertices. (For
_polygon_w, points[0] and points[1] specify the x and y coordinates,
respectively, of the first point.) The argument numpoints indicates the
number of elements (the number of vertices) in the points array.

The control argument can be one of the following manifest constants:

Constant                          Action
────────────────────────────────────────────────────────────────────────────
_GFILLINTERIOR                    Fills the polygon using the current fill
                                    mask

_GBORDER                          Does not fill the polygon

The _setwritemode, _setlinestyle, and _setfillmask functions all affect the
output from the_polygon functions.


Return Value

The _polygon functions return a nonzero value if the arc is successfully
drawn; otherwise, they return 0.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_ellipse functions,  _floodfill,  _lineto functions,  _pie functions,
_rectangle functions,  _setcolor,  _setfillmask,  _setlinestyle,
_setwritemode


Example

    /* POLYGON.C: This program draws a star-shaped polygon. */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>
    #include <math.h>
    #include <stdlib.h>

    #define PI 3.1415

    void main()
    {
        short  side, radius = 90, x = 0, y = 0;
        double radians;
        struct xycoord polyside[5];
        struct videoconfig vc;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _getvideoconfig( &vc );
        _setvieworg( vc.numxpixels / 2, vc. numypixels / 2 );

        /* Calculate points of star every 144 degrees, then connect them. */
        for( side = 0; side < 5; side++ )
        {
            radians = 144 * PI / 180;
            polyside[side].xcoord = x + (short)(cos( side * radians ) *
radius);
            polyside[side].ycoord = y + (short)(sin( side * radians ) *
radius);
        }
        _polygon( _GFILLINTERIOR, polyside, 5 );

        getch();
        _setvideomode( _DEFAULTMODE );
    }





_popen
────────────────────────────────────────────────────────────────────────────


Description

Creates a pipe and executes a command.

#include <stdio.h>                Required for function declarations only

    FILE *_popen( char *command, char *mode );

command                           Command to be executed

mode                              Mode of returned stream


Remarks

The _popen function creates a pipe and asynchronously executes a child copy
of the command processor with the specified command string command. See
_pipe for a general discussion of pipes in OS/2. The character string mode
specifies the type of access requested, as follows:

Type                              Description
────────────────────────────────────────────────────────────────────────────
"r"                               The calling process can read the child
                                    command's standard output via the
                                    returned stream.

"w"                               The calling process can write to the
                                    child command's standard input via the
                                    returned stream.

"b"                               Open in binary mode.

"t"                               Open in text mode.

See Section 2.7, "Input and Output," for a discussion of text and binary
modes.


Return Value

The _popen function returns a stream associated with one end of the created
pipe. The other end of the pipe is associated with the child command's
standard input or standard output. If an error occurs, NULL is returned.


Compatibility

▼ ANSI  ▼ DOS   OS/2   UNIX   XENIX


A similar function (popen) is available in the XENIX and UNIX operating
environments.


See Also

_pclose,  _pipe


Example

    /* POPEN.C: This program uses _popen and _pclose to receive a stream
    * of text from a child system process.
    */
    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        char    buffer[128];
        FILE    *chkdsk;

        /* Run CHKDSK so that it writes its output to a pipe. Open pipe
        * with read text attribute so that we can read it like a text file.
        */
        if( (chkdsk = _popen( "dir po*.c | sort | more", "rt" )) == NULL )
        exit( 1 );

        /* Read pipe until end of file. End of file indicates that CHKDSK
        * closed its standard out (probably meaning it terminated).
        */
        while( !feof( chkdsk ) )
        {
        if( fgets( buffer, 128, chkdsk ) != NULL )
            printf( buffer );
        }

        /* Close pipe and print return value of CHKDSK. */
        printf( "\nChild returned %d\n", _pclose( chkdsk ) );
    }


Output



        3 File(s)   12683264 bytes free
    Directory of C:\LIBREF
    The volume label in drive C is OS2.
    POLYGON  C        921   6-14-89   6:51p
    POPEN    C        845   6-19-89   2:48p
    POW      C        190   6-13-89   6:07p

    Child returned 0





pow Functions
────────────────────────────────────────────────────────────────────────────


Description

Calculate x raised to the power of y.

    #include <math.h>

    double pow( double x, double y );

    long double powl( long double x, long double y );

x                                 Number to be raised

y                                 Power of x


Remarks

The pow and powl functions compute x raised to the power of y.

The powl function is the 80-bit counterpart, and it uses an 80-bit, 10-byte
coprocessor form of arguments and return values. See the reference page on
the long double functions for more details on this data type.


Return Value

The pow and powl functions return the value of xy. If x is not 0.0 and y is
0.0, pow and powl return the value 1. If x is 0.0 and y is negative, pow and
powl set errno to EDOM and return 0.0. If both x and y are 0.0, or if x is
negative and y is not an integer, the function prints a DOMAIN error message
to stderr, sets errno to EDOM, and returns 0.0. If an overflow results, the
function sets errno to ERANGE and returns±HUGE_VAL. No message is printed on
overflow or underflow.

The pow function does not recognize integral floating-point values greater
than 264, such as  1.0E100.


Compatibility

pow

    ANSI   DOS   OS/2   UNIX   XENIX


powl

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

exp, log functions, sqrt


Example

    /* POW.C */
    #include <math.h>
    #include <stdio.h>

    void main()
    {
        double x = 2.0, y = 3.0, z;

        z = pow( x, y );
        printf( "%.1f to the power of %.1f is %.1f\n", x, y, z );
    }


Output



    2.0 to the power of 3.0 is 8.0





printf
────────────────────────────────────────────────────────────────────────────


Description

Prints formatted output to the standard output stream.

    #include <stdio.h>

    int printf( const char *format [[, argument]]... );

format                            Format control

argument                          Optional arguments


Remarks

The printf function formats and prints a series of characters and values to
the standard output stream, stdout. The format argument consists of ordinary
characters, escape sequences, and (if arguments follow format) format
specifications. The ordinary characters and escape sequences are copied to
stdout in order of their appearance. For example, the line

    printf("Line one\n\t\tLine two\n");

produces the output

    Line one
            Line two

If arguments follow the format string, the format string must contain
specifications that determine the output format for the arguments.

Format specifications always begin with a percent sign (%) and are read left
to right. When the first format specification (if any) is encountered, the
value of the first argument after format is converted and output
accordingly. The second format specification causes the second argument to
be converted and output, and so on. If there are more arguments than there
are format specifications, the extra arguments are ignored. The results are
undefined if there are not enough arguments for all the format
specifications.

A format specification, which consists of optional and required fields, has
the following form:

    %[[flags]] [[width]] [[.precision]] [[{F | N | h | l | L}]] type

Format Specification Fields

Each field of the format specification is a single character or a number
signifying a particular format option. The simplest format specification
contains only the percent sign and a type character (for example,  %s). The
optional fields, which appear before the type character, control other
aspects of the formatting. The fields in a printf format specification are
described in the following list:

Field                             Description
────────────────────────────────────────────────────────────────────────────
type                              Required character that determines
                                    whether the associated argument is
                                    interpreted as a character, a string, or
                                    a number. (See Table R.2.)

flags                             Optional character or characters that
                                    control justification of output and
                                    printing of signs, blanks, decimal
                                    points, and octal and hexadecimal
                                    prefixes. (See Table R.3.) More than one
                                    flag can appear in a format
                                    specification.

width                             Optional number that specifies minimum
                                    number of characters output.

precision                         Optional number that specifies maximum
                                    number of characters printed for all or
                                    part of the output field, or minimum
                                    number of digits printed for integer
                                    values. (See Table R.4.)

F, N                              Optional prefixes that refer to the
                                    "distance" to the object being printed (
                                    near or far).

                                    F and N are not part of the ANSI
                                    definition for printf. They are
                                    Microsoft extensions that should not be
                                    used if ANSI portability is desired.

h, l, L                           Optional prefixes that determine the
                                    size of the argument expected, as shown
                                    below:

                                    Prefix      Use
────────────────────────────────────────────────────────────────────────────
                                    h           Used with the integer types
                                                d, i, o, x, and X to specify
                                                that the argument is short
                                                int, or with u to specify
                                                short unsigned int. If used
                                                with %p, it indicates a
                                                16-bit pointer.

                                    l           Used with d, i, o, x, and X
                                                types to specify that the
                                                argument is long int, or
                                                with u to specify long
                                                unsigned int; also used with
                                                e, E, f, g, and G types to
                                                specify double rather than
                                                float. If used with %p, it
                                                indicates a 32-bit pointer.

                                    L           Used with e, E, f, g, and G
                                                types to specify long double
                                                .

If a percent sign is followed by a character that has no meaning as a format
field, the character is copied to stdout. For example, to print a
percent-sign character, use %%.


Type Field Characters

The type character is the only required format field for the printf
function; it appears after any optional format fields. The type character
determines whether the associated argument is interpreted as a character, a
string, or a number. (See Table R.2.)

Table   R.2   Type Characters for printf

╓┌──────────┌────────────┌───────────────────────────────────────────────────╖
Character  Type         Output Format
────────────────────────────────────────────────────────────────────────────
d          int          Signed decimal integer.

i          int          Signed decimal integer.

u          int          Unsigned decimal integer.

o          int          Unsigned octal integer.

x          int          Unsigned hexadecimal integer, using "abcdef."

X          int          Unsigned hexadecimal integer, using "ABCDEF."

Character  Type         Output Format
────────────────────────────────────────────────────────────────────────────

f          double       Signed value having the form [-]dddd.dddd, where
                        dddd is one or more decimal digits. The number of
                        digits before the decimal point depends on the
                        magnitude of the number, and the number of digits
                        after the decimal point depends on the requested
                        precision.

e          double       Signed value having the form [-]d.dddd e [sign]ddd
                        , where d is a single decimal digit, dddd is one
                        or more decimal digits, ddd is exactly three
                        decimal digits, and sign is + or -.

E          double       Identical to the e format, except that E, rather
                        than e, introduces the exponent.

g          double       Signed value printed in f or e format, whichever
                        is more compact for the given value and precision.
                        The e format is used only when the exponent of the
Character  Type         Output Format
────────────────────────────────────────────────────────────────────────────
                        The e format is used only when the exponent of the
                        value is less than - 4 or greater than or equal to
                        the precision argument. Trailing zeros are
                        truncated, and the decimal point appears only if
                        one or more digits follow it.

G          double       Identical to the g format, except that G, rather
                        than g, introduces the exponent (where
                        appropriate).

c          int          Single character.

s          String       Characters printed up to the first null character
                        ('\0') or until the
                        precision value is reached.

n          Pointer to   Number of characters successfully written so far
            integer      to the stream or buffer; this value is stored in
                        the integer whose address is given as the
Character  Type         Output Format
────────────────────────────────────────────────────────────────────────────
                        the integer whose address is given as the
                        argument.

p          Far pointer  Prints the address pointed to by the argument in
            to void      the form xxxx:yyyy, where xxxx is the segment and
                        yyyy is the offset, and the digits x and y are
                        uppercase hexadecimal digits; %hp indicates a near
                        pointer and prints only the offset of the address.

────────────────────────────────────────────────────────────────────────────




Flag Directives

The first optional field of the format specification is flag. A flag
directive is a character that justifies output and prints signs, blanks,
decimal points, and octal and hexadecimal prefixes. More than one flag
directive may appear in a format specification. (See Table R.3.)

Table   R.3   Flag Characters for printf

╓┌──────────────────────────┌──────────────────────────┌─────────────────────►
Flag(, Meaning , Default)
─────────────────────────────────────────────────────────────────────────────
-                          Left justify the result    Right justify.
                            within the given field
                            width.

+                          Prefix the output value    Sign appears only for
                            with a sign                negative signed values
                            (+ or -) if the output     (-).
                            value is of a signed
                            type.

0                          If width is prefixed with  No padding.
                            0, zeros are added until
                            the minimum width is
                            reached. If 0 and -
Flag(, Meaning , Default)
─────────────────────────────────────────────────────────────────────────────
                            reached. If 0 and -
                            appear, the 0 is
                            ignored. If 0 is
                            specified with an
                            integer format (i, u, x,
                            X, o, d), the
                            0 is ignored.

blank (' ')                Prefix the output value    No blank appears.
                            with a blank if the
                            output value is signed
                            and positive; the blank
                            is ignored if both the
                            blank and + flags appear.

#                          When used with the o, x,   No blank appears.
                            or X format, the # flag
                            prefixes any nonzero
                            output value with 0, 0x,
Flag(, Meaning , Default)
─────────────────────────────────────────────────────────────────────────────
                            output value with 0, 0x,
                            or 0X, respectively.

                            When used with the e, E,   Decimal point appears
                            or f format, the # flag    only if digits follow i
                            forces the output value
                            to contain a decimal
                            point in all cases.

                            When used with the g or G  Decimal point appears
                            format, the # flag forces  only if digits follow i
                            the output value to        Trailing zeros are
                            contain a decimal point    truncated.
                            in all cases and prevents
                            the truncation of
                            trailing zeros.

                            Ignored when used with c,
                            d, i, u, or s.
Flag(, Meaning , Default)
─────────────────────────────────────────────────────────────────────────────
                            d, i, u, or s.

─────────────────────────────────────────────────────────────────────────────




Width Specification

The second optional field of the format specification is the width
specification. The width argument is a non-negative decimal integer
controlling the minimum number of characters printed. If the number of
characters in the output value is less than the specified width, blanks are
added to the left or the right of the values─depending on whether the  -
flag (for left justification) is specified─until the minimum width is
reached. If width is prefixed with 0, zeros are added until the minimum
width is reached (not useful for left-justified numbers).

The width specification never causes a value to be truncated. If the number
of characters in the output value is greater than the specified width, or
width is not given, all characters of the value are printed (subject to the
precision specification).

The width specification may be an asterisk (*), in which case an int
argument from the argument list supplies the value. The width argument must
precede the value being formatted in the argument list. A nonexistent or
small field width does not cause a truncation of a field; if the result of a
conversion is wider than the field width, the field expands to contain the
conversion result.


Precision Specification

The third optional field of the format specification is the precision
specification. It specifies a non-negative decimal integer, preceded by a
period (.), which specifies the number of characters to be printed, the
number of decimal places, or the number of significant digits. (See Table
R.4.) Unlike the width specification, the precision specification can cause
truncation of the output value, or rounding in the case of a floating-point
value. If precision is specified as zero and the value to be converted is
zero, the result is no characters output, as shown below:

    printf( "%.0d", 0 );      /* No characters output */

The precision specification may be an asterisk (*), in which case an int
argument from the argument list supplies the value. The precision argument
must precede the value being formatted in the argument list.

The interpretation of the precision value and the default when precision is
omitted depend on the type, as shown in Table R.4.

Table    R.4  How printf Precision Values Affect Type

╓┌─────────────────┌──────────────────────────────┌──────────────────────────►
Type              Meaning                        Default
─────────────────────────────────────────────────────────────────────────────
d, i, u, o, x, X  The precision specifies the    If precision is 0 or omitted
                    minimum number of digits to    entirely, or if the period (
                    be printed. If the number of   ) appears without a number
                    digits in the argument is      following it, the precision
                    less than precision, the       is set to 1.
Type              Meaning                        Default
─────────────────────────────────────────────────────────────────────────────
                    less than precision, the       is set to 1.
                    output value is padded on the
                    left with zeros. The value is
                    not truncated when the number
                    of digits exceeds precision.

e, E              The precision specifies the    Default precision is 6; if
                    number of digits to be         precision is 0 or the period
                    printed after the decimal      (.) appears without a number
                    point. The last printed digit  following it, no decimal
                    is rounded.                    point is printed.

f                 The precision value specifies  Default precision is 6; if
                    the number of digits after     precision is 0, or if the
                    the decimal point. If a        period (.) appears without a
                    decimal point appears, at      number following it, no
                    least one digit appears        decimal point is printed.
                    before it. The value is
                    rounded to the appropriate
Type              Meaning                        Default
─────────────────────────────────────────────────────────────────────────────
                    rounded to the appropriate
                    number of digits.

g, G              The precision specifies the    Six significant digits are
                    maximum number of significant  printed, with any trailing
                    digits printed.                zeros truncated.

c                 The precision has no effect.   Character is printed.

s                 The precision specifies the    Characters are printed until
                    maximum number of characters   a null character is
                    to be printed. Characters in   encountered.
                    excess of precision are not
                    printed.

─────────────────────────────────────────────────────────────────────────────



If the argument corresponding to a floating-point specifier is infinite,
indefinite, or not a number (NAN), the printf function gives the following
output:

Value                             Output
────────────────────────────────────────────────────────────────────────────
+ infinity                        1.#INFrandom-digits

- infinity                        -1.#INFrandom-digits

Indefinite                        digit.#INDrandom-digits

NAN                               digit.#NANrandom-digits


Size and Distance Specification

For printf, the format specification fields F and N refer to the "distance"
to the object being read (near or far), and h and l refer to the "size" of
the object being read (16-bit short or 32-bit long). The following list
clarifies this use of F, N, h, l, and L:

Program Code                      Action
────────────────────────────────────────────────────────────────────────────
printf ("%Ns");                   Print near string

printf ("%Fs");                   Print far string

printf ("%Nn");                   Store char count in near int

printf ("%Fn");                   Store char count in far int

printf ("%hp");                   Print a 16-bit pointer (xxxx)

printf ("%lp");                   Print a 32-bit pointer (xxxx:xxxx)

printf ("%Nhn");                  Store char count in near short int

printf ("%Nln");                  Store char count in near long int

printf ("%Fhn");                  Store char count in far short int

printf ("%Fln");                  Store char count in far int

The specifications "%hs" and "%ls" are meaningless to printf. The
specifications "%Np" and "%Fp" are aliases for "%hp" and "%lp" for the sake
of compatibility with Microsoft C version 4.0.


Return Value

The printf function returns the number of characters printed, or a negative
value in the case of an error.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fprintf, scanf, sprintf, vfprintf, vprintf, vsprintf


Example

    /* PRINTF.C illustrates output formatting with printf. */

    #include <stdio.h>

    void main()
    {
        char   ch = 'h', *string = "computer";
        int    count = -9234;
        double fp = 251.7366;

        /* Display integers. */
        printf( "Integer formats:\n"
                "\tDecimal: %d  Justified: %.6d  Unsigned: %u\n",
                count, count, count, count );

        printf( "Decimal %d as:\n\tHex: %Xh  C hex: 0x%x  Octal: %o\n",
                count, count, count, count );

        /* Display in different radixes. */
        printf( "Digits 10 equal:\n\tHex: %i  Octal: %i  Decimal: %i\n",
                0x10, 010, 10 );

        /* Display characters. */
        printf( "Characters in field:\n%10c   %5c\n", ch, ch );

        /* Display strings. */
        printf( "Strings in field:\n%25s\n%25.4s\n", string, string );

        /* Display real numbers. */
        printf( "Real numbers:\n\t%f    %.2f    %e    %E\n", fp, fp, fp, fp );

        /* Display pointers. */
        printf( "Address as:\n\tDefault: %p  Near: %Np  Far: %Fp\n",
                &count, (int _near *)&count, (int _far *)&count );

        /* Count characters printed. */
        printf( "Display to here:\n" );
        printf( "1234567890123456%n78901234567890\n", &count );
        printf( "\tNumber displayed: %d\n\n", count );

    }


Output



    Integer formats:
            Decimal: -9234  Justified: -009234  Unsigned: 56302
    Decimal -9234 as:
            Hex: DBEEh  C hex: 0xdbee  Octal: 155756
    Digits 10 equal:
            Hex: 16  Octal: 8  Decimal: 10
    Characters in field:
            h       h
    Strings in field:
                    computer
                        comp
    Real numbers:
            251.736600    251.74    2.517366e+002    2.517366E+002
    Address as:
            Default: 141C  Near: 141C  Far: 0087:141C
    Display to here:
    123456789012345678901234567890
            Number displayed: 16





putc, putchar
────────────────────────────────────────────────────────────────────────────


Description

Writes a character to a stream (putc) or to stdout (putchar).

    #include <stdio.h>

    int putc( int c, FILE *stream );

    int putchar( int c );

c                                 Character to be written

stream                            Pointer to FILE structure


Remarks

The putc routine writes the single character c to the output stream at the
current position. The putchar routine is identical to putc(c, stdout).

These routines are implemented as both macros and functions. See Section
1.4, "Choosing Between Functions and Macros," for a discussion of how to
select between the macro and function forms.


Return Value

The putc and putchar routines return the character written, or EOF in the
case of an error. Any integer can be passed to putc, but only the lower 8
bits are written.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fputc, fputchar, getc, getchar


Example

    /* PUTC.C: This program uses putc to write buffer to a stream.
    * If an error occurs, the program will stop before writing the
    * entire buffer.
    */

    #include <stdio.h>

    void main()
    {
        FILE *stream;
        char *p, buffer[] = "This is the line of output\n";
        int  ch;

    /* Make standard out the stream and write to it. */
        stream = stdout;
        for( p = buffer; (ch != EOF) && (*p != '\0'); p++ )
        ch = putc( *p, stream );
    }


Output



    This is the line of output





putch
────────────────────────────────────────────────────────────────────────────


Description

Writes a character to the console.

#include <conio.h>                Required only for function declarations

    int putch( int c );

c                                 Character to be output


Remarks

The putch function writes the character c directly (without buffering) to
the console.


Return Value

The function returns c if successful, and EOF if not.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

cprintf, getch, getche


Example

    /* GETCH.C: This program reads characters from the keyboard until it
    * receives a 'Y' or 'y'.
    */

    #include <conio.h>
    #include <ctype.h>

    void main()
    {
        int ch;

        cputs( "Type 'Y' when finished typing keys: " );
        do
        {
        ch = getch();
        ch = toupper( ch );
        } while( ch != 'Y' );

        putch( ch );
        putch( '\r' );    /* Carriage return */
        putch( '\n' );    /* Line feed       */
    }


Output



    Type 'Y' when finished typing keys: Y





putenv
────────────────────────────────────────────────────────────────────────────


Description

Creates new environment variables.

#include <stdlib.h>               Required only for function declarations

    int putenv( char *envstring );

envstring                         Environment-string definition


Remarks

The putenv function adds new environment variables or modifies the values of
existing environment variables. Environment variables define the environment
in which a process executes (for example, the default search path for
libraries to be linked with a program).

The envstring argument must be a pointer to a string with the form

varname=string

where varname is the name of the environment variable to be added or
modified and string is the variable's value. If varname is already part of
the environment, its value is replaced by string; otherwise, the new varname
variable and its string value are added to the environment. A variable can
be set to an empty value by specifying an empty string.

This function affects only the environment that is local to the currently
running process; it cannot be used to modify the command-level environment.
When the currently running process terminates, the environment reverts to
the level of the parent process (in most cases, the operating system level).
However, the environment affected by putenv can be passed to any child
processes created by spawn, exec, system, or (in OS/2 only) _popen, and
these child processes get any new items added by putenv.

Never free a pointer to an environment entry, because the environment
variable will then point to freed space. A similar problem can occur if you
pass putenv a pointer to a local variable, then exit the function in which
the variable is declared.

The putenv function operates only on data structures accessible to the
run-time library and not on the environment "segment" created for a process
by DOS or OS/2.

Note that environment-table entries must not be changed directly. If an
entry must be changed, use putenv. To modify the returned value without
affecting the environment table, use strdup or strcpy to make a copy of the
string.

The getenv and putenv functions use the global variable environ to access
the environment table. The putenv function may change the value of environ,
thus invalidating the envp argument to the main function. Therefore, it is
safer to use the environ variable to access the environment information.


Return Value

The putenv function returns 0 if it is successful. A return value of -1
indicates an error.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

getenv


Example

    /* GETENV.C: This program uses getenv to retrieve the LIB environment
    * variable and then uses putenv to change it to a new value.
    */

    #include <stdlib.h>
    #include <stdio.h>

    main()
    {
        char *libvar;

        /* Get the value of the LIB environment variable. */
        libvar = getenv( "LIB" );
        if( libvar != NULL )
        printf( "Original LIB variable is: %s\n", libvar );

        /* Attempt to change path. Note that this only affects the environment
        * variable of the current process. The command processor's environment
        * is not changed.
        */
        putenv( "LIB=c:\\mylib;c:\\yourlib" );

        /* Get new value. */
        libvar = getenv( "LIB" );
        if( libvar != NULL )
        printf( "New LIB variable is: %s\n", libvar );

    }


Output



    Original LIB variable is: C:\LIB
    New LIB variable is: c:\mylib;c:\yourlib





_putimage Functions
────────────────────────────────────────────────────────────────────────────


Description

Retrieve images from a buffer.

    #include <graph.h>

    void _far _putimage( short x, short y, char _huge *image, short action );

    void _far _putimage_w( double wx, double wy, char _huge *image, short
    action );

x, y                              Position of upper-left corner of image

image                             Stored image buffer

action                            Interaction with existing screen image

wx, wy                            Position of upper-left corner of image


Remarks

The _putimage function transfers to the screen the image stored in the
buffer that image points to.

In the _putimage function, the upper-left corner of the image is placed at
the view coordinate point (x, y). In the _putimage_w function, the
upper-left corner of the image is placed at the window coordinate point (wx,
wy).

The action argument defines the interaction between the stored image and the
one that is already on the screen. It may be any one of the following
manifest constants (defined in GRAPH.H):

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
_GAND                             Transfers the image over an existing
                                    image on the screen. The resulting image
                                    is the logical-AND product of the two
                                    images: points that had the same color
                                    in both the existing image and the new
                                    one will remain the same color, while
                                    points that have different colors are
                                    joined by logical-AND.

_GOR                              Superimposes the image onto an existing
                                    image. The new image does not erase the
                                    previous screen contents.

_GPRESET                          Transfers the data point-by-point onto
                                    the screen. Each point has the inverse
                                    of the color attribute it had when it
                                    was taken from the screen by _getimage,
                                    producing a negative image.

_GPSET                            Transfers the data point-by-point onto
                                    the screen. Each point has the exact
                                    color attribute it had when it was taken
                                    from the screen by _getimage.

_GXOR                             Causes the points on the screen to be
                                    inverted where a point exists in the
                                    image buffer. This behavior is exactly
                                    like that of the cursor: when an image
                                    is put against a complex background
                                    twice, the background is restored
                                    unchanged. This allows you to move an
                                    object around without erasing the
                                    background. The _GXOR constant is a
                                    special mode often used for animation.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getimage,  _imagesize


Example

See the example for _getimage.





puts
────────────────────────────────────────────────────────────────────────────


Description

Writes a string to stdout.

#include <stdio.h>

    int puts( const char *string );

string                            String to be output


Remarks

The puts function writes string to the standard output stream stdout,
replacing the string's terminating null character ('\0') with a newline
character (\n) in the output stream.


Return Value

The puts function returns a nonnegative value if it is successful. If the
function fails, it returns EOF.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fputs, gets


Example

    /* PUTS.C: This program uses puts to write a string to stdout. */

    #include <stdio.h>

    void main()
    {
        puts( "Hello world from puts!" );
    }


Output



    Hello world from puts!





putw
────────────────────────────────────────────────────────────────────────────


Description

Writes an integer to a stream.

    #include <stdio.h>

    int putw( int binint, FILE *stream );

binint                            Binary integer to be output

stream                            Pointer to FILE structure


Remarks

The putw function writes a binary value of type int to the current position
of stream. The putw function does not affect the alignment of items in the
stream, nor does it assume any special alignment.

The putw function is provided primarily for compatibility with previous
libraries. Note that portability problems may occur with putw, since the
size of an int and ordering of bytes within an int differ across systems.


Return Value

The putw function returns the value written. A return value of EOF may
indicate an error. Since EOF is also a legitimate integer value, ferror
should be used to verify an error.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

getw


Example

    /* PUTW.C: This program uses putw to write a word to a stream,
    * then performs an error check.
    */

    #include <stdio.h>
    #include <stdlib.h>

    void main()
    {
        FILE *stream;
        unsigned u;

        if( (stream = fopen( "data.out", "wb" )) == NULL )
        exit( 1 );
        for( u = 0; u < 10; u++ )
        {
        putw( u + 0x2132, stdout );
        putw( u + 0x2132, stream );   /* Write word to stream. */
        if( ferror( stream ) )        /* Make error check. */
        {
            printf( "putw failed" );
            clearerr( stream );
            exit( 1 );
        }
        }
        printf( "\nWrote ten words\n" );
        fclose( stream );
    }


Output



    2!3!4!5!6!7!8!9!:!;!
    Wrote ten words





qsort
────────────────────────────────────────────────────────────────────────────


Description

Performs a quick sort.

#include <stdlib.h>               For ANSI compatibility

#include <search.h>               Required only for function declarations

    void qsort( void *base, size_t num, size_t width,
    int( *compare ) ( const void *elem1, const void *elem2 ) );

base                              Start of target array

num                               Array size in elements

width                             Element size in bytes

compare                           Comparison function

elem1                             Pointer to the key for the search

elem2                             Pointer to the array element to be
                                    compared with the key


Remarks

The qsort function implements a quick-sort algorithm to sort an array of num
elements, each of width bytes. The argument base is a pointer to the base of
the array to be sorted. The qsort function overwrites this array with the
sorted elements.

The argument compare is a pointer to a user-supplied routine that compares
two array elements and returns a value specifying their relationship. The
qsort function calls the compare routine one or more times during the sort,
passing pointers to two array elements on each call:

compare( (void *) elem1, (void *) elem2 );

The routine must compare the elements, then return one of the following
values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
< 0                               elem1 less than elem2

= 0                               elem1 equivalent to elem2

> 0                               elem1 greater than elem2

The array is sorted in increasing order, as defined by the comparison
function. To sort an array in decreasing order, reverse the sense of
"greater than" and "less than" in the comparison function.


Return Value

None.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

bsearch, lsearch


Example

    /* QSORT.C: This program reads the command-line parameters and
    * uses qsort to sort them. It then displays the sorted arguments.
    */

    #include <search.h>
    #include <string.h>
    #include <stdio.h>

    int compare( char **arg1, char **arg2 );  /* Prototype */

    void main( int argc, char **argv )
    {
        int i;

        /* Eliminate argv[0] from sort: */
        argv++;
        argc─;

        /* Sort remaining args using Quicksort algorithm: */
        qsort( (void *)argv, (size_t)argc, sizeof( char * ), compare );

        /* Output sorted list: */
        for( i = 0; i < argc; ++i )
        printf( "%s ", argv[i] );
        printf( "\n" );
    }

    int compare( char **arg1, char **arg2 )
    {
        /* Compare all of both strings: */
        return strcmpi( *arg1, *arg2 );
    }


Output



    [C:\LIBREF] qsort every good boy deserves favor
    boy deserves every favor good





raise
────────────────────────────────────────────────────────────────────────────


Description

Sends a signal to the executing program.

    #include <signal.h>

    int raise( int sig );

sig                               Signal to be raised


Remarks

The raise function sends sig to the executing program. If a signal-handling
routine for sig has ben installed by a prior call to signal, raise causes
that routine to be executed. If no handler routine has been installed, the
default action (as listed below) is taken.

The signal value sig can be one of the following manifest constants:

╓┌──────────────────────┌──────────────────────────┌─────────────────────────►
Signal                 Meaning                    Default
─────────────────────────────────────────────────────────────────────────────
SIGABRT                Abnormal termination.      Terminates the calling
                                                    program with exit code 3.

SIGBREAK               CTRL+ BREAK interrupt.     Terminates the calling
                                                    program with exit code 3.

SIGFPE                 Floating-point error.      Terminates the calling
                                                    program.

SIGILL                 Illegal instruction. This  Terminates the calling
Signal                 Meaning                    Default
─────────────────────────────────────────────────────────────────────────────
SIGILL                 Illegal instruction. This  Terminates the calling
                        signal is not generated    program.
                        by DOS or OS/2, but is
                        supported for ANSI
                        compatibility.

SIGINT                 CTRL+ C interrupt.         Issues INT23H.

SIGSEGV                Illegal storage access.    Terminates the calling
                        This signal is not         program.
                        generated by DOS or OS/2,
                        but is supported for ANSI
                        compatiblity.

SIGTERM                Termination request sent   Ignores the signal.
                        to the program. This
                        signal is not generated
                        by DOS or OS/2, but is
                        supported for ANSI
Signal                 Meaning                    Default
─────────────────────────────────────────────────────────────────────────────
                        supported for ANSI
                        compatibility.

SIGUSR1                User-defined signals.      Ignores the signal.
SIGUSR2
SIGUSR3




Return Value

If successful, the raise function returns 0. Otherwise, it returns a nonzero
value.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

abort, signal


Example

See the example for signal.





rand
────────────────────────────────────────────────────────────────────────────


Description

Generates a pseudorandom number.

#include <stdlib.h>               Required only for function declarations

    int rand( void );


Remarks

The rand function returns a pseudorandom integer in the range 0 to RAND_MAX.
The srand routine can be used to seed the pseudorandom-number generator
before calling rand.


Return Value

The rand function returns a pseudorandom number, as described above. There
is no error return.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

srand


Example

    /* RAND.C: This program seeds the random-number generator with the
    * time, then displays 20 random integers.
    */

    #include <stdlib.h>
    #include <stdio.h>
    #include <time.h>

    void main()
    {
        int i;

        /* Seed the random-number generator with current time so that
        * the numbers will be different every time we run.
        */
        srand( (unsigned)time( NULL ) );

        /* Display 10 numbers. */
        for( i = 0; i < 10; i++ )
            printf( "  %6d\n", rand() );
    }


Output



        19471
        16395
        8268
        15582
        6489
        28356
        27042
        5276
        23070
        10930





read
────────────────────────────────────────────────────────────────────────────


Description

Reads data from a file.

#include <io.h>                   Required only for function declarations

    int read( int handle, void *buffer, unsigned int count );

handle                            Handle referring to open file

buffer                            Storage location for data

count                             Maximum number of bytes


Remarks

The read function attempts to read count bytes into buffer from the file
associated with handle. The read operation begins at the current position of
the file pointer associated with the given file. After the read operation,
the file pointer points to the next unread character.


Return Value

The read function returns the number of bytes actually read, which may be
less than count if there are fewer than count bytes left in the file, or if
the file was opened in text mode (see below). The return value 0 indicates
an attempt to read at end-of-file. The return value -1 indicates an error,
and errno is set to the following value:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EBADF                             The given handle is invalid; or the file
                                    is not open for reading; or (DOS
                                    versions 3.0 and later and OS/2 only)
                                    the file is locked.

If you are reading more than 32K (the maximum size for type int) from a
file, the return value should be of type unsigned int (see the example that
follows). However, the maximum number of bytes that can be read from a file
in one operation is 65,534, since 65,535 (or 0xFFFF) is indistinguishable
from -1, and therefore cannot be distinguished from an error return.

If the file was opened in text mode, the return value may not correspond to
the number of bytes actually read. When text mode is in effect, each
carriage-return-line-feed (CR-LF) pair is replaced with a single line-feed
character. Only the single line-feed character is counted in the return
value. The replacement does not affect the file pointer.

Note that under DOS and OS/2, when files are opened in text mode, a CTRL+Z
character is treated as an end-of-file indicator. When the CTRL+Z is
encountered, the read terminates, and the next read returns 0 bytes. The
lseek function will clear the end-of-file indicator.


Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

creat, fread, open, write


Example

    /* READ.C: This program opens a file named READ.C and tries to read 60,000
    * bytes from that file using read. It then displays the actual
    * number of bytes read from READ.C.
    */

    #include <fcntl.h>      /* Needed only for O_RDWR definition */
    #include <io.h>
    #include <stdlib.h>
    #include <stdio.h>

    char buffer[60000];

    void main()
    {
        int fh;
        unsigned int nbytes = 60000, bytesread;

        /* Open file for input: */
        if( (fh = open( "read.c", O_RDONLY )) == -1 )
        {
        perror( "open failed on input file" );
        exit( 1 );
        }

        /* Read in input: */
        if( ( bytesread = read( fh, buffer, nbytes ) ) <= 0 )
        perror( "Problem reading file" );
        else
        printf( "Read %u bytes from file\n", bytesread );

        close( fh );
    }


Output



    Read 747 bytes from file





realloc Functions
────────────────────────────────────────────────────────────────────────────


Description


#include <stdlib.h>

                                    For ANSI compatibility (realloc only)

#include <malloc.h>               Required only for function declarations

    void *realloc( void *memblock, size_t size );

    void _based( void ) *_brealloc( _segment seg, void _based( void )
    *memblock,
    size_t size );

    void _far *_frealloc( void _far *memblock, size_t size );

    void _near *_nrealloc( void _near *memblock, size_t size );

memblock                          Pointer to previously allocated memory
                                    block

size                              New size in bytes

seg                               Segment selector


Remarks

The realloc family of functions changes the size of a previously allocated
memory block. The memblock argument points to the beginning of the memory
block. If memblock is NULL, realloc functions in the same way as malloc and
allocates a new block of size bytes. If memblock is not NULL, it should be a
pointer returned by calloc, malloc, or a prior call to realloc.

The size argument gives the new size of the block, in bytes. The contents of
the block are unchanged up to the shorter of the new and old sizes, although
the new block may be in a different location.

The memblock argument can also point to a block that has been freed, as long
as there has been no intervening call to the corresponding calloc, malloc,
_expand, or realloc function. If successful, the reallocated block is marked
in use.

In large data models (that is, compact-, large-, and huge-model programs),
realloc maps to _frealloc. In small data models (tiny-, small-, and
medium-model programs), realloc maps to _nrealloc.

The various realloc functions reallocate memory in the heap specified in the
following list:

Function                          Heap
────────────────────────────────────────────────────────────────────────────
realloc                           Depends on data model of program

_brealloc                         Based heap specified by seg value

_frealloc                         Far heap (outside default data segment)

_nrealloc                         Near heap (inside default data segment)


Return Value

The realloc functions return a void pointer to the reallocated (and possibly
moved) memory block.

The return value is NULL if the size is zero and the buffer argument is not
NULL, or if there is not enough available memory to expand the block to the
given size. In the first case, the original block is freed. In the second,
the original block is unchanged.

The storage space pointed to by the return value is guaranteed to be
suitably aligned for storage of any type of object. To get a pointer to a
type other than void, use a type cast on the return value.


Compatibility

realloc

    ANSI   DOS   OS/2   UNIX   XENIX


_brealloc,  _frealloc,  _nrealloc

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

calloc functions, free functions, malloc functions


Example

    /* REALLOC.C: This program allocates a block of memory for buffer
    * and then uses _msize to display the size of that block. Next, it
    * uses realloc to expand the amount of memory used by buffer
    * and then calls _msize again to display the new amount of
    * memory allocated to buffer.
    */

    #include <stdio.h>
    #include <malloc.h>
    #include <stdlib.h>

    void main()
    {
        long *buffer;
        size_t size;

        if( (buffer = (long *)malloc( 1000 * sizeof( long ) )) == NULL )
        exit( 1 );

        size = _msize( buffer );
        printf( "Size of block after malloc of 1000 longs: %u\n", size );

        /* Reallocate and show new size: */
        if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) ==
NULL )
        exit( 1 );
        size = _msize( buffer );
        printf( "Size of block after realloc of 1000 more longs: %u\n", size );

        free( buffer );
    }


Output



    Size of block after malloc of 1000 longs: 4000
    Size of block after realloc of 1000 more longs: 8000





_rectangle Functions
────────────────────────────────────────────────────────────────────────────


Description

Draw rectangles.

    #include <graph.h>

    short _far _rectangle( short control, short x1, short y1, short x2, short
    y2 );

    short _far _rectangle_w( short control, double wx1, double wy1, double
    wx2,
    double wy2 );

    short _far _rectangle_wxy( short control, struct _wxycoord _far *pwxy1,
    struct _wxycoord _far *pwxy2 );

control                           Fill flag

x1, y1                            Upper-left corner

x2, y2                            Lower-right corner

wx1, wy1                          Upper-left corner

wx2, wy2                          Lower-right corner

pwxy1                             Upper-left corner

pwxy2                             Lower-right corner


Remarks

The _rectangle functions draw a rectangle with the current line style.

The _rectangle function uses the view coordinate system. The view coordinate
points  (x1, y1) and (x2, y2) are the diagonally opposed corners of the
rectangle.

The _rectangle_w function uses the window coordinate system. The window
coordinate points (wx1, wy1) and (wx2, wy2) are the diagonally opposed
corners of the rectangle.

The _rectangle_wxy function uses the window coordinate system. The window
coordinate points (pwxy1) and (pwxy2) are the diagonally opposed corners of
the rectangle. The coordinates for the _rectangle_wxy routine are given in
terms of an _wxycoord structure (defined in GRAPH.H), which contains the
following elements:

Element                           Description
────────────────────────────────────────────────────────────────────────────
double wx                         window x coordinate

double wy                         window y coordinate

The control parameter can be one of the following manifest constants:

Constant                          Action
────────────────────────────────────────────────────────────────────────────
_GFILLINTERIOR                    Fills the figure with the current color
                                    using the current fill mask

_GBORDER                          Does not fill the rectangle

If the current fill mask is NULL, no mask is used. Instead, the rectangle is
filled with the current color.

If you try to fill the rectangle with the _floodfill function, the rectangle
must be bordered by a solid line-style pattern.


Return Value

The function returns a nonzero value if the rectangle is drawn successfully,
or 0 if not.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_arc functions,  _ellipse functions,  _floodfill,  _getcolor,  _lineto
functions, _pie functions,  _setcolor,  _setfillmask


Example

    /* RECT.C: This program draws a rectangle. */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void main()
    {
        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        _rectangle( _GBORDER, 80, 50, 240, 150 );

        getch();

        _setvideomode( _DEFAULTMODE );
    }





_registerfonts
────────────────────────────────────────────────────────────────────────────


Description

Initializes the fonts graphics system.

    #include <graph.h>

    short _far _registerfonts( unsigned char _far *pathname );

pathname                          Path name specifying .FON files to be
                                    registered


Remarks

The _registerfonts function initializes the fonts graphics system. Font
files must be registered with the _registerfonts function before any other
font-related library function (_getgtextextent, _outgtext, _setfont,
_unregisterfonts) can be used.

The _registerfonts function reads the specified files and loads font header
information into memory. Each font header takes up about 140 bytes of
memory.

The pathname argument is the path specification and file name of valid .FON
files. The pathname can contain standard DOS wild-card characters.

The font functions affect only the output from the font output function
_outgtext; no other C run-time output functions are affected by font usage.



Return Value

The _registerfonts function returns a positive value which indicates the
number of fonts successfully registered. A negative return value indicates
failure. The following negative values may be returned:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
-1                                No such file or directory.

-2                                One or more of the .FON files was not a
                                    valid, binary .FON file.

-3                                One or more of the .FON files is
                                    damaged.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

    _getfontinfo,  _getgtextextent,  _outgtext,  _setfont,  _unregisterfonts


Example

See the example for _outgtext.





_remapallpalette, _remappalette
────────────────────────────────────────────────────────────────────────────


Description

Remap all palette colors.

    #include <graph.h>

    short _far _remapallpalette( long _far *colors );

    long _far _remappalette( short index, long color );

colors                            Color value array

index                             Color index to reassign

color                             Color value to assign color index to


Remarks

The _remapallpalette function remaps the entire color palette simultaneously
to the colors given in the colors array. The colors array is an array of
long integers where the size of the array varies from 16 to 64 to 256,
depending on the video mode. The number of colors mapped depends on the
number of colors supported by the current video mode. The _remapallpalette
function works in all video modes (except _ORESCOLOR mode), but only with
EGA, MCGA, or VGA hardware.

The default color values for a color text on 16-color graphics mode are
shown below:

╓┌───────┌─────────┌───────┌─────────────────────────────────────────────────╖
Number  Color     Number  Color
────────────────────────────────────────────────────────────────────────────
0       Black     8       Dark gray

1       Blue      9       Light blue
Number  Color     Number  Color
────────────────────────────────────────────────────────────────────────────
1       Blue      9       Light blue

2       Green     10      Light green

3       Cyan      11      Light cyan

4       Red       12      Light red

5       Magenta   13      Light magenta

6       Brown     14      Yellow

7       White     15      Bright white



The first array element specifies the new color value to be associated with
color index 0 (the background color in graphics modes). After the call to
_remapallpalette, calls to _setcolor will index into the new array of
colors. The mapping done by _remapallpalette affects the current display
immediately.

The colors array can be larger than the number of colors supported by the
current video mode, but only the first n elements are used, where n is the
number of colors supported by the current video mode, as indicated by the
numcolors element of the videoconfig  structure.

The long color value is defined by specifying three bytes of data
representing the three component colors: red, green, and blue.

Each of the three bytes represents the intensity of one of the red, green,
or blue component colors, and must be in the range 0-31. In other words, the
low-order six bits of each byte specify the component's intensity and the
high-order two bits should be zero. The fourth (high-order) byte in the long
is unused and should be set to zero. The diagram below shows the ordering of
bytes within the long value.

For example, to create a lighter shade of blue, start with lots of blue, add
some green, and maybe a little bit of red. The three-byte color value would
be:

    blue byte            green byte        red byte
    00011111             00101111          00011111
    high ───────────────->  low order

Manifest constants are defined in GRAPH.H for the default color values
corresponding to color indices 0-15 in color text modes and 16-color
graphics modes, as shown below:

╓┌──────┌──────────┌──────┌──────────────────────────────────────────────────╖
Index  Constant   Index  Constant
────────────────────────────────────────────────────────────────────────────
0      _BLACK     8      _GRAY

1      _BLUE      9      _LIGHTBLUE

2      _GREEN     10     _LIGHTGREEN

3      _CYAN      11     _LIGHTCYAN

4      _RED       12     _LIGHTRED
Index  Constant   Index  Constant
────────────────────────────────────────────────────────────────────────────
4      _RED       12     _LIGHTRED

5      _MAGENTA   13     _LIGHTMAGENTA

6      _BROWN     14     _YELLOW

7      _WHITE     15     _BRIGHTWHITE



The VGA supports a palette of 262,144 colors (256K) in color modes, and the
EGA supports a palette of only 64 different colors. Color values for EGA are
specified in exactly the same way as with the VGA; however, the low-order
four bits of each byte are simply ignored.

The _remappalette function assigns a new color value color to the color
index given by index. This remapping affects the current display
immediately.

The _remappalette function works in all graphics modes, but only with EGA,
MCGA, or VGA hardware. An error results if the function is called while
using any other configuration.

The color value used in _remappalette is defined and used exactly as noted
above for _remapallpalette. The range of color indices used with
_remappalette depends on the number of colors supported by the video mode.

The _remapallpalette and _remappalette functions do not affect the
presentation-graphics palettes, which are manipulated with the
_pg_getpalette, _pg_setpalette, and _pg_resetpalette functions.

If a VGA or MCGA adapter is connected to an analog monochrome monitor, the
color value is transformed into its gray-scale equivalent, based on the
weighted sum of its red, green, and blue components (30% red + 50% green +
11% blue). The original red, green, and blue values are lost.


Return Value

If successful, _remapallpalette returns -1 (short). In case of an error,
_remapallpalette returns 0 (short).

If successful, _remappalette returns the color value previously assigned to
index, or -1 if the function is inoperative (not EGA, VGA, or MCGA), or if
the color index is out of range.

Note that _remapallpalette returns a short value and _remappalette returns a
long value.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_selectpalette,  _setbkcolor,  _setvideomode


Example

    /* RMPALPAL.C: This example illustrates functions for assigning
    * color values to color indices. Functions illustrated include:
    *    _remappalette         _remapallpalette
    */

    #include <graph.h>
    #include <conio.h>
    #include <stdio.h>
    #include <stdlib.h>

    /* Macro for mixing Red, Green, and Blue elements of color */
    #define RGB(r,g,b) (((long) ((b) << 8 | (g)) << 8) | (r))

    long tmp, pal[256];
    void main()
    {
        short  red, blue, green;
        short  inc, i, mode, cells, x, y, xinc, yinc;
        char   buf[40];
        struct videoconfig vc;

        /* Make sure all palette numbers are valid. */
        for( i = 0; i < 256; i++ )
        pal[i] = _BLACK;

        /* Loop through each graphics mode that supports palettes. */
        for( mode = _MRES4COLOR; mode <= _MRES256COLOR; mode++ )
        {
        if( mode == _ERESNOCOLOR )
            mode++;
        if( !_setvideomode( mode ) )
            continue;

        /* Set variables for each mode. */
        _getvideoconfig( &vc );
        switch( vc.numcolors )
        {
            case 256:          /* Active bits in this order:           */
                cells = 13;
                inc = 12;       /* ???????? ??bbbbbb ??gggggg ??rrrrrr  */
                break;
            case  16:
                cells = 4;
                if( (vc.mode == _ERESCOLOR) || (vc.mode == _VRES16COLOR) )
                    inc = 16;    /* ???????? ??bb???? ??gg???? ??rr????  */
                else
                    inc = 32;    /* ???????? ??Bb???? ??Gg???? ??Rr????  */
                break;
            case   4:
                cells = 2;
                inc = 32;       /* ???????? ??Bb???? ??Gg???? ??Rr????  */
                break;
            default:
                continue;
        }
        xinc = vc.numxpixels / cells;
        yinc = vc.numypixels / cells;

    /* Fill palette arrays in BGR order. */
        for( i = 0, blue = 0; blue < 64; blue += inc )
            for( green = 0; green < 64; green += inc )
                for( red = 0; red < 64; red += inc )
                {
                    pal[i] = RGB( red, green, blue );
                    /* Special case of using 6 bits to represent 16 colors.
                    * If both bits are on for any color, intensity is set.
                    * If one bit is set for a color, the color is on.
                    */
                    if( inc == 32 )
                    pal[i + 8] = pal[i] | (pal[i] >> 1);
                    i++;
                }

        /* If palettes available, remap all palettes at once. */
        if( !_remapallpalette( pal ) )
        {
            _setvideomode( _DEFAULTMODE );
            _outtext( "Palettes not available with this adapter" );
            exit( 1 );
        }

        /* Draw colored squares. */
        for( i = 0, x = 0; x < ( xinc * cells ); x += xinc )
            for( y = 0; y < ( yinc * cells); y += yinc )
            {
                _setcolor( i++ );
                _rectangle( _GFILLINTERIOR, x, y, x + xinc, y + yinc );
            }

        /* Note that for 256-color mode, not all colors are shown. The
number
            * of colors from mixing three base colors can never be the same as
            * the number that can be shown on a two-dimensional grid.
            */
        sprintf( buf, "Mode %d has %d colors", vc.mode, vc.numcolors );
        _setcolor( vc.numcolors / 2 );
        _outtext( buf );
        getch();

    /* Change each palette entry separately in GRB order. */
        for( i = 0, green = 0; green < 64; green += inc )
            for( red = 0; red < 64; red += inc )
                for(blue = 0; blue < 64; blue += inc )
                {
                    tmp = RGB( red, green, blue );
                    _remappalette( i, tmp );
                    if( inc == 32 )
                    _remappalette( i + 8, tmp | (tmp >> 1) );
                    i++;
                }
        getch();
        }
        _setvideomode( _DEFAULTMODE );
    }





remove
────────────────────────────────────────────────────────────────────────────


Description

Deletes a file.

#include <stdio.h>                Required for ANSI compatibility

#include <io.h>                   Use either IO.H or STDIO.H

    int remove( const char *path );

path                              Path name of file to be removed


Remarks

The remove function deletes the file specified by path.


Return Value

The function returns 0 if the file is successfully deleted. Otherwise, it
returns -1 and sets errno to one of these values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            Path name specifies a read-only file.

ENOENT                            File or path name not found, or path
                                    name specifies a directory.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

unlink


Example

    /* REMOVE.C: This program uses remove to delete REMOVE.OBJ. */

    #include <stdio.h>

    void main()
    {
        if( remove( "remove.obj" ) == -1 )
        perror( "Could not delete 'REMOVE.OBJ'" );
        else
        printf( "Deleted 'REMOVE.OBJ'\n" );
    }


Output



    Deleted 'REMOVE.OBJ'





rename
────────────────────────────────────────────────────────────────────────────


Description

Renames a file or directory.

#include <stdio.h>                Required for ANSI compatibility

#include <io.h>                   Use either IO.H or STDIO.H

    int rename( const char *oldname, const char *newname );

oldname                           Pointer to old name

newname                           Pointer to new name


Remarks

The rename function renames the file or directory specified by oldname to
the name given by newname. The old name must be the path name of an existing
file or directory. The new name must not be the name of an existing file or
directory.

The rename function can be used to move a file from one directory to another
by giving a different path name in the newname argument. However, files
cannot be moved from one device to another (for example, from drive A to
drive B). Directories can only be renamed, not moved.


Return Value

The rename function returns 0 if it is successful. On an error, it returns a
nonzero value and sets errno to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            File or directory specified by newname
                                    already exists or could not be created
                                    (invalid path); or oldname is a
                                    directory and newname specifies a
                                    different path.

ENOENT                            File or path name specified by oldname
                                    not found.

EXDEV                             Attempt to move a file to a different
                                    device.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



Example

    /* RENAMER.C: This program attempts to rename a file named RENAMER.OBJ to
    * RENAMER.JBO. For this operation to succeed, a file named RENAMER.OBJ
    * must exist and a file named RENAMER.JBO must not exist.
    */

    #include <stdio.h>

    void main()
    {
        int  result;
        char old[] = "RENAMER.OBJ", new[] = "RENAMER.JBO";

        /* Attempt to rename file: */
        result = rename( old, new );
        if( result != 0 )
        printf( "Could not rename '%s'\n", old );
        else
        printf( "File '%s' renamed to '%s'\n", old, new );
    }


Output



    File 'RENAMER.OBJ' renamed to 'RENAMER.JBO'





rewind
────────────────────────────────────────────────────────────────────────────


Description

Repositions the file pointer to the beginning of a file.

    #include <stdio.h>

    void rewind( FILE *stream );

stream                            Pointer to FILE structure


Remarks

The rewind function repositions the file pointer associated with stream to
the beginning of the file. A call to rewind is equivalent to

(void) fseek( stream, 0L, SEEK_SET );

except that rewind clears the error indicators for the stream, and fseek
does not. Both rewind and fseek clear the end-of-file indicator. Also, fseek
returns a value that indicates whether the pointer was successfully moved,
but rewind does not return any value.

You can also use the rewind function to clear the keyboard buffer. Use the
rewind function with the stream stdin, which is associated with the keyboard
by default.


Return Value

The rewind function has no return value.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



Example

    /* REWIND.C: This program first opens a file named REWIND.OUT for input
    and
    * output and writes two integers to the file. Next, it uses rewind to
    * reposition the file pointer to the beginning of the file and reads
    * the data back in.
    */

    #include <stdio.h>

    void main()
    {
        FILE *stream;
        int data1, data2;

        data1 = 1;
        data2 = -37;

        if( (stream = fopen( "rewind.out", "w+" )) != NULL )
        {
        fprintf( stream, "%d %d", data1, data2 );
        printf( "The values written are: %d and %d\n", data1, data2 );
        rewind( stream );
        fscanf( stream, "%d %d", &data1, &data2 );
        printf( "The values read are: %d and %d\n", data1, data2 );
        fclose( stream );
        }
    }


Output



    The values written are: 1 and -37
    The values read are: 1 and -37





rmdir
────────────────────────────────────────────────────────────────────────────


Description

Deletes a directory.

#include <direct.h>               Required only for function declarations

    int rmdir( char *dirname );

dirname                           Path name of directory to be removed


Remarks

The rmdir function deletes the directory specified by dirname. The directory
must be empty, and it must not be the current working directory or the root
directory.


Return Value

The rmdir function returns the value 0 if the directory is successfully
deleted. A return value of -1 indicates an error, and errno is set to one of
the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EACCES                            The given path name is not a directory;
                                    or the directory is not empty; or the
                                    directory is the current working
                                    directory or the  root directory.

ENOENT                            Path name not found.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

chdir, mkdir


Example

    /* MAKEDIR.C */
    #include <direct.h>
    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        int result;

    if( mkdir( "\\testtmp" ) == 0 )
        {
        printf( "Directory '\\testtmp' was successfully created\n" );
        system( "dir \\testtmp" );
        if( rmdir( "\\testtmp" ) == 0 )
            printf( "Directory '\\testtmp' was successfully removed\n"  );
        else
            printf( "Problem removing directory '\\testtmp'\n" );
        }
        else
        printf( "Problem creating directory '\\testtmp'\n" );
    }


Output



    Directory '\testtmp' was successfully created

    The volume label in drive C is OS2.
    Directory of C:\TESTTMP

    .            <DIR>      6-19-89  11:20a
    ..           <DIR>      6-19-89  11:20a
        2 File(s)   12730368 bytes free
    Directory '\testtmp' was successfully removed





rmtmp
────────────────────────────────────────────────────────────────────────────


Description

Removes temporary files.

    #include <stdio.h>

    int rmtmp( void );


Remarks

The rmtmp function is used to clean up all the temporary files in the
current directory. The function removes only those files created by tmpfile
and should be used only in the same directory in which the temporary files
were created.


Return Value

The rmtmp function returns the number of temporary files closed and deleted.



Compatibility

▼ ANSI   DOS   OS/2   UNIX   XENIX



See Also

flushall, tmpfile, tmpnam


Example

    /* TMPFILE.C: This program uses tmpfile to create a temporary file,
    * then deletes this file with rmtmp.
    */

    #include <stdio.h>

    void main()
    {
        FILE *stream;
        char tempstring[] = "String to be written";
        int  i;

        /* Create temporary files. */
        for( i = 1; i <= 10; i++ )
        {
        if( (stream = tmpfile()) == NULL )
            perror( "Could not open new temporary file\n" );
        else
            printf( "Temporary file %d was created\n", i );
        }

        /* Remove temporary files. */
        printf( "%d temporary files deleted\n", rmtmp() );
    }


Output



    Temporary file 1 was created
    Temporary file 2 was created
    Temporary file 3 was created
    Temporary file 4 was created
    Temporary file 5 was created
    Temporary file 6 was created
    Temporary file 7 was created
    Temporary file 8 was created
    Temporary file 9 was created
    Temporary file 10 was created
    10 temporary files deleted





_rotl, _rotr
────────────────────────────────────────────────────────────────────────────


Description

Rotate bits to the left (_rotl) or right (_rotr).

    #include <stdlib.h>

    unsigned int _rotl( unsigned int value, int shift );

    unsigned int _rotr( unsigned int value, int shift );

value                             Value to be rotated

shift                             Number of bits to shift


Remarks

The _rotl and _rotr functions rotate the unsigned value by shift bits. The
_rotl function rotates the value left. The _rotr function rotates the value
right. Both functions "wrap" bits rotated off one end of value to the other
end.


Return Value

Both functions return the rotated value. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_lrotl,  _lrotr


Example

    /* ROT.C: This program uses _rotr and _rotl with different shift
    * values to rotate an integer.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        unsigned val = 0x0fd93;

        printf( "0x%4.4x rotated left three times is 0x%4.4x\n",
                val, _rotl( val, 3 ) );
        printf( "0x%4.4x rotated right four times is 0x%4.4x\n",
                val, _rotr( val, 4 ) );
    }


Output



    0xfd93 rotated left three times is 0xec9f
    0xfd93 rotated right four times is 0x3fd9





scanf
────────────────────────────────────────────────────────────────────────────


Description

Reads formatted data from the standard input stream.

    #include <stdio.h>

    int scanf( const char *format [[,argument]]... );

format                            Format control

argument                          Optional argument


Remarks

The scanf function reads data from the standard input stream stdin into the
locations given by argument. Each argument must be a pointer to a variable
with a type that corresponds to a type specifier in format. The format
controls the interpretation of the input fields. The format can contain one
or more of the following:


    ■   White-space characters: blank (' '); tab (\t); or newline (\n). A
        white-space character causes scanf to read, but not store, all
        consecutive white-space characters in the input up to the next
        non-white-space character. One white-space character in the format
        matches any number (including 0) and combination of white-space
        characters in the input.

    ■   Non-white-space characters, except for the percent sign (%). A
        non-white-space character causes scanf to read, but not store, a
        matching non-white-space character. If the next character in stdin
        does not match, scanf terminates.

    ■   Format specifications, introduced by the percent sign (%). A format
        specification causes scanf to read and convert characters in the input
        into values of a specified type. The value is assigned to an argument
        in the argument list.


The format is read from left to right. Characters outside format
specifications are expected to match the sequence of characters in stdin;
the matching characters in stdin are scanned but not stored. If a character
in stdin conflicts with the format specification, scanf terminates. The
character is left in stdin as if it had not been read.

When the first format specification is encountered, the value of the first
input field is converted according to this specification and stored in the
location that is specified by the first argument. The second format
specification causes the second input field to be converted and stored in
the second argument, and so on through the end of the format string.

An input field is defined as all characters up to the first white-space
character (space, tab, or newline), or up to the first character that cannot
be converted according to the format specification, or until the field width
(if specified) is reached. If there are too many arguments for the given
specifications, the extra arguments are evaluated but ignored. The results
are unpredictable if there are not enough arguments for the format
specification.

A format specification has the following form:

    %[[*]] [[width]] [[{F | N}]] [[{h | l}]]type

Each field of the format specification is a single character or a number
signifying a particular format option. The type character, which appears
after the last optional format field, determines whether the input field is
interpreted as a character, a string, or a number. The simplest format
specification contains only the percent sign and a type character (for
example,  %s ).

Each field of the format specification is discussed in detail below. If a
percent sign (%) is followed by a character that has no meaning as a
format-control character, that character and the following characters (up to
the next percent sign) are treated as an ordinary sequence of
characters─that is, a sequence of characters that must match the input. For
example, to specify that a percent-sign character is to be input, use  %%.

An asterisk (*) following the percent sign suppresses assignment of the next
input field, which is interpreted as a field of the specified type. The
field is scanned but not stored.

The width is a positive decimal integer controlling the maximum number of
characters to be read from stdin. No more than width characters are
converted and stored at the corresponding argument. Fewer than width
characters may be read if a white-space character (space, tab, or newline)
or a character that cannot be converted according to the given format occurs
before width is reached.

The optional F and N prefixes allow the user to specify whether the argument
is far or near, respectively. F should be prefixed to an argument pointing
to a far object, while N should be prefixed to an argument pointing to a
near object. Note also that the F and N prefixes are not part of the ANSI
definition for scanf, but are instead Microsoft extensions, which should not
be used when ANSI portability is desired.

The optional prefix l indicates that the long version of the following type
is to be used, while the prefix h indicates that the short version is to be
used. The corresponding argument should point to a long or double object
(with the l character) or a short object (with the h character). The l and h
modifiers can be used with the d, i, n, o, x, and u type characters. The l
modifier can also be used with the e, f, and g type characters. The l and h
modifiers are ignored if specified for any other type.

For scanf, N and F refer to the "distance" to the object being read in (near
or far) and h and l refer to the "size" of the object being read in (16-bit
short or 32-bit long). The list below clarifies this use of N, F, l, and h:


Program Code                      Action
────────────────────────────────────────────────────────────────────────────
scanf( "%Ns", &x );               Read a string into near memory

scanf( "%Fs", &x );               Read a string into far memory

scanf( "%Nd", &x );               Read an int into near memory

scanf( "%Fd", &x );               Read an int into far memory

scanf( "%Nld", &x );              Read a long int into near memory

scanf( "%Fld", &x );              Read a long int into far memory

scanf( "%Nhp", &x );              Read a 16-bit pointer into near memory

scanf( "%Nlp", &x );              Read a 32-bit pointer into near memory

scanf( "%Fhp", &x );              Read a 16-bit pointer into far memory

scanf( "%Flp", &x );              Read a 32-bit pointer into far memory

The type characters and their meanings are described in Table R.5.

To read strings not delimited by space characters, a set of characters in
brackets ([ ]) can be substituted for the s (string) type character. The
corresponding input field is read up to the first character that does not
appear in the bracketed character set. If the first character in the set is
a caret (^), the effect is reversed: the input field is read up to the first
character that does appear in the rest of the character set.

Note that %[a-z] and %[z-a] are interpreted as equivalent to %[abcde...z].
This is a common scanf extension, but note that it is not required by the
ANSI specification.

To store a string without storing a terminating null character ('\0'), use
the specification %nc, where n is a decimal integer. In this case, the c
type character indicates that the argument is a pointer to a character
array. The next n characters are read from the input stream into the
specified location, and no null character ('\0') is appended. If n is not
specified, the default value for it is 1.

The scanf function scans each input field, character by character. It may
stop reading a particular input field before it reaches a space character
for a variety of reasons: the specified width has been reached; the next
character cannot be converted as specified; the next character conflicts
with a character in the control string that it is supposed to match; or the
next character fails to appear in a given character set. For whatever
reason, when scanf stops reading an input field, the next input field is
considered to begin at the first unread character. The conflicting
character, if there is one, is considered unread and is the first character
of the next input field or the first character in subsequent read operations
on stdin.

Table   R.5 Type Characters for scanf

╓┌──────────────────────────┌──────────────────────────┌─────────────────────►
Character                  Type of Input Expected     Type of Argument
─────────────────────────────────────────────────────────────────────────────
d                          Decimal integer            Pointer to int

o                          Octal integer              Pointer to int

x                          Hexadecimal integer(1)     Pointer to int

Character                  Type of Input Expected     Type of Argument
─────────────────────────────────────────────────────────────────────────────

i                          Decimal, hexadecimal, or   Pointer to int
                            octal integer

u                          Unsigned decimal integer   Pointer to unsigned int

U                          Unsigned decimal integer   Pointer to unsigned lon

e, E                       Floating-point value       Pointer to float
f                          consisting of an optional
g, G                       sign (+ or -), a series
                            of one or more decimal
                            digits containing a
                            decimal point, and an
                            optional exponent ("e" or
                            "E") followed by an
                            optionally signed integer
                            value.

Character                  Type of Input Expected     Type of Argument
─────────────────────────────────────────────────────────────────────────────

c                          Character. White-space     Pointer to char
                            characters that are
                            ordinarily skipped are
                            read when c is specified;
                            to read the next
                            non-white-space
                            character, use  %1s.

s                          String                     Pointer to character
                                                        array large enough for
                                                        input field plus a
                                                        terminating null
                                                        character ('\0'), which
                                                        is automatically
                                                        appended.

n                          No input read from stream  Pointer to int, into
                            or buffer.                 which is stored the
Character                  Type of Input Expected     Type of Argument
─────────────────────────────────────────────────────────────────────────────
                            or buffer.                 which is stored the
                                                        number of characters
                                                        successfully read from
                                                        the stream or buffer up
                                                        to that point in the
                                                        current call to scanf.

p                          Value in the form xxxx:    Pointer to far pointer
                            yyyy, where the digits x   void
                            and y are uppercase
                            hexadecimal digits.

─────────────────────────────────────────────────────────────────────────────



1     Since the input for a %x format specifier is always interpreted as a
hexadecimal number, the input should     not include a leading 0x. (If 0x is
included, the 0 is interpreted as a hexadecimal input value.)



Return Value

The scanf function returns the number of fields that were successfully
converted and assigned. The return value may be less than the number
requested in the call to scanf. The return value does not include fields
that were read but not assigned.

The return value is EOF if the end-of-file or end-of-string is encountered
in the first attempt to read a character.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fscanf, printf, sscanf, vfprintf, vprintf, vsprintf


Example

    /* SCANF.C: This program receives formatted input using scanf. */
    #include <stdio.h>

    void main()
    {
        int   i;
        float fp;
        char  c, s[81];
        int   result;

        printf( "Enter an integer, a floating-point number, "
                "a character and a string:\n" );
        result = scanf( "%d %f %c %s", &i, &fp, &c, s );

        printf( "\nThe number of fields input is %d\n", result );
        printf( "The contents are: %d %f %c %s\n", i, fp, c, s );
    }


Output



    Enter an integer, a floating-point number, a character and a string:
    71
    98.6
    h
    White space stops input

    The number of fields input is 4
    The contents are: 71 98.599998 h White





_scrolltextwindow
────────────────────────────────────────────────────────────────────────────


Description

Scrolls the text in a text window.

    #include <graph.h>

    void _far _scrolltextwindow( short lines );

lines                             Number of lines to scroll


Remarks

The _scrolltextwindow function scrolls the text in a text window (previously
defined by the _settextwindow function). The lines argument specifies the
number of lines to scroll. A positive value of lines scrolls the window up
(the usual direction); a negative value scrolls the window down. Specifying
a number larger than the height of the current text window is equivalent to
calling _clearscreen( _GWINDOW ). A value of 0 for lines has no effect on
the text.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_gettextposition,  _outmem,  _outtext,  _settextposition,  _settextwindow


Example

    /* SCRTXWIN.C: This program displays text in text windows and then
    * scrolls, inserts, and deletes lines.
    */

    #include <stdio.h>
    #include <conio.h>
    #include <graph.h>

    void deleteline( void );
    void insertline( void );
    void status( char *msg );

    void main()
    {
        short row;
        char  buf[40];

        /* Set up screen for scrolling, and put text window around scroll area.
*/
        _settextrows( 25 );
        _clearscreen( _GCLEARSCREEN );

    for( row = 1; row <= 25; row++ )
        {
        _settextposition( row, 1 );
        sprintf( buf, "Line %c             %2d", row + 'A' - 1, row );
        _outtext( buf );
        }
        getch();
        _settextwindow( 1, 1, 25, 10 );

        /* Delete some lines. */
        _settextposition( 11, 1 );
        for( row = 12; row < 20; row++ )
        deleteline();
        status( "Deleted 8 lines" );

        /* Insert some lines. */
        _settextposition( 5, 1 );
        for( row = 1; row < 6; row++ )
        insertline();
        status( "Inserted 5 lines" );

        /* Scroll up and down. */
        _scrolltextwindow( -7 );
        status( "Scrolled down 7 lines" );
        _scrolltextwindow( 5 );
        status( "Scrolled up 5 lines" );
        _setvideomode( _DEFAULTMODE );
    }

    /* Delete lines by scrolling them off the top of the current text window.
    * Save and restore original window.
    */
    void deleteline()
    {
        short left, top, right, bottom;
        struct rccoord rc;

        _gettextwindow( &top, &left, &bottom, &right );
        rc = _gettextposition();
        _settextwindow( rc.row, left, bottom, right );
        _scrolltextwindow( _GSCROLLUP );
        _settextwindow( top, left, bottom, right );
        _settextposition( rc.row, rc.col );
    }

    /* Insert some lines by scrolling in blank lines from the top of the
    * current text window. Save and restore original window.
    */
    void insertline()
    {
        short left, top, right, bottom;
        struct rccoord rc;

        _gettextwindow( &top, &left, &bottom, &right );
        rc = _gettextposition();
        _settextwindow( rc.row, left, bottom, right );
        _scrolltextwindow( _GSCROLLDOWN );
        _settextwindow( top, left, bottom, right );
        _settextposition( rc.row, rc.col );
    }

    /* Display and clear status in its own window. */
    void status( char *msg )
    {
        short left, top, right, bottom;
        struct rccoord rc;

        _gettextwindow( &top, &left, &bottom, &right );
        _settextwindow( 1, 50, 2, 80 );
        _outtext( msg );
        getch();
        _clearscreen( _GWINDOW );
        _settextwindow( top, left, bottom, right );
    }





_searchenv
────────────────────────────────────────────────────────────────────────────


Description

Searches for a file using environment paths.

    #include <stdlib.h>

    void _searchenv( char *filename, char *varname, char *pathname );

filename                          Name of file to search for

varname                           Environment to search

pathname                          Buffer to store complete path


Remarks

The _searchenv routine searches for the target file in the specified domain.
The varname variable can be any environment variable which specifies a list
of directory paths, such as PATH, LIB, INCLUDE, or other user-defined
variables. It is most often PATH, which searches for filename on all paths
specified in the PATH variable. The _searchenv function is case-sensitive,
so the varname variable should match the case of the environment variable.

The routine first searches for the file in the current working directory. If
it doesn't find the file, it next looks through the directories specified by
the environment variable.

If the target file is found in one of the directories, the newly created
path is copied into the buffer pointed to by pathname. You must ensure that
there is sufficient space for the constructed path name. If the filename
file is not found, pathname will contain an empty null-terminated string.


Return Value

The _searchenv function does not return a value.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

getenv, putenv


Example

    /* SEARCHEN.C: This program searches for a file in a directory
    * specified by an environment variable.
    */

    #include <stdlib.h>
    #include <stdio.h>

    void main()
    {
        char pathbuffer[_MAX_PATH];
        char searchfile[] = "CL.EXE";
        char envvar[] = "PATH";
        /* Search for file in PATH environment variable: */
        _searchenv( searchfile, envvar, pathbuffer );
        if( *pathbuffer != '\0' )
        printf( "Path for %s: %s\n", searchfile, pathbuffer );
        else
        printf( "%s not found\n", searchfile );
    }


Output



    Path for CL.EXE: C:\BIN\CL.EXE





segread
────────────────────────────────────────────────────────────────────────────


Description

Gets the current values of segment registers.

    #include <dos.h>

    void segread( struct SREGS *segregs );

segregs                           Segment-register values


Remarks

The segread function fills the structure pointed to by segregs with the
current contents of the segment registers. The SREGS union is described in
the reference section for int86x. This function is intended to be used with
the intdosx and int86x functions to retrieve segment-register values for
later use.


Return Value

None.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

FP_SEG, intdosx, int86x


Example

    /* SEGREAD.C: This program gets the current segment values with segread.
    */

    #include <dos.h>
    #include <stdio.h>

    void main()
    {
        struct   SREGS segregs;
        unsigned cs, ds, es, ss;

        /* Read the segment register values */
        segread( &segregs );
        cs = segregs.cs;
        ds = segregs.ds;
        es = segregs.es;
        ss = segregs.ss;
        printf( "CS = 0x%.4x    DS = 0x%.4x    ES = 0x%.4x    SS = 0x%.4x\n",
                cs, ds, es, ss );
    }


Output



    CS = 0x0047    DS = 0x0067    ES = 0x0067    SS = 0x0067

    CS = 0x2bcc    DS = 0x2ce8    ES = 0x2ba3    SS = 0x2ce8





_selectpalette
────────────────────────────────────────────────────────────────────────────


Description

Selects a graphics palette.

    #include <graph.h>

    short _far _selectpalette( short number );

number                            Palette number


Remarks

The _selectpalette function works only under the video modes _MRES4COLOR and
_MRESNOCOLOR. A palette consists of a selectable background color (Color 0)
and three set colors. Under the _MRES4COLOR mode, the number argument
selects one of the four predefined palettes shown in Table R.6.

Table   R.6 _MRES4COLOR Palette Colors

╓┌───────────────┌─────────────┌───────────────┌─────────────────────────────╖
────────────────────────────────────────────────────────────────────────────

Palette Number  Color 1       Color 2         Color 3
────────────────────────────────────────────────────────────────────────────
Palette Number  Color 1       Color 2         Color 3

0               Green         Red             Brown

1               Cyan          Magenta         Light gray

2               Light green   Light red       Yellow

3               Light cyan    Light magenta   White

────────────────────────────────────────────────────────────────────────────



The _MRESNOCOLOR video mode is used with black-and-white displays, producing
palettes consisting of various shades of gray. It will also produce color
when used with a color display. The number of palettes available depends
upon whether a CGA or EGA hardware package is employed. Under a CGA
configuration, only the two palettes shown in Table R.7 are available.

Table   R.7 _MRESNOCOLOR Mode CGA Palette Colors

╓┌───────────────┌─────────────┌──────────────┌──────────────────────────────╖
────────────────────────────────────────────────────────────────────────────

Palette         Color 1       Color 2        Color 3
Number

0               Blue          Red            Light gray

1               Light blue    Light red      White

────────────────────────────────────────────────────────────────────────────



Under the EGA configuration, the three palettes shown in Table R.8 are
available in the _MRESNOCOLOR video mode.

Table   R.8 _MRESNOCOLOR Mode EGA Palette Colors

╓┌───────────────┌─────────────┌─────────────┌───────────────────────────────╖
────────────────────────────────────────────────────────────────────────────

Palette         Color 1       Color 2       Color 3
Number

0               Green         Red           Brown

1               Light green   Light red     Yellow

2               Light cyan    Light red     Yellow

────────────────────────────────────────────────────────────────────────────



Note that with an EGA in _MRESNOCOLOR video mode, Palette 3 is identical to
Palette 1.


Return Value

The function returns the value of the previous palette. There is no error
return.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getvideoconfig,  _setbkcolor,  _setvideomode


Example

    /* SELPAL.C: This program changes the current CGA palette. */

    #include <stdio.h>
    #include <stdlib.h>
    #include <conio.h>
    #include <graph.h>

    long bkcolor[8] = { _BLACK,  _BLUE,     _GREEN,  _CYAN,
                        _RED,    _MAGENTA,  _BROWN,  _WHITE };
    char *bkname [] = { "BLACK", "BLUE",    "GREEN", "CYAN",
                        "RED",   "MAGENTA", "BROWN", "WHITE" };
    void main()
    {
        int i, j, k;

        if ( !_setvideomode( _MRES4COLOR ) )
        {
        printf( "No palettes available" );
        exit( 1 );
        }
        for( i = 0; i < 4; i++ )                    /* Palette loop          */
        {
            _selectpalette( i );
            for( k = 0; k < 8; k++ )                /* Background color loop */
            {
                _clearscreen( _GCLEARSCREEN );
                _setbkcolor( bkcolor[k] );
                _settextposition( 1, 1 );
                printf( "Background: %s\tPalette: %d", bkname[k], i );
                for( j = 1; j < 4; j++ )            /* Foreground color loop */
                {
                    _setcolor( j );
                    _ellipse( _GFILLINTERIOR, 100, j * 30, 220, 80 + (j * 30)
);
                }
                getch();
            }
        }
        _setvideomode( _DEFAULTMODE );
    }





_setactivepage
────────────────────────────────────────────────────────────────────────────


Description

Sets the active page.

    #include <graph.h>

    short _far _setactivepage( short  page );

page                              Memory page number


Remarks

For hardware and mode configurations with enough memory to support multiple
screen pages,  _setactivepage specifies the area in memory in which graphics
output is written. The page argument selects the current active page. The
default page number is 0.

Screen animation can be done by alternating the graphics pages displayed.
Use the _setvisualpage function to display a completed graphics page while
executing graphics statements in another active page.

These functions can also be used to control text output if you use the text
functions _gettextcursor,  _settextcursor,  _outtext,  _settextposition,
_gettextposition,  _settextcolor,  _gettextcolor,  _settextwindow, and
_wrapon instead of the standard C-language I/O functions.

The CGA hardware configuration has only 16K of RAM available to support
multiple video pages, and only in the text mode. The EGA and VGA
configurations may be equipped with up to 256K of RAM for multiple video
pages in graphics mode.


Return Value

If successful, the function returns the page number of the previous active
page. If the function fails, it returns a negative value.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getactivepage,  _getvisualpage,  _setvisualpage


Example

    /* PAGE.C illustrates video page functions including:
    *      _getactivepage  _getvisualpage  _setactivepage  _setvisualpage
    */

    #include <conio.h>
    #include <graph.h>
    #include <stdlib.h>

    void main()
    {
        short  oldvpage, oldapage, page, row, col, line;
        struct videoconfig vc;
        char   buf[80];

        _getvideoconfig( &vc );
        if( vc.numvideopages < 4 )
            exit( 1 );              /* Fail for OS/2 or monochrome */
        oldapage  = _getactivepage();
        oldvpage  = _getvisualpage();
        _displaycursor( _GCURSOROFF );

        /* Draw arrows in different place on each page. */
        for( page = 1; page < 4; page++ )
        {
        _setactivepage( page );
        _settextposition( 12, 16 * page );
        _outtext( ">>>>>>>>" );
        }

        while( !kbhit() )
        /* Cycle through pages 1 to 3 to show moving image. */
        for( page = 1; page < 4; page++ )
            _setvisualpage( page );
        getch();

        /* Restore original page (normally 0) to restore screen. */
        _setactivepage( oldapage );
        _setvisualpage( oldvpage );
        _displaycursor( _GCURSORON );
    }





_setbkcolor
────────────────────────────────────────────────────────────────────────────


Description

Sets the current background color.

    #include <graph.h>

    long _far _setbkcolor( long color );

color                             Desired color


Remarks

The _setbkcolor function sets the current background color to the color
value color.

In a color text mode (such as _TEXTC80), _setbkcolor accepts (and
_getbkcolor returns) a color index. The value for the default colors is
given in a table in the description of the _settextcolor function. For
example, _setbkcolor(2L) sets the background color to color index 2. The
actual color displayed depends on the palette mapping for color index 2. The
default is green in a color text mode.

In a color graphics mode (such as _ERESCOLOR), _setbkcolor accepts (and
_getbkcolor returns) a color value. The value for the background color is
given by the manifest constants defined in the GRAPH.H include file. For
example, _setbkcolor( _GREEN) sets the background color in a graphics mode
to green. These manifest constants are provided as a convenience in defining
and manipulating the most common colors. The actual range of colors is, in
general, much greater.

In general, whenever an argument is long, it refers to a color value, and
whenever it is short, it refers to a color index. The two exceptions are
_setbkcolor and _getbkcolor.

Since the background color is color index 0, the _remappalette function will
act identically to the _setbkcolor function. Unlike _remappalette, however,
_setbkcolor does not require an EGA or VGA environment.

In a text mode, the _setbkcolor function does not affect anything already
appearing on the display; only the subsequent output is affected. In a
graphics mode, it immediately changes all background pixels.


Return Value

In text modes, _setbkcolor returns the color index of the old background
color. In graphics modes, _setbkcolor returns the old color value of color
index 0. There is no error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_getbkcolor,  _remappalette,  _selectpalette


Example

See the example for _getcolor.



setbuf
────────────────────────────────────────────────────────────────────────────


Description

Controls stream buffering.

    #include <stdio.h>

    void setbuf( FILE *stream, char *buffer );

stream                            Pointer to FILE structure

buffer                            User-allocated buffer


Remarks

The setbuf function allows the user to control buffering for stream. The
stream argument must refer to an open file that has not been read or
written. If the buffer argument is NULL, the stream is unbuffered. If not,
the buffer must point to a character array of length BUFSIZ, where BUFSIZ is
the buffer size as defined in STDIO.H. The user-specified buffer, instead of
the default system-allocated buffer for the given stream, is used for I/O
buffering.

The stderr and (in DOS only) stdaux streams are unbuffered by default, but
may be assigned buffers with setbuf.

The setbuf function has been subsumed by the setvbuf function, which should
be the preferred routine for new code. The setbuf function is retained for
compatibility with existing code.


Return Value

None.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

fclose, fflush, fopen, setvbuf


Example

    /* SETBUF.C: This program first opens files named DATA1 and DATA2.
    * Then it uses setbuf to give DATA1 a user-assigned buffer
    * and to change DATA2 so that it has no buffer.
    */

    #include <stdio.h>

    void main()
    {
        char buf[BUFSIZ];
        FILE *stream1, *stream2;

        if( ((stream1 = fopen( "data1", "a" )) != NULL) &&
            ((stream2 = fopen( "data2", "w" )) != NULL) )
        {
        /* "stream1" uses user-assigned buffer: */
        setbuf( stream1, buf );
        printf( "stream1 set to user-defined buffer at: %Fp\n", buf );

        /* "stream2" is unbuffered              */
        setbuf( stream2, NULL );
        printf( "stream2 buffering disabled\n" );
        fcloseall();
        }


Output



    stream1 set to user-defined buffer at: 0298:0DF2
    stream2 buffering disabled





_setcliprgn
────────────────────────────────────────────────────────────────────────────


Description

Sets the clipping region for graphics.

    #include <graph.h>

    void _far _setcliprgn( short x1, short y1, short x2, short y2 );

x1, y1                            Upper-left corner of clip region

x2, y2                            Lower-right corner of clip region


Remarks

The _setcliprgn function limits the display of subsequent graphics output
and font text output to an area of the screen called the "clipping region."
The physical points (x1, y1) and (x2, y2) are the diagonally opposed sides
of a rectangle that defines the clipping region. This function does not
change the view coordinate system. Rather, it merely masks the screen.

Note that the _setcliprgn function affects graphics and font text output
only. To mask the screen for text output, use the _settextwindow function.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_settextwindow,  _setvieworg,  _setviewport,  _setwindow


Example

    /* SCLIPRGN.C */
    #include <stdlib.h>
    #include <conio.h>
    #include <graph.h>

    void main()
    {
        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        /* Set clip region, then draw and ellipse larger than the region. */
        _setcliprgn( 0, 0, 200, 125 );
        _ellipse( _GFILLINTERIOR, 80, 50, 240, 190 );

    getch();
        _setvideomode( _DEFAULTMODE );
    }





_setcolor
────────────────────────────────────────────────────────────────────────────


Description

Sets the current color.

    #include <graph.h>

    short _far _setcolor( short color );

color                             Desired color index


Remarks

The _setcolor function sets the current color index to color. The color
parameter is masked but always within range. The following graphics
functions use the current color:  _arc,  _ellipse,  _floodfill,  _lineto,
_outgtext,  _pie,  _rectangle, and  _setpixel.

The _setcolor function accepts an int value as an argument. It is a color
index.

The default color index is the highest numbered color index in the current
palette.

Note that the _setcolor function does not affect the output of the
presentation-graphics functions.


Return Value

This function returns the previous color. If the function fails (e.g., if
used in a text mode), it returns  -1.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_arc functions,  _ellipse functions,  _floodfill,  _getcolor,  _lineto
functions,  _outgtext,  _pie functions,  _rectangle functions,
_selectpalette,  _setpixel functions


Example

    /* GPIXEL.C: This program assigns different colors to randomly
    * selected pixels.
    */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void main()
    {
        short xvar, yvar;
        struct videoconfig vc;

    /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );
        _getvideoconfig( &vc );

        /* Draw filled ellipse to turn on certain pixels. */
        _ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6,
                                vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5
                                                );

        /* Draw random pixels in random colors... */
        while( !kbhit() )
        {
        /* ...but only if they are already on (inside the ellipse). */
        xvar = rand() % vc.numxpixels;
        yvar = rand() % vc.numypixels;
        if( _getpixel( xvar, yvar ) != 0 )
        {
            _setcolor( rand() % 16 );
            _setpixel( xvar, yvar );
        }
        }

        getch();          /* Throw away the keystroke. */
        _setvideomode( _DEFAULTMODE );
    }





_setfillmask
────────────────────────────────────────────────────────────────────────────


Description

Sets the fill mask.

    #include <graph.h>

    void _far _setfillmask( unsigned char _far *mask );

mask                              Mask array


Remarks

The _setfillmask function sets the current fill mask, which determines the
fill pattern. The mask is an 8-by-8 array of bits in which each bit
represents a pixel. A 1 bit sets the corresponding pixel to the current
color, while a 0 bit leaves the pixel unchanged. The pattern is repeated
over the entire fill area.

If no fill mask is set (mask is NULL─the default), only the current color is
used in fill operations.


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_ellipse functions,  _floodfill,  _getfillmask,  _pie functions,  _rectangle
functions


Example

    /* GFILLMSK.C: This program illustrates _getfillmask and _setfillmask. */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void ellipsemask( short x1, short y1, short x2, short y2, char _far
*newmask );

    unsigned char mask1[8] = { 0x43, 0x23, 0x7c, 0xf7, 0x8a, 0x4d, 0x78, 0x39
};
    unsigned char mask2[8] = { 0x18, 0xad, 0xc0, 0x79, 0xf6, 0xc4, 0xa8, 0x23
};
    char oldmask[8];

    void main()
    {
        int loop;

        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXRESMODE ) )
        exit( 1 );

        /* Set first fill mask and draw rectangle. */
        _setfillmask( mask1 );
        _rectangle( _GFILLINTERIOR, 20, 20, 100, 100 );
        getch();

        /* Call routine that saves and restores mask. */
        ellipsemask( 60, 60, 150, 150, mask2 );
        getch();

        /* Back to original mask. */
        _rectangle( _GFILLINTERIOR, 120, 120, 190, 190 );
        getch();

        _setvideomode( _DEFAULTMODE );
    }

    /* Draw an ellipse with a specified fill mask. */
    void ellipsemask( short x1, short y1, short x2, short y2, char _far
*newmask )
    {
        unsigned char savemask[8];

        _getfillmask( savemask );                    /* Save mask         */
        _setfillmask( newmask );                     /* Set new mask      */
        _ellipse( _GFILLINTERIOR, x1, y1, x2, y2 );  /* Use new mask      */
        _setfillmask( savemask );                    /* Restore original  */
    }






_setfont
────────────────────────────────────────────────────────────────────────────


Description

Finds a single font.

    #include <graph.h>

    short _far _setfont( unsigned char _far *options );

options                           String describing font characteristics


Remarks

The _setfont function finds a single font, from the set of registered fonts,
that has the characteristics specified by the options string. If a font is
found, it is made the current font. The current font is used in all
subsequent calls to the _outgtext function. There can be only one active
font at any time.

The options string is a set of characters that specifies the desired
characteristics of the font. The _setfont function searches the list of
registered fonts for a font matching the specified characteristics.

The characteristics that may be specified in the options string are shown in
the list below. Characteristics specified in the options string are not
case- or position-sensitive.

Characteristic                    Description
────────────────────────────────────────────────────────────────────────────
t'fontname'                       Typeface.

hx                                Character height, where x is the number
                                    of pixels.

wy                                Character width, where y is the number
                                    of pixels.

f                                 Find only a fixed-space font (should not
                                    be used with the
                                    p characteristic).

p                                 Find only a proportionally spaced font
                                    (should not be used with the f
                                    characteristic).

v                                 Find only a vector font (should not be
                                    used with the r
                                    characteristic).

r                                 Find only a raster-mapped (bit-mapped)
                                    font (should not be used with the v
                                    characteristic).

b                                 Select a best fit font.

nx                                Select font number x, where x is less
                                    than or equal to the value returned by
                                    the _registerfonts function. Use this
                                    option to "step through" an entire set
                                    of fonts.

You can request as many options as desired, except with nx, which should be
used alone. If mutually exclusive options are requested (such as the pair
f/p or r/v), the _setfont function ignores them. There is no error detection
for incompatible parameters used with nx.

Options can be separated by blanks in the options string. Any other
character is ignored by _setfont.

The t (the typeface specification) in options is specified as a "t" followed
by fontname in single quotes. Choose fontname from the following list:

Fontname                          Description
────────────────────────────────────────────────────────────────────────────
Courier                           Fixed-width bit-mapped font with serifs

Helv                              Sans serif proportional bit-mapped font

Tms Rmn                           Proportional bit-mapped font with serifs

Script                            Proportional vector-mapped font of
                                    slanted characters formed from nearly
                                    continuous lines

Modern                            Proportional vector-mapped font without
                                    serifs

Roman                             Proportional vector-mapped font with
                                    serifs

A b in the options field causes the _setfont routine to automatically select
the "best fit" font that matches the other characteristics you have
specified. If the b parameter is spec-ified and at least one font is
registered, _setfont will always be able to set a font and will return 0 to
indicate success.

In selecting a font, the _setfont routine uses the following precedence
(rated from highest precedence to lowest):


    1.  Pixel height

    2.  Typeface

    3.  Pixel width

    4.  Fixed or proportional font


You can also specify a pixel width and height for fonts. If a nonexistent
value is chosen for either, and the b option is specified, the _setfont
function will chose the closest match. A smaller font size has precedence
over a larger size. If _setfont requests Helv 12 with best fit, and only
Helv 10 and Helv 14 are available, _setfont will select Helv 10.

If a nonexistent value is chosen for pixel height and width, the _setfont
function will apply a magnification factor to a vector-mapped font to obtain
a suitable font size. This automatic magnification does not apply if the r
(raster-mapped font) option is specified, or if a specific typeface is
requested and no best fit (b) option is specified.

If you specify the nx parameter, _setfont will ignore any other specified
options and supply only the font number corresponding to x.

Note that the font functions affect only the output from the font output
function _outgtext; no other C run-time output functions are affected by
font usage.


Return Value

The _setfont function returns a 0 to indicate success and a -1 to indicate
an error. An error occurs if a request for a specific font fails and the b
option was not specified, or if fonts have not yet been registered.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getfontinfo,  _getgtextextent,  _outgtext,  _registerfonts,
_unregisterfonts


Example

See the example for _outgtext.



_setgtextvector
────────────────────────────────────────────────────────────────────────────


Description

Changes the orientation of font text output.

    #include <graph.h>

    struct xycoord _far _setgtextvector( short x, short y );

x, y                              Integers specifying font rotation


Remarks

The _setgtextvector function sets the current orientation for font text
output to the vector specified by x and y. The current orientation is used
in calls to the _outgtext function.

The values of x and y define the vector which determines the direction of
rotation of font text on the screen. The text-rotation options are shown
below:

(x, y)                            Text Orientation
────────────────────────────────────────────────────────────────────────────
(0, 0)                            Unchanged

(1, 0)                            Horizontal text (default)

(0, 1)                            Rotated 90 degrees counterclockwise

(-1, 0)                           Rotated 180 degrees

(0, -1)                           Rotated 270 degrees counterclockwise

If other values are input, only the sign of the input is used. For example,
(-3, 0) is interpreted as (-1, 0).


Return Value

The _setgtextvector function returns the previous vector in a structure of
xycoord type. If you pass the _setgtextvector function the values (0, 0),
the function returns the current vector values in the xycoord structure.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getfontinfo,  _getgtextextent,  _grstatus,  _outgtext,  _registerfonts,
_setfont, _unregisterfonts


Example

See the example for _outgtext.



setjmp
────────────────────────────────────────────────────────────────────────────


Description

Saves the current state of the program.

    #include <setjmp.h>

    int setjmp( jmp_buf env );

env                               Variable in which environment is stored


Remarks

The setjmp function saves a stack environment that can be subsequently
restored using longjmp. Used together this way, setjmp and longjmp provide a
way to execute a "non-local goto." They are typically used to pass execution
control to error-handling or recovery code in a previously called routine
without using the normal calling or return conventions.

A call to setjmp causes the current stack environment to be saved in env. A
subsequent call to longjmp restores the saved environment and returns
control to the point just after the corresponding setjmp call. All variables
(except register variables) accessible to the routine receiving control
contain the values they had when setjmp was called.


Return Value

The setjmp function returns 0 after saving the stack environment. If setjmp
returns as a result of a longjmp call, it returns the value argument of
longjmp, or, if the value argument of longjmp is 0, setjmp returns 1. There
is no error return.


Compatibility

    ANSI   DOS   OS/2   UNIX   XENIX



See Also

longjmp


Example

See the example for _fpreset.





_setlinestyle
────────────────────────────────────────────────────────────────────────────


Description

Sets the line style.

    #include <graph.h>

    void _far _setlinestyle( unsigned short mask );

mask                              Desired line-style mask


Remarks

Some graphics routines ( _lineto and _rectangle) draw straight lines on the
screen. The type of line is controlled by the current line-style mask.

The _setlinestyle function selects the mask used for line drawing. The mask
argument is a 16-bit array, where each bit represents a pixel in the line
being drawn. If a bit is 1, the corresponding pixel is set to the color of
the line (the current color). If a bit is 0, the corresponding pixel is left
unchanged. The template is repeated for the entire length of the line.

The default mask is 0xFFFF (a solid line).


Return Value

None.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getlinestyle,  _lineto functions,  _rectangle functions


Example

See the example for _getlinestyle.



setlocale
────────────────────────────────────────────────────────────────────────────


Description

Defines the locale.

    #include <locale.h>

    char *setlocale( int category, const char *locale );

category                          Category affected by locale

locale                            Name of the locale that will control the
                                    specified category


Remarks

The setlocale function sets the categories specified by category to the
locale specified by locale. The "locale" refers to the locality (country)
for which certain aspects of your program can be customized. Some
locale-dependent aspects include the formatting of dates and the display
format for monetary values.

The setlocale function is used to set or get the program's current entire
locale or simply portions of the locale information. The category argument
specifies which portion of a program's locale information will be used. The
manifest constants used for the category argument are listed below:

Category                          Parts of Program Affected
────────────────────────────────────────────────────────────────────────────
LC_ALL                            All categories listed below.

LC_COLLATE                        The strcoll and strxfrm functions.

LC_CTYPE                          The character-handling functions (except
                                    for isdigit and isxdigit, which are
                                    unaffected).

LC_MONETARY                       Monetary formatting information returned
                                    by the localeconv function.

LC_NUMERIC                        Decimal point character for the
                                    formatted output routines (such as
                                    printf), for the data conversion
                                    routines, and for
                                    the nonmonetary formatting information
                                    returned by the
                                    localeconv function.

LC_TIME                           The strftime function.

The locale argument is a pointer to a string that specifies the name of the
locale. If locale points to an empty string, the locale is the
implementation-defined native environment. A value of "C" specifies the
minimal ANSI conforming environment for C translation. This is the only
locale supported in Microsoft C, version 6.0.

If the locale argument is a null pointer, setlocale returns a pointer to the
string associated with the category of the program's locale. The program's
current locale setting is not changed.


Return Value

If a valid locale and category are given, _setlocale returns a pointer to
the string associated with the specified category for the new locale. If the
locale or category is invalid, the setlocale function returns a null pointer
and the program's current locale settings are not changed.

The pointer to a string returned by setlocale can be used in subsequent
calls to restore that part of the program's locale information. Later calls
to setlocale will overwrite the string.


Compatibility

    ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

localeconv, strcoll, strftime, strxfrm





setmode
────────────────────────────────────────────────────────────────────────────


Description

Sets the file translation mode.

#include <fcntl.h>

#include <io.h>                   Required only for function declarations

    int setmode ( int handle, int mode );

handle                            File handle

mode                              New translation mode


Remarks

The setmode function sets to mode the translation mode of the file given by
handle. The mode must be one of the following manifest constants:

Constant                          Meaning
────────────────────────────────────────────────────────────────────────────
O_TEXT                            Sets text (translated) mode.
                                    Carriage-return-line-feed (CR-LF)
                                    combinations are translated into a
                                    single line-feed (LF) character on
                                    input. Line-feed characters are
                                    translated into CR-LF combinations on
                                    output.

O_BINARY                          Sets binary (untranslated) mode. The
                                    above translations are suppressed.

The setmode function is typically used to modify the default translation
mode of stdin, stdout, stderr, stdaux, and stdprn, but can be used on any
file. If setmode is applied to the file handle for a stream, the setmode
function should be called before any input or output operations are
performed on the stream.


Return Value

If successful, setmode returns the previous translation mode. A return value
of -1 indicates an error, and errno is set to one of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
EBADF                             Invalid file handle

EINVAL                            Invalid mode argument (neither O_TEXTnor
                                    O_BINARY )


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

creat, fopen, open


Example

    /* SETMODE.C: This program uses setmode to change stdin from text
    * mode to binary mode.
    */

    #include <stdio.h>
    #include <fcntl.h>
    #include <io.h>

    void main()
    {
        int result;

        /* Set "stdin" to have binary mode: */
        result = setmode( fileno( stdin ), O_BINARY );
        if( result == -1 )
        perror( "Cannot set mode" );
        else
        printf( "'stdin' successfully changed to binary mode\n" );
    }


Output


Output



    'stdin' successfully changed to binary mode





_setpixel Functions
────────────────────────────────────────────────────────────────────────────


Description

Set a pixel to the current color.

    #include <graph.h>

    short _far _setpixel( short x, short y );

    short _far _setpixel_w( double wx, double wy );

x, y                              Target pixel

wx, wy                            Target pixel


Remarks

The _setpixel and the _setpixel_w functions set a pixel at a specified
location to the current color.

The _setpixel function sets the pixel at the view-coordinate point (x, y) to
the current color.

The _setpixel_w function sets the pixel at the window-coordinate point (wx,
wy) to the current color.


Return Value

The function returns the previous value of the target pixel. If the function
fails (for example, the point lies outside of the clipping region), it will
return -1.


Compatibility

▼ ANSI   DOS  ▼ OS/2  ▼ UNIX  ▼ XENIX



See Also

_getpixel functions,  _setcolor


Example

    /* GPIXEL.C: This program assigns different colors to randomly
    * selected pixels.
    */

    #include <conio.h>
    #include <stdlib.h>
    #include <graph.h>

    void main()
    {
        short xvar, yvar;
        struct videoconfig vc;


        /* Find a valid graphics mode. */
        if( !_setvideomode( _MAXCOLORMODE ) )
        exit( 1 );
        _getvideoconfig( &vc );

        /* Draw filled ellipse to turn on certain pixels. */
        _ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6,
                                vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5
                                                );

        /* Draw random pixels in random colors... */
        while( !kbhit() )
        {
        /* ...but only if they are already on (inside the ellipse). */
        xvar = rand() % vc.numxpixels;
        yvar = rand() % vc.numypixels;
        if( _getpixel( xvar, yvar ) != 0 )
        {
            _setcolor( rand() % 16 );
            _setpixel( xvar, yvar );
        }
        }

        getch();          /* Throw away the keystroke. */
        _setvideomode( _DEFAULTMODE );
    }





_settextcolor
────────────────────────────────────────────────────────────────────────────


Description

Sets the current text color.

    #include <graph.h>

    short _far _settextcolor( short index );

index                             Desired color index


Remarks

The _settextcolor function sets the current text color to the color index
specified by index. The default text color is the same as the maximum color
index.

The _settextcolor routine sets the color for the _outtext and _outmem
functions only. It does not affect the color of the printf function or the
color of text output with the _outgtext font routine. Use the _setcolor
function to change the color of font output.

In text color mode, you can specify a color index in the range 0 -31. The
colors in the range 0 -15 are interpreted as normal (non-blinking). The
normal color range is defined below:

╓┌───────┌─────────┌──────┌──────────────────────────────────────────────────╖
Index   Color     Index  Color
────────────────────────────────────────────────────────────────────────────
0       Black     8      Dark gray

1       Blue      9      Light blue

2       Green     10     Light green

3       Cyan      11     Light cyan

4       Red       12     Light red
Index   Color     Index  Color
────────────────────────────────────────────────────────────────────────────
4       Red       12     Light red

5       Magenta   13     Light magenta

6       Brown     14     Yellow

7       White     15     Bright white



Blinking is selected by adding 16 to the normal color value.

In every text mode, including monochrome, _getvideoconfig returns the value
32 for the number of available colors. The value 32 indicates the range of
values (0 -31) accepted by the _settextcolor function. This includes sixteen
normal colors (0 -15) and sixteen blinking colors (16 -31). Monochrome text
mode has fewer unique display attributes, so some color values are
redundant. However, because blinking is selected in the same manner,
monochrome text mode has the same range (0 -31) as other text modes.


Return Value

The function returns the color index of the previous text color. There is no
error return.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_gettextcolor,  _outtext


Example

    /* OUTTXT.C: This example illustrates text output functions:
    *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
    *    _settextcolor   _setbkcolor   _settextposition
    */

    #include <conio.h>
    #include <stdio.h>
    #include <graph.h>

    char buffer [80];

    void main()
    {

        /* Save original foreground, background, and text position */
        short blink, fgd, oldfgd;
        long  bgd, oldbgd;
        struct rccoord oldpos;

        /* Save original foreground, background, and text position. */
        oldfgd = _gettextcolor();
        oldbgd = _getbkcolor();
        oldpos = _gettextposition();
        _clearscreen( _GCLEARSCREEN );

        /* First time no blink, second time blinking. */
        for( blink = 0; blink <= 16; blink += 16 )
        {
        /* Loop through 8 background colors. */
        for( bgd = 0; bgd < 8; bgd++ )
        {
            _setbkcolor( bgd );
            _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
            _settextcolor( 7 );
            sprintf(buffer, "Back: %d Fore:", bgd );
            _outtext( buffer );

    /* Loop through 16 foreground colors. */
            for( fgd = 0; fgd < 16; fgd++ )
            {
                _settextcolor( fgd + blink );
                sprintf( buffer, " %2d ", fgd + blink );
                _outtext( buffer );
            }
        }
        }
        getch();

        /* Restore original foreground, background, and text position. */
        _settextcolor( oldfgd );
        _setbkcolor( oldbgd );
        _clearscreen( _GCLEARSCREEN );
        _settextposition( oldpos.row, oldpos.col );
    }





_settextcursor
────────────────────────────────────────────────────────────────────────────


Description

Sets the current cursor attribute.

    #include <graph.h>

    short _far _settextcursor( short attr );

attr                              Cursor attribute


Remarks

The _settextcursor function sets the cursor attribute (i.e., the shape) to
the value specified by attr. The high-order byte of attr determines the top
line of the cursor within the character cell. The low-order byte of attr
determines the bottom line of the cursor.

The _settextcursor function uses the same format as the BIOS routines in
setting the cursor. Typical values for the cursor attribute are listed
below:

Attribute                         Cursor Shape
────────────────────────────────────────────────────────────────────────────
0x0707                            Underline

0x0007                            Full block cursor

0x0607                            Double underline

0x2000                            No cursor

Note that this function works only in text video modes.


Return Value

The function returns the previous cursor attribute, or -1 if an error occurs
(such as calling the function in a graphics screen mode).


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_displaycursor,  _gettextcursor


Example

    /* DISCURS.C: This program changes the cursor shape using _gettextcursor
    * and _settextcursor, and hides the cursor using _displaycursor.
    */

    #include <conio.h>
    #include <graph.h>

    void main()
    {
        short oldcursor;
        short newcursor = 0x007;        /* Full block cursor */

        /* Save old cursor shape and make sure cursor is on. */
        oldcursor = _gettextcursor();
        _clearscreen( _GCLEARSCREEN );
        _displaycursor( _GCURSORON );
        _outtext( "\nOld cursor shape: " );
        getch();

        /* Change cursor shape. */
        _outtext( "\nNew cursor shape: " );
        _settextcursor( newcursor );
        getch();

        /* Restore original cursor shape. */
        _outtext( "\n" );
        _settextcursor( oldcursor );
    }





_settextposition
────────────────────────────────────────────────────────────────────────────


Description

Sets the text position.

    #include <graph.h>

    struct rccoord _far _settextposition( short row, short column );

row, column                       New output start position


Remarks

The _settextposition function sets the current text position to the display
point (row, column). The _outtext and _outmem functions (and standard
console I/O routines, such as printf) output text at that point.

The rccoord structure, defined in GRAPH.H, contains the following elements:


Element                           Description
────────────────────────────────────────────────────────────────────────────
short row                         Row coordinate

short col                         Column coordinate


Return Value

The function returns the previous text position in an rccoord structure,
defined in GRAPH.H.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_gettextposition,  _outtext,  _settextwindow


Example

    /* OUTTXT.C: This example illustrates text output functions:
    *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
    *    _settextcolor   _setbkcolor   _settextposition
    */

    #include <conio.h>
    #include <stdio.h>
    #include <graph.h>

    char buffer [80];

    void main()
    {

    /* Save original foreground, background, and text position */
        short blink, fgd, oldfgd;
        long  bgd, oldbgd;
        struct rccoord oldpos;

        /* Save original foreground, background, and text position. */
        oldfgd = _gettextcolor();
        oldbgd = _getbkcolor();
        oldpos = _gettextposition();
        _clearscreen( _GCLEARSCREEN );

        /* First time no blink, second time blinking. */
        for( blink = 0; blink <= 16; blink += 16 )
        {
        /* Loop through 8 background colors. */
        for( bgd = 0; bgd < 8; bgd++ )
        {
            _setbkcolor( bgd );
            _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
            _settextcolor( 7 );
            sprintf(buffer, "Back: %d Fore:", bgd );
            _outtext( buffer );

            /* Loop through 16 foreground colors. */
            for( fgd = 0; fgd < 16; fgd++ )
            {
                _settextcolor( fgd + blink );
                sprintf( buffer, " %2d ", fgd + blink );
                _outtext( buffer );
            }
        }
        }
        getch();

        /* Restore original foreground, background, and text position. */
        _settextcolor( oldfgd );
        _setbkcolor( oldbgd );
        _clearscreen( _GCLEARSCREEN );
        _settextposition( oldpos.row, oldpos.col );
    }





_settextrows
────────────────────────────────────────────────────────────────────────────


Description

Sets the number of screen rows for text modes.

    #include <graph.h>

    short _far _settextrows( short rows );

rows                              Number of text rows


Remarks

The _settextrows function specifies the number of screen rows to be used in
text modes.

If the constant _MAXTEXTROWS is specified for the rows argument, the
function will choose the maximum number of rows available. In text modes,
this is 50 rows on VGA, 43 on EGA, and 25 on others. In graphics modes that
support 30 or 60 rows, _MAXTEXTROWS specifies 60 rows.


Return Value

This function returns the numbers of rows set. The function returns 0 if an
error occurred.


Compatibility

▼ ANSI   DOS   OS/2  ▼ UNIX  ▼ XENIX



See Also

_getvideoconfig,  _setvideomode,  _setvideomoderows


Example

    /* STXTROWS.C: This program attempts to set the screen height. It returns
    * an errorlevel code of 1 (fail) or 0 (success) that could be tested in
    * a batch file.
    */

    #include <graph.h>
    #include <stdlib.h>

    void main( int argc, char **argv )
    {
        short rows;

        if( !(rows = atoi( argv[1] )) )
        {
        _outtext( "\n