home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Programmer's Library 1.3 / Microsoft-Programers-Library-v1.3.iso / books / clibref.db < prev    next >
Encoding:
Text File  |  1991-03-01  |  1.6 MB  |  42,325 lines
Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents.
  1. %@1@%%@AB@%Microsoft  C - RUN-TIME LIBRARY REFERENCE%@AE@%%@EH@%%@NL@%
  2.                                       %@NL@%
  3.                                       %@NL@%
  4.                                       %@NL@%
  5.                                       %@NL@%
  6.                                       %@NL@%
  7.                                       %@NL@%
  8.                                       %@NL@%
  9.  
  10. ────────────────────────────────────────────────────────────────────────────%@NL@%
  11.                 %@AB@%Microsoft (R) C - RUN-TIME LIBRARY REFERENCE%@AE@%%@NL@%
  12.                                       %@NL@%
  13.                              %@AB@%FOR THE MS-DOS (R)
  14.                               %@AB@%OPERATING SYSTEM%@AE@%%@NL@%
  15. ────────────────────────────────────────────────────────────────────────────%@NL@%
  16.                                       %@NL@%
  17.                                       %@NL@%
  18.                            MICROSOFT CORPORATION %@NL@%
  19.                                       %@NL@%
  20. %@NL@%
  21. %@NL@%
  22. %@NL@%
  23. %@NL@%%@NL@%
  24. %@NL@%
  25.  
  26.  
  27. PUBLISHED BY
  28. Microsoft Press
  29. A Division of Microsoft Corporation
  30. One Microsoft Way, Redmond, Washington 98052-6399
  31.  
  32. Copyright (C)  1990 by Microsoft Press
  33.  
  34. All rights reserved. No part of the contents of this book may be reproduced
  35. or transmitted in any form or by any means without the written permission of
  36. the publisher.
  37.  
  38. Library of Congress Cataloging-in-Publication Data
  39.  
  40. Microsoft C run-time library reference.
  41.  
  42. Includes  index.
  43. 1. C (Computer program language) 2. Microsoft C
  44. (Computer program) 3. Macro instructions (Electronic
  45. computers) I. Microsoft.
  46. QA76.73.C15M52  1990         005.13'3         89-12240
  47. ISBN 1-55615-225-6
  48.  
  49. Printed and bound in the United States of America.
  50.  
  51. 1 2 3 4 5 6 7 8 9  HCHC 3 2 1 0 9
  52.  
  53. Distributed to the book trade in Canada by General Publishing Company, Ltd.
  54.  
  55. Distributed to the book trade outside the United States and Canada by
  56. Penguin
  57. Books  Ltd.
  58.  
  59. Penguin Books Ltd., Harmondsworth, Middlesex, England
  60. Penguin Books Australia Ltd., Ringwood, Victoria, Australia
  61. Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New Zealand
  62.  
  63. British Cataloging in Publication Data available.
  64.  
  65.                                             %@AB@%Sample%@AE@%
  66. %@AB@%Writers:%@AE@%           %@AB@%Editors:%@AE@%                 %@AB@%Programs:%@AE@%
  67. Phil Nelson        Amanda Clark             Bruce McKinney
  68. Terry Ward         Moira Macdonald
  69.                    Marjorie Manwaring
  70.                    Bill Nolan%@NL@%
  71. %@NL@%
  72. Microsoft, the Microsoft logo, MS-DOS, QuickC, and XENIX are
  73. registered trademarks and Windows is a trademark of Microsoft Corporation.%@NL@%
  74. %@NL@%
  75. AT&T and UNIX are registered trademarks of American Telephone
  76. and Telegraph Company.%@NL@%
  77. %@NL@%
  78. Hercules is a registered trademark of Hercules Computer
  79. Technology.%@NL@%
  80. %@NL@%
  81. IBM is a registered trademark of International Business
  82. Machines Corporation.%@NL@%
  83. %@NL@%
  84. Olivetti is a registered trademark of Ing. C. Olivetti.%@NL@%
  85. %@NL@%
  86. Document No. 410840021-520-R00-1088
  87. Part No. 04412%@NL@%
  88. %@NL@%
  89. %@NL@%
  90. %@NL@%
  91. %@NL@%
  92. %@1@%%@AB@%Table of Contents%@AE@%%@EH@%%@NL@%
  93. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  94. %@NL@%
  95.  
  96. %@NL@%
  97. %@AB@%Introduction%@AE@%%@BO:        60e8@%%@NL@%
  98.      About the C Run-Time Library%@BO:        681f@%%@NL@%
  99.             ANSI C Compatibility%@BO:        6ad6@%%@NL@%
  100.             OS/2 and XENIX(R) Programming%@BO:        6ef0@%%@NL@%
  101.             Expanded Graphics Library%@BO:        7195@%%@NL@%
  102.      About This Book%@BO:        7603@%%@NL@%
  103.      Other Books of Interest%@BO:        7cc7@%%@NL@%
  104.      Document Conventions%@BO:        8d75@%%@NL@%
  105. %@NL@%
  106. %@NL@%
  107. %@AB@%PART I%@AE@%%@BO:        9ce2@%  %@AB@%Overview%@AE@%%@NL@%
  108. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  109. %@NL@%
  110. %@NL@%
  111. %@AB@%Chapter 1%@AE@%%@BO:        9f3e@%  %@AB@%Using C Library Routines%@AE@%%@NL@%
  112. %@NL@%
  113.      1.1%@BO:        a17a@%   Calling Library Routines%@NL@%
  114.      1.2%@BO:        acbb@%   Using Header Files%@NL@%
  115.             1.2.1%@BO:        adcb@%    Including Necessary Definitions%@NL@%
  116.             1.2.2%@BO:        b402@%    Including Function Declarations%@NL@%
  117.      1.3%@BO:        c64f@%   File Names and Path Names%@NL@%
  118.      1.4%@BO:        cd69@%   Choosing Between Functions and Macros%@NL@%
  119.      1.5%@BO:        e2d8@%   Stack Checking on Entry%@NL@%
  120.      1.6%@BO:        e7ec@%   Handling Errors%@NL@%
  121.      1.7%@BO:        f3f7@%   Operating-System Considerations%@NL@%
  122.      1.8%@BO:        ff84@%   Floating-Point Support%@NL@%
  123.      1.9%@BO:       1101b@%   Using Huge Arrays with Library Functions%@NL@%
  124. %@NL@%
  125. %@AB@%Chapter 2%@AE@%%@BO:       117ed@%  %@AB@%Run-Time Routines by Category%@AE@%%@NL@%
  126. %@NL@%
  127.      2.1%@BO:       11d28@%   Buffer Manipulation%@NL@%
  128.      2.2%@BO:       12a93@%   Character Classification and Conversion%@NL@%
  129.      2.3%@BO:       136c7@%   Data Conversion %@NL@%
  130.      2.4%@BO:       14030@%   Directory Control%@NL@%
  131.      2.5%@BO:       1456f@%   File Handling%@NL@%
  132.      2.6%@BO:       1555d@%   Graphics%@NL@%
  133.             2.6.1%@BO:       15786@%    Low-Level Graphics and Character-Font Functions%@NL@%
  134.             2.6.2%@BO:       1afcf@%    Presentation-Graphics Functions%@NL@%
  135.      2.7%@BO:       1cc64@%   Input and Output%@NL@%
  136.             2.7.1%@BO:       1d597@%    Text and Binary Modes%@NL@%
  137.             2.7.2%@BO:       1e13d@%    Stream Routines%@NL@%
  138.             2.7.3%@BO:       221df@%    Low-Level Routines%@NL@%
  139.             2.7.4%@BO:       239df@%    Console and Port I/O%@NL@%
  140.      2.8%@BO:       24c42@%   Internationalization%@NL@%
  141.      2.9%@BO:       250cb@%   Math%@NL@%
  142.      2.10%@BO:       2719e@%  Memory Allocation %@NL@%
  143.             2.10.1%@BO:       28704@%   Near and Far Heaps%@NL@%
  144.             2.10.2%@BO:       28cf2@%   Based Heaps%@NL@%
  145.      2.11%@BO:       29437@%  Process and Environment Control %@NL@%
  146.      2.12%@BO:       2c9a9@%  Searching and Sorting %@NL@%
  147.      2.13%@BO:       2cd6b@%  String Manipulation%@NL@%
  148.      2.14%@BO:       2dde5@%  System Calls%@NL@%
  149.             2.14.1%@BO:       2df7d@%   BIOS Interface %@NL@%
  150.             2.14.2%@BO:       2e68c@%   DOS Interface%@NL@%
  151.      2.15%@BO:       31041@%  Time%@NL@%
  152.      2.16%@BO:       3212e@%  Variable-Length Argument Lists%@NL@%
  153. %@NL@%
  154. %@AB@%Chapter 3%@AE@%%@BO:       325f9@%  %@AB@%Global Variables and Standard Types%@AE@%%@NL@%
  155. %@NL@%
  156.      3.1%@BO:       3283e@%   _amblksiz%@NL@%
  157.      3.2%@BO:       330b2@%   daylight, timezone, tzname%@NL@%
  158.      3.3%@BO:       33a2f@%   _doserrno, errno, sys_errlist, sys_nerr    %@NL@%
  159.      3.4%@BO:       34df1@%   _fmode  %@NL@%
  160.      3.5%@BO:       35126@%   _osmajor, _osminor, _osmode, _osversion    %@NL@%
  161.      3.6%@BO:       358aa@%   environ%@NL@%
  162.      3.7%@BO:       35e51@%   _psp%@NL@%
  163.      3.8%@BO:       36186@%   Standard Types%@NL@%
  164. %@NL@%
  165. %@NL@%
  166. %@AB@%PART II%@AE@%%@BO:       388bb@%  %@AB@%Run-Time Functions%@AE@%%@NL@%
  167. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@NL@%
  168. %@NL@%
  169.      About the Run-Time Reference%@BO:       38b14@%%@NL@%
  170.             abort%@BO:       3918f@%%@NL@%
  171.             abs%@BO:       39c83@%%@NL@%
  172.             access%@BO:       3a51d@%%@NL@%
  173.             acos Functions%@BO:       3b2f2@%%@NL@%
  174.             alloca%@BO:       3bfb2@%%@NL@%
  175.             _arc Functions%@BO:       3cd40@%%@NL@%
  176.             asctime%@BO:       3dfa0@%%@NL@%
  177.             asin Functions%@BO:       3ef49@%%@NL@%
  178.             assert%@BO:       3fba2@%%@NL@%
  179.             atan Functions%@BO:       40aaa@%%@NL@%
  180.             atexit%@BO:       4182b@%%@NL@%
  181.             atof, atoi, atol, _atold%@BO:       42491@%%@NL@%
  182.             bdos%@BO:       4396d@%%@NL@%
  183.             _beginthread%@BO:       44616@%%@NL@%
  184.             Bessel Functions%@BO:       467cf@%%@NL@%
  185.             _bfreeseg%@BO:       47c82@%%@NL@%
  186.             _bheapseg%@BO:       48b9d@%%@NL@%
  187.             _bios_disk%@BO:       49d7c@%%@NL@%
  188.             _bios_equiplist%@BO:       4c4f3@%%@NL@%
  189.             _bios_keybrd%@BO:       4d003@%%@NL@%
  190.             _bios_memsize%@BO:       4e8f5@%%@NL@%
  191.             _bios_printer%@BO:       4ef09@%%@NL@%
  192.             _bios_serialcom%@BO:       50135@%%@NL@%
  193.             _bios_timeofday%@BO:       51aa3@%%@NL@%
  194.             bsearch%@BO:       526b2@%%@NL@%
  195.             cabs, cabsl%@BO:       53a4b@%%@NL@%
  196.             calloc Functions%@BO:       544f9@%%@NL@%
  197.             ceil, ceill%@BO:       555d7@%%@NL@%
  198.             _cexit, _c_exit%@BO:       5608d@%%@NL@%
  199.             cgets%@BO:       56b23@%%@NL@%
  200.             _chain_intr%@BO:       577bb@%%@NL@%
  201.             chdir%@BO:       585ac@%%@NL@%
  202.             _chdrive%@BO:       593ee@%%@NL@%
  203.             chmod%@BO:       5a293@%%@NL@%
  204.             chsize%@BO:       5b15c@%%@NL@%
  205.             _clear87%@BO:       5bfa2@%%@NL@%
  206.             clearerr%@BO:       5c99b@%%@NL@%
  207.             _clearscreen%@BO:       5d349@%%@NL@%
  208.             clock%@BO:       5dd96@%%@NL@%
  209.             close%@BO:       5ea6b@%%@NL@%
  210.             _control87%@BO:       5f46c@%%@NL@%
  211.             cos Functions%@BO:       608a6@%%@NL@%
  212.             cprintf%@BO:       615fd@%%@NL@%
  213.             cputs%@BO:       62053@%%@NL@%
  214.             creat%@BO:       6275b@%%@NL@%
  215.             cscanf%@BO:       63b00@%%@NL@%
  216.             ctime%@BO:       646ec@%%@NL@%
  217.             cwait%@BO:       65444@%%@NL@%
  218.             dieeetomsbin, dmsbintoieee%@BO:       674ae@%%@NL@%
  219.             difftime%@BO:       67d18@%%@NL@%
  220.             _displaycursor%@BO:       686db@%%@NL@%
  221.             div%@BO:       69024@%%@NL@%
  222.             _dos_allocmem%@BO:       69bf6@%%@NL@%
  223.             _dos_close%@BO:       6a817@%%@NL@%
  224.             _dos_creat Functions%@BO:       6b1ef@%%@NL@%
  225.             _dos_find Functions%@BO:       6c149@%%@NL@%
  226.             _dos_freemem%@BO:       6df3c@%%@NL@%
  227.             _dos_getdate%@BO:       6ea74@%%@NL@%
  228.             _dos_getdiskfree%@BO:       6f474@%%@NL@%
  229.             _dos_getdrive%@BO:       7006a@%%@NL@%
  230.             _dos_getfileattr%@BO:       70a67@%%@NL@%
  231.             _dos_getftime%@BO:       71b5c@%%@NL@%
  232.             _dos_gettime%@BO:       72d14@%%@NL@%
  233.             _dos_getvect%@BO:       736d0@%%@NL@%
  234.             _dos_keep%@BO:       73dbd@%%@NL@%
  235.             _dos_open%@BO:       74998@%%@NL@%
  236.             _dos_read%@BO:       75c4f@%%@NL@%
  237.             _dos_setblock%@BO:       76a0b@%%@NL@%
  238.             _dos_setdate%@BO:       7760e@%%@NL@%
  239.             _dos_setdrive%@BO:       782a0@%%@NL@%
  240.             _dos_setfileattr%@BO:       78e46@%%@NL@%
  241.             _dos_setftime%@BO:       7a046@%%@NL@%
  242.             _dos_settime%@BO:       7b17b@%%@NL@%
  243.             _dos_setvect%@BO:       7bdfd@%%@NL@%
  244.             _dos_write%@BO:       7d825@%%@NL@%
  245.             dosexterr%@BO:       7e534@%%@NL@%
  246.             dup, dup2%@BO:       7f385@%%@NL@%
  247.             ecvt%@BO:       803c0@%%@NL@%
  248.             _ellipse Functions%@BO:       8119d@%%@NL@%
  249.             _enable%@BO:       82278@%%@NL@%
  250.             _endthread%@BO:       825f4@%%@NL@%
  251.             eof%@BO:       82ba1@%%@NL@%
  252.             exec Functions%@BO:       83572@%%@NL@%
  253.             exit, _exit%@BO:       86c0b@%%@NL@%
  254.             exp, expl%@BO:       87c85@%%@NL@%
  255.             _expand Functions%@BO:       88501@%%@NL@%
  256.             fabs, fabsl%@BO:       89b71@%%@NL@%
  257.             fclose, fcloseall%@BO:       8a5c9@%%@NL@%
  258.             fcvt%@BO:       8b384@%%@NL@%
  259.             fdopen%@BO:       8c1f2@%%@NL@%
  260.             feof%@BO:       8d62b@%%@NL@%
  261.             ferror%@BO:       8e0f7@%%@NL@%
  262.             fflush%@BO:       8eb47@%%@NL@%
  263.             fgetc, fgetchar%@BO:       8f6d7@%%@NL@%
  264.             fgetpos%@BO:       903d7@%%@NL@%
  265.             fgets%@BO:       9124b@%%@NL@%
  266.             fieeetomsbin, fmsbintoieee%@BO:       91df3@%%@NL@%
  267.             filelength%@BO:       9260a@%%@NL@%
  268.             fileno%@BO:       92fa7@%%@NL@%
  269.             _floodfill, _floodfill_w%@BO:       937b9@%%@NL@%
  270.             floor, floorl%@BO:       9445a@%%@NL@%
  271.             flushall%@BO:       94ebe@%%@NL@%
  272.             fmod, fmodl%@BO:       956a5@%%@NL@%
  273.             fopen%@BO:       96058@%%@NL@%
  274.             FP_OFF, FP_SEG%@BO:       97d48@%%@NL@%
  275.             _fpreset%@BO:       98566@%%@NL@%
  276.             fprintf%@BO:       99b20@%%@NL@%
  277.             fputc, fputchar%@BO:       9a664@%%@NL@%
  278.             fputs%@BO:       9b19d@%%@NL@%
  279.             fread%@BO:       9b8ea@%%@NL@%
  280.             free Functions%@BO:       9c89a@%%@NL@%
  281.             _freect%@BO:       9dbfa@%%@NL@%
  282.             freopen%@BO:       9e721@%%@NL@%
  283.             frexp, frexpl%@BO:       a0465@%%@NL@%
  284.             fscanf%@BO:       a0f0e@%%@NL@%
  285.             fseek%@BO:       a1cd1@%%@NL@%
  286.             fsetpos%@BO:       a2edd@%%@NL@%
  287.             _fsopen%@BO:       a3d28@%%@NL@%
  288.             fstat%@BO:       a5e7a@%%@NL@%
  289.             ftell%@BO:       a7374@%%@NL@%
  290.             ftime%@BO:       a8370@%%@NL@%
  291.             _fullpath%@BO:       a9207@%%@NL@%
  292.             fwrite%@BO:       aa009@%%@NL@%
  293.             gcvt%@BO:       aae6c@%%@NL@%
  294.             _getactivepage%@BO:       ab89b@%%@NL@%
  295.             _getarcinfo%@BO:       ac314@%%@NL@%
  296.             _getbkcolor%@BO:       accf6@%%@NL@%
  297.             getc, getchar%@BO:       ad644@%%@NL@%
  298.             getch, getche%@BO:       ae25a@%%@NL@%
  299.             _getcolor%@BO:       aebc0@%%@NL@%
  300.             _getcurrentposition Functions%@BO:       af76f@%%@NL@%
  301.             getcwd%@BO:       b069d@%%@NL@%
  302.             _getdcwd%@BO:       b13ae@%%@NL@%
  303.             _getdrive%@BO:       b25f3@%%@NL@%
  304.             getenv%@BO:       b2a78@%%@NL@%
  305.             _getfillmask%@BO:       b3958@%%@NL@%
  306.             _getfontinfo%@BO:       b47b4@%%@NL@%
  307.             _getgtextextent%@BO:       b518c@%%@NL@%
  308.             _getimage Functions%@BO:       b578c@%%@NL@%
  309.             _getlinestyle%@BO:       b6b86@%%@NL@%
  310.             _getphyscoord%@BO:       b79d6@%%@NL@%
  311.             getpid%@BO:       b8070@%%@NL@%
  312.             _getpixel Functions%@BO:       b872a@%%@NL@%
  313.             gets%@BO:       b93d1@%%@NL@%
  314.             _gettextcolor%@BO:       b9c6b@%%@NL@%
  315.             _gettextcursor%@BO:       ba2b6@%%@NL@%
  316.             _gettextposition%@BO:       ba79f@%%@NL@%
  317.             _gettextwindow%@BO:       bb713@%%@NL@%
  318.             _getvideoconfig%@BO:       bbf34@%%@NL@%
  319.             _getviewcoord Functions%@BO:       bdaa1@%%@NL@%
  320.             _getvisualpage%@BO:       be761@%%@NL@%
  321.             getw%@BO:       bed02@%%@NL@%
  322.             _getwindowcoord%@BO:       bf896@%%@NL@%
  323.             _getwritemode%@BO:       bffc1@%%@NL@%
  324.             gmtime%@BO:       c0c44@%%@NL@%
  325.             _grstatus%@BO:       c1b7a@%%@NL@%
  326.             halloc%@BO:       c50a1@%%@NL@%
  327.             _hard Functions%@BO:       c5ae8@%%@NL@%
  328.             _heapadd Functions%@BO:       c8111@%%@NL@%
  329.             _heapchk Functions%@BO:       c986a@%%@NL@%
  330.             _heapmin Functions%@BO:       ca8c3@%%@NL@%
  331.             _heapset Functions%@BO:       cb359@%%@NL@%
  332.             _heapwalk Functions%@BO:       cc691@%%@NL@%
  333.             hfree%@BO:       ce432@%%@NL@%
  334.             hypot, hypotl%@BO:       ced41@%%@NL@%
  335.             _imagesize Functions%@BO:       cf737@%%@NL@%
  336.             inp, inpw%@BO:       d034f@%%@NL@%
  337.             int86%@BO:       d0c38@%%@NL@%
  338.             int86x%@BO:       d1a2f@%%@NL@%
  339.             intdos%@BO:       d2a93@%%@NL@%
  340.             intdosx%@BO:       d37ba@%%@NL@%
  341.             is Functions%@BO:       d467d@%%@NL@%
  342.             isatty%@BO:       d5fa1@%%@NL@%
  343.             itoa%@BO:       d66b5@%%@NL@%
  344.             kbhit%@BO:       d7284@%%@NL@%
  345.             labs%@BO:       d7a47@%%@NL@%
  346.             ldexp, ldexpl%@BO:       d82cd@%%@NL@%
  347.             ldiv%@BO:       d8bf5@%%@NL@%
  348.             lfind%@BO:       d9730@%%@NL@%
  349.             _lineto Functions%@BO:       da6e4@%%@NL@%
  350.             localeconv%@BO:       db323@%%@NL@%
  351.             localtime%@BO:       dd16a@%%@NL@%
  352.             locking%@BO:       de396@%%@NL@%
  353.             log Functions%@BO:       dfccd@%%@NL@%
  354.             long double Functions%@BO:       e08bc@%%@NL@%
  355.             longjmp%@BO:       e14ca@%%@NL@%
  356.             _lrotl, _lrotr%@BO:       e22e1@%%@NL@%
  357.             lsearch%@BO:       e2b64@%%@NL@%
  358.             lseek%@BO:       e37af@%%@NL@%
  359.             ltoa%@BO:       e4a65@%%@NL@%
  360.             _makepath%@BO:       e564b@%%@NL@%
  361.             malloc Functions%@BO:       e6d90@%%@NL@%
  362.             matherr, _matherrl%@BO:       e9184@%%@NL@%
  363.             max%@BO:       ead81@%%@NL@%
  364.             _memavl%@BO:       eb4bb@%%@NL@%
  365.             memccpy, _fmemccpy%@BO:       ebfb6@%%@NL@%
  366.             memchr, _fmemchr%@BO:       eccf2@%%@NL@%
  367.             memcmp, _fmemcmp%@BO:       edb82@%%@NL@%
  368.             memcpy, _fmemcpy%@BO:       eecbb@%%@NL@%
  369.             memicmp, _fmemicmp%@BO:       f019c@%%@NL@%
  370.             _memmax%@BO:       f1163@%%@NL@%
  371.             memmove, _fmemmove%@BO:       f1b64@%%@NL@%
  372.             memset, _fmemset%@BO:       f2e58@%%@NL@%
  373.             min%@BO:       f3a2b@%%@NL@%
  374.             mkdir%@BO:       f4166@%%@NL@%
  375.             mktemp%@BO:       f4dcd@%%@NL@%
  376.             mktime%@BO:       f5f19@%%@NL@%
  377.             modf, modfl%@BO:       f6e15@%%@NL@%
  378.             movedata%@BO:       f7841@%%@NL@%
  379.             _moveto Functions%@BO:       f863b@%%@NL@%
  380.             _msize Functions%@BO:       f93b6@%%@NL@%
  381.             onexit%@BO:       fa55b@%%@NL@%
  382.             open%@BO:       fb0e9@%%@NL@%
  383.             _outgtext%@BO:       fd68e@%%@NL@%
  384.             _outmem%@BO:       fea80@%%@NL@%
  385.             outp, outpw%@BO:       ff351@%%@NL@%
  386.             _outtext%@BO:      10053b@%%@NL@%
  387.             _pclose%@BO:      10126a@%%@NL@%
  388.             perror%@BO:      101a68@%%@NL@%
  389.             _pg_analyzechart Functions%@BO:      102aba@%%@NL@%
  390.             _pg_analyzepie%@BO:      10438e@%%@NL@%
  391.             _pg_analyzescatter Functions%@BO:      104bad@%%@NL@%
  392.             _pg_chart Functions%@BO:      10587e@%%@NL@%
  393.             _pg_chartscatter Functions%@BO:      106ee0@%%@NL@%
  394.             _pg_chartpie%@BO:      107ac6@%%@NL@%
  395.             _pg_defaultchart%@BO:      10849d@%%@NL@%
  396.             _pg_getchardef%@BO:      109371@%%@NL@%
  397.             _pg_getpalette%@BO:      1098dc@%%@NL@%
  398.             _pg_getstyleset%@BO:      10b2f4@%%@NL@%
  399.             _pg_hlabelchart%@BO:      10b7a5@%%@NL@%
  400.             _pg_initchart%@BO:      10bea1@%%@NL@%
  401.             _pg_resetpalette%@BO:      10c693@%%@NL@%
  402.             _pg_resetstyleset%@BO:      10cc89@%%@NL@%
  403.             _pg_setchardef%@BO:      10d100@%%@NL@%
  404.             _pg_setpalette%@BO:      10d692@%%@NL@%
  405.             _pg_setstyleset%@BO:      10dd45@%%@NL@%
  406.             _pg_vlabelchart%@BO:      10e1de@%%@NL@%
  407.             _pie Functions%@BO:      10e8d4@%%@NL@%
  408.             _pipe%@BO:      10fd2d@%%@NL@%
  409.             _polygon Functions%@BO:      111db1@%%@NL@%
  410.             _popen%@BO:      112f74@%%@NL@%
  411.             pow Functions%@BO:      113f34@%%@NL@%
  412.             printf%@BO:      114b08@%%@NL@%
  413.             putc, putchar%@BO:      11afff@%%@NL@%
  414.             putch%@BO:      11ba7c@%%@NL@%
  415.             putenv%@BO:      11c223@%%@NL@%
  416.             _putimage Functions%@BO:      11d544@%%@NL@%
  417.             puts%@BO:      11e6e5@%%@NL@%
  418.             putw%@BO:      11edcd@%%@NL@%
  419.             qsort%@BO:      11f8f4@%%@NL@%
  420.             raise%@BO:      1209b7@%%@NL@%
  421.             rand%@BO:      121769@%%@NL@%
  422.             read%@BO:      121fe1@%%@NL@%
  423.             realloc Functions%@BO:      12321d@%%@NL@%
  424.             _rectangle Functions%@BO:      124988@%%@NL@%
  425.             _registerfonts%@BO:      125b2e@%%@NL@%
  426.             _remapallpalette, _remappalette%@BO:      1265e5@%%@NL@%
  427.             remove%@BO:      129398@%%@NL@%
  428.             rename%@BO:      129be8@%%@NL@%
  429.             rewind%@BO:      12a97e@%%@NL@%
  430.             rmdir%@BO:      12b52b@%%@NL@%
  431.             rmtmp%@BO:      12c0fc@%%@NL@%
  432.             _rotl, _rotr%@BO:      12cabd@%%@NL@%
  433.             scanf%@BO:      12d39b@%%@NL@%
  434.             _scrolltextwindow%@BO:      131185@%%@NL@%
  435.             _searchenv%@BO:      132443@%%@NL@%
  436.             segread%@BO:      133031@%%@NL@%
  437.             _selectpalette%@BO:      1338f3@%%@NL@%
  438.             _setactivepage%@BO:      134f2f@%%@NL@%
  439.             _setbkcolor%@BO:      135d81@%%@NL@%
  440.             setbuf%@BO:      136986@%%@NL@%
  441.             _setcliprgn%@BO:      1375e9@%%@NL@%
  442.             _setcolor%@BO:      137f24@%%@NL@%
  443.             _setfillmask%@BO:      138c65@%%@NL@%
  444.             _setfont%@BO:      139939@%%@NL@%
  445.             _setgtextvector%@BO:      13b65a@%%@NL@%
  446.             setjmp%@BO:      13bff2@%%@NL@%
  447.             _setlinestyle%@BO:      13c8cb@%%@NL@%
  448.             setlocale%@BO:      13cf6e@%%@NL@%
  449.             setmode%@BO:      13e030@%%@NL@%
  450.             _setpixel Functions%@BO:      13efb1@%%@NL@%
  451.             _settextcolor%@BO:      13fbad@%%@NL@%
  452.             _settextcursor%@BO:      140ea8@%%@NL@%
  453.             _settextposition%@BO:      141a4a@%%@NL@%
  454.             _settextrows%@BO:      1428ed@%%@NL@%
  455.             _settextwindow%@BO:      143229@%%@NL@%
  456.             setvbuf%@BO:      143a0b@%%@NL@%
  457.             _setvideomode%@BO:      144bab@%%@NL@%
  458.             _setvideomoderows%@BO:      1471df@%%@NL@%
  459.             _setvieworg%@BO:      147cb4@%%@NL@%
  460.             _setviewport%@BO:      148835@%%@NL@%
  461.             _setvisualpage%@BO:      149155@%%@NL@%
  462.             _setwindow%@BO:      149700@%%@NL@%
  463.             _setwritemode%@BO:      14b303@%%@NL@%
  464.             signal%@BO:      14ba04@%%@NL@%
  465.             sin Functions%@BO:      14fca4@%%@NL@%
  466.             sopen%@BO:      1509fa@%%@NL@%
  467.             spawn Functions%@BO:      1530a2@%%@NL@%
  468.             _splitpath%@BO:      15729e@%%@NL@%
  469.             sprintf%@BO:      1581ec@%%@NL@%
  470.             sqrt, sqrtl%@BO:      158dcd@%%@NL@%
  471.             srand%@BO:      1596bc@%%@NL@%
  472.             sscanf%@BO:      15a07a@%%@NL@%
  473.             stackavail%@BO:      15ac8b@%%@NL@%
  474.             stat%@BO:      15b49e@%%@NL@%
  475.             _status87%@BO:      15c7a1@%%@NL@%
  476.             strcat, _fstrcat%@BO:      15d21c@%%@NL@%
  477.             strchr, _fstrchr%@BO:      15ddf9@%%@NL@%
  478.             strcmp, _fstrcmp%@BO:      15ef39@%%@NL@%
  479.             strcmpi%@BO:      160083@%%@NL@%
  480.             strcoll%@BO:      160916@%%@NL@%
  481.             strcpy, _fstrcpy%@BO:      161199@%%@NL@%
  482.             strcspn, _fstrcspn%@BO:      161d81@%%@NL@%
  483.             _strdate%@BO:      1629b2@%%@NL@%
  484.             strdup Functions%@BO:      16324c@%%@NL@%
  485.             strerror, _strerror%@BO:      1640af@%%@NL@%
  486.             strftime%@BO:      1651ca@%%@NL@%
  487.             stricmp, _fstricmp%@BO:      166454@%%@NL@%
  488.             strlen, _fstrlen%@BO:      166ff9@%%@NL@%
  489.             strlwr, _fstrlwr%@BO:      1678a7@%%@NL@%
  490.             strncat, _fstrncat%@BO:      1682e1@%%@NL@%
  491.             strncmp, _fstrncmp%@BO:      168fa4@%%@NL@%
  492.             strncpy, _fstrncpy%@BO:      16a1c0@%%@NL@%
  493.             strnicmp, _fstrnicmp%@BO:      16aec9@%%@NL@%
  494.             strnset, _fstrnset%@BO:      16b9a8@%%@NL@%
  495.             strpbrk, _fstrpbrk%@BO:      16c426@%%@NL@%
  496.             strrchr, _fstrrchr%@BO:      16d07b@%%@NL@%
  497.             strrev, _fstrrev%@BO:      16e11b@%%@NL@%
  498.             strset, _fstrset%@BO:      16ec0f@%%@NL@%
  499.             strspn, _fstrspn%@BO:      16f56c@%%@NL@%
  500.             strstr, _fstrstr%@BO:      170273@%%@NL@%
  501.             _strtime%@BO:      170fa5@%%@NL@%
  502.             strtod, strtol, _strtold, strtoul%@BO:      1718a0@%%@NL@%
  503.             strtok, _fstrtok%@BO:      1736b8@%%@NL@%
  504.             strupr, _fstrupr%@BO:      17484b@%%@NL@%
  505.             strxfrm%@BO:      175200@%%@NL@%
  506.             swab%@BO:      175c20@%%@NL@%
  507.             system%@BO:      17646b@%%@NL@%
  508.             tan Functions%@BO:      17742e@%%@NL@%
  509.             tell%@BO:      1782fe@%%@NL@%
  510.             tempnam, tmpnam%@BO:      178b8a@%%@NL@%
  511.             time%@BO:      17a158@%%@NL@%
  512.             tmpfile%@BO:      17a9fb@%%@NL@%
  513.             toascii, tolower, toupper Functions%@BO:      17b4c9@%%@NL@%
  514.             tzset%@BO:      17ca1b@%%@NL@%
  515.             ultoa%@BO:      17dd29@%%@NL@%
  516.             umask%@BO:      17e88d@%%@NL@%
  517.             ungetc%@BO:      17f63c@%%@NL@%
  518.             ungetch%@BO:      1805dc@%%@NL@%
  519.             unlink%@BO:      18106f@%%@NL@%
  520.             _unregisterfonts%@BO:      1818e9@%%@NL@%
  521.             utime%@BO:      181e8c@%%@NL@%
  522.             va_arg, va_end, va_start%@BO:      182ded@%%@NL@%
  523.             vfprintf, vprintf, vsprintf%@BO:      185300@%%@NL@%
  524.             wait%@BO:      1869bd@%%@NL@%
  525.             _wrapon%@BO:      18855d@%%@NL@%
  526.             write%@BO:      189031@%%@NL@%
  527.  
  528. %@AB@%Index%@AE@%%@BO:      18a0ba@%
  529.  
  530.  
  531. %@NL@%
  532. %@NL@%
  533. %@CR:C6A-Intro   @%%@1@%%@AB@%Introduction%@AE@%%@EH@%%@NL@%
  534. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  535. %@NL@%
  536. The Microsoft(R) C Run-Time Library is a set of over 500 ready-to-use
  537. functions and macros designed for use in C programs. The run-time library
  538. makes programming easier by providing  %@NL@%
  539. %@NL@%
  540. %@NL@%
  541.   ■   Fast and efficient routines to perform common programming tasks (such
  542.       as string manipulation), sparing you the time and effort needed to
  543.       write such routines%@NL@%
  544. %@NL@%
  545.   ■   Reliable methods of performing operating-system functions (such as
  546.       opening and closing files)%@NL@%
  547. %@NL@%
  548. %@NL@%
  549. The C run-time library is important because it provides basic functions not
  550. provided by the C language itself. These functions include input and output,
  551. memory allocation, process control, graphics, and many others.  %@NL@%
  552. %@NL@%
  553. This book describes the Microsoft C run-time library routines included with
  554. the Microsoft Professional Development System version 6.0. These comprise
  555. all of the routines included with earlier versions of Microsoft C, as well
  556. as many new routines.  %@NL@%
  557. %@NL@%
  558. ────────────────────────────────────────────────────────────────────────────%@NL@%
  559. NOTE
  560.  
  561. %@AI@%Microsoft documentation uses the term "OS/2" to refer to the OS/2
  562. %@AI@%systems─Microsoft Operating System/2 (MS%@AI@%(R)%@AE@%%@AI@% OS/2) and IBM%@AE@%%@AI@%(R)%@AE@%%@AI@% OS/2.
  563. %@AI@%Similarly, the term "DOS" refers to both the MS-DOS%@AE@%%@AI@%(R)%@AE@%%@AI@% %@AE@%%@AI@%and IBM Personal
  564. %@AI@%Computer DOS operating systems. The name of a specific operating system is
  565. %@AI@%used when it is necessary to note features that are unique to that system.%@AE@%%@AE@%%@NL@%
  566. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  567. %@NL@%
  568. %@NL@%
  569. %@2@%%@CR:C6A00000001 @%%@AB@%About the C Run-Time Library%@AE@%%@EH@%%@NL@%
  570. %@NL@%
  571. The Microsoft C run-time library contains a number of new routines and
  572. features which support American National Standards Institute (ANSI) C
  573. compatibility, OS/2 and XENIX(R) programming, and sophisticated graphics
  574. programming.  %@NL@%
  575. %@NL@%
  576. To ease the task of transporting programs from one operating system to
  577. another, the description of each library routine includes compatibility
  578. boxes, which show at a glance whether the routine is compatible with ANSI C,
  579. MS-DOS, OS/2, UNIX(R), and XENIX. (In this book, references to XENIX systems
  580. also encompass UNIX and other UNIX-like systems.)  %@NL@%
  581. %@NL@%
  582. %@NL@%
  583. %@3@%%@CR:C6A00000002 @%%@AB@%ANSI C Compatibility%@AE@%%@EH@%%@NL@%
  584. %@NL@%
  585. The C run-time library routines are designed for compatibility with the ANSI
  586. C standard, which Microsoft C compilers support. The major innovation of
  587. ANSI C is to permit argument-type lists in function prototypes
  588. (declarations). Given the information in the function prototype, the
  589. compiler can check later references to the function to make sure that the
  590. references use the correct number and type of arguments and the correct
  591. return value.  %@NL@%
  592. %@NL@%
  593. To take advantage of the compiler's type-checking ability, the include files
  594. that accompany the C run-time library have been expanded. In addition to the
  595. definitions and declarations required by library routines, the include files
  596. now contain function declarations with argument-type lists. Several new
  597. include files have also been added. The names of these files are chosen to
  598. maximize compatibility with the ANSI C standard and with XENIX and UNIX
  599. names.%@CR:C6A00000003 @%%@CR:C6A00000004 @%  %@NL@%
  600. %@NL@%
  601. %@NL@%
  602. %@3@%%@CR:C6A00000005 @%%@AB@%OS/2 and XENIX(R) Programming%@AE@%%@EH@%%@NL@%
  603. %@NL@%
  604. Microsoft C run-time library routines are designed to maintain maximum
  605. compatibility between MS-DOS, OS/2, and XENIX or UNIX systems. The library
  606. offers a number of operating-system interface routines that allow you to
  607. take advantage of specific DOS and OS/2 features.  %@NL@%
  608. %@NL@%
  609. Most of the functions in the C library for DOS and OS/2 are compatible with
  610. like-named routines in the C library for XENIX. For additional
  611. compatibility, the math library functions have been extended to provide
  612. exception handling in the same manner as the UNIX System V math functions.  %@NL@%
  613. %@NL@%
  614. %@NL@%
  615. %@3@%%@CR:C6A00000006 @%%@AB@%Expanded Graphics Library%@AE@%%@EH@%%@NL@%
  616. %@NL@%
  617. The Microsoft C run-time library now contains over one hundred graphics
  618. routines. The core of this library consists of several dozen low-level
  619. graphics routines, which allow your programs to select video modes, set
  620. points, draw lines, change colors, and draw shapes such as rectangles and
  621. ellipses. You can display real-valued data, such as floating-point values,
  622. within windows of different sizes by using various coordinate systems.  %@NL@%
  623. %@NL@%
  624. Recent additions to the graphics library include presentation graphics and
  625. fonts. The presentation-graphics library provides powerful tools for adding
  626. presentation-quality graphics to your programs. These routines can display
  627. data as a variety of graphs, including pie charts, bar and column charts,
  628. line graphs, and scatter diagrams.  %@NL@%
  629. %@NL@%
  630. The fonts library allows your programs to display various styles and sizes
  631. of text in graphics images or charts. You can use font-manipulation routines
  632. with any graphics routines that display text, including presentation
  633. graphics.  %@NL@%
  634. %@NL@%
  635. %@NL@%
  636. %@2@%%@CR:C6A00000007 @%%@AB@%About This Book%@AE@%%@EH@%%@NL@%
  637. %@NL@%
  638. This book assumes that you understand the C language and know how to compile
  639. and link programs. If you have questions about these subjects, consult your
  640. compiler documentation.  %@NL@%
  641. %@NL@%
  642. This book has two parts. Part 1, "Overview," introduces the Microsoft C
  643. library. It describes general rules for using the library and summarizes the
  644. main categories of library routines. Part 1 contains the following chapters:
  645. %@NL@%
  646. %@NL@%
  647. %@NL@%
  648.   ■   Chapter 1, "Using C Library Routines," gives general rules for
  649.       understanding and using C library routines and mentions special
  650.       considerations that apply to certain routines. It is recommended that
  651.       you read this chapter before using the run-time library; you may also
  652.       want to turn to Chapter 1 when you have questions about library
  653.       procedures.%@NL@%
  654. %@NL@%
  655.   ■   Chapter 2, "Run-Time Routines by Category," lists the C library
  656.       routines by category and discusses considerations that apply to each
  657.       category. This chapter makes it easy to locate routines by task. Once
  658.       you find the routine you want, turn to the reference page in Part 2
  659.       for a detailed description.%@NL@%
  660. %@NL@%
  661.   ■   Chapter 3, "Global Variables and Standard Types," describes variables
  662.       and types that are used by library routines. Global variables and
  663.       standard types are also described in the reference descriptions of the
  664.       routines that use them.%@NL@%
  665. %@NL@%
  666. %@NL@%
  667. Part 2, "Run-Time Functions," describes the library routines in alphabetical
  668. order. Once you are familiar with the C library rules and procedures, you
  669. will probably use this part most often.  %@NL@%
  670. %@NL@%
  671. %@NL@%
  672. %@2@%%@CR:C6A00000008 @%%@AB@%Other Books of Interest%@AE@%%@EH@%%@NL@%
  673. %@NL@%
  674. This book provides a guide to the C run-time library provided with the
  675. Microsoft C Professional Development System version 6.0.  %@NL@%
  676. %@NL@%
  677. The following books cover a variety of topics that you may find useful. They
  678. are listed only for your convenience. With the exception of its own
  679. publications, Microsoft does not endorse these books or recommend them over
  680. others on the same subject.  %@NL@%
  681. %@NL@%
  682. %@NL@%
  683.   ■   Barkakati, Nabajyoti. %@AI@%The Waite Group's Microsoft C Bible%@AE@%.
  684.       Indianapolis, IN: Howard W. Sams, 1988.%@NL@%
  685. %@NL@%
  686. %@STUB@%      A topical guide to the Microsoft C run-time library. A similar volume
  687.       is available for the Microsoft QuickC(R) product.%@NL@%
  688. %@NL@%
  689.   ■   Campbell, Joe. %@AI@%C Programmer's Guide to Serial Communications%@AE@%.
  690.       Indianapolis, IN: Howard W. Sams & Company, 1987.%@NL@%
  691. %@NL@%
  692. %@STUB@%      A comprehensive guide to the specialized area of serial communication
  693.       programming in C.%@NL@%
  694. %@NL@%
  695.   ■   Hansen, Augie. %@AI@%Proficient C: The Microsoft Guide to Intermediate &
  696. %@AI@%      Advanced C Programming%@AE@%. Redmond, WA: Microsoft Press, 1987.%@NL@%
  697. %@NL@%
  698. %@STUB@%      An intermediate-level guide to C programming.%@NL@%
  699. %@NL@%
  700.   ■   Harbison, Samuel P., and Guy L. Steele, Jr. %@AI@%C: A Reference Manual%@AE@%, 2d
  701.       ed. Englewood Cliffs, NJ: Prentice Hall, 1987.%@NL@%
  702. %@NL@%
  703. %@STUB@%      A comprehensive guide to the C language and the standard library.%@NL@%
  704. %@NL@%
  705.   ■   Kernighan, Brian W., and Dennis M. Ritchie. %@AI@%The C Programming
  706. %@AI@%      Language%@AE@%, 2d ed. Englewood Cliffs, NJ: Prentice Hall, 1988.%@NL@%
  707. %@NL@%
  708. %@STUB@%      The first edition of this book is the classic definition of the C
  709.       language. The second edition includes new information on the proposed
  710.       ANSI C standard.%@NL@%
  711. %@NL@%
  712.   ■   Lafore, Robert. %@AI@%Microsoft C Programming for the IBM%@AE@%. Indianapolis, IN:
  713.       Howard W. Sams & Company, 1987.%@NL@%
  714. %@NL@%
  715. %@STUB@%      The first half of this book teaches C. The second half concentrates on
  716.       specifics of the PC environment, such as BIOS calls, memory, and video
  717.       displays.%@NL@%
  718. %@NL@%
  719.   ■   Mark Williams Company. %@AI@%ANSI C: A Lexical Guide%@AE@%. Englewood Cliffs, NJ:
  720.       Prentice Hall, 1988.%@NL@%
  721. %@NL@%
  722. %@STUB@%      A dictionary-style guide to the ANSI C standard.%@NL@%
  723. %@NL@%
  724.   ■   Plauger, P. J., and Jim Brodie. %@AI@%Standard C%@AE@%. Redmond, WA: Microsoft
  725.       Press, 1989.%@NL@%
  726. %@NL@%
  727. %@STUB@%      A quick reference guide to the ANSI C implementation by the secretary
  728.       and chairman of the ANSI-authorized C Programming Language Standards
  729.       Committee.%@NL@%
  730. %@NL@%
  731.   ■   Plum, Thomas. %@AI@%Reliable Data Structures in C%@AE@%. Cardiff, NJ: Plum Hall,
  732.       1985.%@NL@%
  733. %@NL@%
  734. %@STUB@%      An intermediate-level look at data structures using the C language.%@NL@%
  735. %@NL@%
  736.   ■   Plum, Thomas, and Jim Brodie. %@AI@%Efficient C%@AE@%. Cardiff, NJ: Plum Hall,
  737.       1985.%@NL@%
  738. %@NL@%
  739. %@STUB@%      A guide to techniques for increasing the efficiency of C programs.%@NL@%
  740. %@NL@%
  741.   ■   Press, William H., Brian P. Flannery, Saul A. Teukolsky, and William
  742.       T. Vetterling. %@AI@%Numerical Recipes in C: The Art of Scientific
  743. %@AI@%      Computing%@AE@%. New York: Cambridge University Press, 1988.%@NL@%
  744. %@NL@%
  745. %@STUB@%      A comprehensive look at numerical techniques using the C language.%@NL@%
  746. %@NL@%
  747.   ■   Schustack, Steve. %@AI@%Variations in C: Programming Techniques for
  748. %@AI@%      Developing Efficient Professional Applications%@AE@%. Redmond, WA: Microsoft
  749.       Press, 1985.%@NL@%
  750. %@NL@%
  751. %@STUB@%      An intermediate-level guide to developing business applications in C.%@NL@%
  752. %@NL@%
  753.   ■   Ward, Robert. %@AI@%Debugging C%@AE@%. Indianapolis, IN: Que Corporation, 1986.%@NL@%
  754. %@NL@%
  755. %@STUB@%      An advanced guide to the theory and practice of debugging C programs.%@NL@%
  756. %@NL@%
  757.   ■   Wilton, Richard. %@AI@%Programmer's Guide to PC and PS/2 Video
  758. %@AI@%      Systems:Maximum Video Performance from the EGA, VGA, HGC, & MCGA%@AE@%.
  759.       Redmond, WA: Microsoft Press, 1987.%@NL@%
  760. %@NL@%
  761. %@STUB@%      An advanced guide to all the PC and PS/2 video modes.%@NL@%
  762. %@NL@%
  763. %@NL@%
  764. %@NL@%
  765. %@2@%%@CR:C6A00000009 @%%@AB@%Document Conventions%@AE@%%@EH@%%@NL@%
  766. %@NL@%
  767. This book uses the following document conventions :%@CR:C6A00000010 @%  %@NL@%
  768. %@NL@%
  769. %@AB@%Example%@AE@%                           %@AB@%Description%@AE@%
  770. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  771. STDIO.H                           Uppercase letters indicate file names, 
  772.                                   segment names, registers, and terms used
  773.                                   at the operating-system command level. %@CR:C6A00000011 @%
  774.  
  775. %@AB@%_far%@AE@%                              Boldface letters indicate C keywords, 
  776.                                   operators, language-specific characters,
  777.                                   and library routines. Within discussions
  778.                                   of syntax, bold type indicates that the 
  779.                                   text must be entered exactly as shown. %@CR:C6A00000012 @%
  780.  
  781. %@AI@%expression%@AE@%                        Words in italics indicate placeholders 
  782.                                   for information you must supply, such as
  783.                                   a file name. Italics are also 
  784.                                   occasionally used for emphasis in the 
  785.                                   text. %@CR:C6A00000013 @%
  786.  
  787. [[%@AI@%option%@AE@%]]                        Items inside double square brackets are 
  788.                                   optional. %@CR:C6A00000014 @%%@CR:C6A00000015 @%
  789.  
  790. %@AB@%#pragma pack%@AE@% {%@AB@%1%@AE@%|%@AB@%2%@AE@%}                Braces and a vertical bar indicate a 
  791.                                   choice among two or more items. You must
  792.                                   choose one of these items unless double 
  793.                                   square brackets surround the braces.
  794.  
  795. %@AS@%#include <io.h>%@AE@%                   This font is used for examples, user 
  796.                                   input, program output, and error 
  797.                                   messages in text. %@CR:C6A00000016 @%
  798.  
  799. %@AB@%CL%@AE@% %@AI@%options%@AE@% [[%@AI@%files%@AE@%...]]           Three dots following an item indicate 
  800.                                   that more items having the same form may
  801.                                   appear. %@CR:C6A00000017 @%
  802.  
  803. %@AS@%while()%@AE@%                           A column of three dots tells you that 
  804. %@AS@%{%@AE@%                                 part of the example program has been 
  805. %@AS@%   .%@AE@%                              intentionally omitted. %@CR:C6A00000018 @%
  806. %@AS@%   .%@AE@%                              
  807. %@AS@%   .%@AE@%                              
  808. %@AS@%}%@AE@%                                 
  809.  
  810. CTRL+ENTER                        Small capital letters are used for the 
  811.                                   names of keys on the keyboard. When you 
  812.                                   see a plus sign (+) between two key 
  813.                                   names, you should hold down the first 
  814.                                   key while pressing the second. %@CR:C6A00000019 @%
  815.  
  816.                                   The carriage-return key, sometimes 
  817.                                   marked as a bent arrow on the keyboard, 
  818.                                   is called ENTER.
  819.  
  820. "argument"                        Quotation marks enclose a new term the 
  821.                                   first time it is defined in text. %@CR:C6A00000020 @%
  822.  
  823. %@AS@%"C string"%@AE@%                        Some C constructs, such as strings, 
  824.                                   require quotation marks. Quotation marks
  825.                                   required by the language have the form %@AS@%"%@AE@%
  826.                                   %@AS@%"%@AE@% and %@AS@%' '%@AE@% rather than " " and ' '.
  827.  
  828. Color Graphics Adapter (CGA)      The first time an acronym is used, it is
  829.                                   often spelled out.
  830.  
  831. %@NL@%
  832. %@NL@%
  833. %@NL@%
  834. %@NL@%
  835. %@NL@%
  836. %@CR:C6A-Part 01 @%%@1@%%@AB@%PART I  Overview%@AE@%%@EH@%%@NL@%
  837. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  838. %@NL@%
  839. The first part of this book provides an overview of the run-time library
  840. provided with the Microsoft C Professional Development System.  %@NL@%
  841. %@NL@%
  842. Chapter 1 is a general guide to the use of the run-time library routines.  %@NL@%
  843. %@NL@%
  844. Chapter 2 lists the routines by category.  %@NL@%
  845. %@NL@%
  846. Chapter 3 tells how to access global variables and types defined in the
  847. run-time library.  %@NL@%
  848. %@NL@%
  849. %@NL@%
  850. %@NL@%
  851. %@NL@%
  852. %@NL@%
  853. %@NL@%
  854. %@CR:C6A00010001 @%%@1@%%@AB@%Chapter 1  Using C Library Routines%@AE@%%@EH@%%@NL@%
  855. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  856. %@NL@%
  857. This chapter provides basic information about how to use Microsoft C library
  858. routines. It also describes some special rules, such as file- and path-name
  859. conventions, that apply to particular routines. You should read this chapter
  860. before you begin to use C library routines, and you may also want to refer
  861. back to it if you have questions about library procedures.  %@NL@%
  862. %@NL@%
  863. %@NL@%
  864. %@2@%%@CR:C6A00010002 @%%@AB@%1.1  Calling Library Routines%@AE@%%@EH@%%@NL@%
  865. %@NL@%
  866. To use a C library routine, simply call it in your program, just as if it is
  867. defined there. For instance, suppose you write the following program and
  868. name it SAMPLE.C:  %@NL@%
  869. %@NL@%
  870. %@AS@%  #include <stdio.h>
  871. %@AS@%  main()
  872. %@AS@%  {
  873. %@AS@%     printf( "Microsoft C" );
  874. %@AS@%  }%@AE@%%@NL@%
  875. %@NL@%
  876. The program prints %@AS@% Microsoft C %@AE@% by calling the %@AB@%printf%@AE@% routine, which is
  877. part of the standard C library. Calling a library routine normally involves
  878. two groups of files:  %@NL@%
  879. %@NL@%
  880. %@NL@%
  881.   1.  Header ("include") files that contain declarations and type
  882.       definitions required by library routines %@NL@%
  883. %@NL@%
  884.   2.  Library files that contain the library routines in compiled form%@NL@%
  885. %@NL@%
  886. %@NL@%
  887. Header files and library files are both included with Microsoft C. Header
  888. files are used when compiling, and library files are used when linking.  %@NL@%
  889. %@NL@%
  890. You include the necessary header files in your program source code with
  891. %@AB@%#include%@AE@% directives. The description of each library routine in Part 2,
  892. "Reference," tells you what header file the routine requires. Since %@AB@%printf%@AE@%
  893. requires the STDIO.H header file, the SAMPLE.C program contains the
  894. following line:  %@NL@%
  895. %@NL@%
  896. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  897. %@NL@%
  898. This line causes the compiler to insert the contents of STDIO.H into the
  899. source file SAMPLE.C.  %@NL@%
  900. %@NL@%
  901. After you compile the source file, you link the resulting object (.OBJ) file
  902. with the appropriate library (.LIB) file to create an executable (.EXE)
  903. file. Your object file contains the name of every routine that your program
  904. calls, including library routines. If a routine is not defined in your
  905. program, the linker searches for its code in a library file and includes
  906. that code in the executable file.  %@NL@%
  907. %@NL@%
  908. Normally, the code for standard library routines is contained in the
  909. "default library" that you create when installing Microsoft C. Since the
  910. linker automatically searches the default library, you do not need to
  911. specify that library's name when linking your program. The following command
  912. links the example program with the default library:  %@NL@%
  913. %@NL@%
  914. %@AS@%  link sample,,,;%@AE@%%@NL@%
  915. %@NL@%
  916. If you call a library routine that is not contained in the default library,
  917. you must give the linker the name of the library file that contains the
  918. routine. For instance, suppose your program uses a Microsoft C graphics
  919. routine and you did not make GRAPHICS.LIB part of your default library when
  920. installing Microsoft C. You would then link the program using a line like
  921. the following:  %@NL@%
  922. %@NL@%
  923. %@AS@%  link sample,,, graphics.lib;%@AE@%%@NL@%
  924. %@NL@%
  925. For more information about libraries and linking, consult the installation
  926. documentation for your compiler.  %@NL@%
  927. %@NL@%
  928. %@NL@%
  929. %@2@%%@CR:C6A00010003 @%%@AB@%1.2  Using Header Files%@AE@%%@EH@%%@NL@%
  930. %@NL@%
  931. As stated in the previous section, you should include C header files when
  932. using library routines. This section describes particular reasons why header
  933. files are required.  %@NL@%
  934. %@NL@%
  935. %@NL@%
  936. %@3@%%@CR:C6A00010004 @%%@AB@%1.2.1  Including Necessary Definitions%@AE@%%@EH@%%@NL@%
  937. %@NL@%
  938. Many C library routines use constants, type definitions, or macros defined
  939. in a header file. To use the routine, you must include the header file
  940. containing the needed definition(s). The following list gives examples:  %@NL@%
  941. %@NL@%
  942. %@AB@%Definition%@AE@%                        %@AB@%Example%@AE@%
  943. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  944. Macro                             If a library routine is implemented as a
  945.                                   macro, the macro definition appears in a
  946.                                   header file. For instance, the %@AB@%toupper%@AE@% 
  947.                                   macro is defined in the header file 
  948.                                   CTYPE.H.
  949.  
  950. Manifest constant                 Many library routines refer to constants
  951.                                   that are defined in header files. For 
  952.                                   instance, the %@AB@%open%@AE@% routine uses 
  953.                                   constants such as %@AB@%O_CREAT%@AE@%, which is 
  954.                                   defined in the header file FCNTL.H.
  955.  
  956. Type definition                   Some library routines return a structure
  957.                                   or take a structure as an argument. For 
  958.                                   example, stream input/output routines 
  959.                                   use a structure of type %@AB@%FILE%@AE@%, which is 
  960.                                   defined in STDIO.H.
  961.  
  962. %@NL@%
  963. %@3@%%@CR:C6A00010005 @%%@AB@%1.2.2  Including Function Declarations%@AE@%%@EH@%%@NL@%
  964. %@NL@%
  965. The Microsoft C header files also contain function declarations for every
  966. function in the C library. These declarations are in the style recommended
  967. by the ANSI C standard. Given these declarations, the compiler can perform
  968. "type checking" on every reference to a library function, making sure that
  969. you have used the correct return type and arguments. Function declarations
  970. are sometimes called "prototypes," since the declaration serves as a
  971. prototype or template for every subsequent reference to the function.  %@NL@%
  972. %@NL@%
  973. A function declaration lists the name of the function, its return type, and
  974. the number and type of its arguments. For instance, below is the declaration
  975. of the %@AB@%pow%@AE@% library function from the header file MATH.H:  %@NL@%
  976. %@NL@%
  977. %@AS@%  double pow( double x, double y );%@AE@%%@NL@%
  978. %@NL@%
  979. The example declares that %@AB@%pow%@AE@% returns a value of type %@AB@%double%@AE@% and takes two
  980. arguments of type %@AB@%double%@AE@%. Given this declaration, the compiler can check
  981. every reference to %@AB@%pow%@AE@% in your program to ensure that the reference passes
  982. two %@AB@%double%@AE@% arguments to %@AB@%pow%@AE@% and takes a return value of type %@AB@%double%@AE@%.  %@NL@%
  983. %@NL@%
  984. The compiler can perform type checking only for function references that
  985. appear after the function declaration. Because of this, function
  986. declarations normally appear near the beginning of the source file, prior to
  987. any use of the functions they declare.  %@NL@%
  988. %@NL@%
  989. Function declarations are especially important for functions that return a
  990. value of some type other than %@AB@%int%@AE@%, which is the default. For example, the
  991. %@AB@%pow%@AE@% function returns a %@AB@%double%@AE@% value. If you do not declare such a function,
  992. the compiler treats its return value as %@AB@%int%@AE@%, which can cause unexpected
  993. results.  %@NL@%
  994. %@NL@%
  995. It is also a good practice to provide declarations for functions that you
  996. write. If you do not want to type the declarations by hand, you can generate
  997. them automatically by using the /Zg compiler option. This option causes the
  998. compiler to generate ANSI-standard function declarations for every function
  999. defined in the current source file. Redirect this output to a file, then
  1000. insert the file near the beginning of your source file.  %@NL@%
  1001. %@NL@%
  1002. Your program can contain more than one declaration of the same function, as
  1003. long as the declarations do not conflict. This is important if you have old
  1004. programs whose function declarations do not contain argument-type lists. For
  1005. instance, if your program contains the declaration  %@NL@%
  1006. %@NL@%
  1007. %@AS@%  char *calloc( );%@AE@%%@NL@%
  1008. %@NL@%
  1009. you can later include the following declaration:  %@NL@%
  1010. %@NL@%
  1011. %@AS@%  char *calloc(unsigned, unsigned);%@AE@%%@NL@%
  1012. %@NL@%
  1013. Because the two declarations are compatible, even though they are not
  1014. identical, no conflict occurs. The second declaration simply gives more
  1015. information about function arguments than the second. A conflict would
  1016. arise, however, if the declarations gave a different number of arguments or
  1017. gave arguments of different types.  %@NL@%
  1018. %@NL@%
  1019. Some library functions can take a variable number of arguments. For
  1020. instance, the %@AB@%printf %@AE@%function can take one argument or several. The compiler
  1021. can perform only limited type checking on such functions, a factor that
  1022. affects the following library functions:  %@NL@%
  1023. %@NL@%
  1024. %@NL@%
  1025.   ■   In calls to %@AB@%cprintf%@AE@%, %@AB@%cscanf%@AE@%, %@AB@%printf%@AE@%, and %@AB@%scanf%@AE@%, only the first
  1026.       argument (the format string) is type checked. %@NL@%
  1027. %@NL@%
  1028.   ■   In calls to %@AB@%fprintf%@AE@%, %@AB@%fscanf%@AE@%, %@AB@%sprintf%@AE@%, and %@AB@%sscanf%@AE@%, only the first two
  1029.       arguments (the file or buffer and the format string) are type checked.%@NL@%
  1030. %@NL@%
  1031.   ■   In calls to %@AB@%open%@AE@%, only the first two arguments (the path name and the
  1032.       %@AB@%open%@AE@% flag) are type checked. %@NL@%
  1033. %@NL@%
  1034.   ■   In calls to %@AB@%sopen%@AE@%, only the first three arguments (the path name, the
  1035.       %@AB@%open%@AE@% flag, and the sharing mode) are type checked. %@NL@%
  1036. %@NL@%
  1037.   ■   In calls to %@AB@%execl%@AE@%, %@AB@%execle%@AE@%, %@AB@%execlp%@AE@%, and %@AB@%execlpe%@AE@%, only the first two
  1038.       arguments (the path name and the first argument pointer) are type
  1039.       checked.%@NL@%
  1040. %@NL@%
  1041.   ■   In calls to %@AB@%spawnl%@AE@%, %@AB@%spawnle%@AE@%, %@AB@%spawnlp%@AE@%, and %@AB@%spawnlpe%@AE@%, only the first
  1042.       three arguments (the mode flag, the path name, and the first argument
  1043.       pointer) are type checked.%@NL@%
  1044. %@NL@%
  1045. %@NL@%
  1046. %@NL@%
  1047. %@2@%%@CR:C6A00010006 @%%@AB@%1.3  File Names and Path Names%@AE@%%@EH@%%@NL@%
  1048. %@NL@%
  1049. Many library routines take strings representing paths and file names as
  1050. arguments. If you plan to transport your programs to the XENIX operating
  1051. system, you should remember that XENIX uses file- and path-name conventions
  1052. that are different from those used by DOS and OS/2. If you do not plan to
  1053. transport your programs to XENIX, you can skip this section.  %@NL@%
  1054. %@NL@%
  1055. %@NL@%
  1056. %@4@%%@AB@%Case Sensitivity%@AE@%%@EH@%%@NL@%
  1057. %@NL@%
  1058. The DOS and OS/2 operating systems are not case sensitive (they do not
  1059. distinguish between uppercase and lowercase letters). Thus, SAMPLE.C and
  1060. Sample.C refer to the same file in DOS and OS/2. However, the XENIX
  1061. operating system is case sensitive. In XENIX, SAMPLE.C and Sample.C refer to
  1062. different files. To transport programs to XENIX, choose file and path names
  1063. that work correctly in XENIX, since either case works in DOS and OS/2. For
  1064. instance, the following directives are identical in DOS and OS/2, but only
  1065. the second works in XENIX:  %@NL@%
  1066. %@NL@%
  1067. %@AS@%  #include <STDIO.H>
  1068. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  1069. %@NL@%
  1070. %@NL@%
  1071. %@4@%%@AB@%Subdirectory Conventions%@AE@%%@EH@%%@NL@%
  1072. %@NL@%
  1073. Under XENIX, certain header files are normally placed in a subdirectory
  1074. named SYS. Microsoft C follows this convention to ease the process of
  1075. transporting programs to XENIX. If you do not plan to transport your
  1076. programs, you can place the SYS header files elsewhere.  %@NL@%
  1077. %@NL@%
  1078. %@NL@%
  1079. %@4@%%@AB@%Path-Name Delimiters%@AE@%%@EH@%%@NL@%
  1080. %@NL@%
  1081. XENIX uses the slash (%@AB@%/%@AE@%) in path names, while DOS and OS/2 use the backslash
  1082. (%@AB@%\%@AE@%). To transport programs to XENIX, it is advantageous to use path-name
  1083. delimiters that are compatible with XENIX whenever possible.  %@NL@%
  1084. %@NL@%
  1085. %@NL@%
  1086. %@2@%%@CR:C6A00010007 @%%@AB@%1.4  Choosing Between Functions and Macros%@AE@%%@EH@%%@NL@%
  1087. %@NL@%
  1088. This book uses the words "routine" and "function" interchangeably. However,
  1089. the term "routine" actually encompasses both functions and macros. Because
  1090. functions and macros have different properties, you should pay attention to
  1091. which form you are using. The descriptions in the reference section indicate
  1092. whether routines are implemented as functions or as macros.  %@NL@%
  1093. %@NL@%
  1094. Most routines in the Microsoft C library are functions. They consist of
  1095. compiled C code or assembled Microsoft Macro Assembler (MASM) code. However,
  1096. a few library routines are implemented as macros that behave like functions.
  1097. You can pass arguments to library macros and invoke them in the same way you
  1098. invoke functions.  %@NL@%
  1099. %@NL@%
  1100. The main benefit of using macros is faster execution time. A macro is
  1101. expanded (replaced by its definition) during preprocessing, creating in-line
  1102. code. Thus, macros do not have the overhead associated with function calls.
  1103. On the other hand, each use of a macro inserts the same code in your
  1104. program, whereas a function definition occurs only once regardless of how
  1105. many times it is called. Functions and macros thus offer a trade-off between
  1106. speed and size.  %@NL@%
  1107. %@NL@%
  1108. Apart from speed and size issues, macros and functions have some other
  1109. important differences:  %@NL@%
  1110. %@NL@%
  1111. %@NL@%
  1112.   ■   Some macros treat arguments with side effects incorrectly when the
  1113.       macro evaluates its arguments more than once (see the example that
  1114.       follows this list). Not every macro has this effect. To determine if a
  1115.       macro handles side effects as desired, examine its definition in the
  1116.       appropriate header file.%@NL@%
  1117. %@NL@%
  1118.   ■   A function name evaluates to an address, but a macro name does not.
  1119.       Thus, you cannot use a macro name in contexts requiring a function
  1120.       pointer. For instance, you can declare a pointer to a function, but
  1121.       you cannot declare a pointer to a macro.%@NL@%
  1122. %@NL@%
  1123.   ■   You can declare functions, but you cannot declare macros. Thus, the
  1124.       compiler cannot perform type checking of macro arguments as it does of
  1125.       function arguments. However, the compiler can detect when you pass the
  1126.       wrong number of arguments to a macro.%@NL@%
  1127. %@NL@%
  1128.   ■   You must always include the appropriate header file when using a
  1129.       library macro. Every library macro is defined with a %@AB@%#define%@AE@% directive
  1130.       in a header file. If you do not include the header file, the macro is
  1131.       undefined.%@NL@%
  1132. %@NL@%
  1133. %@NL@%
  1134. The following example demonstrates how some macros can produce unwanted side
  1135. effects. It uses the %@AB@%toupper%@AE@% routine from the standard C library.  %@NL@%
  1136. %@NL@%
  1137. %@AS@%  #include <ctype.h>
  1138. %@AS@%  
  1139. %@AS@%  int a = 'm';
  1140. %@AS@%  a = toupper(a++);%@AE@%%@NL@%
  1141. %@NL@%
  1142. The example increments %@AS@% a %@AE@% when passing it as an argument to the %@AB@%toupper%@AE@%
  1143. routine, which is implemented as a macro. It is defined in CTYPE.H:  %@NL@%
  1144. %@NL@%
  1145. %@AS@%  #define toupper(c)  ( (islower(c)) ? _toupper(c) : (c) )%@AE@%%@NL@%
  1146. %@NL@%
  1147. The definition uses the conditional operator (%@AB@%? :%@AE@%). The conditional
  1148. expression evaluates the argument %@AS@% c %@AE@% twice: once to check if it is
  1149. lowercase and again to create the result. This macro evaluates the argument %@AS@%
  1150. %@AS@%a++ %@AE@% twice, increasing %@AS@% a %@AE@% by 2 instead of 1. As a result, the value
  1151. operated on by %@AB@%islower%@AE@% differs from the value operated on by %@AB@%_toupper%@AE@%.  %@NL@%
  1152. %@NL@%
  1153. Like some other library routines, %@AB@%toupper%@AE@% is provided in both macro and
  1154. function versions. The header file CTYPE.H not only declares the %@AB@%toupper%@AE@%
  1155. function but also defines the %@AB@%toupper%@AE@% macro.  %@NL@%
  1156. %@NL@%
  1157. Choosing between the macro version and function version of such routines is
  1158. easy. If you wish to use the macro version, you can simply include the
  1159. header file that contains the macro definition. Because the macro definition
  1160. of the routine always appears after the function declaration, the macro
  1161. definition normally takes precedence. Thus, if your program includes CTYPE.H
  1162. and then calls %@AB@%toupper%@AE@%, the compiler uses the %@AB@%toupper%@AE@% macro:  %@NL@%
  1163. %@NL@%
  1164. %@AS@%  #include <ctype.h>
  1165. %@AS@%  
  1166. %@AS@%  int a = 'm';
  1167. %@AS@%  a = toupper(a);%@AE@%%@NL@%
  1168. %@NL@%
  1169. You can force the compiler to use the function version of a routine by
  1170. enclosing the routine's name in parentheses:  %@NL@%
  1171. %@NL@%
  1172. %@AS@%  #include <ctype.h>
  1173. %@AS@%  
  1174. %@AS@%  int a = 'm';
  1175. %@AS@%  a = (toupper) (a);%@AE@%%@NL@%
  1176. %@NL@%
  1177. Because the name %@AB@%toupper%@AE@% is not immediately followed by a left parenthesis,
  1178. the compiler cannot interpret it as a macro name. It must use the %@AB@%toupper%@AE@%
  1179. function.  %@NL@%
  1180. %@NL@%
  1181. A second way to do this is to "undefine" the macro definition with the
  1182. %@AB@%#undef%@AE@% directive:  %@NL@%
  1183. %@NL@%
  1184. %@AS@%  #include <ctype.h>
  1185. %@AS@%  #undef toupper%@AE@%%@NL@%
  1186. %@NL@%
  1187. Since the macro definition no longer exists, subsequent references to
  1188. %@AB@%toupper%@AE@% use the function version.  %@NL@%
  1189. %@NL@%
  1190. A third way to make sure the compiler uses the function version is to
  1191. declare the function explicitly:  %@NL@%
  1192. %@NL@%
  1193. %@AS@%  #include <ctype.h>
  1194. %@AS@%  int toupper(int _c);%@AE@%%@NL@%
  1195. %@NL@%
  1196. Since this function declaration appears after the macro definition in
  1197. CTYPE.H, it causes the compiler to use the %@AB@%toupper%@AE@% function.  %@NL@%
  1198. %@NL@%
  1199. %@NL@%
  1200. %@2@%%@CR:C6A00010008 @%%@AB@%1.5  Stack Checking on Entry%@AE@%%@EH@%%@NL@%
  1201. %@NL@%
  1202. For certain library routines, the compiler performs stack checking on entry.
  1203. (The "stack" is a memory area used for temporary storage.) Upon entry to
  1204. such a routine, the stack is checked to determine if it has enough room for
  1205. the local variables used by that routine. If it does, space is allocated by
  1206. adjusting the stack pointer. Otherwise, a "stack overflow" run-time error
  1207. occurs. If stack checking is disabled, the compiler assumes there is enough
  1208. stack space; if there is not, you might overwrite memory locations in the
  1209. data segment and receive no warning.  %@NL@%
  1210. %@NL@%
  1211. Typically, stack checking is enabled only for functions with large
  1212. local-variable requirements (more than about 150 bytes), since there is
  1213. enough free space between the stack and data segments to handle functions
  1214. with smaller requirements. If the function is called many times, stack
  1215. checking slows execution slightly.  %@NL@%
  1216. %@NL@%
  1217. Stack checking is enabled for the following library functions:  %@NL@%
  1218. %@NL@%
  1219. %@AB@%execvp          printf          spawnvpe        system%@AE@%
  1220. %@AB@%execvpe         scanf           sprintf         vprintf%@AE@%
  1221. %@AB@%fprintf         spawnvp         sscanf          write %@AE@%
  1222. %@AB@%fscanf          
  1223.  
  1224. %@2@%%@CR:C6A00010009 @%%@AB@%1.6  Handling Errors%@AE@%%@EH@%%@NL@%
  1225. %@NL@%
  1226. Many library routines return a value that indicates an error condition. To
  1227. avoid unexpected results, your code should always check such error values
  1228. and handle all of the possible error conditions. The description of each
  1229. library routine in the reference section lists the routine's return
  1230. value(s).  %@NL@%
  1231. %@NL@%
  1232. Some library functions do not have a set error return. These include
  1233. functions that return nothing and functions whose range of return values
  1234. makes it impossible to return a unique error value. To aid in error
  1235. handling, some functions in this category set the value of a global variable
  1236. named %@AB@%errno%@AE@%.  %@NL@%
  1237. %@NL@%
  1238. If the reference description of a routine states that it sets the %@AB@%errno%@AE@%
  1239. variable, you can use %@AB@%errno%@AE@% in two ways:  %@NL@%
  1240. %@NL@%
  1241. %@NL@%
  1242.   1.  Compare %@AB@%errno%@AE@% to the values defined in the header file ERRNO.H.%@NL@%
  1243. %@NL@%
  1244.   2.  Handle %@AB@%errno%@AE@% with the %@AB@%perror%@AE@% or %@AB@%strerror%@AE@% library routines. The %@AB@%perror%@AE@%
  1245.       routine prints a system error message to the standard error (%@AB@%stderr%@AE@%).
  1246.       The %@AB@%strerror%@AE@% routine stores the same information in a string for later
  1247.       use.%@NL@%
  1248. %@NL@%
  1249. %@NL@%
  1250. When you use %@AB@%errno%@AE@%, %@AB@%perror%@AE@%, and %@AB@%strerror%@AE@%, remember that the value of %@AB@%errno%@AE@%
  1251. reflects the error value for the last call that set %@AB@%errno%@AE@%. To avoid
  1252. confusion, you should always test the return value to verify that an error
  1253. actually occurred. Once you determine that an error has occurred, use %@AB@%errno%@AE@%
  1254. or %@AB@%perror%@AE@% immediately. Otherwise, the value of %@AB@%errno%@AE@% may be changed by
  1255. intervening calls.  %@NL@%
  1256. %@NL@%
  1257. Library math routines set %@AB@%errno%@AE@% by calling the %@AB@%matherr%@AE@% or %@AB@%_matherrl%@AE@% library
  1258. routines, which are described in the reference section. If you wish to
  1259. handle math errors differently from these routines, you can write your own
  1260. routine and name it %@AB@%matherr%@AE@% or %@AB@%_matherrl%@AE@%. Your routine must follow the rules
  1261. listed in the %@AB@%matherr%@AE@% reference description.  %@NL@%
  1262. %@NL@%
  1263. The %@AB@%ferror%@AE@% library routine allows you to check for errors in stream
  1264. input/output operations. This routine checks if an error indicator has been
  1265. set for a given stream. Closing or rewinding the stream automatically clears
  1266. the error indicator. You can also reset the error indicator by calling the
  1267. %@AB@%clearerr%@AE@% library routine.  %@NL@%
  1268. %@NL@%
  1269. The %@AB@%feof%@AE@% library routine tests for end-of-file on a given stream. An
  1270. end-of-file condition in low-level input and output can be detected with the
  1271. %@AB@%eof%@AE@% routine or when a %@AB@%read%@AE@% operation returns 0 as the number of bytes read.
  1272. %@NL@%
  1273. %@NL@%
  1274. The %@AB@%_grstatus%@AE@% library routine allows you to check for errors after calling
  1275. certain graphics library operations. See the reference page on the %@AB@%_grstatus%@AE@%
  1276. function for details.  %@NL@%
  1277. %@NL@%
  1278. %@NL@%
  1279. %@2@%%@CR:C6A00010010 @%%@AB@%1.7  Operating-System Considerations%@AE@%%@EH@%%@NL@%
  1280. %@NL@%
  1281. The library routines listed in this section behave differently under
  1282. different operating system versions. For more information on an individual
  1283. routine, see the description of that routine in the reference section.  %@NL@%
  1284. %@NL@%
  1285. %@AB@%Routine%@AE@%                           %@AB@%Restrictions%@AE@%
  1286. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1287. %@AB@%locking%@AE@%                           These routines are effective only in 
  1288. %@AB@%sopen%@AE@%                             OS/2 and in DOS versions 3.0 and later.
  1289. %@AB@%_fsopen%@AE@%                           
  1290.  
  1291. %@AB@%dosexterr%@AE@%                         The %@AB@%dosexterr%@AE@% routine provides error 
  1292.                                   handling for system call 0x59 (get 
  1293.                                   extended error) in DOS versions 3.0 and 
  1294.                                   later.
  1295.  
  1296. %@AB@%dup%@AE@%                               The %@AB@%dup%@AE@% and %@AB@%dup2%@AE@% routines can cause 
  1297. %@AB@%dup2%@AE@%                              unexpected results in DOS versions 
  1298.                                   earlier than 3.0. If you use %@AB@%dup%@AE@% or %@AB@%dup2%@AE@%
  1299.                                   to create a duplicate file handle for %@AB@%%@AE@%
  1300.                                   %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, %@AB@%stderr%@AE@%, %@AB@%stdaux%@AE@%, or %@AB@%stdprn%@AE@%
  1301.                                   , calling the %@AB@%close%@AE@% function with one 
  1302.                                   handle causes errors in later I/O 
  1303.                                   operations that use the other handle. 
  1304.                                   This anomaly does not occur in OS/2 or 
  1305.                                   in DOS versions 3.0 and later.
  1306.  
  1307. %@AB@%exec%@AE@%                              When using the %@AB@%exec%@AE@% and %@AB@%spawn%@AE@% families 
  1308. %@AB@%spawn%@AE@%                             of functions under DOS versions earlier 
  1309.                                   than 3.0, the value of the %@AI@%arg0%@AE@% argument
  1310.                                   (or %@AI@%argv%@AE@%[0] to the child process) is not
  1311.                                   available to the user; a null string (%@AS@%""%@AE@%
  1312.                                   ) is stored in that position instead. In
  1313.                                   OS/2, the %@AI@%arg0%@AE@% argument contains the 
  1314.                                   command name; in DOS versions 3.0 and 
  1315.                                   later, it contains the complete command 
  1316.                                   path.
  1317.  
  1318. Microsoft C defines global variables that indicate the version of the
  1319. current operating system. You can use these to determine the
  1320. operating-system version in which a program is executing. See Chapter 3,
  1321. "Global Variables and Standard Types," for more information.  %@NL@%
  1322. %@NL@%
  1323. %@NL@%
  1324. %@2@%%@CR:C6A00010011 @%%@AB@%1.8  Floating-Point Support%@AE@%%@EH@%%@NL@%
  1325. %@NL@%
  1326. Microsoft math library routines require floating-point support to perform
  1327. calculations with real numbers (numbers that can contain fractions). This
  1328. support can be provided by the floating-point libraries that accompany your
  1329. compiler software or by an 8087, 80287, or 80387 coprocessor. The names of
  1330. the functions that require floating-point support are listed below:  %@NL@%
  1331. %@NL@%
  1332. %@AB@%acos            cos             fmod            modfl%@AE@%
  1333. %@AB@%acosl           cosl            fmodl           pow%@AE@%
  1334. %@AB@%asin            cosh            fmsbintoieee    powl%@AE@%
  1335. %@AB@%asinl           coshl           _fpreset        sin%@AE@%
  1336. %@AB@%atan            dieeetomsbin    frexp           sinl%@AE@%
  1337. %@AB@%atanl           difftime        frexpl          sinh%@AE@%
  1338. %@AB@%atan2           dmsbintoieee    gcvt            sinhl%@AE@%
  1339. %@AB@%atan2l          ecvt            hypot           sqrt%@AE@%
  1340. %@AB@%atof            exp             hypotl          sqrtl%@AE@%
  1341. %@AB@%_atold          expl            ldexp           _status87%@AE@%
  1342. %@AB@%bessel          fabs            ldexpl          strtod%@AE@%
  1343. %@AB@%cabs            fabsl           log             _strtold%@AE@%
  1344. %@AB@%cabsl           fcvt            logl            tan%@AE@%
  1345. %@AB@%ceil            fieeetomsbin    log10           tanl%@AE@%
  1346. %@AB@%ceill           floor           log10l          tanh%@AE@%
  1347. %@AB@%_clear87        floorl          modf            tanhl%@AE@%
  1348. %@AB@%_control87      
  1349.  
  1350. Note that the %@AB@%bessel%@AE@% routine does not correspond to a single function, but
  1351. to twelve functions named %@AB@%j0%@AE@%, %@AB@%j1%@AE@%, %@AB@%jn%@AE@%, %@AB@%y0%@AE@%, %@AB@%y1%@AE@%, %@AB@%yn%@AE@%, %@AB@%_j0l%@AE@%, %@AB@%_j1l%@AE@%, %@AB@%_jnl%@AE@%, %@AB@%_y0l%@AE@%,
  1352. %@AB@%_y1l%@AE@%, and %@AB@%_ynl%@AE@%. Also note that the %@AB@%_clear87%@AE@% and %@AB@%_control87%@AE@% functions are not
  1353. available with the /FPa compiler option.  %@NL@%
  1354. %@NL@%
  1355. Also requiring floating-point support is the %@AB@%printf%@AE@% family of functions
  1356. (%@AB@%cprintf%@AE@%, %@AB@%fprintf%@AE@%, %@AB@%printf%@AE@%, %@AB@%sprintf%@AE@%, %@AB@%vfprintf%@AE@%, %@AB@%vprintf%@AE@%, and %@AB@%vsprintf%@AE@%). These
  1357. functions require support for floating-point input and output if used to
  1358. print floating-point values.  %@NL@%
  1359. %@NL@%
  1360. The C compiler tries to detect whether floating-point values are used in a
  1361. program so that supporting functions are loaded only if required. This
  1362. behavior saves a considerable amount of space for programs that do not
  1363. require floating-point support.  %@NL@%
  1364. %@NL@%
  1365. When you use a floating-point type specifier in the format string for a
  1366. %@AB@%printf%@AE@% or %@AB@%scanf%@AE@% call, make sure you specify floating-point values or
  1367. pointers to floating-point values in the argument list. These must
  1368. correspond to any floating-point  %@NL@%
  1369. %@NL@%
  1370. type specifiers in the format string. The presence of floating-point
  1371. arguments allows the compiler to detect that floating-point support code is
  1372. required. If a floating-point type specifier is used to print an integer
  1373. argument, for example, floating-point values will not be detected because
  1374. the compiler does not actually read the format string used in the %@AB@%printf%@AE@% and
  1375. %@AB@%scanf%@AE@% functions. For instance, the following program produces an error at
  1376. run time:  %@NL@%
  1377. %@NL@%
  1378. %@AS@%  main( ) /* This example causes an error */
  1379. %@AS@%   {
  1380. %@AS@%    long f = 10L;
  1381. %@AS@%    printf("%f", f);
  1382. %@AS@%   }%@AE@%%@NL@%
  1383. %@NL@%
  1384. In the preceding example, the functions for floating-point support are not
  1385. loaded because  %@NL@%
  1386. %@NL@%
  1387. %@NL@%
  1388.   ■   No floating-point arguments are given in the call to %@AB@%printf%@AE@%.%@NL@%
  1389. %@NL@%
  1390.   ■   No floating-point values are used elsewhere in the program.%@NL@%
  1391. %@NL@%
  1392. %@NL@%
  1393. As a result, the following error occurs:  %@NL@%
  1394. %@NL@%
  1395. %@AS@%  Floating point not loaded%@AE@%%@NL@%
  1396. %@NL@%
  1397. Here is a corrected version of the above call to %@AB@%printf%@AE@% in which the long
  1398. integer value is cast to %@AB@%double%@AE@%:  %@NL@%
  1399. %@NL@%
  1400. %@AS@%  main( ) /* This example works correctly */
  1401. %@AS@%   {
  1402. %@AS@%    long f = 10L;
  1403. %@AS@%    printf("%f", (double) f);
  1404. %@AS@%   }%@AE@%%@NL@%
  1405. %@NL@%
  1406. %@NL@%
  1407. %@2@%%@CR:C6A00010012 @%%@AB@%1.9  Using Huge Arrays with Library Functions%@AE@%%@EH@%%@NL@%
  1408. %@NL@%
  1409. In programs that use small, compact, medium, and large memory models,
  1410. Microsoft C allows you to use arrays exceeding the 64K (kilobyte) limit of
  1411. physical memory in these models by explicitly declaring the arrays as %@AB@%_huge%@AE@%.
  1412. However, generally, you cannot pass %@AB@%_huge%@AE@% data items as arguments to C
  1413. library functions. In the compact-model library used by compact-model
  1414. programs and in the large-model library used by both large-model and
  1415. huge-model programs, only the functions listed below use argument arithmetic
  1416. that works with %@AB@%_huge%@AE@% items:  %@NL@%
  1417. %@NL@%
  1418. %@AB@%bsearch         _fmemcmp        _fmemset        lsearch%@AE@%
  1419. %@AB@%fread           _fmemcpy        halloc          memccpy%@AE@%
  1420. %@AB@%fwrite          _fmemicmp       hfree           memchr%@AE@%
  1421. %@AB@%_fmemccpy       _fmemmove       lfind           %@AE@%
  1422. %@AB@%_fmemchr        
  1423.  
  1424. With this set of functions, you can read from, write to, search, sort, copy,
  1425. initialize, compare, or dynamically allocate and free %@AB@%_huge%@AE@% arrays; the
  1426. %@AB@%_huge%@AE@% array can be passed without difficulty to any of these functions in a
  1427. compact-, large-, or huge-model program. The model-independent routines in
  1428. the above list (those beginning with %@AB@%_f%@AE@%) are available in all memory models.
  1429. %@NL@%
  1430. %@NL@%
  1431. The %@AB@%memset%@AE@%, %@AB@%memcpy%@AE@%, and %@AB@%memcmp%@AE@%library routines are available in two
  1432. versions: as C functions and as intrinsic (in-line) code. The function
  1433. versions of these routines support huge pointers in compact and large memory
  1434. models, but the intrinsic versions do not support huge pointers. (The
  1435. function version of such routines generates a call to a library function,
  1436. whereas the intrinsic version inserts in-line code into your program. Your
  1437. compiler documentation explains how to select the intrinsic versions of
  1438. library routines.) %@NL@%
  1439. %@NL@%
  1440. %@NL@%
  1441. %@NL@%
  1442. %@NL@%
  1443. %@CR:C6A00020001 @%%@1@%%@AB@%Chapter 2  Run-Time Routines by Category%@AE@%%@EH@%%@NL@%
  1444. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1445. %@NL@%
  1446. Microsoft C library routines handle various kinds of tasks. If you know the
  1447. type of task you need done, but don't know exactly which routine to use, the
  1448. categorized lists of routines in this chapter can help.  %@NL@%
  1449. %@NL@%
  1450. The descriptions here are intended only to give you a brief overview of the
  1451. capabilities of the run-time library. For a complete description of the
  1452. behavior, syntax, and use of each routine, see Part 2, "Run-Time Functions."
  1453. %@NL@%
  1454. %@NL@%
  1455. The main categories of library routines are  %@NL@%
  1456. %@NL@%
  1457. %@NL@%
  1458.   ■   Buffer manipulation%@NL@%
  1459. %@NL@%
  1460.   ■   Character classification and conversion%@NL@%
  1461. %@NL@%
  1462.   ■   Data conversion%@NL@%
  1463. %@NL@%
  1464.   ■   Directory control%@NL@%
  1465. %@NL@%
  1466.   ■   File handling%@NL@%
  1467. %@NL@%
  1468.   ■   Graphics%@NL@%
  1469. %@NL@%
  1470.   ■   Input and output%@NL@%
  1471. %@NL@%
  1472.   ■   Internationalization%@NL@%
  1473. %@NL@%
  1474.   ■   Math%@NL@%
  1475. %@NL@%
  1476.   ■   Memory allocation%@NL@%
  1477. %@NL@%
  1478.   ■   Process and environment control%@NL@%
  1479. %@NL@%
  1480.   ■   Searching and sorting%@NL@%
  1481. %@NL@%
  1482.   ■   String manipulation%@NL@%
  1483. %@NL@%
  1484.   ■   System calls%@NL@%
  1485. %@NL@%
  1486.   ■   Time%@NL@%
  1487. %@NL@%
  1488.   ■   Variable-length argument lists%@NL@%
  1489. %@NL@%
  1490. %@NL@%
  1491. %@NL@%
  1492. %@2@%%@CR:C6A00020002 @%%@AB@%2.1  Buffer Manipulation%@AE@%%@EH@%%@NL@%
  1493. %@NL@%
  1494. The buffer-manipulation routines are useful for working with areas of memory
  1495. on a character-by-character basis. A "buffer" is an array of characters,
  1496. similar to a character string. However, unlike strings, buffers are not
  1497. usually terminated with a null character (%@AB@%'\0'%@AE@%). Therefore, the
  1498. buffer-manipulation routines always take a %@AI@%length%@AE@% or %@AI@%count%@AE@% argument.
  1499. Function declarations for the buffermanipulation routines are given in the
  1500. include files MEMORY.H and STRING.H, with an exception being the %@AB@%swab%@AE@%
  1501. function, which appears in STDLIB.H.%@CR:C6A00020003 @%%@CR:C6A00020004 @%  %@NL@%
  1502. %@NL@%
  1503. Routines beginning with %@AB@%_f%@AE@%  are model independent; the %@AB@%_f%@AE@%  stands for %@AB@%far%@AE@%.
  1504. These routines are useful in writing mixed-model programs because they can
  1505. be called from any program, regardless of the memory model being used.%@CR:C6A00020005 @%  %@NL@%
  1506. %@NL@%
  1507. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1508. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1509. %@AB@%memccpy%@AE@%,  %@AB@%_fmemccpy%@AE@%               Copy characters from one buffer to 
  1510.                                   another until a given character or a 
  1511.                                   given number of characters has been 
  1512.                                   copied %@CR:C6A00020006 @% %@CR:C6A00020007 @%
  1513.  
  1514. %@AB@%memchr%@AE@%,  %@AB@%_fmemchr%@AE@%                 Return a pointer to the first 
  1515.                                   occurrence, within a specified number of
  1516.                                   characters, of a given character in the 
  1517.                                   buffer %@CR:C6A00020008 @% %@CR:C6A00020009 @%
  1518.  
  1519. %@AB@%memcmp%@AE@%,  %@AB@%_fmemcmp%@AE@%                 Compare a specified number of characters
  1520.                                   from two buffers %@CR:C6A00020010 @% %@CR:C6A00020011 @%
  1521.  
  1522. %@AB@%memcpy%@AE@%,  %@AB@%_fmemcpy%@AE@%                 Copy a specified number of characters 
  1523.                                   from one buffer to another %@CR:C6A00020012 @% %@CR:C6A00020013 @%
  1524.  
  1525. %@AB@%memicmp%@AE@%, %@AB@%_fmemicmp%@AE@%                Compare a specified number of characters
  1526.                                   from two buffers without regard to the 
  1527.                                   case of the letters (uppercase and 
  1528.                                   lowercase treated as equivalent) %@CR:C6A00020014 @% %@CR:C6A00020015 @%
  1529.  
  1530. %@AB@%memmove%@AE@%,%@AB@%%@AE@%                          Copy a specified number of characters 
  1531. %@AB@%_fmemmove%@AE@%                         from one buffer to another %@CR:C6A00020016 @% %@CR:C6A00020017 @%
  1532.  
  1533. %@AB@%memset%@AE@%,  %@AB@%_fmemset%@AE@%                 Use a given character to initialize a 
  1534.                                   specified number of bytes in the buffer %@CR:C6A00020018 @%
  1535.                                   %@CR:C6A00020019 @%
  1536.  
  1537. %@AB@%swab%@AE@%                              Swaps bytes of data and stores them at 
  1538.                                   the specified location
  1539.  
  1540. When the source and target areas overlap, only the %@AB@%memmove%@AE@% and %@AB@%_fmemmove%@AE@%
  1541. functions are guaranteed to copy the full source properly. (The %@AB@%memcpy%@AE@% and
  1542. %@AB@%_fmemcpy%@AE@% routines do not always copy the full source in such cases.)  %@NL@%
  1543. %@NL@%
  1544. %@NL@%
  1545. %@2@%%@CR:C6A00020020 @%%@AB@%2.2  Character Classification and Conversion%@AE@%%@EH@%%@NL@%
  1546. %@NL@%
  1547. The character classification and conversion routines allow you to test
  1548. individual characters in a variety of ways and to convert between uppercase
  1549. and lowercase characters.  %@NL@%
  1550. %@NL@%
  1551. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1552. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1553. %@AB@%isalnum%@AE@%%@CR:C6A00020021 @%%@CR:C6A00020022 @%                           Tests for alphanumeric character
  1554.  
  1555. %@AB@%isalpha%@AE@%                           Tests for alphabetic character
  1556.  
  1557. %@AB@%isascii%@AE@%                           Tests for ASCII character
  1558.  
  1559. %@AB@%iscntrl%@AE@%                           Tests for control character
  1560.  
  1561. %@AB@%isdigit%@AE@%                           Tests for decimal digit
  1562.  
  1563. %@AB@%isgraph%@AE@%                           Tests for printable character except 
  1564.                                   space
  1565.  
  1566. %@AB@%islower%@AE@%%@CR:C6A00020023 @%%@CR:C6A00020024 @%                           Tests for lowercase character
  1567.  
  1568. %@AB@%isprint%@AE@%%@CR:C6A00020025 @%%@CR:C6A00020026 @%                           Tests for printable character
  1569.  
  1570. %@AB@%ispunct%@AE@%%@CR:C6A00020027 @%%@CR:C6A00020028 @%                           Tests for punctuation character
  1571.  
  1572. %@AB@%isspace%@AE@%%@CR:C6A00020029 @%%@CR:C6A00020030 @%                           Tests for white-space character
  1573.  
  1574. %@AB@%isupper%@AE@%%@CR:C6A00020031 @%                           Tests for uppercase character
  1575.  
  1576. %@AB@%isxdigit%@AE@%%@CR:C6A00020032 @%                          Tests for hexadecimal digit
  1577.  
  1578. %@AB@%toascii%@AE@% %@CR:C6A00020033 @%%@CR:C6A00020034 @%                          Converts character to ASCII code
  1579.  
  1580. %@AB@%tolower%@AE@%%@CR:C6A00020035 @%                           Tests character and converts to 
  1581.                                   lowercase if uppercase%@CR:C6A00020036 @%%@CR:C6A00020037 @% %@CR:C6A00020038 @%
  1582.  
  1583. %@AB@%_tolower%@AE@%                          Converts character to lowercase 
  1584.                                   (unconditional)
  1585.  
  1586. %@AB@%toupper%@AE@%                           Tests character and converts to 
  1587.                                   uppercase if
  1588.                                   lowercase
  1589.  
  1590. %@AB@%_toupper%@AE@%                          Converts character to uppercase 
  1591.                                   (unconditional)
  1592.  
  1593. The classification routines identify characters by finding them in a table
  1594. of classification codes. Using these routines to classify characters is
  1595. generally faster than writing a test expression such as the following:  %@NL@%
  1596. %@NL@%
  1597. %@AS@%  if ((c >= 0) || c <= 0x7f))%@AE@%%@NL@%
  1598. %@NL@%
  1599. All of these routines are implemented in two versions: as functions and as
  1600. macros. The function prototypes and macro definitions appear in CTYPE.H.
  1601. Section 1.4, "Choosing Between Functions and Macros," explains how to choose
  1602. the appropriate version. The %@AB@%toupper%@AE@% and %@AB@%tolower%@AE@% functions are also declared
  1603. in the STDLIB.H header file.%@CR:C6A00020039 @%%@CR:C6A00020040 @%%@CR:C6A00020041 @%  %@NL@%
  1604. %@NL@%
  1605. %@NL@%
  1606. %@2@%%@CR:C6A00020042 @%%@AB@%2.3  Data Conversion%@CR:C6A00020043 @% %@CR:C6A00020044 @%%@CR:C6A00020045 @%%@AE@%%@EH@%%@NL@%
  1607. %@NL@%
  1608. The data-conversion routines convert numbers to strings of ASCII characters
  1609. and vice versa. These routines are implemented as functions, all of which
  1610. are declared in the include file STDLIB.H. The %@AB@%atof%@AE@% function, which converts
  1611. a string to a floating-point value, is also declared in MATH.H.  %@NL@%
  1612. %@NL@%
  1613. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1614. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1615. %@AB@%abs%@AE@%                               Finds absolute value of integer
  1616.  
  1617. %@AB@%atof%@AE@%%@CR:C6A00020046 @%%@CR:C6A00020047 @%                              Converts string to %@AB@%float%@AE@%
  1618.  
  1619. %@AB@%atoi%@AE@%%@CR:C6A00020048 @%                              Converts string to %@AB@%int%@AE@%
  1620.  
  1621. %@AB@%atol%@AE@%                              Converts string to %@AB@%long%@AE@%
  1622.  
  1623. %@AB@%_atold%@AE@%                            Converts string to %@AB@%long double%@AE@%
  1624.  
  1625. %@AB@%ecvt%@AE@%%@CR:C6A00020049 @%%@CR:C6A00020050 @%                              Converts %@AB@%double%@AE@% to string
  1626.  
  1627. %@AB@%fcvt%@AE@%%@CR:C6A00020051 @%%@CR:C6A00020052 @%                              Converts %@AB@%double%@AE@% to string
  1628.  
  1629. %@AB@%gcvt%@AE@%%@CR:C6A00020053 @%%@CR:C6A00020054 @%                              Converts %@AB@%double%@AE@% to string
  1630.  
  1631. %@AB@%itoa%@AE@%%@CR:C6A00020055 @%%@CR:C6A00020056 @%                              Converts %@AB@%int%@AE@% to string
  1632.  
  1633. %@AB@%labs%@AE@%                              Finds absolute value of %@AB@%long%@AE@% integer
  1634.  
  1635. %@AB@%ltoa%@AE@%%@CR:C6A00020057 @%%@CR:C6A00020058 @%                              Converts %@AB@%long%@AE@% to string
  1636.  
  1637. %@AB@%strtod%@AE@%%@CR:C6A00020059 @%                            Converts string to %@AB@%double%@AE@%
  1638.  
  1639. %@AB@%strtol%@AE@%%@CR:C6A00020060 @%%@CR:C6A00020061 @%                            Converts string to a %@AB@%long%@AE@% integer
  1640.  
  1641. %@AB@%_strtold%@AE@%                          Converts string to %@AB@%long double%@AE@%
  1642.  
  1643. %@AB@%strtoul%@AE@%%@CR:C6A00020062 @%                           Converts string to an %@AB@%unsigned long%@AE@% 
  1644.                                   integer
  1645.  
  1646. %@AB@%ultoa%@AE@%%@CR:C6A00020063 @%%@CR:C6A00020064 @%                             Converts %@AB@%unsigned long%@AE@% to string
  1647.  
  1648. %@NL@%
  1649. %@2@%%@CR:C6A00020065 @%%@AB@%2.4  Directory Control%@CR:C6A00020066 @%%@AE@%%@EH@%%@NL@%
  1650. %@NL@%
  1651. The directory-control routines let a program access, modify, and obtain
  1652. information about the directory structure. These routines are functions and
  1653. are declared in DIRECT.H.%@CR:C6A00020067 @%  %@NL@%
  1654. %@NL@%
  1655. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1656. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1657. %@AB@%chdir%@AE@%%@CR:C6A00020068 @%%@CR:C6A00020069 @%%@CR:C6A00020070 @%                             Changes current working directory
  1658.  
  1659. %@AB@%_chdrive%@AE@%                          Changes current drive
  1660.  
  1661. %@AB@%getcwd%@AE@%%@CR:C6A00020071 @%%@CR:C6A00020072 @%                            Gets current working directory
  1662.  
  1663. %@AB@%_getdcwd%@AE@%                          Gets current working directory for the 
  1664.                                   specified drive
  1665.  
  1666. %@AB@%_getdrive%@AE@%                         Gets the current disk drive
  1667.  
  1668. %@AB@%mkdir%@AE@%%@CR:C6A00020073 @%%@CR:C6A00020074 @%                             Makes a new directory
  1669.  
  1670. %@AB@%rmdir%@AE@%%@CR:C6A00020075 @%%@CR:C6A00020076 @%                             Removes a directory
  1671.  
  1672. %@AB@%_searchenv%@AE@%                        Searches for a given file on specified 
  1673.                                   paths
  1674.  
  1675. %@NL@%
  1676. %@2@%%@CR:C6A00020077 @%%@AB@%2.5  File Handling%@AE@%%@EH@%%@NL@%
  1677. %@NL@%
  1678. The file-handling routines let you create, manipulate, and delete files.
  1679. They also set and check file-access permissions.  %@NL@%
  1680. %@NL@%
  1681. File-handling routines work on a file designated by a path name or by a
  1682. "file handle," an integer assigned by the operating system that identifies
  1683. an open file. These routines modify or give information about the designated
  1684. file. Most of them are declared in the include file IO.H, with the
  1685. exceptions being the %@AB@%fstat%@AE@% and %@AB@%stat%@AE@% functions (declared in SYS\STAT.H), the
  1686. %@AB@%_fullpath%@AE@% routine (declared in DIRECT.H), and the %@AB@%remove%@AE@% and %@AB@%rename%@AE@%
  1687. functions (also declared in STDIO.H).%@CR:C6A00020078 @%%@CR:C6A00020079 @%%@CR:C6A00020080 @%%@CR:C6A00020081 @%  %@NL@%
  1688. %@NL@%
  1689. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1690. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1691. %@AB@%access%@AE@%%@CR:C6A00020082 @%                            Checks file-permission setting
  1692.  
  1693. %@AB@%chmod%@AE@%%@CR:C6A00020083 @%%@CR:C6A00020084 @%                             Changes file-permission setting
  1694.  
  1695. %@AB@%chsize%@AE@% %@CR:C6A00020085 @%%@CR:C6A00020086 @%                           Changes file size
  1696.  
  1697. %@AB@%filelength%@AE@%%@CR:C6A00020087 @%%@CR:C6A00020088 @%                        Gets file length
  1698.  
  1699. %@AB@%fstat%@AE@%%@CR:C6A00020089 @%%@CR:C6A00020090 @%                             Gets file-status information on handle
  1700.  
  1701. %@AB@%_fullpath%@AE@%                         Makes an absolute path name from a 
  1702.                                   relative path name
  1703.  
  1704. %@AB@%isatty%@AE@% %@CR:C6A00020091 @%%@CR:C6A00020092 @%                           Checks for character device
  1705.  
  1706. %@AB@%locking%@AE@%%@CR:C6A00020093 @%%@CR:C6A00020094 @%                           Locks areas of file (available with OS/2
  1707.                                   and
  1708.                                   DOS versions 3.0 and later)
  1709.  
  1710. %@AB@%_makepath%@AE@%                         Merges path-name components into a 
  1711.                                   single, full path name
  1712.  
  1713. %@AB@%mktemp%@AE@%%@CR:C6A00020095 @%%@CR:C6A00020096 @%                            Creates unique file name
  1714.  
  1715. %@AB@%remove%@AE@%%@CR:C6A00020097 @%%@CR:C6A00020098 @%                            Deletes file
  1716.  
  1717. %@AB@%rename%@AE@%%@CR:C6A00020099 @%%@CR:C6A00020100 @%                            Renames file
  1718.  
  1719. %@AB@%setmode%@AE@%%@CR:C6A00020101 @%%@CR:C6A00020102 @%                           Sets file-translation mode
  1720.  
  1721. %@AB@%_splitpath%@AE@%                        Splits a path name into component pieces
  1722.  
  1723. %@AB@%stat%@AE@%%@CR:C6A00020103 @%%@CR:C6A00020104 @%                              Gets file-status information on named 
  1724.                                   file
  1725.  
  1726. %@AB@%umask%@AE@%%@CR:C6A00020105 @%%@CR:C6A00020106 @%                             Sets default-permission mask
  1727.  
  1728. %@AB@%unlink%@AE@%%@CR:C6A00020107 @%%@CR:C6A00020108 @%                            Deletes file
  1729.  
  1730. The %@AB@%access%@AE@%, %@AB@%chmod%@AE@%, %@AB@%_fullpath%@AE@%, %@AB@%_makepath%@AE@%, %@AB@%remove%@AE@%, %@AB@%rename%@AE@%, %@AB@%_splitpath%@AE@%, %@AB@%stat%@AE@%,
  1731. and %@AB@%unlink%@AE@% routines operate on files specified by a path name or file name.%@CR:C6A00020109 @%
  1732. %@NL@%
  1733. %@NL@%
  1734. The %@AB@%chsize%@AE@%, %@AB@%filelength%@AE@%, %@AB@%fstat%@AE@%,%@AB@% isatty%@AE@%, %@AB@%locking%@AE@%, and %@AB@%setmode%@AE@% routines work
  1735. with files designated by a file handle.  %@NL@%
  1736. %@NL@%
  1737. The %@AB@%mktemp%@AE@% and %@AB@%umask%@AE@% routines have functions that are slightly different
  1738. from the other routines. The %@AB@%mktemp%@AE@% routine creates a unique file name, and
  1739. the programmer can use %@AB@%mktemp%@AE@% to create unique file names that do not
  1740. conflict with the names of existing files. The %@AB@%umask%@AE@% routine sets the
  1741. default permission mask for any new files created in a program. The mask can
  1742. override the permission setting given in the %@AB@%open%@AE@% or %@AB@%creat%@AE@% call for the new
  1743. file.  %@NL@%
  1744. %@NL@%
  1745. %@NL@%
  1746. %@2@%%@CR:C6A00020110 @%%@AB@%2.6  Graphics%@AE@%%@EH@%%@NL@%
  1747. %@NL@%
  1748. Microsoft C graphics routines offer a wide variety of graphics functions,
  1749. low-level graphics primitives, font functions, and presentation graphics
  1750. (displays such as graphs and pie charts).  %@NL@%
  1751. %@NL@%
  1752. Graphics functions are supplied in two libraries that must be explicitly
  1753. linked with your program. The GRAPHICS.LIB library provides support for
  1754. low-level graphics and character-font routines. The library PGCHART.LIB
  1755. supports presentation-graphics routines.  %@NL@%
  1756. %@NL@%
  1757. %@NL@%
  1758. %@3@%%@CR:C6A00020111 @%%@AB@%2.6.1  Low-Level Graphics and Character-Font Functions%@AE@%%@EH@%%@NL@%
  1759. %@NL@%
  1760. The low-level graphics and font functions are declared in the include file
  1761. GRAPH.H.  %@NL@%
  1762. %@NL@%
  1763. The library can be divided into the eight categories listed below, which
  1764. correspond to the different tasks involved in creating and manipulating
  1765. graphic objects.  %@NL@%
  1766. %@NL@%
  1767. Most graphics routines work only in DOS. Two categories of routines
  1768. ("configuring mode and environment" and "creating text output") work in OS/2
  1769. as well as DOS.  %@NL@%
  1770. %@NL@%
  1771. %@AB@%Category%@AE@%                          %@AB@%Task%@AE@%
  1772. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1773. Configuring mode and environment  Select the proper display mode for the 
  1774. (OS/2 and DOS)                    hardware and establish memory areas for 
  1775.                                   writing and displaying of images
  1776.  
  1777. Setting coordinates               Specify the logical origin and the 
  1778.                                   active display area within the screen
  1779.  
  1780. Setting low-level graphics        Specify a palette mapping for low-level 
  1781. palettes                          graphics routines
  1782.  
  1783. Setting attributes                Specify background and foreground 
  1784.                                   colors, fill masks, and line styles for 
  1785.                                   low-level graphics routines
  1786.  
  1787. Creating graphics                 Draw and fill figures
  1788. output                            
  1789.  
  1790. Creating text output (OS/2 and    Write text on the screen
  1791. DOS)                              
  1792.  
  1793. Transferring images               Store images in memory and retrieve them
  1794.  
  1795. Displaying fonts                  Display text in character fonts 
  1796.                                   compatible with Microsoft Windows(tm) %@CR:C6A00020112 @%
  1797.  
  1798. The following sections explain each of these categories.  %@NL@%
  1799. %@NL@%
  1800. %@NL@%
  1801. %@4@%%@AB@%2.6.1.1  Configuring Mode and Environment%@CR:C6A00020113 @% %@CR:C6A00020114 @%%@AE@%%@EH@%%@NL@%
  1802. %@NL@%
  1803. Routines that configure the mode and environment establish the graphics or
  1804. text mode of operation, determine the current graphics environment, and
  1805. control the display of the cursor.%@CR:C6A00020115 @%%@CR:C6A00020116 @%%@CR:C6A00020117 @%%@CR:C6A00020118 @%  %@NL@%
  1806. %@NL@%
  1807. All of the routines listed in this section are available in OS/2 as well as
  1808. DOS.%@CR:C6A00020119 @%%@CR:C6A00020120 @%  %@NL@%
  1809. %@NL@%
  1810. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1811. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1812. %@AB@%_clearscreen%@AE@%                      Erases the screen and fills it with the 
  1813.                                   current background color
  1814.  
  1815. %@AB@%_getactivepage%@AE@%                    Gets the current active page number
  1816.  
  1817. %@AB@%_getbkcolor%@AE@%                       Returns the current background color
  1818.  
  1819. %@AB@%_getvideoconfig%@AE@%                   Obtains status of current graphics 
  1820.                                   environment
  1821.  
  1822. %@AB@%_getvisualpage%@AE@%                    Gets the current visual page number
  1823.  
  1824. %@AB@%_grstatus%@AE@%                         Returns the status of the most recent 
  1825.                                   graphics function call
  1826.  
  1827. %@AB@%_setactivepage%@AE@%                    Sets memory area for the active page for
  1828.                                   writing
  1829.                                   images
  1830.  
  1831. %@AB@%_setbkcolor%@AE@%                       Sets the current background color
  1832.  
  1833. %@AB@%_settextrows%@AE@%                      Sets the number of text rows
  1834.  
  1835. %@AB@%_setvideomode%@AE@%                     Selects an operating mode for the 
  1836.                                   display screen
  1837.  
  1838. %@AB@%_setvideomoderows%@AE@%                 Sets the video mode and the number of 
  1839.                                   rows for text operations
  1840.  
  1841. %@AB@%_setvisualpage%@AE@%                    Sets memory area for the current visual 
  1842.                                   page
  1843.  
  1844. %@NL@%
  1845. %@4@%%@AB@%2.6.1.2  Setting Coordinates%@CR:C6A00020121 @%%@CR:C6A00020122 @%%@CR:C6A00020123 @%%@AE@%%@EH@%%@NL@%
  1846. %@NL@%
  1847. The "set coordinates" routines set the current text or graphics position and
  1848. convert pixel coordinates between the various graphic coordinate systems.%@CR:C6A00020124 @%%@CR:C6A00020125 @%%@CR:C6A00020126 @%%@CR:C6A00020127 @%%@CR:C6A00020128 @%  %@NL@%
  1849. %@NL@%
  1850. The Microsoft C graphics functions recognize three sets of coordinates:%@CR:C6A00020129 @%%@CR:C6A00020130 @%%@CR:C6A00020131 @%%@CR:C6A00020132 @%%@CR:C6A00020133 @%  %@NL@%
  1851. %@NL@%
  1852. %@NL@%
  1853.   1.  Fixed physical coordinates%@NL@%
  1854. %@NL@%
  1855.   2.  View coordinates defined by the application%@NL@%
  1856. %@NL@%
  1857.   3.  Window coordinates that can include floating-point values%@NL@%
  1858. %@NL@%
  1859. %@NL@%
  1860. The functions in this category establish window and view coordinate systems
  1861. and translate between physical, view, and window coordinate systems.  %@NL@%
  1862. %@NL@%
  1863. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1864. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1865. %@AB@%_getcurrentposition%@AE@%               Determines current position in view 
  1866.                                   coordinates
  1867.  
  1868. %@AB@%_getcurrentposition_w%@AE@%             Determines current position in window 
  1869.                                   coordinates
  1870.  
  1871. %@AB@%_getphyscoord%@AE@%                     Converts view coordinates to physical 
  1872.                                   coordinates
  1873.  
  1874. %@AB@%_getviewcoord%@AE@%                     Converts physical coordinates to view 
  1875.                                   coordinates
  1876.  
  1877. %@AB@%_getviewcoord_w%@AE@%                   Converts window coordinates to view 
  1878.                                   coordinates
  1879.  
  1880. %@AB@%_getviewcoord_wxy%@AE@%                 Converts window coordinates in %@AB@%_wxycoord%@AE@%
  1881.                                   structure to view coordinates
  1882.  
  1883. %@AB@%_getwindowcoord%@AE@%                   Converts view coordinates to window 
  1884.                                   coordinates
  1885.  
  1886. %@AB@%_setcliprgn%@AE@%                       Limits graphic output to a region of the
  1887.                                   screen
  1888.  
  1889. %@AB@%_setvieworg%@AE@%                       Positions the view-coordinate origin
  1890.  
  1891. %@AB@%_setviewport%@AE@%                      Limits graphics output to a region of 
  1892.                                   the screen and positions the 
  1893.                                   view-coordinate origin to the upper-left
  1894.                                   corner of that region
  1895.  
  1896. %@AB@%_setwindow%@AE@%                        Defines a floating-point window 
  1897.                                   coordinate system
  1898.  
  1899. The default view coordinate system is identical to the physical screen
  1900. coordinate system. The physical origin (0, 0) is always in the upper-left
  1901. corner of the display. The %@AI@%x%@AE@% axis extends in the positive direction left to
  1902. right, while the %@AI@%y%@AE@% axis extends in the positive direction top to bottom.  %@NL@%
  1903. %@NL@%
  1904. The physical horizontal and vertical dimensions depend on the hardware
  1905. display configuration and the selected mode. These values are accessible at
  1906. run time by examining the %@AB@%numxpixels%@AE@% and %@AB@%numypixels%@AE@% fields of the
  1907. %@AB@%videoconfig%@AE@% structure returned by %@AB@%_getvideoconfig%@AE@%. (The %@AB@%_getvideoconfig%@AE@%
  1908. routine is listed in the previous section.)  %@NL@%
  1909. %@NL@%
  1910. The %@AB@%_setvieworg%@AE@% function allows you to move the viewport origin to a new
  1911. position relative to the physical screen.  %@NL@%
  1912. %@NL@%
  1913. Routines that refer to coordinates on the physical screen or viewport
  1914. require integer values. However, in real-world graphing applications, you
  1915. might wish to use floating-point values, such as stock prices or average
  1916. rainfall. The window coordinate system allows you to display graphics using
  1917. floating-point values instead of integers.  %@NL@%
  1918. %@NL@%
  1919. The %@AB@%_getcurrentposition%@AE@% and %@AB@%_getcurrentposition_w%@AE@% routines allow you to
  1920. determine the location of the current graphics-output point.  %@NL@%
  1921. %@NL@%
  1922. The %@AB@%_setcliprgn%@AE@% function defines a restricted active display area on the
  1923. screen. The %@AB@%_setviewport%@AE@% function does the same thing and also resets the
  1924. viewport origin to the upper-left corner of the restricted active display
  1925. area.  %@NL@%
  1926. %@NL@%
  1927. The physical coordinates of any view-coordinate point can be determined with
  1928. the %@AB@%_getphyscoord%@AE@% function, and the view coordinates of any physical point
  1929. can be determined with the %@AB@%_getviewcoord%@AE@% function.  %@NL@%
  1930. %@NL@%
  1931. The view coordinates of any window coordinate can be determined with the
  1932. %@AB@%_getviewcoord_w%@AE@% and %@AB@%_getviewcoord_wxy%@AE@% functions. The window coordinates of
  1933. any view coordinate can be determined with the %@AB@%_getwindowcoord%@AE@% function.  %@NL@%
  1934. %@NL@%
  1935. The %@AB@%_setwindow%@AE@% function defines the current viewport as a real-coordinate
  1936. window bound by the specified floating-point values.  %@NL@%
  1937. %@NL@%
  1938. %@NL@%
  1939. %@4@%%@AB@%2.6.1.3  Setting Low-Level Graphics Palettes%@CR:C6A00020134 @%%@CR:C6A00020135 @%%@AE@%%@EH@%%@NL@%
  1940. %@NL@%
  1941. Use the low-level palette routines to select or remap color palettes.%@CR:C6A00020136 @%%@CR:C6A00020137 @%%@CR:C6A00020138 @%%@CR:C6A00020139 @%  %@NL@%
  1942. %@NL@%
  1943. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1944. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1945. %@AB@%_remapallpalette%@AE@%%@CR:C6A00020140 @%                  Changes all color indexes in the current
  1946.                                   palette
  1947.  
  1948. %@AB@%_remappalette%@AE@%                     Changes a single color index in the 
  1949.                                   current palette
  1950.  
  1951. %@AB@%_selectpalette%@AE@%                    Selects a predefined palette
  1952.  
  1953. Some video modes support a "color palette," which is a table of the color
  1954. values that can be displayed together on the screen at any given time. A
  1955. "color value" is a %@AB@%long%@AE@% integer representing a color that can be displayed
  1956. on your system.  %@NL@%
  1957. %@NL@%
  1958. In CGA color graphics modes, you can use the %@AB@%_selectpalette%@AE@% routine to
  1959. choose one of several predefined palettes.  %@NL@%
  1960. %@NL@%
  1961. On EGA and VGA video systems, you can "remap" (change) the palette using the
  1962. %@AB@%_remappalette%@AE@% or %@AB@%_remapallpalette%@AE@% routines. For instance, the EGA %@AB@%_ERESCOLOR%@AE@%
  1963. mode offers a total of 64 color values, of which 16 can be displayed at a
  1964. time. In this mode, the palette contains 16 "color indices," or slots to
  1965. which you can assign color values.  %@NL@%
  1966. %@NL@%
  1967. The %@AB@%_remappalette%@AE@% routine changes a single color index to a specified color
  1968. value. The %@AB@%_remapallpalette%@AE@% routine changes all of the available palette
  1969. entries simultaneously.  %@NL@%
  1970. %@NL@%
  1971. %@NL@%
  1972. %@4@%%@AB@%2.6.1.4  Setting Attributes%@CR:C6A00020141 @%%@CR:C6A00020142 @% %@CR:C6A00020143 @%%@CR:C6A00020144 @%%@CR:C6A00020145 @% %@CR:C6A00020146 @%%@AE@%%@EH@%%@NL@%
  1973. %@NL@%
  1974. The low-level output functions that draw lines, arcs, ellipses, and other
  1975. basic figures do not specify color or line-style information. Instead, the
  1976. low-level graphics functions rely on a set of attributes that are set
  1977. independently by the following functions:%@CR:C6A00020147 @%%@CR:C6A00020148 @%%@CR:C6A00020149 @%  %@NL@%
  1978. %@NL@%
  1979. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  1980. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  1981. %@AB@%_getarcinfo%@AE@%%@CR:C6A00020150 @%%@CR:C6A00020151 @%%@CR:C6A00020152 @%%@CR:C6A00020153 @%                       Determines the endpoints in viewport 
  1982.                                   coordinates of the most recently drawn 
  1983.                                   arc or pie
  1984.  
  1985. %@AB@%_getcolor%@AE@%                         Gets the current color
  1986.  
  1987. %@AB@%_getfillmask%@AE@%                      Gets the current fill mask
  1988.  
  1989. %@AB@%_getlinestyle%@AE@%                     Gets the current line-style mask
  1990.  
  1991. %@AB@%_getwritemode%@AE@%                     Gets the current logical write mode
  1992.  
  1993. %@AB@%_setcolor%@AE@%                         Sets the current color
  1994.  
  1995. %@AB@%_setfillmask%@AE@%                      Sets the current fill mask
  1996.  
  1997. %@AB@%_setlinestyle%@AE@%                     Sets the current line-style mask
  1998.  
  1999. %@AB@%_setwritemode%@AE@%                     Sets logical write mode for line drawing
  2000.  
  2001. The %@AB@%_getcolor%@AE@% and %@AB@%_setcolor%@AE@% functions get or set the current color index for
  2002. graphics and font output. The %@AB@%_getbkcolor%@AE@% and %@AB@%_setbkcolor%@AE@% functions get or
  2003. set the current background color.  %@NL@%
  2004. %@NL@%
  2005. The %@AB@%_getfillmask%@AE@% and %@AB@%_setfillmask%@AE@% functions get or set the current fill
  2006. mask. The mask is an 8-by-8-bit template array, with each bit representing a
  2007. pixel. If a bit is 0, the pixel in memory is left untouched, as the mask is
  2008. transparent to that pixel. If a bit is 1, the pixel is assigned the current
  2009. color value. The template is repeated as necessary over the entire fill
  2010. area.  %@NL@%
  2011. %@NL@%
  2012. The %@AB@%_getlinestyle%@AE@% and %@AB@%_setlinestyle%@AE@% functions get or set the current line
  2013. style. The line style is determined by a 16-bit template buffer with each
  2014. bit corresponding to a pixel. If a bit is 1, the pixel is set to the current
  2015. color. If a bit is 0, the pixel is not changed. The template is repeated for
  2016. the length of the line.  %@NL@%
  2017. %@NL@%
  2018. The %@AB@%_getwritemode%@AE@% and %@AB@%_setwritemode%@AE@% functions get or set the logical write
  2019. mode for straight line drawing. The default mode, %@AB@%_GPSET%@AE@%, causes lines to be
  2020. drawn in the current graphics color. Other modes combine the current
  2021. graphics color and the original screen image using various logical
  2022. operations.  %@NL@%
  2023. %@NL@%
  2024. %@NL@%
  2025. %@4@%%@AB@%2.6.1.5  Creating Graphics Output%@AE@%%@EH@%%@NL@%
  2026. %@NL@%
  2027. The graphics output functions use a set of specified coordinates and draw
  2028. various figures. They use the current or default attributes for line-style
  2029. mask, fill mask, write mode, background color, and foreground color.%@CR:C6A00020154 @%%@CR:C6A00020155 @%  %@NL@%
  2030. %@NL@%
  2031. The name of each function announces its task or the figure it draws, as the
  2032. following list indicates:%@CR:C6A00020156 @%  %@NL@%
  2033. %@NL@%
  2034. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2035. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2036. %@AB@%_arc%@AE@%,  %@AB@%_arc_w%@AE@%,  %@AB@%_arc_wxy%@AE@%%@CR:C6A00020157 @%%@CR:C6A00020158 @%          Draw an arc
  2037.  
  2038. %@AB@%_ellipse%@AE@%,  %@AB@%_ellipse_w%@AE@%,%@AB@%%@AE@%            Draw an ellipse or circle
  2039. %@AB@%_ellipse_wxy%@AE@%                      
  2040.  
  2041. %@AB@%_floodfill%@AE@%,  %@AB@%_floodfill_w%@AE@%%@CR:C6A00020159 @%         Flood-fill an area of the screen with 
  2042.                                   the current color
  2043.  
  2044. %@AB@%_getcurrentposition%@AE@%, %@AB@%%@AE@%             Obtain the current graphic-output 
  2045. %@AB@%_getcurrentposition_w%@AE@%%@CR:C6A00020160 @%             position used by %@AB@%_lineto%@AE@% and %@AB@%_outgtext%@AE@%
  2046.  
  2047. %@AB@%_getpixel%@AE@%, %@AB@%_getpixel_w%@AE@%%@CR:C6A00020161 @%            Obtain a pixel's color
  2048.  
  2049. %@AB@%_lineto%@AE@%,  %@AB@%_lineto_w%@AE@%%@CR:C6A00020162 @% %@CR:C6A00020163 @%%@CR:C6A00020164 @%              Draw a line from the current graphic 
  2050.                                   output position to a specified point
  2051.  
  2052. %@AB@%_moveto%@AE@%,  %@AB@%_moveto_w%@AE@%%@CR:C6A00020165 @% %@CR:C6A00020166 @%              Move the current graphic-output position
  2053.                                   to a specified point
  2054.  
  2055. %@AB@%_pie%@AE@%,  %@AB@%_pie_w%@AE@%,  %@AB@%_pie_wxy%@AE@%%@CR:C6A00020167 @%%@CR:C6A00020168 @%          Draw a pie-slice-shaped figure
  2056.  
  2057. %@AB@%_polygon%@AE@%,  %@AB@%_polygon_w%@AE@%, %@AB@%%@AE@%           Draw or scan-fill a polygon
  2058. %@AB@%_polygon_wxy%@AE@%                      
  2059.  
  2060. %@AB@%_rectangle%@AE@%,  %@AB@%_rectangle_w%@AE@%, %@AB@%%@AE@%       Draw or scan-fill a rectangle
  2061. %@AB@%_rectangle_wxy%@AE@%%@CR:C6A00020169 @%%@CR:C6A00020170 @%                    
  2062.  
  2063. %@AB@%_setpixel%@AE@%,  %@AB@%_setpixel_w%@AE@%%@CR:C6A00020171 @%           Set a pixel's color
  2064.  
  2065. Most of these routines are available in several forms, which are indicated
  2066. by their names. Output functions without a suffix use the view coordinate
  2067. system. Functions that end with %@AB@%_w%@AE@% take %@AB@%double%@AE@% values as arguments and use
  2068. the window coordinate system. Functions that end with %@AB@%_wxy%@AE@% use %@AB@%_wxycoord%@AE@%
  2069. structures to define the coordinates and use the window coordinate system.  %@NL@%
  2070. %@NL@%
  2071. Circular figures, such as arcs and ellipses, are centered within a "bounding
  2072. rectangle" specified by two points that define the diagonally opposed
  2073. corners of the rectangle. The center of the rectangle becomes the center of
  2074. the figure, and the rectangle's borders determine the size of the figure.  %@NL@%
  2075. %@NL@%
  2076. %@NL@%
  2077. %@4@%%@AB@%2.6.1.6  Creating Text Output%@AE@%%@EH@%%@NL@%
  2078. %@NL@%
  2079. The next group of routines provides text output in both graphics and text
  2080. modes. Unlike the standard console I/O library routines, these functions
  2081. recognize text-window boundaries and use the current text color.%@CR:C6A00020172 @%%@CR:C6A00020173 @%%@CR:C6A00020174 @%%@CR:C6A00020175 @%%@CR:C6A00020176 @%%@CR:C6A00020177 @%%@CR:C6A00020178 @%%@CR:C6A00020179 @%  %@NL@%
  2082. %@NL@%
  2083. All of the routines listed in this section work in OS/2 as well as DOS.  %@NL@%
  2084. %@NL@%
  2085. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2086. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2087. %@AB@%_displaycursor%@AE@%                    Sets the cursor on or off upon exit from
  2088.                                   a graphics routine
  2089.  
  2090. %@AB@%_gettextcolor%@AE@%                     Obtains the current text color
  2091.  
  2092. %@AB@%_gettextcursor%@AE@%                    Returns the current cursor attribute 
  2093.                                   (text modes only)
  2094.  
  2095. %@AB@%_gettextposition%@AE@%                  Obtains the current text-output position
  2096.  
  2097. %@AB@%_gettextwindow%@AE@%                    Gets the current text window boundaries
  2098.  
  2099. %@AB@%_outmem%@AE@%                           Prints text of a specified length from a
  2100.                                   memory
  2101.                                   buffer
  2102.  
  2103. %@AB@%_outtext%@AE@%                          Outputs a text string to the screen at 
  2104.                                   the current text position
  2105.  
  2106. %@AB@%_scrolltextwindow%@AE@%                 Scrolls the current text window up or 
  2107.                                   down
  2108.  
  2109. %@AB@%_settextcolor%@AE@%                     Sets the current text color
  2110.  
  2111. %@AB@%_settextcursor%@AE@%                    Sets the current cursor attribute (text 
  2112.                                   modes only)
  2113.  
  2114. %@AB@%_settextposition%@AE@%                  Relocates the current text position
  2115.  
  2116. %@AB@%_settextwindow%@AE@%                    Defines the current text-display window
  2117.  
  2118. %@AB@%_wrapon%@AE@%                           Enables or disables line wrap
  2119.  
  2120. The %@AB@%_outtext%@AE@% and %@AB@%_outmem%@AE@% routines provide no formatting. If you want to
  2121. output integer or floating-point values, you must convert the values into a
  2122. string variable (using the %@AB@%sprintf%@AE@% function) before calling these routines.
  2123. %@NL@%
  2124. %@NL@%
  2125. The %@AB@%_outtext%@AE@% routine recognizes the %@AB@%\n%@AE@% (newline character) and %@AB@%\r%@AE@% (carriage
  2126. return) sequences. The %@AB@%_outmem%@AE@% routine treats these sequences as printable
  2127. graphics characters.  %@NL@%
  2128. %@NL@%
  2129. %@NL@%
  2130. %@4@%%@AB@%2.6.1.7  Transferring Images%@AE@%%@EH@%%@NL@%
  2131. %@NL@%
  2132. The functions in this category transfer screen images between memory and the
  2133. display, using a buffer allocated by the application, or determine the size
  2134. in bytes of the buffer needed to store a given image.%@CR:C6A00020180 @%%@CR:C6A00020181 @%%@CR:C6A00020182 @%  %@NL@%
  2135. %@NL@%
  2136. The functions that end with %@AB@%_w%@AE@% or %@AB@%_wxy%@AE@% use window coordinates; the other
  2137. functions in this set use view coordinates.%@CR:C6A00020183 @%%@CR:C6A00020184 @%%@CR:C6A00020185 @%%@CR:C6A00020186 @%  %@NL@%
  2138. %@NL@%
  2139. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2140. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2141. %@AB@%_getimage%@AE@%,%@AB@%%@AE@%                        Store a screen image in memory
  2142. %@AB@%_getimage_w%@AE@%,%@AB@%%@AE@%                      
  2143. %@AB@%_getimage_wxy%@AE@%                     
  2144.  
  2145. %@AB@%_imagesize%@AE@%,%@AB@%%@AE@%                       Return the size (in bytes) of the buffer
  2146. %@AB@%_imagesize_w%@AE@%,%@AB@%%@AE@%                     needed to store the image
  2147. %@AB@%_imagesize_wxy%@AE@%                    
  2148.  
  2149. %@AB@%_putimage%@AE@%,%@AB@%%@AE@%                        Retrieve an image from memory and 
  2150. %@AB@%_putimage_w%@AE@%                       display it
  2151.  
  2152. In some cases, the buffer needed to store an image with the %@AB@%_getimage%@AE@%
  2153. functions must be larger than 64K (65,535) bytes. Use the %@AB@%halloc%@AE@% routine to
  2154. allocate a buffer larger than 64K.  %@NL@%
  2155. %@NL@%
  2156. %@NL@%
  2157. %@4@%%@AB@%2.6.1.8  Displaying Fonts%@AE@%%@EH@%%@NL@%
  2158. %@NL@%
  2159. The functions listed in this section control the display of font-based
  2160. characters on the screen.%@CR:C6A00020187 @%%@CR:C6A00020188 @%%@CR:C6A00020189 @%%@CR:C6A00020190 @%%@CR:C6A00020191 @%  %@NL@%
  2161. %@NL@%
  2162. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2163. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2164. %@AB@%_getfontinfo%@AE@%                      Obtains the current font characteristics
  2165.  
  2166. %@AB@%_getgtextextent%@AE@%                   Determines the width in pixels of 
  2167.                                   specified text in the current font
  2168.  
  2169. %@AB@%_getgtextvector%@AE@%                   Gets orientation of font text output
  2170.  
  2171. %@AB@%_outgtext%@AE@%                         Outputs text in the current font to the 
  2172.                                   screen at the specified pixel position
  2173.  
  2174. %@AB@%_registerfonts%@AE@%                    Initializes font library
  2175.  
  2176. %@AB@%_setfont%@AE@%                          Finds a single font that matches a 
  2177.                                   specified set of characteristics and 
  2178.                                   makes this font the current font for use
  2179.                                   by the %@AB@%_outgtext%@AE@% function
  2180.  
  2181. %@AB@%_setgtextvector%@AE@%                   Sets the current orientation for font 
  2182.                                   text output
  2183.  
  2184. %@AB@%_unregisterfonts%@AE@%                  Frees memory allocated by %@AB@%_registerfonts%@AE@%
  2185.  
  2186. %@NL@%
  2187. %@3@%%@CR:C6A00020192 @%%@AB@%2.6.2  Presentation-Graphics Functions%@AE@%%@EH@%%@NL@%
  2188. %@NL@%
  2189. The presentation-graphics functions are declared in the PGCHART.H include
  2190. file. The library can be divided into the three categories listed below,
  2191. corresponding to the different tasks involved in creating and manipulating
  2192. graphic objects:%@CR:C6A00020193 @%  %@NL@%
  2193. %@NL@%
  2194. %@AB@%Category%@AE@%                          %@AB@%Task%@AE@%
  2195. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2196. Displaying presentation graphics  Initialize video structures for 
  2197.                                   presentation graphics and establishes 
  2198.                                   the default chart type. Display
  2199.                                   presentation-graphics chart: bar, 
  2200.                                   column, pie, scatter, or line chart.
  2201.  
  2202. Analyzing                         Analyze data (does not display chart).
  2203. presentation-graphics data        
  2204.  
  2205. Manipulating                      Modify basic chart structures (e.g., 
  2206. presentation-graphics structures  palettes, cross-hatching styles). 
  2207.  
  2208. %@NL@%
  2209. %@4@%%@AB@%2.6.2.1  Displaying Presentation Graphics%@CR:C6A00020194 @% %@CR:C6A00020195 @%%@AE@%%@EH@%%@NL@%
  2210. %@NL@%
  2211. The functions listed in this section initialize the presentation-graphics
  2212. library and display the specified graph type.%@CR:C6A00020196 @%%@CR:C6A00020197 @%%@CR:C6A00020198 @%%@CR:C6A00020199 @%  %@NL@%
  2213. %@NL@%
  2214. Because the %@AB@%_pg_initchart%@AE@% routine initializes the presentation-graphics
  2215. library, it must be called before any other function in the
  2216. presentation-graphics library. The %@AB@%_pg_defaultchart%@AE@% function initializes the
  2217. variables in the chart environment.%@CR:C6A00020200 @%%@CR:C6A00020201 @%%@CR:C6A00020202 @%  %@NL@%
  2218. %@NL@%
  2219. The other routines in this category display the specified graph. The
  2220. single-series versions plot one set of data, and the multiseries versions
  2221. (those ending with an %@AB@%ms%@AE@% suffix) plot several sets of data in the same chart
  2222. style.  %@NL@%
  2223. %@NL@%
  2224. Presentation-graphics programs can display text in different font sizes by
  2225. taking advantage of font-based characters (see Section 2.6.1.8, "Displaying
  2226. Fonts.") Call the %@AB@%_registerfonts%@AE@% and %@AB@%_setfont%@AE@% routines to select a font
  2227. before calling the %@AB@%_pginitchart%@AE@% routine. Subsequent charts use the selected
  2228. font. You can later call the %@AB@%_unregisterfonts%@AE@% routine to restore the default
  2229. character font and free the memory previously allocated for fonts.  %@NL@%
  2230. %@NL@%
  2231. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2232. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2233. %@AB@%_pg_chart%@AE@%                         Displays a single-series bar, column, or
  2234.                                   line chart
  2235.  
  2236. %@AB@%_pg_chartms%@AE@%                       Displays a multiseries bar, column, or 
  2237.                                   line chart
  2238.  
  2239. %@AB@%_pg_chartpie%@AE@%                      Displays a pie chart
  2240.  
  2241. %@AB@%_pg_chartscatter%@AE@%                  Displays a scatter diagram for a single 
  2242.                                   series of data
  2243.  
  2244. %@AB@%_pg_chartscatterms%@AE@%                Displays a scatter diagram for more than
  2245.                                   one series of data
  2246.  
  2247. %@AB@%_pg_defaultchart%@AE@%                  Initializes all necessary variables in 
  2248.                                   the chart environment for a specified 
  2249.                                   chart type
  2250.  
  2251. %@AB@%_pg_initchart%@AE@%                     Initializes the presentation-graphics 
  2252.                                   library
  2253.  
  2254. %@NL@%
  2255. %@4@%%@AB@%2.6.2.2  Analyzing Presentation-Graphics Charts%@CR:C6A00020203 @%%@CR:C6A00020204 @% %@CR:C6A00020205 @%%@AE@%%@EH@%%@NL@%
  2256. %@NL@%
  2257. These routines calculate default values for the specified graph type but do
  2258. not display the chart. The single-series versions analyze one set of data,
  2259. and the multiseries versions analyze several sets of data in the same chart
  2260. style.%@CR:C6A00020206 @%%@CR:C6A00020207 @%  %@NL@%
  2261. %@NL@%
  2262. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2263. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2264. %@AB@%_pg_analyzechart%@AE@%%@CR:C6A00020208 @%%@CR:C6A00020209 @%                  Analyzes a single series of data for a 
  2265.                                   bar, column, or line chart
  2266.  
  2267. %@AB@%_pg_analyzechartms%@AE@%                Analyzes a multiseries of data for a 
  2268.                                   bar, column, or line chart
  2269.  
  2270. %@AB@%_pg_analyzepie%@AE@%                    Analyzes data for a pie chart
  2271.  
  2272. %@AB@%_pg_analyzescatter%@AE@%                Analyzes a single series of data for a 
  2273.                                   scatter diagram
  2274.  
  2275. %@AB@%_pg_analyzescatterms%@AE@%              Analyzes a multiseries of data for a 
  2276.                                   scatter diagram 
  2277.  
  2278. %@NL@%
  2279. %@4@%%@AB@%2.6.2.3  Manipulating Presentation-Graphics Structures%@AE@%%@EH@%%@NL@%
  2280. %@NL@%
  2281. These functions control low-level aspects of the presentation-graphics
  2282. package.%@CR:C6A00020210 @%%@CR:C6A00020211 @%%@CR:C6A00020212 @%%@CR:C6A00020213 @%%@CR:C6A00020214 @%%@CR:C6A00020215 @%  %@NL@%
  2283. %@NL@%
  2284. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2285. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2286. %@AB@%_pg_hlabelchart%@AE@%%@CR:C6A00020216 @%%@CR:C6A00020217 @%%@CR:C6A00020218 @%%@CR:C6A00020219 @% %@CR:C6A00020220 @%%@CR:C6A00020221 @%                  Writes text horizontally on the screen%@CR:C6A00020222 @%%@CR:C6A00020223 @%%@CR:C6A00020224 @%%@CR:C6A00020225 @% 
  2287.  
  2288. %@AB@%_pg_vlabelchart%@AE@%                   Writes text vertically on the screen
  2289.  
  2290. %@AB@%_pg_getpalette%@AE@%                    Retrieves current colors, line styles, 
  2291.                                   fill patterns, and plot characters for 
  2292.                                   all presentation-graphics palettes
  2293.  
  2294. %@AB@%_pg_setpalette%@AE@%                    Sets current colors, line styles, fill 
  2295.                                   patterns, and plot characters for all 
  2296.                                   presentation-graphics palettes
  2297.  
  2298. %@AB@%_pg_resetpalette%@AE@%                  Sets current colors, line styles, fill 
  2299.                                   patterns, and plot characters to the 
  2300.                                   default values for the current screen 
  2301.                                   mode
  2302.  
  2303. %@AB@%_pg_getstyleset%@AE@%                   Retrieves the contents of the current 
  2304.                                   styleset
  2305.  
  2306. %@AB@%_pg_setstyleset%@AE@%                   Sets the contents of the current 
  2307.                                   styleset
  2308.  
  2309. %@AB@%_pg_resetstyleset%@AE@%                 Resets the contents of the current 
  2310.                                   styleset to the default value for the 
  2311.                                   current screen mode
  2312.  
  2313. %@AB@%_pg_getchardef%@AE@% %@CR:C6A00020226 @%                   Retrieves the current 8-by-8-pixel bit 
  2314.                                   map for a specified character
  2315.  
  2316. %@AB@%_pg_setchardef%@AE@% %@CR:C6A00020227 @%                   Sets the 8-by-8-pixel bit map for a 
  2317.                                   specified
  2318.                                   character
  2319.  
  2320. %@NL@%
  2321. %@2@%%@CR:C6A00020228 @%%@AB@%2.7  Input and Output%@AE@%%@EH@%%@NL@%
  2322. %@NL@%
  2323. The input and output (I/O) routines of the standard C library allow you to
  2324. read and write data to and from files and devices. In C, there are no
  2325. predefined file structures; all data items are treated as sequences of
  2326. bytes. The following three types of I/O functions are available:  %@NL@%
  2327. %@NL@%
  2328. %@NL@%
  2329.   1.  Stream%@NL@%
  2330. %@NL@%
  2331.   2.  Low-level%@NL@%
  2332. %@NL@%
  2333.   3.  Console and port%@NL@%
  2334. %@NL@%
  2335. %@NL@%
  2336. The "stream" I/O functions treat data as a stream of individual characters.
  2337. By choosing among the many stream functions available, you can process data
  2338. in different sizes and formats, from single characters to large data
  2339. structures. Stream I/O also provides buffering, which can significantly
  2340. improve performance.%@CR:C6A00020229 @%%@CR:C6A00020230 @%  %@NL@%
  2341. %@NL@%
  2342. The "low-level" I/O routines do not perform buffering and formatting.
  2343. Instead, they invoke the operating system's input and output capabilities
  2344. directly. These routines let you access files and peripheral devices at a
  2345. more basic level than the stream functions.%@CR:C6A00020231 @%  %@NL@%
  2346. %@NL@%
  2347. The "console and port" I/O routines allow you to read or write directly to a
  2348. console (keyboard and screen) or an I/O port (such as a printer port). The
  2349. port I/O routines simply read and write data in bytes. With console I/O
  2350. routines, some additional options are available, such as detecting whether a
  2351. character has been typed at the console. You can also choose between echoing
  2352. characters to the screen as they are read or reading characters without
  2353. echoing.%@CR:C6A00020232 @%  %@NL@%
  2354. %@NL@%
  2355. The C library also provides a number of direct DOS I/O system call routines.
  2356. These are described in Section 2.14, "System Calls."  %@NL@%
  2357. %@NL@%
  2358. File I/O operations can be performed in two modes: text or binary. The
  2359. following section describes these modes and their use.  %@NL@%
  2360. %@NL@%
  2361. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2362. %@AU@%WARNING%@AE@%%@NL@%
  2363. %@NL@%
  2364. Because stream routines are buffered and low-level routines are not, the two
  2365. types of routines are generally incompatible. You should use either stream
  2366. or low-level routines consistently for processing a given file.%@NL@%
  2367. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2368. %@NL@%
  2369. %@NL@%
  2370. %@3@%%@CR:C6A00020233 @%%@AB@%2.7.1  Text and Binary Modes%@AE@%%@EH@%%@NL@%
  2371. %@NL@%
  2372. Many C programs use data files for input and output. Under DOS and OS/2,
  2373. data files are normally processed in text mode. In this mode, each
  2374. carriage-return-line-feed (CR-LF) combination is translated into a single
  2375. line-feed character during input. During output, each line-feed character is
  2376. translated into a CR-LF combination.  %@NL@%
  2377. %@NL@%
  2378. Sometimes you may want to process a file without making those translations.
  2379. In these cases you use binary mode, which suppresses CR-LF translations.%@CR:C6A00020234 @%%@CR:C6A00020235 @%  %@NL@%
  2380. %@NL@%
  2381. You can control the file translation mode in the following ways:  %@NL@%
  2382. %@NL@%
  2383. %@NL@%
  2384.   ■   To process a few selected files in binary mode, while retaining the
  2385.       default text mode for most files, you can specify binary mode when you
  2386.       open the selected files. The %@AB@%fopen%@AE@% routine opens a file in binary mode
  2387.       when you specify the letter %@AB@%b%@AE@% in the access-mode string for the file.
  2388.       The %@AB@%open%@AE@% routine opens a file in binary mode when you specify the
  2389.       %@AB@%O_BINARY%@AE@% flag in the %@AI@%oflag%@AE@% argument. For more information about %@AB@%fopen%@AE@%
  2390.       and %@AB@%open%@AE@%, see the reference description of each routine.%@NL@%
  2391. %@NL@%
  2392.   ■   To process most or all files in binary mode, you can change the
  2393.       default mode to binary. The global variable %@AB@%_fmode%@AE@% controls the
  2394.       default translation mode, which is normally text. If you set %@AB@%_fmode%@AE@% to
  2395.       %@AB@%O_BINARY%@AE@%, the default mode is binary except for %@AB@%stdaux%@AE@% and %@AB@%stdprn%@AE@%,
  2396.       which are opened in binary mode by default.%@NL@%
  2397. %@NL@%
  2398. %@NL@%
  2399. You can change the value of %@AB@%_fmode%@AE@% in two ways:  %@NL@%
  2400. %@NL@%
  2401. %@NL@%
  2402.   1.  Link with the file BINMODE.OBJ (supplied with Microsoft C). This
  2403.       changes the initial setting of %@AB@%_fmode%@AE@% to the %@AB@%O_BINARY %@AE@%flag, causing
  2404.       all files except%@AB@% stdin%@AE@%, %@AB@%stdout%@AE@%, and %@AB@%stderr%@AE@% to be opened in binary
  2405.       mode.%@NL@%
  2406. %@NL@%
  2407.   2.  Change the value of %@AB@%_fmode%@AE@% directly by setting it to the %@AB@%O_BINARY%@AE@% flag
  2408.       in your program. This has the same effect as linking with BINMODE.OBJ.%@NL@%
  2409. %@NL@%
  2410. %@NL@%
  2411. You can still override the default mode (now binary) for a particular file
  2412. by opening it in text mode. Specify the letter %@AB@%t%@AE@% when using %@AB@%fopen%@AE@%, or
  2413. specify the %@AB@%O_TEXT%@AE@% flag when using %@AB@%open%@AE@%.  %@NL@%
  2414. %@NL@%
  2415. By default, the %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, and %@AB@%stderr%@AE@% files are opened in text mode, and
  2416. the %@AB@%stdaux%@AE@% and %@AB@%stdprn%@AE@% files are opened in binary mode. The %@AB@%setmode%@AE@% routine
  2417. allows you to change these defaults or change the mode of a file after it
  2418. has been opened. See the reference description of %@AB@%setmode%@AE@% for details.  %@NL@%
  2419. %@NL@%
  2420. %@NL@%
  2421. %@3@%%@CR:C6A00020236 @%%@AB@%2.7.2  Stream Routines%@AE@%%@EH@%%@NL@%
  2422. %@NL@%
  2423. Stream I/O functions handle data as a continuous stream of characters. To
  2424. use the stream functions, you must include the file STDIO.H in your program.
  2425. This file defines constants, types, and structures used in the stream
  2426. functions, and contains function declarations and macro definitions for the
  2427. stream  routines.%@CR:C6A00020237 @%%@CR:C6A00020238 @%%@CR:C6A00020239 @%%@CR:C6A00020240 @%%@CR:C6A00020241 @%  %@NL@%
  2428. %@NL@%
  2429. When a file is opened for I/O using the stream functions, the opened file is
  2430. associated with a structure of type %@AB@%FILE%@AE@% (defined in STDIO.H) containing
  2431. basic information about the file. A pointer to the %@AB@%FILE%@AE@% structure is
  2432. returned when the stream is opened. Subsequent operations use this pointer
  2433. (also called the "stream pointer," or just "stream") to refer to the file.%@CR:C6A00020242 @%%@CR:C6A00020243 @%  %@NL@%
  2434. %@NL@%
  2435. The stream functions provide for buffered, formatted, or unformatted input
  2436. and output. When a stream is buffered, data that is read from or written to
  2437. the stream is collected in an intermediate storage location called a
  2438. "buffer". In write operations, the output buffer's contents are written to
  2439. the appropriate final location when the buffer is full, the stream is
  2440. closed, or the program terminates normally. The buffer is said to be
  2441. "flushed" when this occurs. In read operations, a block of data is placed in
  2442. the input buffer read from the buffer; when the input buffer is empty, the
  2443. next block of data is transferred into the buffer.%@CR:C6A00020244 @%%@CR:C6A00020245 @%  %@NL@%
  2444. %@NL@%
  2445. Buffering produces efficient I/O because the system can transfer a large
  2446. block of data in a single operation rather than performing an I/O operation
  2447. each time a data item is read from or written to a stream. However, if a
  2448. program terminates abnormally, output buffers may not be flushed, resulting
  2449. in loss of data.  %@NL@%
  2450. %@NL@%
  2451. Some of the constants defined in STDIO.H may be useful in your program. The
  2452. manifest constant %@AB@%EOF%@AE@% is defined to be the value returned at end-of-file.
  2453. %@AB@%NULL%@AE@% is the null pointer. %@AB@%FILE%@AE@% is the structure that maintains information
  2454. about a stream. %@AB@%BUFSIZ%@AE@% defines the default size of stream buffers, in bytes.%@CR:C6A00020246 @%%@CR:C6A00020247 @%%@CR:C6A00020248 @%%@CR:C6A00020249 @%
  2455. %@NL@%
  2456. %@NL@%
  2457. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2458. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2459. %@AB@%clearerr%@AE@%                          Clears the error indicator for a stream %@CR:C6A00020250 @%
  2460.  
  2461. %@AB@%fclose%@AE@%                            Closes a stream %@CR:C6A00020251 @%
  2462.  
  2463. %@AB@%fcloseall%@AE@%                         Closes all open streams
  2464.  
  2465. %@AB@%fdopen%@AE@%                            Associates a stream with an open file 
  2466.                                   handle %@CR:C6A00020252 @%
  2467.  
  2468. %@AB@%feof%@AE@%                              Tests for end-of-file on a stream %@CR:C6A00020253 @%
  2469.  
  2470. %@AB@%ferror%@AE@%                            Tests for error on a stream %@CR:C6A00020254 @%
  2471.  
  2472. %@AB@%fflush%@AE@%                            Flushes a stream %@CR:C6A00020255 @%
  2473.  
  2474. %@AB@%fgetc%@AE@%                             Reads a character from a stream 
  2475.                                   (function version) %@CR:C6A00020256 @%
  2476.  
  2477. %@AB@%fgetchar %@AE@%                         Reads a character from %@AB@%stdin%@AE@% (function 
  2478.                                   version)
  2479.  
  2480. %@AB@%fgetpos%@AE@%                           Gets the position indicator of a stream %@CR:C6A00020257 @%
  2481.  
  2482. %@AB@%fgets%@AE@%                             Reads a string from a stream %@CR:C6A00020258 @%
  2483.  
  2484. %@AB@%fileno%@AE@%                            Gets the file handle associated with a 
  2485.                                   stream %@CR:C6A00020259 @%
  2486.  
  2487. %@AB@%flushall%@AE@%                          Flushes all streams %@CR:C6A00020260 @%
  2488.  
  2489. %@AB@%fopen%@AE@%                             Opens a stream %@CR:C6A00020261 @%
  2490.  
  2491. %@AB@%fprintf%@AE@%                           Writes formatted data to a stream %@CR:C6A00020262 @%
  2492.  
  2493. %@AB@%fputc%@AE@%                             Writes a character to a stream (function
  2494.                                   version) %@CR:C6A00020263 @%
  2495.  
  2496. %@AB@%fputchar%@AE@%                          Writes a character to %@AB@%stdout%@AE@% (function 
  2497.                                   version)
  2498.  
  2499. %@AB@%fputs%@AE@%                             Writes a string to a stream %@CR:C6A00020264 @%
  2500.  
  2501. %@AB@%fread%@AE@%                             Reads unformatted data from a stream %@CR:C6A00020265 @%
  2502.  
  2503. %@AB@%freopen%@AE@%                           Reassigns a %@AB@%FILE%@AE@% pointer to a new file%@CR:C6A00020266 @%
  2504.  
  2505. %@AB@%fscanf%@AE@%                            Reads formatted data from a stream %@CR:C6A00020267 @%
  2506.  
  2507. %@AB@%fseek%@AE@%                             Moves file position to a given location %@CR:C6A00020268 @%
  2508.  
  2509. %@AB@%fsetpos%@AE@%                           Sets the position indicator of a stream %@CR:C6A00020269 @%
  2510.  
  2511. %@AB@%_fsopen%@AE@%                           Opens a stream with file sharing %@CR:C6A00020270 @%
  2512.  
  2513. %@AB@%ftell%@AE@%                             Gets current file position %@CR:C6A00020271 @%
  2514.  
  2515. %@AB@%fwrite%@AE@%                            Writes unformatted data items to a 
  2516.                                   stream %@CR:C6A00020272 @%
  2517.  
  2518. %@AB@%getc%@AE@%                              Reads a character from a stream %@CR:C6A00020273 @%
  2519.  
  2520. %@AB@%getchar%@AE@%                           Reads a character from %@AB@%stdin%@AE@%
  2521.  
  2522. %@AB@%gets%@AE@%                              Reads a line from %@AB@%stdin%@AE@% %@CR:C6A00020274 @%
  2523.  
  2524. %@AB@%getw%@AE@%                              Reads a binary %@AB@%int%@AE@% item from a stream %@CR:C6A00020275 @%
  2525.  
  2526. %@AB@%printf%@AE@%                            Writes formatted data to %@AB@%stdout%@AE@% %@CR:C6A00020276 @%
  2527.  
  2528. %@AB@%putc%@AE@%                              Writes a character to a stream
  2529.  
  2530. %@AB@%putchar%@AE@%                           Writes a character to %@AB@%stdout%@AE@% %@CR:C6A00020277 @%
  2531.  
  2532. %@AB@%puts%@AE@%                              Writes a line to a stream %@CR:C6A00020278 @%
  2533.  
  2534. %@AB@%putw%@AE@%                              Writes a binary %@AB@%int%@AE@% item to a stream %@CR:C6A00020279 @%
  2535.  
  2536. %@AB@%rewind%@AE@%                            Moves file position to beginning of a 
  2537.                                   stream %@CR:C6A00020280 @%
  2538.  
  2539. %@AB@%rmtmp%@AE@%                             Removes temporary files created by %@AB@%%@AE@%
  2540.                                   %@AB@%tmpfile%@AE@% %@CR:C6A00020281 @%
  2541.  
  2542. %@AB@%scanf%@AE@%                             Reads formatted data from %@AB@%stdin%@AE@% %@CR:C6A00020282 @%
  2543.  
  2544. %@AB@%setbuf%@AE@%                            Controls stream buffering %@CR:C6A00020283 @%
  2545.  
  2546. %@AB@%setvbuf%@AE@%                           Controls stream buffering and buffer 
  2547.                                   size %@CR:C6A00020284 @%
  2548.  
  2549. %@AB@%sprintf%@AE@%                           Writes formatted data to a string
  2550.  
  2551. %@AB@%sscanf%@AE@%                            Reads formatted data from a string %@CR:C6A00020285 @%
  2552.  
  2553. %@AB@%tempnam%@AE@%                           Generates a temporary file name in given
  2554.                                   directory %@CR:C6A00020286 @%
  2555.  
  2556. %@AB@%tmpfile%@AE@%                           Creates a temporary file %@CR:C6A00020287 @%
  2557.  
  2558. %@AB@%tmpnam%@AE@%                            Generates a temporary file name
  2559.  
  2560. %@AB@%ungetc%@AE@%                            Places a character in the buffer %@CR:C6A00020288 @%
  2561.  
  2562. %@AB@%vfprintf%@AE@%                          Writes formatted data to a stream %@CR:C6A00020289 @%
  2563.  
  2564. %@AB@%vprintf%@AE@%                           Writes formatted data to %@AB@%stdout%@AE@%
  2565.  
  2566. %@AB@%vsprintf%@AE@%                          Writes formatted data to a string
  2567.  
  2568. %@NL@%
  2569. %@4@%%@AB@%2.7.2.1  Opening a Stream%@AE@%%@EH@%%@NL@%
  2570. %@NL@%
  2571. A stream must be opened using the %@AB@%fdopen%@AE@%, %@AB@%fopen%@AE@%, %@AB@%freopen%@AE@%, or %@AB@%_fsopen%@AE@%
  2572. function before input and output can be performed on that stream. When
  2573. opening a stream, the named stream can be opened for reading, writing, or
  2574. both, and can be opened in either text or binary mode.%@CR:C6A00020290 @%  %@NL@%
  2575. %@NL@%
  2576. The %@AB@%fdopen%@AE@%, %@AB@%fopen%@AE@%, %@AB@%freopen%@AE@%, and %@AB@%_fsopen%@AE@% functions return a %@AB@%FILE%@AE@% pointer. You
  2577. normally assign the pointer value to a variable and use the variable to
  2578. refer to the opened stream. For instance, if your program contains the lines
  2579. %@NL@%
  2580. %@NL@%
  2581. %@AS@%  FILE *infile
  2582. %@AS@%  infile = fopen ("test.dat", "r");%@AE@%%@NL@%
  2583. %@NL@%
  2584. you can use the %@AB@%FILE%@AE@% pointer variable %@AS@% infile %@AE@% to refer to the stream.  %@NL@%
  2585. %@NL@%
  2586. %@NL@%
  2587. %@4@%%@AB@%2.7.2.2  Using Predefined Stream Pointers%@AE@%%@EH@%%@NL@%
  2588. %@NL@%
  2589. When a program begins execution, the C start-up code automatically opens
  2590. several streams: standard input, standard output, and standard error. By
  2591. default, the standard input, standard output, and standard error streams are
  2592. directed to the console (keyboard and screen). This means that when a
  2593. program expects input from the "standard input," it receives that input from
  2594. the console. Similarly, a program that writes to the "standard output"
  2595. prints its data to the console. Error messages generated by the library
  2596. routines are sent to the "standard error," meaning that error messages
  2597. appear on the user's console.%@CR:C6A00020291 @%%@CR:C6A00020292 @%%@CR:C6A00020293 @%  %@NL@%
  2598. %@NL@%
  2599. Under DOS, two additional streams are opened: standard auxiliary and
  2600. standard print. (These streams are not available in OS/2.) The assignment of
  2601. standard auxiliary and standard print depends on the machine configuration.
  2602. These streams usually refer to the first serial port and a printer port, but
  2603. those ports may not be available on some systems. Be sure to check your
  2604. machine configuration before using these streams.%@CR:C6A00020294 @%%@CR:C6A00020295 @%  %@NL@%
  2605. %@NL@%
  2606. You can refer to the standard streams with the following predefined stream
  2607. pointers:  %@NL@%
  2608. %@NL@%
  2609. %@AB@%Pointer%@AE@%                           %@AB@%Stream%@AE@%
  2610. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2611. %@AB@%stdin%@AE@%                             Standard input
  2612.  
  2613. %@AB@%stdout%@AE@%                            Standard output
  2614.  
  2615. %@AB@%stderr%@AE@%                            Standard error
  2616.  
  2617. %@AB@%stdaux%@AE@%                            Standard auxiliary (DOS only)
  2618.  
  2619. %@AB@%stdprn%@AE@%                            Standard print (DOS only)
  2620.  
  2621. You can use these pointers in any function that requires a stream pointer as
  2622. an argument. Some functions, such as %@AB@%getchar%@AE@% and %@AB@%putchar%@AE@%, are designed to
  2623. use %@AB@%stdin%@AE@% or %@AB@%stdout%@AE@% automatically. The pointers %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, %@AB@%stderr%@AE@%,
  2624. %@AB@%stdaux%@AE@%, and %@AB@%stdprn%@AE@% are constants, not variables; do not try to assign them a
  2625. new stream pointer value.  %@NL@%
  2626. %@NL@%
  2627. DOS and OS/2 allow you to redirect a program's standard input and standard
  2628. output at the operating-system command level. OS/2 also allows you to
  2629. redirect a program's standard error. See your operating system user's manual
  2630. for a complete discussion of redirection.%@CR:C6A00020296 @%  %@NL@%
  2631. %@NL@%
  2632. Within your program, you can use %@AB@%freopen%@AE@% to redirect %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, %@AB@%stderr%@AE@%,
  2633. %@AB@%stdaux%@AE@%, or %@AB@%stdprn%@AE@% so that it refers to a disk file or to a device. See the
  2634. reference description of %@AB@%freopen%@AE@% for more details.  %@NL@%
  2635. %@NL@%
  2636. %@NL@%
  2637. %@4@%%@AB@%2.7.2.3  Controlling Stream Buffering%@AE@%%@EH@%%@NL@%
  2638. %@NL@%
  2639. As mentioned earlier, stream routines can use in-memory buffers to speed I/O
  2640. operations. Files opened using the stream routines are buffered by default,
  2641. except for %@AB@%stdaux%@AE@% and %@AB@%stdprn%@AE@%, which are normally unbuffered. The %@AB@%stdout%@AE@% and
  2642. %@AB@%stderr%@AE@% streams are flushed whenever they are full or (if you are writing to
  2643. a character device) after each library call.%@CR:C6A00020297 @%%@CR:C6A00020298 @%%@CR:C6A00020299 @%%@CR:C6A00020300 @%%@CR:C6A00020301 @%  %@NL@%
  2644. %@NL@%
  2645. By using the %@AB@%setbuf%@AE@% or %@AB@%setvbuf%@AE@% function, you can cause a stream to be
  2646. unbuffered, or you can associate a buffer with an unbuffered stream. Buffers
  2647. allocated by the system are not accessible to you, but buffers allocated
  2648. with %@AB@%setbuf%@AE@% or %@AB@% setvbuf%@AE@% refer to arrays in your program and can be
  2649. manipulated. Buffers can be any size up to 32,767 bytes. This size is set by
  2650. the manifest constant %@AB@%BUFSIZ%@AE@% in STDIO.H if you use%@AB@% seftbuf%@AE@%; if you use
  2651. %@AB@%setvbuf%@AE@%, you can set the size of the buffer yourself. (See the descriptions
  2652. of %@AB@%setbuf%@AE@% and %@AB@%setvbuf%@AE@% in the reference section for more details.)%@CR:C6A00020302 @%%@CR:C6A00020303 @%  %@NL@%
  2653. %@NL@%
  2654. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2655. NOTE
  2656.  
  2657. %@AI@%These routines affect only buffers created by C library routines. They have
  2658. %@AI@%no effect on buffers created by the operating system.%@AE@%%@NL@%
  2659. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2660. %@NL@%
  2661. %@NL@%
  2662. %@4@%%@AB@%2.7.2.4  Closing Streams%@AE@%%@EH@%%@NL@%
  2663. %@NL@%
  2664. The %@AB@%fclose%@AE@% and %@AB@%fcloseall%@AE@% functions close a stream or streams. The %@AB@%fclose%@AE@%
  2665. routine closes a single specified stream; %@AB@%fcloseall%@AE@% closes all open streams
  2666. except %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, %@AB@%stderr%@AE@%, %@AB@%stdaux%@AE@%, and %@AB@%stdprn%@AE@%. If your program does not
  2667. explicitly close a stream, the stream is automatically closed when the
  2668. program terminates. How-ever, it is a good practice to close a stream when
  2669. your program is finished with it, as the number of streams that can be open
  2670. at a given time is limited.%@CR:C6A00020304 @%  %@NL@%
  2671. %@NL@%
  2672. %@NL@%
  2673. %@4@%%@AB@%2.7.2.5  Reading and Writing Data%@AE@%%@EH@%%@NL@%
  2674. %@NL@%
  2675. The stream functions allow you to transfer data in a variety of ways. You
  2676. can read and write binary data (a sequence of bytes), or specify reading and
  2677. writing by characters, lines, or more complicated formats.  %@NL@%
  2678. %@NL@%
  2679. Reading and writing operations on streams always begin at the current
  2680. position of the stream, known as the "file pointer" for the stream. The file
  2681. pointer is changed to reflect the new position after a read or write
  2682. operation takes place. For example, if you read a single character from a
  2683. stream, the file pointer is increased by one byte so that the next operation
  2684. begins with the first unread character. If a stream is opened for appending,
  2685. the file pointer is automatically positioned at the end of the file before
  2686. each write operation.%@CR:C6A00020305 @%  %@NL@%
  2687. %@NL@%
  2688. The %@AB@%fseek%@AE@% and %@AB@%fsetpos%@AE@% functions allow you to position the file pointer
  2689. anywhere in a file. The next operation occurs at the position you specified.
  2690. The %@AB@%rewind%@AE@% routine positions the file pointer at the beginning of the file.
  2691. Use the %@AB@%ftell%@AE@% or %@AB@%fgetpos%@AE@% routine to determine the current position of the
  2692. file pointer.  %@NL@%
  2693. %@NL@%
  2694. The %@AB@%feof%@AE@% macro detects an end-of-file condition on a stream. Once the
  2695. end-of-file indicator is set, it remains set until the file is closed, or
  2696. until %@AB@%clearerr%@AE@%, %@AB@%fseek%@AE@%, %@AB@%fsetpos%@AE@%, or %@AB@%rewind%@AE@% is called.  %@NL@%
  2697. %@NL@%
  2698. Streams associated with a character-oriented device (such as a console) do
  2699. not have file pointers. Data coming from or going to a console cannot be
  2700. accessed randomly. Routines that set or get the file-pointer position (such
  2701. as %@AB@%fseek%@AE@%, %@AB@%fgetpos%@AE@%, %@AB@%fsetpos%@AE@%, %@AB@%ftell%@AE@%, or %@AB@%rewind%@AE@%) have undefined results if used
  2702. on a stream associated with a character-oriented device.  %@NL@%
  2703. %@NL@%
  2704. %@NL@%
  2705. %@4@%%@AB@%2.7.2.6  Detecting Errors%@AE@%%@EH@%%@NL@%
  2706. %@NL@%
  2707. When an error occurs in a stream operation, an error indicator for the
  2708. stream is set. You can use the %@AB@%ferror%@AE@% macro to test the error indicator and
  2709. determine whether an error has occurred. Once an error has occurred, the
  2710. error indicator for the stream remains set until the stream is closed, or
  2711. until you explicitly clear the error indicator by calling %@AB@%clearerr%@AE@% or
  2712. %@AB@%rewind%@AE@%.%@CR:C6A00020306 @%%@CR:C6A00020307 @%  %@NL@%
  2713. %@NL@%
  2714. %@NL@%
  2715. %@3@%%@CR:C6A00020308 @%%@AB@%2.7.3  Low-Level Routines%@CR:C6A00020309 @%%@CR:C6A00020310 @%%@AE@%%@EH@%%@NL@%
  2716. %@NL@%
  2717. Low-level input and output calls do not buffer or format data. Declarations
  2718. for the low-level functions are given in the include files IO.H, FCNTL.H,
  2719. SYS\TYPES.H, and SYS\STAT.H. Unlike the stream functions, low-level
  2720. functions do not require the include file STDIO.H. However, some common
  2721. constants are defined in STDIO.H; for example, the end-of-file indicator
  2722. (%@AB@%EOF%@AE@%) may be useful. If your program requires these constants, you must
  2723. include STDIO.H.%@CR:C6A00020311 @%%@CR:C6A00020312 @%%@CR:C6A00020313 @%%@CR:C6A00020314 @%%@CR:C6A00020315 @%%@CR:C6A00020316 @%%@CR:C6A00020317 @%  %@NL@%
  2724. %@NL@%
  2725. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2726. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2727. %@AB@%close%@AE@%%@CR:C6A00020318 @%%@CR:C6A00020319 @% %@CR:C6A00020320 @%%@CR:C6A00020321 @%%@CR:C6A00020322 @%%@CR:C6A00020323 @%%@CR:C6A00020324 @%                            Closes a file
  2728.  
  2729. %@AB@%creat%@AE@%%@CR:C6A00020325 @%                             Creates a file
  2730.  
  2731. %@AB@%dup%@AE@%%@CR:C6A00020326 @%                               Creates a second handle for a file
  2732.  
  2733. %@AB@%dup2%@AE@%                              Reassigns a handle to a file
  2734.  
  2735. %@AB@%eof%@AE@%%@CR:C6A00020327 @%                               Tests for end-of-file
  2736.  
  2737. %@AB@%lseek%@AE@%%@CR:C6A00020328 @%                             Repositions file pointer to a given 
  2738.                                   location
  2739.  
  2740. %@AB@%open%@AE@%%@CR:C6A00020329 @%                              Opens a file
  2741.  
  2742. %@AB@%read%@AE@%%@CR:C6A00020330 @%                              Reads data from a file
  2743.  
  2744. %@AB@%sopen%@AE@%%@CR:C6A00020331 @%                             Opens a file for file sharing
  2745.  
  2746. %@AB@%tell%@AE@%                              Gets current file-pointer position
  2747.  
  2748. %@AB@%umask%@AE@%                             Sets default file-permission mask
  2749.  
  2750. %@AB@%write%@AE@%                             Writes data to a file
  2751.  
  2752. %@NL@%
  2753. %@4@%%@AB@%2.7.3.1  Opening a File%@AE@%%@EH@%%@NL@%
  2754. %@NL@%
  2755. You must open a file before performing I/O functions on it. The %@AB@%open%@AE@%
  2756. function opens a file; it can also create the file when opening it. In OS/2
  2757. and DOS versions 3.0 and later, you can use %@AB@%sopen%@AE@% to open a file with
  2758. file-sharing attributes. The %@AB@%creat%@AE@% function can create and open a file.  %@NL@%
  2759. %@NL@%
  2760. The file can be opened for reading, writing, or both, and opened in either
  2761. text or binary mode (see Section 2.7.1, "Text and Binary Modes"). The
  2762. include file FCNTL.H must be included when opening a file, as it contains
  2763. definitions for flags used in %@AB@%open%@AE@%. In some cases, the files SYS\TYPES.H and
  2764. SYS\STAT.H must also be included; for more information, see the reference
  2765. description for the %@AB@%open%@AE@% function.%@CR:C6A00020332 @%  %@NL@%
  2766. %@NL@%
  2767. These functions return a file handle, which is normally assigned to an
  2768. integer variable. You use the variable to refer to the opened file.%@CR:C6A00020333 @%  %@NL@%
  2769. %@NL@%
  2770. %@NL@%
  2771. %@4@%%@AB@%2.7.3.2  Reading and Writing Data%@AE@%%@EH@%%@NL@%
  2772. %@NL@%
  2773. Use the %@AB@%read%@AE@% and %@AB@%write%@AE@% routines to read and write to files. These operations
  2774. begin at the current position in the file. The current position is updated
  2775. each time a read or write operation occurs.%@CR:C6A00020334 @%  %@NL@%
  2776. %@NL@%
  2777. The %@AB@%lseek%@AE@% function allows you to place the file pointer anywhere in the
  2778. file. The next operation occurs at the position you specified. The %@AB@%tell%@AE@%
  2779. function indicates the current position of the file pointer. The %@AB@%eof%@AE@% routine
  2780. tests for the end of the file.  %@NL@%
  2781. %@NL@%
  2782. Low-level I/O routines set the %@AB@%errno%@AE@% variable when an error occurs. Chapter
  2783. 3, "Global Variables and Standard Types," describes %@AB@%errno%@AE@%.%@CR:C6A00020335 @%%@CR:C6A00020336 @%  %@NL@%
  2784. %@NL@%
  2785. Character-oriented devices, such as the console, do not have file pointers.
  2786. The %@AB@%lseek%@AE@% and %@AB@%tell%@AE@% routines have undefined results if used on a handle
  2787. associated with a device.  %@NL@%
  2788. %@NL@%
  2789. %@NL@%
  2790. %@4@%%@AB@%2.7.3.3  Closing Files%@AE@%%@EH@%%@NL@%
  2791. %@NL@%
  2792. The %@AB@%close%@AE@% function closes an open file. Open files are automatically closed
  2793. when a program terminates. However, it is a good practice to close a file
  2794. when your program is finished with it, as there is a limit to the number of
  2795. files that can be open at one time.%@CR:C6A00020337 @%  %@NL@%
  2796. %@NL@%
  2797. %@NL@%
  2798. %@4@%%@AB@%2.7.3.4  Using Predefined Handles%@AE@%%@EH@%%@NL@%
  2799. %@NL@%
  2800. When a program begins execution, three files are automatically opened:
  2801. standard input, standard output, and standard error. In DOS, two additional
  2802. files are opened: standard auxiliary and standard print. (These files are
  2803. not available in OS/2.)%@CR:C6A00020338 @%%@CR:C6A00020339 @%  %@NL@%
  2804. %@NL@%
  2805. Low-level routines can access these files using the following predefined
  2806. handles:%@CR:C6A00020340 @%%@CR:C6A00020341 @%  %@NL@%
  2807. %@NL@%
  2808. %@AB@%Stream%@AE@%                            %@AB@%Handle%@AE@%
  2809. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2810. %@AB@%stdin%@AE@%                             0
  2811.  
  2812. %@AB@%stdout%@AE@%                            1
  2813.  
  2814. %@AB@%stderr%@AE@%                            2
  2815.  
  2816. %@AB@%stdaux%@AE@% (DOS only)                 3
  2817.  
  2818. %@AB@%stdprn%@AE@% (DOS only)                 4
  2819.  
  2820. You can use these file handles without previously opening the files. The
  2821. files are opened and the handles are assigned when the program starts.  %@NL@%
  2822. %@NL@%
  2823. The %@AB@%dup%@AE@% and %@AB@%dup2%@AE@% functions allow you to assign multiple handles for the same
  2824. file. These functions are typically used to associate the predefined file
  2825. handles with different files.%@CR:C6A00020342 @%  %@NL@%
  2826. %@NL@%
  2827. In DOS and OS/2, you can redirect the standard input and standard output at
  2828. the operating-system command level. OS/2 also allows you to redirect the
  2829. standard error. See your operating system user's manual for a complete
  2830. discussion of redirection.%@CR:C6A00020343 @%  %@NL@%
  2831. %@NL@%
  2832. %@NL@%
  2833. %@3@%%@CR:C6A00020344 @%%@AB@%2.7.4  Console and Port I/O%@AE@%%@EH@%%@NL@%
  2834. %@NL@%
  2835. The console and port I/O routines are implemented as functions and are
  2836. declared in the include file CONIO.H. These functions perform reading and
  2837. writing operations on your console or on the specified port. The %@AB@%cgets%@AE@%,
  2838. %@AB@%cscanf%@AE@%, %@AB@%getch%@AE@%, %@AB@%getche%@AE@%, and %@AB@%kbhit%@AE@% routines take input from the console, while
  2839. %@AB@%cprintf%@AE@%, %@AB@%cputs%@AE@%, %@AB@%putch%@AE@%, and %@AB@%ungetch%@AE@% write to the console. The input or output
  2840. of these functions can be redirected.%@CR:C6A00020345 @%%@CR:C6A00020346 @%%@CR:C6A00020347 @%%@CR:C6A00020348 @%  %@NL@%
  2841. %@NL@%
  2842. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2843. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2844. %@AB@%cgets%@AE@%%@CR:C6A00020349 @%%@CR:C6A00020350 @%                             Reads a string from the console
  2845.  
  2846. %@AB@%cprintf%@AE@%%@CR:C6A00020351 @%%@CR:C6A00020352 @%                           Writes formatted data to the console
  2847.  
  2848. %@AB@%cputs%@AE@%%@CR:C6A00020353 @%                             Writes a string to the console
  2849.  
  2850. %@AB@%cscanf%@AE@%%@CR:C6A00020354 @%%@CR:C6A00020355 @%                            Reads formatted data from the console
  2851.  
  2852. %@AB@%getch%@AE@%%@CR:C6A00020356 @%%@CR:C6A00020357 @%                             Reads a character from the console
  2853.  
  2854. %@AB@%getche%@AE@%                            Reads a character from the console and 
  2855.                                   echoes it
  2856.  
  2857. %@AB@%inp%@AE@%%@CR:C6A00020358 @%%@CR:C6A00020359 @%                               Reads one byte from the specified I/O 
  2858.                                   port
  2859.  
  2860. %@AB@%inpw%@AE@%                              Reads a two-byte word from the specified
  2861.                                   I/O port
  2862.  
  2863. %@AB@%kbhit%@AE@%%@CR:C6A00020360 @%%@CR:C6A00020361 @%                             Checks for a keystroke at the console
  2864.  
  2865. %@AB@%outp%@AE@%%@CR:C6A00020362 @%%@CR:C6A00020363 @%                              Writes one byte to the specified I/O 
  2866.                                   port
  2867.  
  2868. %@AB@%outpw%@AE@%                             Writes a two-byte word to the specified 
  2869.                                   I/O port
  2870.  
  2871. %@AB@%putch%@AE@%%@CR:C6A00020364 @%%@CR:C6A00020365 @%                             Writes a character to the console
  2872.  
  2873. %@AB@%ungetch%@AE@%%@CR:C6A00020366 @%%@CR:C6A00020367 @%                           "Ungets" the last character read from 
  2874.                                   the console so that it becomes the next 
  2875.                                   character read
  2876.  
  2877. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2878. NOTE
  2879.  
  2880. %@AI@%Programs that need only run under DOS can also use a number of direct DOS
  2881. %@AI@%I/O system calls (%@AB@% %@AE@%%@AI@%_dos_open, _dos_read, _dos_close,%@AE@%%@AI@% etc.) These are
  2882. %@AI@%described in detail in Section 2.14, "System Calls."%@AE@%%@AE@%%@NL@%
  2883. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2884. %@NL@%
  2885. The console or port does not have to be opened or closed before I/O is
  2886. performed, so there are no open or close routines in this category. The port
  2887. I/O routines %@AB@%inp%@AE@% and %@AB@%outp%@AE@% read or write one byte at a time from the
  2888. specified port. The %@AB@%inpw%@AE@% and %@AB@%outpw%@AE@% routines read and write two-byte words,
  2889. respectively.%@CR:C6A00020368 @%%@CR:C6A00020369 @%  %@NL@%
  2890. %@NL@%
  2891. The console I/O routines allow reading and writing of strings (%@AB@%cgets %@AE@%and
  2892. %@AB@%cputs%@AE@%), formatted data (%@AB@%cscanf %@AE@%and %@AB@%cprintf%@AE@%), and characters. Several options
  2893. are available when reading and writing characters.  %@NL@%
  2894. %@NL@%
  2895. The %@AB@%putch%@AE@% routine writes a single character to the console. The %@AB@%getch%@AE@% and
  2896. %@AB@%getche%@AE@% routines read a single character from the console; %@AB@%getche%@AE@% echoes the
  2897. character back to the console, while %@AB@%getch%@AE@% does not. The %@AB@%ungetch%@AE@% routine
  2898. "ungets" the last character read; the next read operation on the console
  2899. begins with the "ungotten" character.  %@NL@%
  2900. %@NL@%
  2901. The %@AB@%kbhit%@AE@% routine determines whether a key has been struck at the console.
  2902. This routine allows you to test for keyboard input before you attempt to
  2903. read from the console.  %@NL@%
  2904. %@NL@%
  2905. ────────────────────────────────────────────────────────────────────────────%@NL@%
  2906. NOTE
  2907.  
  2908. %@AI@%The console I/O routines are not compatible with stream or low-level library
  2909. %@AI@%routines and should not be used with them.%@AE@%%@NL@%
  2910. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  2911. %@NL@%
  2912. %@NL@%
  2913. %@2@%%@CR:C6A00020370 @%%@AB@%2.8  Internationalization%@AE@%%@EH@%%@NL@%
  2914. %@NL@%
  2915. Internationalization routines are useful for creating different versions of
  2916. a program for international markets. These routines are declared in the
  2917. header file LOCALE.H, except for %@AB@%strftime%@AE@%, which is declared in TIME.H.  %@NL@%
  2918. %@NL@%
  2919. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2920. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2921. %@AB@%localeconv%@AE@%                        Sets a structure with appropriate values
  2922.                                   for formatting numeric quantities
  2923.  
  2924. %@AB@%setlocale%@AE@%                         Selects the appropriate locale for the 
  2925.                                   program
  2926.  
  2927. %@AB@%strcoll%@AE@%                           Compares strings using locale-specific 
  2928.                                   information
  2929.  
  2930. %@AB@%strftime%@AE@%                          Formats a date and time string
  2931.  
  2932. %@AB@%strxfrm%@AE@%                           Transforms a string based on 
  2933.                                   locale-specific
  2934.                                   information
  2935.  
  2936. %@NL@%
  2937. %@2@%%@CR:C6A00020371 @%%@AB@%2.9  Math%@AE@%%@EH@%%@NL@%
  2938. %@NL@%
  2939. The math routines allow you to perform common mathematical calculations. All
  2940. math routines work with floating-point values and therefore require
  2941. floating-point support (see Section 1.8, "Floating-Point Support").%@CR:C6A00020372 @%%@CR:C6A00020373 @%%@CR:C6A00020374 @%%@CR:C6A00020375 @%%@CR:C6A00020376 @%%@CR:C6A00020377 @%%@CR:C6A00020378 @%%@CR:C6A00020379 @%%@CR:C6A00020380 @%
  2942. %@CR:C6A00020381 @%%@CR:C6A00020382 @%  %@NL@%
  2943. %@NL@%
  2944. The math library provides two versions of some routines. The first version
  2945. of the routine supports %@AB@%double%@AE@% arguments and return values. The second
  2946. version supports an 80-bit data type, allowing the routine to take %@AB@%long
  2947. %@AB@%double%@AE@% arguments and return a %@AB@%long double%@AE@% value. The second version usually
  2948. has the same name with the suffix %@AB@%l%@AE@%. For instance, the %@AB@%acos%@AE@% routine supports
  2949. %@AB@%double%@AE@% arguments and return values, while %@AB@%acosl%@AE@% supports %@AB@%long double%@AE@%
  2950. arguments and return values.%@CR:C6A00020383 @%%@CR:C6A00020384 @%%@CR:C6A00020385 @%%@CR:C6A00020386 @%%@CR:C6A00020387 @%%@CR:C6A00020388 @%%@CR:C6A00020389 @%%@CR:C6A00020390 @%%@CR:C6A00020391 @%  %@NL@%
  2951. %@NL@%
  2952. Routines which support %@AB@%long double%@AE@% values are not available when you compile
  2953. with the /Fpa (alternate math) compiler option. The same is true of the
  2954. %@AB@%_clear 87%@AE@%,%@AB@% _control87%@AE@%, and %@AB@%_status87%@AE@% routines.%@CR:C6A00020392 @%%@CR:C6A00020393 @%%@CR:C6A00020394 @%%@CR:C6A00020395 @%%@CR:C6A00020396 @%%@CR:C6A00020397 @%%@CR:C6A00020398 @%%@CR:C6A00020399 @%%@CR:C6A00020400 @%
  2955. %@CR:C6A00020401 @%%@CR:C6A00020402 @%%@CR:C6A00020403 @%  %@NL@%
  2956. %@NL@%
  2957. Most math declarations are in the include file MATH.H. However, the
  2958. %@AB@%_clear87%@AE@%, %@AB@%_control87%@AE@%, %@AB@%_fpreset%@AE@%, and %@AB@%_status87%@AE@% routines are defined in
  2959. FLOAT.H, the%@AB@% abs%@AE@% and %@AB@%labs%@AE@% functions are defined in MATH.H and STDLIB.H, and
  2960. the %@AB@%div%@AE@% and %@AB@%ldiv%@AE@% routines are declared in STDLIB.H.%@CR:C6A00020404 @%%@CR:C6A00020405 @%%@CR:C6A00020406 @%%@CR:C6A00020407 @%%@CR:C6A00020408 @%%@CR:C6A00020409 @%%@CR:C6A00020410 @%%@CR:C6A00020411 @%%@CR:C6A00020412 @%
  2961. %@CR:C6A00020413 @%%@CR:C6A00020414 @%%@CR:C6A00020415 @%%@CR:C6A00020416 @%%@CR:C6A00020417 @%  %@NL@%
  2962. %@NL@%
  2963. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  2964. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  2965. %@AB@%acos%@AE@%, %@AB@%acosl%@AE@%                       Calculate the arccosine
  2966.  
  2967. %@AB@%asin%@AE@%, %@AB@%asinl%@AE@%                       Calculate the arcsine
  2968.  
  2969. %@AB@%atan%@AE@%, %@AB@%atanl%@AE@%                       Calculate the arctangent
  2970.  
  2971. %@AB@%atan2%@AE@%, %@AB@%atan2l%@AE@%                     Calculate the arctangent
  2972.  
  2973. %@AB@%bessel%@AE@%                            Calculates Bessel functions
  2974.  
  2975. %@AB@%cabs%@AE@%, %@AB@%cabsl%@AE@%                       Find the absolute value of a complex 
  2976.                                   number
  2977.  
  2978. %@AB@%ceil%@AE@%, %@AB@%ceill%@AE@%                       Find the integer ceiling
  2979.  
  2980. %@AB@%_clear87%@AE@%                          Gets and clears the floating-point 
  2981.                                   status word
  2982.  
  2983. %@AB@%_control87%@AE@%                        Gets the old floating-point control word
  2984.                                   and sets a new control-word value
  2985.  
  2986. %@AB@%cos%@AE@%, %@AB@%cosl%@AE@%                         Calculate the cosine
  2987.  
  2988. %@AB@%cosh%@AE@%, %@AB@%coshl%@AE@%                       Calculate the hyperbolic cosine
  2989.  
  2990. %@AB@%dieeetomsbin%@AE@%                      Converts IEEE double-precision number to
  2991.                                   Microsoft (MS) binary format %@CR:C6A00020418 @%
  2992.  
  2993. %@AB@%div%@AE@%                               Divides one integer by another, 
  2994.                                   returning the quotient and remainder
  2995.  
  2996. %@AB@%dmsbintoieee%@AE@%                      Converts Microsoft binary 
  2997.                                   double-precision number to IEEE format
  2998.  
  2999. %@AB@%exp%@AE@%, %@AB@%expl%@AE@%                         Calculate the exponential function
  3000.  
  3001. %@AB@%fabs%@AE@%, %@AB@%fabsl%@AE@%                       Find the absolute value
  3002.  
  3003. %@AB@%fieeetomsbin%@AE@%                      Converts IEEE single-precision number to
  3004.                                   Microsoft binary format %@CR:C6A00020419 @%
  3005.  
  3006. %@AB@%floor%@AE@%, %@AB@%floorl%@AE@%                     Find the largest integer less than or 
  3007.                                   equal to the
  3008.                                   argument
  3009.  
  3010. %@AB@%fmod%@AE@%, %@AB@%fmodl%@AE@%                       Find the floating-point remainder
  3011.  
  3012. %@AB@%fmsbintoieee%@AE@%                      Converts Microsoft binary 
  3013.                                   single-precision number to IEEE format
  3014.  
  3015. %@AB@%_fpreset%@AE@%                          Reinitializes the floating-point-math 
  3016.                                   package
  3017.  
  3018. %@AB@%frexp%@AE@%, %@AB@%frexpl%@AE@%                     Calculate an exponential value
  3019.  
  3020. %@AB@%hypot%@AE@%, %@AB@%hypotl%@AE@%                     Calculate the hypotenuse of right 
  3021.                                   triangle
  3022.  
  3023. %@AB@%ldexp%@AE@%, %@AB@%ldexpl%@AE@%                     Calculate the product of the argument 
  3024.                                   and 2exp
  3025.  
  3026. %@AB@%ldiv%@AE@%                              Divides one %@AB@%long%@AE@% integer by another, 
  3027.                                   returning the quotient and remainder
  3028.  
  3029. %@AB@%log%@AE@%, %@AB@%logl%@AE@%                         Calculate the natural logarithm
  3030.  
  3031. %@AB@%log10%@AE@%, %@AB@%log10l%@AE@%                     Calculate the base-10 logarithm
  3032.  
  3033. %@AB@%_lrotl%@AE@%,  %@AB@%_lrotr%@AE@%                   Shift an %@AB@%unsigned long int%@AE@% item left ( 
  3034.                                   _lrotl) or right ( _lrotr)
  3035.  
  3036. %@AB@%matherr%@AE@%,  %@AB@%_matherrl%@AE@%               Handle math errors
  3037.  
  3038. %@AB@%max%@AE@%, %@AB@%min%@AE@%                          Return the larger or smaller of two 
  3039.                                   values
  3040.  
  3041. %@AB@%modf%@AE@%, %@AB@%modfl%@AE@%                       Break down the argument into integer and
  3042.                                   fractional parts
  3043.  
  3044. %@AB@%pow%@AE@%, %@AB@%powl%@AE@%                         Calculate a value raised to a power
  3045.  
  3046. %@AB@%rand%@AE@%                              Gets a pseudorandom number
  3047.  
  3048. %@AB@%_rotl%@AE@%,  %@AB@%_rotr%@AE@%                     Shift an %@AB@%unsigned int%@AE@% item left ( _rotl)
  3049.                                   or right
  3050.                                   ( _rotr)
  3051.  
  3052. %@AB@%sin%@AE@%, %@AB@%sinl%@AE@%                         Calculate the sine
  3053.  
  3054. %@AB@%sinh%@AE@%, %@AB@%sinhl%@AE@%                       Calculate the hyperbolic sine
  3055.  
  3056. %@AB@%sqrt%@AE@%, %@AB@%sqrtl%@AE@%                       Find the square root
  3057.  
  3058. %@AB@%srand%@AE@%                             Initializes a pseudorandom series
  3059.  
  3060. %@AB@%_status87%@AE@%                         Gets the floating-point status word
  3061.  
  3062. %@AB@%tan%@AE@%, %@AB@%tanl%@AE@%                         Calculate the tangent
  3063.  
  3064. %@AB@%tanh%@AE@%, %@AB@%tanhl%@AE@%                       Calculate the hyperbolic tangent
  3065.  
  3066. The %@AB@%bessel%@AE@% routine does not correspond to a single function, but to twelve
  3067. functions named %@AB@%j0%@AE@%, %@AB@%j1%@AE@%, %@AB@%jn%@AE@%, %@AB@%y0%@AE@%, %@AB@%y1%@AE@%, %@AB@%yn%@AE@%,  %@AB@%_j0l%@AE@%,  %@AB@%_j1l%@AE@%,  %@AB@%_jnl%@AE@%,  %@AB@%_y0l%@AE@%,  %@AB@%_y1l%@AE@%,
  3068. and  %@AB@%_ynl%@AE@%.  %@NL@%
  3069. %@NL@%
  3070. The %@AB@%matherr%@AE@% and %@AB@%_matherrl%@AE@% routines are invoked by the math functions when
  3071. errors occur. The %@AB@%matherr%@AE@% routine handles functions that return a %@AB@%double%@AE@%
  3072. value and %@AB@%_matherrl%@AE@% handles routines that return a %@AB@%long double%@AE@%.  %@NL@%
  3073. %@NL@%
  3074. These routines are defined in the library, but you can redefine them for
  3075. different error-handling. The user-defined function, if given, must follow
  3076. the rules given in the reference description of %@AB@%matherr%@AE@% and %@AB@%_matherrl%@AE@%.  %@NL@%
  3077. %@NL@%
  3078. You are not required to supply a definition for the %@AB@%matherr%@AE@% routines. If no
  3079. definition is present, the default error returns for each routine are used.
  3080. The reference description of each routine describes that routine's error
  3081. returns.%@CR:C6A00020420 @%%@CR:C6A00020421 @%  %@NL@%
  3082. %@NL@%
  3083. %@NL@%
  3084. %@2@%%@CR:C6A00020422 @%%@AB@%2.10  Memory Allocation%@CR:C6A00020423 @% %@CR:C6A00020424 @%%@CR:C6A00020425 @%%@CR:C6A00020426 @%%@CR:C6A00020427 @%%@AE@%%@EH@%%@NL@%
  3085. %@NL@%
  3086. The memory-allocation routines allow you to allocate, free, and reallocate
  3087. blocks of memory. Memory-allocation routines are declared in the include
  3088. file MALLOC.H.%@CR:C6A00020428 @%%@CR:C6A00020429 @%%@CR:C6A00020430 @%%@CR:C6A00020431 @%%@CR:C6A00020432 @%%@CR:C6A00020433 @%%@CR:C6A00020434 @%%@CR:C6A00020435 @%  %@NL@%
  3089. %@NL@%
  3090. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3091. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3092. %@AB@%alloca%@AE@%                            Allocates a block of memory from the 
  3093.                                   program's stack
  3094.  
  3095. %@AB@%_bfreeseg%@AE@%                         Frees a based heap
  3096.  
  3097. %@AB@%_bheapseg%@AE@%                         Allocates a based heap
  3098.  
  3099. %@AB@%calloc%@AE@%, %@AB@% _bcalloc%@AE@%,  %@AB@%_fcalloc%@AE@%,  %@AB@%%@AE@%   Allocate storage for an array
  3100. %@AB@%_ncalloc%@AE@%                          
  3101.  
  3102. %@AB@%_expand%@AE@%,  %@AB@%_bexpand%@AE@%,  %@AB@%_fexpand%@AE@%, %@AB@%%@AE@%   Expand or shrink a block of memory 
  3103. %@AB@%_nexpand%@AE@%                          without moving its location
  3104.  
  3105. %@AB@%free%@AE@%,  %@AB@%_bfree%@AE@%,  %@AB@%_ffree%@AE@%,  %@AB@%_nfree%@AE@%%@CR:C6A00020436 @%   Free an allocated block
  3106.  
  3107. %@AB@%_freect%@AE@%                           Returns approximate number of items of 
  3108.                                   given size that could be allocated in 
  3109.                                   the near heap
  3110.  
  3111. %@AB@%halloc%@AE@%%@CR:C6A00020437 @%                            Allocates storage for huge array
  3112.  
  3113. %@AB@%_heapadd%@AE@%,  %@AB@%_bheapadd%@AE@%              Add memory to a heap
  3114.  
  3115. %@AB@%_heapchk%@AE@%,  %@AB@%_bheapchk%@AE@%,  %@AB@%_fheapchk%@AE@%  Check a heap for consistency
  3116. , %@AB@%_nheapchk%@AE@%                       
  3117.  
  3118. %@AB@%_heapmin%@AE@%,  %@AB@%_bheapmin%@AE@%,%@AB@%%@AE@%             Release unused memory in a heap
  3119. %@AB@%_fheapmin%@AE@%,  %@AB@%_nheapmin%@AE@%             
  3120.  
  3121. %@AB@%_heapset%@AE@%,  %@AB@%_bheapset%@AE@%,  %@AB@%_fheapset%@AE@%  Fill free heap entries with a specified 
  3122. , %@AB@%_nheapset%@AE@%%@CR:C6A00020438 @%%@CR:C6A00020439 @%%@CR:C6A00020440 @%                       value
  3123.  
  3124. %@AB@%_heapwalk%@AE@%,  %@AB@%_bheapwalk%@AE@%, %@AB@%%@AE@%          Return information about each entry in a
  3125. %@AB@%_fheapwalk%@AE@%, %@AB@%_nheapwalk%@AE@%            heap
  3126.  
  3127. %@AB@%hfree%@AE@%%@CR:C6A00020441 @%                             Frees a block allocated by %@AB@%halloc%@AE@%
  3128.  
  3129. %@AB@%malloc%@AE@%,  %@AB@%_bmalloc%@AE@%,  %@AB@%_fmalloc%@AE@%, %@AB@%%@AE@%    Allocate a block of memory
  3130. %@AB@%_nmalloc%@AE@%%@CR:C6A00020442 @%%@CR:C6A00020443 @%                          
  3131.  
  3132. %@AB@%_memavl%@AE@%%@CR:C6A00020444 @%                           Returns approximate number of bytes 
  3133.                                   available for allocation in the near 
  3134.                                   heap
  3135.  
  3136. %@AB@%_memmax%@AE@%%@CR:C6A00020445 @%                           Returns size of largest contiguous free 
  3137.                                   block in the near heap
  3138.  
  3139. %@AB@%_msize%@AE@%,  %@AB@%_bmsize%@AE@%,  %@AB@%_fmsize%@AE@%, %@AB@%%@AE@%      Return size of an allocated block
  3140. %@AB@%_nmsize%@AE@%%@CR:C6A00020446 @%                           
  3141.  
  3142. %@AB@%realloc%@AE@%,  %@AB@%_brealloc%@AE@%,  %@AB@%_frealloc%@AE@%,  Reallocate a block to a new size%@CR:C6A00020448 @%
  3143. %@AB@%_nrealloc%@AE@%%@CR:C6A00020447 @%                         
  3144.  
  3145. %@AB@%stackavail%@AE@%%@CR:C6A00020449 @%                        Returns size of stack space available 
  3146.                                   for allocation with %@AB@%alloca%@AE@%
  3147.  
  3148. Some memory-management routines, such as %@AB@%malloc%@AE@%, are available in different
  3149. versions that begin with %@AB@%_b%@AE@%, %@AB@%_f%@AE@%, or %@AB@%_n%@AE@%. These variations are described in
  3150. the following section.  %@NL@%
  3151. %@NL@%
  3152. The %@AB@%malloc%@AE@% and %@AB@%free%@AE@% routines allocate and free memory space, respectively,
  3153. while a program runs. The %@AB@%malloc%@AE@% routine allocates memory from the "heap,"
  3154. which is a pool of memory not otherwise used by your program. In tiny-,
  3155. small-, and medium-model programs, the heap consists of unused memory in
  3156. your program's default data segment. In compact-, large-, and huge-model
  3157. programs, it is unused memory outside the default data segment.  %@NL@%
  3158. %@NL@%
  3159. The %@AB@%malloc%@AE@% and %@AB@%free%@AE@% routines satisfy the memory-allocation requirements of
  3160. most programs. More specialized memory-management routines are discussed
  3161. below.  %@NL@%
  3162. %@NL@%
  3163. The %@AB@%realloc%@AE@% and %@AB@%_expand%@AE@% routines can expand or shrink an allocated memory
  3164. block. They behave differently in cases in which there is not enough room to
  3165. expand the block in its current location. In this case, %@AB@%realloc%@AE@% moves the
  3166. block as needed, but %@AB@%_expand%@AE@% does not.  %@NL@%
  3167. %@NL@%
  3168. The %@AB@%calloc%@AE@% routine allocates memory for an array and initializes every byte
  3169. in the allocated block to 0.  %@NL@%
  3170. %@NL@%
  3171. The %@AB@%halloc%@AE@% routine is similar to %@AB@%calloc%@AE@%, except that it can allocate memory
  3172. for a huge array (one that exceeds 64K in size). This routine is useful when
  3173. you need a very large data object, or if you need to return allocated memory
  3174. to the operating system for subsequent calls to the %@AB@%spawn%@AE@% family of
  3175. functions.  %@NL@%
  3176. %@NL@%
  3177. %@NL@%
  3178. %@3@%%@CR:C6A00020450 @%%@AB@%2.10.1  Near and Far Heaps%@AE@%%@EH@%%@NL@%
  3179. %@NL@%
  3180. As mentioned in the previous section, heap memory can reside inside or
  3181. outside your program's default data segment, depending on what memory model
  3182. your program uses. When it lies inside the default data segment, the heap is
  3183. called the "near heap," since it can be accessed with near pointers. The
  3184. "far heap" is memory that spans one or more segments outside the default
  3185. data segment. The far heap can be accessed only with far pointers.  %@NL@%
  3186. %@NL@%
  3187. In various memory models, %@AB@%malloc%@AE@% automatically allocates memory from the
  3188. near heap or far heap, as appropriate. The C library also includes near and
  3189. far versions of %@AB@%malloc%@AE@%, %@AB@%free%@AE@%, and other memory-management routines, which
  3190. allow you to specify the near and far heaps explicitly. These have the same
  3191. names as standard memory routines, but are preceded by %@AB@%_n%@AE@% (for %@AB@%near%@AE@%) or %@AB@%_f%@AE@%
  3192. (for %@AB@%far%@AE@%).  %@NL@%
  3193. %@NL@%
  3194. For instance, the %@AB@%_nmalloc%@AE@% routine always allocates memory from the near
  3195. heap and returns a near pointer, no matter which memory model your program
  3196. uses. Use %@AB@%_nfree%@AE@% to release memory allocated with %@AB@%_nmalloc%@AE@%.  %@NL@%
  3197. %@NL@%
  3198. Similarly, %@AB@%_fmalloc%@AE@% always allocates memory from the far heap and returns a
  3199. far pointer, regardless of memory model. Use the %@AB@%_ffree%@AE@% routine to release
  3200. memory allocated with %@AB@%_fmalloc%@AE@%.  %@NL@%
  3201. %@NL@%
  3202. %@NL@%
  3203. %@3@%%@CR:C6A00020451 @%%@AB@%2.10.2  Based Heaps%@AE@%%@EH@%%@NL@%
  3204. %@NL@%
  3205. You can also allocate memory from a "based heap," which is a single segment
  3206. that lies outside the default data segment. Based-heap routines generally
  3207. use the same names as standard memory routines, but begin with %@AB@%_b%@AE@%. For
  3208. instance, %@AB@%_bmalloc%@AE@% allocates a memory block from the based heap and %@AB@%_bfree%@AE@%
  3209. frees the block.  %@NL@%
  3210. %@NL@%
  3211. Based heaps offer the following advantages:  %@NL@%
  3212. %@NL@%
  3213. %@NL@%
  3214.   ■   Localized data. Based heaps allow you to group related data in a
  3215.       single segment. This can simplify the management of related data. In
  3216.       OS/2, based heaps can also minimize the risk of general protection
  3217.       faults and improve performance.%@NL@%
  3218. %@NL@%
  3219.   ■   Faster pointer arithmetic. Although the based heap lies in the far
  3220.       data segment, pointers to its data items are the same size as near
  3221.       pointers. Thus, pointer arithmetic on items in a based heap is faster
  3222.       than pointer arithmetic on items in the far heap.%@NL@%
  3223. %@NL@%
  3224. %@NL@%
  3225. The %@AB@%_bheapseg%@AE@% routine allocates a based heap segment, from which you can
  3226. then allocate blocks of memory. You can call %@AB@%_bheapseg%@AE@% more than once to
  3227. allocate as many based-heap segments as needed (within the confines of
  3228. available memory).  %@NL@%
  3229. %@NL@%
  3230. The %@AB@%_bfreeseg%@AE@% routine frees a based-heap segment. This routine frees every
  3231. block in the based-heap segment, whether or not you previously freed the
  3232. blocks individually.  %@NL@%
  3233. %@NL@%
  3234. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3235. NOTE
  3236. %@AI@%Near- , far- , and based-heap calls are not ANSI compatible and will make
  3237. %@AI@%your program less portable.%@AE@%%@NL@%
  3238. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  3239. %@NL@%
  3240. %@NL@%
  3241. %@2@%%@CR:C6A00020452 @%%@AB@%2.11  Process and Environment Control%@CR:C6A00020453 @% %@CR:C6A00020454 @%%@CR:C6A00020455 @%%@AE@%%@EH@%%@NL@%
  3242. %@NL@%
  3243. The process-control routines allow you to start, stop, and manage processes
  3244. from within a program. Environment-control routines allow you to get and
  3245. change information about the operating-system environment.%@CR:C6A00020456 @%%@CR:C6A00020457 @%%@CR:C6A00020458 @%%@CR:C6A00020459 @%%@CR:C6A00020460 @%%@CR:C6A00020461 @%%@CR:C6A00020462 @%  %@NL@%
  3246. %@NL@%
  3247. A "process" is a program being executed by the operating system. It consists
  3248. of the program's code and data, plus information about the process, such as
  3249. the number of open files. Whenever you execute a program at the
  3250. operating-system level, you start a process.%@CR:C6A00020463 @%%@CR:C6A00020464 @%%@CR:C6A00020465 @%%@CR:C6A00020466 @%%@CR:C6A00020467 @%%@CR:C6A00020468 @%%@CR:C6A00020469 @%%@CR:C6A00020470 @%%@CR:C6A00020471 @%%@CR:C6A00020472 @%  %@NL@%
  3251. %@NL@%
  3252. All process-control functions except %@AB@%signal%@AE@% are declared in the include file
  3253. PROCESS.H. The %@AB@%signal%@AE@% function is declared in SIGNAL.H. The %@AB@%abort%@AE@%, %@AB@%exit%@AE@%, and
  3254. %@AB@%system%@AE@% functions are also declared in the STDLIB.H include file. The
  3255. environment-control routines (%@AB@%getenv%@AE@% and %@AB@%putenv%@AE@%) are declared in STDLIB.H.%@CR:C6A00020473 @%%@CR:C6A00020474 @%%@CR:C6A00020475 @%%@CR:C6A00020476 @%  %@NL@%
  3256. %@NL@%
  3257. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3258. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3259. %@AB@%abort%@AE@%                             Aborts a process without flushing 
  3260.                                   buffers or calling functions registered 
  3261.                                   by %@AB@%atexit%@AE@% and %@AB@%onexit%@AE@%
  3262.  
  3263. %@AB@%assert%@AE@%                            Tests for logic error
  3264.  
  3265. %@AB@%atexit%@AE@%                            Schedules routines for execution at 
  3266.                                   program
  3267.                                   termination
  3268.  
  3269. %@AB@%_beginthread%@AE@%                      Creates an execution thread (OS/2 only)
  3270.  
  3271. %@AB@%_cexit%@AE@%                            Performs the %@AB@%exit%@AE@% termination procedures
  3272.                                   (such as flushing buffers) and returns 
  3273.                                   control to the calling program
  3274.  
  3275. %@AB@%_c_exit%@AE@%                           Performs the %@AB@%_exit%@AE@% termination 
  3276.                                   procedures and returns control to the 
  3277.                                   calling program
  3278.  
  3279. %@AB@%cwait%@AE@%                             Suspends the calling process until a 
  3280.                                   specified child process terminates (OS/2
  3281.                                   only)
  3282.  
  3283. %@AB@%_endthread%@AE@%                        Terminates an execution thread (OS/2 
  3284.                                   only)
  3285.  
  3286. %@AB@%execl%@AE@%                             Executes child process with argument 
  3287.                                   list
  3288.  
  3289. %@AB@%execle%@AE@%                            Executes child process with argument 
  3290.                                   list and given environment
  3291.  
  3292. %@AB@%execlp%@AE@%                            Executes child process using PATH 
  3293.                                   variable and argument list
  3294.  
  3295. %@AB@%execlpe%@AE@%                           Executes child process using PATH 
  3296.                                   variable, given environment, and 
  3297.                                   argument list
  3298.  
  3299. %@AB@%execv%@AE@%                             Executes child process with argument 
  3300.                                   array
  3301.  
  3302. %@AB@%execve%@AE@%                            Executes child process with argument 
  3303.                                   array and given environment
  3304.  
  3305. %@AB@%execvp%@AE@%                            Executes child process using PATH 
  3306.                                   variable and argument array
  3307.  
  3308. %@AB@%execvpe%@AE@%                           Executes child process using PATH 
  3309.                                   variable, given environment, and 
  3310.                                   argument array
  3311.  
  3312. %@AB@%exit%@AE@%                              Calls functions registered by %@AB@%atexit%@AE@% and
  3313.                                   %@AB@%onexit%@AE@%, then flushes all buffers and 
  3314.                                   closes all open files before terminating
  3315.                                   the process
  3316.  
  3317. %@AB@%_exit%@AE@%                             Terminates process without processing %@AB@%%@AE@%
  3318.                                   %@AB@%atexit%@AE@% or %@AB@%onexit%@AE@% functions or flushing 
  3319.                                   buffers
  3320.  
  3321. %@AB@%getenv%@AE@%                            Gets the value of an environment 
  3322.                                   variable
  3323.  
  3324. %@AB@%getpid%@AE@%                            Gets process ID number
  3325.  
  3326. %@AB@%longjmp%@AE@%                           Restores a saved stack environment
  3327.  
  3328. %@AB@%onexit%@AE@%                            Schedules routines for execution at 
  3329.                                   program
  3330.                                   termination
  3331.  
  3332. %@AB@%_pclose%@AE@%                           Waits for a child command and closes a 
  3333.                                   pipe on the associated stream
  3334.  
  3335. %@AB@%perror%@AE@%                            Prints error message
  3336.  
  3337. %@AB@%_pipe%@AE@%                             Creates a pipe
  3338.  
  3339. %@AB@%_popen%@AE@%                            Creates a pipe and asynchronously 
  3340.                                   executes a child copy of the command 
  3341.                                   processor
  3342.  
  3343. %@AB@%putenv%@AE@%                            Adds or changes the value of an 
  3344.                                   environment
  3345.                                   variable
  3346.  
  3347. %@AB@%raise%@AE@%                             Sends a signal to the calling process
  3348.  
  3349. %@AB@%setjmp%@AE@%                            Saves a stack environment
  3350.  
  3351. %@AB@%signal%@AE@%                            Handles an interrupt signal
  3352.  
  3353. %@AB@%spawnl%@AE@%                            Executes child process with argument 
  3354.                                   list
  3355.  
  3356. %@AB@%spawnle%@AE@%                           Executes child process with argument 
  3357.                                   list and given environment
  3358.  
  3359. %@AB@%spawnlp%@AE@%                           Executes child process using PATH 
  3360.                                   variable and argument list
  3361.  
  3362. %@AB@%spawnlpe%@AE@%                          Executes child process using PATH 
  3363.                                   variable, given environment, and 
  3364.                                   argument list
  3365.  
  3366. %@AB@%spawnv%@AE@%                            Executes child process with argument 
  3367.                                   array
  3368.  
  3369. %@AB@%spawnve%@AE@%                           Executes child process with argument 
  3370.                                   array and given environment
  3371.  
  3372. %@AB@%spawnvp%@AE@%                           Executes child process using PATH 
  3373.                                   variable and argument array
  3374.  
  3375. %@AB@%spawnvpe%@AE@%                          Executes child process using PATH 
  3376.                                   variable, given environment, and 
  3377.                                   argument array
  3378.  
  3379. %@AB@%system%@AE@%                            Executes an operating system command
  3380.  
  3381. %@AB@%wait%@AE@%                              Suspends the calling process until any 
  3382.                                   of the caller's immediate child 
  3383.                                   processes terminate (OS/2 only)
  3384.  
  3385. The %@AB@%atexit%@AE@% and %@AB@%onexit%@AE@% routines create a list of functions to be executed
  3386. when the calling program terminates. The only difference between the two is
  3387. that %@AB@%atexit%@AE@% is part of the ANSI standard. The %@AB@%onexit%@AE@% function is offered for
  3388. compatibility with previous versions of Microsoft C.  %@NL@%
  3389. %@NL@%
  3390. The %@AB@%_exit%@AE@% routine terminates a process immediately, whereas %@AB@%exit%@AE@% terminates
  3391. the process only after flushing buffers and calling any functions previously
  3392. registered by %@AB@%atexit%@AE@% and %@AB@%onexit%@AE@%. The %@AB@%_cexit%@AE@% and %@AB@%_c_exit%@AE@% routines are
  3393. identical to %@AB@%exit%@AE@% and %@AB@%_exit%@AE@%, respectively, except that they return control
  3394. to the calling program without terminating the process.  %@NL@%
  3395. %@NL@%
  3396. The %@AB@%setjmp%@AE@% and %@AB@%longjmp%@AE@% routines save and restore a stack environment. These
  3397. allow you to execute a nonlocal %@AB@%goto%@AE@%.  %@NL@%
  3398. %@NL@%
  3399. The %@AB@%exec%@AE@% and %@AB@%spawn%@AE@% routines start a new process called the "child" process.
  3400. The difference between the %@AB@%exec%@AE@% and %@AB@%spawn%@AE@% routines is that the %@AB@%spawn%@AE@%
  3401. routines are capable of returning control from the child process to its
  3402. caller (the "parent" process). Both the parent process and the child process
  3403. are present in memory (unless %@AB@%P_OVERLAY%@AE@% is specified). In the %@AB@%exec%@AE@% routines,
  3404. the child process overlays the parent process, so returning control to the
  3405. parent process is impossible (unless an error occurs when attempting to
  3406. start execution of the child process).  %@NL@%
  3407. %@NL@%
  3408. There are eight forms each of the %@AB@%spawn%@AE@% and %@AB@%exec%@AE@% routines (see Table 2.1).
  3409. The differences among the forms involve the method of locating the file to
  3410. be executed as the child process, the method for passing arguments to the
  3411. child process, and the method of setting the environment.  %@NL@%
  3412. %@NL@%
  3413. Passing an argument list means that the arguments to the child process are
  3414. listed separately in the %@AB@%exec%@AE@% or %@AB@%spawn%@AE@% call. Passing an argument array means
  3415. that the arguments are stored in an array, and a pointer to the array is
  3416. passed to the child process. The argument-list method is typically used when
  3417. the number of arguments is constant or is known at compile time. The
  3418. argument-array method is useful when the number of arguments must be
  3419. determined at run time.  %@NL@%
  3420. %@NL@%
  3421. Several process-control routines take advantage of the multitasking
  3422. capability of OS/2. The %@AB@%_beginthread%@AE@% and %@AB@%_endthread%@AE@% routines create and
  3423. terminate execution threads. The %@AB@%cwait%@AE@% and %@AB@%wait%@AE@% routines suspend the calling
  3424. process until one child process terminates. The %@AB@%_pipe%@AE@%, %@AB@%_popen%@AE@%, and %@AB@%_pclose%@AE@%
  3425. routines create and manipulate pipes, which link processes for sequential
  3426. execution.  %@NL@%
  3427. %@NL@%
  3428. %@AB@%Table 2.1  Forms of the spawn and exec Routines%@AE@%
  3429.  
  3430. %@TH:  42  2708 03 20 19 21 21 @%                                       Argument-Passing     Routines            Locating the File  Convention           Environment                                                             Settings%@AB@%─────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%execl%@AE@%, %@AB@%spawnl%@AE@%       Do not use PATH    Argument list        Inherited from                                                             parent%@AB@%execle%@AE@%, %@AB@%spawnle%@AE@%     Do not use PATH    Argument list        Pointer to                                                             environment table                                                             for child process                                                             passed as last                                                             argument%@AB@%execlp%@AE@%, %@AB@%spawnlp%@AE@%     Use PATH           Argument list        Inherited from                                                             parent%@AB@%execlpe%@AE@%, %@AB@%spawnlpe%@AE@%   Use PATH           Argument list        Pointer to                                                             environment table                                                             for child process                                                             passed as last                                                            argument%@AB@%execv%@AE@%, %@AB@%spawnv%@AE@%       Do not use PATH    Argument array       Inherited from                                                             parent%@AB@%execve%@AE@%, %@AB@%spawnve%@AE@%     Do not use PATH    Argument array       Pointer to                                                             environment table                                                             for child process                                                             passed as last                                                            argument%@AB@%execvp%@AE@%, %@AB@%spawnvp%@AE@%     Use PATH           Argument array       Inherited from                                                             parent%@AB@%execvpe%@AE@%, %@AB@%spawnvpe%@AE@%   Use PATH           Argument array       Pointer to                                                             environment table                                                             for child process                                                             passed as last                                                             argument%@AB@%─────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  42  2708 03 20 19 21 21 @%
  3431.  
  3432. The %@AB@%assert%@AE@% macro is typically used to test for logic errors. It prints a
  3433. message when a given "assertion" fails to hold true. Defining the identifier
  3434. %@AB@%NDEBUG%@AE@% to any value causes occurrences of %@AB@%assert%@AE@% to be removed from the
  3435. source file, thus allowing you to turn off assertion checking without
  3436. modifying the source file.  %@NL@%
  3437. %@NL@%
  3438. %@NL@%
  3439. %@2@%%@CR:C6A00020477 @%%@AB@%2.12  Searching and Sorting%@CR:C6A00020478 @% %@CR:C6A00020479 @%%@AE@%%@EH@%%@NL@%
  3440. %@NL@%
  3441. Search and sort routines provide binary-search, linear-search, and
  3442. quick-sort capabilities. They are all declared in SEARCH.H.%@CR:C6A00020480 @%  %@NL@%
  3443. %@NL@%
  3444. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3445. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3446. %@AB@%bsearch%@AE@%%@CR:C6A00020481 @%%@CR:C6A00020482 @%                           Performs binary search
  3447.  
  3448. %@AB@%lfind%@AE@%%@CR:C6A00020483 @%%@CR:C6A00020484 @%                             Performs linear search for given value
  3449.  
  3450. %@AB@%lsearch%@AE@%%@CR:C6A00020485 @%                           Performs linear search for given value, 
  3451.                                   which is added to array if not found
  3452.  
  3453. %@AB@%qsort%@AE@%%@CR:C6A00020486 @%  %@CR:C6A00020487 @%                           Performs quick sort
  3454.  
  3455. %@NL@%
  3456. %@2@%%@CR:C6A00020488 @%%@AB@%2.13  String Manipulation%@CR:C6A00020489 @%%@AE@%%@EH@%%@NL@%
  3457. %@NL@%
  3458. The string functions are declared in the include file STRING.H. They allow
  3459. you to compare strings, copy them, search for strings and characters, and
  3460. perform various other operations.%@CR:C6A00020490 @%%@CR:C6A00020491 @%%@CR:C6A00020492 @%%@CR:C6A00020493 @%%@CR:C6A00020494 @%%@CR:C6A00020495 @%%@CR:C6A00020496 @%%@CR:C6A00020497 @%%@CR:C6A00020498 @%%@CR:C6A00020499 @%%@CR:C6A00020500 @%
  3461. %@CR:C6A00020501 @%%@CR:C6A00020502 @%  %@NL@%
  3462. %@NL@%
  3463. Routines beginning with %@AB@%_f%@AE@% are model-independent versions of the
  3464. corresponding routines and are useful in mixed-model programs. These
  3465. routines can be called from any point in the program, regardless of which
  3466. model is being used.%@CR:C6A00020503 @%%@CR:C6A00020504 @%%@CR:C6A00020505 @%%@CR:C6A00020506 @%%@CR:C6A00020507 @%%@CR:C6A00020508 @%%@CR:C6A00020509 @%%@CR:C6A00020510 @%  %@NL@%
  3467. %@NL@%
  3468. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3469. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3470. %@AB@%strcat%@AE@%,   %@AB@%_fstrcat%@AE@%%@CR:C6A00020511 @%                Append one string to another
  3471.  
  3472. %@AB@%strchr%@AE@%,  %@AB@%_fstrchr%@AE@%%@CR:C6A00020512 @%                 Find first occurrence of a given 
  3473.                                   character in a string
  3474.  
  3475. %@AB@%strcmp%@AE@%,  %@AB@%_fstrcmp%@AE@%%@CR:C6A00020513 @%                 Compare two strings
  3476.  
  3477. %@AB@%strcpy%@AE@%,  %@AB@%_fstrcpy%@AE@%%@CR:C6A00020514 @%                 Copy one string to another
  3478.  
  3479. %@AB@%strcspn%@AE@%,  %@AB@%_fstrcspn%@AE@%               Find first occurrence of a character 
  3480.                                   from a given character set in a string
  3481.  
  3482. %@AB@%strdup%@AE@%,  %@AB@%_fstrdup%@AE@%, %@AB@%_nstrdup%@AE@%       Duplicate a string
  3483.  
  3484. %@AB@%strerror%@AE@%                          Maps an error number to a message string
  3485.  
  3486. %@AB@%_strerror%@AE@%                         Maps a user-defined error message to a 
  3487.                                   string
  3488.  
  3489. %@AB@%stricmp%@AE@%,  %@AB@%_fstricmp%@AE@%               Compare two strings without regard to 
  3490.                                   case
  3491.  
  3492. %@AB@%strlen%@AE@%,  %@AB@%_fstrlen%@AE@%                 Find length of string
  3493.  
  3494. %@AB@%strlwr%@AE@%,  %@AB@%_fstrlwr%@AE@%                 Convert string to lowercase
  3495.  
  3496. %@AB@%strncat%@AE@%,  %@AB@%_fstrncat%@AE@%               Append characters of a string
  3497.  
  3498. %@AB@%strncmp%@AE@%,  %@AB@%_fstrncmp%@AE@%               Compare characters of two strings
  3499.  
  3500. %@AB@%strncpy%@AE@%,  %@AB@%_fstrncpy%@AE@%               Copy characters of one string to another
  3501.  
  3502. %@AB@%strnicmp%@AE@%,  %@AB@%_fstrnicmp%@AE@%             Compare characters of two strings 
  3503.                                   without regard
  3504.                                   to case 
  3505.  
  3506. %@AB@%strnset%@AE@%,  %@AB@%_fstrnset%@AE@%               Set characters of a string to a given 
  3507.                                   character
  3508.  
  3509. %@AB@%strpbrk%@AE@%,  %@AB@%_fstrpbrk%@AE@%               Find first occurrence of a character 
  3510.                                   from one string in another
  3511.  
  3512. %@AB@%strrchr%@AE@%,  %@AB@%_fstrrchr%@AE@%               Find last occurrence of a given 
  3513.                                   character in string
  3514.  
  3515. %@AB@%strrev%@AE@%,  %@AB@%_fstrrev%@AE@%                 Reverse string
  3516.  
  3517. %@AB@%strset%@AE@%,  %@AB@%_fstrset%@AE@%                 Set all characters of a string to a 
  3518.                                   given character
  3519.  
  3520. %@AB@%strspn%@AE@%,  %@AB@%_fstrspn%@AE@%                 Find first substring from a given 
  3521.                                   character set in a string
  3522.  
  3523. %@AB@%strstr%@AE@%,  %@AB@%_fstrstr%@AE@%                 Find first occurrence of a given string 
  3524.                                   in another string
  3525.  
  3526. %@AB@%strtok%@AE@%,  %@AB@%_fstrtok%@AE@%                 Find next token in a string
  3527.  
  3528. %@AB@%strupr%@AE@%,  %@AB@%_fstrupr%@AE@%                 Convert a string to uppercase
  3529.  
  3530. All string functions work on null-terminated character strings. When working
  3531. with character arrays that do not end with a null character, you can use the
  3532. buffer-manipulation routines, described in Section 2.1.  %@NL@%
  3533. %@NL@%
  3534. %@NL@%
  3535. %@2@%%@CR:C6A00020515 @%%@AB@%2.14  System Calls%@AE@%%@EH@%%@NL@%
  3536. %@NL@%
  3537. The following routines give access to IBM-PC BIOS interrupts and DOS system
  3538. calls. Except for the %@AB@%FP_OFF%@AE@%, %@AB@%FP_SEG%@AE@%, and %@AB@%segread%@AE@% routines, these routines
  3539. are for DOS application programs only; they do not work under OS/2.%@CR:C6A00020516 @%%@CR:C6A00020517 @%%@CR:C6A00020518 @%  %@NL@%
  3540. %@NL@%
  3541. %@NL@%
  3542. %@3@%%@CR:C6A00020519 @%%@AB@%2.14.1  BIOS Interface%@CR:C6A00020520 @% %@CR:C6A00020521 @%%@CR:C6A00020522 @%%@CR:C6A00020523 @%%@AE@%%@EH@%%@NL@%
  3543. %@NL@%
  3544. The functions in this category provide direct access to the BIOS interrupt
  3545. services. They are all declared in BIOS.H.  %@NL@%
  3546. %@NL@%
  3547. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3548. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3549. %@AB@%_bios_disk%@AE@%                        Issues service requests for both hard 
  3550.                                   and floppy disks, using INT 0x13
  3551.  
  3552. %@AB@%_bios_equiplist%@AE@%                   Performs an equipment check, using INT 
  3553.                                   0x11
  3554.  
  3555. %@AB@%_bios_keybrd%@AE@%                      Provides access to keyboard services, 
  3556.                                   using
  3557.                                   INT 0x16
  3558.  
  3559. %@AB@%_bios_memsize%@AE@%                     Obtains information about available 
  3560.                                   memory, using INT 0x12
  3561.  
  3562. %@AB@%_bios_printer%@AE@%                     Performs printer output services, using 
  3563.                                   INT 0x17
  3564.  
  3565. %@AB@%_bios_serialcom%@AE@%                   Performs serial communications tasks, 
  3566.                                   using
  3567.                                   INT 0x14
  3568.  
  3569. %@AB@%_bios_timeofday%@AE@%                   Provides access to system clock, using 
  3570.                                   INT 0x1A
  3571.  
  3572. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3573. NOTE
  3574. %@AI@%BIOS routines are hardware dependent. Some of them may not work as expected
  3575. %@AI@%on machines whose hardware differs from the IBM PC.%@AE@%%@NL@%
  3576. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  3577. %@NL@%
  3578. %@NL@%
  3579. %@3@%%@CR:C6A00020524 @%%@AB@%2.14.2  DOS Interface%@CR:C6A00020525 @%%@CR:C6A00020526 @%%@CR:C6A00020527 @%%@AE@%%@EH@%%@NL@%
  3580. %@NL@%
  3581. These routines are implemented as functions and declared in DOS.H.%@CR:C6A00020528 @%%@CR:C6A00020529 @%%@CR:C6A00020530 @%%@CR:C6A00020531 @%%@CR:C6A00020532 @%  %@NL@%
  3582. %@NL@%
  3583. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3584. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3585. %@AB@%bdos%@AE@%                              Invokes DOS system call; uses only DX 
  3586.                                   and AL registers %@CR:C6A00020533 @%
  3587.  
  3588. %@AB@%_chain_intr%@AE@%                       Chains one interrupt handler to another %@CR:C6A00020534 @%
  3589.  
  3590. %@AB@%_disable%@AE@%                          Disables interrupts %@CR:C6A00020535 @%
  3591.  
  3592. %@AB@%_dos_allocmem%@AE@%                     Allocates a block of memory, using DOS 
  3593.                                   system call 0x48 %@CR:C6A00020536 @%
  3594.  
  3595. %@AB@%_dos_close%@AE@%                        Closes a file, using DOS system call 
  3596.                                   0x3E %@CR:C6A00020537 @%
  3597.  
  3598. %@AB@%_dos_creat%@AE@%                        Creates a new file and erases any 
  3599.                                   existing file having the same name, 
  3600.                                   using DOS system call 0x3C %@CR:C6A00020538 @%
  3601.  
  3602. %@AB@%_dos_creatnew%@AE@%                     Creates a new file and returns an error 
  3603.                                   if a file having the same name exists, 
  3604.                                   using DOS system
  3605.                                   call 0x5B %@CR:C6A00020539 @%
  3606.  
  3607. %@AB@%_dos_findfirst%@AE@%                    Finds first occurrence of a given file, 
  3608.                                   using DOS system call 0x4E %@CR:C6A00020540 @%
  3609.  
  3610. %@AB@%_dos_findnext%@AE@%                     Finds subsequent occurrences of a given 
  3611.                                   file, using DOS system call 0x4F %@CR:C6A00020541 @%
  3612.  
  3613. %@AB@%_dos_freemem%@AE@%                      Frees a block of memory, using DOS 
  3614.                                   system
  3615.                                   call 0x49 %@CR:C6A00020542 @%
  3616.  
  3617. %@AB@%_dos_getdate%@AE@%                      Gets the system date, using DOS system 
  3618.                                   call 0x2A %@CR:C6A00020543 @%
  3619.  
  3620. %@AB@%_dos_getdiskfree%@AE@%                  Gets information on a disk volume, using
  3621.                                   DOS system call 0x36 %@CR:C6A00020544 @%
  3622.  
  3623. %@AB@%_dos_getdrive%@AE@%                     Gets the current default drive, using 
  3624.                                   DOS system call 0x19 %@CR:C6A00020545 @%
  3625.  
  3626. %@AB@%_dos_getfileattr%@AE@%                  Gets current attributes of a file or 
  3627.                                   directory, using DOS system call 0x43 %@CR:C6A00020546 @%
  3628.  
  3629. %@AB@%_dos_getftime%@AE@%                     Gets the date and time a file was last 
  3630.                                   written, using DOS system call 0x57 %@CR:C6A00020547 @%
  3631.  
  3632. %@AB@%_dos_gettime%@AE@%                      Gets the current system time, using DOS 
  3633.                                   system
  3634.                                   call 0x2C %@CR:C6A00020548 @%
  3635.  
  3636. %@AB@%_dos_getvect%@AE@%                      Gets the current value of a specified 
  3637.                                   interrupt vector, using DOS system call 
  3638.                                   0x35 %@CR:C6A00020549 @%
  3639.  
  3640. %@AB@%_dos_keep%@AE@%                         Installs terminate-and-stay-resident 
  3641.                                   (TSR) programs using DOS system call 
  3642.                                   0x31 %@CR:C6A00020550 @%
  3643.  
  3644. %@AB@%_dos_open%@AE@%                         Opens an existing file, using DOS system
  3645.                                   call 0x3D %@CR:C6A00020551 @%
  3646.  
  3647. %@AB@%_dos_read%@AE@%                         Reads a file, using DOS system call 0x3F
  3648.                                   %@CR:C6A00020552 @%
  3649.  
  3650. %@AB@%_dos_setblock%@AE@%                     Changes the size of a previously 
  3651.                                   allocated block, using DOS system call 
  3652.                                   0x4A %@CR:C6A00020553 @%
  3653.  
  3654. %@AB@%_dos_setdate%@AE@%                      Sets the current system date, using DOS 
  3655.                                   system
  3656.                                   call 0x2B %@CR:C6A00020554 @%
  3657.  
  3658. %@AB@%_dos_setdrive%@AE@%                     Sets the default disk drive, using DOS 
  3659.                                   system
  3660.                                   call 0x0E %@CR:C6A00020555 @%
  3661.  
  3662. %@AB@%_dos_setfileattr%@AE@%                  Sets the current attributes of a file, 
  3663.                                   using DOS system call 0x43 %@CR:C6A00020556 @%
  3664.  
  3665. %@AB@%_dos_setftime%@AE@%                     Sets the date and time that the 
  3666.                                   specified file was last written, using 
  3667.                                   DOS system call 0x57 %@CR:C6A00020557 @%
  3668.  
  3669. %@AB@%_dos_settime%@AE@%                      Sets the system time, using DOS system 
  3670.                                   call 0x2D %@CR:C6A00020558 @%
  3671.  
  3672. %@AB@%_dos_setvect%@AE@%                      Sets a new value for the specified 
  3673.                                   interrupt vector, using DOS system call 
  3674.                                   0x25 %@CR:C6A00020559 @%
  3675.  
  3676. %@AB@%_dos_write%@AE@%                        Sends output to a file, using DOS system
  3677.                                   call 0x40 %@CR:C6A00020560 @%
  3678.  
  3679. %@AB@%dosexterr%@AE@%                         Obtains in-depth error information from 
  3680.                                   DOS system call 0x59 %@CR:C6A00020561 @%
  3681.  
  3682. %@AB@%_enable%@AE@% %@CR:C6A00020562 @%                          Enables interrupts 
  3683.  
  3684. %@AB@%FP_OFF%@AE@%                            Returns offset portion of a far pointer 
  3685.                                   (OS/2
  3686.                                   and DOS) %@CR:C6A00020563 @%
  3687.  
  3688. %@AB@%FP_SEG%@AE@%                            Returns segment portion of a far pointer
  3689.                                   (OS/2
  3690.                                   and DOS)
  3691.  
  3692. %@AB@%_harderr%@AE@%                          Establishes a hardware error handler %@CR:C6A00020564 @%
  3693.  
  3694. %@AB@%_hardresume%@AE@%                       Returns to DOS after a hardware error %@CR:C6A00020565 @%
  3695.  
  3696. %@AB@%_hardretn%@AE@%                         Returns to the application after a 
  3697.                                   hardware error %@CR:C6A00020566 @%
  3698.  
  3699. %@AB@%int86%@AE@%                             Invokes DOS interrupts %@CR:C6A00020567 @%
  3700.  
  3701. %@AB@%int86x%@AE@%                            Invokes DOS interrupts with segment 
  3702.                                   register values %@CR:C6A00020568 @%
  3703.  
  3704. %@AB@%intdos%@AE@%                            Invokes DOS system call using registers 
  3705.                                   other than DX and AL %@CR:C6A00020569 @%
  3706.  
  3707. %@AB@%intdosx%@AE@%                           Invokes DOS system call using registers 
  3708.                                   other than DX and AL with segment 
  3709.                                   register values %@CR:C6A00020570 @%
  3710.  
  3711. %@AB@%segread%@AE@%                           Returns current values of segment 
  3712.                                   registers (OS/2 and DOS) %@CR:C6A00020571 @%
  3713.  
  3714. The %@AB@%_harderr%@AE@% routine is used to define a hardware-error interrupt handler.
  3715. The %@AB@%_hardresume%@AE@% and %@AB@%_hardretn%@AE@% routines are used within a hardware error
  3716. handler to define the return from the error.  %@NL@%
  3717. %@NL@%
  3718. The %@AB@%dosexterr%@AE@% function obtains and stores the error information returned by
  3719. DOS system call 0x59 (extended error handling). This function is provided
  3720. for use with DOS versions 3.0 and later.%@CR:C6A00020572 @%%@CR:C6A00020573 @%%@CR:C6A00020574 @%  %@NL@%
  3721. %@NL@%
  3722. The %@AB@%bdos%@AE@% routine is useful for invoking DOS calls that use either or both of
  3723. the DX (DH/DL) and AL registers for arguments. However, %@AB@%bdos%@AE@% should not be
  3724. used to invoke system calls that return an error code in AX if the carry
  3725. flag is set; since your program cannot detect whether the carry flag is set,
  3726. it cannot determine whether the value in AX is a legitimate value or an
  3727. error value. In this case, the %@AB@%intdos%@AE@% routine should be used instead, since
  3728. it allows the program to detect whether the carry flag is set. The %@AB@%intdos%@AE@%
  3729. routine can also be used to invoke DOS calls that use registers other than
  3730. DX and AL.  %@NL@%
  3731. %@NL@%
  3732. The %@AB@%intdosx%@AE@% routine is similar to the %@AB@%intdos%@AE@% routine, but is used when ES is
  3733. required by the system call, when DS must contain a value other than the
  3734. default data segment (for instance, when a far pointer is used), or when
  3735. making the system call in a large-model program. When calling %@AB@%intdosx%@AE@%, give
  3736. an argument that specifies the segment values to be used in the call.  %@NL@%
  3737. %@NL@%
  3738. The %@AB@%int86%@AE@% routine can be used to invoke any interrupt. The %@AB@%int86x%@AE@% routine is
  3739. similar; however, like the %@AB@%intdosx%@AE@% routine, it is designed to work with
  3740. large-model programs and far items, as described in the preceding paragraph.
  3741. %@NL@%
  3742. %@NL@%
  3743. The %@AB@%FP_OFF%@AE@% and %@AB@%FP_SEG%@AE@% routines allow easy access to the segment and offset
  3744. portions of a far pointer value. %@AB@%FP_OFF%@AE@% and %@AB@%FP_SEG%@AE@% are implemented as macros
  3745. and defined in DOS.H. You can use these macros in OS/2 as well as DOS.%@CR:C6A00020575 @%%@CR:C6A00020576 @%  %@NL@%
  3746. %@NL@%
  3747. The %@AB@%segread%@AE@% routine returns the current values of the segment registers.
  3748. This routine is typically used with the %@AB@%intdosx%@AE@% and %@AB@%int86x%@AE@% routines to
  3749. obtain the correct segment values.  %@NL@%
  3750. %@NL@%
  3751. The %@AB@%_chain_intr%@AE@% routine is useful for chaining interrupt handlers together.
  3752. The %@AB@%_enable%@AE@% routine enables interrupts, while the %@AB@%_disable%@AE@% routine disables
  3753. interrupts.  %@NL@%
  3754. %@NL@%
  3755. %@CR:C6A00020577 @%%@CR:C6A00020578 @%The routines prefixed with  %@AB@%_dos_%@AE@%  are all direct system interfaces that use
  3756. the system calls noted above. More detailed information on these system
  3757. calls can be found in the %@AI@%MS-DOS Encyclopedia %@AE@%(Duncan, ed.; Redmond, WA:
  3758. Microsoft Press, 1988)or the%@AI@% Programmer's PC Sourcebook %@AE@%(Hogan; Redmond, WA:
  3759. Microsoft Press, 1988)%@AI@%.  %@AE@%%@NL@%
  3760. %@NL@%
  3761. ────────────────────────────────────────────────────────────────────────────%@NL@%
  3762. NOTE
  3763.  
  3764. %@AI@%The DOS interface I/O routines are generally incompatible with console,
  3765. %@AI@%low-level, and stream I/O routines. Do not mix different types of I/O
  3766. %@AI@%routines in the same source file.%@AE@%%@NL@%
  3767. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  3768. %@NL@%
  3769. %@NL@%
  3770. %@2@%%@CR:C6A00020579 @%%@AB@%2.15  Time%@CR:C6A00020580 @%%@CR:C6A00020581 @%%@CR:C6A00020582 @%%@CR:C6A00020583 @%%@AE@%%@EH@%%@NL@%
  3771. %@NL@%
  3772. The time functions allow you to obtain the current time, then convert and
  3773. store it according to your particular needs. The current time is always
  3774. taken from the system time.%@CR:C6A00020584 @%%@CR:C6A00020585 @%%@CR:C6A00020586 @%%@CR:C6A00020587 @%%@CR:C6A00020588 @%%@CR:C6A00020589 @%%@CR:C6A00020590 @%%@CR:C6A00020591 @%  %@NL@%
  3775. %@NL@%
  3776. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3777. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3778. %@AB@%asctime%@AE@%                           Converts time from type %@AB@%struct tm%@AE@% to a 
  3779.                                   character string
  3780.  
  3781. %@AB@%clock%@AE@%                             Returns the elapsed CPU time for a 
  3782.                                   process
  3783.  
  3784. %@AB@%ctime%@AE@%                             Converts time from a long integer to a 
  3785.                                   character string
  3786.  
  3787. %@AB@%difftime%@AE@%                          Computes the difference between two 
  3788.                                   times
  3789.  
  3790. %@AB@%ftime%@AE@%                             Puts current system time in variable of 
  3791.                                   type%@AB@%%@AE@%
  3792.                                   %@AB@%struct tm%@AE@%
  3793.  
  3794. %@AB@%gmtime%@AE@%                            Converts time from integer to %@AB@%struct tm%@AE@%
  3795.  
  3796. %@AB@%localtime%@AE@%                         Converts time from integer to %@AB@%struct tm%@AE@% 
  3797.                                   with local correction
  3798.  
  3799. %@AB@%mktime%@AE@%                            Converts time to a calendar value
  3800.  
  3801. %@AB@%_strdate%@AE@%                          Returns the current system date as a 
  3802.                                   string
  3803.  
  3804. %@AB@%strftime%@AE@%                          Formats a date and time string
  3805.  
  3806. %@AB@%_strtime%@AE@%                          Returns the current system time as a 
  3807.                                   string
  3808.  
  3809. %@AB@%time%@AE@%                              Gets current system time as a long 
  3810.                                   integer
  3811.  
  3812. %@AB@%tzset%@AE@%                             Sets external time variables from the 
  3813.                                   environment time variable
  3814.  
  3815. %@AB@%utime%@AE@%                             Sets file-modification time
  3816.  
  3817. The %@AB@%time%@AE@% and %@AB@%ftime%@AE@% functions return the current time as the number of
  3818. seconds elapsed since midnight Universal Coordinated Time (UTC) on January
  3819. 1, 1970. This value can be converted, adjusted, and stored in a variety of
  3820. ways by using the %@AB@%asctime%@AE@%, %@AB@%ctime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, and %@AB@%mktime%@AE@% functions.
  3821. The %@AB@%utime%@AE@% function sets the modification time for a specified file, using
  3822. either the current time or a time value stored in a structure.%@CR:C6A00020592 @%%@CR:C6A00020593 @%%@CR:C6A00020594 @%  %@NL@%
  3823. %@NL@%
  3824. The %@AB@%clock%@AE@% function returns the elapsed CPU time for the calling process.  %@NL@%
  3825. %@NL@%
  3826. The %@AB@%ftime%@AE@% function requires two files: SYS\TYPES.H and SYS\TIMEB.H. It is
  3827. declared in SYS\TIMEB.H. The %@AB@%utime%@AE@% function also requires two include files:
  3828. SYS\TYPES.H and SYS\UTIME.H. It is declared in SYS\UTIME.H. The remainder of
  3829. the time functions are declared in the include file TIME.H.%@CR:C6A00020595 @%%@CR:C6A00020596 @%%@CR:C6A00020597 @%%@CR:C6A00020598 @%%@CR:C6A00020599 @%  %@NL@%
  3830. %@NL@%
  3831. When you want to use %@AB@%ftime%@AE@% or %@AB@%localtime%@AE@% to make adjustments for local time,
  3832. you must define an environment variable named TZ. Section 3.2, which
  3833. describes the global variables %@AB@%daylight%@AE@%, %@AB@%timezone%@AE@%, and %@AB@%tzname%@AE@%, includes a
  3834. discussion of the TZ variable. TZ is also described on the %@AB@%tzset%@AE@% reference
  3835. page in Part 2 of this book.%@CR:C6A00020600 @%%@CR:C6A00020601 @%  %@NL@%
  3836. %@NL@%
  3837. The %@AB@%_strdate%@AE@% and %@AB@%_strtime%@AE@% routines return strings containing the current
  3838. date and time, respectively, in the DOS and OS/2 date and time format rather
  3839. than in the XENIX-style formats.  %@NL@%
  3840. %@NL@%
  3841. The %@AB@%stfrtime%@AE@% function is useful for creating international versions of a
  3842. program. See Section 2.8, "Internationalization."  %@NL@%
  3843. %@NL@%
  3844. %@NL@%
  3845. %@2@%%@CR:C6A00020602 @%%@AB@%2.16  Variable-Length Argument Lists%@AE@%%@EH@%%@NL@%
  3846. %@NL@%
  3847. The %@AB@%va_arg%@AE@%, %@AB@%va_end%@AE@%, and %@AB@%va_start%@AE@% routines are macros that provide a portable
  3848. way to access the arguments to a function when the function takes a variable
  3849. number of arguments. Two versions of the macros are available: the macros
  3850. defined in the VARARG.H include file, which are compatible with the UNIX
  3851. System V definition, and the macros defined in STDARG.H, which conform to
  3852. the ANSI C standard.%@CR:C6A00020603 @%%@CR:C6A00020604 @%%@CR:C6A00020605 @%  %@NL@%
  3853. %@NL@%
  3854. %@AB@%Routine%@AE@%                           %@AB@%Use%@AE@%
  3855. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3856. %@AB@%va_arg%@AE@%                            Retrieves argument from list
  3857.  
  3858. %@AB@%va_end%@AE@%                            Resets pointer
  3859.  
  3860. %@AB@%va_start%@AE@%                          Sets pointer to beginning of argument 
  3861.                                   list
  3862.  
  3863. For more information on the differences between the two versions and for an
  3864. explanation of how to use the macros, see their descriptions in Part 2 of
  3865. this book.  %@NL@%
  3866. %@NL@%
  3867. %@NL@%
  3868. %@NL@%
  3869. %@NL@%
  3870. %@NL@%
  3871. %@NL@%
  3872. %@CR:C6A00030001 @%%@1@%%@AB@%Chapter 3  Global Variables and Standard Types%@AE@%%@EH@%%@NL@%
  3873. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3874. %@NL@%
  3875. The Microsoft C Run-Time Library contains definitions for a number of
  3876. variables and standard types used by library routines. You can access these
  3877. variables and types by including in your program the files in which they are
  3878. declared, or by giving appropriate declarations in your program, as shown in
  3879. the following sections.%@CR:C6A00030002 @%%@CR:C6A00030003 @%  %@NL@%
  3880. %@NL@%
  3881. %@NL@%
  3882. %@2@%%@CR:C6A00030004 @%%@AB@%3.1  _amblksiz%@AE@%%@EH@%%@NL@%
  3883. %@NL@%
  3884. The %@AB@%_amblksiz%@AE@% variable controls memory heap granularity.%@CR:C6A00030005 @%%@CR:C6A00030006 @%  %@NL@%
  3885. %@NL@%
  3886. It is declared in the MALLOC.H include file as follows:  %@NL@%
  3887. %@NL@%
  3888. %@AS@%  extern unsigned int _amblksiz;%@AE@%%@NL@%
  3889. %@NL@%
  3890. The %@AB@%_amblksiz%@AE@% variable controls the amount of memory used in the heap for
  3891. dynamic memory allocation.%@CR:C6A00030007 @%  %@NL@%
  3892. %@NL@%
  3893. Memory space is always requested from the operating system in blocks
  3894. containing %@AB@%_amblksiz%@AE@% bytes. The first time a program calls a
  3895. memory-allocation function such as %@AB@%malloc%@AE@%, the operating system allocates a
  3896. block of heap memory. The size of this block is defined by %@AB@%_amblksiz%@AE@%, which
  3897. has a default value of 8K (8,192 bytes).  %@NL@%
  3898. %@NL@%
  3899. Later memory requests are satisfied from the original block. When that block
  3900. is exhausted, another block of %@AB@%_amblksiz%@AE@% bytes is allocated. If your C
  3901. program allocates a block larger than %@AB@%_amblksiz%@AE@%, multiple blocks that are
  3902. each of size %@AB@%_amblksiz%@AE@% are allocated until the request is satisfied.  %@NL@%
  3903. %@NL@%
  3904. To change the size of the default memory block, assign the desired size to
  3905. the %@AB@%_amblksiz%@AE@% variable, as in the following example:  %@NL@%
  3906. %@NL@%
  3907. %@AS@%  _amblksiz = 2048;%@AE@%%@NL@%
  3908. %@NL@%
  3909. The heap allocator always rounds the operating-system request to the nearest
  3910. power of 2 greater than or equal to %@AB@%_amblksiz%@AE@%. The above statement allocates
  3911. memory in multiples of 2K (2,048 bytes).  %@NL@%
  3912. %@NL@%
  3913. Fewer system calls are required if you set %@AB@%_amblksiz%@AE@% to a large value, but
  3914. your program may use more memory than needed. If program speed is important,
  3915. set %@AB@%_amblksiz%@AE@% to a large value. If size is important, set %@AB@%_amblksiz%@AE@% to a
  3916. smaller value.  %@NL@%
  3917. %@NL@%
  3918. Note that adjusting the value of %@AB@%_amblksiz%@AE@% affects allocation in the near,
  3919. far, and based heaps. The value of %@AB@%_amblksiz%@AE@% has no effect on huge memory
  3920. blocks (those allocated with %@AB@%halloc%@AE@% and similar functions).  %@NL@%
  3921. %@NL@%
  3922. %@NL@%
  3923. %@2@%%@CR:C6A00030008 @%%@AB@%3.2  daylight, timezone, tzname%@AE@%%@EH@%%@NL@%
  3924. %@NL@%
  3925. The %@AB@%daylight%@AE@%, %@AB@%timezone%@AE@%, and %@AB@%tzname%@AE@% variables are global timezone variables
  3926. used in time functions.%@CR:C6A00030009 @%%@CR:C6A00030010 @%%@CR:C6A00030011 @%%@CR:C6A00030012 @%%@CR:C6A00030013 @%%@CR:C6A00030014 @%  %@NL@%
  3927. %@NL@%
  3928. They are declared in the TIME.H include files as follows:  %@NL@%
  3929. %@NL@%
  3930. %@AS@%  extern int daylight;%@AE@%%@NL@%
  3931. %@NL@%
  3932. %@AS@%  extern long timezone;%@AE@%%@NL@%
  3933. %@NL@%
  3934. %@AS@%  extern char *tzname [2];%@AE@%%@NL@%
  3935. %@NL@%
  3936. Some time and date routines use the %@AB@%daylight%@AE@%, %@AB@%timezone%@AE@%, and %@AB@%tzname%@AE@% variables
  3937. to make local-time adjustments. Whenever a program calls the %@AB@%ftime%@AE@%,
  3938. %@AB@%localtime%@AE@%, or %@AB@%tzset%@AE@% function, the value of %@AB@%daylight%@AE@%, %@AB@%timezone%@AE@%, and %@AB@%tzname%@AE@% is
  3939. determined from the value of the %@AB@%TZ%@AE@% environment variable. If you do not
  3940. explicitly set the value of %@AB@%TZ%@AE@%, the default value of PST8PDT is used. The
  3941. following list shows each variable and its value:%@CR:C6A00030015 @%%@CR:C6A00030016 @%  %@NL@%
  3942. %@NL@%
  3943. %@AB@%Variable%@AE@%                          %@AB@%Value%@AE@%
  3944. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  3945. %@AB@%daylight%@AE@%                          Nonzero if a daylight-saving-time zone 
  3946.                                   (DST) is specified in %@AB@%TZ%@AE@%; otherwise 
  3947.                                   zero. Default value is one.
  3948.  
  3949. %@AB@%timezone%@AE@%                          Difference in seconds between Greenwich 
  3950.                                   mean time and the local time. Default 
  3951.                                   value is 28,800.
  3952.  
  3953. %@AB@%tzname[0]%@AE@%                         Three-letter time zone name derived from
  3954.                                   the %@AB@%TZ%@AE@% environment variable. Default 
  3955.                                   value is "PST" (Pacific standard time).
  3956.  
  3957. %@AB@%tzname[1]%@AE@%                         Three-letter daylight-saving-time zone 
  3958.                                   name derived from the %@AB@%TZ%@AE@% environment 
  3959.                                   variable. Default value is PDT. If the 
  3960.                                   DST zone is omitted from %@AB@%TZ%@AE@%, %@AB@%tzname[1]%@AE@% 
  3961.                                   is an empty string.
  3962.  
  3963. %@NL@%
  3964. %@2@%%@CR:C6A00030017 @%%@AB@%3.3  _doserrno, errno, sys_errlist, sys_nerr%@CR:C6A00030018 @% %@CR:C6A00030019 @%%@CR:C6A00030020 @%%@CR:C6A00030021 @% %@CR:C6A00030022 @% %@CR:C6A00030023 @%%@CR:C6A00030024 @% %@CR:C6A00030025 @%%@AE@%%@EH@%%@NL@%
  3965. %@NL@%
  3966. The %@AB@%_doserrno%@AE@%, %@AB@%errno%@AE@%, %@AB@%sys_errlist%@AE@%, and %@AB@%sys_nerr%@AE@% variables contain error
  3967. codes, and are used by the %@AB@%perror%@AE@% and %@AB@%_strerror%@AE@% routines to print error
  3968. information.  %@NL@%
  3969. %@NL@%
  3970. These variables are declared in the STDLIB.H include file. Manifest
  3971. constants for the %@AB@%errno%@AE@% variables are declared in the ERRNO.H include file.
  3972. The declarations are as follows:  %@NL@%
  3973. %@NL@%
  3974. %@AS@%  extern int _doserrno;%@AE@%%@NL@%
  3975. %@NL@%
  3976. %@AS@%  extern int errno;%@AE@%%@NL@%
  3977. %@NL@%
  3978. %@AS@%  extern char *sys_errlist[ ];%@AE@%%@NL@%
  3979. %@NL@%
  3980. %@AS@%  extern int sys_nerr;%@AE@%%@NL@%
  3981. %@NL@%
  3982. The %@AB@%errno%@AE@% variable is set to an integer value to reflect the type of error
  3983. that has occurred in a system-level call. Each %@AB@%errno%@AE@% value is associated
  3984. with an error message, which can be printed with the %@AB@%perror%@AE@% routine or
  3985. stored in a string with the %@AB@%strerror%@AE@% routine.  %@NL@%
  3986. %@NL@%
  3987. Note that only some routines set the %@AB@%errno%@AE@% variable. If a routine sets
  3988. %@AB@%errno%@AE@%, the description of the routine in the reference section says so
  3989. explicitly.  %@NL@%
  3990. %@NL@%
  3991. The value of %@AB@%errno%@AE@% reflects the error value for the last call that set
  3992. %@AB@%errno%@AE@%. However, this value is not necessarily reset by later successful
  3993. calls. To avoid confusion, test for errors immediately after a call.  %@NL@%
  3994. %@NL@%
  3995. The include file ERRNO.H contains the definitions of the %@AB@%errno%@AE@% values.
  3996. However, not all of the definitions given in ERRNO.H are used in DOS and
  3997. OS/2. Some of the values in ERRNO.H are present to maintain compatibility
  3998. with XENIX and UNIX operating systems.  %@NL@%
  3999. %@NL@%
  4000. The %@AB@%errno%@AE@% values in DOS and OS/2 are a subset of the values for %@AB@%errno%@AE@% in
  4001. XENIX systems. Thus, the %@AB@%errno%@AE@% value is not necessarily the same as the
  4002. actual error code returned by a DOS or OS/2 system call. To access the
  4003. actual DOS and OS/2 error code, use the %@AB@%_doserrno%@AE@% variable, which contains
  4004. this value.%@CR:C6A00030026 @%%@CR:C6A00030027 @%  %@NL@%
  4005. %@NL@%
  4006. In general, you should use %@AB@%_doserrno%@AE@% only for error detection in operations
  4007. involving input and output, since the %@AB@%errno%@AE@% values for input and output
  4008. errors have DOS and OS/2 error-code equivalents. In other cases, the value
  4009. of %@AB@%_doserrno%@AE@% is undefined.  %@NL@%
  4010. %@NL@%
  4011. The %@AB@%syserrlist%@AE@% variable is an array; the %@AB@%perror%@AE@% and %@AB@%strerror%@AE@% routines use it
  4012. to process error information. The %@AB@%sys_nerr%@AE@% variable tells how many elements
  4013. the %@AB@%sys_errlist%@AE@% array contains.  %@NL@%
  4014. %@NL@%
  4015. Table 3.1 gives the %@AB@%errno%@AE@% values for DOS and OS/2, the system error message
  4016. for each value, and the value of each constant. Note that only the %@AB@%ERANGE%@AE@%
  4017. and %@AB@%EDOM%@AE@% constants are specified in the ANSI standard.  %@NL@%
  4018. %@NL@%
  4019. %@AB@%Table   3.1 errno Values and Their Meanings%@AE@%
  4020.  
  4021. %@TH:  32  1783 02 12 59 07 @%Constant    Meaning                                                    Value%@AB@%──────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%E2BIG%@AE@%       Argument list too long %@CR:C6A00030028 @%                                    7%@AB@%EACCES%@AE@%      Permission denied %@CR:C6A00030029 @%                                         13%@AB@%EBADF%@AE@%       Bad file number %@CR:C6A00030030 @%                                           9%@AB@%EDEADLOCK%@AE@%   Resource deadlock would occur %@CR:C6A00030031 @%                             36%@AB@%EDOM%@AE@%        Math argument %@CR:C6A00030032 @%                                             33%@AB@%EEXIST%@AE@%      File exists %@CR:C6A00030033 @%                                               17%@AB@%EINVAL%@AE@%      Invalid argument %@CR:C6A00030034 @%                                          22%@AB@%EMFILE%@AE@%      Too many open files %@CR:C6A00030035 @%                                       24%@AB@%ENOENT%@AE@%      No such file or directory %@CR:C6A00030036 @%                                 2%@AB@%ENOEXEC%@AE@%     Exec format error %@CR:C6A00030037 @%                                         8%@AB@%ENOMEM%@AE@%      Not enough memory %@CR:C6A00030038 @%                                         12%@AB@%ENOSPC%@AE@%      No space left on device %@CR:C6A00030039 @%                                   28%@AB@%ERANGE%@AE@%      Result too large %@CR:C6A00030040 @%                                          34%@AB@%EXDEV%@AE@%       Cross-device link %@CR:C6A00030041 @%                                         18%@AB@%──────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  32  1783 02 12 59 07 @%
  4022.  
  4023. %@NL@%
  4024. %@2@%%@CR:C6A00030042 @%%@AB@%3.4  _fmode%@CR:C6A00030043 @%%@CR:C6A00030044 @% %@CR:C6A00030045 @%%@CR:C6A00030046 @% %@CR:C6A00030047 @%%@CR:C6A00030048 @%%@CR:C6A00030049 @%%@AE@%%@EH@%%@NL@%
  4025. %@NL@%
  4026. The %@AB@%_fmode%@AE@% variable controls the default file-translation mode.  %@NL@%
  4027. %@NL@%
  4028. It is declared in the STDLIB.H include file as follows:  %@NL@%
  4029. %@NL@%
  4030. %@AS@%  extern int _fmode;%@AE@%%@NL@%
  4031. %@NL@%
  4032. By default, the value of %@AB@%_fmode%@AE@% is %@AB@%O_TEXT%@AE@%, causing files to be translated in
  4033. text mode (unless specifically opened or set to binary mode). When %@AB@%_fmode%@AE@% is
  4034. set to %@AB@%O_BINARY%@AE@%, the default mode is binary. You can set %@AB@%_fmode%@AE@% to the flag
  4035. %@AB@%O_BINARY%@AE@% by linking with BINMODE.OBJ or by assigning it the %@AB@%O_BINARY %@AE@%value.
  4036. %@NL@%
  4037. %@NL@%
  4038. %@NL@%
  4039. %@2@%%@CR:C6A00030050 @%%@AB@%3.5  _osmajor, _osminor, _osmode, _osversion%@CR:C6A00030051 @% %@CR:C6A00030052 @%%@CR:C6A00030053 @% %@CR:C6A00030054 @% %@CR:C6A00030055 @%%@CR:C6A00030056 @% %@CR:C6A00030057 @%%@AE@%%@EH@%%@NL@%
  4040. %@NL@%
  4041. The %@AB@%_osmajor%@AE@%, %@AB@%_osminor%@AE@%, %@AB@%_osmode%@AE@%, and %@AB@%_osversion%@AE@% variables specify the
  4042. version number of the operating system or the current mode of operation.  %@NL@%
  4043. %@NL@%
  4044. They are declared in the STDLIB.H include file as follows:  %@NL@%
  4045. %@NL@%
  4046. %@AS@%  extern unsigned char _osmajor;%@AE@%%@NL@%
  4047. %@NL@%
  4048. %@AS@%  extern unsigned char _osminor;%@AE@%%@NL@%
  4049. %@NL@%
  4050. %@AS@%  extern unsigned char _osmode;%@AE@%%@NL@%
  4051. %@NL@%
  4052. %@AS@%  extern unsigned char _osversion;%@AE@%%@NL@%
  4053. %@NL@%
  4054. The %@AB@%_osmajor%@AE@%, %@AB@%_osminor%@AE@%, and %@AB@%_osversion%@AE@% variables specify the version number
  4055. of DOS or OS/2 currently in use. The %@AB@%_osmajor%@AE@% variable holds the "major"
  4056. version number and the %@AB@%_osminor%@AE@% variable stores the "minor" version number.
  4057. Thus, under DOS version 3.20, %@AB@%_osmajor%@AE@% is 3 and %@AB@%_osminor%@AE@% is 20. The %@AB@%
  4058. %@AB@%_osversion%@AE@% variable holds both values; its low byte contains the major
  4059. version number and its high byte the minor version number.  %@NL@%
  4060. %@NL@%
  4061. These variables are useful for creating programs that run in different
  4062. versions of DOS and OS/2. For example, you can test the %@AB@%_osmajor%@AE@% variable
  4063. before making a call to %@AB@%sopen%@AE@%; if the major version number is earlier (less)
  4064. than 3, %@AB@%open%@AE@% should be used instead of %@AB@%sopen%@AE@%.  %@NL@%
  4065. %@NL@%
  4066. The %@AB@%_osmode%@AE@% variable indicates whether the program is in OS/2 protected mode
  4067. or in real mode (DOS or OS/2 real mode). An %@AB@%_osmode%@AE@% value of %@AB@%DOS_MODE%@AE@%
  4068. indicates real mode operation and a value of %@AB@%OS2_MODE%@AE@% indicates protected
  4069. operation.  %@NL@%
  4070. %@NL@%
  4071. %@NL@%
  4072. %@2@%%@CR:C6A00030058 @%%@AB@%3.6  environ%@CR:C6A00030059 @%%@CR:C6A00030060 @%%@AE@%%@EH@%%@NL@%
  4073. %@NL@%
  4074. The %@AB@%environ%@AE@% variable is a pointer to the strings in the process environment.
  4075. %@NL@%
  4076. %@NL@%
  4077. It is declared in the STDLIB.H include file as follows:  %@NL@%
  4078. %@NL@%
  4079. %@AS@%  extern char *environ [ ];%@AE@%%@NL@%
  4080. %@NL@%
  4081. The %@AB@%environ%@AE@% variable provides access to memory areas containing
  4082. process-specific information.  %@NL@%
  4083. %@NL@%
  4084. The %@AB@%environ%@AE@% variable is an array of pointers to the strings that constitute
  4085. the process environment. The environment consists of one or more entries of
  4086. the form%@CR:C6A00030061 @%  %@NL@%
  4087. %@NL@%
  4088. %@AB@%NAME%@AE@%=%@AI@%string%@AE@%  %@NL@%
  4089. %@NL@%
  4090. where %@AB@%NAME %@AE@%is the name of an environment variable and %@AI@%string %@AE@%is the value of
  4091. that variable. The string may be empty. The initial environment settings are
  4092. taken from the operating-system environment at the time of program
  4093. execution.  %@NL@%
  4094. %@NL@%
  4095. The %@AB@%getenv%@AE@% and %@AB@%putenv%@AE@% routines use the %@AB@%environ%@AE@% variable to access and modify
  4096. the environment table. When %@AB@%putenv%@AE@% is called to add or delete environment
  4097. settings, the environment table changes size; its location in memory may
  4098. also change, depending on the program's memory requirements. The %@AB@%environ%@AE@%
  4099. variable is adjusted in these cases and always points to the correct table
  4100. location.  %@NL@%
  4101. %@NL@%
  4102. %@NL@%
  4103. %@2@%%@CR:C6A00030062 @%%@AB@%3.7  _psp%@CR:C6A00030063 @%%@CR:C6A00030064 @%%@CR:C6A00030065 @%%@AE@%%@EH@%%@NL@%
  4104. %@NL@%
  4105. The %@AB@%_psp%@AE@% variable contains the segment address of the program segment prefix
  4106. (PSP) for the process.  %@NL@%
  4107. %@NL@%
  4108. It is declared in the STDLIB.H include file as follows:  %@NL@%
  4109. %@NL@%
  4110. %@AS@%  extern unsigned int _psp;%@AE@%%@NL@%
  4111. %@NL@%
  4112. The PSP contains execution information about the process, such as a copy of
  4113. the command line that invoked the process and the return address on process
  4114. termination or interrupt. The %@AB@%_psp%@AE@% variable can be used to form a long
  4115. pointer to the PSP, where %@AB@%_psp%@AE@% is the segment value and 0 is the offset
  4116. value.%@CR:C6A00030066 @%  %@NL@%
  4117. %@NL@%
  4118. Note that the %@AB@%_psp%@AE@% variable is supported only in DOS.  %@NL@%
  4119. %@NL@%
  4120. %@NL@%
  4121. %@2@%%@CR:C6A00030067 @%%@AB@%3.8  Standard Types%@AE@%%@EH@%%@NL@%
  4122. %@NL@%
  4123. A number of library routines use values whose types are defined in include
  4124. files. In the following list, these types are described, and the include
  4125. file defining each type is given.%@CR:C6A00030068 @%  %@NL@%
  4126. %@NL@%
  4127. %@AB@%Standard Type%@AE@%                     %@AB@%Description%@AE@%
  4128. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4129. %@AB@%clock_t%@AE@%                           The %@AB@%clock_t%@AE@% type, defined in TIME.H, 
  4130.                                   stores time values. It is used by the %@AB@%%@AE@%
  4131.                                   %@AB@%clock%@AE@% function. %@CR:C6A00030069 @%%@CR:C6A00030070 @%
  4132.  
  4133. %@AB@%complex%@AE@%                           The %@AB@%complex%@AE@% structure, defined in 
  4134.                                   MATH.H, stores the real and imaginary 
  4135.                                   parts of complex numbers. It is used by 
  4136.                                   the %@AB@%cabs%@AE@% function. %@CR:C6A00030071 @%%@CR:C6A00030072 @%
  4137.  
  4138. %@AB@%diskfree_t%@AE@%                        The %@AB@%diskfree_t%@AE@% structure, defined in 
  4139.                                   DOS.H, stores disk information used by 
  4140.                                   the %@AB@%_dos_getdiskfree%@AE@% routine. %@CR:C6A00030073 @%%@CR:C6A00030074 @%
  4141.  
  4142. %@AB@%diskinfo_t%@AE@%                        The %@AB@%diskinfo_t%@AE@% structure, defined in 
  4143.                                   BIOS.H, records information about disk 
  4144.                                   drives returned by the %@AB@%_bios_disk%@AE@% 
  4145.                                   routine. %@CR:C6A00030075 @%%@CR:C6A00030076 @%
  4146.  
  4147. %@AB@%div_t%@AE@%, %@AB@%ldiv_t%@AE@%                     The %@AB@%div_t%@AE@% and %@AB@%ldiv_t%@AE@% structures, defined
  4148.                                   in STDLIB.H, store the values returned 
  4149.                                   by the %@AB@%div%@AE@% and %@AB@%ldiv%@AE@% functions, 
  4150.                                   respectively. %@CR:C6A00030077 @%%@CR:C6A00030078 @%%@CR:C6A00030079 @%%@CR:C6A00030080 @%
  4151.  
  4152. %@AB@%dosdate_t%@AE@%                         The %@AB@%dosdate_t%@AE@% structure, defined in 
  4153.                                   DOS.H, records the current system date 
  4154.                                   used in the %@AB@%_dos_getdate%@AE@% and %@AB@%%@AE@%
  4155.                                   %@AB@%_dos_setdate%@AE@% routines. %@CR:C6A00030081 @%
  4156.  
  4157. %@AB@%dostime_t%@AE@%                         The %@AB@%dostime_t%@AE@% structure, defined in 
  4158.                                   DOS.H, records the current system time 
  4159.                                   used in the %@AB@%_dos_gettime%@AE@% and %@AB@%%@AE@%
  4160.                                   %@AB@%_dos_settime%@AE@% routines. %@CR:C6A00030082 @%%@CR:C6A00030083 @%
  4161.  
  4162. %@AB@%DOSERROR%@AE@%                          The %@AB@%DOSERROR%@AE@% structure, defined in 
  4163.                                   DOS.H, stores values returned by DOS 
  4164.                                   system call 59H (available under DOS 
  4165.                                   versions 3.0 and later). %@CR:C6A00030084 @%%@CR:C6A00030085 @%
  4166.  
  4167. %@AB@%exception%@AE@%                         The %@AB@%exception%@AE@% structure, defined in 
  4168.                                   MATH.H, stores error information for 
  4169.                                   math routines. It is used by the %@AB@%matherr%@AE@%
  4170.                                   routine. %@CR:C6A00030086 @%%@CR:C6A00030087 @%
  4171.  
  4172. %@AB@%FILE%@AE@%                              The %@AB@%FILE%@AE@% structure, defined in STDIO.H, 
  4173.                                   is the structure used in all stream 
  4174.                                   input and output operations. The fields 
  4175.                                   of the %@AB@%FILE%@AE@% structure store information 
  4176.                                   about the current state of the stream. %@CR:C6A00030088 @%%@CR:C6A00030089 @%
  4177.  
  4178. %@AB@%find_t%@AE@%                            The %@AB@%find_t%@AE@% structure, defined in DOS.H, 
  4179.                                   stores file-attribute information 
  4180.                                   returned by the %@AB@%_dos_findfirst%@AE@% and %@AB@%%@AE@%
  4181.                                   %@AB@%_dos_findnext%@AE@% routines. %@CR:C6A00030090 @%%@CR:C6A00030091 @%
  4182.  
  4183. %@AB@%fpos_t%@AE@%                            The %@AB@%fgetpos%@AE@% and %@AB@%fsetpos%@AE@% functions use 
  4184.                                   the %@AB@%fpos_t%@AE@% object type, defined in 
  4185.                                   STDIO.H, to record all the information 
  4186.                                   necessary to uniquely specify every 
  4187.                                   position within the file. %@CR:C6A00030092 @%%@CR:C6A00030093 @%
  4188.  
  4189. %@AB@%jmp_buf%@AE@%                           The %@AB@%jmp_buf%@AE@% type, defined in SETJMP.H, 
  4190.                                   is an array type rather than a structure
  4191.                                   type. A buffer of this type is used by 
  4192.                                   the %@AB@%setjmp%@AE@% and %@AB@%longjmp%@AE@% routines to save 
  4193.                                   and restore the program 
  4194.                                   environment. %@CR:C6A00030094 @%%@CR:C6A00030095 @%
  4195.  
  4196. %@AB@%lconv%@AE@%                             The %@AB@%lconv%@AE@% type is a structure containing
  4197.                                   formatting rules for numeric values in 
  4198.                                   different countries. It is defined in 
  4199.                                   LOCALE.H.
  4200.  
  4201. %@AB@%onexit_t%@AE@%                          The %@AB@%onexit%@AE@% routine is declared as an %@AB@%%@AE@%
  4202.                                   %@AB@%onexit_t%@AE@% pointer type, which is defined 
  4203.                                   in STDLIB.H.
  4204.  
  4205. %@AB@%ptrdiff_t%@AE@%                         The %@AB@%ptrdiff_t%@AE@% type is used for the 
  4206.                                   signed integral result of the 
  4207.                                   subtraction of two pointers.
  4208.  
  4209. %@AB@%REGS%@AE@%                              The %@AB@%REGS %@AE@%union, defined in DOS.H, stores
  4210.                                   byte and word register values to be 
  4211.                                   passed to and returned from calls to the
  4212.                                   DOS interface functions. %@CR:C6A00030096 @%%@CR:C6A00030097 @%
  4213.  
  4214. %@AB@%sig_atomic_t%@AE@%                      The %@AB@%sig_atomic_t%@AE@% type, defined in 
  4215.                                   SIGNAL.H, is the integral type of an 
  4216.                                   object that can be modified as an atomic
  4217.                                   entity, even in the presence of 
  4218.                                   asynchronous interrupts. It is used in 
  4219.                                   conjunction with the %@AB@%signal%@AE@% routine.
  4220.  
  4221. %@AB@%size_t%@AE@%                            The %@AB@%size_t%@AE@% type, defined in STDDEF.H and
  4222.                                   several other include files, is the 
  4223.                                   unsigned integral result of the %@AB@%sizeof%@AE@% 
  4224.                                   operator. %@CR:C6A00030098 @%%@CR:C6A00030099 @%
  4225.  
  4226. %@AB@%SREGS%@AE@%                             The %@AB@%SREGS%@AE@% structure, defined in DOS.H, 
  4227.                                   stores the values of the ES, CS, SS, and
  4228.                                   DS registers. This structure is used by 
  4229.                                   the DOS interface functions that require
  4230.                                   segment register values (%@AB@%int86x%@AE@%, %@AB@%intdosx%@AE@%
  4231.                                   , and %@AB@%segread%@AE@%). %@CR:C6A00030100 @%%@CR:C6A00030101 @%
  4232.  
  4233. %@AB@%stat%@AE@%                              The %@AB@%stat%@AE@% structure, defined in 
  4234.                                   SYS\STAT.H, contains file-status 
  4235.                                   information returned by the %@AB@%stat%@AE@% and %@AB@%%@AE@%
  4236.                                   %@AB@%fstat%@AE@% routines. %@CR:C6A00030102 @%
  4237.  
  4238. %@AB@%time_t%@AE@%                            The %@AB@%time_t%@AE@% type, defined in TIME.H, 
  4239.                                   represents time values in the %@AB@%mktime%@AE@% and
  4240.                                   %@AB@%time%@AE@% routines. %@CR:C6A00030103 @%%@CR:C6A00030104 @%
  4241.  
  4242. %@AB@%timeb%@AE@%                             The %@AB@%timeb%@AE@% structure, defined in 
  4243.                                   SYS\TIMEB.H, is used by the %@AB@%ftime%@AE@% 
  4244.                                   routine to store the current system 
  4245.                                   time. %@CR:C6A00030105 @%%@CR:C6A00030106 @%
  4246.  
  4247. %@AB@%tm%@AE@%                                The %@AB@%tm%@AE@% structure, defined in TIME.H, is 
  4248.                                   used by the %@AB@%asctime%@AE@%, %@AB@%gmtime%@AE@%, and %@AB@%%@AE@%
  4249.                                   %@AB@%localtime%@AE@% functions to store and 
  4250.                                   retrieve time information. %@CR:C6A00030107 @%%@CR:C6A00030108 @%
  4251.  
  4252. %@AB@%utimbuf%@AE@%                           The %@AB@%utimbuf%@AE@% structure, defined in 
  4253.                                   SYS\UTIME.H, stores file access and 
  4254.                                   modification times used by the %@AB@%utime%@AE@% 
  4255.                                   function to change file-modification 
  4256.                                   dates. %@CR:C6A00030109 @%%@CR:C6A00030110 @%
  4257.  
  4258. %@AB@%va_list%@AE@%                           The %@AB@%va_list%@AE@% array type, defined in 
  4259.                                   STDARG.H, is used to hold information 
  4260.                                   needed by the %@AB@%va_arg%@AE@% macro and the %@AB@%%@AE@%
  4261.                                   %@AB@%va_end%@AE@% routine. The called function 
  4262.                                   declares a variable of type %@AB@%va_list%@AE@%, 
  4263.                                   which may be passed as an argument to 
  4264.                                   another function. %@CR:C6A00030111 @%%@CR:C6A00030112 @% 
  4265.  
  4266. %@NL@%
  4267. %@NL@%
  4268. %@NL@%
  4269. %@NL@%
  4270. %@NL@%
  4271. %@CR:C6A-Part 02 @%%@1@%%@AB@%PART II  Run-Time Functions%@AE@%%@EH@%%@NL@%
  4272. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4273. %@NL@%
  4274. The second part of this book is the reference section. It describes, in
  4275. alphabetical order, each function of the run-time library provided with the
  4276. Microsoft C Professional Development System.  %@NL@%
  4277. %@NL@%
  4278. Each reference entry gives syntax, return values, and other useful
  4279. information about the library functions. Information on compatibility is
  4280. supplied to assist you in writing portable programs.  %@NL@%
  4281. %@NL@%
  4282. %@NL@%
  4283. %@2@%%@CR:C6A00030113 @%%@AB@%About the Run-Time Reference%@AE@%%@EH@%%@NL@%
  4284. %@NL@%
  4285. The following pages describe, in alphabetical order, the more than 400
  4286. functions in the Microsoft run-time library. In some cases, related routines
  4287. are clustered in the same description. For example, the based, near, and far
  4288. versions of %@AB@%_heapwalk %@AE@%are in the same discussion, as are the regular and
  4289. long double versions of the math functions, such as %@AB@%acos%@AE@% and %@AB@%atan%@AE@%.
  4290. Differences are noted where appropriate. Refer to Chapter 2, "Run-Time
  4291. Routines by Category," or to the index to locate any function that does not
  4292. appear in the expected position within the alphabetical reference.  %@NL@%
  4293. %@NL@%
  4294. The discussion of each function (or group of functions) is divided into the
  4295. following sections:  %@NL@%
  4296. %@NL@%
  4297. %@NL@%
  4298.   ■   %@AB@%%@AE@%%@AI@%Description%@AE@%. Summarizes the routine's effect, names the include
  4299.       file(s) containing its declaration, illustrates the syntax, and
  4300.       briefly describes the arguments.%@NL@%
  4301. %@NL@%
  4302.   ■   %@AB@%%@AE@%%@AI@%Remarks%@AE@%. Gives a more detailed description of the routine and how it
  4303.       is used.%@NL@%
  4304. %@NL@%
  4305.   ■   %@AB@%%@AE@%%@AI@%Return Value%@AE@%. Describes the value returned by the routine.%@NL@%
  4306. %@NL@%
  4307.   ■   %@AB@%%@AE@%%@AI@%Compatibility.%@AE@% Tells whether the routine is compatible with ANSI C,
  4308.       MS-DOS, OS/2, UNIX, and XENIX.%@NL@%
  4309. %@NL@%
  4310.   ■   %@AB@%%@AE@%%@AI@%See Also%@AE@%. Names related routines.%@NL@%
  4311. %@NL@%
  4312.   ■   %@AB@%%@AE@%%@AI@%Example%@AE@%. Gives a complete program showing the use of the routine. %@NL@%
  4313. %@NL@%
  4314. %@NL@%
  4315. %@NL@%
  4316. %@NL@%
  4317. %@NL@%
  4318. %@QR:abort@%%@NL@%
  4319. %@2@%%@CR:C6A00050114 @%%@AB@%abort%@AE@%%@EH@%%@NL@%
  4320. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4321. %@NL@%
  4322. %@NL@%
  4323. %@3@%%@AB@%Description%@CR:C6A00050115 @%%@CR:C6A00050116 @%%@AE@%%@EH@%%@NL@%
  4324. %@NL@%
  4325. Aborts the current process and returns an error code.  %@NL@%
  4326. %@NL@%
  4327. %@AB@%#include <process.h>%@AE@%              Required only for function declarations;
  4328. %@AB@%#include <stdlib.h>%@AE@%               use either PROCESS.H or STDLIB.H
  4329.  
  4330. %@AS@%  void abort( void );%@AE@%%@NL@%
  4331. %@NL@%
  4332. %@NL@%
  4333. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4334. %@NL@%
  4335. The %@AB@%abort%@AE@% function prints the message  %@NL@%
  4336. %@NL@%
  4337. %@AS@%  abnormal program termination%@AE@%%@NL@%
  4338. %@NL@%
  4339. to %@AB@%stderr%@AE@%, then calls %@AB@%raise(SIGABRT)%@AE@%. The action taken in response to the
  4340. %@AB@%SIGABRT%@AE@% signal depends on what action has been defined for that signal in a
  4341. prior call to the %@AB@%signal%@AE@% function. The default %@AB@%SIGABRT%@AE@% action is for the
  4342. calling process to terminate with exit code 3, returning control to the
  4343. parent process or operating system.  %@NL@%
  4344. %@NL@%
  4345. The %@AB@%abort%@AE@% function does not flush stream buffers or do %@AB@%atexit%@AE@%/%@AB@%onexit%@AE@%
  4346. processing.  %@NL@%
  4347. %@NL@%
  4348. %@NL@%
  4349. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4350. %@NL@%
  4351. The %@AB@%abort%@AE@% function does not return control to the caller. Rather, it
  4352. terminates the process and, by default, returns an exit code of 3 to the
  4353. parent process.  %@NL@%
  4354. %@NL@%
  4355. %@NL@%
  4356. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4357. %@NL@%
  4358. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  4359. %@NL@%
  4360. %@NL@%
  4361. In multithread libraries, the %@AB@%abort %@AE@%function does not call %@AB@%raise%@AE@%(%@AB@%SIGABRT)%@AE@%.
  4362. Instead, it simply terminates the process with exit code 3.  %@NL@%
  4363. %@NL@%
  4364. %@NL@%
  4365. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4366. %@NL@%
  4367. %@AB@%exec%@AE@% functions, %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, %@AB@%raise%@AE@%, %@AB@%signal%@AE@%, %@AB@%spawn%@AE@% functions  %@NL@%
  4368. %@NL@%
  4369. %@NL@%
  4370. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4371. %@NL@%
  4372. %@AS@%  /* ABORT.C:  This tries to open a file and aborts if the attempt fails. */
  4373. %@AS@%  
  4374. %@AS@%  #include <stdio.h>
  4375. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  4376. %@NL@%
  4377. %@AS@%  void main()
  4378. %@AS@%  {
  4379. %@AS@%  
  4380. %@AS@%     FILE *stream;
  4381. %@AS@%  
  4382. %@AS@%     if( (stream = fopen( "NOSUCHF.ILE", "r" )) == NULL )
  4383. %@AS@%     {
  4384. %@AS@%        perror( "Couldn't open file" );
  4385. %@AS@%        abort();
  4386. %@AS@%     }
  4387. %@AS@%     else
  4388. %@AS@%        fclose( stream );
  4389. %@AS@%  }%@AE@%%@NL@%
  4390. %@NL@%
  4391. %@NL@%
  4392. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  4393. %@NL@%
  4394. %@AS@%  
  4395. %@AS@%  
  4396. %@AS@%  Couldn't open file: No such file or directory
  4397. %@AS@%  
  4398. %@AS@%  abnormal program termination
  4399. %@AS@%  %@AE@%%@NL@%
  4400. %@NL@%
  4401. %@NL@%
  4402. %@NL@%
  4403. %@NL@%
  4404. %@QR:abs@%%@NL@%
  4405. %@2@%%@CR:C6A00060117 @%%@AB@%abs%@AE@%%@EH@%%@NL@%
  4406. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4407. %@NL@%
  4408. %@NL@%
  4409. %@3@%%@AB@%Description%@CR:C6A00060118 @%%@CR:C6A00060119 @%%@AE@%%@EH@%%@NL@%
  4410. %@NL@%
  4411. Calculates the absolute value.  %@NL@%
  4412. %@NL@%
  4413. %@AB@%#include <stdlib.h>%@AE@%%@AB@%%@AE@%               Required only for function declarations;
  4414. %@AB@%#include <math.h>%@AE@%                 use either STDLIB.H or MATH.H
  4415.  
  4416. %@AS@%  int abs( int n );%@AE@%%@NL@%
  4417. %@NL@%
  4418. %@AI@%n%@AE@%                                 Integer value
  4419.  
  4420. %@NL@%
  4421. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4422. %@NL@%
  4423. The %@AB@%abs%@AE@% function returns the absolute value of its integer argument %@AI@%n%@AE@%.  %@NL@%
  4424. %@NL@%
  4425. %@NL@%
  4426. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4427. %@NL@%
  4428. The %@AB@%abs%@AE@% function returns the absolute value of its argument. There is no
  4429. error return.  %@NL@%
  4430. %@NL@%
  4431. %@NL@%
  4432. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4433. %@NL@%
  4434. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  4435. %@NL@%
  4436. %@NL@%
  4437. %@NL@%
  4438. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4439. %@NL@%
  4440. %@AB@%cabs%@AE@%, %@AB@%fabs%@AE@%, %@AB@%labs%@AE@%  %@NL@%
  4441. %@NL@%
  4442. %@NL@%
  4443. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4444. %@NL@%
  4445. %@AS@%  /* ABS.C: This program computes and displays the absolute values of
  4446. %@AS@%   * several numbers.
  4447. %@AS@%   */
  4448. %@AS@%  
  4449. %@AS@%  #include <stdio.h>
  4450. %@AS@%  #include <math.h>
  4451. %@AS@%  #include <stdlib.h>
  4452. %@AS@%  
  4453. %@AS@%  void main()
  4454. %@AS@%  {
  4455. %@AS@%     int    ix = -4, iy;
  4456. %@AS@%     long   lx = -41567L, ly;
  4457. %@AS@%     double dx = -3.141593, dy;
  4458. %@AS@%  
  4459. %@AS@%     iy = abs( ix );
  4460. %@AS@%     printf( "The absolute value of %d is %d\n", ix, iy);
  4461. %@AS@%  
  4462. %@AS@%     ly = labs( lx );
  4463. %@AS@%     printf( "The absolute value of %ld is %ld\n", lx, ly);
  4464. %@AS@%  
  4465. %@AS@%     dy = fabs( dx );
  4466. %@AS@%     printf( "The absolute value of %f is %f\n", dx, dy );
  4467. %@AS@%  }%@AE@%%@NL@%
  4468. %@NL@%
  4469. %@NL@%
  4470. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  4471. %@NL@%
  4472. %@AS@%  
  4473. %@AS@%  
  4474. %@AS@%  The absolute value of -4 is 4
  4475. %@AS@%  The absolute value of -41567 is 41567
  4476. %@AS@%  The absolute value of -3.141593 is 3.141593 %@AE@%%@NL@%
  4477. %@NL@%
  4478. %@NL@%
  4479. %@NL@%
  4480. %@NL@%
  4481. %@QR:access@%%@NL@%
  4482. %@2@%%@CR:C6A00070120 @%%@AB@%access%@AE@%%@EH@%%@NL@%
  4483. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4484. %@NL@%
  4485. %@NL@%
  4486. %@3@%%@AB@%Description%@CR:C6A00070121 @%%@CR:C6A00070122 @%%@AE@%%@EH@%%@NL@%
  4487. %@NL@%
  4488. Determines file-access permission.  %@NL@%
  4489. %@NL@%
  4490. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  4491.  
  4492. %@AB@%#include <errno.h>%@AE@%                Required for definition of %@AB@%errno%@AE@% 
  4493.                                   constants
  4494.  
  4495. %@AS@%  int access( char *pathname, int mode );%@AE@%%@NL@%
  4496. %@NL@%
  4497. %@AI@%pathname%@AE@%                          File or directory path name
  4498.  
  4499. %@AI@%mode%@AE@%                              Permission setting
  4500.  
  4501. %@NL@%
  4502. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4503. %@NL@%
  4504. With files, the %@AB@%access%@AE@% function determines whether the specified file exists
  4505. and can be accessed in %@AI@%mode%@AE@%. The possible mode values and their meanings in
  4506. the %@AB@%access%@AE@% call are as follows: %@CR:C6A00070123 @%  %@NL@%
  4507. %@NL@%
  4508. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  4509. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4510. 00                                Check for existence only
  4511.  
  4512. 02                                Check for write permission
  4513.  
  4514. 04                                Check for read permission
  4515.  
  4516. 06                                Check for read and write permission
  4517.  
  4518. With directories, %@AB@%access%@AE@% determines only whether the specified directory
  4519. exists; under DOS and OS/2, all directories have read and write access.  %@NL@%
  4520. %@NL@%
  4521. %@NL@%
  4522. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4523. %@NL@%
  4524. The %@AB@%access%@AE@% function returns the value 0 if the file has the given mode. A
  4525. return value of -1 indicates that the named file does not exist or is not
  4526. accessible in the given mode, and %@AB@%errno%@AE@% is set to one of the following
  4527. values:  %@NL@%
  4528. %@NL@%
  4529. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  4530. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4531. %@AB@%EACCES%@AE@%                            Access denied: the file's permission 
  4532.                                   setting does not allow the specified 
  4533.                                   access.
  4534.  
  4535. %@AB@%ENOENT%@AE@%                            File or path name not found.
  4536.  
  4537. %@NL@%
  4538. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4539. %@NL@%
  4540.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  4541. %@NL@%
  4542. %@NL@%
  4543. %@NL@%
  4544. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4545. %@NL@%
  4546. %@AB@%chmod%@AE@%, %@AB@%fstat%@AE@%, %@AB@%open%@AE@%, %@AB@%stat%@AE@%  %@NL@%
  4547. %@NL@%
  4548. %@NL@%
  4549. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4550. %@NL@%
  4551. %@AS@%  /* ACCESS.C: This example uses access to check the file named "data"
  4552. %@AS@%   * to see if it exists and if writing is allowed.
  4553. %@AS@%   */
  4554. %@AS@%  
  4555. %@AS@%  #include <io.h>
  4556. %@AS@%  #include <stdio.h>
  4557. %@AS@%  #include <stdlib.h>
  4558. %@AS@%  
  4559. %@AS@%  void main()
  4560. %@AS@%  {
  4561. %@AS@%     /* Check for existence */
  4562. %@AS@%     if( (access( "access.c", 0 )) != -1 )
  4563. %@AS@%     {
  4564. %@AS@%        printf( "File exists\n" );
  4565. %@AS@%  
  4566. %@AS@%        /* Check for write permission */
  4567. %@AS@%        if( (access( "access.c", 2 )) != -1 )
  4568. %@AS@%           printf( "File has write permission\n" );
  4569. %@AS@%     }
  4570. %@AS@%  }%@AE@%%@NL@%
  4571. %@NL@%
  4572. %@NL@%
  4573. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  4574. %@NL@%
  4575. %@AS@%  
  4576. %@AS@%  
  4577. %@AS@%  File exists
  4578. %@AS@%  File has write permission%@AE@%%@NL@%
  4579. %@NL@%
  4580. %@NL@%
  4581. %@NL@%
  4582. %@NL@%
  4583. %@QR:acos@%%@NL@%
  4584. %@2@%%@CR:C6A00080124 @%%@AB@%acos Functions%@AE@%%@EH@%%@NL@%
  4585. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4586. %@NL@%
  4587. %@NL@%
  4588. %@3@%%@AB@%Description%@CR:C6A00080125 @%%@CR:C6A00080126 @% %@CR:C6A00080127 @%%@CR:C6A00080128 @%%@CR:C6A00080129 @%%@CR:C6A00080130 @%%@AE@%%@EH@%%@NL@%
  4589. %@NL@%
  4590. Calculate the arccosine.  %@NL@%
  4591. %@NL@%
  4592. %@AB@%#include <math.h>%@AE@%  %@NL@%
  4593. %@NL@%
  4594. %@AB@%#include <errno.h>%@AE@%                Required for definition of %@AB@%errno%@AE@% 
  4595.                                   constant
  4596.  
  4597. %@AS@%  double acos( double x );%@AE@%%@NL@%
  4598. %@NL@%
  4599. %@AS@%  long double acosl( long double x );%@AE@%%@NL@%
  4600. %@NL@%
  4601. %@AI@%x%@AE@%                                 Value whose arccosine is to be 
  4602.                                   calculated
  4603.  
  4604. %@NL@%
  4605. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4606. %@NL@%
  4607. The %@AB@%acos%@AE@% functions return the arccosine of %@AI@%x%@AE@% in the range 0 to π radians.
  4608. The value of %@AI@%x%@AE@% must be between -1 and 1. The %@AB@%acosl%@AE@% function is the 80-bit
  4609. counterpart, which uses an 80-bit, 10-byte coprocessor form of arguments and
  4610. return values. See the reference page on the long double functions for more
  4611. details on this data type.  %@NL@%
  4612. %@NL@%
  4613. %@NL@%
  4614. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4615. %@NL@%
  4616. The %@AB@%acos%@AE@% functions return the arccosine result. If %@AI@%x%@AE@% is less than -1 or
  4617. greater than 1, the function sets %@AB@%errno%@AE@% to %@AB@%EDOM%@AE@%, prints a %@AB@%DOMAIN %@AE@%error
  4618. message to %@AB@%stderr%@AE@%, and returns 0. Error handling can be modified with the
  4619. %@AB@%matherr%@AE@% (or %@AB@%_matherrl%@AE@%) routine.  %@NL@%
  4620. %@NL@%
  4621. %@NL@%
  4622. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4623. %@NL@%
  4624. %@AB@%acos%@AE@%  %@NL@%
  4625. %@NL@%
  4626. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  4627. %@NL@%
  4628. %@NL@%
  4629. %@AB@%acosl%@AE@%  %@NL@%
  4630. %@NL@%
  4631.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  4632. %@NL@%
  4633. %@NL@%
  4634. %@NL@%
  4635. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4636. %@NL@%
  4637. %@AB@%asin%@AE@% functions, %@AB@%atan%@AE@% functions, %@AB@%cos%@AE@% functions, %@AB@%matherr%@AE@%, %@AB@%sin%@AE@% functions, %@AB@%tan%@AE@%
  4638. functions  %@NL@%
  4639. %@NL@%
  4640. %@NL@%
  4641. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4642. %@NL@%
  4643. %@AS@%  /* ASINCOS.C: This program prompts for a value in the range -1 to 1.
  4644. %@AS@%   * Input values outside this range will produce DOMAIN error messages.
  4645. %@AS@%   * If a valid value is entered, the program prints the arcsine and the
  4646. %@AS@%   * arccosine of that value.
  4647. %@AS@%   */
  4648. %@AS@%  
  4649. %@AS@%  #include <math.h>
  4650. %@AS@%  #include <stdio.h>
  4651. %@AS@%  #include <stdlib.h>
  4652. %@AS@%  #include <errno.h>
  4653. %@AS@%  
  4654. %@AS@%  void main()
  4655. %@AS@%  {
  4656. %@AS@%     double x, y;
  4657. %@AS@%  
  4658. %@AS@%     printf( "Enter a real number between -1 and 1: " );
  4659. %@AS@%     scanf( "%lf", &x );
  4660. %@AS@%     y = asin( x );
  4661. %@AS@%     printf( "Arcsine of %f = %f\n", x, y );
  4662. %@AS@%     y = acos( x );
  4663. %@AS@%     printf( "Arccosine of %f = %f\n", x, y );
  4664. %@AS@%  }%@AE@%%@NL@%
  4665. %@NL@%
  4666. %@NL@%
  4667. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  4668. %@NL@%
  4669. %@AS@%  
  4670. %@AS@%  
  4671. %@AS@%  Enter a real number between -1 and 1: .32696
  4672. %@AS@%  Arcsine of 0.326960 = 0.333085
  4673. %@AS@%  Arccosine of 0.326960 = 1.237711%@AE@%%@NL@%
  4674. %@NL@%
  4675. %@NL@%
  4676. %@NL@%
  4677. %@NL@%
  4678. %@QR:alloca@%%@NL@%
  4679. %@2@%%@CR:C6A00090131 @%%@AB@%alloca%@AE@%%@EH@%%@NL@%
  4680. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4681. %@NL@%
  4682. %@NL@%
  4683. %@3@%%@AB@%Description%@CR:C6A00090132 @%%@AE@%%@EH@%%@NL@%
  4684. %@NL@%
  4685. Allocates memory on the stack.  %@NL@%
  4686. %@NL@%
  4687. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  4688.  
  4689. %@AS@%  void *alloca( size_t size );%@AE@%%@NL@%
  4690. %@NL@%
  4691. %@AI@%size%@AE@%                              Bytes to be allocated from stack
  4692.  
  4693. %@NL@%
  4694. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4695. %@NL@%
  4696. The %@AB@%alloca%@AE@% routine allocates %@AI@%size%@AE@% bytes from the program's stack. The
  4697. allocated space is automatically freed when the calling function is exited.
  4698. %@NL@%
  4699. %@NL@%
  4700. When you compile with optimization on (either by default or by using one of
  4701. the /O options), the stack pointer may not be restored properly in functions
  4702. that have no local variables and that also reference the %@AB@%alloca%@AE@% function.
  4703. The following program demonstrates the problem:  %@NL@%
  4704. %@NL@%
  4705. %@AS@%  /* Compile with CL /Lp /AM /Ox /Fc */
  4706. %@AS@%  #include <malloc.h>
  4707. %@AS@%  
  4708. %@AS@%  void main( void )
  4709. %@AS@%  {
  4710. %@AS@%     func( 10 );
  4711. %@AS@%  }
  4712. %@AS@%  void func( register int i )
  4713. %@AS@%  {
  4714. %@AS@%     alloca( i );
  4715. %@AS@%  }%@AE@%%@NL@%
  4716. %@NL@%
  4717. To ensure that the stack pointer is properly restored, make sure that any
  4718. function referencing %@AB@%alloca%@AE@% declares at least one local variable.  %@NL@%
  4719. %@NL@%
  4720. The pointer value returned by %@AB@%alloca%@AE@% should never be passed as an argument
  4721. to %@AB@%free%@AE@%, nor should %@AB@%alloca%@AE@% be used in an expression that is an argument to a
  4722. function.  %@NL@%
  4723. %@NL@%
  4724. %@NL@%
  4725. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4726. %@NL@%
  4727. The %@AB@%alloca%@AE@% routine returns a %@AB@%void%@AE@% pointer to the allocated space, which is
  4728. guaranteed to be suitably aligned for storage of any type of object. To get
  4729. a pointer to a type other than %@AB@%char%@AE@%, use a type cast on the return value.
  4730. The return value is %@AB@%NULL%@AE@% if the space cannot be allocated.  %@NL@%
  4731. %@NL@%
  4732. %@NL@%
  4733. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4734. %@NL@%
  4735.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX   XENIX%@NL@%
  4736. %@NL@%
  4737. %@NL@%
  4738. %@NL@%
  4739. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4740. %@NL@%
  4741. %@AB@%calloc%@AE@% functions, %@AB@%malloc%@AE@% functions, %@AB@%realloc%@AE@% functions  %@NL@%
  4742. %@NL@%
  4743. %@NL@%
  4744. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4745. %@NL@%
  4746. %@AS@%  /* ALLOCA.C: This program checks the stack space available before
  4747. %@AS@%   * and after using the alloca function to allocate space on the stack.
  4748. %@AS@%   */
  4749. %@AS@%  
  4750. %@AS@%  #include <malloc.h>
  4751. %@AS@%  #include <stdio.h>
  4752. %@AS@%  
  4753. %@AS@%  void main()
  4754. %@AS@%  {
  4755. %@AS@%     char *buffer;
  4756. %@AS@%  
  4757. %@AS@%     printf( "Bytes available on stack: %u\n", stackavail() );
  4758. %@AS@%  
  4759. %@AS@%     /* Allocate memory for string. */
  4760. %@AS@%     buffer = alloca( 120 * sizeof( char ) );
  4761. %@AS@%     printf( "Enter a string: " );
  4762. %@AS@%     gets( buffer );
  4763. %@AS@%     printf( "You entered: %s\n", buffer );
  4764. %@AS@%  
  4765. %@AS@%     printf( "Bytes available on stack: %u\n", stackavail() );
  4766. %@AS@%  }%@AE@%%@NL@%
  4767. %@NL@%
  4768. %@NL@%
  4769. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  4770. %@NL@%
  4771. %@AS@%  
  4772. %@AS@%  
  4773. %@AS@%  Bytes available on stack: 2028
  4774. %@AS@%  Enter a string: How much stack space will this string take?
  4775. %@AS@%  You entered: How much stack space will this string take?
  4776. %@AS@%  Bytes available on stack: 1902%@AE@%%@NL@%
  4777. %@NL@%
  4778. %@NL@%
  4779. %@NL@%
  4780. %@NL@%
  4781. %@QR:_arc@%%@NL@%
  4782. %@2@%%@CR:C6A00100133 @%%@AB@%_arc Functions%@AE@%%@EH@%%@NL@%
  4783. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4784. %@NL@%
  4785. %@NL@%
  4786. %@3@%%@AB@%Description%@CR:C6A00100134 @%%@CR:C6A00100135 @%%@AE@%%@EH@%%@NL@%
  4787. %@NL@%
  4788. Draw elliptical arcs.  %@NL@%
  4789. %@NL@%
  4790. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  4791. %@NL@%
  4792. %@AS@%  short _far _arc( short x1, short y1, short x2, short y2, short x3, 
  4793. %@AS@%    short y3, short x4, short y4 );%@AE@%%@NL@%
  4794. %@NL@%
  4795. %@AS@%  short _far _arc_w( double x1, double y1, double x2, double y2, double x3, 
  4796. %@AS@%    double y3, double x4, double y4 );%@AE@%%@NL@%
  4797. %@NL@%
  4798. %@AS@%  short _far _arc_wxy( struct _wxycoord _far *pwxy1, 
  4799. %@AS@%    struct _wxycoord _far *pwxy2, 
  4800. %@AS@%    struct _wxycoord _far *pwxy3, struct _wxycoord _far *pwxy4);%@AE@%%@NL@%
  4801. %@NL@%
  4802. %@AI@%x1%@AE@%, %@AI@%y1%@AE@%                            Upper-left corner of bounding rectangle
  4803.  
  4804. %@AI@%x2%@AE@%, %@AI@%y2%@AE@%                            Lower-right corner of bounding rectangle
  4805.  
  4806. %@AI@%x3%@AE@%, %@AI@%y3%@AE@%                            Second point of start vector (center of 
  4807.                                   bounding rectangle is first point)
  4808.  
  4809. %@AI@%x4%@AE@%, %@AI@%y4%@AE@%                            Second point of end vector (center of 
  4810.                                   bounding rectangle is first point)
  4811.  
  4812. %@AI@%pwxy1%@AE@%                             Upper-left corner of bounding rectangle
  4813.  
  4814. %@AI@%pwxy2%@AE@%                             Lower-right corner of bounding rectangle
  4815.  
  4816. %@AI@%pwxy3%@AE@%                             Second point of start vector (center of 
  4817.                                   bounding rectangle is first point)
  4818.  
  4819. %@AI@%pwxy4%@AE@%                             Second point of end vector (center of 
  4820.                                   bounding rectangle is first point)
  4821.  
  4822. %@NL@%
  4823. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4824. %@NL@%
  4825. The %@AB@%_arc%@AE@% functions draw elliptical arcs. The center of the arc is the center
  4826. of the bounding rectangle, which is defined by points (%@AI@%x1%@AE@%, %@AI@%y1%@AE@%) and (%@AI@%x2%@AE@%,%@AI@% y2%@AE@%)
  4827. for%@AB@% _arc%@AE@% and %@AB@%_arc_w%@AE@% and by points%@AB@% %@AE@%%@AI@%pwxy1%@AE@% and %@AI@%pwxy2%@AE@% for%@AB@% _arc_wxy%@AE@%. The arc
  4828. starts where it intersects an imaginary line extending from the center of
  4829. the arc through (%@AI@%x3%@AE@%,%@AI@% y3%@AE@%) for %@AB@%_arc%@AE@% and%@AB@% _arc_w%@AE@% and through %@AI@%pwxy3%@AE@% for %@AB@%_arc_wxy%@AE@%.
  4830. It is drawn counterclockwise about the center of the arc, ending where it
  4831. intersects an imaginary line extending from the center of the arc through
  4832. (%@AI@%x4%@AE@%,%@AI@% y4%@AE@%) for %@AB@%_arc %@AE@% and %@AB@%_arc_w%@AE@% and through %@AI@%pwxy4%@AE@% for %@AB@%_arc_wxy%@AE@%.  %@NL@%
  4833. %@NL@%
  4834. The %@AB@%_arc%@AE@% routine uses the view coordinate system. The %@AB@%_arc_w%@AE@% and %@AB@%_arc_wxy%@AE@%
  4835. functions use the real-valued window coordinate system.  %@NL@%
  4836. %@NL@%
  4837. In each case, the arc is drawn using the current color. Since an arc does
  4838. not define a closed area, it is not filled.  %@NL@%
  4839. %@NL@%
  4840. %@NL@%
  4841. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4842. %@NL@%
  4843. These functions return a nonzero value if the arc is successfully drawn;
  4844. otherwise, they return 0.  %@NL@%
  4845. %@NL@%
  4846. %@NL@%
  4847. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4848. %@NL@%
  4849.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  4850. %@NL@%
  4851. %@NL@%
  4852. %@NL@%
  4853. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4854. %@NL@%
  4855. %@AB@%_ellipse%@AE@% functions, %@AB@% _lineto%@AE@% functions, %@AB@% _pie%@AE@% functions, %@AB@% _rectangle%@AE@%
  4856. functions,  %@AB@%_setcolor%@AE@%  %@NL@%
  4857. %@NL@%
  4858. %@NL@%
  4859. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4860. %@NL@%
  4861. %@AS@%  /* ARC.C: This program draws a simple arc. */
  4862. %@AS@%  
  4863. %@AS@%  #include <graph.h>
  4864. %@AS@%  #include <stdlib.h>
  4865. %@AS@%  #include <conio.h>
  4866. %@AS@%  
  4867. %@AS@%  void main()
  4868. %@AS@%  {
  4869. %@AS@%     short x, y;
  4870. %@AS@%     struct xycoord xystart, xyend, xyfill;
  4871. %@AS@%  
  4872. %@AS@%     /* Find a valid graphics mode */
  4873. %@AS@%     if( !_setvideomode( _MAXRESMODE ) )
  4874. %@AS@%        exit( 1 );
  4875. %@AS@%  
  4876. %@AS@%     /* Draw arcs         */
  4877. %@AS@%     x = 100; y = 100;
  4878. %@AS@%     _arc( x - 60, y - 60, x, y, x - 30, y - 60, x - 60, y - 30 );
  4879. %@AS@%     _arc( x + 60, y + 60, x, y, x,      y + 30, x + 30, y );
  4880. %@AS@%  
  4881. %@AS@%     /* Get endpoints of second arc and enclose the figure, then fill it. */
  4882. %@AS@%     _getarcinfo( &xystart, &xyend, &xyfill );
  4883. %@AS@%     _moveto( xystart.xcoord, xystart.ycoord );
  4884. %@AS@%     _lineto( xyend.xcoord,   xyend.ycoord );
  4885. %@AS@%     _floodfill( xyfill.xcoord, xyfill.ycoord, _getcolor() );
  4886. %@AS@%  
  4887. %@AS@%     getch();
  4888. %@AS@%     _setvideomode( _DEFAULTMODE );
  4889. %@AS@%  }%@AE@%%@NL@%
  4890. %@NL@%
  4891. %@NL@%
  4892. %@NL@%
  4893. %@NL@%
  4894. %@QR:asctime@%%@NL@%
  4895. %@2@%%@CR:C6A00110136 @%%@AB@%asctime%@AE@%%@EH@%%@NL@%
  4896. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4897. %@NL@%
  4898. %@NL@%
  4899. %@3@%%@AB@%Description%@CR:C6A00110137 @%%@CR:C6A00110138 @%%@AE@%%@EH@%%@NL@%
  4900. %@NL@%
  4901. Converts a %@AB@%tm%@AE@% time structure to a character string.  %@NL@%
  4902. %@NL@%
  4903. %@AS@%  #include <time.h>%@AE@%%@NL@%
  4904. %@NL@%
  4905. %@AS@%  char *asctime( const struct tm *timeptr );%@AE@%%@NL@%
  4906. %@NL@%
  4907. %@AI@%timeptr%@AE@%                           Time/date structure
  4908.  
  4909. %@NL@%
  4910. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  4911. %@NL@%
  4912. The %@AB@%asctime%@AE@% function converts a time stored as a structure to a character
  4913. string. The %@AI@%timeptr%@AE@% value is usually obtained from a call to %@AB@%gmtime%@AE@% or
  4914. %@AB@%localtime%@AE@%, both of which return a pointer to a %@AB@%tm%@AE@% structure, defined in
  4915. TIME.H. (See %@AB@%gmtime%@AE@% for a complete description of the %@AB@%tm%@AE@% structure fields.) %@CR:C6A00110139 @%
  4916. %@NL@%
  4917. %@NL@%
  4918. The %@AB@%tm%@AE@% structure contains the following elements:  %@NL@%
  4919. %@NL@%
  4920. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  4921. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  4922. %@AB@%int tm_sec%@AE@%                        Seconds after the minute (0 -59)
  4923.  
  4924. %@AB@%int tm_min%@AE@%                        Minutes after the hour (0 -59)
  4925.  
  4926. %@AB@%int%@AE@% %@AB@%tm_hour%@AE@%                       Hours since midnight (0 -23)
  4927.  
  4928. %@AB@%int%@AE@% %@AB@%tm_mday%@AE@%                       Day of the month (0 -31)
  4929.  
  4930. %@AB@%int tm_mon%@AE@%                        Months since January (0 -11)
  4931.  
  4932. %@AB@%int tm_year%@AE@%                       Years since 1900
  4933.  
  4934. %@AB@%int tm_wday%@AE@%                       Days since Sunday (0 - 6)
  4935.  
  4936. %@AB@%int%@AE@% %@AB@%tm_yday%@AE@%                       Days since January 1 (0 -365)
  4937.  
  4938. %@AB@%int tm_isdst%@AE@%                      Daylight-saving-time flag
  4939.  
  4940. The string result produced by %@AB@%asctime%@AE@% contains exactly 26 characters and has
  4941. the form of the following example:  %@NL@%
  4942. %@NL@%
  4943. %@AS@%  Wed Jan 02 02:03:55 1980\n\0%@AE@%%@NL@%
  4944. %@NL@%
  4945. A 24-hour clock is used. All fields have a constant width. The newline
  4946. character (%@AB@%\n%@AE@%) and the null character (%@AB@%'\0'%@AE@%) occupy the last two positions
  4947. of the string. The %@AB@%asctime%@AE@% function uses a single statically allocated
  4948. buffer to hold the return string. Each call to this routine destroys the
  4949. result of the previous call.  %@NL@%
  4950. %@NL@%
  4951. %@NL@%
  4952. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  4953. %@NL@%
  4954. The %@AB@%asctime%@AE@% function returns a pointer to the character string result. There
  4955. is no error return.  %@NL@%
  4956. %@NL@%
  4957. %@NL@%
  4958. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  4959. %@NL@%
  4960. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  4961. %@NL@%
  4962. %@NL@%
  4963. %@NL@%
  4964. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  4965. %@NL@%
  4966. %@AB@%ctime%@AE@%, %@AB@%ftime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%time%@AE@%, %@AB@%tzset%@AE@%  %@NL@%
  4967. %@NL@%
  4968. %@NL@%
  4969. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  4970. %@NL@%
  4971. %@AS@%  /* ASCTIME.C: This program places the system time in the long integer
  4972. %@AS@%  aclock,
  4973. %@AS@%   * translates it into the structure newtime and then converts it to
  4974. %@AS@%   * string form for output, using the asctime function.
  4975. %@AS@%   */
  4976. %@AS@%  
  4977. %@AS@%  #include <time.h>
  4978. %@AS@%  #include <stdio.h>
  4979. %@AS@%  
  4980. %@AS@%  struct tm *newtime;
  4981. %@AS@%  time_t aclock;
  4982. %@AS@%  
  4983. %@AS@%  void main()
  4984. %@AS@%  {
  4985. %@AS@%     time( &aclock );                    /* Get time in seconds */
  4986. %@AS@%  
  4987. %@AS@%     newtime = localtime( &aclock );     /* Convert time to struct tm form
  4988. %@AS@%*/
  4989. %@AS@%  
  4990. %@AS@%     /* Print local time as a string */
  4991. %@AS@%     printf( "The current date and time are: %s\n", asctime( newtime ) );
  4992. %@AS@%  }%@AE@%%@NL@%
  4993. %@NL@%
  4994. %@NL@%
  4995. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  4996. %@NL@%
  4997. %@AS@%  
  4998. %@AS@%  
  4999. %@AS@%  The current date and time are: Thu Jun 15 06:57:59 1989%@AE@%%@NL@%
  5000. %@NL@%
  5001. %@NL@%
  5002. %@NL@%
  5003. %@NL@%
  5004. %@QR:asin@%%@NL@%
  5005. %@2@%%@CR:C6A00120140 @%%@AB@%asin Functions%@AE@%%@EH@%%@NL@%
  5006. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5007. %@NL@%
  5008. %@NL@%
  5009. %@3@%%@AB@%Description%@CR:C6A00120141 @%%@CR:C6A00120142 @% %@CR:C6A00120143 @%%@CR:C6A00120144 @%%@CR:C6A00120145 @%%@CR:C6A00120146 @%%@AE@%%@EH@%%@NL@%
  5010. %@NL@%
  5011. Calculate the arcsine.  %@NL@%
  5012. %@NL@%
  5013. %@AS@%  #include <math.h>%@AE@%%@NL@%
  5014. %@NL@%
  5015. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  5016. %@NL@%
  5017. %@AS@%  double asin( double x );%@AE@%%@NL@%
  5018. %@NL@%
  5019. %@AS@%  long double asinl( long double x );%@AE@%%@NL@%
  5020. %@NL@%
  5021. %@AI@%x%@AE@%                                 Value whose arcsine is to be calculated
  5022.  
  5023. %@NL@%
  5024. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5025. %@NL@%
  5026. The %@AB@%asin%@AE@% functions calculate the arcsine of %@AI@%x%@AE@% in the range -π/2 to π/2
  5027. radians. The value of %@AI@%x%@AE@% must be between -1 and 1. The %@AB@%asinl%@AE@% function is the
  5028. 80-bit counterpart, which uses an 80-bit, 10-byte coprocessor form of
  5029. arguments and return values. See the reference page on the long double
  5030. functions for more details on this data type.  %@NL@%
  5031. %@NL@%
  5032. %@NL@%
  5033. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5034. %@NL@%
  5035. The %@AB@%asin%@AE@% functions return the arcsine result. If %@AI@%x%@AE@% is less than -1 or
  5036. greater than 1, %@AB@%asin%@AE@% sets %@AB@%errno%@AE@% to %@AB@%EDOM%@AE@%, prints a %@AB@%DOMAIN%@AE@% error message to
  5037. %@AB@%stderr%@AE@%, and returns 0.  %@NL@%
  5038. %@NL@%
  5039. Error handling can be modified by using the %@AB@%matherr%@AE@% (or %@AB@%_matherrl%@AE@%) routine.
  5040. %@NL@%
  5041. %@NL@%
  5042. %@NL@%
  5043. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5044. %@NL@%
  5045. %@AB@%asin%@AE@%  %@NL@%
  5046. %@NL@%
  5047. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  5048. %@NL@%
  5049. %@NL@%
  5050. %@AB@%asinl%@AE@%  %@NL@%
  5051. %@NL@%
  5052.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  5053. %@NL@%
  5054. %@NL@%
  5055. %@NL@%
  5056. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5057. %@NL@%
  5058. %@AB@%acos%@AE@% functions, %@AB@%atan%@AE@% functions, %@AB@%cos%@AE@% functions, %@AB@%matherr%@AE@%, %@AB@%sin%@AE@% functions,%@AB@% tan%@AE@%
  5059. functions  %@NL@%
  5060. %@NL@%
  5061. %@NL@%
  5062. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5063. %@NL@%
  5064. %@AS@%  /* ASINCOS.C: This program prompts for a value in the range -1 to 1.
  5065. %@AS@%   * Input values outside this range will produce DOMAIN error messages.
  5066. %@AS@%   * If a valid value is entered, the program prints the arcsine and the
  5067. %@AS@%   * arccosine of that value.
  5068. %@AS@%   */
  5069. %@AS@%  
  5070. %@AS@%  #include <math.h>
  5071. %@AS@%  #include <stdio.h>
  5072. %@AS@%  #include <stdlib.h>
  5073. %@AS@%  #include <errno.h>
  5074. %@AS@%  
  5075. %@AS@%  void main()
  5076. %@AS@%  {
  5077. %@AS@%     double x, y;
  5078. %@AS@%  
  5079. %@AS@%     printf( "Enter a real number between -1 and 1: " );
  5080. %@AS@%     scanf( "%lf", &x );
  5081. %@AS@%     y = asin( x );
  5082. %@AS@%     printf( "Arcsine of %f = %f\n", x, y );
  5083. %@AS@%     y = acos( x );
  5084. %@AS@%     printf( "Arccosine of %f = %f\n", x, y );
  5085. %@AS@%  }%@AE@%%@NL@%
  5086. %@NL@%
  5087. %@NL@%
  5088. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5089. %@NL@%
  5090. %@AS@%  
  5091. %@AS@%  
  5092. %@AS@%  Enter a real number between -1 and 1: .32696
  5093. %@AS@%  Arcsine of 0.326960 = 0.333085
  5094. %@AS@%  Arccosine of 0.326960 = 1.237711%@AE@%%@NL@%
  5095. %@NL@%
  5096. %@NL@%
  5097. %@NL@%
  5098. %@NL@%
  5099. %@QR:assert@%%@NL@%
  5100. %@2@%%@CR:C6A00130147 @%%@AB@%assert%@AE@%%@EH@%%@NL@%
  5101. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5102. %@NL@%
  5103. %@NL@%
  5104. %@3@%%@AB@%Description%@CR:C6A00130148 @%%@CR:C6A00130149 @%%@AE@%%@EH@%%@NL@%
  5105. %@NL@%
  5106. Prints an error message and aborts the program.  %@NL@%
  5107. %@NL@%
  5108. %@AB@%#include <assert.h>%@AE@%               
  5109.  
  5110. %@AB@%#include <stdio.h>%@AE@%                
  5111.  
  5112. %@AS@%  void assert( int expression );%@AE@%%@NL@%
  5113. %@NL@%
  5114. %@AI@%expression%@AE@%                        C expression specifying assertion being 
  5115.                                   tested
  5116.  
  5117. %@NL@%
  5118. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5119. %@NL@%
  5120. The %@AB@%assert%@AE@% routine prints a diagnostic message and calls the %@AB@%abort%@AE@% routine
  5121. if %@AI@%expression%@AE@% is false (0). The diagnostic message has the form   %@CR:C6A00130150 @%  %@NL@%
  5122. %@NL@%
  5123. %@AS@%  Assertion failed: expression, file filename, line linenumber%@AE@%%@NL@%
  5124. %@NL@%
  5125. where %@AI@%filename%@AE@% is the name of the source file and %@AI@%linenumber%@AE@% is the line
  5126. number of the assertion that failed in the source file. No action is taken
  5127. if %@AI@%expression%@AE@% is true (nonzero).  %@NL@%
  5128. %@NL@%
  5129. The %@AB@%assert%@AE@% routine is typically used in program development to identify
  5130. program logic errors. The given expression should be chosen so that it holds
  5131. true only if the program is operating as intended. After a program has been
  5132. debugged, the special "no debug" identifier %@AB@%NDEBUG%@AE@% can be used to remove
  5133. %@AB@%assert%@AE@% calls from the program. If %@AB@%NDEBUG%@AE@% is defined (by any value) with a /D
  5134. command-line option or with a %@AB@%#define%@AE@% directive, the C preprocessor removes
  5135. all %@AB@%assert%@AE@% calls from the program source.%@CR:C6A00130151 @%%@CR:C6A00130152 @%  %@NL@%
  5136. %@NL@%
  5137. The %@AB@%assert%@AE@% routine is implemented as a macro.  %@NL@%
  5138. %@NL@%
  5139. %@NL@%
  5140. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5141. %@NL@%
  5142. None.  %@NL@%
  5143. %@NL@%
  5144. %@NL@%
  5145. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5146. %@NL@%
  5147. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  5148. %@NL@%
  5149. %@NL@%
  5150. %@NL@%
  5151. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5152. %@NL@%
  5153. %@AB@%abort%@AE@%, %@AB@%raise%@AE@%, %@AB@%signal%@AE@%  %@NL@%
  5154. %@NL@%
  5155. %@NL@%
  5156. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5157. %@NL@%
  5158. %@AS@%  /* ASSERT.C: In this program, the analyze_string function uses the
  5159. %@AS@%   * assert function to test several conditions related to string and
  5160. %@AS@%   * length. If any of the conditions fails, the program prints a
  5161. %@AS@%   * message indicating what caused the failure.
  5162. %@AS@%   */
  5163. %@AS@%  
  5164. %@AS@%  #include <stdio.h>
  5165. %@AS@%  #include <assert.h>
  5166. %@AS@%  #include <string.h>
  5167. %@AS@%  
  5168. %@AS@%  void analyze_string( char *string );   /* Prototype */
  5169. %@AS@%  
  5170. %@AS@%  void main()
  5171. %@AS@%  {
  5172. %@AS@%     char  test1[] = "abc", *test2 = NULL, test3[] = "";
  5173. %@AS@%  
  5174. %@AS@%     printf ( "Analyzing string '%s'\n", test1 );
  5175. %@AS@%     analyze_string( test1 );
  5176. %@AS@%     printf ( "Analyzing string '%s'\n", test2 );
  5177. %@AS@%     analyze_string( test2 );
  5178. %@AS@%     printf ( "Analyzing string '%s'\n", test3 );
  5179. %@AS@%     analyze_string( test3 );
  5180. %@AS@%  }
  5181. %@AS@%  
  5182. %@AS@%  /* Tests a string to see if it is NULL, empty, or longer than 0 characters
  5183. %@AS@%*/
  5184. %@AS@%  void analyze_string( char * string )
  5185. %@AS@%  {
  5186. %@AS@%     assert( string != NULL );        /* Cannot be NULL */
  5187. %@AS@%     assert( *string != '\0' );       /* Cannot be empty */
  5188. %@AS@%     assert( strlen( string ) > 2 );  /* Length must be greater than 2 */
  5189. %@AS@%  }%@AE@%%@NL@%
  5190. %@NL@%
  5191. %@NL@%
  5192. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5193. %@NL@%
  5194. %@AS@%  
  5195. %@AS@%  
  5196. %@AS@%  Analyzing string 'abc'
  5197. %@AS@%  Analyzing string '(null)'
  5198. %@AS@%  Assertion failed: string != NULL, file assert.c, line 28
  5199. %@AS@%  
  5200. %@AS@%  abnormal program termination %@AE@%%@NL@%
  5201. %@NL@%
  5202. %@NL@%
  5203. %@NL@%
  5204. %@NL@%
  5205. %@QR:atan@%%@NL@%
  5206. %@2@%%@CR:C6A00140153 @%%@AB@%atan Functions%@AE@%%@EH@%%@NL@%
  5207. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5208. %@NL@%
  5209. %@NL@%
  5210. %@3@%%@AB@%Description%@CR:C6A00140154 @%%@CR:C6A00140155 @% %@CR:C6A00140156 @%%@CR:C6A00140157 @% %@CR:C6A00140158 @%%@CR:C6A00140159 @%%@CR:C6A00140160 @%%@AE@%%@EH@%%@NL@%
  5211. %@NL@%
  5212. Calculate the arctangent of %@AI@%x%@AE@% (%@AB@%atan%@AE@% and %@AB@%atanl%@AE@%) and the arctangent of %@AI@%y/x%@AE@%
  5213. (%@AB@%atan2%@AE@% and %@AB@%atan2l%@AE@%).  %@NL@%
  5214. %@NL@%
  5215. %@AS@%  #include <math.h>%@AE@%%@NL@%
  5216. %@NL@%
  5217. %@AS@%  double atan( double x );%@AE@%%@NL@%
  5218. %@NL@%
  5219. %@AS@%  double atan2( double y, double x );%@AE@%%@NL@%
  5220. %@NL@%
  5221. %@AS@%  long double atanl( long double x );%@AE@%%@NL@%
  5222. %@NL@%
  5223. %@AS@%  long double atan2l( long double y, long double x );%@AE@%%@NL@%
  5224. %@NL@%
  5225. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Any number
  5226.  
  5227. %@NL@%
  5228. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5229. %@NL@%
  5230. The %@AB@%atan%@AE@% family of functions calculates the arctangent of %@AI@%x%@AE@%, and the %@AB@%atan2%@AE@%
  5231. family of functions calculates the arctangent of %@AI@%y%@AE@%/%@AI@%x%@AE@%. The %@AB@%atan%@AE@% group returns
  5232. a value in the range -π/2 to π/2 radians, and the %@AB@%atan2%@AE@% group returns a
  5233. value in the range -π toπ radians. The %@AB@%atan2%@AE@% functions use the signs of both
  5234. arguments to determine the quadrant of the return value.  %@NL@%
  5235. %@NL@%
  5236. %@NL@%
  5237. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5238. %@NL@%
  5239. The %@AB@%atan%@AE@% family of functions returns the arctangent result. If both
  5240. arguments of %@AB@%atan2%@AE@% or %@AB@%atan2l%@AE@% are 0, the function sets %@AB@%errno%@AE@% to %@AB@%EDOM%@AE@%, prints
  5241. a %@AB@%DOMAIN%@AE@% error message to %@AB@%stderr%@AE@%, and returns 0.  %@NL@%
  5242. %@NL@%
  5243. Error handling can be modified by using the %@AB@%matherr%@AE@% (or %@AB@%_matherrl%@AE@%) routine.
  5244. %@NL@%
  5245. %@NL@%
  5246. %@NL@%
  5247. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5248. %@NL@%
  5249. %@AB@%atan%@AE@%, %@AB@%atan2%@AE@%  %@NL@%
  5250. %@NL@%
  5251. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  5252. %@NL@%
  5253. %@NL@%
  5254. %@AB@%atanl%@AE@%, %@AB@%atan2l%@AE@%  %@NL@%
  5255. %@NL@%
  5256.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  5257. %@NL@%
  5258. %@NL@%
  5259. %@NL@%
  5260. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5261. %@NL@%
  5262. %@AB@%acos%@AE@% functions, %@AB@%asin%@AE@% functions, %@AB@%cos %@AE@%functions, %@AB@%matherr%@AE@%, %@AB@%sin%@AE@% functions, %@AB@%tan%@AE@%
  5263. functions  %@NL@%
  5264. %@NL@%
  5265. %@NL@%
  5266. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5267. %@NL@%
  5268. %@AS@%  /* ATAN.C: This program calculates the arctangent of 1 and -1. */
  5269. %@AS@%  
  5270. %@AS@%  #include <math.h>
  5271. %@AS@%  #include <stdio.h>
  5272. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  5273. %@NL@%
  5274. %@AS@%  void main()
  5275. %@AS@%  {
  5276. %@AS@%     double x1, x2, y;
  5277. %@AS@%  
  5278. %@AS@%     printf( "Enter a real number: " );
  5279. %@AS@%     scanf( "%lf", &x1 );
  5280. %@AS@%     y = atan( x1 );
  5281. %@AS@%     printf( "Arctangent of %f: %f\n", x1, y );
  5282. %@AS@%     printf( "Enter a second real number: " );
  5283. %@AS@%     scanf( "%lf", &x2 );
  5284. %@AS@%     y = atan2( x1, x2 );
  5285. %@AS@%     printf( "Arctangent of %f / %f: %f\n", x1, x2, y );
  5286. %@AS@%  }%@AE@%%@NL@%
  5287. %@NL@%
  5288. %@NL@%
  5289. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5290. %@NL@%
  5291. %@AS@%  
  5292. %@AS@%  
  5293. %@AS@%  Enter a real number: -862.42
  5294. %@AS@%  Arctangent of -862.420000: -1.569637
  5295. %@AS@%  Enter a second real number: 78.5149
  5296. %@AS@%  Arctangent of -862.420000 / 78.514900: -1.480006 %@AE@%%@NL@%
  5297. %@NL@%
  5298. %@NL@%
  5299. %@NL@%
  5300. %@NL@%
  5301. %@QR:atexit@%%@NL@%
  5302. %@2@%%@CR:C6A00150161 @%%@AB@%atexit%@AE@%%@EH@%%@NL@%
  5303. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5304. %@NL@%
  5305. %@NL@%
  5306. %@3@%%@AB@%Description%@CR:C6A00150162 @%%@CR:C6A00150163 @%%@AE@%%@EH@%%@NL@%
  5307. %@NL@%
  5308. Processes the specified function at exit.  %@NL@%
  5309. %@NL@%
  5310. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  5311.  
  5312. %@AS@%  int atexit( void ( *func )( void ) );%@AE@%%@NL@%
  5313. %@NL@%
  5314. %@AI@%func%@AE@%                              Function to be called
  5315.  
  5316. %@NL@%
  5317. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5318. %@NL@%
  5319. The %@AB@%atexit%@AE@% function is passed the address of a function (%@AI@%func%@AE@%) to be called
  5320. when the program terminates normally. Successive calls to %@AB@%atexit%@AE@% create a
  5321. register of functions that are executed in LIFO (last-in-first-out) order.
  5322. No more than 32 functions can be registered with %@AB@%atexit%@AE@% or %@AB@%onexit%@AE@%. The
  5323. functions passed to %@AB@%atexit%@AE@% cannot take parameters.  %@NL@%
  5324. %@NL@%
  5325. All routines passed to %@AB@%atexit%@AE@% should have the %@AB@%_loadds%@AE@% attribute if used in
  5326. multithread dynamic-link libraries.  %@NL@%
  5327. %@NL@%
  5328. %@NL@%
  5329. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5330. %@NL@%
  5331. The %@AB@%atexit%@AE@% function returns 0 if it is successful, or a nonzero value if an
  5332. error occurs (e.g., if there are already 32 exit functions defined).  %@NL@%
  5333. %@NL@%
  5334. %@NL@%
  5335. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5336. %@NL@%
  5337. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  5338. %@NL@%
  5339. %@NL@%
  5340. Use the ANSI-standard %@AB@%atexit%@AE@% function (rather than the similar %@AB@%onexit%@AE@%
  5341. function) whenever ANSI portability is desired.  %@NL@%
  5342. %@NL@%
  5343. In the OS/2 environment, the %@AB@%atexit%@AE@% function calls the OS/2 function
  5344. %@AB@%DosExitList%@AE@%.  %@NL@%
  5345. %@NL@%
  5346. %@NL@%
  5347. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5348. %@NL@%
  5349. %@AB@%abort%@AE@%, %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, %@AB@%onexit%@AE@%  %@NL@%
  5350. %@NL@%
  5351. %@NL@%
  5352. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5353. %@NL@%
  5354. %@AS@%  /* ATEXIT.C: This program pushes four functions onto the stack of
  5355. %@AS@%  functions
  5356. %@AS@%   * to be executed when atexit is called. When the program exits, these
  5357. %@AS@%   * programs are executed on a "last in, first out" basis.
  5358. %@AS@%   */
  5359. %@AS@%  
  5360. %@AS@%  #include <stdlib.h>
  5361. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  5362. %@NL@%
  5363. %@AS@%  void fn1( void ), fn2( void ), fn3( void ), fn4( void );
  5364. %@AS@%  
  5365. %@AS@%  void main()
  5366. %@AS@%  {
  5367. %@AS@%     atexit( fn1 );
  5368. %@AS@%     atexit( fn2 );
  5369. %@AS@%     atexit( fn3 );
  5370. %@AS@%     atexit( fn4 );
  5371. %@AS@%     printf( "This is executed first.\n" );
  5372. %@AS@%  }
  5373. %@AS@%  
  5374. %@AS@%  void fn1()
  5375. %@AS@%  {
  5376. %@AS@%     printf( "next.\n" );
  5377. %@AS@%  }
  5378. %@AS@%  
  5379. %@AS@%  void fn2()
  5380. %@AS@%  {
  5381. %@AS@%     printf( "executed " );
  5382. %@AS@%  }
  5383. %@AS@%  
  5384. %@AS@%  void fn3()
  5385. %@AS@%  {
  5386. %@AS@%     printf( "is " );
  5387. %@AS@%  }
  5388. %@AS@%  
  5389. %@AS@%  void fn4()
  5390. %@AS@%  {
  5391. %@AS@%     printf( "This " );
  5392. %@AS@%  }%@AE@%%@NL@%
  5393. %@NL@%
  5394. %@NL@%
  5395. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5396. %@NL@%
  5397. %@AS@%  
  5398. %@AS@%  
  5399. %@AS@%  This is executed first.
  5400. %@AS@%  This is executed next. %@AE@%%@NL@%
  5401. %@NL@%
  5402. %@NL@%
  5403. %@NL@%
  5404. %@NL@%
  5405. %@QR:atof@%%@QR:atoi@%%@QR:atol@%%@QR:_atold@%%@NL@%
  5406. %@2@%%@CR:C6A00160164 @%%@AB@%atof, atoi, atol, _atold%@AE@%%@EH@%%@NL@%
  5407. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5408. %@NL@%
  5409. %@NL@%
  5410. %@3@%%@AB@%Description%@CR:C6A00160165 @% %@CR:C6A00160166 @%%@CR:C6A00160167 @%%@AE@%%@EH@%%@NL@%
  5411. %@NL@%
  5412. Convert strings to double (%@AB@%atof%@AE@%), long double (%@AB@%_atold%@AE@%) integer %@AB@%(atoi%@AE@%), or
  5413. long (%@AB@%atol%@AE@%).  %@NL@%
  5414. %@NL@%
  5415. %@AB@%#include <math.h>%@AE@%                 %@AB@%atof%@AE@%,%@AB@% _atold%@AE@%
  5416.  
  5417. %@AB@%#include <stdlib.h>%@AE@%               %@AB@%atof%@AE@%, %@AB@%_atold%@AE@%, %@AB@%atoi%@AE@%, %@AB@%atol%@AE@%
  5418.  
  5419. %@AS@%  double atof( const char *string );%@AE@%%@NL@%
  5420. %@NL@%
  5421. %@AS@%  long double _atold( const char *string );%@AE@%%@NL@%
  5422. %@NL@%
  5423. %@AS@%  int atoi( const char *string );%@AE@%%@NL@%
  5424. %@NL@%
  5425. %@AS@%  long atol( const char *string );%@AE@%%@NL@%
  5426. %@NL@%
  5427. %@AI@%string%@AE@%                            String to be converted
  5428.  
  5429. %@NL@%
  5430. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5431. %@NL@%
  5432. These functions convert a character string to a double-precision
  5433. floating-point value (%@AB@%atof%@AE@%), an integer value (%@AB@%atoi%@AE@%), a long integer value
  5434. (%@AB@%atol%@AE@%), or a long double value (%@AB@%_atold%@AE@%). The input string is a sequence of
  5435. characters that can be interpreted as a numerical value of the specified
  5436. type.%@CR:C6A00160168 @%%@CR:C6A00160169 @%  %@NL@%
  5437. %@NL@%
  5438. The string size that can be handled by the %@AB@%atof%@AE@% or %@AB@%_atold %@AE@%function is
  5439. limited to 100 characters. %@AB@%  %@AE@%%@NL@%
  5440. %@NL@%
  5441. The function stops reading the input string at the first character that it
  5442. cannot recognize as part of a number. This character may be the null
  5443. character (%@AB@%'\0'%@AE@%) terminating the string.  %@NL@%
  5444. %@NL@%
  5445. The %@AB@%atof%@AE@% and %@AB@%_atold%@AE@% functions expect %@AI@%string%@AE@% to have the following form:  %@NL@%
  5446. %@NL@%
  5447. %@AS@%  [[whitespace]] [[{sign}]] [[ IK0digits]] [[.digits]] 
  5448. %@AS@%  [[{d| D | e | E}[[sign]digits]]%@AE@%%@NL@%
  5449. %@NL@%
  5450. A %@AI@%whitespace%@AE@% consists of space and/or tab characters, which are ignored;
  5451. %@AI@%sign%@AE@% is either plus (+) or minus (-); and %@AI@%digits%@AE@% are one or more decimal
  5452. digits. If no digits appear before the decimal point, at least one must
  5453. appear after the decimal point. The decimal digits may be followed by an
  5454. exponent, which consists of an introductory letter (%@AB@%d%@AE@%, %@AB@%D%@AE@%, %@AB@%e%@AE@%, or %@AB@%E%@AE@%) and an
  5455. optionally signed decimal integer.  %@NL@%
  5456. %@NL@%
  5457. The %@AB@%atoi%@AE@% and %@AB@%atol%@AE@% functions do not recognize decimal points or exponents.
  5458. The %@AI@%string%@AE@% argument for these functions has the form  %@NL@%
  5459. %@NL@%
  5460. %@AS@%  [[whitespace]] [[sign]]digits %@AE@%%@NL@%
  5461. %@NL@%
  5462. where %@AI@%whitespace%@AE@%, %@AI@%sign%@AE@%, and %@AI@%digits%@AE@% are exactly as described above for %@AB@%atof%@AE@%.
  5463. %@NL@%
  5464. %@NL@%
  5465. %@NL@%
  5466. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5467. %@NL@%
  5468. Each function returns the %@AB@%double%@AE@%, %@AB@%long double%@AE@%, %@AB@%int%@AE@%, or %@AB@%long%@AE@% value produced
  5469. by interpreting the input characters as a number. The return value is 0 (for
  5470. %@AB@%atoi%@AE@%), 0L (for %@AB@%atol%@AE@%), and 0.0 (for %@AB@%atof%@AE@% and %@AB@%_atold%@AE@%) if the input cannot be
  5471. converted to a value of that type. The return value is undefined in case of
  5472. overflow.  %@NL@%
  5473. %@NL@%
  5474. %@NL@%
  5475. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5476. %@NL@%
  5477. %@AB@%atof%@AE@%,%@AB@% atoi%@AE@%, %@AB@%atol%@AE@%  %@NL@%
  5478. %@NL@%
  5479. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  5480. %@NL@%
  5481. %@NL@%
  5482. %@AB@%_atold%@AE@%  %@NL@%
  5483. %@NL@%
  5484.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  5485. %@NL@%
  5486. %@NL@%
  5487. %@NL@%
  5488. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5489. %@NL@%
  5490. %@AB@%ecvt%@AE@%, %@AB@%fcvt%@AE@%, %@AB@%gcvt%@AE@%  %@NL@%
  5491. %@NL@%
  5492. %@NL@%
  5493. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5494. %@NL@%
  5495. %@AS@%  /* ATOF.C: This program shows how numbers stored as strings can be
  5496. %@AS@%   * converted to numeric values using the atof, atoi, and atol functions.
  5497. %@AS@%   */
  5498. %@AS@%  
  5499. %@AS@%  #include <stdlib.h>
  5500. %@AS@%  #include <stdio.h>
  5501. %@AS@%  
  5502. %@AS@%  void main()
  5503. %@AS@%  {
  5504. %@AS@%     char *s; double x; int i; long l;
  5505. %@AS@%  
  5506. %@AS@%     s = "  -2309.12E-15";    /* Test of atof */
  5507. %@AS@%     x = atof( s );
  5508. %@AS@%     printf( "atof test:  ASCII string: %s\tfloat:     %e\n", s, x );
  5509. %@AS@%  
  5510. %@AS@%     s = "7.8912654773d210";  /* Test of atof */
  5511. %@AS@%     x = atof( s );
  5512. %@AS@%     printf( "atof test:  ASCII string: %s\tfloat:     %e\n", s, x );
  5513. %@AS@%  
  5514. %@AS@%     s = "  -9885 pigs";      /* Test of atoi */
  5515. %@AS@%     i = atoi( s );
  5516. %@AS@%     printf( "atoi test:  ASCII string: %s\t\tinteger: %d\n", s, i );
  5517. %@AS@%  
  5518. %@AS@%     s = "98854 dollars";     /* Test of atol */
  5519. %@AS@%     l = atol( s );
  5520. %@AS@%     printf( "atol test:  ASCII string: %s\t\tlong:    %ld\n", s, l );
  5521. %@AS@%  }%@AE@%%@NL@%
  5522. %@NL@%
  5523. %@NL@%
  5524. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5525. %@NL@%
  5526. %@AS@%  
  5527. %@AS@%  
  5528. %@AS@%  atof test:  ASCII string:   -2309.12E-15        float:     -2.309120e-012
  5529. %@AS@%  atof test:  ASCII string: 7.8912654773d210      float:     7.891265e+210
  5530. %@AS@%  atoi test:  ASCII string:   -9885 pigs          integer: -9885
  5531. %@AS@%  atol test:  ASCII string: 98854 dollars         long:    98854 %@AE@%%@NL@%
  5532. %@NL@%
  5533. %@NL@%
  5534. %@NL@%
  5535. %@NL@%
  5536. %@QR:bdos@%%@NL@%
  5537. %@2@%%@CR:C6A00170170 @%%@AB@%bdos%@AE@%%@EH@%%@NL@%
  5538. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5539. %@NL@%
  5540. %@NL@%
  5541. %@3@%%@AB@%Description%@CR:C6A00170171 @%%@CR:C6A00170172 @%%@AE@%%@EH@%%@NL@%
  5542. %@NL@%
  5543. Invokes the DOS system call.  %@NL@%
  5544. %@NL@%
  5545. %@AB@%#include <dos.h>%@AE@%  %@NL@%
  5546. %@NL@%
  5547. %@AS@%  int bdos( int dosfunc, unsigned int dosdx, unsigned int dosal );%@AE@%%@NL@%
  5548. %@NL@%
  5549. %@AI@%dosfunc%@AE@%                           Function number
  5550.  
  5551. %@AI@%dosdx%@AE@%                             DX register value
  5552.  
  5553. %@AI@%dosal%@AE@%                             AL register value
  5554.  
  5555. %@NL@%
  5556. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5557. %@NL@%
  5558. The %@AB@%bdos%@AE@% function invokes the DOS system call specified by %@AI@%dosfunc%@AE@% after
  5559. placing the values specified by %@AI@%dosdx%@AE@% and %@AI@%dosal%@AE@% in the DX and AL registers,
  5560. respectively. The %@AB@%bdos%@AE@% function executes an INT 21H instruction to invoke
  5561. the system call. When the system call is complete, %@AB@%bdos%@AE@% returns the contents
  5562. of the AX register. %@CR:C6A00170173 @%  %@NL@%
  5563. %@NL@%
  5564. The %@AB@%bdos%@AE@% function is intended to be used to invoke DOS system calls that
  5565. either take no arguments or take arguments only in the DX (DH, DL) and/or AL
  5566. registers.  %@NL@%
  5567. %@NL@%
  5568. Do not use the %@AB@%bdos%@AE@% function to call interrupts that modify the DS register.
  5569. Instead, use the %@AB@%intdosx%@AE@% or %@AB@%int86x%@AE@% function. The %@AB@%intdosx%@AE@% and %@AB@%int86x%@AE@%
  5570. functions load the DS and ES registers from the %@AI@%segregs%@AE@% parameter and also
  5571. store the DS and ES registers into %@AI@%segregs%@AE@% after the function call.  %@NL@%
  5572. %@NL@%
  5573. This call should not be used to invoke system calls that indicate errors by
  5574. setting the carry flag. Since C programs do not have access to this flag,
  5575. your program cannot determine whether the return value is an error code. The
  5576. %@AB@%intdos%@AE@% function should be used in these cases.  %@NL@%
  5577. %@NL@%
  5578. %@NL@%
  5579. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5580. %@NL@%
  5581. The %@AB@%bdos%@AE@% function returns the value of the AX register after the system call
  5582. has completed.  %@NL@%
  5583. %@NL@%
  5584. %@NL@%
  5585. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5586. %@NL@%
  5587.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  5588. %@NL@%
  5589. %@NL@%
  5590. %@NL@%
  5591. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5592. %@NL@%
  5593. %@AB@%intdos%@AE@%, %@AB@%intdosx%@AE@%%@CR:C6A00170174 @%  %@NL@%
  5594. %@NL@%
  5595. %@NL@%
  5596. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5597. %@NL@%
  5598. %@AS@%  /* BDOS.C: This example calls DOS function 0x9 (display string)
  5599. %@AS@%   * to display a $-terminated string.
  5600. %@AS@%   */
  5601. %@AS@%  
  5602. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  5603. %@NL@%
  5604. %@AS@%  /* Function 0x09 assumes that DS will contain segment of the string.
  5605. %@AS@%   * This will be true for all memory models if the string is declared near.
  5606. %@AS@%   */
  5607. %@AS@%  char _near str[] = "Hello world!\r\n$";
  5608. %@AS@%  
  5609. %@AS@%  void main()
  5610. %@AS@%  {
  5611. %@AS@%     /* Offset of string must be in DX, segment in DS. AL is not needed,
  5612. %@AS@%      * so 0 is used.
  5613. %@AS@%      */
  5614. %@AS@%     bdos( 0x09, (int)str, 0 );
  5615. %@AS@%  }%@AE@%%@NL@%
  5616. %@NL@%
  5617. %@NL@%
  5618. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5619. %@NL@%
  5620. %@AS@%  
  5621. %@AS@%  
  5622. %@AS@%  Hello world! %@AE@%%@NL@%
  5623. %@NL@%
  5624. %@NL@%
  5625. %@NL@%
  5626. %@NL@%
  5627. %@QR:_beginthread@%%@NL@%
  5628. %@2@%%@CR:C6A00180175 @%%@AB@%_beginthread%@AE@%%@EH@%%@NL@%
  5629. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5630. %@NL@%
  5631. %@NL@%
  5632. %@3@%%@AB@%Description%@CR:C6A00180176 @% %@CR:C6A00180177 @%%@AE@%%@EH@%%@NL@%
  5633. %@NL@%
  5634. Begins thread in OS/2 process.  %@NL@%
  5635. %@NL@%
  5636. %@AB@%#include <process.h>%@AE@%              Multithread version of PROCESS.H
  5637.  
  5638. %@AB@%#include <stddef.h>%@AE@%               Declaration of %@AI@%threadid%@AE@% variable
  5639.  
  5640. %@AS@%  int _far  _beginthread( void( _far *start_address )( void _far * ), 
  5641. %@AS@%  void  _far *stack_bottom, unsigned stack_size, void  _far *arglist );%@AE@%%@NL@%
  5642. %@NL@%
  5643. %@AI@%start_address%@AE@%                     Starting address
  5644.  
  5645. %@AI@%stack_bottom%@AE@%                      Address of the thread stack
  5646.  
  5647. %@AI@%stack_size%@AE@%                        Stack size for thread
  5648.  
  5649. %@AI@%arglist%@AE@%                           Argument list for thread
  5650.  
  5651. %@NL@%
  5652. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5653. %@NL@%
  5654. The %@AB@%_beginthread%@AE@% function creates a thread that begins execution of a far
  5655. routine at %@AI@%start_address%@AE@%. When the thread returns from that far routine, it
  5656. is terminated automatically. The user can also terminate the thread by
  5657. calling %@AB@%_endthread%@AE@%.  %@NL@%
  5658. %@NL@%
  5659. The address of the thread stack is given by %@AI@%stack_bottom%@AE@%. If %@AI@%stack_bottom%@AE@% is
  5660. set to %@AB@%NULL%@AE@%, the run-time library code will allocate and deallocate the
  5661. thread stack as needed. Since the %@AB@%_beginthread%@AE@% function can determine the
  5662. current status of all thread IDs, it can free the old stack and allocate a
  5663. new stack whenever a thread is reused.  %@NL@%
  5664. %@NL@%
  5665. If it is not %@AB@%NULL%@AE@%, the %@AI@%stack_bottom%@AE@% argument must specify a word address,
  5666. and the stack must be at least as long as specified by the %@AI@%stack_size%@AE@%
  5667. argument. Usually this memory is either a global array or memory returned by
  5668. %@AB@%malloc%@AE@% or %@AB@%_fmalloc%@AE@%.  %@NL@%
  5669. %@NL@%
  5670. The %@AI@%stack_size%@AE@% argument must be even and nonzero.  %@NL@%
  5671. %@NL@%
  5672. If you are writing multithread programs that make C run-time calls from
  5673. child threads, be sure to allocate a sufficiently large stack. For example,
  5674. the C function %@AB@%printf%@AE@% requires more than 500 bytes of stack space. To be
  5675. safe, allocate at least 2,048 bytes for a thread's stack. (If your child
  5676. thread makes no run-time calls, stack space is generally not a problem.)  %@NL@%
  5677. %@NL@%
  5678. As a general rule, you should have 2K of stack space free when calling any
  5679. API (Applications Program Interface) routine (e.g., OS/2 system calls).  %@NL@%
  5680. %@NL@%
  5681. The %@AI@%arglist%@AE@% is a parameter, the size of a far pointer, to be passed to the
  5682. newly created thread. Typically it is the address of a data item, such as a
  5683. character string, to be passed to the new thread. The %@AI@%arglist%@AE@% may be %@AB@%NULL%@AE@% if
  5684. not needed, but %@AB@%_beginthread%@AE@% should be provided with some value to pass to
  5685. the child thread.  %@NL@%
  5686. %@NL@%
  5687. All threads will be terminated if any thread calls %@AB@%abort%@AE@%, %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, or
  5688. %@AB@%DosExit%@AE@%. A good practice in multithread programming is to make the first
  5689. thread the main thread and wait until other threads have terminated before
  5690. exiting the program.  %@NL@%
  5691. %@NL@%
  5692. The OS/2 function %@AB@%DosCreateThread%@AE@% should not be called directly to create
  5693. threads. The %@AB@%_beginthread%@AE@% function performs initialization procedures
  5694. required to call other C run-time library functions safely.  %@NL@%
  5695. %@NL@%
  5696. %@NL@%
  5697. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5698. %@NL@%
  5699. The function returns the thread identification number of the new thread, if
  5700. successful. A return value of -1 indicates an error, and %@AB@%errno%@AE@% is set to one
  5701. of the following values:  %@NL@%
  5702. %@NL@%
  5703. %@AB@%Value %@AE@%                            %@AB@%Meaning%@AE@%
  5704. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5705. %@AB@%EAGAIN%@AE@%                            Too many threads
  5706.  
  5707. %@AB@%EINVAL%@AE@%                            Invalid argument, "bad stack"
  5708.  
  5709. %@NL@%
  5710. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5711. %@NL@%
  5712.  ANSI   DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  5713. %@NL@%
  5714. %@NL@%
  5715. %@NL@%
  5716. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5717. %@NL@%
  5718. %@AB@%_endthread%@AE@%  %@NL@%
  5719. %@NL@%
  5720. %@NL@%
  5721. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5722. %@NL@%
  5723. %@AS@%  /* BEGTHRD.C illustrates multiple threads using functions:
  5724. %@AS@%   *      _beginthread            _endthread
  5725. %@AS@%   *
  5726. %@AS@%   * Also the global variable:
  5727. %@AS@%   *      _threadid
  5728. %@AS@%   *
  5729. %@AS@%   * This program requires the multithread library. For example, compile
  5730. %@AS@%   * with the following command line:
  5731. %@AS@%   *      CL /MT THREADS.C
  5732. %@AS@%   */
  5733. %@AS@%  
  5734. %@AS@%  #define INCL_NOCOMMON
  5735. %@AS@%  #define INCL_NOPM
  5736. %@AS@%  #define INCL_DOSPROCESS
  5737. %@AS@%  #define INCL_VIO
  5738. %@AS@%  #include <os2.h>
  5739. %@AS@%  #include <process.h>    /* _beginthread, _endthread */
  5740. %@AS@%  #include <stddef.h>     /* _threadid                */
  5741. %@AS@%  #include <stdlib.h>
  5742. %@AS@%  #include <conio.h>
  5743. %@AS@%  
  5744. %@AS@%  void Bounce( int c );       /* Prototypes */
  5745. %@AS@%  void CheckKey( void *dummy );%@AE@%%@NL@%
  5746. %@NL@%
  5747. %@AS@%  /* GetRandom returns a random integer between min and max. */
  5748. %@AS@%  #define GetRandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) +
  5749. %@AS@%(min))
  5750. %@AS@%  
  5751. %@AS@%  #define STACK_SIZE   4096
  5752. %@AS@%  
  5753. %@AS@%  BOOL repeat = TRUE;         /* Global repeat flag and video variable */
  5754. %@AS@%  VIOMODEINFO vmi = { sizeof( VIOMODEINFO ) };
  5755. %@AS@%  
  5756. %@AS@%  void main()
  5757. %@AS@%  {
  5758. %@AS@%      PCHAR   stack;
  5759. %@AS@%      CHAR    ch = 'A';
  5760. %@AS@%  
  5761. %@AS@%      /* Get display screen's text row and column information. */
  5762. %@AS@%      VioGetMode( &vmi, 0 );
  5763. %@AS@%  
  5764. %@AS@%      /* Launch CheckKey thread to check for terminating keystroke. */
  5765. %@AS@%      _beginthread( CheckKey, NULL, STACK_SIZE, NULL );
  5766. %@AS@%  
  5767. %@AS@%      /* Loop until CheckKey terminates program. */
  5768. %@AS@%      while( repeat )
  5769. %@AS@%      {
  5770. %@AS@%          /* On first loops, launch character threads. */
  5771. %@AS@%          _beginthread( Bounce, NULL, STACK_SIZE, (void *)ch++ );
  5772. %@AS@%  
  5773. %@AS@%          /* Wait one second between loops. */
  5774. %@AS@%          DosSleep( 1000L );
  5775. %@AS@%      }
  5776. %@AS@%  }
  5777. %@AS@%  
  5778. %@AS@%  /* CheckKey - Thread to wait for a keystroke, then clear repeat flag. */
  5779. %@AS@%  void CheckKey( void *dummy )
  5780. %@AS@%  {
  5781. %@AS@%      getch();
  5782. %@AS@%      repeat = 0;      /* _endthread implied */
  5783. %@AS@%  }
  5784. %@AS@%  
  5785. %@AS@%  /* Bounce - Thread to create and control a colored letter that moves
  5786. %@AS@%   * around on the screen.
  5787. %@AS@%   *
  5788. %@AS@%   * Params: ch - the letter to be moved
  5789. %@AS@%   */
  5790. %@AS@%  void Bounce( int ch )
  5791. %@AS@%  {
  5792. %@AS@%      /* Generate letter and color attribute from thread argument. */
  5793. %@AS@%      char      blankcell[2] = { 0x20, 0x07 };
  5794. %@AS@%      char      blockcell[2] = { ch , (ch % 16) + 1 };
  5795. %@AS@%      int       xold, xcur, yold, ycur;
  5796. %@AS@%      BOOL      first = TRUE;%@AE@%%@NL@%
  5797. %@NL@%
  5798. %@AS@%  /* Seed random number generator and get initial location. */
  5799. %@AS@%      srand( *_threadid );
  5800. %@AS@%      xcur = GetRandom( 0, vmi.col - 1 );
  5801. %@AS@%      ycur = GetRandom( 0, vmi.row - 1 );
  5802. %@AS@%      while( repeat )
  5803. %@AS@%      {
  5804. %@AS@%          /* Pause between loops. */
  5805. %@AS@%          DosSleep( 100L );
  5806. %@AS@%  
  5807. %@AS@%          /* Blank out our old position on the screen, and draw new letter.
  5808. %@AS@%*/
  5809. %@AS@%          if( first )
  5810. %@AS@%              first = FALSE;
  5811. %@AS@%          else
  5812. %@AS@%              VioWrtCellStr( blankcell, 2, yold, xold, 0 );
  5813. %@AS@%          VioWrtCellStr( blockcell, 2, ycur, xcur, 0 );
  5814. %@AS@%  
  5815. %@AS@%          /* Increment the coordinate for next placement of the block. */
  5816. %@AS@%          xold = xcur;
  5817. %@AS@%          yold = ycur;
  5818. %@AS@%          xcur += GetRandom( -1, 1 );
  5819. %@AS@%          ycur += GetRandom( -1, 1 );
  5820. %@AS@%  
  5821. %@AS@%          /* Correct placement (and beep) if about to go off the screen. */
  5822. %@AS@%          if( xcur < 0 )
  5823. %@AS@%              xcur = 1;
  5824. %@AS@%          else if( xcur == vmi.col )
  5825. %@AS@%              xcur = vmi.col - 2;
  5826. %@AS@%          else if( ycur < 0 )
  5827. %@AS@%              ycur = 1;
  5828. %@AS@%          else if( ycur == vmi.row )
  5829. %@AS@%              ycur = vmi.row - 2;
  5830. %@AS@%  
  5831. %@AS@%          /* If not at screen border, continue, otherwise beep. */
  5832. %@AS@%          else
  5833. %@AS@%              continue;
  5834. %@AS@%          DosBeep( (ch - 'A') * 100, 175 );
  5835. %@AS@%      }
  5836. %@AS@%      /* _endthread given (but not really needed) to terminate. */
  5837. %@AS@%      _endthread();
  5838. %@AS@%  }%@AE@%%@NL@%
  5839. %@NL@%
  5840. %@NL@%
  5841. %@NL@%
  5842. %@NL@%
  5843. %@QR:Bessel@%%@NL@%
  5844. %@2@%%@CR:C6A00190178 @%%@AB@%Bessel Functions%@AE@%%@EH@%%@NL@%
  5845. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5846. %@NL@%
  5847. %@NL@%
  5848. %@3@%%@AB@%Description%@CR:C6A00190179 @%%@CR:C6A00190180 @% %@CR:C6A00190181 @%%@CR:C6A00190182 @% %@CR:C6A00190183 @% %@CR:C6A00190184 @%%@CR:C6A00190185 @%%@CR:C6A00190186 @% %@CR:C6A00190187 @%%@CR:C6A00190188 @%%@CR:C6A00190189 @%%@CR:C6A00190190 @%%@EH@%
  5849. %@AB@%%@AE@%%@NL@%
  5850. %@NL@%
  5851. Compute the Bessel function.  %@NL@%
  5852. %@NL@%
  5853. %@AB@%#include <math.h>%@AE@%  %@NL@%
  5854. %@NL@%
  5855. %@AS@%  double j0( double x );%@AE@%%@NL@%
  5856. %@NL@%
  5857. %@AS@%  double j1( double x );%@AE@%%@NL@%
  5858. %@NL@%
  5859. %@AS@%  double jn( int n, double x );%@AE@%%@NL@%
  5860. %@NL@%
  5861. %@AS@%  double y0( double x );%@AE@%%@NL@%
  5862. %@NL@%
  5863. %@AS@%  double y1( double x );%@AE@%%@NL@%
  5864. %@NL@%
  5865. %@AS@%  double yn( int n, double x );%@AE@%%@NL@%
  5866. %@NL@%
  5867. %@AS@%  long double _j0l( long double x );%@AE@%%@NL@%
  5868. %@NL@%
  5869. %@AS@%  long double _jnl( int n, long double x );%@AE@%%@NL@%
  5870. %@NL@%
  5871. %@AS@%  long double _j1l( long double x );%@AE@%%@NL@%
  5872. %@NL@%
  5873. %@AS@%  long double _y0l( long double x );%@AE@%%@NL@%
  5874. %@NL@%
  5875. %@AS@%  long double _y1l( long double x );%@AE@%%@NL@%
  5876. %@NL@%
  5877. %@AS@%  long double _ynl( int n, long double x );%@AE@%%@NL@%
  5878. %@NL@%
  5879. %@AI@%x%@AE@%                                 Floating-point value
  5880.  
  5881. %@AI@%n%@AE@%                                 Integer order
  5882.  
  5883. %@NL@%
  5884. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5885. %@NL@%
  5886. The %@AB@%j0%@AE@%, %@AB@%j1%@AE@%, and %@AB@%jn%@AE@% routines return Bessel functions of the first kind─orders
  5887. 0, 1, and %@AI@%n%@AE@%, respectively.  %@NL@%
  5888. %@NL@%
  5889. The %@AB@%y0%@AE@%, %@AB@%y1%@AE@%, and %@AB@%yn%@AE@% routines return Bessel functions of the second
  5890. kind─orders 0, 1, and %@AI@%n%@AE@%, respectively. The argument %@AI@%x%@AE@% must be positive.  %@NL@%
  5891. %@NL@%
  5892. The long double versions of these functions are the 80-bit counterparts and
  5893. use the 80-bit, 10-byte coprocessor form of arguments and return values. See
  5894. the reference page on the long double functions for more details on this
  5895. data type.  %@NL@%
  5896. %@NL@%
  5897. The Bessel functions are explained more fully in most mathematics reference
  5898. books, such as the %@AI@%Handbook of Mathematical Functions%@AE@% (Abramowitz and
  5899. Stegun; Washington: U.S. Government Printing Office, 1964). These functions
  5900. are commonly used in the mathematics of electromagnetic wave theory.  %@NL@%
  5901. %@NL@%
  5902. %@NL@%
  5903. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  5904. %@NL@%
  5905. These functions return the result of a Bessel function of %@AI@%x%@AE@%.  %@NL@%
  5906. %@NL@%
  5907. For %@AB@%y0%@AE@%, %@AB@%y1%@AE@%, or %@AB@%yn%@AE@%, if %@AI@%x%@AE@% is negative, the routine sets %@AB@%errno%@AE@% to %@AB@%EDOM%@AE@%, prints
  5908. a %@AB@%DOMAIN%@AE@% error message to %@AB@%stderr%@AE@%, and returns %@AB@%-HUGE_VAL%@AE@%.  %@NL@%
  5909. %@NL@%
  5910. Error handling can be modified by using the %@AB@%matherr%@AE@% (or %@AB@%_matherrl%@AE@%) routine.
  5911. %@NL@%
  5912. %@NL@%
  5913. %@NL@%
  5914. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  5915. %@NL@%
  5916. %@AB@%j0%@AE@%, %@AB@%j1%@AE@%, %@AB@%jn%@AE@%, %@AB@%y0%@AE@%, %@AB@%y1%@AE@%, %@AB@%yn%@AE@%  %@NL@%
  5917. %@NL@%
  5918.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  5919. %@NL@%
  5920. %@NL@%
  5921. %@AB@%_j0l%@AE@%,  %@AB@%_j1l%@AE@%,  %@AB@%_jnl%@AE@%,  %@AB@%_y0l%@AE@%,  %@AB@%_y1l%@AE@%,  %@AB@%_ynl%@AE@%  %@NL@%
  5922. %@NL@%
  5923.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  5924. %@NL@%
  5925. %@NL@%
  5926. %@NL@%
  5927. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  5928. %@NL@%
  5929. %@AB@%matherr%@AE@%  %@NL@%
  5930. %@NL@%
  5931. %@NL@%
  5932. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  5933. %@NL@%
  5934. %@AS@%  /* BESSEL.C: This program illustrates Bessel functions, including:
  5935. %@AS@%   *      j0          j1          jn          y0          y1          yn
  5936. %@AS@%   */
  5937. %@AS@%  
  5938. %@AS@%  #include <math.h>
  5939. %@AS@%  #include <stdio.h>
  5940. %@AS@%  
  5941. %@AS@%  void main()
  5942. %@AS@%  {
  5943. %@AS@%      double x = 2.387;
  5944. %@AS@%      int n = 3, c;
  5945. %@AS@%  
  5946. %@AS@%      printf( "Bessel functions for x = %f:\n", x );
  5947. %@AS@%      printf( "  Kind\t\tOrder\t\Function\tResult\n\n" );
  5948. %@AS@%      printf( "  First\t\t0\tj0( x )\t\t%f\n", j0( x ) );
  5949. %@AS@%      printf( "  First\t\t1\tj1( x )\t\t%f\n", j1( x ) );
  5950. %@AS@%      for( c = 2; c < 5; c++ )
  5951. %@AS@%          printf( "  First\t\t%d\tjn( n, x )\t%f\n", c, jn( c, x ) );
  5952. %@AS@%  
  5953. %@AS@%      printf( "  Second\t0\ty0( x )\t\t%f\n", y0( x ) );
  5954. %@AS@%      printf( "  Second\t1\ty1( x )\t\t%f\n", y1( x ) );
  5955. %@AS@%      for( c = 2; c < 5; c++ )
  5956. %@AS@%          printf( "  Second\t%d\tyn( n, x )\t%f\n", c, yn( c, x ) );
  5957. %@AS@%  }%@AE@%%@NL@%
  5958. %@NL@%
  5959. %@NL@%
  5960. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  5961. %@NL@%
  5962. %@AS@%  
  5963. %@AS@%  
  5964. %@AS@%  Bessel functions for x = 2.387000:
  5965. %@AS@%    Kind          Order   Function        Result
  5966. %@AS@%  
  5967. %@AS@%    First         0       j0( x )         0.009288
  5968. %@AS@%    First         1       j1( x )         0.522941
  5969. %@AS@%    First         2       jn( n, x )      0.428870
  5970. %@AS@%    First         3       jn( n, x )      0.195734
  5971. %@AS@%    First         4       jn( n, x )      0.063131
  5972. %@AS@%    Second        0       y0( x )         0.511681
  5973. %@AS@%    Second        1       y1( x )         0.094374
  5974. %@AS@%    Second        2       yn( n, x )      -0.432608
  5975. %@AS@%    Second        3       yn( n, x )      -0.819314
  5976. %@AS@%    Second        4       yn( n, x )      -1.626833%@AE@%%@NL@%
  5977. %@NL@%
  5978. %@NL@%
  5979. %@NL@%
  5980. %@NL@%
  5981. %@QR:_bfreeseg@%%@NL@%
  5982. %@2@%%@CR:C6A00200191 @%%@AB@%_bfreeseg%@AE@%%@EH@%%@NL@%
  5983. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  5984. %@NL@%
  5985. %@NL@%
  5986. %@3@%%@AB@%Description%@CR:C6A00200192 @% %@CR:C6A00200193 @%%@AE@%%@EH@%%@NL@%
  5987. %@NL@%
  5988. Frees a specified based heap.  %@NL@%
  5989. %@NL@%
  5990. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  5991.  
  5992. %@AS@%  int _bfreeseg( _segment seg );%@AE@%%@NL@%
  5993. %@NL@%
  5994. %@AI@%seg%@AE@%                               Segment selected
  5995.  
  5996. %@NL@%
  5997. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  5998. %@NL@%
  5999. The %@AB@%_bfreeseg%@AE@% function frees a based heap. The %@AI@%seg%@AE@% argument is a based heap
  6000. returned by an earlier call to %@AB@%_bheapseg%@AE@%. It specifies the based heap to be
  6001. freed.  %@NL@%
  6002. %@NL@%
  6003. The number of bytes freed is the number of bytes specified when the block
  6004. was allocated. After the call, the freed heap is again available for
  6005. allocation.  %@NL@%
  6006. %@NL@%
  6007. %@NL@%
  6008. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6009. %@NL@%
  6010. The %@AB@%_bfreeseg%@AE@% function returns 0 if successful and -1 in the case of an
  6011. error.  %@NL@%
  6012. %@NL@%
  6013. %@NL@%
  6014. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6015. %@NL@%
  6016.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  6017. %@NL@%
  6018. %@NL@%
  6019. %@NL@%
  6020. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  6021. %@NL@%
  6022. %@AB@%_bheapseg%@AE@%, %@AB@%calloc%@AE@% functions, %@AB@%free%@AE@% functions,%@AB@% malloc%@AE@% functions, %@AB@%realloc%@AE@%
  6023. functions  %@NL@%
  6024. %@NL@%
  6025. %@NL@%
  6026. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6027. %@NL@%
  6028. %@AS@%  /* BHEAPSEG.C: This program C illustrates dynamic allocation of based
  6029. %@AS@%   * memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree.
  6030. %@AS@%   */
  6031. %@AS@%  
  6032. %@AS@%  #include <stdio.h>
  6033. %@AS@%  #include <malloc.h>
  6034. %@AS@%  #include <stdlib.h>
  6035. %@AS@%  #include <string.h>
  6036. %@AS@%  
  6037. %@AS@%  void main()
  6038. %@AS@%  {
  6039. %@AS@%      _segment seg;
  6040. %@AS@%      char _based( seg ) *outstr, _based( seg ) *instr;
  6041. %@AS@%      char _based( seg ) *pout,   _based( seg ) *pin;
  6042. %@AS@%      char tmpstr[80];
  6043. %@AS@%      int  len;
  6044. %@AS@%  
  6045. %@AS@%      printf( "Enter a string: " );
  6046. %@AS@%      gets( tmpstr );
  6047. %@AS@%  
  6048. %@AS@%      /* Request a based heap. Use based so that memory won't be taken from
  6049. %@AS@%       * near heap.
  6050. %@AS@%       */
  6051. %@AS@%      if( (seg = _bheapseg( 1000 )) == _NULLSEG )
  6052. %@AS@%          exit( 1 );
  6053. %@AS@%  
  6054. %@AS@%      /* Allocate based memory for two strings. */
  6055. %@AS@%      len = strlen( tmpstr );
  6056. %@AS@%      if( ((instr  = _bmalloc( seg, len + 1 )) == _NULLOFF) ||
  6057. %@AS@%          ((outstr = _bmalloc( seg, len + 1 )) == _NULLOFF) )
  6058. %@AS@%          exit( 1 );
  6059. %@AS@%  
  6060. %@AS@%      /* Copy a lowercased string to dynamic memory. The based memory is
  6061. %@AS@%       * far when addressed as a whole.
  6062. %@AS@%       */
  6063. %@AS@%      _fstrlwr( _fstrcpy( (char _far *)instr, (char _far *)tmpstr ) );
  6064. %@AS@%  
  6065. %@AS@%      /* Copy input string to output string in reversed order. When reading
  6066. %@AS@%       * and writing individual characters from a based heap, the compiler
  6067. %@AS@%will
  6068. %@AS@%       * try to process them as near, thus speeding up the processing.
  6069. %@AS@%       */
  6070. %@AS@%      for( pin = instr + len - 1, pout = outstr;
  6071. %@AS@%                  pout < outstr + len; pin--, pout++ )
  6072. %@AS@%          *pout = *pin;
  6073. %@AS@%      *pout = '\0';
  6074. %@AS@%  
  6075. %@AS@%      /* Display strings. Again strings as a whole are far. */
  6076. %@AS@%      printf( "Input:  %Fs\n", (char _far *)instr );
  6077. %@AS@%      printf( "Output: %Fs\n", (char _far *)outstr );
  6078. %@AS@%  
  6079. %@AS@%      /* Free blocks and release based heap. */
  6080. %@AS@%      _bfree( seg, instr );
  6081. %@AS@%      _bfree( seg, outstr );
  6082. %@AS@%      _bfreeseg( seg );
  6083. %@AS@%  }%@AE@%%@NL@%
  6084. %@NL@%
  6085. %@NL@%
  6086. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6087. %@NL@%
  6088. %@AS@%  
  6089. %@AS@%  
  6090. %@AS@%  Enter a string: Was I god
  6091. %@AS@%  Input:  was i god
  6092. %@AS@%  Output: dog i saw%@AE@%%@NL@%
  6093. %@NL@%
  6094. %@NL@%
  6095. %@NL@%
  6096. %@NL@%
  6097. %@QR:_bheapseg@%%@NL@%
  6098. %@2@%%@CR:C6A00210194 @%%@AB@%_bheapseg%@AE@%%@EH@%%@NL@%
  6099. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6100. %@NL@%
  6101. %@NL@%
  6102. %@3@%%@AB@%Description%@CR:C6A00210195 @% %@CR:C6A00210196 @%%@AE@%%@EH@%%@NL@%
  6103. %@NL@%
  6104. Allocates a based heap.  %@NL@%
  6105. %@NL@%
  6106. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  6107.  
  6108. %@AS@%  _segment _bheapseg( size_t size );%@AE@%%@NL@%
  6109. %@NL@%
  6110. %@AI@%size%@AE@%                              Segment size to allocate
  6111.  
  6112. %@NL@%
  6113. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6114. %@NL@%
  6115. The %@AB@%_bheapseg%@AE@% function allocates a based-heap segment of at least %@AI@%size%@AE@%
  6116. bytes. (The block may be larger than %@AI@%size%@AE@% bytes because of space required
  6117. for alignment and for maintenance information.)  %@NL@%
  6118. %@NL@%
  6119. The heap code will try to enlarge the heap as necessary. If the original
  6120. block of memory is depleted (e.g., by calls to %@AB@%_bmalloc%@AE@% and %@AB@%_brealloc%@AE@%), the
  6121. run-time code will try to enlarge the heap as necessary.  %@NL@%
  6122. %@NL@%
  6123. The value returned by %@AB@%_bheapseg%@AE@% is the identifier of the based-heap segment.
  6124. This value should be saved and used in subsequent calls to other based-heap
  6125. functions.  %@NL@%
  6126. %@NL@%
  6127. The %@AB@%_bheapseg%@AE@% function can be called repeatedly. For each call, the C
  6128. library will allocate a new based-heap segment.  %@NL@%
  6129. %@NL@%
  6130. %@NL@%
  6131. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6132. %@NL@%
  6133. The %@AB@%_bheapseg%@AE@% function returns the newly allocated segment selector that the
  6134. user must save for use in subsequent based-heap functions. A return value of
  6135. -1 indicates failure.  %@NL@%
  6136. %@NL@%
  6137. Always check the return from the %@AB@%_bheapseg%@AE@% function (especially when it is
  6138. used in real mode), even if the amount of memory requested is small.  %@NL@%
  6139. %@NL@%
  6140. %@NL@%
  6141. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6142. %@NL@%
  6143.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  6144. %@NL@%
  6145. %@NL@%
  6146. %@NL@%
  6147. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  6148. %@NL@%
  6149. %@AB@%calloc%@AE@% functions, %@AB@%free%@AE@% functions, %@AB@%malloc%@AE@% functions, %@AB@%realloc%@AE@% functions  %@NL@%
  6150. %@NL@%
  6151. %@NL@%
  6152. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6153. %@NL@%
  6154. %@AS@%  /* BHEAPSEG.C: This program C illustrates dynamic allocation of based
  6155. %@AS@%   * memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree.
  6156. %@AS@%   */
  6157. %@AS@%  
  6158. %@AS@%  #include <stdio.h>
  6159. %@AS@%  #include <malloc.h>
  6160. %@AS@%  #include <stdlib.h>
  6161. %@AS@%  #include <string.h>%@AE@%%@NL@%
  6162. %@NL@%
  6163. %@AS@%  void main()
  6164. %@AS@%  {
  6165. %@AS@%      _segment seg;
  6166. %@AS@%      char _based( seg ) *outstr, _based( seg ) *instr;
  6167. %@AS@%      char _based( seg ) *pout,   _based( seg ) *pin;
  6168. %@AS@%      char tmpstr[80];
  6169. %@AS@%      int  len;
  6170. %@AS@%  
  6171. %@AS@%      printf( "Enter a string: " );
  6172. %@AS@%      gets( tmpstr );
  6173. %@AS@%  
  6174. %@AS@%      /* Request a based heap. Use based so that memory won't be taken from
  6175. %@AS@%       * near heap.
  6176. %@AS@%       */
  6177. %@AS@%      if( (seg = _bheapseg( 1000 )) == _NULLSEG )
  6178. %@AS@%          exit( 1 );
  6179. %@AS@%  
  6180. %@AS@%      /* Allocate based memory for two strings. */
  6181. %@AS@%      len = strlen( tmpstr );
  6182. %@AS@%      if( ((instr  = _bmalloc( seg, len + 1 )) == _NULLOFF) ||
  6183. %@AS@%          ((outstr = _bmalloc( seg, len + 1 )) == _NULLOFF) )
  6184. %@AS@%          exit( 1 );
  6185. %@AS@%  
  6186. %@AS@%      /* Copy a lowercased string to dynamic memory. The based memory is
  6187. %@AS@%       * far when addressed as a whole.
  6188. %@AS@%       */
  6189. %@AS@%      _fstrlwr( _fstrcpy( (char _far *)instr, (char _far *)tmpstr ) );
  6190. %@AS@%  
  6191. %@AS@%      /* Copy input string to output string in reversed order. When reading
  6192. %@AS@%       * and writing individual characters from a based heap, the compiler
  6193. %@AS@%will
  6194. %@AS@%       * try to process them as near, thus speeding up the processing.
  6195. %@AS@%       */
  6196. %@AS@%      for( pin = instr + len - 1, pout = outstr;
  6197. %@AS@%                  pout < outstr + len; pin--, pout++ )
  6198. %@AS@%          *pout = *pin;
  6199. %@AS@%      *pout = '\0';
  6200. %@AS@%  
  6201. %@AS@%      /* Display strings. Again, strings as a whole are far. */
  6202. %@AS@%      printf( "Input:  %Fs\n", (char _far *)instr );
  6203. %@AS@%      printf( "Output: %Fs\n", (char _far *)outstr );
  6204. %@AS@%  
  6205. %@AS@%      /* Free blocks and release based heap. */
  6206. %@AS@%      _bfree( seg, instr );
  6207. %@AS@%      _bfree( seg, outstr );
  6208. %@AS@%      _bfreeseg( seg );
  6209. %@AS@%  }%@AE@%%@NL@%
  6210. %@NL@%
  6211. %@NL@%
  6212. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6213. %@NL@%
  6214. %@AS@%  
  6215. %@AS@%  
  6216. %@AS@%  Enter a string: Was I god
  6217. %@AS@%  Input:  was i god
  6218. %@AS@%  Output: dog i saw%@AE@%%@NL@%
  6219. %@NL@%
  6220. %@NL@%
  6221. %@NL@%
  6222. %@NL@%
  6223. %@QR:_bios_disk@%%@NL@%
  6224. %@2@%%@CR:C6A00220197 @%%@AB@%_bios_disk%@AE@%%@EH@%%@NL@%
  6225. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6226. %@NL@%
  6227. %@NL@%
  6228. %@3@%%@AB@%Description%@CR:C6A00220198 @% %@CR:C6A00220199 @%%@AE@%%@EH@%%@NL@%
  6229. %@NL@%
  6230. Calls BIOS disk services using system call INT 0x13.  %@NL@%
  6231. %@NL@%
  6232. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  6233. %@NL@%
  6234. %@AS@%  unsigned _bios_disk( unsigned service, struct diskinfo_t  *diskinfo );%@AE@%%@NL@%
  6235. %@NL@%
  6236. %@AI@%service%@AE@%                           Disk function desired
  6237.  
  6238. %@AI@%diskinfo%@AE@%                          Disk parameters
  6239.  
  6240. %@NL@%
  6241. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6242. %@NL@%
  6243. The %@AB@%_bios_disk%@AE@% routine uses system call INT 0x13 to provide several
  6244. disk-access functions. The %@AI@%service%@AE@% parameter selects the function desired,
  6245. while the %@AI@%diskinfo%@AE@% structure provides the necessary parameters. Note that
  6246. the low-level disk operations allowed by the %@AB@%_bios_disk%@AE@% routine are very
  6247. dangerous to use because they allow direct manipulation of the disk.  %@NL@%
  6248. %@NL@%
  6249. The %@AI@%diskinfo%@AE@% structure provides the following parameters:  %@NL@%
  6250. %@NL@%
  6251. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  6252. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6253. %@AB@%unsigned drive%@AE@%                    Drive number
  6254.  
  6255. %@AB@%unsigned head%@AE@%                     Head number
  6256.  
  6257. %@AB@%unsigned track%@AE@%                    Track number
  6258.  
  6259. %@AB@%unsigned sector%@AE@%                   Starting sector number
  6260.  
  6261. %@AB@%unsigned nsectors%@AE@%                 Number of sectors to read, write, or 
  6262.                                   compare
  6263.  
  6264. %@AB@%void far *buffer%@AE@%                  Memory location to write to, read from, 
  6265.                                   or compare
  6266.  
  6267. The %@AI@%service%@AE@% argument can be set to one of the following manifest constants:
  6268. %@NL@%
  6269. %@NL@%
  6270. %@AB@%Constant%@AE@%                          %@AB@%Function%@AE@%
  6271. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6272. %@AB@%_DISK_FORMAT%@AE@%                      Formats the track specified by %@AI@%diskinfo%@AE@%.
  6273.                                   The %@AI@%head%@AE@% and %@AI@%track%@AE@% fields indicate the 
  6274.                                   track to format. Only one track can be 
  6275.                                   formatted in a single call. The %@AI@%buffer%@AE@% 
  6276.                                   field points to a set of sector markers.
  6277.                                   The format of the markers depends on the
  6278.                                   type of disk drive; see a technical 
  6279.                                   reference to the PC BIOS to determine 
  6280.                                   the marker format. There is no return 
  6281.                                   value.
  6282.  
  6283. %@AB@%_DISK_READ%@AE@%                        Reads one or more disk sectors into 
  6284.                                   memory. This service uses all fields of 
  6285.                                   the structure pointed to by %@AI@%diskinfo%@AE@%, as
  6286.                                   defined earlier in this section. If no 
  6287.                                   error occurs, the function returns 0 in 
  6288.                                   the high-order byte and the number of 
  6289.                                   sectors read in the low-order byte. If 
  6290.                                   there is an error, the high-order byte 
  6291.                                   will contain a set of status flags. If 
  6292.                                   there is an error, the high-order byte 
  6293.                                   will contain a set of status flags, as 
  6294.                                   defined under %@AB@%_DISK_READ%@AE@%. Status is 
  6295.                                   returned in the 8 high-order bits of the
  6296.                                   return value, as listed below: 
  6297.  
  6298.                                   %@AB@%Bits%@AE@%          %@AB@%Meaning%@AE@%
  6299. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6300.                                   0x01**        Invalid request or a bad 
  6301.                                   command
  6302.  
  6303.                                   0x02**        Address mark not found
  6304.  
  6305.                                   0x04**        Sector not found
  6306.  
  6307.                                   0x05**        Reset failed
  6308.  
  6309.                                   0x07**        Drive parameter activity 
  6310.                                   failed
  6311.  
  6312.                                   0x09**        Direct Memory Access (DMA)
  6313.                                   overrun
  6314.  
  6315.                                   0x0A**        Bad sector flag detected
  6316.  
  6317.                                   0x10**        Data read (ECC) error
  6318.  
  6319.                                   0x11**        Corrected data read (ECC) 
  6320.                                   error
  6321.  
  6322.                                   0x20**        Controller failure
  6323.  
  6324.                                   0x40**        Seek error
  6325.  
  6326.                                   0x80**        Disk timed out or failed 
  6327.                                   to respond
  6328.  
  6329.                                   0xAA**        Drive not ready
  6330.  
  6331.                                   0xBB**        Undefined error
  6332.  
  6333.                                   0xCC**        Write fault on drive
  6334.  
  6335.                                   0xE0**        Status error
  6336.  
  6337. %@AB@%_DISK_RESET%@AE@%                       Forces the disk controller to do a hard 
  6338.                                   reset, preparing for floppy-disk I/O. 
  6339.                                   This is useful after an error occurs in 
  6340.                                   another operation, such as a read. If 
  6341.                                   this service is specified, the%@AI@%%@AE@%
  6342.                                   %@AI@%diskinfo%@AE@% argument is ignored.
  6343.  
  6344. %@AB@%_DISK_STATUS%@AE@%                      Obtains the status of the last disk 
  6345.                                   operation. If this service is specified,
  6346.                                   the %@AI@%diskinfo%@AE@% argument is ignored. 
  6347.  
  6348. %@AB@%_DISK_VERIFY%@AE@%                      Checks the disk to be sure the specified
  6349.                                   sectors exist and can be read. It also 
  6350.                                   runs a CRC (cyclic redundancy check) 
  6351.                                   test. This service uses all fields 
  6352.                                   (except %@AI@%buffer%@AE@%) of the structure pointed
  6353.                                   to by %@AI@%diskinfo%@AE@%, as defined earlier in 
  6354.                                   this section. If no error occurs, the 
  6355.                                   function returns 0 in the high-order 
  6356.                                   byte and the number of sectors compared 
  6357.                                   in the low-order byte. If there is an 
  6358.                                   error, the high-order byte will contain 
  6359.                                   a set of status flags, as defined under %@AB@%%@AE@%
  6360.                                   %@AB@%_DISK_READ%@AE@% (above).
  6361.  
  6362. %@AB@%_DISK_WRITE%@AE@%                       Writes data from memory to one or more 
  6363.                                   disk sectors. This service uses all 
  6364.                                   fields of the structure pointed to by %@AI@%%@AE@%
  6365.                                   %@AI@%diskinfo%@AE@%, as defined earlier in this 
  6366.                                   section. If no error occurs, the 
  6367.                                   function returns 0 in the high-order 
  6368.                                   byte and the number of sectors written 
  6369.                                   in the low-order byte. If there is an 
  6370.                                   error, the high-order byte will contain 
  6371.                                   a set of status flags, as defined under %@AB@%%@AE@%
  6372.                                   %@AB@%_DISK_READ%@AE@% (above).
  6373.  
  6374. %@NL@%
  6375. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6376. %@NL@%
  6377. The %@AB@%_bios_disk%@AE@% function returns the value in the AX register after the BIOS
  6378. interrupt.  %@NL@%
  6379. %@NL@%
  6380. %@NL@%
  6381. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6382. %@NL@%
  6383.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  6384. %@NL@%
  6385. %@NL@%
  6386. %@NL@%
  6387. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6388. %@NL@%
  6389. %@AS@%  /* BDISK.C: This program first attempts to verify a disk by using an
  6390. %@AS@%   * invalid disk head number. After printing the return value error code,
  6391. %@AS@%   * the program verifies the disk by using a valid disk head code.
  6392. %@AS@%   */
  6393. %@AS@%  
  6394. %@AS@%  #include <conio.h>
  6395. %@AS@%  #include <stdio.h>
  6396. %@AS@%  #include <bios.h>
  6397. %@AS@%  
  6398. %@AS@%  void main()
  6399. %@AS@%  {
  6400. %@AS@%     unsigned status = 0;
  6401. %@AS@%     struct diskinfo_t disk_info;
  6402. %@AS@%  
  6403. %@AS@%     disk_info.drive    = 0;
  6404. %@AS@%     disk_info.head     = 10;   /* Invalid head number */
  6405. %@AS@%     disk_info.track    = 1;
  6406. %@AS@%     disk_info.sector   = 2;
  6407. %@AS@%     disk_info.nsectors = 8;%@AE@%%@NL@%
  6408. %@NL@%
  6409. %@AS@%  printf( "Insert disk in drive A: and press any key\n" );
  6410. %@AS@%     getch();
  6411. %@AS@%     status = _bios_disk( _DISK_VERIFY, &disk_info );
  6412. %@AS@%     printf( "Return value: 0x%.4x\n", status );
  6413. %@AS@%     if( status & 0xff00 )      /* Error if high byte is 0 */
  6414. %@AS@%        printf( "Seek error\n" );
  6415. %@AS@%     else
  6416. %@AS@%        printf( "No seek error\n" );
  6417. %@AS@%  
  6418. %@AS@%     printf( "Press any key\n" );
  6419. %@AS@%     getch();
  6420. %@AS@%     disk_info.head = 0;        /* Valid head number */
  6421. %@AS@%     status = _bios_disk( _DISK_VERIFY, &disk_info );
  6422. %@AS@%     printf( "Return value: 0x%.4x\n", status );
  6423. %@AS@%     if( status & 0xff00 )      /* Error if high byte is 0 */
  6424. %@AS@%        printf( "Seek error\n" );
  6425. %@AS@%     else
  6426. %@AS@%        printf( "No seek error\n" );
  6427. %@AS@%  }%@AE@%%@NL@%
  6428. %@NL@%
  6429. %@NL@%
  6430. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6431. %@NL@%
  6432. %@AS@%  
  6433. %@AS@%  
  6434. %@AS@%  Insert disk in drive A: and press any key
  6435. %@AS@%  Return value: 0x0400
  6436. %@AS@%  Seek error
  6437. %@AS@%  Press any key
  6438. %@AS@%  Return value: 0x0008
  6439. %@AS@%  No seek error %@AE@%%@NL@%
  6440. %@NL@%
  6441. %@NL@%
  6442. %@NL@%
  6443. %@NL@%
  6444. %@QR:_bios_equiplist@%%@NL@%
  6445. %@2@%%@CR:C6A00230200 @%%@AB@%_bios_equiplist%@AE@%%@EH@%%@NL@%
  6446. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6447. %@NL@%
  6448. %@NL@%
  6449. %@3@%%@AB@%Description%@CR:C6A00230201 @% %@CR:C6A00230202 @%%@AE@%%@EH@%%@NL@%
  6450. %@NL@%
  6451. Calls BIOS equipment-list service, using system call INT 0x11.  %@NL@%
  6452. %@NL@%
  6453. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  6454. %@NL@%
  6455. %@AS@%  unsigned _bios_equiplist( void );%@AE@%%@NL@%
  6456. %@NL@%
  6457. %@NL@%
  6458. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6459. %@NL@%
  6460. The %@AB@%_bios_equiplist%@AE@% routine uses system call INT 0x11 to determine what
  6461. hardware and peripherals are currently installed on the machine.  %@NL@%
  6462. %@NL@%
  6463. %@NL@%
  6464. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6465. %@NL@%
  6466. The function returns a set of bits indicating what is installed, as defined
  6467. below:  %@NL@%
  6468. %@NL@%
  6469. %@AB@%Bits%@AE@%                              %@AB@%Meaning%@AE@%
  6470. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6471. 0                                 Any disk drive installed if true
  6472.  
  6473. 1                                 True (1) if math coprocessor installed
  6474.  
  6475. 2 -3                              System RAM in 16K blocks (16-64K)
  6476.  
  6477. 4 -5                              Initial video mode
  6478.  
  6479. 6 -7                              Number of floppy-disk drives installed 
  6480.                                   (00 = 1,  01 = 2, etc.)
  6481.  
  6482. 8                                 False (0) if and only if a Direct Memory
  6483.                                   Access (DMA) chip is installed
  6484.  
  6485. 9 -11                             Number of RS232 serial ports installed
  6486.  
  6487. 12                                True (1) if and only if a game adapter 
  6488.                                   is installed
  6489.  
  6490. 13                                True (1) if and only if an internal 
  6491.                                   modem is installed
  6492.  
  6493. 14 -15                            Number of printers installed
  6494.  
  6495. %@NL@%
  6496. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6497. %@NL@%
  6498.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  6499. %@NL@%
  6500. %@NL@%
  6501. %@NL@%
  6502. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6503. %@NL@%
  6504. %@AS@%  /* BEQUIPLI.C: This program checks for the presence of diskettes. */
  6505. %@AS@%  
  6506. %@AS@%  #include <bios.h>
  6507. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  6508. %@NL@%
  6509. %@AS@%  void main()
  6510. %@AS@%  {
  6511. %@AS@%     unsigned equipment;
  6512. %@AS@%  
  6513. %@AS@%     equipment = _bios_equiplist();
  6514. %@AS@%     printf( "Equipment bits: 0x%.4x\n", equipment );
  6515. %@AS@%     if( equipment & 0x1000 )      /* Check for game adapter bit */
  6516. %@AS@%        printf( "Game adapter installed\n" );
  6517. %@AS@%     else
  6518. %@AS@%        printf( "No game adapter installed\n" );
  6519. %@AS@%  }%@AE@%%@NL@%
  6520. %@NL@%
  6521. %@NL@%
  6522. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6523. %@NL@%
  6524. %@AS@%  
  6525. %@AS@%  
  6526. %@AS@%  Equipment bits: 0x4061
  6527. %@AS@%  No game adapter installed%@AE@%%@NL@%
  6528. %@NL@%
  6529. %@NL@%
  6530. %@NL@%
  6531. %@NL@%
  6532. %@QR:_bios_keybrd@%%@NL@%
  6533. %@2@%%@CR:C6A00240203 @%%@AB@%_bios_keybrd%@AE@%%@EH@%%@NL@%
  6534. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6535. %@NL@%
  6536. %@NL@%
  6537. %@3@%%@AB@%Description%@CR:C6A00240204 @% %@CR:C6A00240205 @%%@AE@%%@EH@%%@NL@%
  6538. %@NL@%
  6539. Calls BIOS keyboard services, using INT 0x16.  %@NL@%
  6540. %@NL@%
  6541. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  6542. %@NL@%
  6543. %@AS@%  unsigned _bios_keybrd( unsigned service );%@AE@%%@NL@%
  6544. %@NL@%
  6545. %@AI@%service%@AE@%                           Keyboard function desired
  6546.  
  6547. %@NL@%
  6548. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6549. %@NL@%
  6550. The %@AB@%_bios_keybrd%@AE@% routine uses system call INT 0x16 to access the keyboard
  6551. services. The %@AI@%service%@AE@% argument can be any of the following manifest
  6552. constants:  %@NL@%
  6553. %@NL@%
  6554. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  6555. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6556. %@AB@%_KEYBRD_READ%@AE@%,%@AB@%%@AE@%                     Reads the next character from the 
  6557. %@AB@%_NKEYBRD_READ%@AE@%                     keyboard. If no character has been 
  6558.                                   typed, the call will wait for one. If 
  6559.                                   the low-order byte of the return value 
  6560.                                   is nonzero, the call contains the ASCII 
  6561.                                   value of the character typed. The 
  6562.                                   high-order byte contains the keyboard 
  6563.                                   scan code for the character. The %@AB@%%@AE@%
  6564.                                   %@AB@%_NKEYBRD_READ%@AE@% constant is used with 
  6565.                                   enhanced keyboards to obtain the scan 
  6566.                                   codes for function keys F11 and F12 and 
  6567.                                   the cursor control keys. 
  6568.  
  6569. %@AB@%_KEYBRD_READY%@AE@%,%@AB@%%@AE@%                    Checks whether a keystroke is waiting to
  6570. %@AB@%_NKEYBRD_READY%@AE@%                    be read and, if so, reads it. The return
  6571.                                   value is 0 if no keystroke is waiting, 
  6572.                                   or it is the character waiting to be 
  6573.                                   read, in the same format as the %@AB@%%@AE@%
  6574.                                   %@AB@%_KEYBRD_READ%@AE@% or  %@AB@%_NKEYBRD_READY%@AE@% return. 
  6575.                                   This service does not remove the waiting
  6576.                                   character from the input buffer, as does
  6577.                                   the%@AB@% _KEYBRD_READ%@AE@% or %@AB@%_NKEYBRD_READ%@AE@% 
  6578.                                   service.  The %@AB@%_NKEYBRD_READY%@AE@% constant is
  6579.                                   used with enhanced keyboards to obtain 
  6580.                                   the scan codes for function keys F11 and
  6581.                                   F12 and the cursor control keys.
  6582.  
  6583. %@AB@%_KEYBRD_SHIFTSTATUS%@AE@%, %@AB@%%@AE@%             Returns the current SHIFT-key status. 
  6584. %@AB@%_NKEYBRD_SHIFTSTATUS%@AE@%              Only the low-order byte of the return 
  6585.                                   value is affected. The %@AB@%%@AE@%
  6586.                                   %@AB@%_NKEYBRD_SHIFTSTATUS%@AE@% constant is used to
  6587.                                   get a full 16-bit status value. Any 
  6588.                                   combination of the following bits may be
  6589.                                   set:
  6590.  
  6591.                                   %@AB@%Bit%@AE@%         %@AB@%Meaning%@AE@% %@AB@%if%@AE@% %@AB@%True%@AE@%
  6592. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6593.                                   00H         Rightmost SHIFT key pressed
  6594.  
  6595.                                   01H         Leftmost SHIFT key pressed
  6596.  
  6597.                                   02H         Either CTRL key pressed
  6598.  
  6599.                                   3H          Either ALT key pressed
  6600.  
  6601.                                   04H         SCROLL LOCK on
  6602.  
  6603.                                   05H         NUM LOCK on
  6604.  
  6605.                                   06H         CAPS LOCK on
  6606.  
  6607.                                   07H         In insert mode (INS)
  6608.  
  6609.                                   08H         Left CTRL key pressed
  6610.  
  6611.                                   09H         Left ALT key pressed
  6612.  
  6613.                                   0AH         Right CTRL key pressed
  6614.  
  6615.                                   0BH         Right ALT key pressed
  6616.  
  6617.                                   0CH         SCROLL LOCK key pressed
  6618.  
  6619.                                   0DH         NUM LOCK key pressed
  6620.  
  6621.                                   0EH         CAPS LOCK key pressed
  6622.  
  6623.                                   0FH         SYS REQ key pressed
  6624.  
  6625. %@NL@%
  6626. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6627. %@NL@%
  6628. With the %@AB@%...READ%@AE@% and %@AB@%...SHIFTSTATUS%@AE@% arguments, the %@AB@%_bios_keybrd%@AE@% function
  6629. returns the contents of the AX register after the BIOS call.  %@NL@%
  6630. %@NL@%
  6631. With the %@AB@%...READY%@AE@% argument, %@AB@%_bios_keybrd%@AE@% returns 0 if there is no key. If
  6632. there is a key, %@AB@%_bios_keybrd%@AE@% returns the key waiting to be read (i.e. the
  6633. same value as %@AB@%_KEYBRD_READ%@AE@%).  %@NL@%
  6634. %@NL@%
  6635. With the %@AB@%...READ%@AE@% and the %@AB@%...READY%@AE@% arguments, the %@AB@%_bios_keybrd%@AE@% function
  6636. returns -1 if CTRL+BREAK has been pressed and is the next keystroke to be
  6637. read.  %@NL@%
  6638. %@NL@%
  6639. %@NL@%
  6640. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6641. %@NL@%
  6642.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  6643. %@NL@%
  6644. %@NL@%
  6645. %@NL@%
  6646. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6647. %@NL@%
  6648. %@AS@%  /* BKEYBRD.C: This program prints a message on the screen until the
  6649. %@AS@%   * right SHIFT key is pressed.
  6650. %@AS@%   */
  6651. %@AS@%  
  6652. %@AS@%  #include <bios.h>
  6653. %@AS@%  #include <stdio.h>
  6654. %@AS@%  
  6655. %@AS@%  void main()
  6656. %@AS@%  {
  6657. %@AS@%     while( !(_bios_keybrd( _KEYBRD_SHIFTSTATUS ) & 0001) )
  6658. %@AS@%        printf( "Use the right SHIFT key to stop this message\n" );
  6659. %@AS@%     printf( "Right SHIFT key pressed\n" );
  6660. %@AS@%  }%@AE@%%@NL@%
  6661. %@NL@%
  6662. %@NL@%
  6663. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6664. %@NL@%
  6665. %@AS@%  
  6666. %@AS@%  
  6667. %@AS@%  Use the right SHIFT key to stop this message
  6668. %@AS@%  Use the right SHIFT key to stop this message
  6669. %@AS@%  Use the right SHIFT key to stop this message
  6670. %@AS@%  Use the right SHIFT key to stop this message
  6671. %@AS@%  Right SHIFT key pressed%@AE@%%@NL@%
  6672. %@NL@%
  6673. %@NL@%
  6674. %@NL@%
  6675. %@NL@%
  6676. %@QR:_bios_memsize@%%@NL@%
  6677. %@2@%%@CR:C6A00250206 @%%@AB@%_bios_memsize%@AE@%%@EH@%%@NL@%
  6678. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6679. %@NL@%
  6680. %@NL@%
  6681. %@3@%%@AB@%Description%@CR:C6A00250207 @% %@CR:C6A00250208 @%%@AE@%%@EH@%%@NL@%
  6682. %@NL@%
  6683. Calls the BIOS memory-size service, using system call INT 0x12.  %@NL@%
  6684. %@NL@%
  6685. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  6686. %@NL@%
  6687. %@AS@%  unsigned _bios_memsize( void );%@AE@%%@NL@%
  6688. %@NL@%
  6689. %@NL@%
  6690. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6691. %@NL@%
  6692. The %@AB@%_bios_memsize%@AE@% routine uses system call INT 0x12 to determine the total
  6693. amount of main memory installed.  %@NL@%
  6694. %@NL@%
  6695. %@NL@%
  6696. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6697. %@NL@%
  6698. The routine returns the total amount of installed memory in 1K blocks. The
  6699. maximum return value is 640, representing 640K of main memory.  %@NL@%
  6700. %@NL@%
  6701. %@NL@%
  6702. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6703. %@NL@%
  6704.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  6705. %@NL@%
  6706. %@NL@%
  6707. %@NL@%
  6708. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6709. %@NL@%
  6710. %@AS@%  /* BMEMSIZE.C: This program displays the amount of memory installed. */
  6711. %@AS@%  
  6712. %@AS@%  #include <bios.h>
  6713. %@AS@%  #include <stdio.h>
  6714. %@AS@%  
  6715. %@AS@%  void main()
  6716. %@AS@%  {
  6717. %@AS@%     unsigned memory;
  6718. %@AS@%  
  6719. %@AS@%     memory = _bios_memsize();
  6720. %@AS@%     printf ( "The amount of memory installed is: %dK\n", memory );
  6721. %@AS@%  }%@AE@%%@NL@%
  6722. %@NL@%
  6723. %@NL@%
  6724. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6725. %@NL@%
  6726. %@AS@%  
  6727. %@AS@%  
  6728. %@AS@%  The amount of memory installed is: 639K%@AE@%%@NL@%
  6729. %@NL@%
  6730. %@NL@%
  6731. %@NL@%
  6732. %@NL@%
  6733. %@QR:_bios_printer@%%@NL@%
  6734. %@2@%%@CR:C6A00260209 @%%@AB@%_bios_printer%@AE@%%@EH@%%@NL@%
  6735. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6736. %@NL@%
  6737. %@NL@%
  6738. %@3@%%@AB@%Description%@CR:C6A00260210 @% %@CR:C6A00260211 @%%@AE@%%@EH@%%@NL@%
  6739. %@NL@%
  6740. Calls BIOS printer services using system call INT 0x17.  %@NL@%
  6741. %@NL@%
  6742. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  6743. %@NL@%
  6744. %@AS@%  unsigned _bios_printer( unsigned service, unsigned printer, unsigned data
  6745. %@AS@%  );%@AE@%%@NL@%
  6746. %@NL@%
  6747. %@AI@%service%@AE@%                           Printer function desired
  6748.  
  6749. %@AI@%printer%@AE@%                           Target printer port
  6750.  
  6751. %@AI@%data%@AE@%                              Output data
  6752.  
  6753. %@NL@%
  6754. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6755. %@NL@%
  6756. The %@AB@%_bios_printer%@AE@% routine uses system call INT 0x17 to perform printer
  6757. output services for parallel printers. The %@AI@%printer%@AE@% argument specifies the
  6758. affected printer, where 0 is LPT1, 1 is LPT2, and so forth.  %@NL@%
  6759. %@NL@%
  6760. Some printers do not support the full set of signals. As a result, the "Out
  6761. of Paper" condition, for example, may not be returned to your program.  %@NL@%
  6762. %@NL@%
  6763. The %@AI@%service%@AE@% argument can be any of the following manifest constants:  %@NL@%
  6764. %@NL@%
  6765. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  6766. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6767. %@AB@%_PRINTER_INIT%@AE@%                     Initializes the selected printer. The %@AI@%%@AE@%
  6768.                                   %@AI@%data%@AE@% argument is ignored. The return 
  6769.                                   value is the low-order status byte 
  6770.                                   defined below.
  6771.  
  6772. %@AB@%_PRINTER_STATUS%@AE@%                   Returns the printer status in the 
  6773.                                   low-order status byte defined below. The%@AI@%%@AE@%
  6774.                                   %@AI@%data%@AE@% argument is ignored.
  6775.  
  6776. %@AB@%_PRINTER_WRITE%@AE@%                    Sends the low-order byte of %@AI@%data%@AE@% to the 
  6777.                                   printer specified by %@AI@%printer%@AE@%. The 
  6778.                                   low-order byte of the return value 
  6779.                                   indicates the printer status after the 
  6780.                                   operation, as defined below:%@AI@%%@AE@%
  6781.  
  6782.                                   %@AB@%Bit%@AE@%      %@AB@%Meaning%@AE@% %@AB@%if%@AE@% %@AB@%True%@AE@%
  6783. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6784.                                   0         Printer timed out
  6785.  
  6786.                                   1         Not used
  6787.  
  6788.                                   2         Not used
  6789.  
  6790.                                   3         I/O error
  6791.  
  6792.                                   4         Printer selected
  6793.  
  6794.                                   5         Out of paper
  6795.  
  6796.                                   6         Acknowledge
  6797.  
  6798.                                   7         Printer not busy
  6799.  
  6800. %@AB@%%@AE@%
  6801.  
  6802. %@NL@%
  6803. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6804. %@NL@%
  6805. The %@AB@%_bios_printer%@AE@% function returns the value in the AX register after the
  6806. BIOS interrupt.  %@NL@%
  6807. %@NL@%
  6808. %@NL@%
  6809. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  6810. %@NL@%
  6811.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  6812. %@NL@%
  6813. %@NL@%
  6814. %@NL@%
  6815. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  6816. %@NL@%
  6817. %@AS@%  /* BPRINTER.C: This program checks the status of the printer attached to
  6818. %@AS@%   * LPT1 when it is off line, then initializes the printer.
  6819. %@AS@%   */
  6820. %@AS@%  
  6821. %@AS@%  #include <bios.h>
  6822. %@AS@%  #include <conio.h>
  6823. %@AS@%  #include <stdio.h>
  6824. %@AS@%  
  6825. %@AS@%  #define LPT1 0
  6826. %@AS@%  
  6827. %@AS@%  void main()
  6828. %@AS@%  {
  6829. %@AS@%     unsigned status;
  6830. %@AS@%  
  6831. %@AS@%     printf ( "Place printer off line and press any key\n" );
  6832. %@AS@%     getch();
  6833. %@AS@%  
  6834. %@AS@%     status = _bios_printer( _PRINTER_STATUS, LPT1, 0 );
  6835. %@AS@%     printf( "Status with printer off line: 0x%.4x\n\n", status );
  6836. %@AS@%     printf( "Put the printer on line and then\n" );
  6837. %@AS@%     printf( "Press any key to initialize printer\n" );
  6838. %@AS@%     getch();
  6839. %@AS@%  
  6840. %@AS@%     status = _bios_printer( _PRINTER_INIT, LPT1, 0 );
  6841. %@AS@%     printf( "Status after printer initialized: 0x%.4x\n", status );
  6842. %@AS@%  }%@AE@%%@NL@%
  6843. %@NL@%
  6844. %@NL@%
  6845. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  6846. %@NL@%
  6847. %@AS@%  
  6848. %@AS@%  
  6849. %@AS@%  Place printer off line and press any key
  6850. %@AS@%  Status with printer off line: 0x0018
  6851. %@AS@%  
  6852. %@AS@%  Put the printer on line and then
  6853. %@AS@%  Press any key to initialize printer
  6854. %@AS@%  Status after printer initialized: 0x0090%@AE@%%@NL@%
  6855. %@NL@%
  6856. %@NL@%
  6857. %@NL@%
  6858. %@NL@%
  6859. %@QR:_bios_serialcom@%%@NL@%
  6860. %@2@%%@CR:C6A00270212 @%%@AB@%_bios_serialcom%@AE@%%@EH@%%@NL@%
  6861. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6862. %@NL@%
  6863. %@NL@%
  6864. %@3@%%@AB@%Description%@CR:C6A00270213 @% %@CR:C6A00270214 @%%@AE@%%@EH@%%@NL@%
  6865. %@NL@%
  6866. Calls BIOS communications services, using system call INT 0x14.  %@NL@%
  6867. %@NL@%
  6868. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  6869. %@NL@%
  6870. %@AS@%  unsigned _bios_serialcom( unsigned service, unsigned serial_port, unsigned
  6871. %@AS@%  data );%@AE@%%@NL@%
  6872. %@NL@%
  6873. %@AI@%service%@AE@%                           Communications service
  6874.  
  6875. %@AI@%serial_port%@AE@%                       Serial port to use
  6876.  
  6877. %@AI@%data%@AE@%                              Port configuration bits
  6878.  
  6879. %@NL@%
  6880. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  6881. %@NL@%
  6882. The %@AB@%_bios_serialcom%@AE@% routine uses system call INT 0x14 to provide serial
  6883. communications services. The %@AI@%serial_port%@AE@% argument is set to 0 for COM1, to 1
  6884. for COM2, and so on.  %@NL@%
  6885. %@NL@%
  6886. The %@AB@%_bios_serialcom%@AE@% routine may not be able to establish reliable
  6887. communications at baud rates in excess of 1,200 baud ( %@AB@%_COM_1200%@AE@%) due to the
  6888. overhead associated with servicing computer interrupts. Faster data
  6889. communication rates are possible with more direct programming of serial-port
  6890. controllers. See %@AI@%C Programmer's Guide to Serial Communications%@AE@% for more
  6891. details on serial-communications programming in C.  %@NL@%
  6892. %@NL@%
  6893. The %@AI@%service%@AE@% argument can be set to one of the following manifest constants:
  6894. %@NL@%
  6895. %@NL@%
  6896. %@AB@%Constant%@AE@%                          %@AB@%Service%@AE@%
  6897. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6898. %@AB@%_COM_INIT%@AE@%                         Sets the port to the parameters 
  6899.                                   specified in the %@AI@%data%@AE@% argument
  6900.  
  6901. %@AB@%_COM_SEND%@AE@%                         Transmits the %@AI@%data%@AE@% characters over the 
  6902.                                   selected serial port
  6903.  
  6904. %@AB@%_COM_RECEIVE%@AE@%                      Accepts an input character from the 
  6905.                                   selected serial port
  6906.  
  6907. %@AB@%_COM_STATUS%@AE@%                       Returns the current status of the 
  6908.                                   selected serial port
  6909.  
  6910. The %@AI@%data%@AE@% argument is ignored if %@AI@%service%@AE@% is set to %@AB@%_COM_RECEIVE%@AE@% or
  6911. %@AB@%_COM_STATUS.%@AE@% The %@AI@%data%@AE@% argument for %@AB@%_COM_INIT%@AE@% is created by combining (with
  6912. the OR operator) one or more of the following constants:  %@NL@%
  6913. %@NL@%
  6914. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  6915. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6916. %@AB@%_COM_CHR7 %@AE@%                        7 data bits
  6917.  
  6918. %@AB@%_COM_CHR8%@AE@%                         8 data bits
  6919.  
  6920. %@AB@%_COM_STOP1%@AE@%                        1 stop bit
  6921.  
  6922. %@AB@%_COM_STOP2%@AE@%                        2 stop bits
  6923.  
  6924. %@AB@%_COM_NOPARITY%@AE@%                     No parity
  6925.  
  6926. %@AB@%_COM_EVENPARITY%@AE@%                   Even parity
  6927.  
  6928. %@AB@%_COM_ODDPARITY%@AE@%                    Odd parity
  6929.  
  6930. %@AB@%_COM_110%@AE@%                          110 baud
  6931.  
  6932. %@AB@%_COM_150%@AE@%                          150 baud
  6933.  
  6934. %@AB@%_COM_300%@AE@%                          300 baud
  6935.  
  6936. %@AB@%_COM_600%@AE@%                          600 baud
  6937.  
  6938. %@AB@%_COM_1200%@AE@%                         1,200 baud
  6939.  
  6940. %@AB@%_COM_2400%@AE@%                         2,400 baud
  6941.  
  6942. %@AB@%_COM_4800%@AE@%                         4,800 baud
  6943.  
  6944. %@AB@%_COM_9600%@AE@%                         9,600 baud
  6945.  
  6946. The default value of %@AI@%data%@AE@% is 1 stop bit, no parity, and 110 baud.  %@NL@%
  6947. %@NL@%
  6948. %@NL@%
  6949. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  6950. %@NL@%
  6951. The function returns a 16-bit integer whose high-order byte contains status
  6952. bits. The meaning of the low-order byte varies, depending on the %@AI@%service%@AE@%
  6953. value. The high-order bits have the following meanings:  %@NL@%
  6954. %@NL@%
  6955. %@AB@%Bit%@AE@%                               %@AB@%Meaning if Set%@AE@%
  6956. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6957. 15                                Timed out
  6958.  
  6959. 14                                Transmission-shift register empty
  6960.  
  6961. 13                                Transmission-hold register empty
  6962.  
  6963. 12                                Break detected
  6964.  
  6965. 11                                Framing error
  6966.  
  6967. 10                                Parity error
  6968.  
  6969. 9                                 Overrun error
  6970.  
  6971. 8                                 Data ready
  6972.  
  6973. When %@AI@%service%@AE@% is%@AB@% _COM_SEND%@AE@%, bit 15 will be set if %@AI@%data%@AE@% could not be sent.  %@NL@%
  6974. %@NL@%
  6975. When %@AI@%service%@AE@% is %@AB@%_COM_RECEIVE%@AE@%, the byte read will be returned in the
  6976. low-order bits if the call is successful. If an error occurs, any of the
  6977. bits 9, 10, 11, or 15 will be set.  %@NL@%
  6978. %@NL@%
  6979. When %@AI@%service%@AE@% is %@AB@%_COM_INIT%@AE@% or %@AB@%_COM_STATUS%@AE@%, the low-order bits are defined as
  6980. follows:  %@NL@%
  6981. %@NL@%
  6982. %@AB@%Bit%@AE@%                               %@AB@%Meaning if Set%@AE@%
  6983. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  6984. 7                                 Receive-line signal detected
  6985.  
  6986. 6                                 Ring indicator
  6987.  
  6988. 5                                 Data set ready
  6989.  
  6990. 4                                 Clear to send
  6991.  
  6992. 3                                 Change in receive-line signal detected
  6993.  
  6994. 2                                 Trailing-edge ring indicator
  6995.  
  6996. 1                                 Change in data-set-ready status
  6997.  
  6998. 0                                 Change in clear-to-send status
  6999.  
  7000. Note that this function works only with IBM personal computers and true
  7001. compatibles.  %@NL@%
  7002. %@NL@%
  7003. %@NL@%
  7004. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7005. %@NL@%
  7006.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  7007. %@NL@%
  7008. %@NL@%
  7009. %@NL@%
  7010. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7011. %@NL@%
  7012. %@AS@%  /* BSERIALC.C: This program checks the status of serial port COM1. */
  7013. %@AS@%  
  7014. %@AS@%  #include <bios.h>
  7015. %@AS@%  #include <stdio.h>
  7016. %@AS@%  
  7017. %@AS@%  void main()
  7018. %@AS@%  {
  7019. %@AS@%     unsigned com1_status;
  7020. %@AS@%  
  7021. %@AS@%     com1_status =  _bios_serialcom( _COM_STATUS, 0, 0 );
  7022. %@AS@%     printf ( "COM1 status: 0x%.4x\n", com1_status );
  7023. %@AS@%  }%@AE@%%@NL@%
  7024. %@NL@%
  7025. %@NL@%
  7026. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7027. %@NL@%
  7028. %@AS@%  
  7029. %@AS@%  
  7030. %@AS@%  COM1 status: 0x6000%@AE@%%@NL@%
  7031. %@NL@%
  7032. %@NL@%
  7033. %@NL@%
  7034. %@NL@%
  7035. %@QR:_bios_timeofday@%%@NL@%
  7036. %@2@%%@CR:C6A00280215 @%%@AB@%_bios_timeofday%@AE@%%@EH@%%@NL@%
  7037. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7038. %@NL@%
  7039. %@NL@%
  7040. %@3@%%@AB@%Description%@CR:C6A00280216 @% %@CR:C6A00280217 @%%@AE@%%@EH@%%@NL@%
  7041. %@NL@%
  7042. Calls BIOS time and date services, using system call INT 0x1A.  %@NL@%
  7043. %@NL@%
  7044. %@AB@%#include <bios.h>%@AE@%  %@NL@%
  7045. %@NL@%
  7046. %@AS@%  unsigned _bios_timeofday( unsigned service, long *timeval );%@AE@%%@NL@%
  7047. %@NL@%
  7048. %@AI@%service%@AE@%                           Time function desired
  7049.  
  7050. %@AI@%timeval%@AE@%                           Clock count
  7051.  
  7052. %@NL@%
  7053. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7054. %@NL@%
  7055. The %@AB@%_bios_timeofday%@AE@% routine uses system call INT 0x1A to get or set the
  7056. clock count. The %@AI@%service%@AE@% argument can be either of the following manifest
  7057. constants:  %@NL@%
  7058. %@NL@%
  7059. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  7060. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7061. %@AB@%_TIME_GETCLOCK%@AE@%                    Copies the current value of the clock 
  7062.                                   count to the location pointed to by %@AI@%%@AE@%
  7063.                                   %@AI@%timeval%@AE@%. If midnight has not passed 
  7064.                                   since the last time the system clock was
  7065.                                   read or set, the function returns 0; 
  7066.                                   otherwise, the function returns 1.
  7067.  
  7068. %@AB@%_TIME_SETCLOCK%@AE@%                    Sets the current value of the system 
  7069.                                   clock to the value in the location 
  7070.                                   pointed to by %@AI@%timeval%@AE@%. There is no 
  7071.                                   return value.
  7072.  
  7073. %@NL@%
  7074. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7075. %@NL@%
  7076. The %@AB@%_bios_timeofday%@AE@% function returns the value in the AX register after the
  7077. BIOS interrupt.  %@NL@%
  7078. %@NL@%
  7079. %@NL@%
  7080. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7081. %@NL@%
  7082.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  7083. %@NL@%
  7084. %@NL@%
  7085. %@NL@%
  7086. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7087. %@NL@%
  7088. %@AS@%  /* BTIMEOFD.C: This program gets the current system clock count before and
  7089. %@AS@%  after
  7090. %@AS@%   * a "do-nothing" loop and displays the difference.
  7091. %@AS@%   */
  7092. %@AS@%  
  7093. %@AS@%  #include <bios.h>
  7094. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  7095. %@NL@%
  7096. %@AS@%  void main()
  7097. %@AS@%  {
  7098. %@AS@%     long i, begin_tick, end_tick;
  7099. %@AS@%  
  7100. %@AS@%     _bios_timeofday( _TIME_GETCLOCK, &begin_tick );
  7101. %@AS@%     printf( "Beginning tick count: %lu\n", begin_tick );
  7102. %@AS@%     for( i = 1; i <= 900000; i++ )
  7103. %@AS@%        ;
  7104. %@AS@%     _bios_timeofday( _TIME_GETCLOCK, &end_tick );
  7105. %@AS@%     printf( "Ending tick count:    %lu\n", end_tick );
  7106. %@AS@%     printf( "Elapsed ticks:        %lu\n", end_tick - begin_tick );
  7107. %@AS@%  }%@AE@%%@NL@%
  7108. %@NL@%
  7109. %@NL@%
  7110. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7111. %@NL@%
  7112. %@AS@%  
  7113. %@AS@%  
  7114. %@AS@%  Beginning tick count: 1114255
  7115. %@AS@%  Ending tick count:    1114287
  7116. %@AS@%  Elapsed ticks:        32 %@AE@%%@NL@%
  7117. %@NL@%
  7118. %@NL@%
  7119. %@NL@%
  7120. %@NL@%
  7121. %@QR:bsearch@%%@NL@%
  7122. %@2@%%@CR:C6A00290218 @%%@AB@%bsearch%@AE@%%@EH@%%@NL@%
  7123. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7124. %@NL@%
  7125. %@NL@%
  7126. %@3@%%@AB@%Description%@CR:C6A00290219 @%%@CR:C6A00290220 @%%@CR:C6A00290221 @%%@AE@%%@EH@%%@NL@%
  7127. %@NL@%
  7128. Performs binary search of a sorted array.  %@NL@%
  7129. %@NL@%
  7130. %@AB@%#include <stdlib.h>%@AE@%               Required for ANSI compatibility
  7131.  
  7132. %@AB@%#include <search.h>%@AE@%               Required only for function declarations
  7133.  
  7134. %@AS@%  void *bsearch( const void *key, const void *base, size_t num, size_t
  7135. %@AS@%  width, 
  7136. %@AS@%  int ( *compare )( const void *elem1, const void *elem2 ) );%@AE@%%@NL@%
  7137. %@NL@%
  7138. %@AI@%key%@AE@%                               Object to search for
  7139.  
  7140. %@AI@%base%@AE@%                              Pointer to base of search data
  7141.  
  7142. %@AI@%num%@AE@%                               Number of elements
  7143.  
  7144. %@AI@%width%@AE@%                             Width of elements
  7145.  
  7146. %@AI@%compare%@AE@%                           Function that compares two elements:  %@AI@%%@AE@%
  7147.                                   %@AI@%elem1%@AE@% and %@AI@%elem2%@AE@%
  7148.  
  7149. %@AI@%elem1%@AE@%                             Pointer to the key for the search
  7150.  
  7151. %@AI@%elem2%@AE@%                             Pointer to the array element to be 
  7152.                                   compared with the key
  7153.  
  7154. %@NL@%
  7155. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7156. %@NL@%
  7157. The %@AB@%bsearch%@AE@% function performs a binary search of a sorted array of %@AI@%num%@AE@%
  7158. elements, each of %@AI@%width%@AE@% bytes in size. The %@AI@%base%@AE@% value is a pointer to the
  7159. base of the array to be searched, and %@AI@%key%@AE@% is the value being sought.  %@NL@%
  7160. %@NL@%
  7161. The %@AI@%compare%@AE@% argument is a pointer to a user-supplied routine that compares
  7162. two array elements and returns a value specifying their relationship. The
  7163. %@AB@%bsearch%@AE@% function calls the %@AI@%compare%@AE@% routine one or more times during the
  7164. search, passing pointers to two array elements on each call. The routine
  7165. compares the elements, then returns one of the following values:  %@NL@%
  7166. %@NL@%
  7167. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  7168. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7169. < 0                               %@AI@%elem1%@AE@% less than %@AI@%elem2%@AE@%
  7170.  
  7171. = 0                               %@AI@%elem1%@AE@% identical to %@AI@%elem2%@AE@%
  7172.  
  7173. > 0                               %@AI@%elem1%@AE@% greater than %@AI@%elem2%@AE@%
  7174.  
  7175. If the array you are searching is not in ascending sort order, %@AB@%bsearch%@AE@% does
  7176. not work properly. If the array contains duplicate records with identical
  7177. keys, there is no way to predict which of the duplicate records will be
  7178. located by %@AB@%bsearch%@AE@%.  %@NL@%
  7179. %@NL@%
  7180. %@NL@%
  7181. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7182. %@NL@%
  7183. The %@AB@%bsearch%@AE@% function returns a pointer to the first occurrence of %@AI@%key%@AE@% in the
  7184. array pointed to by %@AI@%base%@AE@%. If %@AI@%key%@AE@% is not found, the function returns %@AB@%NULL%@AE@%.  %@NL@%
  7185. %@NL@%
  7186. %@NL@%
  7187. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7188. %@NL@%
  7189. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  7190. %@NL@%
  7191. %@NL@%
  7192. %@NL@%
  7193. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7194. %@NL@%
  7195. %@AB@%lfind%@AE@%, %@AB@%lsearch%@AE@%, %@AB@%qsort%@AE@%  %@NL@%
  7196. %@NL@%
  7197. %@NL@%
  7198. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7199. %@NL@%
  7200. %@AS@%  /* BSEARCH.C: This program reads the command-line arguments, sorting them
  7201. %@AS@%   * with qsort, and then uses bsearch to find the word "cat."
  7202. %@AS@%   */
  7203. %@AS@%  
  7204. %@AS@%  #include <search.h>
  7205. %@AS@%  #include <string.h>
  7206. %@AS@%  #include <stdio.h>
  7207. %@AS@%  
  7208. %@AS@%  int compare( char **arg1, char **arg2 );  /* Declare a function for
  7209. %@AS@%compare */
  7210. %@AS@%  
  7211. %@AS@%  void main( int argc, char **argv )
  7212. %@AS@%  {
  7213. %@AS@%  
  7214. %@AS@%     char **result;
  7215. %@AS@%     char *key = "cat";
  7216. %@AS@%     int i;
  7217. %@AS@%  
  7218. %@AS@%     /* Sort using Quicksort algorithm: */
  7219. %@AS@%     qsort( (char *)argv, argc, sizeof( char * ), compare );
  7220. %@AS@%  
  7221. %@AS@%     for( i = 0; i < argc; ++i )        /* Output sorted list */
  7222. %@AS@%        printf( "%s ", argv[i] );
  7223. %@AS@%  
  7224. %@AS@%     /*  Find the word "cat" using a binary search algorithm: */
  7225. %@AS@%     result = (char **)bsearch( (char *) &key, (char *)argv, argc,
  7226. %@AS@%                                sizeof( char * ), compare );
  7227. %@AS@%     if( result )
  7228. %@AS@%        printf( "\n%s found at %Fp\n", *result, result );
  7229. %@AS@%     else
  7230. %@AS@%        printf( "\nCat not found!\n" );
  7231. %@AS@%  }
  7232. %@AS@%  
  7233. %@AS@%  int compare( char **arg1, char **arg2 )
  7234. %@AS@%  {
  7235. %@AS@%     /* Compare all of both strings: */
  7236. %@AS@%     return strcmpi( *arg1, *arg2 );
  7237. %@AS@%  }%@AE@%%@NL@%
  7238. %@NL@%
  7239. %@NL@%
  7240. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7241. %@NL@%
  7242. %@AS@%  
  7243. %@AS@%  
  7244. %@AS@%  [C:\LIBREF] bsearch dog pig horse cat human rat cow goat
  7245. %@AS@%  bsearch cat cow dog goat horse human pig rat
  7246. %@AS@%  cat found at 0292:0FD0 %@AE@%%@NL@%
  7247. %@NL@%
  7248. %@NL@%
  7249. %@NL@%
  7250. %@NL@%
  7251. %@QR:cabs@%%@QR:cabsl@%%@NL@%
  7252. %@2@%%@CR:C6A00300222 @%%@AB@%cabs, cabsl%@AE@%%@EH@%%@NL@%
  7253. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7254. %@NL@%
  7255. %@NL@%
  7256. %@3@%%@AB@%Description%@CR:C6A00300223 @%%@CR:C6A00300224 @%%@CR:C6A00300225 @% %@CR:C6A00300226 @%%@CR:C6A00300227 @%%@AE@%%@EH@%%@NL@%
  7257. %@NL@%
  7258. Calculate absolute value of a complex number.  %@NL@%
  7259. %@NL@%
  7260. %@AS@%  #include <math.h>%@AE@%%@NL@%
  7261. %@NL@%
  7262. %@AS@%  double cabs( struct complex z );%@AE@%%@NL@%
  7263. %@NL@%
  7264. %@AS@%  long double cabsl( struct _complexl z );%@AE@%%@NL@%
  7265. %@NL@%
  7266. %@AI@%z%@AE@%                                 Complex number
  7267.  
  7268. %@NL@%
  7269. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7270. %@NL@%
  7271. The %@AB@%cabs%@AE@% and %@AB@%cabsl%@AE@% functions calculate the absolute value of a complex
  7272. number, which must be a structure of type %@AB@%complex%@AE@% (or %@AB@%_complexl%@AE@%). The
  7273. structure %@AI@%z%@AE@% is composed of a real component %@AI@%x%@AE@% and an imaginary component %@AI@%y%@AE@%.
  7274. A call to one of the %@AB@%cabs%@AE@% routines is equivalent to the following:  %@NL@%
  7275. %@NL@%
  7276. %@AS@%  
  7277. %@AS@%  sqrt( z.x*z.x + z.y*z.y )%@AE@%%@NL@%
  7278. %@NL@%
  7279. The %@AB@%cabsl%@AE@% function is the 80-bit counterpart and it uses the 80-bit, 10-byte
  7280. coprocessor form of arguments and return values. See the reference page on
  7281. the long double functions for more details on this data type.  %@NL@%
  7282. %@NL@%
  7283. %@NL@%
  7284. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7285. %@NL@%
  7286. On overflow, these functions call %@AB@%matherr%@AE@% or %@AB@%_matherrl%@AE@%, return %@AB@%HUGE_VAL%@AE@%, and
  7287. set %@AB@%errno%@AE@% to %@AB@%ERANGE%@AE@%.  %@NL@%
  7288. %@NL@%
  7289. %@NL@%
  7290. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7291. %@NL@%
  7292. %@AS@%  cabs%@AE@%%@NL@%
  7293. %@NL@%
  7294.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  7295. %@NL@%
  7296. %@NL@%
  7297. %@AS@%  cabsl%@AE@%%@NL@%
  7298. %@NL@%
  7299.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  7300. %@NL@%
  7301. %@NL@%
  7302. %@NL@%
  7303. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7304. %@NL@%
  7305. %@AB@%abs%@AE@%, %@AB@%fabs%@AE@%, %@AB@%labs%@AE@%  %@NL@%
  7306. %@NL@%
  7307. %@NL@%
  7308. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7309. %@NL@%
  7310. %@AS@%  /* CABS.C: Using cabs, this program calculates the absolute value of
  7311. %@AS@%   * a complex number.
  7312. %@AS@%   */
  7313. %@AS@%  
  7314. %@AS@%  #include <math.h>
  7315. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  7316. %@NL@%
  7317. %@AS@%  void main()
  7318. %@AS@%  {
  7319. %@AS@%     struct complex number = { 3.0, 4.0 };
  7320. %@AS@%     double d;
  7321. %@AS@%  
  7322. %@AS@%     d = cabs( number );
  7323. %@AS@%     printf( "The absolute value of %f + %fi is %f\n",
  7324. %@AS@%             number.x, number.y, d );
  7325. %@AS@%  }%@AE@%%@NL@%
  7326. %@NL@%
  7327. %@NL@%
  7328. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7329. %@NL@%
  7330. %@AS@%  
  7331. %@AS@%  
  7332. %@AS@%  The absolute value of 3.000000 + 4.000000i is 5.000000 %@AE@%%@NL@%
  7333. %@NL@%
  7334. %@NL@%
  7335. %@NL@%
  7336. %@NL@%
  7337. %@QR:calloc@%%@NL@%
  7338. %@2@%%@CR:C6A00310228 @%%@AB@%calloc Functions%@AE@%%@EH@%%@NL@%
  7339. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7340. %@NL@%
  7341. %@NL@%
  7342. %@3@%%@AB@%Description%@CR:C6A00310229 @%%@CR:C6A00310230 @%%@CR:C6A00310231 @% %@CR:C6A00310232 @%%@CR:C6A00310233 @% %@CR:C6A00310234 @%%@CR:C6A00310235 @% %@CR:C6A00310236 @%%@AE@%%@EH@%%@NL@%
  7343. %@NL@%
  7344. Allocate an array in memory with elements initialized to 0.  %@NL@%
  7345. %@NL@%
  7346. %@AB@%#include <stdlib.h>%@AE@%               For ANSI compatibility (%@AB@%calloc%@AE@% only) 
  7347.  
  7348. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  7349.  
  7350. %@AS@%  void *calloc( size_t num, size_t size );%@AE@%%@NL@%
  7351. %@NL@%
  7352. %@AS@%  void _based( void ) *_bcalloc( _segment seg, size_t num, size_t size );%@AE@%%@NL@%
  7353. %@NL@%
  7354. %@AS@%  void _far *_fcalloc( size_t num, size_t size );%@AE@%%@NL@%
  7355. %@NL@%
  7356. %@AS@%  void _near *_ncalloc( size_t num, size_t size );%@AE@%%@NL@%
  7357. %@NL@%
  7358. %@AI@%num%@AE@%                               Number of elements
  7359.  
  7360. %@AI@%size%@AE@%                              Length in bytes of each element
  7361.  
  7362. %@AI@%seg%@AE@%                               Segment selector
  7363.  
  7364. %@NL@%
  7365. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7366. %@NL@%
  7367. The %@AB@%calloc%@AE@% family of functions allocates storage space for an array of %@AI@%num%@AE@%
  7368. elements, each of length %@AI@%size%@AE@% bytes. Each element is initialized to 0.  %@NL@%
  7369. %@NL@%
  7370. In large data models (compact-, large-, and huge-model programs), %@AB@%calloc%@AE@%
  7371. maps to %@AB@% _fcalloc%@AE@%. In small data models (tiny-, small-, and medium-model
  7372. programs), %@AB@%calloc%@AE@% maps to %@AB@%_ncalloc%@AE@%.  %@NL@%
  7373. %@NL@%
  7374. The various %@AB@%calloc%@AE@% functions allocate storage space in the data segments
  7375. shown in the list below:  %@NL@%
  7376. %@NL@%
  7377. %@AB@%Function%@AE@%                          %@AB@%Data Segment%@AE@%
  7378. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7379. %@AB@%calloc%@AE@%                            Depends on data model of program
  7380.  
  7381. %@AB@%_bcalloc%@AE@%                          Based heap, specified by %@AI@%seg%@AE@% segment 
  7382.                                   selector
  7383.  
  7384. %@AB@%_fcalloc%@AE@%                          Far heap (outside default data segment)
  7385.  
  7386. %@AB@%_ncalloc%@AE@%                          Near heap (inside default data segment)
  7387.  
  7388. %@NL@%
  7389. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7390. %@NL@%
  7391. The %@AB@%calloc%@AE@% functions return a pointer to the allocated space. The storage
  7392. space pointed to by the return value is guaranteed to be suitably aligned
  7393. for storage of any type of object. To get a pointer to a type other than
  7394. %@AB@%void%@AE@%, use a type cast on the return value.  %@NL@%
  7395. %@NL@%
  7396. The %@AB@%_fcalloc%@AE@% and %@AB@%_ncalloc%@AE@% functions return %@AB@%NULL%@AE@% if there is insufficient
  7397. memory available or if %@AI@%num%@AE@% or %@AI@%size%@AE@% is 0. The %@AB@%_bcalloc%@AE@% function returns
  7398. %@AB@%_NULLOFF%@AE@% in this case.  %@NL@%
  7399. %@NL@%
  7400. %@NL@%
  7401. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7402. %@NL@%
  7403. %@AS@%  calloc%@AE@%%@NL@%
  7404. %@NL@%
  7405. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  7406. %@NL@%
  7407. %@NL@%
  7408. %@AB@%_bcalloc%@AE@%, %@AB@%_fcalloc%@AE@%, %@AB@%_ncalloc%@AE@%  %@NL@%
  7409. %@NL@%
  7410.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  7411. %@NL@%
  7412. %@NL@%
  7413. %@NL@%
  7414. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7415. %@NL@%
  7416. %@AB@%free %@AE@%functions, %@AB@%halloc%@AE@%, %@AB@%hfree%@AE@%, %@AB@%malloc %@AE@%functions, %@AB@%realloc%@AE@% functions  %@NL@%
  7417. %@NL@%
  7418. %@NL@%
  7419. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7420. %@NL@%
  7421. %@AS@%  /* CALLOC.C: This program uses calloc to allocate space for 40 long
  7422. %@AS@%  integers.
  7423. %@AS@%   * It initializes each element to zero.
  7424. %@AS@%   */
  7425. %@AS@%  
  7426. %@AS@%  #include <stdio.h>
  7427. %@AS@%  #include <malloc.h>
  7428. %@AS@%  
  7429. %@AS@%  void main()
  7430. %@AS@%  {
  7431. %@AS@%     long *buffer;
  7432. %@AS@%  
  7433. %@AS@%     buffer = (long *)calloc( 40, sizeof( long ) );
  7434. %@AS@%     if( buffer != NULL )
  7435. %@AS@%        printf( "Allocated 40 long integers\n" );
  7436. %@AS@%     else
  7437. %@AS@%        printf( "Can't allocate memory\n" );
  7438. %@AS@%     free( buffer );
  7439. %@AS@%  }%@AE@%%@NL@%
  7440. %@NL@%
  7441. %@NL@%
  7442. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7443. %@NL@%
  7444. %@AS@%  
  7445. %@AS@%  
  7446. %@AS@%  Allocated 40 long integers %@AE@%%@NL@%
  7447. %@NL@%
  7448. %@NL@%
  7449. %@NL@%
  7450. %@NL@%
  7451. %@QR:ceil@%%@QR:ceill@%%@NL@%
  7452. %@2@%%@CR:C6A00320237 @%%@AB@%ceil, ceill%@AE@%%@EH@%%@NL@%
  7453. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7454. %@NL@%
  7455. %@NL@%
  7456. %@3@%%@AB@%Description%@CR:C6A00320238 @%%@CR:C6A00320239 @%%@CR:C6A00320240 @%%@AE@%%@EH@%%@NL@%
  7457. %@NL@%
  7458. Calculate the ceiling of a value.  %@NL@%
  7459. %@NL@%
  7460. %@AS@%  #include <math.h>%@AE@%%@NL@%
  7461. %@NL@%
  7462. %@AS@%  double ceil( double x );%@AE@%%@NL@%
  7463. %@NL@%
  7464. %@AS@%  long double ceill( long double x );%@AE@%%@NL@%
  7465. %@NL@%
  7466. %@AI@%x%@AE@%                                 Floating-point value
  7467.  
  7468. %@NL@%
  7469. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7470. %@NL@%
  7471. The %@AB@%ceil%@AE@% and %@AB@%ceill%@AE@% functions return a %@AB@%double%@AE@% (or %@AB@%long double%@AE@%) value
  7472. representing the smallest integer that is greater than or equal to %@AI@%x%@AE@%.  %@NL@%
  7473. %@NL@%
  7474. The %@AB@%ceill%@AE@% function is the 80-bit counterpart and it uses the 80-bit, 10-byte
  7475. coprocessor form of arguments and return values. See the reference page on
  7476. the long double functions for more details on this data type.  %@NL@%
  7477. %@NL@%
  7478. %@NL@%
  7479. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7480. %@NL@%
  7481. These functions return the %@AB@%double%@AE@% or %@AB@%long double%@AE@% result. There is no error
  7482. return.  %@NL@%
  7483. %@NL@%
  7484. %@NL@%
  7485. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7486. %@NL@%
  7487. %@AS@%  ceil%@AE@%%@NL@%
  7488. %@NL@%
  7489. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  7490. %@NL@%
  7491. %@NL@%
  7492. %@AS@%  ceill%@AE@%%@NL@%
  7493. %@NL@%
  7494.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  7495. %@NL@%
  7496. %@NL@%
  7497. %@NL@%
  7498. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7499. %@NL@%
  7500. %@AB@%floor%@AE@%, %@AB@%fmod%@AE@%  %@NL@%
  7501. %@NL@%
  7502. %@NL@%
  7503. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7504. %@NL@%
  7505. %@AS@%  /* FLOOR.C: This example displays the largest integers less than or equal
  7506. %@AS@%   * to the floating-point values 2.8 and -2.8. It then shows the smallest
  7507. %@AS@%   * integers greater than or equal to 2.8 and -2.8.
  7508. %@AS@%   */
  7509. %@AS@%  
  7510. %@AS@%  #include <math.h>
  7511. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  7512. %@NL@%
  7513. %@AS@%  void main()
  7514. %@AS@%  {
  7515. %@AS@%     double y;
  7516. %@AS@%  
  7517. %@AS@%     y = floor( 2.8 );
  7518. %@AS@%     printf( "The floor of 2.8 is %f\n", y );
  7519. %@AS@%     y = floor( -2.8 );
  7520. %@AS@%     printf( "The floor of -2.8 is %f\n", y );
  7521. %@AS@%  
  7522. %@AS@%     y = ceil( 2.8 );
  7523. %@AS@%     printf( "The ceil of 2.8 is %f\n", y );
  7524. %@AS@%     y = ceil( -2.8 );
  7525. %@AS@%     printf( "The ceil of -2.8 is %f\n", y );
  7526. %@AS@%  }%@AE@%%@NL@%
  7527. %@NL@%
  7528. %@NL@%
  7529. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7530. %@NL@%
  7531. %@AS@%  
  7532. %@AS@%  
  7533. %@AS@%  The floor of 2.8 is 2.000000
  7534. %@AS@%  The floor of -2.8 is -3.000000
  7535. %@AS@%  The ceil of 2.8 is 3.000000
  7536. %@AS@%  The ceil of -2.8 is -2.000000 %@AE@%%@NL@%
  7537. %@NL@%
  7538. %@NL@%
  7539. %@NL@%
  7540. %@NL@%
  7541. %@QR:_cexit@%%@QR:_c_exit@%%@NL@%
  7542. %@2@%%@CR:C6A00330241 @%%@AB@%_cexit, _c_exit%@AE@%%@EH@%%@NL@%
  7543. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7544. %@NL@%
  7545. %@NL@%
  7546. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  7547. %@NL@%
  7548. Perform clean-up operations and return without terminating the process.  %@NL@%
  7549. %@NL@%
  7550. %@CR:C6A00330242 @%%@CR:C6A00330243 @%%@AS@%  #include <process.h>       %@AE@%%@NL@%
  7551. %@NL@%
  7552. %@AS@%  void _cexit( void ); %@AE@%%@NL@%
  7553. %@NL@%
  7554. %@AS@%  void _c_exit( void );%@AE@%%@NL@%
  7555. %@NL@%
  7556. %@NL@%
  7557. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7558. %@NL@%
  7559. The %@AB@%_cexit%@AE@% function calls, in LIFO ("last in, first out") order, the
  7560. functions registered by %@AB@%atexit%@AE@% and %@AB@%onexit%@AE@%. Then the %@AB@%_cexit%@AE@% function flushes
  7561. all I/O buffers and closes all open files before returning.  %@NL@%
  7562. %@NL@%
  7563. The %@AB@%_c_exit%@AE@% function returns to the calling process without processing
  7564. %@AB@%atexit%@AE@% or %@AB@%onexit%@AE@% functions or flushing stream buffers.  %@NL@%
  7565. %@NL@%
  7566. The behavior of the %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, %@AB@%_cexit%@AE@%, and %@AB@%_c_exit%@AE@% functions is described
  7567. in the following list:  %@NL@%
  7568. %@NL@%
  7569. %@AB@%Function %@AE@%                         %@AB@%Action%@AE@%
  7570. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7571. %@AB@%exit%@AE@%                              Performs complete C library termination 
  7572.                                   procedures, terminates the process, and 
  7573.                                   exits with the supplied status code
  7574.  
  7575. %@AB@%_exit%@AE@%                             Performs "quick" C library termination 
  7576.                                   procedures, terminates the process, and 
  7577.                                   exits with the supplied status code
  7578.  
  7579. %@AB@%_cexit%@AE@%                            Performs complete C library termination 
  7580.                                   procedures and returns to caller, but 
  7581.                                   does not terminate the process
  7582.  
  7583. %@AB@%_c_exit%@AE@%                           Performs "quick" C library termination 
  7584.                                   procedures and returns to caller, but 
  7585.                                   does not terminate the process
  7586.  
  7587. %@NL@%
  7588. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7589. %@NL@%
  7590. None.  %@NL@%
  7591. %@NL@%
  7592. %@NL@%
  7593. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7594. %@NL@%
  7595.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  7596. %@NL@%
  7597. %@NL@%
  7598. %@NL@%
  7599. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7600. %@NL@%
  7601. %@AB@%abort%@AE@%, %@AB@%atexit%@AE@%, %@AB@%exec%@AE@% functions, %@AB@%exit%@AE@%, %@AB@%onexit%@AE@%, %@AB@%spawn%@AE@% functions, %@AB@%system%@AE@%  %@NL@%
  7602. %@NL@%
  7603. %@NL@%
  7604. %@NL@%
  7605. %@NL@%
  7606. %@QR:cgets@%%@NL@%
  7607. %@2@%%@CR:C6A00340244 @%%@AB@%cgets%@AE@%%@EH@%%@NL@%
  7608. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7609. %@NL@%
  7610. %@NL@%
  7611. %@3@%%@AB@%Description%@CR:C6A00340245 @% %@CR:C6A00340246 @% %@CR:C6A00340247 @%%@CR:C6A00340248 @%%@AE@%%@EH@%%@NL@%
  7612. %@NL@%
  7613. Gets a character string from the console.  %@NL@%
  7614. %@NL@%
  7615. %@AB@%#include <conio.h>%@AE@%                Required only for function declarations
  7616.  
  7617. %@AS@%  char *cgets( char *buffer );%@AE@%%@NL@%
  7618. %@NL@%
  7619. %@AI@%buffer%@AE@%                            Storage location for data
  7620.  
  7621. %@NL@%
  7622. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7623. %@NL@%
  7624. The %@AB@%cgets%@AE@% function reads a string of characters directly from the console
  7625. and stores the string and its length in the location pointed to by %@AI@%buffer%@AE@%.
  7626. The %@AI@%buffer%@AE@% argument must be a pointer to a character array. The first
  7627. element of the array, %@AI@%buffer%@AE@%[0], must contain the maximum length (in
  7628. characters) of the string to be read. The array must contain enough elements
  7629. to hold the string, a terminating null character (%@AB@%'\0'%@AE@%), and two additional
  7630. bytes.  %@NL@%
  7631. %@NL@%
  7632. The %@AB@%cgets%@AE@% function continues to read characters until a
  7633. carriage-return-line-feed (CR-LF) combination is read, or the specified
  7634. number of characters is read. The string is stored starting at %@AI@%str%@AE@%[2]. If a
  7635. CR-LF combination is read, it is replaced with a null character (%@AB@%'\0'%@AE@%)
  7636. before being stored. The %@AB@%cgets%@AE@% function then stores the actual length of the
  7637. string in the second array element, %@AI@%buffer%@AE@%[1].  %@NL@%
  7638. %@NL@%
  7639. Because all DOS editing keys are active when you call %@AB@%cgets%@AE@%, pressing F3
  7640. repeats the last entry.  %@NL@%
  7641. %@NL@%
  7642. %@NL@%
  7643. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7644. %@NL@%
  7645. The %@AB@%cgets%@AE@% function returns a pointer to the start of the string, at
  7646. %@AI@%buffer%@AE@%[2]. There is no error return.  %@NL@%
  7647. %@NL@%
  7648. %@NL@%
  7649. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7650. %@NL@%
  7651.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  7652. %@NL@%
  7653. %@NL@%
  7654. %@NL@%
  7655. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7656. %@NL@%
  7657. %@AB@%getch%@AE@%, %@AB@%getche%@AE@%  %@NL@%
  7658. %@NL@%
  7659. %@NL@%
  7660. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7661. %@NL@%
  7662. %@AS@%  /* CGETS.C: This program creates a buffer and initializes the first byte
  7663. %@AS@%   * to the size of the buffer - 2. Next, the program accepts an input
  7664. %@AS@%string
  7665. %@AS@%   * using cgets and displays the size and text of that string.
  7666. %@AS@%   */
  7667. %@AS@%  
  7668. %@AS@%  #include <conio.h>
  7669. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  7670. %@NL@%
  7671. %@AS@%  void main()
  7672. %@AS@%  {
  7673. %@AS@%     char buffer[82] = { 80 };  /* Maximum characters in first byte */
  7674. %@AS@%     char *result;
  7675. %@AS@%  
  7676. %@AS@%     printf( "Input line of text, followed by carriage return:\n");
  7677. %@AS@%     result = cgets( buffer );  /* Input a line of text */
  7678. %@AS@%     printf( "\nLine length = %d\nText = %s\n", buffer[1], result );
  7679. %@AS@%  }%@AE@%%@NL@%
  7680. %@NL@%
  7681. %@NL@%
  7682. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7683. %@NL@%
  7684. %@AS@%  
  7685. %@AS@%  
  7686. %@AS@%  Input line of text, followed by carriage return:
  7687. %@AS@%  This is some text
  7688. %@AS@%  Line length = 17
  7689. %@AS@%  Text = This is some text %@AE@%%@NL@%
  7690. %@NL@%
  7691. %@NL@%
  7692. %@NL@%
  7693. %@NL@%
  7694. %@QR:_chain_intr@%%@NL@%
  7695. %@2@%%@CR:C6A00350249 @%%@AB@%_chain_intr%@AE@%%@EH@%%@NL@%
  7696. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7697. %@NL@%
  7698. %@NL@%
  7699. %@3@%%@AB@%Description%@CR:C6A00350250 @% %@CR:C6A00350251 @%%@AE@%%@EH@%%@NL@%
  7700. %@NL@%
  7701. Chains an interrupt from one handler to another.  %@NL@%
  7702. %@NL@%
  7703. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  7704. %@NL@%
  7705. %@AS@%  void _chain_intr( void( _interrupt _far *target )());%@AE@%%@NL@%
  7706. %@NL@%
  7707. %@AI@%target%@AE@%                            Target interrupt routine
  7708.  
  7709. %@NL@%
  7710. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7711. %@NL@%
  7712. The %@AB@%_chain_intr%@AE@% routine passes control from one interrupt handler to
  7713. another. The stack and the registers of the first routine are passed to the
  7714. second, allowing the second routine to return as if it had been called
  7715. directly.  %@NL@%
  7716. %@NL@%
  7717. The %@AB@%_chain_intr%@AE@% routine is generally used when a user-defined interrupt
  7718. handler begins processing, then chains to the original interrupt handler to
  7719. finish processing.  %@NL@%
  7720. %@NL@%
  7721. Chaining is one of two techniques, listed below, that can be used to
  7722. transfer control from a new interrupt routine to an old one:  %@NL@%
  7723. %@NL@%
  7724. %@NL@%
  7725.   1.  Call %@AB@%_chain_intr%@AE@% with the interrupt routine as an argument. Do this if
  7726.       your routine is finished and you want the second interrupt routine to
  7727.       terminate the interrupt call.
  7728. %@NL@%
  7729. %@AS@%      void _interrupt new_int( unsigned _es, unsigned _ds,
  7730. %@AS@%         unsigned _di, unsigned _si,... )
  7731. %@AS@%      {
  7732. %@AS@%          ++_di;                  /* Initial processing here  */
  7733. %@AS@%          _chain_intr( old_int ); /* New DI passed to old_int */
  7734. %@AS@%          --_di;                  /* This is never executed   */
  7735. %@AS@%      }%@AE@%%@NL@%
  7736. %@NL@%
  7737. %@NL@%
  7738.   2.  Call the interrupt routine (after casting it to an interrupt function
  7739.       if necessary). Do this if you need to do further processing after the
  7740.       second interrupt routine finishes.
  7741. %@NL@%
  7742. %@AS@%      void _interrupt new_int( unsigned _es, unsigned _ds,
  7743. %@AS@%         unsigned _di, unsigned _si,... )
  7744. %@AS@%      {
  7745. %@AS@%          ++_di;                   /* Initial processing here  */
  7746. %@AS@%          (*old_int)();            /* New DI passed to old_int */
  7747. %@AS@%          _asm mov _di, di         /* Put real DI from old_int */
  7748. %@AS@%                                   /*   into _di for return    */
  7749. %@AS@%      }%@AE@%%@NL@%
  7750. %@NL@%
  7751. %@NL@%
  7752. %@NL@%
  7753. Note that the real registers set by the old interrupt function are not
  7754. automatically set to the pseudoregisters of the new routine.  %@NL@%
  7755. %@NL@%
  7756. Use the %@AB@%_chain_intr%@AE@% function when you do not want to replace the default
  7757. interrupt handler, but you do need to see its input. An example is a TSR
  7758. (terminate-and-stay-resident) program that checks all keyboard input for a
  7759. particular "hot key" sequence.  %@NL@%
  7760. %@NL@%
  7761. The %@AB@%_chain_intr%@AE@% function should be used only with C functions that have been
  7762. declared with type %@AB@%_interrupt%@AE@%. The %@AB@%_interrupt%@AE@% declaration ensures that the
  7763. procedure's entry/exit sequence is appropriate for an interrupt handler.  %@NL@%
  7764. %@NL@%
  7765. %@NL@%
  7766. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7767. %@NL@%
  7768. The %@AB@%_chain_intr%@AE@% function does not return to the caller.  %@NL@%
  7769. %@NL@%
  7770. %@NL@%
  7771. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7772. %@NL@%
  7773.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  7774. %@NL@%
  7775. %@NL@%
  7776. %@NL@%
  7777. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7778. %@NL@%
  7779. %@AB@%_dos_getvect%@AE@%,  %@AB@%_dos_keep%@AE@%,  %@AB@%_dos_setvect%@AE@%  %@NL@%
  7780. %@NL@%
  7781. %@NL@%
  7782. %@NL@%
  7783. %@NL@%
  7784. %@QR:chdir@%%@NL@%
  7785. %@2@%%@CR:C6A00360252 @%%@AB@%chdir%@AE@%%@EH@%%@NL@%
  7786. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7787. %@NL@%
  7788. %@NL@%
  7789. %@3@%%@AB@%Description%@CR:C6A00360253 @%%@AE@%%@EH@%%@NL@%
  7790. %@NL@%
  7791. Changes the current working directory.  %@NL@%
  7792. %@NL@%
  7793. %@AB@%#include <direct.h%@AE@%>               Required only for function declarations
  7794.  
  7795. %@AB@%#include <errno.h>%@AE@%                Required for %@AB@%errno%@AE@% constants
  7796.  
  7797. %@AS@%  int chdir( char *dirname );%@AE@%%@NL@%
  7798. %@NL@%
  7799. %@AI@%dirname%@AE@%                           Path name of new working directory
  7800.  
  7801. %@NL@%
  7802. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7803. %@NL@%
  7804. The %@AB@%chdir%@AE@% function changes the current working directory to the directory
  7805. specified by %@AI@% dirname%@AE@%. The %@AI@%dirname%@AE@% argument must refer to an existing
  7806. directory.  %@NL@%
  7807. %@NL@%
  7808. This function can change the current working directory on any drive; it
  7809. cannot be used to change the default drive itself. For example, if A: is the
  7810. default drive and \BIN is the current working directory, the following call
  7811. changes the current working directory for drive C:  %@NL@%
  7812. %@NL@%
  7813. %@AS@%  chdir("c:\\temp");%@AE@%%@NL@%
  7814. %@NL@%
  7815. Notice that you must place two backslashes ( \\ ) in a C string in order to
  7816. represent a single backslash ( \ ); the backslash is the escape character
  7817. for C strings and therefore requires special handling.  %@NL@%
  7818. %@NL@%
  7819. This function call has no apparent immediate effect. However, when the
  7820. %@AB@%_chdrive%@AE@% function is called to change the default drive to C:, the current
  7821. working directory becomes C:\TEMP.  %@NL@%
  7822. %@NL@%
  7823. In OS/2 protected mode, the current working directory is local to a process
  7824. rather than system-wide. When a process terminates, the current working
  7825. directory is restored to its original value. Under DOS, the new directory
  7826. set by the program becomes the new current working directory.  %@NL@%
  7827. %@NL@%
  7828. %@NL@%
  7829. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7830. %@NL@%
  7831. The %@AB@%chdir%@AE@% function returns a value of 0 if the working directory is
  7832. successfully changed. A return value of -1 indicates an error, in which case
  7833. %@AB@%errno%@AE@% is set to %@AB@%ENOENT%@AE@%, indicating that the specified path name could not be
  7834. found.  %@NL@%
  7835. %@NL@%
  7836. %@NL@%
  7837. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7838. %@NL@%
  7839.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  7840. %@NL@%
  7841. %@NL@%
  7842. %@NL@%
  7843. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7844. %@NL@%
  7845. %@AB@%_dos_setdrive%@AE@%, %@AB@%mkdir%@AE@%, %@AB@%rmdir%@AE@%, %@AB@%system%@AE@%  %@NL@%
  7846. %@NL@%
  7847. %@NL@%
  7848. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7849. %@NL@%
  7850. %@AS@%  /* CHGDIR.C: This program uses the chdir function to verify that a
  7851. %@AS@%   * given directory exists. Under real mode that directory also becomes
  7852. %@AS@%   * the current directory. Under protected mode, it is only the default
  7853. %@AS@%   * directory for the current process.
  7854. %@AS@%   */
  7855. %@AS@%  
  7856. %@AS@%  #include <direct.h>
  7857. %@AS@%  #include <stdio.h>
  7858. %@AS@%  #include <stdlib.h>
  7859. %@AS@%  
  7860. %@AS@%  void main( int argc, char *argv[] )
  7861. %@AS@%  {
  7862. %@AS@%     if( chdir( argv[1] )   )
  7863. %@AS@%        printf( "Unable to locate the directory: %s\n", argv[1] );
  7864. %@AS@%     else
  7865. %@AS@%        system( "dir *.c" );
  7866. %@AS@%  }%@AE@%%@NL@%
  7867. %@NL@%
  7868. %@NL@%
  7869. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7870. %@NL@%
  7871. %@AS@%  
  7872. %@AS@%  
  7873. %@AS@%  [C:\LIBREF] chgdir \tmp
  7874. %@AS@%  
  7875. %@AS@%   The volume label in drive C is OS2.
  7876. %@AS@%   Directory of C:\TMP
  7877. %@AS@%  
  7878. %@AS@%  DUP      C        232   4-18-89  11:18a
  7879. %@AS@%  TEST     C        713   4-07-88   2:49p
  7880. %@AS@%       2 File(s)   14155776 bytes free %@AE@%%@NL@%
  7881. %@NL@%
  7882. %@NL@%
  7883. %@NL@%
  7884. %@NL@%
  7885. %@QR:_chdrive@%%@NL@%
  7886. %@2@%%@CR:C6A00370254 @%%@AB@%_chdrive%@AE@%%@EH@%%@NL@%
  7887. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  7888. %@NL@%
  7889. %@NL@%
  7890. %@3@%%@AB@%Description%@CR:C6A00370255 @%%@CR:C6A00370256 @%%@AE@%%@EH@%%@NL@%
  7891. %@NL@%
  7892. Changes the current working drive.  %@NL@%
  7893. %@NL@%
  7894. %@AB@%#include <direct.h>%@AE@%               Required only for function declarations
  7895.  
  7896. %@AS@%  int _chdrive( int drive );%@AE@%%@NL@%
  7897. %@NL@%
  7898. %@AI@%drive%@AE@%                             Number of new working drive
  7899.  
  7900. %@NL@%
  7901. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  7902. %@NL@%
  7903. The %@AB@%_chdrive%@AE@% function changes the current working drive to the drive
  7904. specified by %@AI@%drive%@AE@%. The %@AI@%drive%@AE@% argument uses an integer to specify the new
  7905. working drive (1=A, 2=B, etc.).  %@NL@%
  7906. %@NL@%
  7907. This function changes only the working drive; the %@AB@%chdir%@AE@% function changes the
  7908. working directory.  %@NL@%
  7909. %@NL@%
  7910. In OS/2 protected mode, the working drive is local to a process rather than
  7911. system-wide. When a process terminates, the working drive is restored to its
  7912. original value. Under DOS, the new drive set by the program becomes the new
  7913. working drive.  %@NL@%
  7914. %@NL@%
  7915. %@NL@%
  7916. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  7917. %@NL@%
  7918. The %@AB@%_chdrive%@AE@% function returns a value of 0 if the working drive is
  7919. successfully changed. A return value of -1 indicates an error.  %@NL@%
  7920. %@NL@%
  7921. %@NL@%
  7922. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  7923. %@NL@%
  7924.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  7925. %@NL@%
  7926. %@NL@%
  7927. %@NL@%
  7928. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  7929. %@NL@%
  7930. %@AB@%chdir%@AE@%,  %@AB@%_dos_setdrive%@AE@%,  %@AB@%_fullpath%@AE@%, %@AB@% _getcwd%@AE@%, %@AB@% _getdrive%@AE@%, %@AB@%mkdir%@AE@%, %@AB@%rmdir%@AE@%,
  7931. %@AB@%system%@AE@%  %@NL@%
  7932. %@NL@%
  7933. %@NL@%
  7934. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  7935. %@NL@%
  7936. %@AS@%  /* GETDRIVE.C illustrates drive functions including:
  7937. %@AS@%   *      _getdrive       _chdrive        _getdcwd
  7938. %@AS@%   */
  7939. %@AS@%  
  7940. %@AS@%  #include <stdio.h>
  7941. %@AS@%  #include <conio.h>
  7942. %@AS@%  #include <direct.h>
  7943. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  7944. %@NL@%
  7945. %@AS@%  void main()
  7946. %@AS@%  {
  7947. %@AS@%     int ch, drive, curdrive;
  7948. %@AS@%     static char path[_MAX_PATH];
  7949. %@AS@%  
  7950. %@AS@%     /* Save current drive. */
  7951. %@AS@%     curdrive = _getdrive();
  7952. %@AS@%  
  7953. %@AS@%     printf( "Available drives are: \n" );
  7954. %@AS@%  
  7955. %@AS@%     /* If we can switch to the drive, it exists. */
  7956. %@AS@%     for( drive = 1; drive <= 26; drive++ )
  7957. %@AS@%        if( !_chdrive( drive ) )
  7958. %@AS@%           printf( "%c: ", drive + 'A' - 1 );
  7959. %@AS@%  
  7960. %@AS@%     while( 1 )
  7961. %@AS@%     {
  7962. %@AS@%        printf( "\nType drive letter to check or ESC to quit: " );
  7963. %@AS@%        ch = getch();
  7964. %@AS@%        if( ch == 27 )
  7965. %@AS@%           break;
  7966. %@AS@%        if( isalpha( ch ) )
  7967. %@AS@%           putch( ch );
  7968. %@AS@%        if( _getdcwd( toupper( ch ) - 'A' + 1, path, _MAX_PATH ) != NULL )
  7969. %@AS@%           printf( "\nCurrent directory on that drive is %s\n", path );
  7970. %@AS@%     }
  7971. %@AS@%  
  7972. %@AS@%     /* Restore original drive. This is only necessary for DOS. Under OS/2
  7973. %@AS@%      * the current drive of the calling process is always restored.
  7974. %@AS@%      */
  7975. %@AS@%     _chdrive( curdrive );
  7976. %@AS@%     printf( "\n" );
  7977. %@AS@%  }%@AE@%%@NL@%
  7978. %@NL@%
  7979. %@NL@%
  7980. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  7981. %@NL@%
  7982. %@AS@%  
  7983. %@AS@%  
  7984. %@AS@%  Available drives are:
  7985. %@AS@%  A: B: C:
  7986. %@AS@%  Type drive letter to check or ESC to quit: q
  7987. %@AS@%  Type drive letter to check or ESC to quit: a
  7988. %@AS@%  Current directory on that drive is A:\
  7989. %@AS@%  
  7990. %@AS@%  Type drive letter to check or ESC to quit: c
  7991. %@AS@%  Current directory on that drive is C:\LIBREF
  7992. %@AS@%  
  7993. %@AS@%  Type drive letter to check or ESC to quit:%@AE@%%@NL@%
  7994. %@NL@%
  7995. %@NL@%
  7996. %@NL@%
  7997. %@NL@%
  7998. %@QR:chmod@%%@NL@%
  7999. %@2@%%@CR:C6A00380257 @%%@AB@%chmod%@AE@%%@EH@%%@NL@%
  8000. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8001. %@NL@%
  8002. %@NL@%
  8003. %@3@%%@AB@%Description%@CR:C6A00380258 @%%@CR:C6A00380259 @% %@CR:C6A00380260 @%%@AE@%%@EH@%%@NL@%
  8004. %@NL@%
  8005. Changes the file-permission settings.  %@NL@%
  8006. %@NL@%
  8007. %@AB@%#include <sys\types.h>%@AE@%            
  8008.  
  8009. %@AB@%#include <sys\stat.h>%@AE@%             
  8010.  
  8011. %@AB@%#include <errno.h>%@AE@%                
  8012.  
  8013. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  8014.  
  8015. %@AS@%  int chmod( char *filename, int pmode );%@AE@%%@NL@%
  8016. %@NL@%
  8017. %@AI@%filename%@AE@%                          Path name of existing file
  8018.  
  8019. %@AI@%pmode%@AE@%                             Permission setting for file
  8020.  
  8021. %@NL@%
  8022. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8023. %@NL@%
  8024. The %@AB@%chmod%@AE@% function changes the permission setting of the file specified by
  8025. %@AI@%filename.%@AE@% The permission setting controls read and write access to the file.
  8026. The constant expression %@AI@%pmode%@AE@% contains one or both of the manifest constants
  8027. %@AB@%S_IWRITE%@AE@% and %@AB@%S_IREAD%@AE@%, defined in SYS\STAT.H. Any other values for %@AI@%pmode%@AE@% are
  8028. ignored. When both constants are given, they are joined with the bitwise-OR
  8029. operator ( | ). The meaning of the %@AI@%pmode%@AE@% argument is as follows:  %@NL@%
  8030. %@NL@%
  8031. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  8032. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8033. %@AB@%S_IWRITE%@AE@%                          Writing permitted
  8034.  
  8035. %@AB@%S_IREAD%@AE@%                           Reading permitted
  8036.  
  8037. %@AB@%S_IREAD%@AE@% |  %@AB@%S_IWRITE%@AE@%               Reading and writing permitted
  8038.  
  8039. If write permission is not given, the file is read-only. Under DOS and OS/2,
  8040. all files are readable; it is not possible to give write-only permission.
  8041. Thus the modes %@AB@%S_IWRITE%@AE@% and %@AB@%S_IREAD%@AE@%  |  %@AB@%S_IWRITE%@AE@% are equivalent.  %@NL@%
  8042. %@NL@%
  8043. %@NL@%
  8044. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8045. %@NL@%
  8046. The %@AB@%chmod%@AE@% function returns the value 0 if the permission setting is
  8047. successfully changed. A return value of -1 indicates an error; in this case,
  8048. %@AB@%errno%@AE@% is set to %@AB@%ENOENT%@AE@%, indicating that the specified file could not be
  8049. found.  %@NL@%
  8050. %@NL@%
  8051. %@NL@%
  8052. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8053. %@NL@%
  8054.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  8055. %@NL@%
  8056. %@NL@%
  8057. %@NL@%
  8058. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8059. %@NL@%
  8060. %@AB@%access%@AE@%, %@AB@%creat%@AE@%, %@AB@%fstat%@AE@%, %@AB@%open%@AE@%, %@AB@%stat%@AE@%  %@NL@%
  8061. %@NL@%
  8062. %@NL@%
  8063. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8064. %@NL@%
  8065. %@AS@%  /* CHMOD.C: This program uses chmod to change the mode of a file to
  8066. %@AS@%   * read-only. It then attempts to modify the file.
  8067. %@AS@%   */
  8068. %@AS@%  
  8069. %@AS@%  #include <sys\types.h>
  8070. %@AS@%  #include <sys\stat.h>
  8071. %@AS@%  #include <io.h>
  8072. %@AS@%  #include <stdio.h>
  8073. %@AS@%  #include <stdlib.h>
  8074. %@AS@%  
  8075. %@AS@%  void main()
  8076. %@AS@%  {
  8077. %@AS@%     /* Make file read-only: */
  8078. %@AS@%     if( chmod( "CHMOD.C", S_IREAD ) == -1 )
  8079. %@AS@%        perror( "File not found\n" );
  8080. %@AS@%     else
  8081. %@AS@%        printf( "Mode changed to read-only\n" );
  8082. %@AS@%     system( "echo /* End of file */ >> CHMOD.C" );
  8083. %@AS@%  
  8084. %@AS@%     /* Change back to read/write: */
  8085. %@AS@%     if( chmod( "CHMOD.C", S_IWRITE ) == -1 )
  8086. %@AS@%        perror( "File not found\n" );
  8087. %@AS@%     else
  8088. %@AS@%        printf( "Mode changed to read/write\n" );
  8089. %@AS@%  }%@AE@%%@NL@%
  8090. %@NL@%
  8091. %@NL@%
  8092. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8093. %@NL@%
  8094. %@AS@%  
  8095. %@AS@%  
  8096. %@AS@%  Mode changed to read-only
  8097. %@AS@%  Access denied
  8098. %@AS@%  Mode changed to read/write %@AE@%%@NL@%
  8099. %@NL@%
  8100. %@NL@%
  8101. %@NL@%
  8102. %@NL@%
  8103. %@QR:chsize@%%@NL@%
  8104. %@2@%%@CR:C6A00390261 @%%@AB@%chsize%@AE@%%@EH@%%@NL@%
  8105. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8106. %@NL@%
  8107. %@NL@%
  8108. %@3@%%@AB@%Description%@CR:C6A00390262 @%%@CR:C6A00390263 @%%@CR:C6A00390264 @%%@AE@%%@EH@%%@NL@%
  8109. %@NL@%
  8110. Changes the file size.  %@NL@%
  8111. %@NL@%
  8112. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  8113.  
  8114. %@AB@%#include <errno.h>%@AE@%                
  8115.  
  8116. %@AS@%  int chsize( int handle, long size );%@AE@%%@NL@%
  8117. %@NL@%
  8118. %@AI@%handle%@AE@%                            Handle referring to open file
  8119.  
  8120. %@AI@%size%@AE@%                              New length of file in bytes
  8121.  
  8122. %@NL@%
  8123. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8124. %@NL@%
  8125. The %@AB@%chsize%@AE@% function extends or truncates the file associated with %@AI@%handle%@AE@% to
  8126. the length specified by %@AI@%size%@AE@%. The file must be open in a mode that permits
  8127. writing. Null characters (%@AB@%'\0'%@AE@%) are appended if the file is extended. If the
  8128. file is truncated, all data from the end of the shortened file to the
  8129. original length of the file is lost.  %@NL@%
  8130. %@NL@%
  8131. In DOS, the directory update is done when a file is closed. Consequently,
  8132. while a program is running, requests to determine the amount of free disk
  8133. space may receive inaccurate results.  %@NL@%
  8134. %@NL@%
  8135. %@NL@%
  8136. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8137. %@NL@%
  8138. The %@AB@%chsize%@AE@% function returns the value 0 if the file size is successfully
  8139. changed. A return value of -1 indicates an error, and %@AB@%errno%@AE@% is set to one of
  8140. the following values:  %@NL@%
  8141. %@NL@%
  8142. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  8143. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8144. %@AB@%EACCES%@AE@%                            Specified file is locked against access 
  8145.                                   (OS/2 and DOS versions 3.0 and later 
  8146.                                   only).
  8147.  
  8148. %@AB@%EBADF%@AE@%                             Specified file is read-only or an 
  8149.                                   invalid file handle.
  8150.  
  8151. %@AB@%ENOSPC%@AE@%                            No space is left on device.
  8152.  
  8153. %@NL@%
  8154. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8155. %@NL@%
  8156.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  8157. %@NL@%
  8158. %@NL@%
  8159. %@NL@%
  8160. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8161. %@NL@%
  8162. %@AB@%close%@AE@%, %@AB@%creat%@AE@%, %@AB@%open%@AE@%  %@NL@%
  8163. %@NL@%
  8164. %@NL@%
  8165. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8166. %@NL@%
  8167. %@AS@%  /* CHSIZE.C: This program uses filelength to report the size of a
  8168. %@AS@%   * file before and after modifying it with chsize.
  8169. %@AS@%   */%@AE@%%@NL@%
  8170. %@NL@%
  8171. %@AS@%  #include <io.h>
  8172. %@AS@%  #include <fcntl.h>
  8173. %@AS@%  #include <sys\types.h>
  8174. %@AS@%  #include <sys\stat.h>
  8175. %@AS@%  #include <stdio.h>
  8176. %@AS@%  
  8177. %@AS@%  void main()
  8178. %@AS@%  {
  8179. %@AS@%     int fh, result;
  8180. %@AS@%     unsigned int nbytes = BUFSIZ;
  8181. %@AS@%  
  8182. %@AS@%     /* Open a file */
  8183. %@AS@%     if( (fh = open( "data", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 )
  8184. %@AS@%     {
  8185. %@AS@%        printf( "File length before: %ld\n", filelength( fh ) );
  8186. %@AS@%        if( chsize( fh, 329678 ) == 0 )
  8187. %@AS@%           printf( "Size successfully changed\n" );
  8188. %@AS@%        else
  8189. %@AS@%           printf( "Problem in changing the size\n" );
  8190. %@AS@%        printf( "File length after:  %ld\n", filelength( fh ) );
  8191. %@AS@%        close( fh );
  8192. %@AS@%     }
  8193. %@AS@%  }%@AE@%%@NL@%
  8194. %@NL@%
  8195. %@NL@%
  8196. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8197. %@NL@%
  8198. %@AS@%  
  8199. %@AS@%  
  8200. %@AS@%  File length before: 0
  8201. %@AS@%  Size successfully changed
  8202. %@AS@%  File length after:  329678%@AE@%%@NL@%
  8203. %@NL@%
  8204. %@NL@%
  8205. %@NL@%
  8206. %@NL@%
  8207. %@QR:_clear87@%%@NL@%
  8208. %@2@%%@CR:C6A00400265 @%%@AB@%_clear87%@AE@%%@EH@%%@NL@%
  8209. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8210. %@NL@%
  8211. %@NL@%
  8212. %@3@%%@AB@%Description%@CR:C6A00400266 @%%@CR:C6A00400267 @% %@CR:C6A00400268 @%%@AE@%%@EH@%%@NL@%
  8213. %@NL@%
  8214. Gets and clears the floating-point status word.  %@NL@%
  8215. %@NL@%
  8216. %@AS@%  #include <float.h>%@AE@%%@NL@%
  8217. %@NL@%
  8218. %@AS@%  unsigned int _clear87( void );%@AE@%%@NL@%
  8219. %@NL@%
  8220. %@NL@%
  8221. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8222. %@NL@%
  8223. The %@AB@%_clear87%@AE@% function gets and clears the floating-point status word. The
  8224. floating-point status word is a combination of the 8087/80287 status word
  8225. and other conditions detected by the 8087/80287 exception handler, such as
  8226. floating-point stack overflow and underflow.  %@NL@%
  8227. %@NL@%
  8228. %@NL@%
  8229. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8230. %@NL@%
  8231. The bits in the value returned indicate the floating-point status. See the
  8232. FLOAT.H include file for a complete definition of the bits returned by
  8233. %@AB@%_clear87%@AE@%.  %@NL@%
  8234. %@NL@%
  8235. Many of the math library functions modify the 8087/80287 status word, with
  8236. unpredictable results. Return values from %@AB@%_clear87%@AE@% and %@AB@%_status87%@AE@% become more
  8237. reliable as fewer floating-point operations are performed between known
  8238. states of the floating-point status word.  %@NL@%
  8239. %@NL@%
  8240. %@NL@%
  8241. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8242. %@NL@%
  8243.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8244. %@NL@%
  8245. %@NL@%
  8246. %@NL@%
  8247. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8248. %@NL@%
  8249. %@AB@%_control87%@AE@%, %@AB@%_status87%@AE@%  %@NL@%
  8250. %@NL@%
  8251. %@NL@%
  8252. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8253. %@NL@%
  8254. %@AS@%  /* CLEAR87.C: This program creates various floating-point problems,
  8255. %@AS@%   * then uses _clear87 to report on these problems.
  8256. %@AS@%   */
  8257. %@AS@%  
  8258. %@AS@%  #include <stdio.h>
  8259. %@AS@%  #include <float.h>
  8260. %@AS@%  
  8261. %@AS@%  void main()
  8262. %@AS@%  {
  8263. %@AS@%     double a = 1e-40, b;
  8264. %@AS@%     float x, y;
  8265. %@AS@%  
  8266. %@AS@%     printf( "Status: %.4x - clear\n", _clear87()  );
  8267. %@AS@%  
  8268. %@AS@%     /* Store into y is inexact and underflows: */
  8269. %@AS@%     y = a;
  8270. %@AS@%     printf( "Status: %.4x - inexact, underflow\n", _clear87() );%@AE@%%@NL@%
  8271. %@NL@%
  8272. %@AS@%  /* y is denormal: */
  8273. %@AS@%     b = y;
  8274. %@AS@%     printf( "Status: %.4x - denormal\n", _clear87() );
  8275. %@AS@%  }%@AE@%%@NL@%
  8276. %@NL@%
  8277. %@NL@%
  8278. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8279. %@NL@%
  8280. %@AS@%  
  8281. %@AS@%  
  8282. %@AS@%  Status: 0000 - clear
  8283. %@AS@%  Status: 0030 - inexact, underflow
  8284. %@AS@%  Status: 0002 - denormal %@AE@%%@NL@%
  8285. %@NL@%
  8286. %@NL@%
  8287. %@NL@%
  8288. %@NL@%
  8289. %@QR:clearerr@%%@NL@%
  8290. %@2@%%@CR:C6A00410269 @%%@AB@%clearerr%@AE@%%@EH@%%@NL@%
  8291. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8292. %@NL@%
  8293. %@NL@%
  8294. %@3@%%@AB@%Description%@CR:C6A00410270 @%%@CR:C6A00410271 @% %@CR:C6A00410272 @%%@CR:C6A00410273 @% %@CR:C6A00410274 @%%@CR:C6A00410275 @% %@CR:C6A00410276 @%%@AE@%%@EH@%%@NL@%
  8295. %@NL@%
  8296. Resets the error indicator for a stream.  %@NL@%
  8297. %@NL@%
  8298. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  8299. %@NL@%
  8300. %@AS@%  void clearerr( FILE *stream );%@AE@%%@NL@%
  8301. %@NL@%
  8302. %@AI@%stream%@AE@%                            Pointer to%@AB@% FILE structure%@AE@%
  8303.  
  8304. %@NL@%
  8305. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8306. %@NL@%
  8307. The %@AB@%clearerr%@AE@% function resets the error indicator and end-of-file indicator
  8308. for %@AI@%stream%@AE@%. Error indicators are not automatically cleared; once the error
  8309. indicator for a specified stream is set, operations on that stream continue
  8310. to return an error value until %@AB@%clearerr%@AE@%,%@AB@% fseek%@AE@%,%@AB@% fsetpos%@AE@%,%@AB@% %@AE@%or %@AB@%rewind%@AE@% is
  8311. called.  %@NL@%
  8312. %@NL@%
  8313. %@NL@%
  8314. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8315. %@NL@%
  8316. None.  %@NL@%
  8317. %@NL@%
  8318. %@NL@%
  8319. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8320. %@NL@%
  8321. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  8322. %@NL@%
  8323. %@NL@%
  8324. %@NL@%
  8325. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8326. %@NL@%
  8327. %@AB@%eof%@AE@%, %@AB@%feof%@AE@%, %@AB@%ferror%@AE@%, %@AB@%perror%@AE@%  %@NL@%
  8328. %@NL@%
  8329. %@NL@%
  8330. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8331. %@NL@%
  8332. %@AS@%  /* CLEARERR.C: This program creates an error on the standard input
  8333. %@AS@%   * stream, then clears it so that future reads won't fail.
  8334. %@AS@%   */
  8335. %@AS@%  
  8336. %@AS@%  #include <stdio.h>
  8337. %@AS@%  
  8338. %@AS@%  void main()
  8339. %@AS@%  {
  8340. %@AS@%     int c;
  8341. %@AS@%  
  8342. %@AS@%     /* Create an error by writing to standard input. */
  8343. %@AS@%     putc( 'c', stdin );
  8344. %@AS@%     if( ferror( stdin ) )
  8345. %@AS@%     {
  8346. %@AS@%        perror( "Write error" );
  8347. %@AS@%        clearerr( stdin );
  8348. %@AS@%     }%@AE@%%@NL@%
  8349. %@NL@%
  8350. %@AS@%  /* See if read causes an error. */
  8351. %@AS@%     printf( "Will input cause an error? " );
  8352. %@AS@%     c = getc( stdin );
  8353. %@AS@%     if( ferror( stdin ) )
  8354. %@AS@%     {
  8355. %@AS@%        perror( "Read error" );
  8356. %@AS@%        clearerr( stdin );
  8357. %@AS@%     }
  8358. %@AS@%  }%@AE@%%@NL@%
  8359. %@NL@%
  8360. %@NL@%
  8361. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8362. %@NL@%
  8363. %@AS@%  
  8364. %@AS@%  
  8365. %@AS@%  Write error: Error 0
  8366. %@AS@%  Will input cause an error? n%@AE@%%@NL@%
  8367. %@NL@%
  8368. %@NL@%
  8369. %@NL@%
  8370. %@NL@%
  8371. %@QR:_clearscreen@%%@NL@%
  8372. %@2@%%@CR:C6A00420277 @%%@AB@%_clearscreen%@AE@%%@EH@%%@NL@%
  8373. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8374. %@NL@%
  8375. %@NL@%
  8376. %@3@%%@AB@%Description%@CR:C6A00420278 @%%@AE@%%@EH@%%@NL@%
  8377. %@NL@%
  8378. Clears the specified area of the screen.  %@NL@%
  8379. %@NL@%
  8380. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  8381. %@NL@%
  8382. %@AS@%  void _far _clearscreen( short area );%@AE@%%@NL@%
  8383. %@NL@%
  8384. %@AI@%area%@AE@%                              Target area
  8385.  
  8386. %@NL@%
  8387. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8388. %@NL@%
  8389. The %@AB@%_clearscreen%@AE@% function erases the target area, filling it with the
  8390. current background color. The %@AI@%area%@AE@% parameter can be one of the following
  8391. manifest constants (defined in GRAPH.H):  %@NL@%
  8392. %@NL@%
  8393. %@AB@%Constant%@AE@%                          %@AB@%Action%@AE@%
  8394. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8395. %@AB@%_GCLEARSCREEN%@AE@%                     Clears and fills the entire screen
  8396.  
  8397. %@AB@%_GVIEWPORT%@AE@%                        Clears and fills only within the current
  8398.                                   view port
  8399.  
  8400. %@AB@%_GWINDOW%@AE@%                          Clears and fills only within the current
  8401.                                   text window
  8402.  
  8403. %@NL@%
  8404. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8405. %@NL@%
  8406. None.  %@NL@%
  8407. %@NL@%
  8408. %@NL@%
  8409. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8410. %@NL@%
  8411.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8412. %@NL@%
  8413. %@NL@%
  8414. %@NL@%
  8415. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8416. %@NL@%
  8417. %@AB@%_getbkcolor%@AE@%, %@AB@% _setbkcolor%@AE@%  %@NL@%
  8418. %@NL@%
  8419. %@NL@%
  8420. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8421. %@NL@%
  8422. %@AS@%  /* CLRSCRN.C */
  8423. %@AS@%  #include <conio.h>
  8424. %@AS@%  #include <graph.h>
  8425. %@AS@%  #include <stdlib.h>
  8426. %@AS@%  
  8427. %@AS@%  void main()
  8428. %@AS@%  {
  8429. %@AS@%     short xhalf, yhalf, xquar, yquar;
  8430. %@AS@%     struct videoconfig vc;%@AE@%%@NL@%
  8431. %@NL@%
  8432. %@AS@%  /* Find a valid graphics mode. */
  8433. %@AS@%     if( !_setvideomode( _MAXRESMODE ) )
  8434. %@AS@%        exit( 1 );
  8435. %@AS@%  
  8436. %@AS@%     _getvideoconfig( &vc );
  8437. %@AS@%  
  8438. %@AS@%     xhalf = vc.numxpixels / 2;
  8439. %@AS@%     yhalf = vc.numypixels / 2;
  8440. %@AS@%     xquar = xhalf / 2;
  8441. %@AS@%     yquar = yhalf / 2;
  8442. %@AS@%  
  8443. %@AS@%     _setviewport( 0, 0, xhalf - 1, yhalf - 1 );
  8444. %@AS@%     _rectangle( _GBORDER, 0,  0, xhalf - 1, yhalf - 1 );
  8445. %@AS@%     _ellipse( _GFILLINTERIOR, xquar / 4, yquar / 4,
  8446. %@AS@%                         xhalf - (xquar / 4), yhalf - (yquar / 4) );
  8447. %@AS@%     getch();
  8448. %@AS@%     _clearscreen( _GVIEWPORT );
  8449. %@AS@%  
  8450. %@AS@%     getch();
  8451. %@AS@%     _setvideomode( _DEFAULTMODE );
  8452. %@AS@%  }%@AE@%%@NL@%
  8453. %@NL@%
  8454. %@NL@%
  8455. %@NL@%
  8456. %@NL@%
  8457. %@QR:clock@%%@NL@%
  8458. %@2@%%@CR:C6A00430279 @%%@AB@%clock%@AE@%%@EH@%%@NL@%
  8459. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8460. %@NL@%
  8461. %@NL@%
  8462. %@3@%%@AB@%Description%@CR:C6A00430280 @%%@CR:C6A00430281 @%%@AE@%%@EH@%%@NL@%
  8463. %@NL@%
  8464. Calculates the time used by the calling process.  %@NL@%
  8465. %@NL@%
  8466. %@AS@%  #include <time.h>%@AE@%%@NL@%
  8467. %@NL@%
  8468. %@AS@%  clock_t clock( void );%@AE@%%@NL@%
  8469. %@NL@%
  8470. %@NL@%
  8471. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8472. %@NL@%
  8473. The %@AB@%clock%@AE@% function tells how much processor time has been used by the
  8474. calling process. The time in seconds is approximated by dividing the %@AB@%clock%@AE@%
  8475. return value by the value of the %@AB@%CLOCKS_PER_SEC%@AE@% constant.  %@NL@%
  8476. %@NL@%
  8477. In other words, the %@AB@%clock%@AE@% function returns the number of processor timer
  8478. ticks that have elapsed. A timer tick is approximately equal to
  8479. 1/%@AB@%CLOCKS_PER_SEC%@AE@% seconds.  %@NL@%
  8480. %@NL@%
  8481. %@NL@%
  8482. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8483. %@NL@%
  8484. The %@AB@%clock%@AE@% function returns the product of the time in seconds and the value
  8485. of the %@AB@%CLOCKS_PER_SEC%@AE@% constant. If the processor time is not available, the
  8486. function returns the value -1, cast as %@AB@%clock_t%@AE@%.  %@NL@%
  8487. %@NL@%
  8488. %@NL@%
  8489. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8490. %@NL@%
  8491. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8492. %@NL@%
  8493. %@NL@%
  8494. In both DOS and OS/2, %@AB@%clock%@AE@% returns the time elapsed since the process
  8495. started. This may not be equal to the actual processor time used by the
  8496. process.  %@NL@%
  8497. %@NL@%
  8498. In previous versions of Microsoft C, the %@AB@%CLOCKS_PER_SEC%@AE@% constant was called
  8499. %@AB@%CLK_TCK%@AE@%.  %@NL@%
  8500. %@NL@%
  8501. %@NL@%
  8502. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8503. %@NL@%
  8504. %@AB@%difftime%@AE@%, %@AB@%time%@AE@%  %@NL@%
  8505. %@NL@%
  8506. %@NL@%
  8507. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8508. %@NL@%
  8509. %@AS@%  /* CLOCK.C: This example prompts for how long the program is to run and
  8510. %@AS@%   * then continuously displays the elapsed time for that period.
  8511. %@AS@%   */
  8512. %@AS@%  
  8513. %@AS@%  #include <stdio.h>
  8514. %@AS@%  #include <stdlib.h>
  8515. %@AS@%  #include <time.h>
  8516. %@AS@%  
  8517. %@AS@%  void sleep( clock_t wait );
  8518. %@AS@%  
  8519. %@AS@%  void main()
  8520. %@AS@%  {
  8521. %@AS@%     long    i = 600000L;
  8522. %@AS@%     clock_t start, finish;
  8523. %@AS@%     double  duration;
  8524. %@AS@%  
  8525. %@AS@%     /* Delay for a specified time. */
  8526. %@AS@%     printf( "Delay for three seconds\n" );
  8527. %@AS@%     sleep( (clock_t)3 * CLOCKS_PER_SEC );
  8528. %@AS@%     printf( "Done!\n" );
  8529. %@AS@%  
  8530. %@AS@%     /* Measure the duration of an event. */
  8531. %@AS@%     printf( "Time to do %ld empty loops is ", i );
  8532. %@AS@%     start = clock();
  8533. %@AS@%     while( i-- )
  8534. %@AS@%        ;
  8535. %@AS@%     finish = clock();
  8536. %@AS@%     duration = (double)(finish - start) / CLOCKS_PER_SEC;
  8537. %@AS@%     printf( "%2.1f seconds\n", duration );
  8538. %@AS@%  }
  8539. %@AS@%  
  8540. %@AS@%  /* Pauses for a specified number of microseconds. */
  8541. %@AS@%  void sleep( clock_t wait )
  8542. %@AS@%  {
  8543. %@AS@%      clock_t goal;
  8544. %@AS@%  
  8545. %@AS@%      goal = wait + clock();
  8546. %@AS@%      while( goal > clock() )
  8547. %@AS@%          ;
  8548. %@AS@%  }%@AE@%%@NL@%
  8549. %@NL@%
  8550. %@NL@%
  8551. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8552. %@NL@%
  8553. %@AS@%  
  8554. %@AS@%  
  8555. %@AS@%  Delay for five seconds
  8556. %@AS@%  Done!
  8557. %@AS@%  Time to do 900000 empty loops is 2.0 seconds%@AE@%%@NL@%
  8558. %@NL@%
  8559. %@NL@%
  8560. %@NL@%
  8561. %@NL@%
  8562. %@QR:close@%%@NL@%
  8563. %@2@%%@CR:C6A00440282 @%%@AB@%close%@AE@%%@EH@%%@NL@%
  8564. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8565. %@NL@%
  8566. %@NL@%
  8567. %@3@%%@AB@%Description%@CR:C6A00440283 @%%@CR:C6A00440284 @%%@CR:C6A00440285 @%%@AE@%%@EH@%%@NL@%
  8568. %@NL@%
  8569. Closes a file.  %@NL@%
  8570. %@NL@%
  8571. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  8572.  
  8573. %@AB@%#include <errno.h>%@AE@%                
  8574.  
  8575. %@AS@%  int close( int handle );%@AE@%%@NL@%
  8576. %@NL@%
  8577. %@AI@%handle%@AE@%                            Handle referring to open file
  8578.  
  8579. %@NL@%
  8580. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8581. %@NL@%
  8582. The %@AB@%close%@AE@% function closes the file associated with %@AI@%handle%@AE@%.  %@NL@%
  8583. %@NL@%
  8584. %@NL@%
  8585. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8586. %@NL@%
  8587. The %@AB@%close%@AE@% function returns 0 if the file was successfully closed. A return
  8588. value of -1 indicates an error, and %@AB@%errno%@AE@% is set to %@AB@%EBADF%@AE@%, indicating an
  8589. invalid file-handle argument.  %@NL@%
  8590. %@NL@%
  8591. %@NL@%
  8592. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8593. %@NL@%
  8594.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  8595. %@NL@%
  8596. %@NL@%
  8597. %@NL@%
  8598. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8599. %@NL@%
  8600. %@AB@%chsize%@AE@%, %@AB@%creat%@AE@%, %@AB@%dup%@AE@%, %@AB@%dup2%@AE@%, %@AB@%open%@AE@%, %@AB@%unlink%@AE@%  %@NL@%
  8601. %@NL@%
  8602. %@NL@%
  8603. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8604. %@NL@%
  8605. %@AS@%  /* OPEN.C: This program uses open to open a file named OPEN.C for input
  8606. %@AS@%   * and a file named OPEN.OUT for output. The files are then closed.
  8607. %@AS@%   */
  8608. %@AS@%  
  8609. %@AS@%  #include <fcntl.h>
  8610. %@AS@%  #include <sys\types.h>
  8611. %@AS@%  #include <sys\stat.h>
  8612. %@AS@%  #include <io.h>
  8613. %@AS@%  #include <stdio.h>
  8614. %@AS@%  
  8615. %@AS@%  void main()
  8616. %@AS@%  {
  8617. %@AS@%     int fh1, fh2;
  8618. %@AS@%     fh1 = open( "OPEN.C", O_RDONLY );
  8619. %@AS@%     if( fh1 == -1 )
  8620. %@AS@%        perror( "open failed on input file" );
  8621. %@AS@%     else
  8622. %@AS@%     {
  8623. %@AS@%        printf( "open succeeded on input file\n" );
  8624. %@AS@%        close( fh1 );
  8625. %@AS@%     }%@AE@%%@NL@%
  8626. %@NL@%
  8627. %@AS@%  fh2 = open( "OPEN.OUT", O_WRONLY | O_CREAT, S_IREAD | S_IWRITE );
  8628. %@AS@%     if( fh2 == -1 )
  8629. %@AS@%        perror( "open failed on output file" );
  8630. %@AS@%     else
  8631. %@AS@%     {
  8632. %@AS@%        printf( "open succeeded on output file\n" );
  8633. %@AS@%        close( fh2 );
  8634. %@AS@%     }
  8635. %@AS@%  }%@AE@%%@NL@%
  8636. %@NL@%
  8637. %@NL@%
  8638. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8639. %@NL@%
  8640. %@AS@%  
  8641. %@AS@%  
  8642. %@AS@%  open succeeded on input file
  8643. %@AS@%  open succeeded on output file%@AE@%%@NL@%
  8644. %@NL@%
  8645. %@NL@%
  8646. %@NL@%
  8647. %@NL@%
  8648. %@QR:_control87@%%@NL@%
  8649. %@2@%%@CR:C6A00450286 @%%@AB@%_control87%@AE@%%@EH@%%@NL@%
  8650. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8651. %@NL@%
  8652. %@NL@%
  8653. %@3@%%@AB@%Description%@CR:C6A00450287 @% %@CR:C6A00450288 @%%@CR:C6A00450289 @%%@AE@%%@EH@%%@NL@%
  8654. %@NL@%
  8655. Gets and sets the floating-point control word.  %@NL@%
  8656. %@NL@%
  8657. %@AS@%  #include <float.h>%@AE@%%@NL@%
  8658. %@NL@%
  8659. %@AS@%  unsigned int _control87( unsigned int new, unsigned int mask );%@AE@%%@NL@%
  8660. %@NL@%
  8661. %@AI@%new%@AE@%                               New control-word bit values
  8662.  
  8663. %@AI@%mask%@AE@%                              Mask for new control-word bits to set
  8664.  
  8665. %@NL@%
  8666. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8667. %@NL@%
  8668. The %@AB@%_control87%@AE@% function gets and sets the floating-point control word. The
  8669. floating-point control word allows the program to change the precision,
  8670. rounding, and infinity modes in the floating-point-math package.
  8671. Floating-point exceptions can also be masked or unmasked using the
  8672. %@AB@%_control87%@AE@% function.  %@NL@%
  8673. %@NL@%
  8674. If the value for %@AI@%mask%@AE@% is equal to 0, then %@AB@%_control87%@AE@% gets the floating-point
  8675. control word. If %@AI@%mask%@AE@% is nonzero, then a new value for the control word is
  8676. set in the following manner: for any bit that is on (equal to 1) in %@AI@%mask%@AE@%,
  8677. the corresponding bit in %@AI@%new%@AE@% is used to update the control word. To put it
  8678. another way,  %@NL@%
  8679. %@NL@%
  8680. %@AS@%  fpcntrl = ((fpcntrl & ~mask) | (new & mask))%@AE@%%@NL@%
  8681. %@NL@%
  8682. where %@AS@% fpcntrl %@AE@% is the floating-point control word.  %@NL@%
  8683. %@NL@%
  8684. The possible values for the mask constant (%@AI@%mask%@AE@%) and new control values
  8685. (%@AI@%new%@AE@%) are shown in Table R.1.  %@NL@%
  8686. %@NL@%
  8687. %@AB@%Table   R.1 Hex Values%@AE@%
  8688.  
  8689. %@TH:  56  1588 02 13 11 17 35 @%Mask         Hex Value  Constant         Hex Value%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%MCW_EM       0x003F     (Interrupt              exception)                                      %@AB@%EM_INVALID%@AE@%       0x0001                         %@AB@%EM_DENORMAL%@AE@%      0x0002                         %@AB@%EM_ZERODIVIDE%@AE@%    0x0004                         %@AB@%EM_OVERFLOW%@AE@%      0x0008                         %@AB@%EM_UNDERFLOW%@AE@%     0x0010                         %@AB@%EM_INEXACT%@AE@%       0x0020                         MCW_IC       0x1000     (Infinity               control)                                        %@AB@%IC_AFFINE%@AE@%        0x1000                         %@AB@%IC_PROJECTIVE%@AE@%    0x0000                         MCW_RC       0x0C00     (Rounding               control)                                        %@AB@%RC_CHOP%@AE@%          0x0C00                         %@AB@%RC_UP%@AE@%            0x0800                         %@AB@%RC_DOWN%@AE@%          0x0400                         %@AB@%RC_NEAR%@AE@%          0x0000                         MCW_PC       0x0300     (Precision              control)                                        %@AB@%PC_24 (24 bits)%@AE@%  0x0000                         %@AB@%PC_53 (53 bits)%@AE@%  0x0200                         %@AB@%PC_64 (64 bits)%@AE@%  0x0300 %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  56  1588 02 13 11 17 35 @%
  8690.  
  8691. %@NL@%
  8692. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8693. %@NL@%
  8694. The bits in the value returned indicate the floating-point control state.
  8695. See the FLOAT.H include file for a complete definition of the bits returned
  8696. by %@AB@%_control87%@AE@%.  %@NL@%
  8697. %@NL@%
  8698. %@NL@%
  8699. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8700. %@NL@%
  8701.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8702. %@NL@%
  8703. %@NL@%
  8704. %@NL@%
  8705. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8706. %@NL@%
  8707. %@AB@%_clear87%@AE@%, %@AB@% _status87%@AE@%  %@NL@%
  8708. %@NL@%
  8709. %@NL@%
  8710. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8711. %@NL@%
  8712. %@AS@%  /* CNTRL87.C: This program uses _control87 to output the control word,
  8713. %@AS@%   * set the precision to 24 bits, and reset the status to the default.
  8714. %@AS@%   */
  8715. %@AS@%  
  8716. %@AS@%  #include <stdio.h>
  8717. %@AS@%  #include <float.h>%@AE@%%@NL@%
  8718. %@NL@%
  8719. %@AS@%  void main()
  8720. %@AS@%  {
  8721. %@AS@%     double a = 0.1;
  8722. %@AS@%  
  8723. %@AS@%     /* Show original control word and do calculation. */
  8724. %@AS@%     printf( "Original: 0x%.4x\n", _control87( 0, 0 ) );
  8725. %@AS@%     printf( "%1.1f * %1.1f = %.15e\n", a, a, a * a );
  8726. %@AS@%  
  8727. %@AS@%     /* Set precision to 24 bits and recalculate. */
  8728. %@AS@%     printf( "24-bit:   0x%.4x\n", _control87( PC_24, MCW_PC ) );
  8729. %@AS@%     printf( "%1.1f * %1.1f = %.15e\n", a, a, a * a );
  8730. %@AS@%  
  8731. %@AS@%     /* Restore to default and recalculate. */
  8732. %@AS@%     printf( "Default:  0x%.4x\n", _control87( CW_DEFAULT, 0xffff ) );
  8733. %@AS@%     printf( "%1.1f * %1.1f = %.15e\n", a, a, a * a );
  8734. %@AS@%  }%@AE@%%@NL@%
  8735. %@NL@%
  8736. %@NL@%
  8737. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8738. %@NL@%
  8739. %@AS@%  
  8740. %@AS@%  
  8741. %@AS@%  Original: 0x1332
  8742. %@AS@%  0.1 * 0.1 = 1.000000000000000e-002
  8743. %@AS@%  24-bit:   0x1332
  8744. %@AS@%  0.1 * 0.1 = 9.999999776482582e-003
  8745. %@AS@%  Default:  0x1032
  8746. %@AS@%  0.1 * 0.1 = 1.000000000000000e-002%@AE@%%@NL@%
  8747. %@NL@%
  8748. %@NL@%
  8749. %@NL@%
  8750. %@NL@%
  8751. %@QR:cos@%%@NL@%
  8752. %@2@%%@CR:C6A00460290 @%%@AB@%cos Functions%@AE@%%@EH@%%@NL@%
  8753. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8754. %@NL@%
  8755. %@NL@%
  8756. %@3@%%@AB@%Description%@CR:C6A00460291 @%%@CR:C6A00460292 @%%@CR:C6A00460293 @% %@CR:C6A00460294 @%%@AE@%%@EH@%%@NL@%
  8757. %@NL@%
  8758. Calculate the cosine (%@AB@%cos%@AE@% and %@AB@%cosl%@AE@%) or hyperbolic cosine (%@AB@%cosh%@AE@% and %@AB@%coshl%@AE@%).  %@NL@%
  8759. %@NL@%
  8760. %@AS@%  #include <math.h>%@AE@%%@NL@%
  8761. %@NL@%
  8762. %@AS@%  double cos( double x );%@AE@%%@NL@%
  8763. %@NL@%
  8764. %@AS@%  double cosh( double x );%@AE@%%@NL@%
  8765. %@NL@%
  8766. %@AS@%  long double cosl( long double x );%@AE@%%@NL@%
  8767. %@NL@%
  8768. %@AS@%  long double coshl( long double x );%@AE@%%@NL@%
  8769. %@NL@%
  8770. %@AI@%x%@AE@%                                 Angle in radians
  8771.  
  8772. %@NL@%
  8773. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8774. %@NL@%
  8775. The %@AB@%cos%@AE@% and %@AB@%cosh%@AE@% functions return the cosine and hyperbolic cosine,
  8776. respectively, of %@AI@%x%@AE@%.  %@NL@%
  8777. %@NL@%
  8778. The %@AB@%cosl%@AE@% and %@AB@%coshl%@AE@% functions are the 80-bit counterparts and use the 80-bit,
  8779. 10-byte coprocessor form of arguments and return values. See the reference
  8780. page on the long double functions for more details on this data type.%@AB@%  %@AE@%%@NL@%
  8781. %@NL@%
  8782. %@NL@%
  8783. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8784. %@NL@%
  8785. If %@AI@%x%@AE@% is large, a partial loss of significance in the result may occur in a
  8786. call to %@AB@%cos%@AE@%, in which case the function generates a %@AB@%PLOSS%@AE@% error. If %@AI@%x%@AE@% is so
  8787. large that significance is completely lost, %@AB@%cos%@AE@% prints a %@AB@%TLOSS%@AE@% message to
  8788. %@AB@%stderr%@AE@% and returns 0. In both cases, %@AB@%errno%@AE@% is set to %@AB@%ERANGE.%@AE@%  %@NL@%
  8789. %@NL@%
  8790. If the result is too large in a %@AB@%cosh%@AE@% call, the function returns %@AB@%HUGE_VAL%@AE@% and
  8791. sets %@AB@%errno%@AE@% to %@AB@%ERANGE%@AE@%.  %@NL@%
  8792. %@NL@%
  8793. %@NL@%
  8794. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8795. %@NL@%
  8796. %@AB@%cos%@AE@%,%@AB@% cosh%@AE@%  %@NL@%
  8797. %@NL@%
  8798. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  8799. %@NL@%
  8800. %@NL@%
  8801. %@AB@%cosl%@AE@%, %@AB@%coshl%@AE@%  %@NL@%
  8802. %@NL@%
  8803.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8804. %@NL@%
  8805. %@NL@%
  8806. %@NL@%
  8807. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8808. %@NL@%
  8809. %@AB@%acos %@AE@%functions, %@AB@%asin %@AE@%functions, %@AB@%atan%@AE@% functions, %@AB@%matherr%@AE@%, %@AB@%sin%@AE@% functions, %@AB@%tan%@AE@%
  8810. functions  %@NL@%
  8811. %@NL@%
  8812. %@NL@%
  8813. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8814. %@NL@%
  8815. %@AS@%  /* SINCOS.C: This program displays the sine, hyperbolic sine, cosine,
  8816. %@AS@%   * and hyperbolic cosine of pi / 2.
  8817. %@AS@%   */
  8818. %@AS@%  
  8819. %@AS@%  #include <math.h>
  8820. %@AS@%  #include <stdio.h>
  8821. %@AS@%  
  8822. %@AS@%  void main()
  8823. %@AS@%  {
  8824. %@AS@%     double pi = 3.1415926535;
  8825. %@AS@%     double x, y;
  8826. %@AS@%  
  8827. %@AS@%     x = pi / 2;
  8828. %@AS@%     y = sin( x );
  8829. %@AS@%     printf( "sin( %f ) = %f\n", x, y );
  8830. %@AS@%     y = sinh( x );
  8831. %@AS@%     printf( "sinh( %f ) = %f\n",x, y );
  8832. %@AS@%     y = cos( x );
  8833. %@AS@%     printf( "cos( %f ) = %f\n", x, y );
  8834. %@AS@%     y = cosh( x );
  8835. %@AS@%     printf( "cosh( %f ) = %f\n",x, y );
  8836. %@AS@%  }%@AE@%%@NL@%
  8837. %@NL@%
  8838. %@NL@%
  8839. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8840. %@NL@%
  8841. %@AS@%  
  8842. %@AS@%  
  8843. %@AS@%  sin( 1.570796 ) = 1.000000
  8844. %@AS@%  sinh( 1.570796 ) = 2.301299
  8845. %@AS@%  cos( 1.570796 ) = 0.000000
  8846. %@AS@%  cosh( 1.570796 ) = 2.509178 %@AE@%%@NL@%
  8847. %@NL@%
  8848. %@NL@%
  8849. %@NL@%
  8850. %@NL@%
  8851. %@QR:cprintf@%%@NL@%
  8852. %@2@%%@CR:C6A00470295 @%%@AB@%cprintf%@AE@%%@EH@%%@NL@%
  8853. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8854. %@NL@%
  8855. %@NL@%
  8856. %@3@%%@AB@%Description%@CR:C6A00470296 @%%@CR:C6A00470297 @% %@CR:C6A00470298 @%%@CR:C6A00470299 @% %@CR:C6A00470300 @%%@CR:C6A00470301 @%%@AE@%%@EH@%%@NL@%
  8857. %@NL@%
  8858. Formats and prints to the console.  %@NL@%
  8859. %@NL@%
  8860. %@AB@%#include <conio.h>%@AE@%                Required only for function declarations
  8861.  
  8862. %@AS@%  int cprintf( char *format [[, argument]] ... );%@AE@%%@NL@%
  8863. %@NL@%
  8864. %@AI@%format%@AE@%                            Format control string
  8865.  
  8866. %@AI@%argument%@AE@%                          Optional arguments
  8867.  
  8868. %@NL@%
  8869. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8870. %@NL@%
  8871. The %@AB@%cprintf%@AE@% function formats and prints a series of characters and values
  8872. directly to the console, using the %@AB@%putch%@AE@% function to output characters. Each
  8873. %@AI@%argument%@AE@% (if any) is converted and output according to the corresponding
  8874. format specification in %@AI@%format%@AE@%. The format has the same form and function as
  8875. the %@AI@%format%@AE@% argument for the %@AB@%printf%@AE@% function; see %@AB@%printf%@AE@% for a description of
  8876. the format and arguments.  %@NL@%
  8877. %@NL@%
  8878. Note that unlike the %@AB@%fprintf%@AE@%, %@AB@%printf%@AE@%, and %@AB@%sprintf%@AE@% functions, %@AB@%cprintf%@AE@% does
  8879. not translate line-feed characters into carriage-return-line-feed
  8880. combinations on output.  %@NL@%
  8881. %@NL@%
  8882. %@NL@%
  8883. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8884. %@NL@%
  8885. The %@AB@%cprintf%@AE@% function returns the number of characters printed.  %@NL@%
  8886. %@NL@%
  8887. %@NL@%
  8888. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8889. %@NL@%
  8890.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8891. %@NL@%
  8892. %@NL@%
  8893. %@NL@%
  8894. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8895. %@NL@%
  8896. %@AB@%cscanf, fprintf%@AE@%, %@AB@%printf%@AE@%, %@AB@%sprintf%@AE@%, %@AB@%vprintf%@AE@%  %@NL@%
  8897. %@NL@%
  8898. %@NL@%
  8899. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8900. %@NL@%
  8901. %@AS@%  /* CPRINTF.C: This program displays some variables to the console. */
  8902. %@AS@%  
  8903. %@AS@%  #include <conio.h>
  8904. %@AS@%  
  8905. %@AS@%  void main()
  8906. %@AS@%  {
  8907. %@AS@%     int      i = -16, h = 29;
  8908. %@AS@%     unsigned u = 62511;
  8909. %@AS@%     char     c = 'A';
  8910. %@AS@%     char     s[] = "Test";%@AE@%%@NL@%
  8911. %@NL@%
  8912. %@AS@%  /* Note that console output does not translate \n as
  8913. %@AS@%      * standard output does. Use \r\n instead.
  8914. %@AS@%      */
  8915. %@AS@%     cprintf( "%d  %.4x  %u  %c %s\r\n", i, h, u, c, s );
  8916. %@AS@%  
  8917. %@AS@%  }%@AE@%%@NL@%
  8918. %@NL@%
  8919. %@NL@%
  8920. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8921. %@NL@%
  8922. %@AS@%  
  8923. %@AS@%  
  8924. %@AS@%  -16  001d  62511  A Test%@AE@%%@NL@%
  8925. %@NL@%
  8926. %@NL@%
  8927. %@NL@%
  8928. %@NL@%
  8929. %@QR:cputs@%%@NL@%
  8930. %@2@%%@CR:C6A00480302 @%%@AB@%cputs%@AE@%%@EH@%%@NL@%
  8931. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8932. %@NL@%
  8933. %@NL@%
  8934. %@3@%%@AB@%Description%@CR:C6A00480303 @%%@CR:C6A00480304 @% %@CR:C6A00480305 @%%@CR:C6A00480306 @%%@AE@%%@EH@%%@NL@%
  8935. %@NL@%
  8936. Puts a string to the console.  %@NL@%
  8937. %@NL@%
  8938. %@AB@%#include <conio.h>%@AE@%                Required only for function declarations
  8939.  
  8940. %@AS@%  int cputs( char *string );%@AE@%%@NL@%
  8941. %@NL@%
  8942. %@AI@%string%@AE@%                            Output string
  8943.  
  8944. %@NL@%
  8945. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  8946. %@NL@%
  8947. The %@AB@%cputs%@AE@% function writes the null-terminated string pointed to by %@AI@%string%@AE@%
  8948. directly to the console. Note that a carriage-return-line-feed (CR-LF)
  8949. combination is not automatically appended to the string.  %@NL@%
  8950. %@NL@%
  8951. %@NL@%
  8952. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  8953. %@NL@%
  8954. If successful, %@AB@%cputs%@AE@% returns a 0. If the function fails, it returns a
  8955. nonzero value.  %@NL@%
  8956. %@NL@%
  8957. %@NL@%
  8958. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  8959. %@NL@%
  8960.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  8961. %@NL@%
  8962. %@NL@%
  8963. %@NL@%
  8964. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  8965. %@NL@%
  8966. %@AB@%putch%@AE@%  %@NL@%
  8967. %@NL@%
  8968. %@NL@%
  8969. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  8970. %@NL@%
  8971. %@AS@%  /* CPUTS.C: This program first displays a string to the console. */
  8972. %@AS@%  
  8973. %@AS@%  #include <conio.h>
  8974. %@AS@%  
  8975. %@AS@%  void main()
  8976. %@AS@%  {
  8977. %@AS@%     /* String to print at console. Note the \r (return) character. */
  8978. %@AS@%     char *buffer = "Hello world (courtesy of cputs)!\r\n";
  8979. %@AS@%  
  8980. %@AS@%     cputs( buffer );
  8981. %@AS@%  }%@AE@%%@NL@%
  8982. %@NL@%
  8983. %@NL@%
  8984. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  8985. %@NL@%
  8986. %@AS@%  
  8987. %@AS@%  
  8988. %@AS@%  Hello world (courtesy of cputs)! %@AE@%%@NL@%
  8989. %@NL@%
  8990. %@NL@%
  8991. %@NL@%
  8992. %@NL@%
  8993. %@QR:creat@%%@NL@%
  8994. %@2@%%@CR:C6A00490307 @%%@AB@%creat%@AE@%%@EH@%%@NL@%
  8995. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  8996. %@NL@%
  8997. %@NL@%
  8998. %@3@%%@AB@%Description%@CR:C6A00490308 @%%@CR:C6A00490309 @%%@CR:C6A00490310 @% %@CR:C6A00490311 @%%@AE@%%@EH@%%@NL@%
  8999. %@NL@%
  9000. Creates a new file.  %@NL@%
  9001. %@NL@%
  9002. %@AB@%#include <sys\types.h>%@AE@%            
  9003.  
  9004. %@AB@%#include <sys\stat.h>%@AE@%             
  9005.  
  9006. %@AB@%#include <errno.h>%@AE@%                
  9007.  
  9008. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  9009.  
  9010. %@AS@%  int creat( char *filename, int pmode );%@AE@%%@NL@%
  9011. %@NL@%
  9012. %@AI@%filename%@AE@%                          Path name of new file
  9013.  
  9014. %@AI@%pmode%@AE@%                             Permission setting
  9015.  
  9016. %@NL@%
  9017. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9018. %@NL@%
  9019. The %@AB@%creat%@AE@% function either creates a new file or opens and truncates an
  9020. existing file. If the file specified by %@AI@%filename%@AE@% does not exist, a new file
  9021. is created with the given permission setting and is opened for writing. If
  9022. the file already exists and its permission setting allows writing, %@AB@%creat%@AE@%
  9023. truncates the file to length 0, destroying the previous contents, and opens
  9024. it for writing.  %@NL@%
  9025. %@NL@%
  9026. The permission setting, %@AI@%pmode%@AE@%, applies to newly created files only. The new
  9027. file receives the specified permission setting after it is closed for the
  9028. first time. The integer expression %@AI@%pmode%@AE@% contains one or both of the
  9029. manifest constants %@AB@%S_IWRITE%@AE@% and%@AB@% S_IREAD%@AE@%, defined in SYS\STAT.H. When both of
  9030. the constants are given, they are joined with the bitwise-OR operator ( | ).
  9031. The %@AI@%pmode%@AE@% argument is set to one of the following values: %@CR:C6A00490312 @%  %@NL@%
  9032. %@NL@%
  9033. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  9034. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9035. %@AB@%S_IWRITE%@AE@%                          Writing permitted
  9036.  
  9037. %@AB@%S_IREAD%@AE@%                           Reading permitted
  9038.  
  9039. %@AB@%S_IREAD%@AE@% | %@AB@%S_IWRITE%@AE@%                Reading and writing permitted
  9040.  
  9041. If write permission is not given, the file is read-only. Under DOS and OS/2,
  9042. it is not possible to give write-only permission. Thus, the %@AB@%S_IWRITE%@AE@% and
  9043. %@AB@%S_IREAD%@AE@% | %@AB@%S_IWRITE%@AE@% modes are equivalent. Under DOS versions 3.0 and later,
  9044. files opened using %@AB@%creat%@AE@% are always opened in compatibility mode (see%@AB@%
  9045. %@AB@%sopen%@AE@%).  %@NL@%
  9046. %@NL@%
  9047. The %@AB@%creat%@AE@% function applies the current file-permission mask to %@AI@%pmode%@AE@% before
  9048. setting the permissions (see %@AB@%umask%@AE@%).  %@NL@%
  9049. %@NL@%
  9050. Note that the %@AB@%creat%@AE@% routine is provided primarily for compatibility with
  9051. previous libraries. A call to %@AB@%open%@AE@% with %@AB@%O_CREAT%@AE@% and %@AB@%O_TRUNC%@AE@% in the %@AI@%oflag
  9052. %@AI@%%@AE@%argument is equivalent to %@AB@%creat%@AE@% and is preferable for new code.  %@NL@%
  9053. %@NL@%
  9054. %@NL@%
  9055. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9056. %@NL@%
  9057. If successful, %@AB@%creat%@AE@% returns a handle for the created file. Otherwise, it
  9058. returns -1 and sets %@AB@%errno%@AE@% to one of the following constants:  %@NL@%
  9059. %@NL@%
  9060. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  9061. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9062. %@AB@%EACCES%@AE@%                            Path name specifies an existing 
  9063.                                   read-only file or specifies a directory 
  9064.                                   instead of a file
  9065.  
  9066. %@AB@%EMFILE %@AE@%                           No more handles available (too many open
  9067.                                   files)
  9068.  
  9069. %@AB@%ENOENT%@AE@%                            Path name not found
  9070.  
  9071. %@NL@%
  9072. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9073. %@NL@%
  9074.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  9075. %@NL@%
  9076. %@NL@%
  9077. %@NL@%
  9078. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9079. %@NL@%
  9080. %@AB@%chmod%@AE@%, %@AB@%chsize%@AE@%, %@AB@%close%@AE@%, %@AB@%dup%@AE@%, %@AB@%dup2%@AE@%, %@AB@%open%@AE@%, %@AB@%sopen%@AE@%, %@AB@%umask%@AE@%  %@NL@%
  9081. %@NL@%
  9082. %@NL@%
  9083. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9084. %@NL@%
  9085. %@AS@%  /* CREAT.C: This program uses creat to create the file (or truncate the
  9086. %@AS@%   * existing file) named data and open it for writing.
  9087. %@AS@%   */
  9088. %@AS@%  
  9089. %@AS@%  #include <sys\types.h>
  9090. %@AS@%  #include <sys\stat.h>
  9091. %@AS@%  #include <io.h>
  9092. %@AS@%  #include <stdio.h>
  9093. %@AS@%  #include <stdlib.h>
  9094. %@AS@%  
  9095. %@AS@%  void main()
  9096. %@AS@%  {
  9097. %@AS@%     int fh;
  9098. %@AS@%  
  9099. %@AS@%     fh = creat( "data", S_IREAD | S_IWRITE );
  9100. %@AS@%     if( fh == -1 )
  9101. %@AS@%        perror( "Couldn't create data file" );
  9102. %@AS@%     else
  9103. %@AS@%     {
  9104. %@AS@%        printf( "Created data file.\n" );
  9105. %@AS@%        close( fh );
  9106. %@AS@%     }
  9107. %@AS@%  }%@AE@%%@NL@%
  9108. %@NL@%
  9109. %@NL@%
  9110. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9111. %@NL@%
  9112. %@AS@%  
  9113. %@AS@%  
  9114. %@AS@%  Created data file.%@AE@%%@NL@%
  9115. %@NL@%
  9116. %@NL@%
  9117. %@NL@%
  9118. %@NL@%
  9119. %@QR:cscanf@%%@NL@%
  9120. %@2@%%@CR:C6A00500313 @%%@AB@%cscanf%@AE@%%@EH@%%@NL@%
  9121. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9122. %@NL@%
  9123. %@NL@%
  9124. %@3@%%@AB@%Description%@CR:C6A00500314 @%%@CR:C6A00500315 @% %@CR:C6A00500316 @%%@CR:C6A00500317 @% %@CR:C6A00500318 @%%@AE@%%@EH@%%@NL@%
  9125. %@NL@%
  9126. Reads formatted data from the console.  %@NL@%
  9127. %@NL@%
  9128. %@AB@%#include <conio.h>%@AE@%                Required only for function declarations
  9129.  
  9130. %@AS@%  int cscanf( char *format [[, argument]] ... );%@AE@%%@NL@%
  9131. %@NL@%
  9132. %@AI@%format%@AE@%                            Format-control string
  9133.  
  9134. %@AI@%argument%@AE@%                          Optional arguments
  9135.  
  9136. %@NL@%
  9137. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9138. %@NL@%
  9139. The %@AB@%cscanf%@AE@% function reads data directly from the console into the locations
  9140. given by %@AI@%argument%@AE@%. The %@AB@%getche%@AE@% function is used to read characters. Each
  9141. optional argument must be a pointer to a variable with a type that
  9142. corresponds to a type specifier in %@AI@%format%@AE@%. The format controls the
  9143. interpretation of the input fields and has the same form and function as the
  9144. %@AI@%format%@AE@% argument for the %@AB@%scanf%@AE@% function; see %@AB@%scanf%@AE@% for a description of
  9145. %@AI@%format%@AE@%.  %@NL@%
  9146. %@NL@%
  9147. While %@AB@%cscanf%@AE@% normally echoes the input character, it will not do so if the
  9148. last call was to %@AB@%ungetch%@AE@%.  %@NL@%
  9149. %@NL@%
  9150. %@NL@%
  9151. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9152. %@NL@%
  9153. The %@AB@%cscanf%@AE@% function returns the number of fields that were successfully
  9154. converted and assigned. The return value does not include fields that were
  9155. read but not assigned.  %@NL@%
  9156. %@NL@%
  9157. The return value is %@AB@%EOF%@AE@% for an attempt to read at end-of-file. This may
  9158. occur when keyboard input is redirected at the operating system command-line
  9159. level. A return value of 0 means that no fields were assigned.  %@NL@%
  9160. %@NL@%
  9161. %@NL@%
  9162. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9163. %@NL@%
  9164.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  9165. %@NL@%
  9166. %@NL@%
  9167. %@NL@%
  9168. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9169. %@NL@%
  9170. %@AB@%cprintf, fscanf, scanf, sscanf%@AE@%  %@NL@%
  9171. %@NL@%
  9172. %@NL@%
  9173. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9174. %@NL@%
  9175. %@AS@%  /* CSCANF.C: This program prompts for a string and uses cscanf to read
  9176. %@AS@%   * in the response. Then cscanf returns the number of items matched,
  9177. %@AS@%   * and the program displays that number.
  9178. %@AS@%   */
  9179. %@AS@%  
  9180. %@AS@%  #include <stdio.h>
  9181. %@AS@%  #include <conio.h>%@AE@%%@NL@%
  9182. %@NL@%
  9183. %@AS@%  void main()
  9184. %@AS@%  {
  9185. %@AS@%     int   result, i[3];
  9186. %@AS@%  
  9187. %@AS@%     cprintf( "Enter three integers: ");
  9188. %@AS@%     result = cscanf( "%i %i %i", &i[0], &i[1], &i[2] );
  9189. %@AS@%     cprintf( "\r\nYou entered " );
  9190. %@AS@%     while( result-- )
  9191. %@AS@%        cprintf( "%i ", i[result] );
  9192. %@AS@%     cprintf( "\r\n" );
  9193. %@AS@%  
  9194. %@AS@%  }%@AE@%%@NL@%
  9195. %@NL@%
  9196. %@NL@%
  9197. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9198. %@NL@%
  9199. %@AS@%  
  9200. %@AS@%  
  9201. %@AS@%  Enter three integers: 34 43 987k
  9202. %@AS@%  You entered 987 43 34 %@AE@%%@NL@%
  9203. %@NL@%
  9204. %@NL@%
  9205. %@NL@%
  9206. %@NL@%
  9207. %@QR:ctime@%%@NL@%
  9208. %@2@%%@CR:C6A00510319 @%%@AB@%ctime%@AE@%%@EH@%%@NL@%
  9209. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9210. %@NL@%
  9211. %@NL@%
  9212. %@3@%%@AB@%Description%@CR:C6A00510320 @%%@CR:C6A00510321 @% %@CR:C6A00510322 @%%@AE@%%@EH@%%@NL@%
  9213. %@NL@%
  9214. Converts a time stored as a %@AB@%time_t%@AE@% value to a character string.  %@NL@%
  9215. %@NL@%
  9216. %@AB@%#include <time.h>%@AE@%                 Required only for function declarations
  9217.  
  9218. %@AS@%  char *ctime( const time_t *timer );%@AE@%%@NL@%
  9219. %@NL@%
  9220. %@AI@%timer%@AE@%                             Pointer to stored time
  9221.  
  9222. %@NL@%
  9223. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9224. %@NL@%
  9225. The %@AB@%ctime%@AE@% function converts a time stored as a %@AB@%time_t%@AE@% value to a character
  9226. string. The %@AI@%timer%@AE@% value is usually obtained from a call to %@AB@%time%@AE@%, which
  9227. returns the number of seconds elapsed since 00:00:00 Greenwich mean time,
  9228. January 1, 1970.  %@NL@%
  9229. %@NL@%
  9230. The string result produced by %@AB@%ctime%@AE@% contains exactly 26 characters and has
  9231. the form of the following example:  %@NL@%
  9232. %@NL@%
  9233. %@AS@%  Wed Jan 02 02:03:55 1980\n\0%@AE@%%@NL@%
  9234. %@NL@%
  9235. A 24-hour clock is used. All fields have a constant width. The newline
  9236. character (%@AB@%\n%@AE@%)%@AB@% %@AE@%and the null character (%@AB@%'\0'%@AE@%) occupy the last two positions
  9237. of the string.  %@NL@%
  9238. %@NL@%
  9239. Calls to the %@AB@%ctime%@AE@% function modify the single statically allocated buffer
  9240. used by the %@AB@%gmtime%@AE@% and the %@AB@%localtime%@AE@% functions. Each call to one of these
  9241. routines destroys the result of the previous call. The %@AB@%ctime%@AE@% function also
  9242. shares a static buffer with the %@AB@%asctime%@AE@% function. Thus, a call to %@AB@%ctime%@AE@%
  9243. destroys the results of any previous call to%@AB@% asctime%@AE@%, %@AB@%localtime%@AE@%, or %@AB@%gmtime%@AE@%.
  9244. %@NL@%
  9245. %@NL@%
  9246. %@NL@%
  9247. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9248. %@NL@%
  9249. The %@AB@%ctime%@AE@% function returns a pointer to the character string result. If %@AI@%time%@AE@%
  9250. represents a date before 1980, %@AB@%ctime%@AE@% returns %@AB@%NULL%@AE@%.  %@NL@%
  9251. %@NL@%
  9252. %@NL@%
  9253. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9254. %@NL@%
  9255. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  9256. %@NL@%
  9257. %@NL@%
  9258. %@NL@%
  9259. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9260. %@NL@%
  9261. %@AB@%asctime%@AE@%, %@AB@%ftime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%time%@AE@%  %@NL@%
  9262. %@NL@%
  9263. %@NL@%
  9264. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9265. %@NL@%
  9266. %@AS@%  /* ASCTIME.C: This program places the system time in the long integer
  9267. %@AS@%  aclock,
  9268. %@AS@%   * translates it into the structure newtime and then converts it to
  9269. %@AS@%   * string form for output, using the asctime function.
  9270. %@AS@%   */
  9271. %@AS@%  
  9272. %@AS@%  #include <time.h>
  9273. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  9274. %@NL@%
  9275. %@AS@%  struct tm *newtime;
  9276. %@AS@%  time_t aclock;
  9277. %@AS@%  
  9278. %@AS@%  void main()
  9279. %@AS@%  {
  9280. %@AS@%     time( &aclock );                    /* Get time in seconds. */
  9281. %@AS@%  
  9282. %@AS@%     newtime = localtime( &aclock );     /* Convert time to struct tm form.
  9283. %@AS@%*/
  9284. %@AS@%  
  9285. %@AS@%     /* Print local time as a string. */
  9286. %@AS@%     printf( "The current date and time are: %s\n", asctime( newtime ) );
  9287. %@AS@%  }%@AE@%%@NL@%
  9288. %@NL@%
  9289. %@NL@%
  9290. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9291. %@NL@%
  9292. %@AS@%  
  9293. %@AS@%  
  9294. %@AS@%  The current date and time are: Thu Jun 15 06:57:59 1989%@AE@%%@NL@%
  9295. %@NL@%
  9296. %@NL@%
  9297. %@NL@%
  9298. %@NL@%
  9299. %@QR:cwait@%%@NL@%
  9300. %@2@%%@CR:C6A00520323 @%%@AB@%cwait%@AE@%%@EH@%%@NL@%
  9301. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9302. %@NL@%
  9303. %@NL@%
  9304. %@3@%%@AB@%Description%@CR:C6A00520324 @%%@CR:C6A00520325 @% %@CR:C6A00520326 @%%@CR:C6A00520327 @%%@AE@%%@EH@%%@NL@%
  9305. %@NL@%
  9306. Waits until the child process terminates.  %@NL@%
  9307. %@NL@%
  9308. %@AS@%  #include <process.h>%@AE@%%@NL@%
  9309. %@NL@%
  9310. %@AS@%  int cwait( int *termstat, int procid, int action );%@AE@%%@NL@%
  9311. %@NL@%
  9312. %@AI@%termstat%@AE@%                          Address for termination status code
  9313.  
  9314. %@AI@%procid%@AE@%                            Process ID of child
  9315.  
  9316. %@AI@%action%@AE@%                            Action code
  9317.  
  9318. %@NL@%
  9319. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9320. %@NL@%
  9321. The %@AB@%cwait%@AE@% function suspends the calling process until the specified child
  9322. process terminates.  %@NL@%
  9323. %@NL@%
  9324. If not %@AB@%NULL%@AE@%, %@AI@%termstat%@AE@% points to a buffer where %@AB@%cwait%@AE@% will place the
  9325. termination-status word and the return code of the terminated child process.
  9326. %@NL@%
  9327. %@NL@%
  9328. The termination-status word indicates whether or not the child process
  9329. terminated normally by calling the OS/2 %@AB@%DosExit%@AE@% function. (Programs that
  9330. terminate with %@AB@%exit%@AE@% or by "falling off the end of main" use %@AB@%DosExit%@AE@%
  9331. internally.) If the process did terminate normally, the low-order and
  9332. high-order bytes of the termination-status word are as follows:  %@NL@%
  9333. %@NL@%
  9334. %@AB@%Byte%@AE@%                              %@AB@%Contents%@AE@%
  9335. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9336. High order                        Contains the low-order byte of the 
  9337.                                   result code that the child code passed 
  9338.                                   to %@AB@%DosExit%@AE@%. The%@AB@% DosExit%@AE@% function is 
  9339.                                   called if the child process called %@AB@%exit%@AE@% 
  9340.                                   or %@AB@%_exit%@AE@%, returned from %@AB@%main%@AE@%, or reached
  9341.                                   the end of %@AB@%main%@AE@%. The low-order byte of 
  9342.                                   the result code is either the low-order 
  9343.                                   byte of the argument to %@AB@%_exit%@AE@% or %@AB@%exit%@AE@%, 
  9344.                                   the low-order byte of the return value 
  9345.                                   from %@AB@%main%@AE@%, or a random value if the 
  9346.                                   child process reached the end of %@AB@%main%@AE@%.
  9347.  
  9348. Low order                         0 (normal termination).
  9349.  
  9350. If the child process terminates without calling %@AB@%DosExit%@AE@%, the high-order and
  9351. low-order bytes of the termination-status word are as follows:  %@NL@%
  9352. %@NL@%
  9353. %@AB@%Byte%@AE@%                              %@AB@%Contents%@AE@%
  9354. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9355. High order                        0
  9356.  
  9357. Low order                         Termination code from %@AB@%DosCWait%@AE@%:
  9358.  
  9359.                                   %@AB@%Code%@AE@%        %@AB@%Meaning%@AE@%
  9360. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9361.                                   1           Hard-error abort
  9362.  
  9363.                                   2           Trap operation
  9364.  
  9365.                                   3           %@AB@%SIGTERM%@AE@% signal not 
  9366.                                               intercepted
  9367.  
  9368. The %@AI@%procid%@AE@% argument specifies which child-process termination to wait for.
  9369. This value is returned by the call to the %@AB@%spawn%@AE@% function that started the
  9370. child process. If the specified child process terminates before %@AB@%cwait%@AE@% is
  9371. called, the function returns immediately.  %@NL@%
  9372. %@NL@%
  9373. The %@AI@%action%@AE@% argument specifies when the parent process resumes execution, as
  9374. shown in the following list:  %@NL@%
  9375. %@NL@%
  9376. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  9377. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9378. %@AB@%WAIT_CHILD%@AE@%                        The parent process waits until the 
  9379.                                   specified child process has ended.
  9380.  
  9381. %@AB@%WAIT_GRANDCHILD%@AE@%                   The parent process waits until the 
  9382.                                   specified child process and all child 
  9383.                                   processes of that child process have 
  9384.                                   ended.
  9385.  
  9386. The %@AB@%WAIT_CHILD%@AE@% and %@AB@%WAIT_GRANDCHILD%@AE@% action codes are defined in PROCESS.H.  %@NL@%
  9387. %@NL@%
  9388. %@NL@%
  9389. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9390. %@NL@%
  9391. If the %@AB@%cwait%@AE@% function returns after normal termination of the child process,
  9392. it returns the child's process ID.  %@NL@%
  9393. %@NL@%
  9394. If the %@AB@%cwait%@AE@% function returns after abnormal termination of the child
  9395. process, it returns -1 and sets %@AB@%errno%@AE@% to%@AB@% EINTR%@AE@%.  %@NL@%
  9396. %@NL@%
  9397. Otherwise, the %@AB@%cwait%@AE@% function returns -1 immediately and sets %@AB@%errno%@AE@% to one
  9398. of the following error codes:  %@NL@%
  9399. %@NL@%
  9400. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  9401. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9402. %@AB@%ECHILD%@AE@%                            No child process exists, or invalid 
  9403.                                   process ID
  9404.  
  9405. %@AB@%EINVAL%@AE@%                            Invalid action code
  9406.  
  9407. %@NL@%
  9408. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9409. %@NL@%
  9410.  ANSI   DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  9411. %@NL@%
  9412. %@NL@%
  9413. Note that the OS/2 %@AB@%DosExit%@AE@% function allows programs to return a 16-bit
  9414. result code. However, the %@AB@%wait%@AE@% and %@AB@%cwait%@AE@% functions return only the low-order
  9415. byte of that result code.  %@NL@%
  9416. %@NL@%
  9417. %@NL@%
  9418. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9419. %@NL@%
  9420. %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, %@AB@%spawn %@AE@%functions, %@AB@%wait%@AE@%  %@NL@%
  9421. %@NL@%
  9422. %@NL@%
  9423. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9424. %@NL@%
  9425. %@AS@%  /* CWAIT.C: This program launches several child processes and waits
  9426. %@AS@%   * for a specified process to finish.
  9427. %@AS@%   */
  9428. %@AS@%  
  9429. %@AS@%  #define INCL_NOPM
  9430. %@AS@%  #define INCL_NOCOMMON
  9431. %@AS@%  #define INCL_DOSPROCESS
  9432. %@AS@%  #include <os2.h>        /* DosSleep */
  9433. %@AS@%  #include <process.h>    /* cwait    */
  9434. %@AS@%  #include <stdlib.h>
  9435. %@AS@%  #include <stdio.h>
  9436. %@AS@%  #include <time.h>
  9437. %@AS@%  
  9438. %@AS@%  /* Macro to get a random integer within a specified range */
  9439. %@AS@%  #define getrandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) +
  9440. %@AS@%(min))
  9441. %@AS@%  
  9442. %@AS@%  struct  CHILD
  9443. %@AS@%  {
  9444. %@AS@%      int     pid;
  9445. %@AS@%      char    name[10];
  9446. %@AS@%  } child[4] = { { 0, "Ann" }, { 0, "Beth"  }, { 0, "Carl" }, { 0, "Dave" }
  9447. %@AS@%};
  9448. %@AS@%  
  9449. %@AS@%  void main( int argc, char *argv[] )
  9450. %@AS@%  {
  9451. %@AS@%      int     termstat, pid, c, tmp;
  9452. %@AS@%  
  9453. %@AS@%      srand( (unsigned)time( NULL ) );               /* Seed randomizer */
  9454. %@AS@%      /* If no arguments, this is the parent. */
  9455. %@AS@%      if( argc == 1 )
  9456. %@AS@%      {
  9457. %@AS@%          /* Spawn children in numeric order. */
  9458. %@AS@%          for( c = 0; c < 4; c++ )
  9459. %@AS@%              child[c].pid = spawnl( P_NOWAIT, argv[0], argv[0],
  9460. %@AS@%                                     child[c].name, NULL );%@AE@%%@NL@%
  9461. %@NL@%
  9462. %@AS@%  /* Wait for randomly specified child, and respond when done. */
  9463. %@AS@%          c = getrandom( 0, 3 );
  9464. %@AS@%          printf( "Come here, %s\n", child[c].name );
  9465. %@AS@%          cwait( &termstat, child[c].pid, WAIT_CHILD );
  9466. %@AS@%          printf( "Thank you, %s\n", child[c].name );
  9467. %@AS@%      }
  9468. %@AS@%  
  9469. %@AS@%      /* If there are arguments, this must be a child. */
  9470. %@AS@%      else
  9471. %@AS@%      {
  9472. %@AS@%          /* Delay for a period determined by process number. */
  9473. %@AS@%          DosSleep( (argv[1][0] - 'A' + 1) * 1000L );
  9474. %@AS@%          printf( "Hi, dad. It's %s.\n", argv[1] );
  9475. %@AS@%      }
  9476. %@AS@%  }%@AE@%%@NL@%
  9477. %@NL@%
  9478. %@NL@%
  9479. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9480. %@NL@%
  9481. %@AS@%  
  9482. %@AS@%  
  9483. %@AS@%  Come here, Carl
  9484. %@AS@%  Hi, dad. It's Ann.
  9485. %@AS@%  Hi, dad. It's Beth.
  9486. %@AS@%  Hi, dad. It's Carl.
  9487. %@AS@%  Thank you, Carl
  9488. %@AS@%  Hi, dad. It's Dave. %@AE@%%@NL@%
  9489. %@NL@%
  9490. %@NL@%
  9491. %@NL@%
  9492. %@NL@%
  9493. %@QR:dieeetomsbin@%%@QR:dmsbintoieee@%%@NL@%
  9494. %@2@%%@CR:C6A00530328 @%%@AB@%dieeetomsbin, dmsbintoieee%@AE@%%@EH@%%@NL@%
  9495. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9496. %@NL@%
  9497. %@NL@%
  9498. %@3@%%@AB@%Description %@CR:C6A00530329 @% %@CR:C6A00530330 @% %@CR:C6A00530331 @% %@CR:C6A00530332 @%%@AE@%%@EH@%%@NL@%
  9499. %@NL@%
  9500. Convert between IEEE double value and Microsoft (MS) binary double value.  %@NL@%
  9501. %@NL@%
  9502. %@AS@%  #include <math.h>%@AE@%%@NL@%
  9503. %@NL@%
  9504. %@AS@%  int dieeetomsbin( double *src8, double *dst8 );%@AE@%%@NL@%
  9505. %@NL@%
  9506. %@AS@%  int dmsbintoieee( double *src8, double *dst8 );%@AE@%%@NL@%
  9507. %@NL@%
  9508. %@AI@%src8%@AE@%                              Buffer containing value to convert
  9509.  
  9510. %@AI@%dst8%@AE@%                              Buffer to store converted value
  9511.  
  9512. %@NL@%
  9513. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9514. %@NL@%
  9515. The %@AB@%dieeetomsbin%@AE@% routine converts a double-precision number in IEEE
  9516. (Institute of Electrical and Electronic Engineers) format to Microsoft (MS)
  9517. binary format. The routine %@AB@%dmsbintoieee%@AE@% converts a double-precision number
  9518. in MS binary format to IEEE format.  %@NL@%
  9519. %@NL@%
  9520. These routines allow C programs (which store floating-point numbers in the
  9521. IEEE format) to use numeric data in random-access data files created with
  9522. those versions of Microsoft BASIC that store floating-point numbers in MS
  9523. binary format, and vice versa.  %@NL@%
  9524. %@NL@%
  9525. The argument %@AI@%src8%@AE@% is a pointer to the %@AB@%double%@AE@% value to be converted. The
  9526. result is stored at the location given by %@AI@%dst8%@AE@%.  %@NL@%
  9527. %@NL@%
  9528. These routines do not handle IEEE NANs ("not a number") and infinities. IEEE
  9529. denormals are treated as 0 in the conversions.  %@NL@%
  9530. %@NL@%
  9531. %@NL@%
  9532. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9533. %@NL@%
  9534. These functions return 0 if the conversion is successful and 1 if the
  9535. conversion causes an overflow.  %@NL@%
  9536. %@NL@%
  9537. %@NL@%
  9538. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9539. %@NL@%
  9540.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  9541. %@NL@%
  9542. %@NL@%
  9543. %@NL@%
  9544. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9545. %@NL@%
  9546. %@AB@%fieeetomsbin%@AE@%, %@AB@%fmsbintoieee%@AE@%  %@NL@%
  9547. %@NL@%
  9548. %@NL@%
  9549. %@NL@%
  9550. %@NL@%
  9551. %@QR:difftime@%%@NL@%
  9552. %@2@%%@CR:C6A00540333 @%%@AB@%difftime%@AE@%%@EH@%%@NL@%
  9553. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9554. %@NL@%
  9555. %@NL@%
  9556. %@3@%%@AB@%Description%@CR:C6A00540334 @%%@CR:C6A00540335 @%%@CR:C6A00540336 @% %@CR:C6A00540337 @%%@CR:C6A00540338 @%%@AE@%%@EH@%%@NL@%
  9557. %@NL@%
  9558. Finds the difference between two times.  %@NL@%
  9559. %@NL@%
  9560. %@AB@%#include <time.h>%@AE@%                 Required only for function declarations
  9561.  
  9562. %@AS@%  double difftime( time_t timer1, time_t timer0 );%@AE@%%@NL@%
  9563. %@NL@%
  9564. %@AI@%timer0%@AE@%                            Beginning time
  9565.  
  9566. %@AI@%timer1%@AE@%                            Ending time
  9567.  
  9568. %@NL@%
  9569. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9570. %@NL@%
  9571. The %@AB@%difftime%@AE@% function computes the difference between the supplied time
  9572. values, %@AI@%timer0 %@AE@%and%@AI@% timer1%@AE@%.  %@NL@%
  9573. %@NL@%
  9574. %@NL@%
  9575. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9576. %@NL@%
  9577. The %@AB@%difftime%@AE@% function returns, in seconds, the elapsed time from %@AI@%timer0%@AE@% to
  9578. %@AI@%timer1%@AE@%. The value returned is a double-precision number.  %@NL@%
  9579. %@NL@%
  9580. %@NL@%
  9581. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9582. %@NL@%
  9583. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  9584. %@NL@%
  9585. %@NL@%
  9586. %@NL@%
  9587. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9588. %@NL@%
  9589. %@AB@%time%@AE@%  %@NL@%
  9590. %@NL@%
  9591. %@NL@%
  9592. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9593. %@NL@%
  9594. %@AS@%  /* DIFFTIME.C: This program calculates the amount of time needed to
  9595. %@AS@%   * do a floating-point multiply 50000 times.
  9596. %@AS@%   */
  9597. %@AS@%  
  9598. %@AS@%  #include <stdio.h>
  9599. %@AS@%  #include <stdlib.h>
  9600. %@AS@%  #include <time.h>
  9601. %@AS@%  
  9602. %@AS@%  void main()
  9603. %@AS@%  {
  9604. %@AS@%     time_t   start, finish;
  9605. %@AS@%     unsigned loop;
  9606. %@AS@%     double   result, elapsed_time;
  9607. %@AS@%  
  9608. %@AS@%     printf( "This program will do a floating point multiply 50000 times\n"
  9609. %@AS@%);
  9610. %@AS@%     printf( "Working...\n" );
  9611. %@AS@%  
  9612. %@AS@%     time( &start );
  9613. %@AS@%     for( loop = 0; loop < 50000L; loop++ )
  9614. %@AS@%        result = 3.63 * 5.27;
  9615. %@AS@%     time( &finish );%@AE@%%@NL@%
  9616. %@NL@%
  9617. %@AS@%  elapsed_time = difftime( finish, start );
  9618. %@AS@%     printf( "\nProgram takes %6.2f seconds.\n", elapsed_time );
  9619. %@AS@%  }%@AE@%%@NL@%
  9620. %@NL@%
  9621. %@NL@%
  9622. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9623. %@NL@%
  9624. %@AS@%  
  9625. %@AS@%  
  9626. %@AS@%  This program will do a floating point multiply 50000 times
  9627. %@AS@%  Working...
  9628. %@AS@%  
  9629. %@AS@%  Program takes   4.00 seconds. %@AE@%%@NL@%
  9630. %@NL@%
  9631. %@NL@%
  9632. %@NL@%
  9633. %@NL@%
  9634. %@QR:_displaycursor@%%@NL@%
  9635. %@2@%%@CR:C6A00550339 @%%@AB@%_displaycursor%@AE@%%@EH@%%@NL@%
  9636. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9637. %@NL@%
  9638. %@NL@%
  9639. %@3@%%@AB@%Description%@CR:C6A00550340 @%%@AE@%%@EH@%%@NL@%
  9640. %@NL@%
  9641. Sets the cursor toggle for graphics functions.  %@NL@%
  9642. %@NL@%
  9643. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  9644. %@NL@%
  9645. %@AS@%  short _far _displaycursor( short toggle );%@AE@%%@NL@%
  9646. %@NL@%
  9647. %@AI@%toggle%@AE@%                            Cursor state
  9648.  
  9649. %@NL@%
  9650. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9651. %@NL@%
  9652. Upon entry into each graphic routine, the screen cursor is turned off. The
  9653. %@AB@%_displaycursor%@AE@% function determines whether the cursor will be turned back on
  9654. when programs exit graphic routines. If %@AI@%toggle%@AE@% is set to %@AB@%_GCURSORON,%@AE@% the
  9655. cursor will be restored on exit. If %@AI@%toggle%@AE@% is set to %@AB@%_GCURSOROFF,%@AE@% the cursor
  9656. will be left off.  %@NL@%
  9657. %@NL@%
  9658. %@NL@%
  9659. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9660. %@NL@%
  9661. The function returns the previous value of %@AI@%toggle%@AE@%. There is no error return.
  9662. %@NL@%
  9663. %@NL@%
  9664. %@NL@%
  9665. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9666. %@NL@%
  9667.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  9668. %@NL@%
  9669. %@NL@%
  9670. %@NL@%
  9671. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9672. %@NL@%
  9673. %@AB@%_gettextcursor%@AE@%, %@AB@%_settextcursor%@AE@%  %@NL@%
  9674. %@NL@%
  9675. %@NL@%
  9676. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9677. %@NL@%
  9678. %@AS@%  /* DISCURS.C: This program changes the cursor shape using _gettextcursor
  9679. %@AS@%   * and _settextcursor, and hides the cursor using _displaycursor.
  9680. %@AS@%   */
  9681. %@AS@%  
  9682. %@AS@%  #include <conio.h>
  9683. %@AS@%  #include <graph.h>
  9684. %@AS@%  
  9685. %@AS@%  void main()
  9686. %@AS@%  {
  9687. %@AS@%     short oldcursor;
  9688. %@AS@%     short newcursor = 0x007;        /* Full block cursor */
  9689. %@AS@%  
  9690. %@AS@%     /* Save old cursor shape and make sure cursor is on */
  9691. %@AS@%     oldcursor = _gettextcursor();
  9692. %@AS@%     _clearscreen( _GCLEARSCREEN );
  9693. %@AS@%     _displaycursor( _GCURSORON );
  9694. %@AS@%     _outtext( "\nOld cursor shape: " );
  9695. %@AS@%     getch();
  9696. %@AS@%  
  9697. %@AS@%     /* Change cursor shape */
  9698. %@AS@%     _outtext( "\nNew cursor shape: " );
  9699. %@AS@%     _settextcursor( newcursor );
  9700. %@AS@%     getch();%@AE@%%@NL@%
  9701. %@NL@%
  9702. %@AS@%  /* Restore original cursor shape */
  9703. %@AS@%     _outtext( "\n" );
  9704. %@AS@%     _settextcursor( oldcursor );
  9705. %@AS@%  }%@AE@%%@NL@%
  9706. %@NL@%
  9707. %@NL@%
  9708. %@NL@%
  9709. %@NL@%
  9710. %@QR:div@%%@NL@%
  9711. %@2@%%@CR:C6A00560341 @%%@AB@%div%@AE@%%@EH@%%@NL@%
  9712. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9713. %@NL@%
  9714. %@NL@%
  9715. %@3@%%@AB@%Description%@CR:C6A00560342 @%%@CR:C6A00560343 @%%@AE@%%@EH@%%@NL@%
  9716. %@NL@%
  9717. Computes the quotient and the remainder of two integer values.  %@NL@%
  9718. %@NL@%
  9719. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  9720. %@NL@%
  9721. %@AS@%  div_t div( int numer, int denom );%@AE@%%@NL@%
  9722. %@NL@%
  9723. %@AI@%numer%@AE@%                             Numerator
  9724.  
  9725. %@AI@%denom%@AE@%                             Denominator
  9726.  
  9727. %@NL@%
  9728. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9729. %@NL@%
  9730. The %@AB@%div%@AE@% function divides %@AI@%numer%@AE@% by %@AI@%denom%@AE@%, computing the quotient and the
  9731. remainder. The %@AB@%div_t%@AE@% structure contains the following elements:  %@NL@%
  9732. %@NL@%
  9733. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  9734. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9735. %@AB@%int quot%@AE@%                          Quotient
  9736.  
  9737. %@AB@%int rem%@AE@%                           Remainder
  9738.  
  9739. The sign of the quotient is the same as that of the mathematical quotient.
  9740. Its absolute value is the largest integer that is less than the absolute
  9741. value of the mathematical quotient. If the denominator is 0, the program
  9742. will terminate with an error message.  %@NL@%
  9743. %@NL@%
  9744. %@NL@%
  9745. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9746. %@NL@%
  9747. The %@AB@%div%@AE@% function returns a structure of type %@AB@%div_t%@AE@%, comprising both the
  9748. quotient and the remainder. The structure is defined in STDLIB.H.  %@NL@%
  9749. %@NL@%
  9750. %@NL@%
  9751. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9752. %@NL@%
  9753. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  9754. %@NL@%
  9755. %@NL@%
  9756. %@NL@%
  9757. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9758. %@NL@%
  9759. %@AB@%ldiv%@AE@%  %@NL@%
  9760. %@NL@%
  9761. %@NL@%
  9762. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9763. %@NL@%
  9764. %@AS@%  /* DIV.C: This example takes two integers as command-line arguments and
  9765. %@AS@%   * displays the results of the integer division. This program accepts
  9766. %@AS@%   * two arguments on the command line following the program name, then
  9767. %@AS@%   * calls div to divide the first argument by the second. Finally,
  9768. %@AS@%   * it prints the structure members quot and rem.
  9769. %@AS@%   */
  9770. %@AS@%  
  9771. %@AS@%  #include <stdlib.h>
  9772. %@AS@%  #include <stdio.h>
  9773. %@AS@%  #include <math.h>%@AE@%%@NL@%
  9774. %@NL@%
  9775. %@AS@%  void main( int argc, char *argv[] )
  9776. %@AS@%  {
  9777. %@AS@%     int x,y;
  9778. %@AS@%     div_t div_result;
  9779. %@AS@%  
  9780. %@AS@%     x = atoi( argv[1] );
  9781. %@AS@%     y = atoi( argv[2] );
  9782. %@AS@%  
  9783. %@AS@%     printf( "x is %d, y is %d\n", x, y );
  9784. %@AS@%     div_result = div( x, y );
  9785. %@AS@%     printf( "The quotient is %d, and the remainder is %d\n",
  9786. %@AS@%             div_result.quot, div_result.rem );
  9787. %@AS@%  }%@AE@%%@NL@%
  9788. %@NL@%
  9789. %@NL@%
  9790. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9791. %@NL@%
  9792. %@AS@%  
  9793. %@AS@%  
  9794. %@AS@%  [C:\LIBREF] div 876 13
  9795. %@AS@%  x is 876, y is 13
  9796. %@AS@%  The quotient is 67, and the remainder is 5 %@AE@%%@NL@%
  9797. %@NL@%
  9798. %@NL@%
  9799. %@NL@%
  9800. %@NL@%
  9801. %@QR:_dos_allocmem@%%@NL@%
  9802. %@2@%%@CR:C6A00570344 @%%@AB@%_dos_allocmem%@AE@%%@EH@%%@NL@%
  9803. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9804. %@NL@%
  9805. %@NL@%
  9806. %@3@%%@AB@%Description%@CR:C6A00570345 @% %@CR:C6A00570346 @%%@AE@%%@EH@%%@NL@%
  9807. %@NL@%
  9808. Allocates a block of memory, using DOS service 0x48.  %@NL@%
  9809. %@NL@%
  9810. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  9811. %@NL@%
  9812. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  9813. %@NL@%
  9814. %@AS@%  unsigned _dos_allocmem( unsigned size, unsigned *seg );%@AE@%%@NL@%
  9815. %@NL@%
  9816. %@AI@%size%@AE@%                              Block size to allocate
  9817.  
  9818. %@AI@%seg%@AE@%                               Return buffer for segment descriptor
  9819.  
  9820. %@NL@%
  9821. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9822. %@NL@%
  9823. The %@AB@%_dos_allocmem%@AE@% function uses DOS service 0x48 to allocate a block of
  9824. memory %@AI@%size%@AE@% paragraphs long. (A paragraph is 16 bytes.) Allocated blocks are
  9825. always paragraph aligned. The segment descriptor for the initial segment of
  9826. the new block is returned in the word that %@AI@%seg%@AE@% points to. If the request
  9827. cannot be satisfied, the maximum possible size (in paragraphs) is returned
  9828. in this word instead.  %@NL@%
  9829. %@NL@%
  9830. %@NL@%
  9831. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9832. %@NL@%
  9833. If successful, the %@AB@%_dos_allocmem%@AE@% returns 0. Otherwise, it returns the DOS
  9834. error code and sets %@AB@%errno%@AE@% to %@AB@%ENOMEM%@AE@%, indicating insufficient memory or
  9835. invalid arena (memory area) headers.  %@NL@%
  9836. %@NL@%
  9837. %@NL@%
  9838. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9839. %@NL@%
  9840.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  9841. %@NL@%
  9842. %@NL@%
  9843. %@NL@%
  9844. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9845. %@NL@%
  9846. %@AB@%alloca%@AE@%, %@AB@%calloc%@AE@% functions, %@AB@%_dos_freemem%@AE@%, %@AB@%_dos_setblock%@AE@%, %@AB@%halloc%@AE@%, %@AB@%malloc%@AE@%
  9847. functions  %@NL@%
  9848. %@NL@%
  9849. %@NL@%
  9850. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9851. %@NL@%
  9852. %@AS@%  /* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases
  9853. %@AS@%   * the allocation to 40 paragraphs, and then frees the memory space.
  9854. %@AS@%   */
  9855. %@AS@%  
  9856. %@AS@%  #include <dos.h>
  9857. %@AS@%  #include <stdio.h>
  9858. %@AS@%  
  9859. %@AS@%  void main()
  9860. %@AS@%  {
  9861. %@AS@%     unsigned segment;
  9862. %@AS@%     unsigned maxsize;%@AE@%%@NL@%
  9863. %@NL@%
  9864. %@AS@%  /* Allocate 20 paragraphs */
  9865. %@AS@%     if( _dos_allocmem( 20, &segment ) != 0 )
  9866. %@AS@%        printf( "allocation failed\n" );
  9867. %@AS@%     else
  9868. %@AS@%        printf( "allocation successful\n" );
  9869. %@AS@%  
  9870. %@AS@%     /* Increase allocation to 40 paragraphs */
  9871. %@AS@%     if( _dos_setblock( 40, segment, &maxsize ) != 0 )
  9872. %@AS@%        printf( "allocation increase failed\n" );
  9873. %@AS@%     else
  9874. %@AS@%        printf( "allocation increase successful\n" );
  9875. %@AS@%  
  9876. %@AS@%     /* free memory */
  9877. %@AS@%     if( _dos_freemem( segment ) != 0 )
  9878. %@AS@%        printf( "free memory failed\n" );
  9879. %@AS@%     else
  9880. %@AS@%        printf( "free memory successful\n" );
  9881. %@AS@%  }%@AE@%%@NL@%
  9882. %@NL@%
  9883. %@NL@%
  9884. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9885. %@NL@%
  9886. %@AS@%  
  9887. %@AS@%  
  9888. %@AS@%  allocation successful
  9889. %@AS@%  allocation increase successful
  9890. %@AS@%  free memory successful %@AE@%%@NL@%
  9891. %@NL@%
  9892. %@NL@%
  9893. %@NL@%
  9894. %@NL@%
  9895. %@QR:_dos_close@%%@NL@%
  9896. %@2@%%@CR:C6A00580347 @%%@AB@%_dos_close%@AE@%%@EH@%%@NL@%
  9897. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9898. %@NL@%
  9899. %@NL@%
  9900. %@3@%%@AB@%Description%@CR:C6A00580348 @% %@CR:C6A00580349 @%%@AE@%%@EH@%%@NL@%
  9901. %@NL@%
  9902. Closes a file using system call INT 0x3E.  %@NL@%
  9903. %@NL@%
  9904. %@AB@%#include <dos.h>%@AE@%                  
  9905.  
  9906. %@AB@%#include <errno.h>%@AE@%                
  9907.  
  9908. %@AS@%  unsigned _dos_close( int handle );%@AE@%%@NL@%
  9909. %@NL@%
  9910. %@AI@%handle%@AE@%                            Target file handle
  9911.  
  9912. %@NL@%
  9913. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  9914. %@NL@%
  9915. The %@AB@%_dos_close%@AE@% function uses system call 0x3E to close the file indicated by
  9916. %@AI@%handle%@AE@%. The file's %@AI@%handle%@AE@% argument is returned by the call that created or
  9917. last opened the file.  %@NL@%
  9918. %@NL@%
  9919. %@NL@%
  9920. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  9921. %@NL@%
  9922. The function returns 0 if successful. Otherwise, it returns the DOS error
  9923. code and sets %@AB@%errno%@AE@% to %@AB@%EBADF%@AE@%, indicating an invalid file handle.  %@NL@%
  9924. %@NL@%
  9925. Do not use the DOS interface I/O routines with the console, low-level, or
  9926. stream I/O routines.  %@NL@%
  9927. %@NL@%
  9928. %@NL@%
  9929. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  9930. %@NL@%
  9931.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  9932. %@NL@%
  9933. %@NL@%
  9934. %@NL@%
  9935. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  9936. %@NL@%
  9937. %@AB@%close%@AE@%,%@AB@% creat%@AE@%, %@AB@% _dos_creat%@AE@% functions, %@AB@% _dos_open%@AE@%, %@AB@% _dos_read%@AE@%, %@AB@% _dos_write%@AE@%,
  9938. %@AB@%dup%@AE@%, %@AB@%open%@AE@%  %@NL@%
  9939. %@NL@%
  9940. %@NL@%
  9941. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  9942. %@NL@%
  9943. %@AS@%  /* DOPEN.C: This program uses DOS I/O functions to open and close a file.
  9944. %@AS@%  */
  9945. %@AS@%  
  9946. %@AS@%  #include <fcntl.h>
  9947. %@AS@%  #include <stdio.h>
  9948. %@AS@%  #include <dos.h>
  9949. %@AS@%  
  9950. %@AS@%  void main()
  9951. %@AS@%  {
  9952. %@AS@%     int fh;
  9953. %@AS@%  
  9954. %@AS@%     /* Open file with _dos_open function */
  9955. %@AS@%     if( _dos_open( "data1", O_RDONLY, &fh ) != 0 )
  9956. %@AS@%        perror( "Open failed on input file\n" );
  9957. %@AS@%     else
  9958. %@AS@%        printf( "Open succeeded on input file\n" );%@AE@%%@NL@%
  9959. %@NL@%
  9960. %@AS@%  /* Close file with _dos_close function */
  9961. %@AS@%     if( _dos_close( fh ) != 0 )
  9962. %@AS@%        perror( "Close failed\n" );
  9963. %@AS@%     else
  9964. %@AS@%        printf( "File successfully closed\n" );
  9965. %@AS@%  }%@AE@%%@NL@%
  9966. %@NL@%
  9967. %@NL@%
  9968. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  9969. %@NL@%
  9970. %@AS@%  
  9971. %@AS@%  
  9972. %@AS@%  Open succeeded on input file
  9973. %@AS@%  File successfully closed %@AE@%%@NL@%
  9974. %@NL@%
  9975. %@NL@%
  9976. %@NL@%
  9977. %@NL@%
  9978. %@QR:_dos_creat@%%@NL@%
  9979. %@2@%%@CR:C6A00590350 @%%@AB@%_dos_creat Functions%@AE@%%@EH@%%@NL@%
  9980. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  9981. %@NL@%
  9982. %@NL@%
  9983. %@3@%%@AB@%Description%@CR:C6A00590351 @%%@CR:C6A00590352 @% %@CR:C6A00590353 @%%@AE@%%@EH@%%@NL@%
  9984. %@NL@%
  9985. Create a new file.  %@NL@%
  9986. %@NL@%
  9987. %@AB@%#include <dos.h>%@AE@%                  
  9988.  
  9989. %@AB@%#include <errno.h>%@AE@%                
  9990.  
  9991. %@AS@%  unsigned _dos_creat( char *filename, unsigned attrib, int *handle );%@AE@%%@NL@%
  9992. %@NL@%
  9993. %@AS@%  unsigned _dos_creatnew( char *filename, unsigned attrib, int *handle );%@AE@%%@NL@%
  9994. %@NL@%
  9995. %@AI@%filename%@AE@%                          File path name
  9996.  
  9997. %@AI@%attrib%@AE@%                            File attributes
  9998.  
  9999. %@AI@%handle%@AE@%                            Handle return buffer
  10000.  
  10001. %@NL@%
  10002. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10003. %@NL@%
  10004. The %@AB@%_dos_creat%@AE@% and %@AB@%_dos_creatnew%@AE@% routines create and open a new file named
  10005. %@AI@%filename%@AE@%; this new file has the access attributes specified in the %@AI@%attrib%@AE@%
  10006. argument. The new file's handle is copied into the integer location pointed
  10007. to by %@AI@%handle%@AE@%. The file is opened for both read and write access. If file
  10008. sharing is installed, the file is opened in compatibility mode.  %@NL@%
  10009. %@NL@%
  10010. The %@AB@%_dos_creat%@AE@% routine uses system call INT 0x3C, and the %@AB@%_dos_creatnew%@AE@%
  10011. routine uses system call INT 0x5B. If the file already exists, %@AB@%_dos_creat%@AE@%
  10012. erases its contents and leaves its attributes unchanged; however, the
  10013. %@AB@%_dos_creatnew%@AE@% routine fails if the file already exists.  %@NL@%
  10014. %@NL@%
  10015. %@NL@%
  10016. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10017. %@NL@%
  10018. If successful, both routines return 0. Otherwise, they return the DOS error
  10019. code and set %@AB@%errno%@AE@% to one of the following values:  %@NL@%
  10020. %@NL@%
  10021. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  10022. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10023. %@AB@%EACCES%@AE@%                            Access denied because the directory is 
  10024.                                   full or, for %@AB@%_dos_creat%@AE@% only, the file 
  10025.                                   exists and cannot be overwritten
  10026.  
  10027. %@AB@%EEXIST%@AE@%                            File already exists (%@AB@%_dos_creatnew%@AE@% only)
  10028.  
  10029. %@AB@%EMFILE%@AE@%                            Too many open file handles
  10030.  
  10031. %@AB@%ENOENT%@AE@%                            Path or file not found
  10032.  
  10033. %@NL@%
  10034. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10035. %@NL@%
  10036.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10037. %@NL@%
  10038. %@NL@%
  10039. %@NL@%
  10040. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10041. %@NL@%
  10042. %@AS@%  /* DCREAT.C: This program creates a file using the _dos_creat function.
  10043. %@AS@%  The
  10044. %@AS@%   * program cannot create a new file using the _dos_creatnew function
  10045. %@AS@%   * because it already exists.
  10046. %@AS@%   */
  10047. %@AS@%  
  10048. %@AS@%  #include <stdio.h>
  10049. %@AS@%  #include <stdlib.h>
  10050. %@AS@%  #include <dos.h>
  10051. %@AS@%  
  10052. %@AS@%  void main()
  10053. %@AS@%  {
  10054. %@AS@%     int fh1, fh2;
  10055. %@AS@%     int result;
  10056. %@AS@%  
  10057. %@AS@%     if( _dos_creat( "data", _A_NORMAL, &fh1 ) != 0 )
  10058. %@AS@%        printf( "Couldn't create data file\n" );
  10059. %@AS@%     else
  10060. %@AS@%     {
  10061. %@AS@%        printf( "Created data file.\n" );
  10062. %@AS@%  
  10063. %@AS@%        /* If _dos_creat is successful, the _dos_creatnew call
  10064. %@AS@%         * will fail since the file exists
  10065. %@AS@%         */
  10066. %@AS@%        if( _dos_creatnew( "data", _A_RDONLY, &fh2 ) != 0 )
  10067. %@AS@%           printf( "Couldn't create data file\n" );
  10068. %@AS@%        else
  10069. %@AS@%        {
  10070. %@AS@%           printf( "Created data file.\n" );
  10071. %@AS@%           _dos_close( fh2 );
  10072. %@AS@%        }
  10073. %@AS@%        _dos_close( fh1 );
  10074. %@AS@%     }
  10075. %@AS@%  }%@AE@%%@NL@%
  10076. %@NL@%
  10077. %@NL@%
  10078. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10079. %@NL@%
  10080. %@AS@%  
  10081. %@AS@%  
  10082. %@AS@%  Created data file.
  10083. %@AS@%  Couldn't create data file %@AE@%%@NL@%
  10084. %@NL@%
  10085. %@NL@%
  10086. %@NL@%
  10087. %@NL@%
  10088. %@QR:_dos_find@%%@NL@%
  10089. %@2@%%@CR:C6A00600354 @%%@AB@%_dos_find Functions%@AE@%%@EH@%%@NL@%
  10090. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10091. %@NL@%
  10092. %@NL@%
  10093. %@3@%%@AB@%Description%@CR:C6A00600355 @% %@CR:C6A00600356 @% %@CR:C6A00600357 @%%@AE@%%@EH@%%@NL@%
  10094. %@NL@%
  10095. Find the file with the specified attributes or find the next file with the
  10096. specified attributes.  %@NL@%
  10097. %@NL@%
  10098. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10099. %@NL@%
  10100. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  10101. %@NL@%
  10102. %@AS@%  unsigned _dos_findfirst( char *filename, unsigned attrib, struct find_t
  10103. %@AS@%  *fileinfo );%@AE@%%@NL@%
  10104. %@NL@%
  10105. %@AS@%  unsigned _dos_findnext( struct find_t *fileinfo );%@AE@%%@NL@%
  10106. %@NL@%
  10107. %@AI@%filename%@AE@%                          Target file name
  10108.  
  10109. %@AI@%attrib%@AE@%                            Target attributes
  10110.  
  10111. %@AI@%fileinfo%@AE@%                          File-information buffer
  10112.  
  10113. %@NL@%
  10114. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10115. %@NL@%
  10116. The %@AB@%_dos_findfirst%@AE@% routine uses system call INT 0x4E to return information
  10117. about the first instance of a file whose name and attributes match %@AI@%filename%@AE@%
  10118. and %@AI@%attrib%@AE@%.  %@NL@%
  10119. %@NL@%
  10120. The %@AI@%filename%@AE@% argument may use wildcards (%@AB@%*%@AE@% and %@AB@%?%@AE@%). The %@AI@%attrib%@AE@% argument can
  10121. be any of the following manifest constants:  %@NL@%
  10122. %@NL@%
  10123. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  10124. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10125. %@AB@%_A_ARCH%@AE@%                           Archive. Set whenever the file is 
  10126.                                   changed, and cleared by the DOS BACKUP 
  10127.                                   command.
  10128.  
  10129. %@AB@%_A_HIDDEN%@AE@%                         Hidden file. Cannot be found with the 
  10130.                                   DOS DIR command. Returns information 
  10131.                                   about normal files as well as about 
  10132.                                   files with this attribute.
  10133.  
  10134. %@AB@%_A_NORMAL%@AE@%                         Normal. File can be read or written 
  10135.                                   without restriction.
  10136.  
  10137. %@AB@%_A_RDONLY%@AE@%                         Read-only. File cannot be opened for 
  10138.                                   writing, and a file with the same name 
  10139.                                   cannot be created. Returns information 
  10140.                                   about normal files as well as about 
  10141.                                   files with this attribute.
  10142.  
  10143. %@AB@%_A_SUBDIR%@AE@%                         Subdirectory. Returns information about 
  10144.                                   normal files as well as about files with
  10145.                                   this attribute.
  10146.  
  10147. %@AB@%_A_SYSTEM%@AE@%                         System file. Cannot be found with the 
  10148.                                   DOS DIR command. Returns information 
  10149.                                   about normal files as well as about 
  10150.                                   files with this attribute.
  10151.  
  10152. %@AB@%_A_VOLID%@AE@%                          Volume ID. Only one file can have this 
  10153.                                   attribute, and it must be in the root 
  10154.                                   directory.
  10155.  
  10156. Multiple constants can be combined (with the OR operator), using the
  10157. vertical-bar ( | ) character.  %@NL@%
  10158. %@NL@%
  10159. If the %@AI@%attributes %@AE@%argument to either of these functions is %@AB@%_A_RDONLY%@AE@%,%@AB@%
  10160. %@AB@%%@AE@%_A_HIDDEN,%@AB@% _A_SYSTEM%@AE@%, or %@AB@%_A_SUBDIR%@AE@%, the function also returns any normal
  10161. attribute files that match the %@AI@%filename%@AE@% argument. That is, a normal file
  10162. does not have a read-only, hidden, system, or directory attribute.  %@NL@%
  10163. %@NL@%
  10164. Information is returned in a %@AB@%find_t%@AE@% structure, defined in DOS.H. The %@AB@%find_t%@AE@%
  10165. structure contains the following elements:  %@NL@%
  10166. %@NL@%
  10167. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  10168. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10169. %@AB@%char reserved[21]%@AE@%                 Reserved for use by DOS
  10170.  
  10171. %@AB@%char attrib%@AE@%                       Attribute byte for matched path
  10172.  
  10173. %@AB@%unsigned wr_time%@AE@%                  Time of last write to file
  10174.  
  10175. %@AB@%unsigned wr_date%@AE@%                  Date of last write to file
  10176.  
  10177. %@AB@%long size%@AE@%                         Length of file in bytes
  10178.  
  10179. %@AB@%char name[13]%@AE@%                     Null-terminated name of matched 
  10180.                                   file/directory, without
  10181.                                   the path
  10182.  
  10183. The formats for the %@AB@%wr_time%@AE@% and %@AB@%wr_date%@AE@% elements are in DOS format and are
  10184. not usable by any other C run-time function. The time format is shown below:
  10185. %@NL@%
  10186. %@NL@%
  10187. %@AB@%Bits%@AE@%                              %@AB@%Contents%@AE@%
  10188. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10189. 0 - 4                             Number of 2-second increments (0 - 29)
  10190.  
  10191. 5 -10                             Minutes (0 - 59)
  10192.  
  10193. 11-15                             Hours (0 - 23)
  10194.  
  10195. The date format is shown below:  %@NL@%
  10196. %@NL@%
  10197. %@AB@%Bits%@AE@%                              %@AB@%Contents%@AE@%
  10198. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10199. 0 - 4                             Day of month (1-31)
  10200.  
  10201. 5 - 8                             Month (1-12)
  10202.  
  10203. 9 -15                             Year (relative to 1980)
  10204.  
  10205. Do not alter the contents of the buffer between a call to %@AB@%_dos_findfirst%@AE@% and
  10206. a subsequent call to the %@AB@%_dos_findnext%@AE@% function. Also, the buffer should not
  10207. be altered between calls to %@AB@%_dos_findnext%@AE@%.  %@NL@%
  10208. %@NL@%
  10209. The %@AB@%_dos_findnext%@AE@% routine uses system call 0x4F to find the next name, if
  10210. any, that matches the %@AI@%filename%@AE@% and %@AI@%attrib%@AE@% arguments specified in a prior
  10211. call to %@AB@%_dos_findfirst%@AE@%. The %@AI@%fileinfo%@AE@% argument must point to a structure
  10212. initialized by a previous call to %@AB@%_dos_findfirst%@AE@%. The contents of the
  10213. structure will be altered as described above if a match is found.  %@NL@%
  10214. %@NL@%
  10215. %@NL@%
  10216. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10217. %@NL@%
  10218. If successful, both functions return 0. Otherwise, they return the DOS error
  10219. code and set %@AB@%errno%@AE@% to %@AB@%ENOENT%@AE@%, indicating that %@AI@% filename%@AE@% could not be
  10220. matched.  %@NL@%
  10221. %@NL@%
  10222. %@NL@%
  10223. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10224. %@NL@%
  10225.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10226. %@NL@%
  10227. %@NL@%
  10228. %@NL@%
  10229. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10230. %@NL@%
  10231. %@AS@%  /* DFIND.C: This program finds and prints all files in the current
  10232. %@AS@%  directory with
  10233. %@AS@%   * the .c extension.
  10234. %@AS@%   */
  10235. %@AS@%  
  10236. %@AS@%  #include <stdio.h>
  10237. %@AS@%  #include <dos.h>
  10238. %@AS@%  
  10239. %@AS@%  main()
  10240. %@AS@%  {
  10241. %@AS@%     struct find_t  c_file;
  10242. %@AS@%  
  10243. %@AS@%     /* find first .c file in current directory */
  10244. %@AS@%     _dos_findfirst( "*.c", _A_NORMAL, &c_file );
  10245. %@AS@%  
  10246. %@AS@%     printf( "Listing of .c files\n\n" );
  10247. %@AS@%     printf( "File: %s is %ld bytes\n", c_file.name, c_file.size );
  10248. %@AS@%  
  10249. %@AS@%     /* find the rest of the .c files */
  10250. %@AS@%     while( _dos_findnext( &c_file ) == 0 )
  10251. %@AS@%        printf( "File: %s is %ld bytes\n", c_file.name, c_file.size );
  10252. %@AS@%  }%@AE@%%@NL@%
  10253. %@NL@%
  10254. %@NL@%
  10255. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10256. %@NL@%
  10257. %@AS@%  
  10258. %@AS@%  
  10259. %@AS@%  Listing of .c files
  10260. %@AS@%  
  10261. %@AS@%  File: CHDIR.C is 524 bytes
  10262. %@AS@%  File: SIGFP.C is 2674 bytes
  10263. %@AS@%  File: MAX.C is 258 bytes
  10264. %@AS@%  File: CGETS.C is 577 bytes
  10265. %@AS@%  File: FWRITE.C is 1123 bytes %@AE@%%@NL@%
  10266. %@NL@%
  10267. %@NL@%
  10268. %@NL@%
  10269. %@NL@%
  10270. %@QR:_dos_freemem@%%@NL@%
  10271. %@2@%%@CR:C6A00610358 @%%@AB@%_dos_freemem%@AE@%%@EH@%%@NL@%
  10272. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10273. %@NL@%
  10274. %@NL@%
  10275. %@3@%%@AB@%Description%@CR:C6A00610359 @% %@CR:C6A00610360 @%%@AE@%%@EH@%%@NL@%
  10276. %@NL@%
  10277. Releases a block of memory (INT 0x49).  %@NL@%
  10278. %@NL@%
  10279. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10280. %@NL@%
  10281. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  10282. %@NL@%
  10283. %@AS@%  unsigned _dos_freemem( unsigned seg );%@AE@%%@NL@%
  10284. %@NL@%
  10285. %@AI@%seg%@AE@%                               Block to be released
  10286.  
  10287. %@NL@%
  10288. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10289. %@NL@%
  10290. The %@AB@%_dos_freemem%@AE@% function uses system call 0x49 to release a block of memory
  10291. previously allocated by %@AB@%_dos_allocmem%@AE@%. The %@AI@%seg%@AE@% argument is a value returned
  10292. by a previous call to %@AB@%_dos_allocmem%@AE@%. The freed memory may no longer be used
  10293. by the application program.  %@NL@%
  10294. %@NL@%
  10295. %@NL@%
  10296. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10297. %@NL@%
  10298. If successful, %@AB@%_dos_freemem%@AE@% returns 0. Otherwise, it returns the DOS error
  10299. code and sets %@AB@%errno%@AE@% to %@AB@%ENOMEM%@AE@%, indicating a bad segment value (one that does
  10300. not correspond to a segment returned by a previous %@AB@%_dos_allocmem%@AE@% call) or
  10301. invalid arena headers.  %@NL@%
  10302. %@NL@%
  10303. %@NL@%
  10304. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10305. %@NL@%
  10306.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10307. %@NL@%
  10308. %@NL@%
  10309. %@NL@%
  10310. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10311. %@NL@%
  10312. %@AB@%_dos_allocmem%@AE@%, %@AB@% _dos_setblock%@AE@%, %@AB@%free%@AE@% functions  %@NL@%
  10313. %@NL@%
  10314. %@NL@%
  10315. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10316. %@NL@%
  10317. %@AS@%  /* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases
  10318. %@AS@%   * the allocation to 40 paragraphs, and then frees the memory space.
  10319. %@AS@%   */
  10320. %@AS@%  
  10321. %@AS@%  #include <dos.h>
  10322. %@AS@%  #include <stdio.h>
  10323. %@AS@%  
  10324. %@AS@%  void main()
  10325. %@AS@%  {
  10326. %@AS@%     unsigned segment;
  10327. %@AS@%     unsigned maxsize;
  10328. %@AS@%  
  10329. %@AS@%     /* Allocate 20 paragraphs */
  10330. %@AS@%     if( _dos_allocmem( 20, &segment ) != 0 )
  10331. %@AS@%        printf( "allocation failed\n" );
  10332. %@AS@%     else
  10333. %@AS@%        printf( "allocation successful\n" );%@AE@%%@NL@%
  10334. %@NL@%
  10335. %@AS@%  /* Increase allocation to 40 paragraphs */
  10336. %@AS@%     if( _dos_setblock( 40, segment, &maxsize ) != 0 )
  10337. %@AS@%        printf( "allocation increase failed\n" );
  10338. %@AS@%     else
  10339. %@AS@%        printf( "allocation increase successful\n" );
  10340. %@AS@%  
  10341. %@AS@%     /* Free memory */
  10342. %@AS@%     if( _dos_freemem( segment ) != 0 )
  10343. %@AS@%        printf( "free memory failed\n" );
  10344. %@AS@%     else
  10345. %@AS@%        printf( "free memory successful\n" );
  10346. %@AS@%  }%@AE@%%@NL@%
  10347. %@NL@%
  10348. %@NL@%
  10349. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10350. %@NL@%
  10351. %@AS@%  
  10352. %@AS@%  
  10353. %@AS@%  allocation successful
  10354. %@AS@%  allocation increase successful
  10355. %@AS@%  free memory successful %@AE@%%@NL@%
  10356. %@NL@%
  10357. %@NL@%
  10358. %@NL@%
  10359. %@NL@%
  10360. %@QR:_dos_getdate@%%@NL@%
  10361. %@2@%%@CR:C6A00620361 @%%@AB@%_dos_getdate%@AE@%%@EH@%%@NL@%
  10362. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10363. %@NL@%
  10364. %@NL@%
  10365. %@3@%%@AB@%Description%@CR:C6A00620362 @% %@CR:C6A00620363 @%%@AE@%%@EH@%%@NL@%
  10366. %@NL@%
  10367. Gets current system date using system call INT 0x2A.  %@NL@%
  10368. %@NL@%
  10369. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10370. %@NL@%
  10371. %@AS@%  void _dos_getdate( struct dosdate_t *date );%@AE@%%@NL@%
  10372. %@NL@%
  10373. %@AI@%date%@AE@%                              Current system date
  10374.  
  10375. %@NL@%
  10376. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10377. %@NL@%
  10378. The %@AB@%_dos_getdate%@AE@% routine uses system call 0x2A to obtain the current system
  10379. date. The date is returned in a %@AB@%dosdate_t%@AE@% structure, defined in DOS.H.  %@NL@%
  10380. %@NL@%
  10381. The %@AB@%dosdate_t%@AE@% structure contains the following elements:  %@NL@%
  10382. %@NL@%
  10383. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  10384. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10385. %@AB@%unsigned char day%@AE@%                 1-31
  10386.  
  10387. %@AB@%unsigned char month%@AE@%               1-12
  10388.  
  10389. %@AB@%unsigned int year%@AE@%                 1980 - 2099
  10390.  
  10391. %@AB@%unsigned char dayofweek%@AE@%           0 - 6 (0 = Sunday)
  10392.  
  10393. %@NL@%
  10394. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10395. %@NL@%
  10396. None.  %@NL@%
  10397. %@NL@%
  10398. %@NL@%
  10399. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10400. %@NL@%
  10401.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10402. %@NL@%
  10403. %@NL@%
  10404. %@NL@%
  10405. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10406. %@NL@%
  10407. %@AB@%_dos_gettime%@AE@%, %@AB@% _dos_setdate%@AE@%, %@AB@% _dos_settime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%mktime%@AE@%, %@AB@%
  10408. %@AB@%_strdate%@AE@%, %@AB@%_strtime%@AE@%, %@AB@%time%@AE@%  %@NL@%
  10409. %@NL@%
  10410. %@NL@%
  10411. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10412. %@NL@%
  10413. %@AS@%  /* DGTIME.C: This program gets and displays current date and time values.
  10414. %@AS@%  */
  10415. %@AS@%  
  10416. %@AS@%  #include <stdio.h>
  10417. %@AS@%  #include <dos.h>
  10418. %@AS@%  
  10419. %@AS@%  void main()
  10420. %@AS@%  {
  10421. %@AS@%     struct dosdate_t date;
  10422. %@AS@%     struct dostime_t time;%@AE@%%@NL@%
  10423. %@NL@%
  10424. %@AS@%  /* Get current date and time values */
  10425. %@AS@%  
  10426. %@AS@%     _dos_getdate( &date );
  10427. %@AS@%     _dos_gettime( &time );
  10428. %@AS@%  
  10429. %@AS@%     printf( "Today's date is %d-%d-%d\n", date.month, date.day, date.year
  10430. %@AS@%);
  10431. %@AS@%     printf( "The time is %02d:%02d\n", time.hour, time.minute );
  10432. %@AS@%  }%@AE@%%@NL@%
  10433. %@NL@%
  10434. %@NL@%
  10435. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10436. %@NL@%
  10437. %@AS@%  
  10438. %@AS@%  
  10439. %@AS@%  Today's date is 6-15-1989
  10440. %@AS@%  The time is 18:07 %@AE@%%@NL@%
  10441. %@NL@%
  10442. %@NL@%
  10443. %@NL@%
  10444. %@NL@%
  10445. %@QR:_dos_getdiskfree@%%@NL@%
  10446. %@2@%%@CR:C6A00630364 @%%@AB@%_dos_getdiskfree%@AE@%%@EH@%%@NL@%
  10447. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10448. %@NL@%
  10449. %@NL@%
  10450. %@3@%%@AB@%Description%@CR:C6A00630365 @% %@CR:C6A00630366 @%%@AE@%%@EH@%%@NL@%
  10451. %@NL@%
  10452. Gets disk information using system call INT 0x36.  %@NL@%
  10453. %@NL@%
  10454. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10455. %@NL@%
  10456. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  10457. %@NL@%
  10458. %@AS@%  unsigned _dos_getdiskfree( unsigned drive, struct diskfree_t *diskspace );%@AE@%%@NL@%
  10459. %@NL@%
  10460. %@AI@%drive%@AE@%                             Drive number (default is 0)
  10461.  
  10462. %@AI@%diskspace%@AE@%                         Buffer to hold disk information
  10463.  
  10464. %@NL@%
  10465. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10466. %@NL@%
  10467. The %@AB@%_dos_getdiskfree%@AE@% routine uses system call 0x36 to obtain information on
  10468. the disk drive specified by %@AI@%drive%@AE@%. The default drive is 0, drive A is 1,
  10469. drive B is 2, and so on. Information is returned in the %@AB@%diskfree_t%@AE@% structure
  10470. (defined in DOS.H) pointed to by %@AI@%diskspace%@AE@%.  %@NL@%
  10471. %@NL@%
  10472. The %@AB@%struct diskfree_t%@AE@% structure contains the following elements:  %@NL@%
  10473. %@NL@%
  10474. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  10475. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10476. %@AB@%unsigned total_clusters%@AE@%           Total clusters on disk
  10477.  
  10478. %@AB@%unsigned avail_clusters%@AE@%           Available clusters on disk
  10479.  
  10480. %@AB@%unsigned sectors_per_cluster%@AE@%      Sectors per cluster
  10481.  
  10482. %@AB@%unsigned bytes_per_sector%@AE@%         Bytes per sector
  10483.  
  10484. %@NL@%
  10485. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10486. %@NL@%
  10487. If successful, the function returns 0. Otherwise, it returns a nonzero value
  10488. and sets %@AB@%errno%@AE@% to %@AB@%EINVAL%@AE@%, indicating that an invalid drive was specified.  %@NL@%
  10489. %@NL@%
  10490. %@NL@%
  10491. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10492. %@NL@%
  10493.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10494. %@NL@%
  10495. %@NL@%
  10496. %@NL@%
  10497. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10498. %@NL@%
  10499. %@AB@%_dos_getdrive%@AE@%, %@AB@%_dos_setdrive%@AE@%  %@NL@%
  10500. %@NL@%
  10501. %@NL@%
  10502. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10503. %@NL@%
  10504. %@AS@%  /* DGDISKFR.C: This program displays information about the default disk
  10505. %@AS@%  drive. */
  10506. %@AS@%  
  10507. %@AS@%  #include <stdio.h>
  10508. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10509. %@NL@%
  10510. %@AS@%  main()
  10511. %@AS@%  {
  10512. %@AS@%     struct diskfree_t drive;
  10513. %@AS@%  
  10514. %@AS@%     /* Get information on default disk drive 0 */
  10515. %@AS@%  
  10516. %@AS@%     _dos_getdiskfree( 0, &drive );
  10517. %@AS@%     printf( "total clusters: %d\n", drive.total_clusters );
  10518. %@AS@%     printf( "available clusters: %d\n", drive.avail_clusters );
  10519. %@AS@%     printf( "sectors per cluster: %d\n", drive.sectors_per_cluster );
  10520. %@AS@%     printf( "bytes per sector: %d\n", drive.bytes_per_sector );
  10521. %@AS@%  }%@AE@%%@NL@%
  10522. %@NL@%
  10523. %@NL@%
  10524. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10525. %@NL@%
  10526. %@AS@%  
  10527. %@AS@%  
  10528. %@AS@%  total clusters: 9013
  10529. %@AS@%  available clusters: 6030
  10530. %@AS@%  sectors per cluster: 4
  10531. %@AS@%  bytes per sector: 512%@AE@%%@NL@%
  10532. %@NL@%
  10533. %@NL@%
  10534. %@NL@%
  10535. %@NL@%
  10536. %@QR:_dos_getdrive@%%@NL@%
  10537. %@2@%%@CR:C6A00640367 @%%@AB@%_dos_getdrive%@AE@%%@EH@%%@NL@%
  10538. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10539. %@NL@%
  10540. %@NL@%
  10541. %@3@%%@AB@%Description%@CR:C6A00640368 @% %@CR:C6A00640369 @%%@AE@%%@EH@%%@NL@%
  10542. %@NL@%
  10543. Gets the current disk drive using system call INT 0x19.  %@NL@%
  10544. %@NL@%
  10545. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10546. %@NL@%
  10547. %@AS@%  void _dos_getdrive( unsigned *drive );%@AE@%%@NL@%
  10548. %@NL@%
  10549. %@AI@%drive%@AE@%                             Current-drive return buffer
  10550.  
  10551. %@NL@%
  10552. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10553. %@NL@%
  10554. The %@AB@%_dos_getdrive%@AE@% routine uses system call 0x19 to obtain the current disk
  10555. drive. The current drive is returned in the word that %@AI@%drive%@AE@% points to: 1 =
  10556. drive A, 2 = drive B, and so on.  %@NL@%
  10557. %@NL@%
  10558. %@NL@%
  10559. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10560. %@NL@%
  10561. None.  %@NL@%
  10562. %@NL@%
  10563. %@NL@%
  10564. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10565. %@NL@%
  10566.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10567. %@NL@%
  10568. %@NL@%
  10569. %@NL@%
  10570. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10571. %@NL@%
  10572. %@AB@%_dos_getdiskfree%@AE@%, %@AB@% _dos_setdrive%@AE@%, %@AB@% _getdrive%@AE@%  %@NL@%
  10573. %@NL@%
  10574. %@NL@%
  10575. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10576. %@NL@%
  10577. %@AS@%  /* DGDRIVE.C: This program prints the letter of the current drive,
  10578. %@AS@%   * changes the default drive to A, then returns the number of disk drives.
  10579. %@AS@%   */
  10580. %@AS@%  
  10581. %@AS@%  #include <stdio.h>
  10582. %@AS@%  #include <dos.h>
  10583. %@AS@%  
  10584. %@AS@%  void main()
  10585. %@AS@%  {
  10586. %@AS@%     unsigned olddrive, newdrive;
  10587. %@AS@%     unsigned number_of_drives;
  10588. %@AS@%  
  10589. %@AS@%     /* Print current default drive information */
  10590. %@AS@%     _dos_getdrive( &olddrive );
  10591. %@AS@%     printf( "The current drive is: %c\n", 'A' + olddrive1 );
  10592. %@AS@%  
  10593. %@AS@%     /* Set default drive to be drive A */
  10594. %@AS@%     printf( "Changing default drive to A\n");
  10595. %@AS@%     _dos_setdrive( 1, &number_of_drives );
  10596. %@AS@%  
  10597. %@AS@%     /* Get new default drive information and total number of drives */
  10598. %@AS@%     _dos_getdrive( &newdrive );
  10599. %@AS@%     printf( "The current drive is: %c\n", 'A' + newdrive1 );
  10600. %@AS@%     printf( "Number of logical drives: %d\n", number_of_drives );%@AE@%%@NL@%
  10601. %@NL@%
  10602. %@AS@%  /* Restore default drive */
  10603. %@AS@%     _dos_setdrive( olddrive, &number_of_drives );
  10604. %@AS@%  }%@AE@%%@NL@%
  10605. %@NL@%
  10606. %@NL@%
  10607. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10608. %@NL@%
  10609. %@AS@%  
  10610. %@AS@%  
  10611. %@AS@%  The current drive is: C
  10612. %@AS@%  Changing default drive to A
  10613. %@AS@%  The current drive is: A
  10614. %@AS@%  Number of logical drives: 26 %@AE@%%@NL@%
  10615. %@NL@%
  10616. %@NL@%
  10617. %@NL@%
  10618. %@NL@%
  10619. %@QR:_dos_getfileattr@%%@NL@%
  10620. %@2@%%@CR:C6A00650370 @%%@AB@%_dos_getfileattr%@AE@%%@EH@%%@NL@%
  10621. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10622. %@NL@%
  10623. %@NL@%
  10624. %@3@%%@AB@%Description%@CR:C6A00650371 @% %@CR:C6A00650372 @%%@AE@%%@EH@%%@NL@%
  10625. %@NL@%
  10626. Gets the current attributes of a file or directory, using system call INT
  10627. 0x43.  %@NL@%
  10628. %@NL@%
  10629. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10630. %@NL@%
  10631. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  10632. %@NL@%
  10633. %@AS@%  unsigned _dos_getfileattr( char *pathname, unsigned *attrib );%@AE@%%@NL@%
  10634. %@NL@%
  10635. %@AI@%pathname%@AE@%                          Full path of target file/directory
  10636.  
  10637. %@AI@%attrib%@AE@%                            Word to store attributes in
  10638.  
  10639. %@NL@%
  10640. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10641. %@NL@%
  10642. The %@AB@%_dos_getfileattr%@AE@% routine uses system call 0x43 to obtain the current
  10643. attributes of the file or directory pointed to by %@AI@%pathname%@AE@% . The attributes
  10644. are copied to the low-order byte of the %@AI@%attrib%@AE@% word. Attributes are
  10645. represented by manifest constants, as described below:  %@NL@%
  10646. %@NL@%
  10647. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  10648. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10649. %@AB@%_A_ARCH%@AE@%                           Archive. Set whenever the file is 
  10650.                                   changed, or cleared by the DOS BACKUP 
  10651.                                   command.
  10652.  
  10653. %@AB@%_A_HIDDEN%@AE@%                         Hidden file. Cannot be found by a 
  10654.                                   directory search.
  10655.  
  10656. %@AB@%_A_NORMAL%@AE@%                         Normal. File can be read or written 
  10657.                                   without restriction.
  10658.  
  10659. %@AB@%_A_RDONLY%@AE@%                         Read-only. File cannot be opened for a 
  10660.                                   write, and a file with the same name 
  10661.                                   cannot be created.
  10662.  
  10663. %@AB@%_A_SUBDIR%@AE@%                         Subdirectory.
  10664.  
  10665. %@AB@%_A_SYSTEM%@AE@%                         System file. Cannot be found by a 
  10666.                                   directory search.
  10667.  
  10668. %@AB@%_A_VOLID%@AE@%                          Volume ID. Only one file can have this 
  10669.                                   attribute, and it must be in the root 
  10670.                                   directory.
  10671.  
  10672. %@AB@%  %@AE@%%@NL@%
  10673. %@NL@%
  10674. %@NL@%
  10675. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10676. %@NL@%
  10677. If successful, the function returns 0. Otherwise, it returns the DOS error
  10678. code and sets %@AB@%errno%@AE@% to %@AB@%ENOENT%@AE@%, indicating that the target file or directory
  10679. could be found.  %@NL@%
  10680. %@NL@%
  10681. %@NL@%
  10682. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10683. %@NL@%
  10684.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10685. %@NL@%
  10686. %@NL@%
  10687. %@NL@%
  10688. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10689. %@NL@%
  10690. %@AB@%access%@AE@%, %@AB@%chmod%@AE@%, %@AB@%_dos_setfileattr%@AE@%, %@AB@%umask%@AE@%  %@NL@%
  10691. %@NL@%
  10692. %@NL@%
  10693. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10694. %@NL@%
  10695. %@AS@%  /* DGFILEAT.C: This program creates a file with the specified attributes,
  10696. %@AS@%   * then prints this information before changing the file attributes back 
  10697. %@AS@%   * to normal.
  10698. %@AS@%   */
  10699. %@AS@%  
  10700. %@AS@%  #include <stdio.h>
  10701. %@AS@%  #include <dos.h>
  10702. %@AS@%  
  10703. %@AS@%  void main()
  10704. %@AS@%  {
  10705. %@AS@%     unsigned oldattrib, newattrib;
  10706. %@AS@%     int fh;
  10707. %@AS@%  
  10708. %@AS@%     /* Get and display file attribute */
  10709. %@AS@%     _dos_getfileattr( "DGFILEAT.C", &oldattrib );
  10710. %@AS@%     printf( "Attribute: 0x%.4x\n", oldattrib );
  10711. %@AS@%     if( ( oldattrib & _A_RDONLY ) != 0 )
  10712. %@AS@%        printf( "Read only file\n" );
  10713. %@AS@%     else
  10714. %@AS@%        printf( "Not a read only file.\n" );
  10715. %@AS@%  
  10716. %@AS@%     /* Reset file attribute to normal file */
  10717. %@AS@%     _dos_setfileattr( "DGFILEAT.C", _A_RDONLY );
  10718. %@AS@%     _dos_getfileattr( "DGFILEAT.C", &newattrib );
  10719. %@AS@%     printf( "Attribute: 0x%.4x\n", newattrib );
  10720. %@AS@%  
  10721. %@AS@%     /* Restore file attribute */
  10722. %@AS@%     _dos_setfileattr( "DGFILEAT.C", oldattrib );
  10723. %@AS@%     _dos_getfileattr( "DGFILEAT.C", &newattrib );
  10724. %@AS@%     printf( "Attribute: 0x%.4x\n", newattrib );
  10725. %@AS@%  }%@AE@%%@NL@%
  10726. %@NL@%
  10727. %@NL@%
  10728. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10729. %@NL@%
  10730. %@AS@%  
  10731. %@AS@%  
  10732. %@AS@%  Attribute: 0x0020
  10733. %@AS@%  Not a read only file.
  10734. %@AS@%  Attribute: 0x0001
  10735. %@AS@%  Attribute: 0x0020 %@AE@%%@NL@%
  10736. %@NL@%
  10737. %@NL@%
  10738. %@NL@%
  10739. %@NL@%
  10740. %@QR:_dos_getftime@%%@NL@%
  10741. %@2@%%@CR:C6A00660373 @%%@AB@%_dos_getftime%@AE@%%@EH@%%@NL@%
  10742. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10743. %@NL@%
  10744. %@NL@%
  10745. %@3@%%@AB@%Description%@CR:C6A00660374 @% %@CR:C6A00660375 @%%@AE@%%@EH@%%@NL@%
  10746. %@NL@%
  10747. Gets the date and time a file was last written, using system call INT 0x57.
  10748. %@NL@%
  10749. %@NL@%
  10750. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10751. %@NL@%
  10752. %@AS@%  #include <errno.h>%@AE@%%@NL@%
  10753. %@NL@%
  10754. %@AS@%  unsigned _dos_getftime( int handle, unsigned *date, unsigned *time );%@AE@%%@NL@%
  10755. %@NL@%
  10756. %@AI@%handle%@AE@%                            Target file
  10757.  
  10758. %@AI@%date%@AE@%                              Date-return buffer
  10759.  
  10760. %@AI@%time%@AE@%                              Time-return buffer
  10761.  
  10762. %@NL@%
  10763. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10764. %@NL@%
  10765. The %@AB@%_dos_getftime%@AE@% routine uses system call 0x57 to get the date and time
  10766. that the specified file was last written. The file must have been opened
  10767. with a call to %@AB@%_dos_open%@AE@% or %@AB@%_dos_creat%@AE@% prior to calling %@AB@%_dos_getftime%@AE@%. The
  10768. date and time are returned in the words pointed to by %@AI@%date%@AE@% and %@AI@%time%@AE@%. The
  10769. values appear in the DOS date and time format:  %@NL@%
  10770. %@NL@%
  10771. %@AB@%Time Bits%@AE@%                         %@AB@%Meaning%@AE@%
  10772. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10773. 0 - 4                             Number of 2-second increments (0 -29)
  10774.  
  10775. 5 -10                             Minutes (0 -59)
  10776.  
  10777. 11-15                             Hours (0 -23)
  10778.  
  10779. %@AB@%Date Bits%@AE@%                         %@AB@%Meaning%@AE@%
  10780. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10781. 0 - 4                             Day (1-31)
  10782.  
  10783. 5 - 8                             Month (1-12)
  10784.  
  10785. 9 -15                             Year (1980 -2099)
  10786.  
  10787. %@NL@%
  10788. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10789. %@NL@%
  10790. If successful, the function returns 0. Otherwise, it returns the DOS error
  10791. code and sets %@AB@%errno%@AE@% to%@AB@% EBADF%@AE@%, indicating that an invalid file handle was
  10792. passed.  %@NL@%
  10793. %@NL@%
  10794. %@NL@%
  10795. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10796. %@NL@%
  10797.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10798. %@NL@%
  10799. %@NL@%
  10800. %@NL@%
  10801. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10802. %@NL@%
  10803. %@AB@%_dos_setftime%@AE@%, %@AB@%fstat%@AE@%, %@AB@%stat%@AE@%  %@NL@%
  10804. %@NL@%
  10805. %@NL@%
  10806. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10807. %@NL@%
  10808. %@AS@%  /* DGFTIME.C: This program displays and modifies the date and time
  10809. %@AS@%   * fields of a file.
  10810. %@AS@%   */
  10811. %@AS@%  
  10812. %@AS@%  #include <fcntl.h>
  10813. %@AS@%  #include <stdio.h>
  10814. %@AS@%  #include <stdlib.h>
  10815. %@AS@%  #include <dos.h>
  10816. %@AS@%  
  10817. %@AS@%  void main()
  10818. %@AS@%  {
  10819. %@AS@%                                   /* FEDC BA98 7654 3210          */
  10820. %@AS@%     unsigned new_date = 0x184f;   /* 0001 1000 0100 1111  2/15/92 */
  10821. %@AS@%     unsigned new_time = 0x48e0;   /* 0100 1000 1110 0000  9:07 AM */
  10822. %@AS@%     unsigned old_date, old_time;
  10823. %@AS@%  
  10824. %@AS@%     int fh;
  10825. %@AS@%  
  10826. %@AS@%     /* Open file with _dos_open function */
  10827. %@AS@%     if( _dos_open( "dgftime.obj", O_RDONLY, &fh ) != 0 )
  10828. %@AS@%        exit( 1 );
  10829. %@AS@%  
  10830. %@AS@%     /* Get file date and time */
  10831. %@AS@%     _dos_getftime( fh, &old_date, &old_time );
  10832. %@AS@%     printf( "Old date field: 0x%.4x\n", old_date );
  10833. %@AS@%     printf( "Old time field: 0x%.4x\n", old_time );
  10834. %@AS@%     system( "dir dgftime.obj" );
  10835. %@AS@%  
  10836. %@AS@%     /* Modify file date and time */
  10837. %@AS@%     if( !_dos_setftime( fh, new_date, new_time ) )
  10838. %@AS@%     {
  10839. %@AS@%        _dos_getftime( fh, &new_date, &new_time );
  10840. %@AS@%        printf( "New date field: 0x%.4x\n", new_date );
  10841. %@AS@%        printf( "New time field: 0x%.4x\n", new_time );
  10842. %@AS@%        system( "dir dgftime.obj" );
  10843. %@AS@%  
  10844. %@AS@%        /* Restore date and time */
  10845. %@AS@%        _dos_setftime( fh, old_date, old_time );
  10846. %@AS@%     }
  10847. %@AS@%     _dos_close( fh );
  10848. %@AS@%  }%@AE@%%@NL@%
  10849. %@NL@%
  10850. %@NL@%
  10851. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10852. %@NL@%
  10853. %@AS@%  
  10854. %@AS@%  
  10855. %@AS@%  Old date field: 0x12cf
  10856. %@AS@%  Old time field: 0x94bb
  10857. %@AS@%  
  10858. %@AS@%   Volume in drive C is OS2
  10859. %@AS@%   Directory of  C:\LIBREF
  10860. %@AS@%  
  10861. %@AS@%  DGFTIME  OBJ     3923   6-15-89   6:37p
  10862. %@AS@%          1 File(s)  13676544 bytes free
  10863. %@AS@%  
  10864. %@AS@%  New date field: 0x184f
  10865. %@AS@%  New time field: 0x48e0
  10866. %@AS@%  
  10867. %@AS@%   Volume in drive C is OS2
  10868. %@AS@%   Directory of  C:\LIBREF
  10869. %@AS@%  
  10870. %@AS@%  DGFTIME  OBJ     3923   2-15-92   9:07a
  10871. %@AS@%          1 File(s)  13676544 bytes free %@AE@%%@NL@%
  10872. %@NL@%
  10873. %@NL@%
  10874. %@NL@%
  10875. %@NL@%
  10876. %@QR:_dos_gettime@%%@NL@%
  10877. %@2@%%@CR:C6A00670376 @%%@AB@%_dos_gettime%@AE@%%@EH@%%@NL@%
  10878. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10879. %@NL@%
  10880. %@NL@%
  10881. %@3@%%@AB@%Description%@CR:C6A00670377 @% %@CR:C6A00670378 @%%@AE@%%@EH@%%@NL@%
  10882. %@NL@%
  10883. Gets the current system time, using system call INT 0x2C.  %@NL@%
  10884. %@NL@%
  10885. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10886. %@NL@%
  10887. %@AS@%  void _dos_gettime( struct dostime_t *time );%@AE@%%@NL@%
  10888. %@NL@%
  10889. %@AI@%time%@AE@%                              Current system time
  10890.  
  10891. %@NL@%
  10892. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10893. %@NL@%
  10894. The %@AB@%_dos_gettime%@AE@% routine uses system call 0x2C to obtain the current system
  10895. time. The time is returned in a %@AB@%dostime_t%@AE@% structure, defined in DOS.H.  %@NL@%
  10896. %@NL@%
  10897. The %@AB@%dostime_t%@AE@% structure contains the following elements:  %@NL@%
  10898. %@NL@%
  10899. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  10900. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10901. %@AB@%unsigned char hour%@AE@%                0 -23
  10902.  
  10903. %@AB@%unsigned char minute%@AE@%              0 -59
  10904.  
  10905. %@AB@%unsigned char second%@AE@%              0 -59
  10906.  
  10907. %@AB@%unsigned char hsecond%@AE@%             1/100 second; 0 -99
  10908.  
  10909. %@NL@%
  10910. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10911. %@NL@%
  10912. None.  %@NL@%
  10913. %@NL@%
  10914. %@NL@%
  10915. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10916. %@NL@%
  10917.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  10918. %@NL@%
  10919. %@NL@%
  10920. %@NL@%
  10921. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  10922. %@NL@%
  10923. %@AB@%_dos_getdate%@AE@%, %@AB@% _dos_setdate%@AE@%, %@AB@% _dos_settime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@% _strtime%@AE@%  %@NL@%
  10924. %@NL@%
  10925. %@NL@%
  10926. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  10927. %@NL@%
  10928. %@AS@%  /* DGTIME.C: This program gets and displays current date and time values.
  10929. %@AS@%  */
  10930. %@AS@%  
  10931. %@AS@%  #include <stdio.h>
  10932. %@AS@%  #include <dos.h>
  10933. %@AS@%  
  10934. %@AS@%  void main()
  10935. %@AS@%  {
  10936. %@AS@%     struct dosdate_t date;
  10937. %@AS@%     struct dostime_t time;%@AE@%%@NL@%
  10938. %@NL@%
  10939. %@AS@%  /* Get current date and time values */
  10940. %@AS@%  
  10941. %@AS@%     _dos_getdate( &date );
  10942. %@AS@%     _dos_gettime( &time );
  10943. %@AS@%  
  10944. %@AS@%     printf( "Today's date is %d-%d-%d\n", date.month, date.day, date.year
  10945. %@AS@%);
  10946. %@AS@%     printf( "The time is %02d:%02d\n", time.hour, time.minute );
  10947. %@AS@%  }%@AE@%%@NL@%
  10948. %@NL@%
  10949. %@NL@%
  10950. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  10951. %@NL@%
  10952. %@AS@%  
  10953. %@AS@%  
  10954. %@AS@%  Today's date is 6-15-1989
  10955. %@AS@%  The time is 18:07 %@AE@%%@NL@%
  10956. %@NL@%
  10957. %@NL@%
  10958. %@NL@%
  10959. %@NL@%
  10960. %@QR:_dos_getvect@%%@NL@%
  10961. %@2@%%@CR:C6A00680379 @%%@AB@%_dos_getvect%@AE@%%@EH@%%@NL@%
  10962. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  10963. %@NL@%
  10964. %@NL@%
  10965. %@3@%%@AB@%Description%@CR:C6A00680380 @% %@CR:C6A00680381 @%%@AE@%%@EH@%%@NL@%
  10966. %@NL@%
  10967. Gets the current value of the interrupt vector, using system call INT 0x35.
  10968. %@NL@%
  10969. %@NL@%
  10970. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  10971. %@NL@%
  10972. %@AS@%  void ( _interrupt _far *_dos_getvect( unsigned intnum))();%@AE@%%@NL@%
  10973. %@NL@%
  10974. %@AI@%intnum%@AE@%                            Target interrupt vector
  10975.  
  10976. %@NL@%
  10977. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  10978. %@NL@%
  10979. The %@AB@%_dos_getvect%@AE@% routine uses system call INT 0x35 to get the current value
  10980. of the interrupt vector specified by %@AI@%intnum%@AE@%.  %@NL@%
  10981. %@NL@%
  10982. This routine is typically used in conjunction with the %@AB@%_dos_setvect%@AE@%
  10983. function. To replace an interrupt vector, first save the current vector of
  10984. the interrupt using %@AB@%_dos_getvect%@AE@%. Then set the vector to your own interrupt
  10985. routine with %@AB@%_dos_setvect%@AE@%. The saved vector can later be restored, if
  10986. necessary, using %@AB@%_dos_setvect%@AE@%. The user-defined routine may also need the
  10987. original vector in order to call that vector or chain to it with
  10988. %@AB@%_chain_intr%@AE@%.  %@NL@%
  10989. %@NL@%
  10990. %@NL@%
  10991. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  10992. %@NL@%
  10993. The function returns a far pointer for the %@AI@%intnum%@AE@% interrupt to the current
  10994. handler, if there is one.  %@NL@%
  10995. %@NL@%
  10996. %@NL@%
  10997. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  10998. %@NL@%
  10999.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11000. %@NL@%
  11001. %@NL@%
  11002. %@NL@%
  11003. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11004. %@NL@%
  11005. %@AB@%_chain_intr%@AE@%, %@AB@% _dos_keep%@AE@%, %@AB@% _dos_setvect%@AE@%  %@NL@%
  11006. %@NL@%
  11007. %@NL@%
  11008. %@NL@%
  11009. %@NL@%
  11010. %@QR:_dos_keep@%%@NL@%
  11011. %@2@%%@CR:C6A00690382 @%%@AB@%_dos_keep%@AE@%%@EH@%%@NL@%
  11012. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11013. %@NL@%
  11014. %@NL@%
  11015. %@3@%%@AB@%Description%@CR:C6A00690383 @% %@CR:C6A00690384 @%%@AE@%%@EH@%%@NL@%
  11016. %@NL@%
  11017. Installs TSR (terminate-and-stay-resident) programs in memory, using system
  11018. call INT 0x31.  %@NL@%
  11019. %@NL@%
  11020. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11021. %@NL@%
  11022. %@AS@%  void _dos_keep( unsigned retcode, unsigned memsize );%@AE@%%@NL@%
  11023. %@NL@%
  11024. %@AI@%retcode%@AE@%                           Exit status code
  11025.  
  11026. %@AI@%memsize%@AE@%                           Allocated resident memory (in 16-byte 
  11027.                                   paragraphs)
  11028.  
  11029. %@NL@%
  11030. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11031. %@NL@%
  11032. The %@AB@%_dos_keep%@AE@% routine installs TSRs (terminate-and-stay-resident programs)
  11033. in memory, using system call INT 0x31.  %@NL@%
  11034. %@NL@%
  11035. The routine first exits the calling process, leaving it in memory. It then
  11036. returns the low-order byte of %@AI@%retcode%@AE@% to the parent of the calling process.
  11037. Before returning execution to the parent process, %@AB@%_dos_keep%@AE@% sets the
  11038. allocated memory for the now-resident process to %@AI@%memsize%@AE@% 16-byte paragraphs.
  11039. Any excess memory is returned to the system.  %@NL@%
  11040. %@NL@%
  11041. The %@AB@%_dos_keep%@AE@% function calls the same internal routines called by %@AB@%exit%@AE@%. It
  11042. therefore takes the following actions:  %@NL@%
  11043. %@NL@%
  11044. %@NL@%
  11045.   ■   Calls %@AB@%atexit%@AE@% and %@AB@%onexit%@AE@% if defined.%@NL@%
  11046. %@NL@%
  11047.   ■   Flushes all file buffers.%@NL@%
  11048. %@NL@%
  11049.   ■   Restores interrupt vectors replaced by the C start-up code. The
  11050.       primary one is interrupt 0 (divide by zero). If the emulator math
  11051.       library is used and there is no coprocessor, interrupts 0x34 through
  11052.       0x3D are restored. If there is a coprocessor, interrupt 2 is restored.%@NL@%
  11053. %@NL@%
  11054. %@NL@%
  11055. The %@AB@%_dos_keep%@AE@% function does not automatically close files; you should do
  11056. this specifically unless you want files opened by the TSR installation code
  11057. to remain open for the TSR.  %@NL@%
  11058. %@NL@%
  11059. Do not use the emulator math library in TSRs unless you are familiar with
  11060. the C start-up code and the coprocessor. Use the alternate math package (not
  11061. supplied with Microsoft QuickC) if the TSR must do floating-point math.  %@NL@%
  11062. %@NL@%
  11063. Do not run programs that use %@AB@%_dos_keep%@AE@% from inside the Microsoft
  11064. Programmer's WorkBench environment, since doing so causes subsequent memory
  11065. problems. The %@AB@%_dos_keep%@AE@% function terminates the program when executed in the
  11066. Programmer's WorkBench environment.  %@NL@%
  11067. %@NL@%
  11068. %@NL@%
  11069. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11070. %@NL@%
  11071. None.  %@NL@%
  11072. %@NL@%
  11073. %@NL@%
  11074. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11075. %@NL@%
  11076.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11077. %@NL@%
  11078. %@NL@%
  11079. %@NL@%
  11080. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11081. %@NL@%
  11082. %@AB@%_cexit%@AE@%,%@AB@%  _chain_intr%@AE@%, %@AB@% _dos_getvect%@AE@%, %@AB@% _dos_setvect%@AE@%, %@AB@% _exit %@AE@%  %@NL@%
  11083. %@NL@%
  11084. %@NL@%
  11085. %@NL@%
  11086. %@NL@%
  11087. %@QR:_dos_open@%%@NL@%
  11088. %@2@%%@CR:C6A00700385 @%%@AB@%_dos_open%@AE@%%@EH@%%@NL@%
  11089. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11090. %@NL@%
  11091. %@NL@%
  11092. %@3@%%@AB@%Description%@CR:C6A00700386 @% %@CR:C6A00700387 @%%@AE@%%@EH@%%@NL@%
  11093. %@NL@%
  11094. Opens a file, using system call INT 0x3D.  %@NL@%
  11095. %@NL@%
  11096. %@AB@%#include <dos.h>%@AE@%                  
  11097.  
  11098. %@AB@%#include <errno.h>%@AE@%                
  11099.  
  11100. %@AB@%#include <fcntl.h>%@AE@%                Access mode constants
  11101.  
  11102. %@AB@%#include <share.h>%@AE@%                Sharing mode constants
  11103.  
  11104. %@AS@%  unsigned _dos_open( char *filename, unsigned mode, int *handle );%@AE@%%@NL@%
  11105. %@NL@%
  11106. %@AI@%filename%@AE@%                          Path to an existing file
  11107.  
  11108. %@AI@%mode%@AE@%                              Permissions
  11109.  
  11110. %@AI@%handle%@AE@%                            Pointer to integer
  11111.  
  11112. %@NL@%
  11113. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11114. %@NL@%
  11115. The %@AB@%_dos_open%@AE@% routine uses system call INT 0x3D to open the existing file
  11116. pointed to by %@AI@%filename%@AE@%. The handle for the opened file is copied into the
  11117. integer pointed to by %@AI@%handle%@AE@%. The %@AI@%mode%@AE@% argument specifies the file's access,
  11118. sharing, and inheritance modes by combining (with the OR operator) manifest
  11119. constants from the three groups shown below. At most, one access mode and
  11120. one sharing mode can be specified at a time.  %@NL@%
  11121. %@NL@%
  11122. %@TH:  21   950 02 14 33 33 @%%@AB@%Constant%@AE@%      %@AB@%Mode%@AE@%                             %@AB@%Meaning%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%O_RDONLY%@AE@%      Access                           Read-only%@AB@%O_WRONLY%@AE@%      Access                           Write-only%@AB@%O_RDWR%@AE@%        Access                           Both read and write%@AB@%SH_COMPAT%@AE@%     Sharing                          Compatibility%@AB@%SH_DENYRW%@AE@%     Sharing                          Deny reading and writing%@AB@%SH_DENYWR%@AE@%     Sharing                          Deny writing%@AB@%SH_DENYRD%@AE@%     Sharing                          Deny reading%@AB@%SH_DENYNO%@AE@%     Sharing                          Deny neither%@AB@%O_NOINHERIT%@AE@%   Inheritance by the child         File is not inherited              process                          %@TE:  21   950 02 14 33 33 @%
  11123.  
  11124. Do not use the DOS interface I/O routines in conjunction with the console,
  11125. low-level, or stream I/O routines.  %@NL@%
  11126. %@NL@%
  11127. %@NL@%
  11128. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11129. %@NL@%
  11130. If successful, the function returns 0. Otherwise, it returns the DOS error
  11131. code and sets %@AB@%errno%@AE@% to one of the following manifest constants:  %@NL@%
  11132. %@NL@%
  11133. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  11134. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11135. %@AB@%EACCES%@AE@%                            Access denied (possible reasons include 
  11136.                                   specifying a directory or volume ID for %@AI@%%@AE@%
  11137.                                   %@AI@%filename%@AE@%, or opening a read-only file 
  11138.                                   for write access)
  11139.  
  11140. %@AB@%EINVAL%@AE@%                            Sharing mode specified when file sharing
  11141.                                   not installed, or
  11142.                                   access-mode value is invalid
  11143.  
  11144. %@AB@%%@AE@%%@AB@%EMFILE%@AE@%                            Too many open file handles
  11145.  
  11146. %@AB@%%@AE@%%@AB@%ENOENT%@AE@%                            Path or file not found
  11147.  
  11148. %@NL@%
  11149. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11150. %@NL@%
  11151.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11152. %@NL@%
  11153. %@NL@%
  11154. %@NL@%
  11155. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11156. %@NL@%
  11157. %@AB@%_dos_close%@AE@%, %@AB@% _dos_read%@AE@%,  %@AB@%_dos_write%@AE@%  %@NL@%
  11158. %@NL@%
  11159. %@NL@%
  11160. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11161. %@NL@%
  11162. %@AS@%  /* DOPEN.C: This program uses DOS I/O functions to open and close a file.
  11163. %@AS@%  */
  11164. %@AS@%  
  11165. %@AS@%  #include <fcntl.h>
  11166. %@AS@%  #include <stdio.h>
  11167. %@AS@%  #include <dos.h>
  11168. %@AS@%  
  11169. %@AS@%  void main()
  11170. %@AS@%  {
  11171. %@AS@%     int fh;
  11172. %@AS@%  
  11173. %@AS@%     /* Open file with _dos_open function */
  11174. %@AS@%     if( _dos_open( "data1", O_RDONLY, &fh ) != 0 )
  11175. %@AS@%        perror( "Open failed on input file\n" );
  11176. %@AS@%     else
  11177. %@AS@%        printf( "Open succeeded on input file\n" );
  11178. %@AS@%  
  11179. %@AS@%     /* Close file with _dos_close function */
  11180. %@AS@%     if( _dos_close( fh ) != 0 )
  11181. %@AS@%        perror( "Close failed\n" );
  11182. %@AS@%     else
  11183. %@AS@%        printf( "File successfully closed\n" );
  11184. %@AS@%  }%@AE@%%@NL@%
  11185. %@NL@%
  11186. %@NL@%
  11187. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11188. %@NL@%
  11189. %@AS@%  
  11190. %@AS@%  
  11191. %@AS@%  Open succeeded on input file
  11192. %@AS@%  File successfully closed %@AE@%%@NL@%
  11193. %@NL@%
  11194. %@NL@%
  11195. %@NL@%
  11196. %@NL@%
  11197. %@QR:_dos_read@%%@NL@%
  11198. %@2@%%@CR:C6A00710388 @%%@AB@%_dos_read%@AE@%%@EH@%%@NL@%
  11199. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11200. %@NL@%
  11201. %@NL@%
  11202. %@3@%%@AB@%Description%@CR:C6A00710389 @% %@CR:C6A00710390 @%%@AE@%%@EH@%%@NL@%
  11203. %@NL@%
  11204. Reads data from a file, using system call INT 0x3F.  %@NL@%
  11205. %@NL@%
  11206. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11207. %@NL@%
  11208. %@AS@%  unsigned _dos_read( int handle, void _far *buffer, unsigned count, 
  11209. %@AS@%  unsigned *numread );%@AE@%%@NL@%
  11210. %@NL@%
  11211. %@AI@%handle%@AE@%                            File to read
  11212.  
  11213. %@AI@%buffer%@AE@%                            Buffer to write to
  11214.  
  11215. %@AI@%count%@AE@%                             Number of bytes to read
  11216.  
  11217. %@AI@%numread%@AE@%                           Number of bytes actually read
  11218.  
  11219. %@NL@%
  11220. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11221. %@NL@%
  11222. The %@AB@%_dos_read%@AE@% routine uses system call INT 0x3F to read %@AI@%count%@AE@% bytes of data
  11223. from the file specified by %@AI@%handle%@AE@%. The routine then copies the data to the
  11224. buffer pointed to by %@AI@%buffer%@AE@%. The integer pointed to by %@AI@%numread%@AE@% will show the
  11225. number of bytes actually read, which may be less than the number requested
  11226. in %@AI@%count%@AE@%. If the number of bytes actually read is 0, it means the routine
  11227. tried to read at end-of-file.  %@NL@%
  11228. %@NL@%
  11229. Do not use the DOS interface I/O routines in conjunction with the console,
  11230. low-level, or stream I/O routines.  %@NL@%
  11231. %@NL@%
  11232. %@NL@%
  11233. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11234. %@NL@%
  11235. If successful, the function returns 0. Otherwise, it returns the DOS error
  11236. code and sets %@AB@%errno%@AE@% to one of the following constants:  %@NL@%
  11237. %@NL@%
  11238. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  11239. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11240. %@AB@%EACCES%@AE@%                            Access denied (%@AI@%handle%@AE@% is not open for 
  11241.                                   read access)
  11242.  
  11243. %@AB@%EBADF%@AE@%                             File handle is invalid
  11244.  
  11245. %@NL@%
  11246. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11247. %@NL@%
  11248.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11249. %@NL@%
  11250. %@NL@%
  11251. %@NL@%
  11252. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11253. %@NL@%
  11254. %@AB@%_dos_close%@AE@%, %@AB@% _dos_open%@AE@%, %@AB@% _dos_write%@AE@%, %@AB@%read%@AE@%  %@NL@%
  11255. %@NL@%
  11256. %@NL@%
  11257. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11258. %@NL@%
  11259. %@AS@%  /* DREAD.C: This program uses the DOS I/O operations to read the contents
  11260. %@AS@%   * of a file.
  11261. %@AS@%   */%@AE@%%@NL@%
  11262. %@NL@%
  11263. %@AS@%  #include <fcntl.h>
  11264. %@AS@%  #include <stdlib.h>
  11265. %@AS@%  #include <stdio.h>
  11266. %@AS@%  #include <dos.h>
  11267. %@AS@%  
  11268. %@AS@%  void main()
  11269. %@AS@%  {
  11270. %@AS@%     int fh;
  11271. %@AS@%     char buffer[50];
  11272. %@AS@%     unsigned number_read;
  11273. %@AS@%  
  11274. %@AS@%     /* Open file with _dos_open function */
  11275. %@AS@%     if( _dos_open( "dread.c", O_RDONLY, &fh ) != 0 )
  11276. %@AS@%        perror( "Open failed on input file\n" );
  11277. %@AS@%     else
  11278. %@AS@%        printf( "Open succeeded on input file\n" );
  11279. %@AS@%  
  11280. %@AS@%     /* Read data with _dos_read function */
  11281. %@AS@%     _dos_read( fh, buffer, 50, &number_read );
  11282. %@AS@%     printf( "First 40 characters are: %.40s\n\n", buffer );
  11283. %@AS@%  
  11284. %@AS@%     /* Close file with _dos_close function */
  11285. %@AS@%     _dos_close( fh );
  11286. %@AS@%  }%@AE@%%@NL@%
  11287. %@NL@%
  11288. %@NL@%
  11289. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11290. %@NL@%
  11291. %@AS@%  
  11292. %@AS@%  
  11293. %@AS@%  Open succeeded on input file
  11294. %@AS@%  First 40 characters are: /* DREAD.C: This program uses the DOS I/ %@AE@%%@NL@%
  11295. %@NL@%
  11296. %@NL@%
  11297. %@NL@%
  11298. %@NL@%
  11299. %@QR:_dos_setblock@%%@NL@%
  11300. %@2@%%@CR:C6A00720391 @%%@AB@%_dos_setblock%@AE@%%@EH@%%@NL@%
  11301. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11302. %@NL@%
  11303. %@NL@%
  11304. %@3@%%@AB@%Description%@CR:C6A00720392 @% %@CR:C6A00720393 @%%@AE@%%@EH@%%@NL@%
  11305. %@NL@%
  11306. Changes the size of a memory segment, using system call INT 0x4A.  %@NL@%
  11307. %@NL@%
  11308. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11309. %@NL@%
  11310. %@AS@%  unsigned _dos_setblock( unsigned size, unsigned seg, unsigned *maxsize );%@AE@%%@NL@%
  11311. %@NL@%
  11312. %@AI@%size%@AE@%                              New segment size
  11313.  
  11314. %@AI@%seg%@AE@%                               Target segment
  11315.  
  11316. %@AI@%maxsize%@AE@%                           Maximum-size buffer
  11317.  
  11318. %@NL@%
  11319. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11320. %@NL@%
  11321. The %@AB@%_dos_setblock%@AE@% routine uses system call INT 0x4A to change the size of
  11322. %@AI@%seg%@AE@%, previously allocated by %@AB@%_dos_allocmem%@AE@%, to %@AI@%size%@AE@% paragraphs. If the
  11323. request cannot be satisfied, the maximum possible segment size is copied to
  11324. the buffer pointed to by %@AI@%maxsize%@AE@%.  %@NL@%
  11325. %@NL@%
  11326. %@NL@%
  11327. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11328. %@NL@%
  11329. The function returns 0 if successful. If the call fails, it returns the DOS
  11330. error code and sets %@AB@%errno%@AE@% to %@AB@%ENOMEM%@AE@%, indicating a bad segment value was
  11331. passed. A bad segment value is one that does not correspond to a segment
  11332. returned from a previous %@AB@%_dos_allocmem%@AE@% call, or one that contains invalid
  11333. arena headers.  %@NL@%
  11334. %@NL@%
  11335. %@NL@%
  11336. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11337. %@NL@%
  11338.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11339. %@NL@%
  11340. %@NL@%
  11341. %@NL@%
  11342. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11343. %@NL@%
  11344. %@AB@%_dos_allocmem%@AE@%, %@AB@% _dos_freemem%@AE@%, %@AB@%realloc%@AE@% functions  %@NL@%
  11345. %@NL@%
  11346. %@NL@%
  11347. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11348. %@NL@%
  11349. %@AS@%  /* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases
  11350. %@AS@%   * the allocation to 40 paragraphs, and then frees the memory space.
  11351. %@AS@%   */
  11352. %@AS@%  
  11353. %@AS@%  #include <dos.h>
  11354. %@AS@%  #include <stdio.h>
  11355. %@AS@%  
  11356. %@AS@%  void main()
  11357. %@AS@%  {
  11358. %@AS@%     unsigned segment;
  11359. %@AS@%     unsigned maxsize;%@AE@%%@NL@%
  11360. %@NL@%
  11361. %@AS@%  /* Allocate 20 paragraphs */
  11362. %@AS@%     if( _dos_allocmem( 20, &segment ) != 0 )
  11363. %@AS@%        printf( "allocation failed\n" );
  11364. %@AS@%     else
  11365. %@AS@%        printf( "allocation successful\n" );
  11366. %@AS@%  
  11367. %@AS@%     /* Increase allocation to 40 paragraphs */
  11368. %@AS@%     if( _dos_setblock( 40, segment, &maxsize ) != 0 )
  11369. %@AS@%        printf( "allocation increase failed\n" );
  11370. %@AS@%     else
  11371. %@AS@%        printf( "allocation increase successful\n" );
  11372. %@AS@%  
  11373. %@AS@%     /* Free memory */
  11374. %@AS@%     if( _dos_freemem( segment ) != 0 )
  11375. %@AS@%        printf( "free memory failed\n" );
  11376. %@AS@%     else
  11377. %@AS@%        printf( "free memory successful\n" );
  11378. %@AS@%  }%@AE@%%@NL@%
  11379. %@NL@%
  11380. %@NL@%
  11381. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11382. %@NL@%
  11383. %@AS@%  
  11384. %@AS@%  
  11385. %@AS@%  allocation successful
  11386. %@AS@%  allocation increase successful
  11387. %@AS@%  free memory successful %@AE@%%@NL@%
  11388. %@NL@%
  11389. %@NL@%
  11390. %@NL@%
  11391. %@NL@%
  11392. %@QR:_dos_setdate@%%@NL@%
  11393. %@2@%%@CR:C6A00730394 @%%@AB@%_dos_setdate%@AE@%%@EH@%%@NL@%
  11394. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11395. %@NL@%
  11396. %@NL@%
  11397. %@3@%%@AB@%Description%@CR:C6A00730395 @% %@CR:C6A00730396 @%%@AE@%%@EH@%%@NL@%
  11398. %@NL@%
  11399. Sets the current system date, using system call INT 0x2B.  %@NL@%
  11400. %@NL@%
  11401. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11402. %@NL@%
  11403. %@AS@%  unsigned _dos_setdate( struct dosdate_t *date );%@AE@%%@NL@%
  11404. %@NL@%
  11405. %@AI@%date%@AE@%                              New system date
  11406.  
  11407. %@NL@%
  11408. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11409. %@NL@%
  11410. The %@AB@%_dos_setdate%@AE@% routine uses system call INT 0x2B to set the current system
  11411. date. The date is stored in the %@AB@%dosdate_t%@AE@% structure pointed to by %@AI@%date%@AE@%,
  11412. defined in DOS.H. The %@AB@%dosdate_t%@AE@% structure contains the following elements:  %@NL@%
  11413. %@NL@%
  11414. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  11415. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11416. %@AB@%unsigned char day%@AE@%                 1 -31
  11417.  
  11418. %@AB@%unsigned char month%@AE@%               1 -12
  11419.  
  11420. %@AB@%unsigned int year%@AE@%                 1980 - 2099
  11421.  
  11422. %@AB@%unsigned char dayofweek%@AE@%           0 - 6 (0 = Sunday)
  11423.  
  11424. %@NL@%
  11425. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11426. %@NL@%
  11427. If successful, the function returns 0. Otherwise, it returns a nonzero value
  11428. and sets %@AB@%errno%@AE@% to %@AB@%EINVAL%@AE@%, indicating an invalid date was specified.  %@NL@%
  11429. %@NL@%
  11430. %@NL@%
  11431. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11432. %@NL@%
  11433.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11434. %@NL@%
  11435. %@NL@%
  11436. %@NL@%
  11437. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11438. %@NL@%
  11439. %@AB@%_dos_gettime%@AE@%, %@AB@% _dos_setdate%@AE@%, %@AB@% _dos_settime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%mktime%@AE@%, %@AB@%
  11440. %@AB@%_strdate%@AE@%, %@AB@%_strtime%@AE@%, %@AB@%time%@AE@%  %@NL@%
  11441. %@NL@%
  11442. %@NL@%
  11443. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11444. %@NL@%
  11445. %@AS@%  /* DSTIME.C: This program changes the time and date values and displays
  11446. %@AS@%  the
  11447. %@AS@%   * new date and time values.
  11448. %@AS@%   */
  11449. %@AS@%  
  11450. %@AS@%  #include <dos.h>
  11451. %@AS@%  #include <conio.h>
  11452. %@AS@%  #include <stdio.h>
  11453. %@AS@%  #include <time.h>%@AE@%%@NL@%
  11454. %@NL@%
  11455. %@AS@%  void main()
  11456. %@AS@%  {
  11457. %@AS@%     struct dosdate_t olddate, newdate = { { 4 }, { 7 }, { 1984 } };
  11458. %@AS@%     struct dostime_t oldtime, newtime = { { 3 }, { 45 }, { 30 }, { 0 } };
  11459. %@AS@%     char   datebuf[40], timebuf[40];
  11460. %@AS@%  
  11461. %@AS@%     /* Get current date and time values */
  11462. %@AS@%     _dos_getdate( &olddate );
  11463. %@AS@%     _dos_gettime( &oldtime );
  11464. %@AS@%     printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );
  11465. %@AS@%  
  11466. %@AS@%     /* Modify date and time structures */
  11467. %@AS@%     _dos_setdate( &newdate );
  11468. %@AS@%     _dos_settime( &newtime );
  11469. %@AS@%     printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );
  11470. %@AS@%  
  11471. %@AS@%     /* Restore old date and time */
  11472. %@AS@%     _dos_setdate( &olddate );
  11473. %@AS@%     _dos_settime( &oldtime );
  11474. %@AS@%  }%@AE@%%@NL@%
  11475. %@NL@%
  11476. %@NL@%
  11477. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11478. %@NL@%
  11479. %@AS@%  
  11480. %@AS@%  
  11481. %@AS@%  06/15/89    18:26:09
  11482. %@AS@%  07/04/84    03:45:30 %@AE@%%@NL@%
  11483. %@NL@%
  11484. %@NL@%
  11485. %@NL@%
  11486. %@NL@%
  11487. %@QR:_dos_setdrive@%%@NL@%
  11488. %@2@%%@CR:C6A00740397 @%%@AB@%_dos_setdrive%@AE@%%@EH@%%@NL@%
  11489. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11490. %@NL@%
  11491. %@NL@%
  11492. %@3@%%@AB@%Description%@CR:C6A00740398 @% %@CR:C6A00740399 @%%@AE@%%@EH@%%@NL@%
  11493. %@NL@%
  11494. Sets the default drive, using system call INT 0x0E.  %@NL@%
  11495. %@NL@%
  11496. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11497. %@NL@%
  11498. %@AS@%  void _dos_setdrive( unsigned drive, unsigned *numdrives );%@AE@%%@NL@%
  11499. %@NL@%
  11500. %@AI@%drive%@AE@%                             New default drive
  11501.  
  11502. %@AI@%numdrives%@AE@%                         Total drives available
  11503.  
  11504. %@NL@%
  11505. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11506. %@NL@%
  11507. The %@AB@%_dos_setdrive%@AE@% routine uses system call INT 0x0E to set the current
  11508. default drive to the %@AI@%drive%@AE@% argument: 1 = drive A, 2 = drive B, and so on.
  11509. The %@AI@%numdrives%@AE@% argument indicates the total number of drives in the system.
  11510. If this value is 4, for example, it does not mean the drives are designated
  11511. A, B, C, and D; it means only that four drives are in the system.  %@NL@%
  11512. %@NL@%
  11513. %@NL@%
  11514. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11515. %@NL@%
  11516. There is no return value. If an invalid drive number is passed, the function
  11517. fails without indication. Use the %@AB@%_dos_getdrive%@AE@% routine to verify whether
  11518. the desired drive has been set.  %@NL@%
  11519. %@NL@%
  11520. %@NL@%
  11521. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11522. %@NL@%
  11523.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11524. %@NL@%
  11525. %@NL@%
  11526. %@NL@%
  11527. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11528. %@NL@%
  11529. %@AB@%_dos_getdiskfree%@AE@%, %@AB@% _dos_getdrive%@AE@%  %@NL@%
  11530. %@NL@%
  11531. %@NL@%
  11532. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11533. %@NL@%
  11534. %@AS@%  /* DGDRIVE.C: This program prints the letter of the current drive,
  11535. %@AS@%   * changes the default drive to A, then returns the number of disk drives.
  11536. %@AS@%   */
  11537. %@AS@%  
  11538. %@AS@%  #include <stdio.h>
  11539. %@AS@%  #include <dos.h>
  11540. %@AS@%  
  11541. %@AS@%  void main()
  11542. %@AS@%  {
  11543. %@AS@%     unsigned olddrive, newdrive;
  11544. %@AS@%     unsigned number_of_drives;
  11545. %@AS@%  
  11546. %@AS@%     /* Print current default drive information */
  11547. %@AS@%     _dos_getdrive( &olddrive );
  11548. %@AS@%     printf( "The current drive is: %c\n", 'A' + olddrive1 );
  11549. %@AS@%  
  11550. %@AS@%     /* Set default drive to be drive A */
  11551. %@AS@%     printf( "Changing default drive to A\n");
  11552. %@AS@%     _dos_setdrive( 1, &number_of_drives );
  11553. %@AS@%  
  11554. %@AS@%     /* Get new default drive information and total number of drives */
  11555. %@AS@%     _dos_getdrive( &newdrive );
  11556. %@AS@%     printf( "The current drive is: %c\n", 'A' + newdrive1 );
  11557. %@AS@%     printf( "Number of logical drives: %d\n", number_of_drives );
  11558. %@AS@%  
  11559. %@AS@%     /* Restore default drive */
  11560. %@AS@%     _dos_setdrive( olddrive, &number_of_drives );
  11561. %@AS@%  }%@AE@%%@NL@%
  11562. %@NL@%
  11563. %@NL@%
  11564. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11565. %@NL@%
  11566. %@AS@%  
  11567. %@AS@%  
  11568. %@AS@%  The current drive is: C
  11569. %@AS@%  Changing default drive to A
  11570. %@AS@%  The current drive is: A
  11571. %@AS@%  Number of logical drives: 26 %@AE@%%@NL@%
  11572. %@NL@%
  11573. %@NL@%
  11574. %@NL@%
  11575. %@NL@%
  11576. %@QR:_dos_setfileattr@%%@NL@%
  11577. %@2@%%@CR:C6A00750400 @%%@AB@%_dos_setfileattr%@AE@%%@EH@%%@NL@%
  11578. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11579. %@NL@%
  11580. %@NL@%
  11581. %@3@%%@AB@%Description%@CR:C6A00750401 @% %@CR:C6A00750402 @%%@AE@%%@EH@%%@NL@%
  11582. %@NL@%
  11583. Sets the attributes of the file or directory, using system call INT 0x43.  %@NL@%
  11584. %@NL@%
  11585. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11586. %@NL@%
  11587. %@AS@%  unsigned _dos_setfileattr( char *pathname, unsigned attrib );%@AE@%%@NL@%
  11588. %@NL@%
  11589. %@AI@%pathname%@AE@%                          Full path of target file/directory
  11590.  
  11591. %@AI@%attrib%@AE@%                            New attributes
  11592.  
  11593. %@NL@%
  11594. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11595. %@NL@%
  11596. The %@AB@%_dos_setfileattr%@AE@% routine uses system call INT 0x43 to set the attributes
  11597. of the file or directory pointed to by %@AI@%pathname%@AE@%. The actual attributes are
  11598. contained in the low-order byte of the %@AI@%attrib%@AE@% word. Attributes are
  11599. represented by manifest constants, as described below:  %@NL@%
  11600. %@NL@%
  11601. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  11602. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11603. %@AB@%_A_ARCH%@AE@%                           Archive. Set whenever the file is 
  11604.                                   changed, or cleared by the DOS BACKUP 
  11605.                                   command.
  11606.  
  11607. %@AB@%_A_HIDDEN%@AE@%                         Hidden file. Cannot be found by a 
  11608.                                   directory search.
  11609.  
  11610. %@AB@%_A_NORMAL%@AE@%                         Normal. File can be read or written to 
  11611.                                   without restriction.
  11612.  
  11613. %@AB@%_A_RDONLY%@AE@%                         Read-only. File cannot be opened for 
  11614.                                   writing, and a file with the same name 
  11615.                                   cannot be created.
  11616.  
  11617. %@AB@%_A_SUBDIR%@AE@%                         Subdirectory.
  11618.  
  11619. %@AB@%_A_SYSTEM%@AE@%                         System file. Cannot be found by a 
  11620.                                   directory search.
  11621.  
  11622. %@AB@%_A_VOLID%@AE@%                          Volume ID. Only one file can have this 
  11623.                                   attribute, and it must be in the root 
  11624.                                   directory.
  11625.  
  11626. %@NL@%
  11627. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11628. %@NL@%
  11629. The function returns 0 if successful. Otherwise, it returns the DOS error
  11630. code and sets %@AB@%errno%@AE@% to one of the following:  %@NL@%
  11631. %@NL@%
  11632. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  11633. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11634. %@AB@%EACCES%@AE@%                            Access denied; cannot change the volume 
  11635.                                   ID or the
  11636.                                   subdirectory.
  11637.  
  11638. %@AB@%ENOENT%@AE@%                            No file or directory matching the target
  11639.                                   was found.
  11640.  
  11641. %@NL@%
  11642. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11643. %@NL@%
  11644.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11645. %@NL@%
  11646. %@NL@%
  11647. %@NL@%
  11648. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11649. %@NL@%
  11650. %@AB@%_dos_getfileattr%@AE@%  %@NL@%
  11651. %@NL@%
  11652. %@NL@%
  11653. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11654. %@NL@%
  11655. %@AS@%  /* DGFILEAT.C: This program creates a file with the specified attributes,
  11656. %@AS@%   * then prints this information before changing the file attributes back 
  11657. %@AS@%   * to normal.
  11658. %@AS@%   */
  11659. %@AS@%  
  11660. %@AS@%  #include <stdio.h>
  11661. %@AS@%  #include <dos.h>
  11662. %@AS@%  
  11663. %@AS@%  void main()
  11664. %@AS@%  {
  11665. %@AS@%     unsigned oldattrib, newattrib;
  11666. %@AS@%     int fh;
  11667. %@AS@%  
  11668. %@AS@%     /* Get and display file attribute */
  11669. %@AS@%     _dos_getfileattr( "DGFILEAT.C", &oldattrib );
  11670. %@AS@%     printf( "Attribute: 0x%.4x\n", oldattrib );
  11671. %@AS@%     if( ( oldattrib & _A_RDONLY ) != 0 )
  11672. %@AS@%        printf( "Read only file\n" );
  11673. %@AS@%     else
  11674. %@AS@%        printf( "Not a read only file.\n" );
  11675. %@AS@%  
  11676. %@AS@%     /* Reset file attribute to normal file */
  11677. %@AS@%     _dos_setfileattr( "DGFILEAT.C", _A_RDONLY );
  11678. %@AS@%     _dos_getfileattr( "DGFILEAT.C", &newattrib );
  11679. %@AS@%     printf( "Attribute: 0x%.4x\n", newattrib );
  11680. %@AS@%  
  11681. %@AS@%     /* Restore file attribute */
  11682. %@AS@%     _dos_setfileattr( "DGFILEAT.C", oldattrib );
  11683. %@AS@%     _dos_getfileattr( "DGFILEAT.C", &newattrib );
  11684. %@AS@%     printf( "Attribute: 0x%.4x\n", newattrib );
  11685. %@AS@%  }%@AE@%%@NL@%
  11686. %@NL@%
  11687. %@NL@%
  11688. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11689. %@NL@%
  11690. %@AS@%  
  11691. %@AS@%  
  11692. %@AS@%  Attribute: 0x0020
  11693. %@AS@%  Not a read only file.
  11694. %@AS@%  Attribute: 0x0001
  11695. %@AS@%  Attribute: 0x0020 %@AE@%%@NL@%
  11696. %@NL@%
  11697. %@NL@%
  11698. %@NL@%
  11699. %@NL@%
  11700. %@QR:_dos_setftime@%%@NL@%
  11701. %@2@%%@CR:C6A00760403 @%%@AB@%_dos_setftime%@AE@%%@EH@%%@NL@%
  11702. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11703. %@NL@%
  11704. %@NL@%
  11705. %@3@%%@AB@%Description%@CR:C6A00760404 @% %@CR:C6A00760405 @%%@AE@%%@EH@%%@NL@%
  11706. %@NL@%
  11707. Sets the date and time for a file, using system call INT 0x57.  %@NL@%
  11708. %@NL@%
  11709. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11710. %@NL@%
  11711. %@AS@%  unsigned _dos_setftime( int handle, unsigned date, unsigned time );%@AE@%%@NL@%
  11712. %@NL@%
  11713. %@AI@%handle%@AE@%                            Target file
  11714.  
  11715. %@AI@%date%@AE@%                              Date of last write
  11716.  
  11717. %@AI@%time%@AE@%                              Time of last write
  11718.  
  11719. %@NL@%
  11720. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11721. %@NL@%
  11722. The %@AB@%_dos_setftime%@AE@% routine uses system call INT 0x57 to set the %@AI@%date%@AE@% and %@AI@%time%@AE@%
  11723. at which the file identified by %@AI@%handle%@AE@% was last written to. These values
  11724. appear in the DOS date and time format, described in the following lists:  %@NL@%
  11725. %@NL@%
  11726. %@AB@%Time Bits%@AE@%                         %@AB@%Meaning%@AE@%
  11727. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11728. 0 - 4                             Number of two-second increments (0 -29)
  11729.  
  11730. 5 - 10                            Minutes (0 -59)
  11731.  
  11732. 11-15                             Hours (0 -23)
  11733.  
  11734. %@AB@%Date Bits%@AE@%                         %@AB@%Meaning%@AE@%
  11735. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11736. 0 - 4                             Day (1-31)
  11737.  
  11738. 5 -8                              Month (1-12)
  11739.  
  11740. 9 -15                             Year since 1980 (for example, 1989 is 
  11741.                                   stored as 9)
  11742.  
  11743. %@NL@%
  11744. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11745. %@NL@%
  11746. If successful, the function returns 0. Otherwise, it returns the DOS error
  11747. code and sets %@AB@%errno%@AE@% to %@AB@%EBADF%@AE@%, indicating that an invalid file handle was
  11748. passed.  %@NL@%
  11749. %@NL@%
  11750. %@NL@%
  11751. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11752. %@NL@%
  11753.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11754. %@NL@%
  11755. %@NL@%
  11756. %@NL@%
  11757. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11758. %@NL@%
  11759. %@AB@%_dos_getftime%@AE@%, %@AB@%fstat%@AE@%, %@AB@%stat%@AE@%  %@NL@%
  11760. %@NL@%
  11761. %@NL@%
  11762. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11763. %@NL@%
  11764. %@AS@%  /* DGFTIME.C: This program displays and modifies the date and time
  11765. %@AS@%   * fields of a file.
  11766. %@AS@%   */
  11767. %@AS@%  
  11768. %@AS@%  #include <fcntl.h>
  11769. %@AS@%  #include <stdio.h>
  11770. %@AS@%  #include <stdlib.h>
  11771. %@AS@%  #include <dos.h>
  11772. %@AS@%  
  11773. %@AS@%  void main()
  11774. %@AS@%  {
  11775. %@AS@%                                   /* FEDC BA98 7654 3210          */
  11776. %@AS@%     unsigned new_date = 0x184f;   /* 0001 1000 0100 1111  2/15/92 */
  11777. %@AS@%     unsigned new_time = 0x48e0;   /* 0100 1000 1110 0000  9:07 AM */
  11778. %@AS@%     unsigned old_date, old_time;
  11779. %@AS@%  
  11780. %@AS@%     int fh;
  11781. %@AS@%  
  11782. %@AS@%     /* Open file with _dos_open function */
  11783. %@AS@%     if( _dos_open( "dgftime.obj", O_RDONLY, &fh ) != 0 )
  11784. %@AS@%        exit( 1 );
  11785. %@AS@%  
  11786. %@AS@%     /* Get file date and time */
  11787. %@AS@%     _dos_getftime( fh, &old_date, &old_time );
  11788. %@AS@%     printf( "Old date field: 0x%.4x\n", old_date );
  11789. %@AS@%     printf( "Old time field: 0x%.4x\n", old_time );
  11790. %@AS@%     system( "dir dgftime.obj" );
  11791. %@AS@%  
  11792. %@AS@%     /* Modify file date and time */
  11793. %@AS@%     if( !_dos_setftime( fh, new_date, new_time ) )
  11794. %@AS@%     {
  11795. %@AS@%        _dos_getftime( fh, &new_date, &new_time );
  11796. %@AS@%        printf( "New date field: 0x%.4x\n", new_date );
  11797. %@AS@%        printf( "New time field: 0x%.4x\n", new_time );
  11798. %@AS@%        system( "dir dgftime.obj" );
  11799. %@AS@%  
  11800. %@AS@%        /* Restore date and time */
  11801. %@AS@%        _dos_setftime( fh, old_date, old_time );
  11802. %@AS@%     }
  11803. %@AS@%     _dos_close( fh );
  11804. %@AS@%  }%@AE@%%@NL@%
  11805. %@NL@%
  11806. %@NL@%
  11807. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11808. %@NL@%
  11809. %@AS@%  
  11810. %@AS@%  
  11811. %@AS@%  Old date field: 0x12cf
  11812. %@AS@%  Old time field: 0x94bb
  11813. %@AS@%  
  11814. %@AS@%   Volume in drive C is OS2
  11815. %@AS@%   Directory of  C:\LIBREF
  11816. %@AS@%  
  11817. %@AS@%  DGFTIME  OBJ     3923   6-15-89   6:37p
  11818. %@AS@%          1 File(s)  13676544 bytes free
  11819. %@AS@%  
  11820. %@AS@%  New date field: 0x184f
  11821. %@AS@%  New time field: 0x48e0
  11822. %@AS@%  
  11823. %@AS@%   Volume in drive C is OS2
  11824. %@AS@%   Directory of  C:\LIBREF
  11825. %@AS@%  
  11826. %@AS@%  DGFTIME  OBJ     3923   2-15-92   9:07a
  11827. %@AS@%          1 File(s)  13676544 bytes free %@AE@%%@NL@%
  11828. %@NL@%
  11829. %@NL@%
  11830. %@NL@%
  11831. %@NL@%
  11832. %@QR:_dos_settime@%%@NL@%
  11833. %@2@%%@CR:C6A00770406 @%%@AB@%_dos_settime%@AE@%%@EH@%%@NL@%
  11834. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11835. %@NL@%
  11836. %@NL@%
  11837. %@3@%%@AB@%Description%@CR:C6A00770407 @% %@CR:C6A00770408 @%%@AE@%%@EH@%%@NL@%
  11838. %@NL@%
  11839. Sets the current system time, using system call INT 0x2D.  %@NL@%
  11840. %@NL@%
  11841. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11842. %@NL@%
  11843. %@AS@%  unsigned _dos_settime( struct dostime_t *time );%@AE@%%@NL@%
  11844. %@NL@%
  11845. %@AI@%time%@AE@%                              New system time
  11846.  
  11847. %@NL@%
  11848. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11849. %@NL@%
  11850. The %@AB@%_dos_settime%@AE@% routine uses system call INT 0x2D to set the current system
  11851. time to the value stored in the %@AB@%dostime_t%@AE@% structure that %@AI@%time%@AE@% points to, as
  11852. defined in DOS.H. The %@AB@%dostime_t%@AE@% structure contains the following elements:  %@NL@%
  11853. %@NL@%
  11854. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  11855. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11856. %@AB@%unsigned char hour%@AE@%                0 -23
  11857.  
  11858. %@AB@%unsigned char minute%@AE@%              0 -59
  11859.  
  11860. %@AB@%unsigned char second%@AE@%              0 -59
  11861.  
  11862. %@AB@%unsigned char hsecond%@AE@%             Hundredths of a second; 0 -99
  11863.  
  11864. %@NL@%
  11865. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  11866. %@NL@%
  11867. If successful, the function returns 0. Otherwise, it returns a nonzero value
  11868. and sets %@AB@%errno%@AE@% to %@AB@%EINVAL%@AE@%, indicating an invalid time was specified.  %@NL@%
  11869. %@NL@%
  11870. %@NL@%
  11871. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  11872. %@NL@%
  11873.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  11874. %@NL@%
  11875. %@NL@%
  11876. %@NL@%
  11877. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  11878. %@NL@%
  11879. %@AB@%_dos_getdate%@AE@%, %@AB@% _dos_gettime%@AE@%, %@AB@% _dos_setdate%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%mktime%@AE@%,
  11880. %@AB@%_strdate%@AE@%, %@AB@% _strtime%@AE@%  %@NL@%
  11881. %@NL@%
  11882. %@NL@%
  11883. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  11884. %@NL@%
  11885. %@AS@%  /* DSTIME.C: This program changes the time and date values and displays
  11886. %@AS@%  the
  11887. %@AS@%   * new date and time values.
  11888. %@AS@%   */
  11889. %@AS@%  
  11890. %@AS@%  #include <dos.h>
  11891. %@AS@%  #include <conio.h>
  11892. %@AS@%  #include <stdio.h>
  11893. %@AS@%  #include <time.h>%@AE@%%@NL@%
  11894. %@NL@%
  11895. %@AS@%  void main()
  11896. %@AS@%  {
  11897. %@AS@%     struct dosdate_t olddate, newdate = { { 4 }, { 7 }, { 1984 } };
  11898. %@AS@%     struct dostime_t oldtime, newtime = { { 3 }, { 45 }, { 30 }, { 0 } };
  11899. %@AS@%     char   datebuf[40], timebuf[40];
  11900. %@AS@%  
  11901. %@AS@%     /* Get current date and time values */
  11902. %@AS@%     _dos_getdate( &olddate );
  11903. %@AS@%     _dos_gettime( &oldtime );
  11904. %@AS@%     printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );
  11905. %@AS@%  
  11906. %@AS@%     /* Modify date and time structures */
  11907. %@AS@%     _dos_setdate( &newdate );
  11908. %@AS@%     _dos_settime( &newtime );
  11909. %@AS@%     printf( "%s    %s\n" , _strdate( datebuf ), _strtime( timebuf ) );
  11910. %@AS@%  
  11911. %@AS@%     /* Restore old date and time */
  11912. %@AS@%     _dos_setdate( &olddate );
  11913. %@AS@%     _dos_settime( &oldtime );
  11914. %@AS@%  }%@AE@%%@NL@%
  11915. %@NL@%
  11916. %@NL@%
  11917. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  11918. %@NL@%
  11919. %@AS@%  
  11920. %@AS@%  
  11921. %@AS@%  06/15/89    18:26:09
  11922. %@AS@%  07/04/84    03:45:30 %@AE@%%@NL@%
  11923. %@NL@%
  11924. %@NL@%
  11925. %@NL@%
  11926. %@NL@%
  11927. %@QR:_dos_setvect@%%@NL@%
  11928. %@2@%%@CR:C6A00780409 @%%@AB@%_dos_setvect%@AE@%%@EH@%%@NL@%
  11929. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  11930. %@NL@%
  11931. %@NL@%
  11932. %@3@%%@AB@%Description%@CR:C6A00780410 @% %@CR:C6A00780411 @%%@AE@%%@EH@%%@NL@%
  11933. %@NL@%
  11934. Sets the current value of the interrupt vector, using system call INT 0x25.
  11935. %@NL@%
  11936. %@NL@%
  11937. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  11938. %@NL@%
  11939. %@AS@%  void _dos_setvect( unsigned intnum, void( _interrupt _far *handler)( ));%@AE@%%@NL@%
  11940. %@NL@%
  11941. %@AI@%intnum%@AE@%                            Target-interrupt vector
  11942.  
  11943. %@AI@%handler%@AE@%                           Interrupt handler for which to assign %@AI@%%@AE@%
  11944.                                   %@AI@%intnum%@AE@%
  11945.  
  11946. %@NL@%
  11947. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  11948. %@NL@%
  11949. The %@AB@%_dos_setvect%@AE@% routine uses system call INT 0x25 to set the current value
  11950. of the interrupt vector %@AI@%intnum%@AE@% to the function pointed to by %@AI@%handler%@AE@%.
  11951. Subsequently, whenever the %@AI@%intnum%@AE@% interrupt is generated, the %@AI@%handler%@AE@%
  11952. routine will be called. If %@AI@%handler%@AE@% is a C function, it must have been
  11953. previously declared with the %@AB@%interrupt%@AE@% attribute. Otherwise, you must make
  11954. sure that the function satisfies the requirements for an interrupt-handling
  11955. routine. For example, if %@AI@%handler%@AE@% is an assembler function, it must be a %@AB@%far%@AE@%
  11956. routine that returns with an %@AB@%IRET %@AE@%instead of a%@AB@% RET%@AE@%.  %@NL@%
  11957. %@NL@%
  11958. The %@AB@%interrupt%@AE@% attribute indicates that the function is an interrupt handler.
  11959. The compiler generates appropriate entry and exit sequences for the
  11960. interrupt-handling function, including saving and restoring all registers
  11961. and executing an %@AB@%IRET%@AE@% instruction to return.  %@NL@%
  11962. %@NL@%
  11963. The %@AB@%_dos_setvect%@AE@% routine is generally used with the %@AB@%_dos_getvect%@AE@% function.
  11964. To replace an interrupt vector, first save the current vector of the
  11965. interrupt using %@AB@%_dos_getvect%@AE@%. Then set the vector to your own interrupt
  11966. routine with %@AB@%_dos_setvect%@AE@%. The saved vector can later be restored, if
  11967. necessary, using %@AB@%_dos_setvect%@AE@%. The user-defined routine may also need the
  11968. original vector in order to call it or to chain to it with %@AB@%_chain_intr%@AE@%.  %@NL@%
  11969. %@NL@%
  11970. %@NL@%
  11971. %@4@%%@AB@%Registers and Interrupt Functions%@AE@%%@EH@%%@NL@%
  11972. %@NL@%
  11973. When you call an interrupt function, the DS register is initialized to the C
  11974. data segment. This allows you to access global variables from within an
  11975. interrupt function.  %@NL@%
  11976. %@NL@%
  11977. In addition, all registers except SS are saved on the stack. You can access
  11978. these registers within the function if you declare a function parameter list
  11979. containing a formal parameter for each saved register. The following example
  11980. illustrates such a declaration:  %@NL@%
  11981. %@NL@%
  11982. %@AS@%  void _interrupt _far int_handler( unsigned _es, unsigned _ds,
  11983. %@AS@%                                    unsigned _di, unsigned _si, 
  11984. %@AS@%                                    unsigned _bp, unsigned _sp,
  11985. %@AS@%                                    unsigned _bx, unsigned _dx, 
  11986. %@AS@%                                   unsigned _cx, unsigned _ax,
  11987. %@AS@%                                    unsigned _ip, unsigned _cs, 
  11988. %@AS@%                                   unsigned _flags )
  11989. %@AS@%  {
  11990. %@AS@%  .
  11991. %@AS@%  .
  11992. %@AS@%  .
  11993. %@AS@%  }%@AE@%%@NL@%
  11994. %@NL@%
  11995. The formal parameters must appear in the opposite order from which they are
  11996. pushed onto the stack. You can omit parameters from the end of the list in a
  11997. declaration, but not from the beginning. For example, if your handler needs
  11998. to use only DI and SI, you must still provide ES and DS, but not necessarily
  11999. BX or DX.  %@NL@%
  12000. %@NL@%
  12001. You can pass additional arguments if your interrupt handler will be called
  12002. directly from C rather than by an INT instruction. To do this, you must
  12003. declare all register parameters and then declare your parameter at the end
  12004. of the list.  %@NL@%
  12005. %@NL@%
  12006. The compiler always saves and restores registers in the same, fixed order.
  12007. Thus, no matter what names you use in the formal parameter list, the first
  12008. parameter in the list refers to ES, the second refers to DS, and so on. If
  12009. your interrupt routines will use in-line assembler, you should distinguish
  12010. the parameter names so that they will not be the same as the real register
  12011. names.  %@NL@%
  12012. %@NL@%
  12013. If you change any of the register parameters of an interrupt function while
  12014. the function is executing, the corresponding register contains the changed
  12015. value when the function returns. For example:  %@NL@%
  12016. %@NL@%
  12017. %@AS@%  void _interrupt _far int_handler( unsigned _es, unsigned _ds,
  12018. %@AS@%                                   unsigned _di, unsigned _si )
  12019. %@AS@%  {
  12020. %@AS@%      _di = -1;
  12021. %@AS@%  }%@AE@%%@NL@%
  12022. %@NL@%
  12023. This code causes the DI register to contain -1 when the %@AI@%handler%@AE@% function
  12024. returns. It is not a good idea to modify the values of the parameters
  12025. representing the IP and CS registers in interrupt functions. If you must
  12026. modify a particular flag (such as the carry flag for certain DOS and BIOS
  12027. interrupt routines), use the OR operator ( | ) so that other bits in the
  12028. flag register are not changed.  %@NL@%
  12029. %@NL@%
  12030. When an interrupt function is called by an INT instruction, the
  12031. interrupt-enable flag is cleared. If your interrupt function needs to do
  12032. significant processing, you should use the %@AB@%_enable%@AE@% function to set the
  12033. interrupt flag so that interrupts can be handled.  %@NL@%
  12034. %@NL@%
  12035. %@NL@%
  12036. %@4@%%@AB@%Precautions for Interrupt Functions%@AE@%%@EH@%%@NL@%
  12037. %@NL@%
  12038. Since DOS is not reentrant (a DOS interrupt cannot be called from inside a
  12039. DOS interrupt), it is usually not safe to call from inside an interrupt
  12040. function any standard library function that calls DOS INT 21H. Similar
  12041. precautions apply to many BIOS functions. Functions that rely on INT 21H
  12042. calls include I/O functions and the %@AB@%_dos%@AE@% family of functions. Functions that
  12043. rely on the machine's BIOS include graphics functions and the %@AB@%_bios%@AE@% family
  12044. of functions. It is usually safe to use functions that do not rely on INT
  12045. 21H or BIOS, such as string-handling functions. Before using a standard
  12046. library function in an interrupt function, be sure that you are familiar
  12047. with the action of the library function.  %@NL@%
  12048. %@NL@%
  12049. %@NL@%
  12050. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12051. %@NL@%
  12052. None.  %@NL@%
  12053. %@NL@%
  12054. %@NL@%
  12055. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12056. %@NL@%
  12057.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  12058. %@NL@%
  12059. %@NL@%
  12060. %@NL@%
  12061. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12062. %@NL@%
  12063. %@AB@%_chain_intr%@AE@%, %@AB@% _dos_getvect%@AE@%, %@AB@% _dos_keep%@AE@%  %@NL@%
  12064. %@NL@%
  12065. %@NL@%
  12066. %@NL@%
  12067. %@NL@%
  12068. %@QR:_dos_write@%%@NL@%
  12069. %@2@%%@CR:C6A00790412 @%%@AB@%_dos_write%@AE@%%@EH@%%@NL@%
  12070. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12071. %@NL@%
  12072. %@NL@%
  12073. %@3@%%@AB@%Description%@CR:C6A00790413 @% %@CR:C6A00790414 @%%@AE@%%@EH@%%@NL@%
  12074. %@NL@%
  12075. Writes a buffer to a file, using system call INT 0x40.  %@NL@%
  12076. %@NL@%
  12077. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  12078. %@NL@%
  12079. %@AS@%  unsigned _dos_write( int handle, void _far *buffer, unsigned count, 
  12080. %@AS@%  unsigned *numwrt );%@AE@%%@NL@%
  12081. %@NL@%
  12082. %@AI@%handle%@AE@%                            File to write to
  12083.  
  12084. %@AI@%buffer%@AE@%                            Buffer to write from
  12085.  
  12086. %@AI@%count%@AE@%                             Number of bytes to write
  12087.  
  12088. %@AI@%numwrt%@AE@%                            Number of bytes actually written
  12089.  
  12090. %@NL@%
  12091. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12092. %@NL@%
  12093. The %@AB@%_dos_write%@AE@% routine uses system call INT 0x40 to write data to the file
  12094. that %@AI@%handle%@AE@% references; %@AI@%count%@AE@% bytes of data from the buffer to which %@AI@%buffer%@AE@%
  12095. points are written to the file. The integer pointed to by %@AI@%numwrt %@AE@%will be the
  12096. number of bytes actually written, which may be less than the number
  12097. requested.%@AI@%  %@AE@%%@NL@%
  12098. %@NL@%
  12099. Do not use the DOS interface routines with the console, low-level, or stream
  12100. I/O routines.  %@NL@%
  12101. %@NL@%
  12102. %@NL@%
  12103. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12104. %@NL@%
  12105. If successful, the function returns 0. Otherwise, it returns the DOS error
  12106. code and sets %@AB@%errno%@AE@% to one of the following manifest constants:  %@NL@%
  12107. %@NL@%
  12108. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  12109. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12110. %@AB@%EACCES%@AE@%                            Access denied (%@AI@%handle%@AE@% references a file 
  12111.                                   not open for write
  12112.                                   access)
  12113.  
  12114. %@AB@%EBADF%@AE@%                             Invalid file handle
  12115.  
  12116. %@NL@%
  12117. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12118. %@NL@%
  12119.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  12120. %@NL@%
  12121. %@NL@%
  12122. %@NL@%
  12123. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12124. %@NL@%
  12125. %@AB@%_dos_close%@AE@%, %@AB@% _dos_open%@AE@%, %@AB@% _dos_read%@AE@%, %@AB@%write%@AE@%  %@NL@%
  12126. %@NL@%
  12127. %@NL@%
  12128. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12129. %@NL@%
  12130. %@AS@%  /* DWRITE.C: This program uses DOS I/O functions to write to a file. */
  12131. %@AS@%  
  12132. %@AS@%  #include <fcntl.h>
  12133. %@AS@%  #include <stdio.h>
  12134. %@AS@%  #include <stdlib.h>
  12135. %@AS@%  #include <dos.h>
  12136. %@AS@%  
  12137. %@AS@%  void main()
  12138. %@AS@%  {
  12139. %@AS@%     char out_buffer[] = "Hello";
  12140. %@AS@%     int  fh;
  12141. %@AS@%     unsigned n_written;
  12142. %@AS@%  
  12143. %@AS@%     /* Open file with _dos_creat function */
  12144. %@AS@%     if( _dos_creat( "data", _A_NORMAL, &fh ) == 0 )
  12145. %@AS@%     {
  12146. %@AS@%        /* Write data with _dos_write function */
  12147. %@AS@%        _dos_write( fh, out_buffer, 5, &n_written );
  12148. %@AS@%        printf( "Number of characters written: %d\n", n_written );
  12149. %@AS@%  
  12150. %@AS@%        _dos_close( fh );
  12151. %@AS@%        printf( "Contents of file are:\n" );
  12152. %@AS@%        system( "type data" );
  12153. %@AS@%     }
  12154. %@AS@%  }%@AE@%%@NL@%
  12155. %@NL@%
  12156. %@NL@%
  12157. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  12158. %@NL@%
  12159. %@AS@%  
  12160. %@AS@%  
  12161. %@AS@%  Number of characters written: 5
  12162. %@AS@%  Contents of file are:
  12163. %@AS@%  Hello %@AE@%%@NL@%
  12164. %@NL@%
  12165. %@NL@%
  12166. %@NL@%
  12167. %@NL@%
  12168. %@QR:dosexterr@%%@NL@%
  12169. %@2@%%@CR:C6A00800415 @%%@AB@%dosexterr%@AE@%%@EH@%%@NL@%
  12170. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12171. %@NL@%
  12172. %@NL@%
  12173. %@3@%%@AB@%Description%@CR:C6A00800416 @%%@CR:C6A00800417 @% %@CR:C6A00800418 @%%@AE@%%@EH@%%@NL@%
  12174. %@NL@%
  12175. Gets register values returned by INT 0x59.  %@NL@%
  12176. %@NL@%
  12177. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  12178. %@NL@%
  12179. %@AS@%  int dosexterr( struct DOSERROR *errorinfo );%@AE@%%@NL@%
  12180. %@NL@%
  12181. %@AI@%errorinfo%@AE@%                         Extended DOS error information
  12182.  
  12183. %@NL@%
  12184. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12185. %@NL@%
  12186. The %@AB@%dosexterr%@AE@% function obtains the extended error information returned by
  12187. the DOS system call INT 0x59 and stores the values in the structure pointed
  12188. to by %@AI@%errorinfo%@AE@%. This function is useful when making system calls under DOS
  12189. versions 3.0 or later, which offer extended error handling. %@CR:C6A00800419 @%%@CR:C6A00800420 @%  %@NL@%
  12190. %@NL@%
  12191. The structure type %@AB@%DOSERROR %@AE@%is defined in DOS.H. The %@AB@%DOSERROR%@AE@% structure
  12192. contains the following elements:%@CR:C6A00800421 @%%@CR:C6A00800422 @%  %@NL@%
  12193. %@NL@%
  12194. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  12195. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12196. %@AB@%int exterror%@AE@%                      AX register contents
  12197.  
  12198. %@AB@%char class%@AE@%                        BH register contents
  12199.  
  12200. %@AB@%char action%@AE@%                       BL register contents
  12201.  
  12202. %@AB@%char locus%@AE@%                        CH register contents
  12203.  
  12204. Giving a %@AB@%NULL%@AE@% pointer argument causes %@AB@%dosexterr%@AE@% to return the value in AX
  12205. without filling in the structure fields. See %@AI@%MS-DOS Encyclopedia %@AE@% (Duncan,
  12206. ed.; Redmond, WA: Microsoft Press, 1988) or %@AI@%Programmer's PC Sourcebook%@AE@%
  12207. (Hogan; Redmond, WA: Microsoft Press, 1988) for more information on the
  12208. register contents.  %@NL@%
  12209. %@NL@%
  12210. %@NL@%
  12211. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12212. %@NL@%
  12213. The %@AB@%dosexterr%@AE@% function returns the value in the AX register (identical to
  12214. the value in the %@AB@%exterror%@AE@% structure field).  %@NL@%
  12215. %@NL@%
  12216. %@NL@%
  12217. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12218. %@NL@%
  12219.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  12220. %@NL@%
  12221. %@NL@%
  12222. The %@AB@%dosexterr%@AE@% function should be used only under DOS versions 3.0 or later.
  12223. %@NL@%
  12224. %@NL@%
  12225. %@NL@%
  12226. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12227. %@NL@%
  12228. %@AB@%perror%@AE@%  %@NL@%
  12229. %@NL@%
  12230. %@NL@%
  12231. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12232. %@NL@%
  12233. %@AS@%  /* DOSEXERR.C: This program tries to open the file test.dat. If the
  12234. %@AS@%   * attempted open operation fails, the program uses dosexterr to display
  12235. %@AS@%   * extended error information.
  12236. %@AS@%   */
  12237. %@AS@%  
  12238. %@AS@%  #include <dos.h>
  12239. %@AS@%  #include <io.h>
  12240. %@AS@%  #include <fcntl.h>
  12241. %@AS@%  #include <stdio.h>
  12242. %@AS@%  
  12243. %@AS@%  void main()
  12244. %@AS@%  {
  12245. %@AS@%     struct DOSERROR doserror;
  12246. %@AS@%     int fd;
  12247. %@AS@%  
  12248. %@AS@%     /* Attempt to open a non-existent file */
  12249. %@AS@%     if( (fd = open( "NOSUCHF.ILE", O_RDONLY )) == -1 )
  12250. %@AS@%     {
  12251. %@AS@%        dosexterr( &doserror );
  12252. %@AS@%        printf( "Error: %d  Class: %d  Action: %d  Locus: %d\n",
  12253. %@AS@%                doserror.exterror, doserror.class,
  12254. %@AS@%                doserror.action,   doserror.locus );
  12255. %@AS@%     }
  12256. %@AS@%     else
  12257. %@AS@%     {
  12258. %@AS@%        printf( "Open succeeded so no extended information printed\n" );
  12259. %@AS@%        close( fd );
  12260. %@AS@%     }
  12261. %@AS@%  }%@AE@%%@NL@%
  12262. %@NL@%
  12263. %@NL@%
  12264. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  12265. %@NL@%
  12266. %@AS@%  
  12267. %@AS@%  
  12268. %@AS@%  Error: 2  Class: 8  Action: 3  Locus: 2 %@AE@%%@NL@%
  12269. %@NL@%
  12270. %@NL@%
  12271. %@NL@%
  12272. %@NL@%
  12273. %@QR:dup@%%@QR:dup2@%%@NL@%
  12274. %@2@%%@CR:C6A00810423 @%%@AB@%dup, dup2%@AE@%%@EH@%%@NL@%
  12275. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12276. %@NL@%
  12277. %@NL@%
  12278. %@3@%%@AB@%Description%@CR:C6A00810424 @%%@CR:C6A00810425 @%%@AE@%%@EH@%%@NL@%
  12279. %@NL@%
  12280. Create a second handle for an open file (%@AB@%dup%@AE@%), or reassign a file handle
  12281. (%@AB@%dup2%@AE@%).  %@NL@%
  12282. %@NL@%
  12283. %@AB@%#include <io.h%@AE@%                    Required only for function declarations
  12284.  
  12285. %@AS@%  int dup( int handle );%@AE@%%@NL@%
  12286. %@NL@%
  12287. %@AS@%  int dup2( int handle1, int handle2 );%@AE@%%@NL@%
  12288. %@NL@%
  12289. %@AI@%handle%@AE@%, %@AI@%handle1%@AE@%                   Handle referring to open file
  12290.  
  12291. %@AI@%handle2%@AE@%                           Any handle value
  12292.  
  12293. %@NL@%
  12294. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12295. %@NL@%
  12296. The %@AB@%dup%@AE@% and %@AB@%dup2%@AE@% functions cause a second file handle to be associated with
  12297. a currently open file. Operations on the file can be carried out using
  12298. either file handle. The type of access allowed for the file is unaffected by
  12299. the creation of a new handle.%@CR:C6A00810426 @%  %@NL@%
  12300. %@NL@%
  12301. The %@AB@%dup%@AE@% function returns the next available file handle for the given file.
  12302. The %@AB@%dup2%@AE@% function forces %@AI@%handle2%@AE@% to refer to the same file as %@AI@%handle1%@AE@%. If
  12303. %@AI@%handle2%@AE@% is associated with an open file at the time of the call, that file
  12304. is closed.  %@NL@%
  12305. %@NL@%
  12306. %@NL@%
  12307. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12308. %@NL@%
  12309. The %@AB@%dup%@AE@% function returns a new file handle. The %@AB@%dup2%@AE@% function returns 0 to
  12310. indicate success. Both functions return -1 if an error occurs and set %@AB@%errno%@AE@%
  12311. to one of the following values:  %@NL@%
  12312. %@NL@%
  12313. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  12314. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12315. %@AB@%EBADF%@AE@%                             Invalid file handle
  12316.  
  12317. %@AB@%EMFILE%@AE@%                            No more file handles available (too many
  12318.                                   open files)
  12319.  
  12320. %@NL@%
  12321. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12322. %@NL@%
  12323.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  12324. %@NL@%
  12325. %@NL@%
  12326. %@NL@%
  12327. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12328. %@NL@%
  12329. %@AB@%close%@AE@%, %@AB@%creat%@AE@%, %@AB@%open%@AE@%  %@NL@%
  12330. %@NL@%
  12331. %@NL@%
  12332. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12333. %@NL@%
  12334. %@AS@%  /* DUP.C: This program uses the variable old to save the original stdout.
  12335. %@AS@%   * It then opens a new file named new and forces stdout to refer
  12336. %@AS@%   * to it. Finally, it restores stdout to its original state.
  12337. %@AS@%   */
  12338. %@AS@%  
  12339. %@AS@%  #include <io.h>
  12340. %@AS@%  #include <stdlib.h>
  12341. %@AS@%  #include <stdio.h>
  12342. %@AS@%  void main()
  12343. %@AS@%  {
  12344. %@AS@%     int old;
  12345. %@AS@%     FILE *new;
  12346. %@AS@%  
  12347. %@AS@%     old = dup( 1 );   /* "old" now refers to "stdout" */
  12348. %@AS@%                       /* Note:  file handle 1 == "stdout" */
  12349. %@AS@%     if( old == -1 )
  12350. %@AS@%     {
  12351. %@AS@%        perror( "dup( 1 ) failure" );
  12352. %@AS@%        exit( 1 );
  12353. %@AS@%     }
  12354. %@AS@%     write( old, "This goes to stdout first\r\n", 27 );
  12355. %@AS@%     if( ( new = fopen( "data", "w" ) ) == NULL )
  12356. %@AS@%     {
  12357. %@AS@%        puts( "Can't open file 'data'\n" );
  12358. %@AS@%        exit( 1 );
  12359. %@AS@%     }
  12360. %@AS@%  
  12361. %@AS@%     /* stdout now refers to file "data" */
  12362. %@AS@%     if( -1 == dup2( fileno( new ), 1 ) )
  12363. %@AS@%     {
  12364. %@AS@%        perror( "Can't dup2 stdout" );
  12365. %@AS@%        exit( 1 );
  12366. %@AS@%     }
  12367. %@AS@%     puts( "This goes to file 'data'\r\n" );
  12368. %@AS@%  
  12369. %@AS@%     /* Flush stdout stream buffer so it goes to correct file */
  12370. %@AS@%     fflush( stdout );
  12371. %@AS@%     fclose( new );
  12372. %@AS@%  
  12373. %@AS@%     /* Restore original stdout */
  12374. %@AS@%     dup2( old, 1 );
  12375. %@AS@%     puts( "This goes to stdout\n" );
  12376. %@AS@%     puts( "The file 'data' contains:" );
  12377. %@AS@%     system( "type data" );
  12378. %@AS@%  }%@AE@%%@NL@%
  12379. %@NL@%
  12380. %@NL@%
  12381. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  12382. %@NL@%
  12383. %@AS@%  
  12384. %@AS@%  
  12385. %@AS@%  This goes to stdout first
  12386. %@AS@%  This goes to stdout
  12387. %@AS@%  
  12388. %@AS@%  The file 'data' contains:
  12389. %@AS@%  This goes to file 'data' %@AE@%%@NL@%
  12390. %@NL@%
  12391. %@NL@%
  12392. %@NL@%
  12393. %@NL@%
  12394. %@QR:ecvt@%%@NL@%
  12395. %@2@%%@CR:C6A00820427 @%%@AB@%ecvt%@AE@%%@EH@%%@NL@%
  12396. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12397. %@NL@%
  12398. %@NL@%
  12399. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  12400. %@NL@%
  12401. Converts a %@AB@%double%@AE@% number to a string.  %@NL@%
  12402. %@NL@%
  12403. %@CR:C6A00820428 @%%@CR:C6A00820429 @%%@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  12404.  
  12405. %@AS@%  char *ecvt( double value, int count, int *dec, int *sign );%@AE@%%@NL@%
  12406. %@NL@%
  12407. %@AI@%value%@AE@%                             Number to be converted
  12408.  
  12409. %@AI@%count%@AE@%                             Number of digits stored
  12410.  
  12411. %@AI@%dec%@AE@%                               Stored decimal-point position
  12412.  
  12413. %@AI@%sign%@AE@%                              Sign of converted number
  12414.  
  12415. %@NL@%
  12416. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12417. %@NL@%
  12418. The %@AB@%ecvt%@AE@% function converts a floating-point number to a character string.
  12419. The %@AI@%value%@AE@% argument is the floating-point number to be converted. The %@AB@%ecvt%@AE@%
  12420. function stores up to %@AI@%count%@AE@% digits of %@AI@%value%@AE@% as a string and appends a null
  12421. character (%@AB@%'\0'%@AE@%). If the number of digits in %@AI@%value%@AE@% exceeds %@AI@%count,%@AE@% the
  12422. low-order digit is rounded. If there are fewer than %@AI@%count%@AE@% digits, the string
  12423. is padded with zeros. %@CR:C6A00820430 @%%@CR:C6A00820431 @%  %@NL@%
  12424. %@NL@%
  12425. Only digits are stored in the string. The position of the decimal point and
  12426. the sign of %@AI@%value%@AE@% can be obtained from %@AI@%dec%@AE@% and %@AI@%sign%@AE@% after the call. The %@AI@%dec%@AE@%
  12427. argument points to an integer value giving the position of the decimal point
  12428. with respect to the beginning of the string. A 0 or negative integer value
  12429. indicates that the decimal point lies to the left of the first digit. The
  12430. %@AI@%sign%@AE@% argument points to an integer indicating the sign of the converted
  12431. number. If the integer value is 0, the number is positive. Otherwise, the
  12432. number is negative.  %@NL@%
  12433. %@NL@%
  12434. The %@AB@%ecvt%@AE@% and %@AB@%fcvt%@AE@% functions use a single statically allocated buffer for the
  12435. conversion. Each call to one of these routines destroys the result of the
  12436. previous call.  %@NL@%
  12437. %@NL@%
  12438. %@NL@%
  12439. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12440. %@NL@%
  12441. The %@AB@%ecvt%@AE@% function returns a pointer to the string of digits. There is no
  12442. error return.  %@NL@%
  12443. %@NL@%
  12444. %@NL@%
  12445. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12446. %@NL@%
  12447.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  12448. %@NL@%
  12449. %@NL@%
  12450. %@NL@%
  12451. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12452. %@NL@%
  12453. %@AB@%atof%@AE@%, %@AB@%atoi%@AE@%, %@AB@%atol%@AE@%, %@AB@%fcvt%@AE@%, %@AB@%gcvt%@AE@%  %@NL@%
  12454. %@NL@%
  12455. %@NL@%
  12456. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12457. %@NL@%
  12458. %@AS@%  /* ECVT.C: This program uses ecvt to convert a floating-point
  12459. %@AS@%   * number to a character string.
  12460. %@AS@%   */
  12461. %@AS@%  
  12462. %@AS@%  #include <stdlib.h>
  12463. %@AS@%  #include <stdio.h>
  12464. %@AS@%  
  12465. %@AS@%  void main()
  12466. %@AS@%  {
  12467. %@AS@%     int     decimal, sign;
  12468. %@AS@%     char    *buffer;
  12469. %@AS@%     int     precision = 10;
  12470. %@AS@%     double  source = 3.1415926535;
  12471. %@AS@%  
  12472. %@AS@%     buffer = ecvt( source, precision, &decimal, &sign );
  12473. %@AS@%     printf( "source: %2.10f   buffer: '%s'  decimal: %d   sign: %d\n",
  12474. %@AS@%             source, buffer, decimal, sign );
  12475. %@AS@%  }%@AE@%%@NL@%
  12476. %@NL@%
  12477. %@NL@%
  12478. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  12479. %@NL@%
  12480. %@AS@%  
  12481. %@AS@%  
  12482. %@AS@%  source: 3.1415926535   buffer: '3141592654'  decimal: 1   sign: 0 %@AE@%%@NL@%
  12483. %@NL@%
  12484. %@NL@%
  12485. %@NL@%
  12486. %@NL@%
  12487. %@QR:_ellipse@%%@NL@%
  12488. %@2@%%@CR:C6A00830432 @%%@AB@%_ellipse Functions%@AE@%%@EH@%%@NL@%
  12489. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12490. %@NL@%
  12491. %@NL@%
  12492. %@3@%%@AB@%Description%@CR:C6A00830433 @% %@CR:C6A00830434 @% %@CR:C6A00830435 @%%@AE@%%@EH@%%@NL@%
  12493. %@NL@%
  12494. Draw ellipses.  %@NL@%
  12495. %@NL@%
  12496. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  12497. %@NL@%
  12498. %@AS@%  short _far _ellipse( short control, short x1, short y1, short x2, short y2
  12499. %@AS@%  );%@AE@%%@NL@%
  12500. %@NL@%
  12501. %@AS@%  short _far _ellipse_w( short control, double wx1, double wy1, double wx2, 
  12502. %@AS@%  double wy2 );%@AE@%%@NL@%
  12503. %@NL@%
  12504. %@AS@%  short _far _ellipse_wxy( short control, struct _wxycoord _far *pwxy1, 
  12505. %@AS@%  struct _wxycoord _far *pwxy2 );%@AE@%%@NL@%
  12506. %@NL@%
  12507. %@AI@%control%@AE@%                           Fill flag
  12508.  
  12509. %@AI@%x1%@AE@%, %@AI@%y1%@AE@%                            Upper-left corner of bounding rectangle
  12510.  
  12511. %@AI@%x2%@AE@%, %@AI@%y2%@AE@%                            Lower-right corner of bounding rectangle
  12512.  
  12513. %@AI@%wx1%@AE@%, %@AI@%wy1%@AE@%                          Upper-left corner of bounding rectangle
  12514.  
  12515. %@AI@%wx2%@AE@%, %@AI@%wy2%@AE@%                          Lower-right corner of bounding rectangle
  12516.  
  12517. %@AI@%pwxy1%@AE@%                             Upper-left corner of bounding rectangle
  12518.  
  12519. %@AI@%pwxy2%@AE@%                             Lower-right corner of bounding rectangle
  12520.  
  12521. %@NL@%
  12522. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12523. %@NL@%
  12524. The %@AB@%_ellipse%@AE@% functions draw ellipses or circles. The borders are drawn in
  12525. the current color. In the %@AB@%_ellipse%@AE@% function, the center of the ellipse is
  12526. the center of the bounding rectangle defined by the view-coordinate points
  12527. (%@AI@%x1%@AE@%, %@AI@%y1%@AE@%) and (%@AI@%x2%@AE@%, %@AI@%y2%@AE@%).  %@NL@%
  12528. %@NL@%
  12529. In the %@AB@%_ellipse_w%@AE@% function, the center of the ellipse is the center of the
  12530. bounding rectangle defined by the window-coordinate points (%@AI@%wx1%@AE@%, %@AI@%wy1%@AE@%) and
  12531. (%@AI@%wx2%@AE@%, %@AI@%wy2%@AE@%).  %@NL@%
  12532. %@NL@%
  12533. In the %@AB@%_ellipse_wxy%@AE@% function, the center of the ellipse is the center of the
  12534. bounding rectangle defined by the window-coordinate pairs (%@AI@%pwxy1%@AE@%) and
  12535. (%@AI@%pwxy2%@AE@%).  %@NL@%
  12536. %@NL@%
  12537. If the bounding-rectangle arguments define a point or a vertical or
  12538. horizontal line, no figure is drawn.  %@NL@%
  12539. %@NL@%
  12540. The %@AI@%control%@AE@% argument can be one of the following manifest constants:  %@NL@%
  12541. %@NL@%
  12542. %@AB@%Constant%@AE@%                          %@AB@%Action%@AE@%
  12543. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12544. %@AB@%_GFILLINTERIOR%@AE@%                    Fills the ellipse using the current fill
  12545.                                   mask
  12546.  
  12547. %@AB@%_GBORDER%@AE@%                          Does not fill the ellipse
  12548.  
  12549. The control option given by %@AB@%_GFILLINTERIOR%@AE@% is equivalent to a subsequent
  12550. call to the %@AB@%_floodfill%@AE@% function, using the center of the ellipse as the
  12551. starting point and the current color (set by %@AB@%_setcolor%@AE@%) as the boundary
  12552. color.  %@NL@%
  12553. %@NL@%
  12554. %@NL@%
  12555. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12556. %@NL@%
  12557. The %@AB@%_ellipse%@AE@% functions return a nonzero value if the ellipse is drawn
  12558. successfully; otherwise, they return 0.  %@NL@%
  12559. %@NL@%
  12560. %@NL@%
  12561. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12562. %@NL@%
  12563.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  12564. %@NL@%
  12565. %@NL@%
  12566. %@NL@%
  12567. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12568. %@NL@%
  12569. %@AB@%_arc%@AE@% functions,  %@AB@%_floodfill%@AE@%,  %@AB@%_grstatus%@AE@%,  %@AB@%_lineto%@AE@% functions,  %@AB@%_pie%@AE@%
  12570. functions, %@AB@%_polygon%@AE@% functions,  %@AB@%_rectangle%@AE@% functions,  %@AB@%_setcolor%@AE@%,%@AB@% %@AE@%
  12571. %@AB@%_setfillmask%@AE@%  %@NL@%
  12572. %@NL@%
  12573. %@NL@%
  12574. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12575. %@NL@%
  12576. %@AS@%  /* ELLIPSE.C: This program draws a simple ellipse. */
  12577. %@AS@%  
  12578. %@AS@%  #include <conio.h>
  12579. %@AS@%  #include <stdlib.h>
  12580. %@AS@%  #include <graph.h>
  12581. %@AS@%  
  12582. %@AS@%  void main()
  12583. %@AS@%  {
  12584. %@AS@%     /* Find a valid graphics mode. */
  12585. %@AS@%     if( !_setvideomode( _MAXRESMODE ) )
  12586. %@AS@%        exit( 1 );
  12587. %@AS@%  
  12588. %@AS@%     _ellipse( _GFILLINTERIOR, 80, 50, 240, 150 );
  12589. %@AS@%  
  12590. %@AS@%     /* Strike any key to clear screen. */
  12591. %@AS@%     getch();
  12592. %@AS@%     _setvideomode( _DEFAULTMODE );
  12593. %@AS@%  } %@AE@%%@NL@%
  12594. %@NL@%
  12595. %@NL@%
  12596. %@NL@%
  12597. %@NL@%
  12598. %@QR:_enable@%%@NL@%
  12599. %@2@%%@CR:C6A00840436 @%%@AB@%_enable%@AE@%%@EH@%%@NL@%
  12600. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12601. %@NL@%
  12602. %@NL@%
  12603. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  12604. %@NL@%
  12605. Enables interrupts.  %@NL@%
  12606. %@NL@%
  12607. %@CR:C6A00840437 @%%@CR:C6A00840438 @%%@AS@%  #include <dos.h>%@AE@%%@NL@%
  12608. %@NL@%
  12609. %@AS@%  void _enable( void );%@AE@%%@NL@%
  12610. %@NL@%
  12611. %@NL@%
  12612. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12613. %@NL@%
  12614. The %@AB@%_enable%@AE@% routine enables interrupts by executing an 8086 %@AB@%STI%@AE@% machine
  12615. instruction.  %@NL@%
  12616. %@NL@%
  12617. %@NL@%
  12618. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12619. %@NL@%
  12620. None.  %@NL@%
  12621. %@NL@%
  12622. %@NL@%
  12623. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12624. %@NL@%
  12625.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  12626. %@NL@%
  12627. %@NL@%
  12628. %@NL@%
  12629. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12630. %@NL@%
  12631. %@AB@%_disable%@AE@%  %@NL@%
  12632. %@NL@%
  12633. %@NL@%
  12634. %@NL@%
  12635. %@NL@%
  12636. %@QR:_endthread@%%@NL@%
  12637. %@2@%%@CR:C6A00850439 @%%@AB@%_endthread%@AE@%%@EH@%%@NL@%
  12638. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12639. %@NL@%
  12640. %@NL@%
  12641. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  12642. %@NL@%
  12643. Terminates an OS/2 thread.  %@NL@%
  12644. %@NL@%
  12645. %@CR:C6A00850440 @%%@CR:C6A00850441 @%%@AB@%#include <process.h>%@AE@%              Multithread version of PROCESS.H
  12646.  
  12647. %@AS@%  void _far _endthread( void );%@AE@%%@NL@%
  12648. %@NL@%
  12649. %@NL@%
  12650. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  12651. %@NL@%
  12652. The %@AB@%_endthread%@AE@% function terminates a thread created by %@AB@%_beginthread%@AE@%.  %@NL@%
  12653. %@NL@%
  12654. Because threads terminate automatically, the%@AB@% _endthread%@AE@% function is normally
  12655. not required. It is used to terminate a thread conditionally.  %@NL@%
  12656. %@NL@%
  12657. The OS/2 function %@AB@%DosExit%@AE@% should not be used to terminate threads created by
  12658. the %@AB@%_beginthread%@AE@% function. If %@AB@%DosExit%@AE@% is used, the results are
  12659. unpredictable.%@CR:C6A00850442 @%%@CR:C6A00850443 @%  %@NL@%
  12660. %@NL@%
  12661. %@NL@%
  12662. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12663. %@NL@%
  12664. None.  %@NL@%
  12665. %@NL@%
  12666. %@NL@%
  12667. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12668. %@NL@%
  12669.  ANSI   DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  12670. %@NL@%
  12671. %@NL@%
  12672. %@NL@%
  12673. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12674. %@NL@%
  12675. %@AB@%_beginthread%@AE@%  %@NL@%
  12676. %@NL@%
  12677. %@NL@%
  12678. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12679. %@NL@%
  12680. See the example for %@AB@%_beginthread%@AE@%.  %@NL@%
  12681. %@NL@%
  12682. %@NL@%
  12683. %@NL@%
  12684. %@NL@%
  12685. %@QR:eof@%%@NL@%
  12686. %@2@%%@CR:C6A00860444 @%%@AB@%eof%@AE@%%@EH@%%@NL@%
  12687. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12688. %@NL@%
  12689. %@NL@%
  12690. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  12691. %@NL@%
  12692. Tests for end-of-file.  %@NL@%
  12693. %@NL@%
  12694. %@CR:C6A00860445 @%%@CR:C6A00860446 @%%@CR:C6A00860447 @%%@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  12695.  
  12696. %@AS@%  int eof( int handle );%@AE@%%@NL@%
  12697. %@NL@%
  12698. %@AI@%handle%@AE@%                            Handle referring to open file
  12699.  
  12700. %@NL@%
  12701. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12702. %@NL@%
  12703. The %@AB@%eof%@AE@% function determines whether the end of the file associated with
  12704. %@AI@%handle%@AE@% has been reached.  %@NL@%
  12705. %@NL@%
  12706. %@NL@%
  12707. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12708. %@NL@%
  12709. The %@AB@%eof%@AE@% function returns the value 1 if the current position is end-of-file,
  12710. or 0 if it is not. A return value of -1 indicates an error; in this case,
  12711. %@AB@%errno%@AE@% is set to %@AB@%EBADF%@AE@%, indicating an invalid file handle.  %@NL@%
  12712. %@NL@%
  12713. %@NL@%
  12714. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12715. %@NL@%
  12716.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  12717. %@NL@%
  12718. %@NL@%
  12719. %@NL@%
  12720. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12721. %@NL@%
  12722. %@AB@%clearerr%@AE@%, %@AB@%feof%@AE@%, %@AB@%ferror%@AE@%, %@AB@%perror%@AE@%  %@NL@%
  12723. %@NL@%
  12724. %@NL@%
  12725. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12726. %@NL@%
  12727. %@AS@%  /* EOF.C: This program reads data from a file ten bytes at a time
  12728. %@AS@%   * until the end of the file is reached or an error is encountered.
  12729. %@AS@%   */
  12730. %@AS@%  
  12731. %@AS@%  #include <io.h>
  12732. %@AS@%  #include <fcntl.h>
  12733. %@AS@%  #include <stdio.h>
  12734. %@AS@%  #include <stdlib.h>
  12735. %@AS@%  
  12736. %@AS@%  void main()
  12737. %@AS@%  {
  12738. %@AS@%     int  fh, count, total = 0;
  12739. %@AS@%     char buf[10];
  12740. %@AS@%  
  12741. %@AS@%     if( (fh = open( "eof.c", O_RDONLY )) == - 1 )
  12742. %@AS@%        exit( 1 );%@AE@%%@NL@%
  12743. %@NL@%
  12744. %@AS@%  /* Cycle until end of file reached: */
  12745. %@AS@%     while( !eof( fh ) )
  12746. %@AS@%     {
  12747. %@AS@%        /* Attempt to read in 10 bytes: */
  12748. %@AS@%        if( (count = read( fh, buf, 10 )) == -1 )
  12749. %@AS@%        {
  12750. %@AS@%           perror( "Read error" );
  12751. %@AS@%           break;
  12752. %@AS@%        }
  12753. %@AS@%  
  12754. %@AS@%        /* Total up actual bytes read */
  12755. %@AS@%        total += count;
  12756. %@AS@%     }
  12757. %@AS@%     printf( "Number of bytes read = %d\n", total );
  12758. %@AS@%     close( fh );
  12759. %@AS@%  }%@AE@%%@NL@%
  12760. %@NL@%
  12761. %@NL@%
  12762. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  12763. %@NL@%
  12764. %@AS@%  
  12765. %@AS@%  
  12766. %@AS@%  Number of bytes read = 715 %@AE@%%@NL@%
  12767. %@NL@%
  12768. %@NL@%
  12769. %@NL@%
  12770. %@NL@%
  12771. %@QR:exec@%%@NL@%
  12772. %@2@%%@CR:C6A00870448 @%%@AB@%exec Functions%@AE@%%@EH@%%@NL@%
  12773. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12774. %@NL@%
  12775. %@NL@%
  12776. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  12777. %@NL@%
  12778. Load and execute new child processes.  %@NL@%
  12779. %@NL@%
  12780. %@CR:C6A00870449 @%%@CR:C6A00870450 @%%@CR:C6A00870451 @%%@AB@%#include <process.h>%@AE@%              Required only for function declarations
  12781.  
  12782. %@AS@%  int execl( char *cmdname, char *arg0, ... char *argn, NULL );%@AE@%%@NL@%
  12783. %@NL@%
  12784. %@AS@%  int execle( char *cmdname, char *arg0, ... char *argn, NULL, 
  12785. %@AS@%  char **envp );%@AE@%%@NL@%
  12786. %@NL@%
  12787. %@AS@%  int execlp( char *cmdname, char *arg0, ... char *argn, NULL  );%@AE@%%@NL@%
  12788. %@NL@%
  12789. %@AS@%  int execlpe( char *cmdname, char *arg0, ... char *argn, NULL, 
  12790. %@AS@%  char **envp  );%@AE@%%@NL@%
  12791. %@NL@%
  12792. %@AS@%  int execv( char *cmdname, char **argv );%@AE@%%@NL@%
  12793. %@NL@%
  12794. %@AS@%  int execve( char *cmdname, char **argv, char **envp );%@AE@%%@NL@%
  12795. %@NL@%
  12796. %@AS@%  int execvp( char *cmdname, char **argv );%@AE@%%@NL@%
  12797. %@NL@%
  12798. %@AS@%  int execvpe( char *cmdname, char **argv, char **envp );%@AE@%%@NL@%
  12799. %@NL@%
  12800. %@AI@%cmdname%@AE@%                           Path name of file to be executed
  12801.  
  12802. %@AI@%arg0, ... argn%@AE@%                    List of pointers to arguments
  12803.  
  12804. %@AI@%argv%@AE@%                              Array of pointers to arguments
  12805.  
  12806. %@AI@%envp%@AE@%                              Array of pointers to environment 
  12807.                                   settings
  12808.  
  12809. %@NL@%
  12810. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  12811. %@NL@%
  12812. The %@AB@%exec%@AE@% functions load and execute new child processes. When the call is
  12813. successful in DOS, the child process is placed in the memory previously
  12814. occupied by the calling process. Under OS/2, calling an %@AB@%exec%@AE@% function is
  12815. equivalent to calling the corresponding function with the %@AB@%P_NOWAITO%@AE@% argument
  12816. specified, followed by a call to the %@AB@%exit%@AE@% function. Sufficient memory must
  12817. be available for loading and executing the child process.  %@NL@%
  12818. %@NL@%
  12819. All of the %@AB@%exec%@AE@% functions use the same operating system function. The
  12820. letter(s) at the end of the function name determine the specific variation,
  12821. as shown in the following list:  %@NL@%
  12822. %@NL@%
  12823. %@AB@%Letter%@AE@%                            %@AB@%Variation%@AE@%
  12824. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12825. %@AB@%e%@AE@%                                 An array of pointers to environment 
  12826.                                   arguments is explicitly passed to the 
  12827.                                   child process.
  12828.  
  12829. %@AB@%l%@AE@%                                 Command-line arguments are passed 
  12830.                                   individually to the %@AB@%exec%@AE@% function.
  12831.  
  12832. %@AB@%p%@AE@%                                 Uses the PATH environment variable to 
  12833.                                   find the file to be 
  12834.                                   executed.
  12835.  
  12836. %@AB@%v%@AE@%                                 Command-line arguments are passed to the
  12837.                                   %@AB@%exec%@AE@% function as an array of pointers.
  12838.  
  12839. The %@AI@%cmdname%@AE@% argument specifies the file to be executed as the child process.
  12840. It can specify a full path (from the root), a partial path (from the current
  12841. working directory), or just a file name. If %@AI@%cmdname%@AE@% does not have a
  12842. file-name extension or does not end with a period (.), the %@AB@%exec%@AE@% function
  12843. searches for the named file; if the search is unsuccessful, it tries the
  12844. same base name, first with the extension .COM, then with the extension .EXE.
  12845. If %@AI@%cmdname%@AE@% has an extension, only that extension is used in the search. If
  12846. %@AI@%cmdname%@AE@% ends with a period, the %@AB@%exec%@AE@% calls search for %@AI@%cmdname%@AE@% with no
  12847. extension. The %@AB@%execlp%@AE@%, %@AB@%execlpe%@AE@%, %@AB@%execvp%@AE@%, and %@AB@%execvpe%@AE@% routines search for
  12848. %@AI@%cmdname%@AE@% (using the same procedures) in the directories specified by the PATH
  12849. environment variable.  %@NL@%
  12850. %@NL@%
  12851. If %@AI@%cmdname%@AE@% contains a drive specifier or any slashes (i.e., if it is a
  12852. relative path name), the %@AB@%exec%@AE@% call searches only for the specified file and
  12853. no path searching is done.  %@NL@%
  12854. %@NL@%
  12855. Arguments are passed to the new process by giving one or more pointers to
  12856. character strings as arguments in the %@AB@%exec%@AE@% call. These character strings
  12857. form the argument list for the child process. The combined length of the
  12858. strings forming the argument list for the new process must not exceed 128
  12859. bytes (in real mode only). The terminating null character (%@AB@%'\0'%@AE@%) for each
  12860. string is not included in the count, but space characters (inserted
  12861. automatically to separate the arguments) are counted.  %@NL@%
  12862. %@NL@%
  12863. The argument pointers can be passed as separate arguments (%@AB@%execl%@AE@%, %@AB@%execle%@AE@%,
  12864. %@AB@%execlp%@AE@%, and %@AB@%execlpe%@AE@%) or as an array of pointers (%@AB@%execv%@AE@%, %@AB@%execve%@AE@%, %@AB@%execvp%@AE@%, and
  12865. %@AB@%execvpe%@AE@%). At least one argument, %@AI@%arg0%@AE@%, must be passed to the child process;
  12866. this argument is %@AI@%argv%@AE@%[0] of the child process. Usually, this argument is a
  12867. copy of the %@AI@%cmdname%@AE@% argument. (A different value will not produce an error.)
  12868. Under versions of DOS earlier than 3.0, the passed value of %@AI@%arg0%@AE@% is not
  12869. available for use in the child process. However, under OS/2 and under DOS
  12870. versions 3.0 and later, %@AI@%cmdname%@AE@% is available as %@AI@%arg0%@AE@%.  %@NL@%
  12871. %@NL@%
  12872. The %@AB@%execl%@AE@%, %@AB@%execle%@AE@%, %@AB@%execlp%@AE@%, and %@AB@%execlpe%@AE@% calls are typically used when the
  12873. number of arguments is known in advance. The argument %@AI@%arg0%@AE@% is usually a
  12874. pointer to %@AI@%cmdname%@AE@%. The arguments %@AI@%arg1%@AE@% through %@AI@%argn%@AE@% point to the character
  12875. strings forming the new argument list. A null pointer must follow %@AI@%argn%@AE@% to
  12876. mark the end of the argument list.  %@NL@%
  12877. %@NL@%
  12878. The %@AB@%execv%@AE@%, %@AB@%execve%@AE@%, %@AB@%execvp%@AE@%, and %@AB@%execvpe%@AE@% calls are useful when the number of
  12879. arguments to the new process is variable. Pointers to the arguments are
  12880. passed as an array, %@AI@%argv%@AE@%. The argument %@AI@%argv%@AE@%[0] is usually a pointer to
  12881. %@AI@%cmdname%@AE@%. The arguments %@AI@%argv%@AE@%[1] through %@AI@%argv%@AE@%[%@AI@%n%@AE@%] point to the character
  12882. strings forming the new argument list. The argument %@AI@%argv%@AE@%[%@AI@%n%@AE@%+1] must be a %@AB@%NULL
  12883. %@AB@%%@AE@%pointer to mark the end of the argument list.  %@NL@%
  12884. %@NL@%
  12885. Files that are open when an %@AB@%exec%@AE@% call is made remain open in the new
  12886. process. In the %@AB@%execl%@AE@%, %@AB@%execlp%@AE@%, %@AB@%execv%@AE@%, and %@AB@%execvp%@AE@% calls, the child process
  12887. inherits the environment of the parent. The %@AB@%execle%@AE@%, %@AB@%execlpe%@AE@%, %@AB@%execve%@AE@%, and
  12888. %@AB@%execvpe%@AE@% calls allow the user to alter the environment for the child process
  12889. by passing a list of environment settings through the %@AI@%envp%@AE@% argument. The
  12890. argument %@AI@%envp%@AE@% is an array of character pointers, each element of which
  12891. (except for the final element) points to a null-terminated string defining
  12892. an environment variable. Such a string usually has the form  %@NL@%
  12893. %@NL@%
  12894. %@AB@%NAME%@AE@%=%@AI@%value%@AE@%  %@NL@%
  12895. %@NL@%
  12896. where %@AB@%NAME%@AE@% is the name of an environment variable and %@AI@%value%@AE@% is the string
  12897. value to which that variable is set. (Note that %@AI@%value%@AE@% is not enclosed in
  12898. double quotation marks.) The final element of the %@AI@%envp%@AE@% array should be %@AB@%NULL%@AE@%.
  12899. When %@AI@%envp%@AE@% itself is %@AB@%NULL%@AE@%, the child process inherits the environment
  12900. settings of the parent process.  %@NL@%
  12901. %@NL@%
  12902. A program executed with one of the %@AB@%exec%@AE@% family of functions is always loaded
  12903. into memory as if the "maximum allocation" field in the program's .EXE file
  12904. header is set to the default value of 0FFFFH. You can use the EXEMOD utility
  12905. to change the maximum allocation field of a program; however, such a program
  12906. invoked with one of the %@AB@%exec%@AE@% functions may behave differently from a program
  12907. invoked directly from the operating-system command line or with one of the
  12908. %@AB@%spawn%@AE@% functions.  %@NL@%
  12909. %@NL@%
  12910. The %@AB@%exec%@AE@% calls do not preserve the translation modes of open files. If the
  12911. child process must use files inherited from the parent, the %@AB@%setmode%@AE@% routine
  12912. should be used to set the translation mode of these files to the desired
  12913. mode.  %@NL@%
  12914. %@NL@%
  12915. You must explicitly flush (using %@AB@%fflush%@AE@% or %@AB@%flushall%@AE@%) or close any stream
  12916. prior to the %@AB@%exec%@AE@% function call.  %@NL@%
  12917. %@NL@%
  12918. Signal settings are not preserved in child processes that are created by
  12919. calls to %@AB@%exec%@AE@% routines. The signal settings are reset to the default in the
  12920. child process.  %@NL@%
  12921. %@NL@%
  12922. %@NL@%
  12923. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  12924. %@NL@%
  12925. The %@AB@%exec%@AE@% functions do not normally return to the calling process. If an %@AB@%exec%@AE@%
  12926. function returns, an error has occurred and the return value is -1. The
  12927. %@AB@%errno%@AE@% variable is set to one of the following values:  %@NL@%
  12928. %@NL@%
  12929. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  12930. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  12931. %@AB@%E2BIG%@AE@%                             The argument list exceeds 128 bytes, or 
  12932.                                   the space required for the environment 
  12933.                                   information exceeds 32K.
  12934.  
  12935. %@AB@%EACCES%@AE@%                            The specified file has a locking or 
  12936.                                   sharing violation
  12937.                                   (OS/2, and DOS versions 3.0 or later).
  12938.  
  12939. %@AB@%EMFILE%@AE@%                            Too many files open (the specified file 
  12940.                                   must be opened to determine whether it 
  12941.                                   is executable).
  12942.  
  12943. %@AB@%ENOENT%@AE@%                            File or path name not found.
  12944.  
  12945. %@AB@%ENOEXEC%@AE@%                           The specified file is not executable or 
  12946.                                   has an invalid
  12947.                                   executable-file format.
  12948.  
  12949. %@AB@%ENOMEM%@AE@%                            Not enough memory is available to 
  12950.                                   execute the child process; or the 
  12951.                                   available memory has been corrupted; or 
  12952.                                   an invalid block exists, indicating that
  12953.                                   the parent process was not allocated 
  12954.                                   properly.
  12955.  
  12956. %@NL@%
  12957. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  12958. %@NL@%
  12959.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  12960. %@NL@%
  12961. %@NL@%
  12962. Because of differences in DOS versions 2.0 and 2.1, child processes
  12963. generated by the %@AB@%exec%@AE@% family of functions (or by the equivalent %@AB@%spawn%@AE@%
  12964. functions with the %@AB@%P_OVERLAY%@AE@% argument) may cause fatal system errors when
  12965. they exit. If you are running DOS 2.0 or 2.1, you must upgrade to DOS
  12966. version 3.0 or later to use these functions.  %@NL@%
  12967. %@NL@%
  12968. Bound programs cannot use the %@AB@%exec%@AE@% family of functions in real mode.  %@NL@%
  12969. %@NL@%
  12970. %@NL@%
  12971. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  12972. %@NL@%
  12973. %@AB@%abort%@AE@%, %@AB@%atexit%@AE@%, %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, %@AB@%onexit%@AE@%, %@AB@%spawn%@AE@% functions, %@AB@%system%@AE@%  %@NL@%
  12974. %@NL@%
  12975. %@NL@%
  12976. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  12977. %@NL@%
  12978. %@AS@%  /* EXEC.C: This program accepts a number in the range 1 through 8 from the
  12979. %@AS@%   * command line. Based on the number it receives, it executes one of the
  12980. %@AS@%   * eight different procedures that spawn the process named child. For
  12981. %@AS@%   * some of these procedures, the child.exe file must be in the same
  12982. %@AS@%   * directory; for others, it need only be in the same path.
  12983. %@AS@%   */
  12984. %@AS@%  
  12985. %@AS@%  #include <stdio.h>
  12986. %@AS@%  #include <process.h>
  12987. %@AS@%  
  12988. %@AS@%  char *my_env[] = {
  12989. %@AS@%                "THIS=environment will be",
  12990. %@AS@%                "PASSED=to child.exe by the",
  12991. %@AS@%                "EXECLE=and",
  12992. %@AS@%                "EXECLPE=and",
  12993. %@AS@%                "EXECVE=and",
  12994. %@AS@%                "EXECVPE=functions",
  12995. %@AS@%                NULL
  12996. %@AS@%                };
  12997. %@AS@%  
  12998. %@AS@%  void main( int argc, char *argv[] )
  12999. %@AS@%  {
  13000. %@AS@%     char *args[4];
  13001. %@AS@%     int result;
  13002. %@AS@%  
  13003. %@AS@%     args[0] = "child";     /* Set up parameters to send */
  13004. %@AS@%     args[1] = "execv??";
  13005. %@AS@%     args[2] = "two";
  13006. %@AS@%     args[3] = NULL;%@AE@%%@NL@%
  13007. %@NL@%
  13008. %@AS@%  switch( argv[1][0] )   /* Based on first letter of argument */
  13009. %@AS@%     {
  13010. %@AS@%        case '1':
  13011. %@AS@%           execl( argv[2], argv[2], "execl", "two", NULL );
  13012. %@AS@%           break;
  13013. %@AS@%        case '2':
  13014. %@AS@%           execle( argv[2], argv[2], "execle", "two", NULL, my_env );
  13015. %@AS@%           break;
  13016. %@AS@%        case '3':
  13017. %@AS@%           execlp( argv[2], argv[2], "execlp", "two", NULL );
  13018. %@AS@%           break;
  13019. %@AS@%        case '4':
  13020. %@AS@%           execlpe( argv[2], argv[2], "execlpe", "two", NULL, my_env );
  13021. %@AS@%           break;
  13022. %@AS@%        case '5':
  13023. %@AS@%           execv( argv[2], args );
  13024. %@AS@%           break;
  13025. %@AS@%        case '6':
  13026. %@AS@%           execve( argv[2], args, my_env );
  13027. %@AS@%           break;
  13028. %@AS@%        case '7':
  13029. %@AS@%           execvp( argv[2], args );
  13030. %@AS@%           break;
  13031. %@AS@%        case '8':
  13032. %@AS@%           execvpe( argv[2], args, my_env );
  13033. %@AS@%           break;
  13034. %@AS@%        default:
  13035. %@AS@%           printf( "SYNTAX: EXEC <1-8> <childprogram>\n" );
  13036. %@AS@%           exit( 1 );
  13037. %@AS@%     }
  13038. %@AS@%     printf( "Process was not spawned.\n" );
  13039. %@AS@%     printf( "Program 'child' was not found." );
  13040. %@AS@%  } %@AE@%%@NL@%
  13041. %@NL@%
  13042. %@NL@%
  13043. %@NL@%
  13044. %@NL@%
  13045. %@QR:exit@%%@QR:_exit@%%@NL@%
  13046. %@2@%%@CR:C6A00880452 @%%@AB@%exit, _exit%@AE@%%@EH@%%@NL@%
  13047. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13048. %@NL@%
  13049. %@NL@%
  13050. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  13051. %@NL@%
  13052. Terminate the calling process after cleanup (%@AB@%exit%@AE@%) or immediately (%@AB@% _exit%@AE@%).
  13053. %@NL@%
  13054. %@NL@%
  13055. %@CR:C6A00880453 @%%@CR:C6A00880454 @%%@AB@%#include <process.h>%@AE@%              Required only for function declarations
  13056.  
  13057. %@AB@%#include <stdlib.h>%@AE@%               Use either PROCESS.H or STDLIB.H
  13058.  
  13059. %@AS@%  void exit( int status );%@AE@%%@NL@%
  13060. %@NL@%
  13061. %@AS@%  void _exit( int status );%@AE@%%@NL@%
  13062. %@NL@%
  13063. %@AI@%status%@AE@%                            Exit status
  13064.  
  13065. %@NL@%
  13066. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13067. %@NL@%
  13068. The %@AB@%exit%@AE@% and %@AB@%_exit%@AE@% functions terminate the calling process. The %@AB@%exit%@AE@%
  13069. function first calls, in LIFO (last-in-first-out) order, the functions
  13070. registered by %@AB@%atexit%@AE@% and %@AB@%onexit%@AE@%, then flushes all file buffers before
  13071. terminating the process. The %@AB@%_exit%@AE@% function terminates the process without
  13072. processing %@AB@%atexit%@AE@% or %@AB@%onexit%@AE@% functions or flushing stream buffers. The %@AI@%status%@AE@%
  13073. value is typically set to 0 to indicate a normal exit and set to some other
  13074. value to indicate an error.%@CR:C6A00880455 @%  %@NL@%
  13075. %@NL@%
  13076. Although the %@AB@%exit%@AE@% and %@AB@%_exit%@AE@% calls do not return a value, the low-order byte
  13077. of %@AI@%status%@AE@% is made available to the waiting parent process, if one exists,
  13078. after the calling process exits. The %@AI@%status%@AE@% value is available to the
  13079. operating-system batch command ERRORLEVEL.  %@NL@%
  13080. %@NL@%
  13081. The behavior of the %@AB@%exit%@AE@%, %@AB@%_exit%@AE@%, %@AB@%_cexit%@AE@%, and %@AB@%_c_exit%@AE@% functions is as
  13082. follows:  %@NL@%
  13083. %@NL@%
  13084. %@AB@%Function%@AE@%                          %@AB@%Action%@AE@%
  13085. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13086. %@AB@%exit%@AE@%                              Performs complete C library termination 
  13087.                                   procedures, terminates the process, and 
  13088.                                   exits with the supplied status code.
  13089.  
  13090. %@AB@%_exit%@AE@%                             Performs "quick" C library termination 
  13091.                                   procedures, terminates the process, and 
  13092.                                   exits with the supplied status code.
  13093.  
  13094. %@AB@%_cexit%@AE@%                            Performs complete C library termination 
  13095.                                   procedures and returns to caller, but 
  13096.                                   does not terminate the process.
  13097.  
  13098. %@AB@%_c_exit%@AE@%                           Performs "quick" C library termination 
  13099.                                   procedures and returns to caller, but 
  13100.                                   does not terminate the process.
  13101.  
  13102. %@NL@%
  13103. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13104. %@NL@%
  13105. None.  %@NL@%
  13106. %@NL@%
  13107. %@NL@%
  13108. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13109. %@NL@%
  13110. %@AB@%exit%@AE@%  %@NL@%
  13111. %@NL@%
  13112. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13113. %@NL@%
  13114. %@NL@%
  13115. %@AB@%_exit%@AE@%  %@NL@%
  13116. %@NL@%
  13117.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  13118. %@NL@%
  13119. %@NL@%
  13120. %@NL@%
  13121. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13122. %@NL@%
  13123. %@AB@%abort%@AE@%, %@AB@%atexit%@AE@%, %@AB@%_cexit%@AE@%, %@AB@%exec%@AE@% functions, %@AB@%onexit%@AE@%, %@AB@%spawn%@AE@% functions, %@AB@%system%@AE@%  %@NL@%
  13124. %@NL@%
  13125. %@NL@%
  13126. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13127. %@NL@%
  13128. %@AS@%  /* EXITER.C: This program prompts the user for a yes or no and returns
  13129. %@AS@%   * a DOS error code of 1 if the user answers Y or y; otherwise it
  13130. %@AS@%   * returns 0. The error code could be tested in a batch file.
  13131. %@AS@%   */
  13132. %@AS@%  
  13133. %@AS@%  #include <conio.h>
  13134. %@AS@%  #include <stdlib.h>
  13135. %@AS@%  
  13136. %@AS@%  void main()
  13137. %@AS@%  {
  13138. %@AS@%     char  ch;
  13139. %@AS@%  
  13140. %@AS@%     cputs( "Yes or no? " );
  13141. %@AS@%     ch = getch();
  13142. %@AS@%     cputs( "\r\n" );
  13143. %@AS@%     if( toupper( ch ) == 'Y' )
  13144. %@AS@%        exit( 1 );
  13145. %@AS@%     else
  13146. %@AS@%        exit( 0 );
  13147. %@AS@%  }%@AE@%%@NL@%
  13148. %@NL@%
  13149. %@NL@%
  13150. %@NL@%
  13151. %@NL@%
  13152. %@QR:exp@%%@QR:expl@%%@NL@%
  13153. %@2@%%@CR:C6A00890456 @%%@AB@%exp, expl%@AE@%%@EH@%%@NL@%
  13154. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13155. %@NL@%
  13156. %@NL@%
  13157. %@3@%%@AB@%Description%@CR:C6A00890457 @%%@CR:C6A00890458 @%%@CR:C6A00890459 @% %@CR:C6A00890460 @%%@AE@%%@EH@%%@NL@%
  13158. %@NL@%
  13159. Calculate the exponential.  %@NL@%
  13160. %@NL@%
  13161. %@AS@%  #include <math.h>%@AE@%%@NL@%
  13162. %@NL@%
  13163. %@AS@%  double exp( double x );%@AE@%%@NL@%
  13164. %@NL@%
  13165. %@AS@%  long double expl( long double x );%@AE@%%@NL@%
  13166. %@NL@%
  13167. %@AI@%x%@AE@%                                 Floating-point value
  13168.  
  13169. %@NL@%
  13170. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13171. %@NL@%
  13172. The %@AB@%exp%@AE@% and %@AB@%expl%@AE@% functions return the exponential function of their
  13173. floating-point arguments (%@AI@%x%@AE@%).  %@NL@%
  13174. %@NL@%
  13175. The %@AB@%expl%@AE@% function is the 80-bit counterpart; it uses an 80-bit, 10-byte
  13176. coprocessor form of arguments and return values. See the reference page on
  13177. the long double functions for more details on this data type.  %@NL@%
  13178. %@NL@%
  13179. %@NL@%
  13180. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13181. %@NL@%
  13182. These functions return ex%@AI@%.%@AE@% The functions return %@AB@%HUGE_VAL%@AE@% on overflow and set
  13183. %@AB@%errno%@AE@% to %@AB@%ERANGE%@AE@%; on underflow, they return 0 but do not set %@AB@%errno%@AE@%.  %@NL@%
  13184. %@NL@%
  13185. %@NL@%
  13186. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13187. %@NL@%
  13188. %@AB@%exp%@AE@%  %@NL@%
  13189. %@NL@%
  13190. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13191. %@NL@%
  13192. %@NL@%
  13193. %@AB@%expl%@AE@%  %@NL@%
  13194. %@NL@%
  13195.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  13196. %@NL@%
  13197. %@NL@%
  13198. %@NL@%
  13199. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13200. %@NL@%
  13201. %@AB@%log%@AE@% functions  %@NL@%
  13202. %@NL@%
  13203. %@NL@%
  13204. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13205. %@NL@%
  13206. %@AS@%  /* EXP.C */
  13207. %@AS@%  #include <math.h>
  13208. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13209. %@NL@%
  13210. %@AS@%  void main()
  13211. %@AS@%  {
  13212. %@AS@%     double x = 2.302585093, y;
  13213. %@AS@%  
  13214. %@AS@%     y = exp( x );
  13215. %@AS@%     printf( "exp( %f ) = %f\n", x, y );
  13216. %@AS@%  }%@AE@%%@NL@%
  13217. %@NL@%
  13218. %@NL@%
  13219. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13220. %@NL@%
  13221. %@AS@%  
  13222. %@AS@%  
  13223. %@AS@%  exp( 2.302585 ) = 10.000000%@AE@%%@NL@%
  13224. %@NL@%
  13225. %@NL@%
  13226. %@NL@%
  13227. %@NL@%
  13228. %@QR:_expand@%%@NL@%
  13229. %@2@%%@CR:C6A00900461 @%%@AB@%_expand Functions%@AE@%%@EH@%%@NL@%
  13230. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13231. %@NL@%
  13232. %@NL@%
  13233. %@3@%%@AB@%Description%@CR:C6A00900462 @%%@CR:C6A00900463 @% %@CR:C6A00900464 @%%@CR:C6A00900465 @%%@CR:C6A00900466 @%%@CR:C6A00900467 @%%@AE@%%@EH@%%@NL@%
  13234. %@NL@%
  13235. Changes the size of a memory block.  %@NL@%
  13236. %@NL@%
  13237. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  13238.  
  13239. %@AS@%  void *_expand( void *memblock, size_t size );%@AE@%%@NL@%
  13240. %@NL@%
  13241. %@AS@%  void _based( void ) *_bexpand( _segment seg, void _based( void )
  13242. %@AS@%  *memblock, 
  13243. %@AS@%  size_t size );%@AE@%%@NL@%
  13244. %@NL@%
  13245. %@AS@%  void _far *_fexpand( void _far *memblock, size_t size );%@AE@%%@NL@%
  13246. %@NL@%
  13247. %@AS@%  void _near *_nexpand( void _near *memblock, size_t size );%@AE@%%@NL@%
  13248. %@NL@%
  13249. %@AI@%memblock%@AE@%                          Pointer to previously allocated memory 
  13250.                                   block
  13251.  
  13252. %@AI@%size%@AE@%                              New size in bytes
  13253.  
  13254. %@AI@%seg%@AE@%                               Value of base segment
  13255.  
  13256. %@NL@%
  13257. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13258. %@NL@%
  13259. The %@AB@%_expand%@AE@% family of functions changes the size of a previously allocated
  13260. memory block by attempting to expand or contract the block without moving
  13261. its location in the heap. The %@AI@%memblock%@AE@% argument points to the beginning of
  13262. the block. The %@AI@%size%@AE@% argument gives the new size of the block, in bytes. The
  13263. contents of the block are unchanged up to the shorter of the new and old
  13264. sizes.  %@NL@%
  13265. %@NL@%
  13266. The %@AI@%memblock%@AE@% argument can also point to a block that has been freed, as long
  13267. as there has been no intervening call to %@AB@%calloc%@AE@%, %@AB@%_expand%@AE@%, %@AB@%malloc%@AE@%, or
  13268. %@AB@%realloc%@AE@%. If %@AI@%memblock%@AE@% points to a freed block, the block remains free after a
  13269. call to one of the %@AB@%_expand%@AE@% functions.  %@NL@%
  13270. %@NL@%
  13271. The %@AI@%seg%@AE@% argument is the segment address of the %@AB@%_based%@AE@% heap.  %@NL@%
  13272. %@NL@%
  13273. In large data models (compact-, large-, and huge-model programs), %@AB@%_expand%@AE@%
  13274. maps to %@AB@%_fexpand%@AE@%. In small data models ( tiny-, small-, and medium-model
  13275. programs), %@AB@%expand%@AE@% maps to %@AB@%_nexpand%@AE@%.  %@NL@%
  13276. %@NL@%
  13277. The various %@AB@%_expand%@AE@% functions change the size of the storage block in the
  13278. data segments shown in the list below:  %@NL@%
  13279. %@NL@%
  13280. %@AB@%Function%@AE@%                          %@AB@%Data Segment%@AE@%
  13281. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13282. %@AB@%_expand%@AE@%                           Depends on data model of program
  13283.  
  13284. %@AB@%_bexpand%@AE@%                          Based heap specified by %@AI@%seg%@AE@%, or in all 
  13285.                                   based heaps if %@AI@%seg%@AE@%
  13286.                                   is zero
  13287.  
  13288. %@AB@%_fexpand%@AE@%                          Far heap (outside default data segment)
  13289.  
  13290. %@AB@%_nexpand%@AE@%                          Near heap (inside default data segment)
  13291.  
  13292. %@NL@%
  13293. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13294. %@NL@%
  13295. The %@AB@%_expand%@AE@% family of functions returns a %@AB@%void%@AE@% pointer to the reallocated
  13296. memory block. Unlike %@AB@%realloc%@AE@%, %@AB@%_expand%@AE@% cannot move a block to change its
  13297. size. This means the %@AI@%memblock%@AE@% argument to %@AB@%_expand%@AE@% is the same as the return
  13298. value if there is sufficient memory available to expand the block without
  13299. moving it.  %@NL@%
  13300. %@NL@%
  13301. With the exception of the %@AB@%_bexpand%@AE@% function, these functions return %@AB@%NULL%@AE@% if
  13302. there is insufficient memory available to expand the block to the given size
  13303. without moving it. The %@AB@%_bexpand%@AE@% function returns %@AB@%_NULLOFF%@AE@% if insufficient
  13304. memory is available. The item pointed to by %@AI@%memblock%@AE@% will have been expanded
  13305. as much as possible in its current location.  %@NL@%
  13306. %@NL@%
  13307. The storage space pointed to by the return value is guaranteed to be
  13308. suitably aligned for storage of any type of object. The new size of the item
  13309. can be checked with the %@AB@%_msize%@AE@% function. To get a pointer to a type other
  13310. than %@AB@%void%@AE@%, use a type cast on the return value.  %@NL@%
  13311. %@NL@%
  13312. %@NL@%
  13313. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13314. %@NL@%
  13315.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  13316. %@NL@%
  13317. %@NL@%
  13318. %@NL@%
  13319. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13320. %@NL@%
  13321. %@AB@%calloc%@AE@% functions, %@AB@%free%@AE@% functions, %@AB@%malloc%@AE@% functions, %@AB@%_msize%@AE@% functions,
  13322. %@AB@%realloc%@AE@% functions  %@NL@%
  13323. %@NL@%
  13324. %@NL@%
  13325. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13326. %@NL@%
  13327. %@AS@%  /* EXPAND.C */
  13328. %@AS@%  #include <stdio.h>
  13329. %@AS@%  #include <malloc.h>
  13330. %@AS@%  #include <stdlib.h>
  13331. %@AS@%  
  13332. %@AS@%  void main()
  13333. %@AS@%  {
  13334. %@AS@%     char *bufchar;
  13335. %@AS@%  
  13336. %@AS@%     printf( "Allocate a 512 element buffer\n" );
  13337. %@AS@%     if( (bufchar = (char *)calloc( 512, sizeof( char ) )) == NULL )
  13338. %@AS@%        exit( 1 );
  13339. %@AS@%     printf( "Allocated %d bytes at %Fp\n",
  13340. %@AS@%           _msize( bufchar ), (void _far *)bufchar );
  13341. %@AS@%  
  13342. %@AS@%     if( (bufchar = (char *)_expand( bufchar, 1024 )) == NULL )
  13343. %@AS@%        printf( "Can't expand" );
  13344. %@AS@%     else
  13345. %@AS@%        printf( "Expanded block to %d bytes at %Fp\n",
  13346. %@AS@%              _msize( bufchar ), (void _far *)bufchar );
  13347. %@AS@%  
  13348. %@AS@%     /* Free memory */
  13349. %@AS@%     free( bufchar );
  13350. %@AS@%     exit( 0 );
  13351. %@AS@%  }%@AE@%%@NL@%
  13352. %@NL@%
  13353. %@NL@%
  13354. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13355. %@NL@%
  13356. %@AS@%  
  13357. %@AS@%  
  13358. %@AS@%  Allocate a 512 element buffer
  13359. %@AS@%  Allocated 512 bytes at 0067:142A
  13360. %@AS@%  Expanded block to 1024 bytes at 0067:142A%@AE@%%@NL@%
  13361. %@NL@%
  13362. %@NL@%
  13363. %@NL@%
  13364. %@NL@%
  13365. %@QR:fabs@%%@QR:fabsl@%%@NL@%
  13366. %@2@%%@CR:C6A00910468 @%%@AB@%fabs, fabsl%@AE@%%@EH@%%@NL@%
  13367. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13368. %@NL@%
  13369. %@NL@%
  13370. %@3@%%@AB@%Description%@CR:C6A00910469 @%%@CR:C6A00910470 @%%@CR:C6A00910471 @% %@CR:C6A00910472 @%%@AE@%%@EH@%%@NL@%
  13371. %@NL@%
  13372. Calculate the absolute value of their floating-point arguments.  %@NL@%
  13373. %@NL@%
  13374. %@AS@%  #include <math.h>%@AE@%%@NL@%
  13375. %@NL@%
  13376. %@AS@%  double fabs( double x );%@AE@%%@NL@%
  13377. %@NL@%
  13378. %@AS@%  long double fabsl( long double x );%@AE@%%@NL@%
  13379. %@NL@%
  13380. %@AI@%x%@AE@%                                 Floating-point value
  13381.  
  13382. %@NL@%
  13383. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13384. %@NL@%
  13385. The %@AB@%fabs%@AE@% and %@AB@%fabsl%@AE@% functions calculate the absolute value of their
  13386. floating-point arguments.  %@NL@%
  13387. %@NL@%
  13388. The %@AB@%fabsl%@AE@% function is the 80-bit counterpart; it uses an 80-bit, 10-byte
  13389. coprocessor form of arguments and return values. See the reference page on
  13390. the long double functions for more details on this data type.  %@NL@%
  13391. %@NL@%
  13392. %@NL@%
  13393. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13394. %@NL@%
  13395. These functions return the absolute value of their arguments. There is no
  13396. error return.  %@NL@%
  13397. %@NL@%
  13398. %@NL@%
  13399. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13400. %@NL@%
  13401. %@AB@%fabs%@AE@%  %@NL@%
  13402. %@NL@%
  13403. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13404. %@NL@%
  13405. %@NL@%
  13406. %@AB@%fabsl%@AE@%  %@NL@%
  13407. %@NL@%
  13408.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  13409. %@NL@%
  13410. %@NL@%
  13411. %@NL@%
  13412. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13413. %@NL@%
  13414. %@AB@%abs%@AE@%, %@AB@%cabs%@AE@%, %@AB@%labs%@AE@%  %@NL@%
  13415. %@NL@%
  13416. %@NL@%
  13417. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13418. %@NL@%
  13419. %@AS@%  /* ABS.C: This program computes and displays the absolute values of
  13420. %@AS@%   * several numbers.
  13421. %@AS@%   */
  13422. %@AS@%  
  13423. %@AS@%  #include <stdio.h>
  13424. %@AS@%  #include <math.h>
  13425. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  13426. %@NL@%
  13427. %@AS@%  void main()
  13428. %@AS@%  {
  13429. %@AS@%     int    ix = -4, iy;
  13430. %@AS@%     long   lx = -41567L, ly;
  13431. %@AS@%     double dx = -3.141593, dy;
  13432. %@AS@%  
  13433. %@AS@%     iy = abs( ix );
  13434. %@AS@%     printf( "The absolute value of %d is %d\n", ix, iy);
  13435. %@AS@%  
  13436. %@AS@%     ly = labs( lx );
  13437. %@AS@%     printf( "The absolute value of %ld is %ld\n", lx, ly);
  13438. %@AS@%  
  13439. %@AS@%     dy = fabs( dx );
  13440. %@AS@%     printf( "The absolute value of %f is %f\n", dx, dy );
  13441. %@AS@%  }%@AE@%%@NL@%
  13442. %@NL@%
  13443. %@NL@%
  13444. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13445. %@NL@%
  13446. %@AS@%  
  13447. %@AS@%  
  13448. %@AS@%  The absolute value of -4 is 4
  13449. %@AS@%  The absolute value of -41567 is 41567
  13450. %@AS@%  The absolute value of -3.141593 is 3.141593%@AE@%%@NL@%
  13451. %@NL@%
  13452. %@NL@%
  13453. %@NL@%
  13454. %@NL@%
  13455. %@QR:fclose@%%@QR:fcloseall@%%@NL@%
  13456. %@2@%%@CR:C6A00920473 @%%@AB@%fclose, fcloseall%@AE@%%@EH@%%@NL@%
  13457. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13458. %@NL@%
  13459. %@NL@%
  13460. %@3@%%@AB@%Description%@CR:C6A00920474 @%%@CR:C6A00920475 @% %@CR:C6A00920476 @%%@AE@%%@EH@%%@NL@%
  13461. %@NL@%
  13462. Closes a stream (%@AB@%fclose%@AE@%) or closes all open streams (%@AB@%fcloseall%@AE@%).  %@NL@%
  13463. %@NL@%
  13464. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13465. %@NL@%
  13466. %@AS@%  int fclose( FILE *stream );%@AE@%%@NL@%
  13467. %@NL@%
  13468. %@AS@%  int fcloseall( void );%@AE@%%@NL@%
  13469. %@NL@%
  13470. %@AI@%stream %@AE@%                           Pointer to %@AB@%FILE%@AE@% structure
  13471.  
  13472. %@NL@%
  13473. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13474. %@NL@%
  13475. The %@AB@%fclose%@AE@% function closes %@AI@%stream%@AE@%. The %@AB@%fcloseall%@AE@% function closes all open
  13476. streams except %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, %@AB@%stderr%@AE@% (and in DOS,%@AB@% stdaux%@AE@% and%@AB@% stdprn%@AE@%). It
  13477. also closes and deletes any temporary files created by %@AB@%tmpfile%@AE@%.  %@NL@%
  13478. %@NL@%
  13479. In both functions, all buffers associated with the stream are flushed prior
  13480. to closing. System-allocated buffers are released when the stream is closed.
  13481. Buffers assigned by the user with %@AB@%setbuf%@AE@% and %@AB@%setvbuf%@AE@% are not automatically
  13482. released.  %@NL@%
  13483. %@NL@%
  13484. %@NL@%
  13485. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13486. %@NL@%
  13487. The %@AB@%fclose%@AE@% function returns 0 if the stream is successfully closed. The
  13488. %@AB@%fcloseall%@AE@% function returns the total number of streams closed. Both
  13489. functions return %@AB@%EOF%@AE@% to indicate an error.  %@NL@%
  13490. %@NL@%
  13491. %@NL@%
  13492. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13493. %@NL@%
  13494. %@AB@%fclose%@AE@%  %@NL@%
  13495. %@NL@%
  13496. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13497. %@NL@%
  13498. %@NL@%
  13499. %@AB@%fcloseall  %@AE@%%@NL@%
  13500. %@NL@%
  13501.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  13502. %@NL@%
  13503. %@NL@%
  13504. %@NL@%
  13505. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13506. %@NL@%
  13507. %@AB@%close%@AE@%, %@AB@%fdopen%@AE@%, %@AB@%fflush%@AE@%, %@AB@%fopen%@AE@%, %@AB@%freopen%@AE@%  %@NL@%
  13508. %@NL@%
  13509. %@NL@%
  13510. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13511. %@NL@%
  13512. %@AS@%  /* FOPEN.C: This program opens files named "data" and "data2". It uses
  13513. %@AS@%   * fclose to close "data" and fcloseall to close all remaining files.
  13514. %@AS@%   */
  13515. %@AS@%  
  13516. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13517. %@NL@%
  13518. %@AS@%  FILE *stream, *stream2;
  13519. %@AS@%  
  13520. %@AS@%  void main()
  13521. %@AS@%  {
  13522. %@AS@%     int numclosed;
  13523. %@AS@%  
  13524. %@AS@%     /* Open for read (will fail if 'data does not exist) */
  13525. %@AS@%     if( (stream  = fopen( "data", "r" )) == NULL )
  13526. %@AS@%        printf( "The file 'data' was not opened\n" );
  13527. %@AS@%     else
  13528. %@AS@%        printf( "The file 'data' was opened\n" );
  13529. %@AS@%  
  13530. %@AS@%     /* Open for write */
  13531. %@AS@%     if( (stream2 = fopen( "data2", "w+" )) == NULL )
  13532. %@AS@%        printf( "The file 'data2' was not opened\n" );
  13533. %@AS@%     else
  13534. %@AS@%        printf( "The file 'data2' was opened\n" );
  13535. %@AS@%  
  13536. %@AS@%     /* Close stream */
  13537. %@AS@%     if( fclose( stream ) )
  13538. %@AS@%        printf( "The file 'data' was not closed\n" );
  13539. %@AS@%  
  13540. %@AS@%     /* All other files are closed: */
  13541. %@AS@%     numclosed = fcloseall( );
  13542. %@AS@%     printf( "Number of files closed by fcloseall: %u\n", numclosed );
  13543. %@AS@%  }%@AE@%%@NL@%
  13544. %@NL@%
  13545. %@NL@%
  13546. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13547. %@NL@%
  13548. %@AS@%  
  13549. %@AS@%  
  13550. %@AS@%  The file 'data' was opened
  13551. %@AS@%  The file 'data2' was opened
  13552. %@AS@%  Number of files closed by fcloseall: 1%@AE@%%@NL@%
  13553. %@NL@%
  13554. %@NL@%
  13555. %@NL@%
  13556. %@NL@%
  13557. %@QR:fcvt@%%@NL@%
  13558. %@2@%%@CR:C6A00930477 @%%@AB@%fcvt%@AE@%%@EH@%%@NL@%
  13559. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13560. %@NL@%
  13561. %@NL@%
  13562. %@3@%%@AB@%Description%@CR:C6A00930478 @%%@CR:C6A00930479 @% %@CR:C6A00930480 @% %@CR:C6A00930481 @%%@AE@%%@EH@%%@NL@%
  13563. %@NL@%
  13564. Converts a floating-point number to a string.  %@NL@%
  13565. %@NL@%
  13566. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  13567.  
  13568. %@AS@%  char *fcvt( double value, int count, int *dec, int *sign );%@AE@%%@NL@%
  13569. %@NL@%
  13570. %@AI@%value%@AE@%                             Number to be converted
  13571.  
  13572. %@AI@%count%@AE@%                             Number of digits after decimal point
  13573.  
  13574. %@AI@%dec%@AE@%                               Pointer to stored decimal-point position
  13575.  
  13576. %@AI@%sign%@AE@%                              Pointer to stored sign indicator
  13577.  
  13578. %@NL@%
  13579. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13580. %@NL@%
  13581. The %@AB@%fcvt%@AE@% function converts a floating-point number to a null-terminated
  13582. character string. The %@AI@%value%@AE@% argument is the floating-point number to be
  13583. converted. The %@AB@%fcvt%@AE@% function stores the digits of %@AI@%value%@AE@% as a string and
  13584. appends a null character (%@AB@%'\0'%@AE@%). The %@AI@%count%@AE@% argument specifies the number of
  13585. digits to be stored after the decimal point. Excess digits are rounded off
  13586. to %@AI@%count%@AE@% places. If there are fewer than %@AI@%count%@AE@% digits of precision, the
  13587. string is padded with zeros.  %@NL@%
  13588. %@NL@%
  13589. Only digits are stored in the string. The position of the decimal point and
  13590. the sign of %@AI@%value%@AE@% can be obtained from %@AI@%dec%@AE@% and %@AI@%sign %@AE@%after the call. The %@AI@%dec
  13591. %@AI@%%@AE@%argument points to an integer value; this integer value gives the position
  13592. of the decimal point with respect to the beginning of the string. A zero or
  13593. negative integer value indicates that the decimal point lies to the left of
  13594. the first digit. The argument %@AI@%sign%@AE@% points to an integer indicating the sign
  13595. of %@AI@%value%@AE@%. The integer is set to 0 if %@AI@%value%@AE@% is positive and is set to a
  13596. nonzero number if %@AI@%value%@AE@% is negative.  %@NL@%
  13597. %@NL@%
  13598. The %@AB@%ecvt %@AE@%and %@AB@%fcvt %@AE@%functions use a single statically allocated buffer for the
  13599. conversion. Each call to one of these routines destroys the results of the
  13600. previous call.  %@NL@%
  13601. %@NL@%
  13602. %@NL@%
  13603. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13604. %@NL@%
  13605. The %@AB@%fcvt%@AE@% function returns a pointer to the string of digits. There is no
  13606. error return.  %@NL@%
  13607. %@NL@%
  13608. %@NL@%
  13609. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13610. %@NL@%
  13611.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13612. %@NL@%
  13613. %@NL@%
  13614. %@NL@%
  13615. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13616. %@NL@%
  13617. %@AB@%atof%@AE@%, %@AB@%atoi%@AE@%, %@AB@%atol%@AE@%, %@AB@%ecvt%@AE@%, %@AB@%gcvt%@AE@%  %@NL@%
  13618. %@NL@%
  13619. %@NL@%
  13620. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13621. %@NL@%
  13622. %@AS@%  /* FCVT.C: This program converts the constant 3.1415926535 to a string and
  13623. %@AS@%   * sets the pointer *buffer to point to that string.
  13624. %@AS@%   */%@AE@%%@NL@%
  13625. %@NL@%
  13626. %@AS@%  #include <stdlib.h>
  13627. %@AS@%  #include <stdio.h>
  13628. %@AS@%  
  13629. %@AS@%  void main()
  13630. %@AS@%  {
  13631. %@AS@%     int  decimal, sign;
  13632. %@AS@%     char *buffer;
  13633. %@AS@%     double source = 3.1415926535;
  13634. %@AS@%  
  13635. %@AS@%     buffer = fcvt( source, 7, &decimal, &sign );
  13636. %@AS@%     printf( "source: %2.10f   buffer: '%s'   decimal: %d   sign: %d\n",
  13637. %@AS@%             source, buffer, decimal, sign );
  13638. %@AS@%  }%@AE@%%@NL@%
  13639. %@NL@%
  13640. %@NL@%
  13641. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13642. %@NL@%
  13643. %@AS@%  
  13644. %@AS@%  
  13645. %@AS@%  source: 3.1415926535   buffer: '31415927'   decimal: 1   sign: 0%@AE@%%@NL@%
  13646. %@NL@%
  13647. %@NL@%
  13648. %@NL@%
  13649. %@NL@%
  13650. %@QR:fdopen@%%@NL@%
  13651. %@2@%%@CR:C6A00940482 @%%@AB@%fdopen%@AE@%%@EH@%%@NL@%
  13652. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13653. %@NL@%
  13654. %@NL@%
  13655. %@3@%%@AB@%Description%@CR:C6A00940483 @%%@CR:C6A00940484 @%%@CR:C6A00940485 @%%@AE@%%@EH@%%@NL@%
  13656. %@NL@%
  13657. Opens a stream using a handle.  %@NL@%
  13658. %@NL@%
  13659. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13660. %@NL@%
  13661. %@AS@%  FILE *fdopen( int handle, char *mode );%@AE@%%@NL@%
  13662. %@NL@%
  13663. %@AI@%handle%@AE@%                            Handle referring to open file
  13664.  
  13665. %@AI@%mode%@AE@%                              Type of access permitted
  13666.  
  13667. %@NL@%
  13668. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13669. %@NL@%
  13670. The %@AB@%fdopen%@AE@% function associates an input/output stream with the file
  13671. identified by %@AI@%handle%@AE@%, thus allowing a file opened for "low-level" I/O to be
  13672. buffered and formatted. (See Section 2.7, "Input and Output," for an
  13673. explanation of stream I/O and low-level I/O.) The %@AI@%mode%@AE@% character string
  13674. specifies the type of access requested for the file, as shown below. The
  13675. following list gives the %@AI@%mode %@AE@%string used in the %@AB@%fopen%@AE@% and %@AB@%fdopen%@AE@% functions
  13676. and the corresponding %@AI@%oflag%@AE@% arguments used in the %@AB@%open%@AE@% and %@AB@%sopen%@AE@% functions.
  13677. A complete description of the %@AI@%mode%@AE@% string argument is given in the remarks
  13678. section of the %@AB@%fopen%@AE@% function. %@CR:C6A00940486 @%  %@NL@%
  13679. %@NL@%
  13680. %@AB@%Type String%@AE@%                       %@AB@%Equivalent Value for open/sopen%@AE@%
  13681. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13682. %@AB@%"r"%@AE@%                               %@AB@%O_RDONLY%@AE@%
  13683.  
  13684. %@AB@%"w"%@AE@%                               %@AB@%O_WRONLY%@AE@% (usually %@AB@%O_WRONLY | O_CREAT | %@AE@%
  13685.                                   %@AB@%O_TRUNC%@AE@%)
  13686.  
  13687. %@AB@%"a"%@AE@%                               %@AB@%O_WRONLY | O_APPEND%@AE@% (usually %@AB@%O_WRONLY | %@AE@%
  13688.                                   %@AB@%O_CREAT | O_APPEND%@AE@%)
  13689.  
  13690. %@AB@%"r+"%@AE@%                              %@AB@%O_RDWR%@AE@%
  13691.  
  13692. %@AB@%"w+"%@AE@%                              %@AB@%O_RDWR%@AE@% (usually %@AB@%O_RDWR | O_CREAT | %@AE@%
  13693.                                   %@AB@%O_TRUNC%@AE@%)
  13694.  
  13695. %@AB@%"a+"%@AE@%                              %@AB@%O_RDWR | O_APPEND%@AE@% (usually %@AB@%O_RDWR | %@AE@%
  13696.                                   %@AB@%O_APPEND | O_CREAT %@AE@%)
  13697.  
  13698. In addition to the values listed above, one of the following characters can
  13699. be included in the %@AI@%mode%@AE@% string to specify the translation mode for newlines.
  13700. These characters correspond to the constants used in the %@AB@%open%@AE@% and %@AB@%sopen%@AE@%
  13701. functions, as shown below: %@CR:C6A00940487 @%%@CR:C6A00940488 @%   %@NL@%
  13702. %@NL@%
  13703. %@AB@%Mode%@AE@%                              %@AB@%Equivalent Value for open/sopen%@AE@%
  13704. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13705. %@AB@%t%@AE@%                                 %@AB@%O_TEXT%@AE@%
  13706.  
  13707. %@AB@%b%@AE@%                                 %@AB@%O_BINARY%@AE@%
  13708.  
  13709. If %@AB@%t%@AE@% or %@AB@%b%@AE@% is not given in the %@AI@%mode%@AE@% string, the translation mode is defined
  13710. by the default-mode variable %@AB@%_fmode%@AE@%.  %@NL@%
  13711. %@NL@%
  13712. The %@AB@%t%@AE@% option is not part of the ANSI standard for %@AB@%fopen%@AE@% and %@AB@%fpopen%@AE@%, but is
  13713. instead a Microsoft extension and should not be used where ANSI portability
  13714. is desired.  %@NL@%
  13715. %@NL@%
  13716. %@NL@%
  13717. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13718. %@NL@%
  13719. The %@AB@%fdopen%@AE@% function returns a pointer to the open stream. A null pointer
  13720. value indicates an error.  %@NL@%
  13721. %@NL@%
  13722. %@NL@%
  13723. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13724. %@NL@%
  13725.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13726. %@NL@%
  13727. %@NL@%
  13728. %@NL@%
  13729. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13730. %@NL@%
  13731. %@AB@%dup%@AE@%, %@AB@%dup2%@AE@%, %@AB@%fclose%@AE@%, %@AB@%fcloseall%@AE@%, %@AB@%fopen%@AE@%, %@AB@%freopen%@AE@%, %@AB@%open%@AE@%  %@NL@%
  13732. %@NL@%
  13733. %@NL@%
  13734. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13735. %@NL@%
  13736. %@AS@%  /* FDOPEN.C: This program opens a file using low-level I/O, then uses
  13737. %@AS@%   * fdopen to switch to stream access. It counts the lines in the file.
  13738. %@AS@%   */
  13739. %@AS@%  
  13740. %@AS@%  #include <stdlib.h>
  13741. %@AS@%  #include <stdio.h>
  13742. %@AS@%  #include <fcntl.h>
  13743. %@AS@%  #include <io.h>
  13744. %@AS@%  
  13745. %@AS@%  void main()
  13746. %@AS@%  {
  13747. %@AS@%     FILE *stream;
  13748. %@AS@%     int  fh, count = 0;
  13749. %@AS@%     char inbuf[128];
  13750. %@AS@%  
  13751. %@AS@%     /* Open a file handle. */
  13752. %@AS@%     if( (fh = open( "fdopen.c", O_RDONLY )) == -1 )
  13753. %@AS@%        exit( 1 );
  13754. %@AS@%  
  13755. %@AS@%     /* Change handle access to stream access. */
  13756. %@AS@%     if( (stream = fdopen( fh, "r" )) == NULL )
  13757. %@AS@%        exit( 1 );
  13758. %@AS@%  
  13759. %@AS@%     while( fgets( inbuf, 128, stream ) != NULL )
  13760. %@AS@%        count++;%@AE@%%@NL@%
  13761. %@NL@%
  13762. %@AS@%  /* After fdopen, close with fclose, not close. */
  13763. %@AS@%     fclose( stream );
  13764. %@AS@%  
  13765. %@AS@%     printf( "Lines in file: %d\n", count );
  13766. %@AS@%  }%@AE@%%@NL@%
  13767. %@NL@%
  13768. %@NL@%
  13769. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13770. %@NL@%
  13771. %@AS@%  
  13772. %@AS@%  
  13773. %@AS@%  Lines in file: 31%@AE@%%@NL@%
  13774. %@NL@%
  13775. %@NL@%
  13776. %@NL@%
  13777. %@NL@%
  13778. %@QR:feof@%%@NL@%
  13779. %@2@%%@CR:C6A00950489 @%%@AB@%feof%@AE@%%@EH@%%@NL@%
  13780. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13781. %@NL@%
  13782. %@NL@%
  13783. %@3@%%@AB@%Description%@CR:C6A00950490 @%%@CR:C6A00950491 @% %@CR:C6A00950492 @%%@AE@%%@EH@%%@NL@%
  13784. %@NL@%
  13785. Tests for end-of-file on a stream.  %@NL@%
  13786. %@NL@%
  13787. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13788. %@NL@%
  13789. %@AS@%  int feof( FILE *stream );%@AE@%%@NL@%
  13790. %@NL@%
  13791. %@AI@%stream%@AE@%                            Pointer to%@AB@% FILE structure%@AE@%
  13792.  
  13793. %@NL@%
  13794. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13795. %@NL@%
  13796. The %@AB@%feof%@AE@% routine (implemented as a macro) determines whether the end of
  13797. %@AI@%stream%@AE@% has been reached. Once the end of the file is reached, read
  13798. operations return an end-of-file indicator until the stream is closed or
  13799. until %@AB@%rewind%@AE@%, %@AB@%fsetpos%@AE@%, %@AB@%fseek%@AE@%, or %@AB@%clearerr%@AE@% is called against it.  %@NL@%
  13800. %@NL@%
  13801. %@NL@%
  13802. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13803. %@NL@%
  13804. The %@AB@%feof%@AE@% function returns a nonzero value after the first read operation
  13805. that attempts to read past the end of the file. It returns 0 if the current
  13806. position is not end-of-file. There is no error return.  %@NL@%
  13807. %@NL@%
  13808. %@NL@%
  13809. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13810. %@NL@%
  13811. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13812. %@NL@%
  13813. %@NL@%
  13814. %@NL@%
  13815. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13816. %@NL@%
  13817. %@AB@%clearerr%@AE@%, %@AB@%eof%@AE@%, %@AB@%ferror%@AE@%, %@AB@%perror%@AE@%  %@NL@%
  13818. %@NL@%
  13819. %@NL@%
  13820. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13821. %@NL@%
  13822. %@AS@%  /* FEOF.C: This program uses feof to indicate when it reaches the end
  13823. %@AS@%   * of the file FEOF.C. It also checks for errors with ferror.
  13824. %@AS@%   */
  13825. %@AS@%  
  13826. %@AS@%  #include <stdio.h>
  13827. %@AS@%  #include <stdlib.h>
  13828. %@AS@%  
  13829. %@AS@%  void main()
  13830. %@AS@%  {
  13831. %@AS@%     int  count, total = 0;
  13832. %@AS@%     char buffer[100];
  13833. %@AS@%     FILE *stream;
  13834. %@AS@%  
  13835. %@AS@%     if( (stream = fopen( "feof.c", "r" )) == NULL )
  13836. %@AS@%        exit( 1 );%@AE@%%@NL@%
  13837. %@NL@%
  13838. %@AS@%  /* Cycle until end of file reached: */
  13839. %@AS@%     while( !feof( stream ) )
  13840. %@AS@%     {
  13841. %@AS@%        /* Attempt to read in 10 bytes: */
  13842. %@AS@%        count = fread( buffer, sizeof( char ), 100, stream );
  13843. %@AS@%        if( ferror( stream ) )
  13844. %@AS@%        {
  13845. %@AS@%           perror( "Read error" );
  13846. %@AS@%           break;
  13847. %@AS@%        }
  13848. %@AS@%  
  13849. %@AS@%        /* Total up actual bytes read */
  13850. %@AS@%        total += count;
  13851. %@AS@%     }
  13852. %@AS@%     printf( "Number of bytes read = %d\n", total );
  13853. %@AS@%     fclose( stream );
  13854. %@AS@%  }%@AE@%%@NL@%
  13855. %@NL@%
  13856. %@NL@%
  13857. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13858. %@NL@%
  13859. %@AS@%  
  13860. %@AS@%  
  13861. %@AS@%  Number of bytes read = 697%@AE@%%@NL@%
  13862. %@NL@%
  13863. %@NL@%
  13864. %@NL@%
  13865. %@NL@%
  13866. %@QR:ferror@%%@NL@%
  13867. %@2@%%@CR:C6A00960493 @%%@AB@%ferror%@AE@%%@EH@%%@NL@%
  13868. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13869. %@NL@%
  13870. %@NL@%
  13871. %@3@%%@AB@%Description%@CR:C6A00960494 @%%@CR:C6A00960495 @%%@AE@%%@EH@%%@NL@%
  13872. %@NL@%
  13873. Tests for an error on a stream.  %@NL@%
  13874. %@NL@%
  13875. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13876. %@NL@%
  13877. %@AS@%  int ferror( FILE *stream );%@AE@%%@NL@%
  13878. %@NL@%
  13879. %@AI@%stream%@AE@%                            Pointer to%@AB@% FILE structure%@AE@%
  13880.  
  13881. %@NL@%
  13882. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13883. %@NL@%
  13884. The %@AB@%ferror%@AE@% routine (implemented as a macro) tests for a reading or writing
  13885. error on the file associated with %@AI@%stream%@AE@%. If an error has occurred, the
  13886. error indicator for the stream remains set until the stream is closed or
  13887. rewound, or until %@AB@%clearerr%@AE@% is called against it. %@CR:C6A00960496 @%  %@NL@%
  13888. %@NL@%
  13889. %@NL@%
  13890. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13891. %@NL@%
  13892. If no error has occurred on %@AI@%stream%@AE@%, %@AB@%ferror%@AE@% returns 0. Otherwise, it returns
  13893. a nonzero value.  %@NL@%
  13894. %@NL@%
  13895. %@NL@%
  13896. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13897. %@NL@%
  13898. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13899. %@NL@%
  13900. %@NL@%
  13901. %@NL@%
  13902. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13903. %@NL@%
  13904. %@AB@%clearerr%@AE@%, %@AB@%eof%@AE@%, %@AB@%feof%@AE@%, %@AB@%fopen%@AE@%, %@AB@%perror%@AE@%  %@NL@%
  13905. %@NL@%
  13906. %@NL@%
  13907. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  13908. %@NL@%
  13909. %@AS@%  /* FEOF.C: This program uses feof to indicate when it reaches the end
  13910. %@AS@%   * of the file FEOF.C. It also checks for errors with ferror.
  13911. %@AS@%   */
  13912. %@AS@%  
  13913. %@AS@%  #include <stdio.h>
  13914. %@AS@%  #include <stdlib.h>
  13915. %@AS@%  
  13916. %@AS@%  void main()
  13917. %@AS@%  {
  13918. %@AS@%     int  count, total = 0;
  13919. %@AS@%     char buffer[100];
  13920. %@AS@%     FILE *stream;
  13921. %@AS@%  
  13922. %@AS@%     if( (stream = fopen( "feof.c", "r" )) == NULL )
  13923. %@AS@%        exit( 1 );%@AE@%%@NL@%
  13924. %@NL@%
  13925. %@AS@%  /* Cycle until end of file reached: */
  13926. %@AS@%     while( !feof( stream ) )
  13927. %@AS@%     {
  13928. %@AS@%        /* Attempt to read in 10 bytes: */
  13929. %@AS@%        count = fread( buffer, sizeof( char ), 100, stream );
  13930. %@AS@%        if( ferror( stream ) )
  13931. %@AS@%        {
  13932. %@AS@%           perror( "Read error" );
  13933. %@AS@%           break;
  13934. %@AS@%        }
  13935. %@AS@%  
  13936. %@AS@%        /* Total up actual bytes read */
  13937. %@AS@%        total += count;
  13938. %@AS@%     }
  13939. %@AS@%     printf( "Number of bytes read = %d\n", total );
  13940. %@AS@%     fclose( stream );
  13941. %@AS@%  }%@AE@%%@NL@%
  13942. %@NL@%
  13943. %@NL@%
  13944. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  13945. %@NL@%
  13946. %@AS@%  
  13947. %@AS@%  
  13948. %@AS@%  Number of bytes read = 697%@AE@%%@NL@%
  13949. %@NL@%
  13950. %@NL@%
  13951. %@NL@%
  13952. %@NL@%
  13953. %@QR:fflush@%%@NL@%
  13954. %@2@%%@CR:C6A00970497 @%%@AB@%fflush%@AE@%%@EH@%%@NL@%
  13955. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  13956. %@NL@%
  13957. %@NL@%
  13958. %@3@%%@AB@%Description%@CR:C6A00970498 @%%@CR:C6A00970499 @%%@CR:C6A00970500 @% %@CR:C6A00970501 @%%@AE@%%@EH@%%@NL@%
  13959. %@NL@%
  13960. Flushes a stream.  %@NL@%
  13961. %@NL@%
  13962. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  13963. %@NL@%
  13964. %@AS@%  int fflush( FILE *stream );%@AE@%%@NL@%
  13965. %@NL@%
  13966. %@AI@%stream%@AE@%                            Pointer to%@AB@% FILE structure%@AE@%
  13967.  
  13968. %@NL@%
  13969. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  13970. %@NL@%
  13971. If the file associated with %@AI@%stream%@AE@% is open for output, %@AB@%fflush%@AE@% writes to that
  13972. file the contents of the buffer associated with the stream. If the stream is
  13973. open for input, %@AB@%fflush%@AE@% clears the contents of the buffer. The %@AB@%fflush%@AE@%
  13974. function negates the effect of any prior call to %@AB@%ungetc%@AE@% against %@AI@%stream%@AE@%.  %@NL@%
  13975. %@NL@%
  13976. Buffers are automatically flushed when they are full, when the stream is
  13977. closed, or when a program terminates normally without closing the stream.  %@NL@%
  13978. %@NL@%
  13979. The stream remains open after the call. The %@AB@%fflush%@AE@% function has no effect on
  13980. an unbuffered stream.  %@NL@%
  13981. %@NL@%
  13982. %@NL@%
  13983. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  13984. %@NL@%
  13985. The %@AB@%fflush%@AE@% function returns the value 0 if the buffer was successfully
  13986. flushed. The value 0 is also returned in cases in which the specified stream
  13987. has no buffer or is open for reading only. A return value of %@AB@%EOF%@AE@% indicates
  13988. an error.  %@NL@%
  13989. %@NL@%
  13990. %@NL@%
  13991. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  13992. %@NL@%
  13993. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  13994. %@NL@%
  13995. %@NL@%
  13996. %@NL@%
  13997. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  13998. %@NL@%
  13999. %@AB@%fclose%@AE@%, %@AB@%flushall%@AE@%, %@AB@%setbuf%@AE@%  %@NL@%
  14000. %@NL@%
  14001. %@NL@%
  14002. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14003. %@NL@%
  14004. %@AS@%  /* FFLUSH.C */
  14005. %@AS@%  #include <stdio.h>
  14006. %@AS@%  #include <conio.h>
  14007. %@AS@%  
  14008. %@AS@%  void main()
  14009. %@AS@%  {
  14010. %@AS@%     int integer;
  14011. %@AS@%     char string[81];%@AE@%%@NL@%
  14012. %@NL@%
  14013. %@AS@%  /* Read each word as a string. */
  14014. %@AS@%     printf( "Enter a sentence of four words with scanf: " );
  14015. %@AS@%     for( integer = 0; integer < 4; integer++ )
  14016. %@AS@%     {
  14017. %@AS@%        scanf( "%s", string );
  14018. %@AS@%        printf( "%s\n", string );
  14019. %@AS@%     }
  14020. %@AS@%  
  14021. %@AS@%     /* You must flush the input buffer before using gets. */
  14022. %@AS@%     fflush( stdin );
  14023. %@AS@%     printf( "Enter the same sentence with gets: " );
  14024. %@AS@%     gets( string );
  14025. %@AS@%     printf( "%s\n", string );
  14026. %@AS@%  }%@AE@%%@NL@%
  14027. %@NL@%
  14028. %@NL@%
  14029. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14030. %@NL@%
  14031. %@AS@%  
  14032. %@AS@%  
  14033. %@AS@%  Enter a sentence of four words with scanf: This is a test
  14034. %@AS@%  This
  14035. %@AS@%  is
  14036. %@AS@%  a
  14037. %@AS@%  test
  14038. %@AS@%  Enter the same sentence with gets: This is a test
  14039. %@AS@%  This is a test%@AE@%%@NL@%
  14040. %@NL@%
  14041. %@NL@%
  14042. %@NL@%
  14043. %@NL@%
  14044. %@QR:fgetc@%%@QR:fgetchar@%%@NL@%
  14045. %@2@%%@CR:C6A00980502 @%%@AB@%fgetc, fgetchar%@AE@%%@EH@%%@NL@%
  14046. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14047. %@NL@%
  14048. %@NL@%
  14049. %@3@%%@AB@%Description%@CR:C6A00980503 @%%@CR:C6A00980504 @% %@CR:C6A00980505 @% %@CR:C6A00980506 @% %@CR:C6A00980507 @%%@CR:C6A00980508 @%%@AE@%%@EH@%%@NL@%
  14050. %@NL@%
  14051. Read a character from a stream (%@AB@%fgetc%@AE@%) or %@AB@%stdin (fgetchar%@AE@%).  %@NL@%
  14052. %@NL@%
  14053. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14054. %@NL@%
  14055. %@AS@%  int fgetc( FILE *stream );%@AE@%%@NL@%
  14056. %@NL@%
  14057. %@AS@%  int fgetchar( void ); %@AE@%%@NL@%
  14058. %@NL@%
  14059. %@AI@%stream %@AE@%                           Pointer to %@AB@%FILE%@AE@% structure
  14060.  
  14061. %@NL@%
  14062. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14063. %@NL@%
  14064. The %@AB@%fgetc%@AE@% function reads a single character from the current position of the
  14065. file associated with %@AI@%stream%@AE@%. The character is converted and returned as an%@AB@%
  14066. %@AB@%int%@AE@%. The function then increments the associated file pointer (if any) to
  14067. point to the next character. The %@AB@%fgetchar%@AE@% function is equivalent to
  14068. %@AB@%fgetc(stdin)%@AE@%.  %@NL@%
  14069. %@NL@%
  14070. The %@AB@%fgetc%@AE@% and %@AB@%fgetchar%@AE@% routines are identical to %@AB@%getc%@AE@% and %@AB@%getchar%@AE@%, but they
  14071. are functions rather than macros.  %@NL@%
  14072. %@NL@%
  14073. %@NL@%
  14074. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14075. %@NL@%
  14076. The %@AB@%fgetc%@AE@% and %@AB@%fgetchar%@AE@% functions return the character read. They return %@AB@%EOF%@AE@%
  14077. to indicate an error or end-of-file. Use %@AB@%feof%@AE@% or %@AB@%ferror%@AE@% to distinguish
  14078. between an error and an end-of-file condition.  %@NL@%
  14079. %@NL@%
  14080. %@NL@%
  14081. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14082. %@NL@%
  14083. %@AB@%fgetc%@AE@%  %@NL@%
  14084. %@NL@%
  14085. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  14086. %@NL@%
  14087. %@NL@%
  14088. %@AB@%fgetchar%@AE@%  %@NL@%
  14089. %@NL@%
  14090.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14091. %@NL@%
  14092. %@NL@%
  14093. %@NL@%
  14094. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14095. %@NL@%
  14096. %@AB@%fputc%@AE@%, %@AB@%fputchar%@AE@%, %@AB@%getc%@AE@%, %@AB@%getchar%@AE@%  %@NL@%
  14097. %@NL@%
  14098. %@NL@%
  14099. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14100. %@NL@%
  14101. %@AS@%  /* FGETC.C: This program uses getc to read the first 80 input characters
  14102. %@AS@%   * (or until the end of input) and place them into a string named buffer.
  14103. %@AS@%   */
  14104. %@AS@%  
  14105. %@AS@%  #include <stdio.h>
  14106. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  14107. %@NL@%
  14108. %@AS@%  void main()
  14109. %@AS@%  {
  14110. %@AS@%     FILE *stream;
  14111. %@AS@%     char buffer[81];
  14112. %@AS@%     int  i, ch;
  14113. %@AS@%  
  14114. %@AS@%     /* Open file to read line from: */
  14115. %@AS@%     if( (stream = fopen( "fgetc.c", "r" )) == NULL )
  14116. %@AS@%        exit( 0 );
  14117. %@AS@%  
  14118. %@AS@%     /* Read in first 80 characters and place them in "buffer": */
  14119. %@AS@%     ch = fgetc( stream );
  14120. %@AS@%     for( i=0; (i < 80 ) && ( feof( stream ) == 0 ); i++ )
  14121. %@AS@%     {
  14122. %@AS@%        buffer[i] = ch;
  14123. %@AS@%        ch = fgetc( stream );
  14124. %@AS@%     }
  14125. %@AS@%     /* Add null to end string */
  14126. %@AS@%     buffer[i] = '\0';
  14127. %@AS@%     printf( "%s\n", buffer );
  14128. %@AS@%     fclose( stream );
  14129. %@AS@%  }%@AE@%%@NL@%
  14130. %@NL@%
  14131. %@NL@%
  14132. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14133. %@NL@%
  14134. %@AS@%  
  14135. %@AS@%  
  14136. %@AS@%  /* FGETC.C: This program uses getc to read the first 80 input characters
  14137. %@AS@%  /* (or%@AE@%%@NL@%
  14138. %@NL@%
  14139. %@AS@%  %@AE@%%@NL@%
  14140. %@NL@%
  14141. %@NL@%
  14142. %@NL@%
  14143. %@NL@%
  14144. %@QR:fgetpos@%%@NL@%
  14145. %@2@%%@CR:C6A00990509 @%%@AB@%fgetpos%@AE@%%@EH@%%@NL@%
  14146. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14147. %@NL@%
  14148. %@NL@%
  14149. %@3@%%@AB@%Description%@CR:C6A00990510 @%%@CR:C6A00990511 @% %@CR:C6A00990512 @%%@CR:C6A00990513 @% %@CR:C6A00990514 @%%@CR:C6A00990515 @%%@AE@%%@EH@%%@NL@%
  14150. %@NL@%
  14151. Gets a stream's file-position indicator.  %@NL@%
  14152. %@NL@%
  14153. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14154. %@NL@%
  14155. %@AS@%  int fgetpos( FILE *stream, fpos_t *pos );%@AE@%%@NL@%
  14156. %@NL@%
  14157. %@AI@%stream%@AE@%                            Target stream
  14158.  
  14159. %@AI@%pos%@AE@%                               Position-indicator storage
  14160.  
  14161. %@NL@%
  14162. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14163. %@NL@%
  14164. The %@AB@%fgetpos%@AE@% function gets the current value of the %@AI@%stream%@AE@% argument's
  14165. file-position indicator and stores it in the object pointed to by %@AI@%pos%@AE@%. The
  14166. %@AB@%fsetpos%@AE@% function can later use information stored in %@AI@%pos%@AE@% to reset the %@AI@%stream%@AE@%
  14167. argument's pointer to its position at the time %@AB@%fgetpos%@AE@% was called.  %@NL@%
  14168. %@NL@%
  14169. The %@AI@%pos %@AE@%value is stored in an internal format and is intended for use only
  14170. by the %@AB@%fgetpos%@AE@% and %@AB@%fsetpos%@AE@% functions.  %@NL@%
  14171. %@NL@%
  14172. %@NL@%
  14173. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14174. %@NL@%
  14175. If successful, the %@AB@%fgetpos%@AE@% function returns 0. On failure, it returns a
  14176. nonzero value and sets %@AB@%errno%@AE@% to one of the following manifest constants
  14177. (defined in STDIO.H):  %@NL@%
  14178. %@NL@%
  14179. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  14180. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14181. %@AB@%EBADF%@AE@%                             The specified stream is not a valid file
  14182.                                   handle or is not 
  14183.                                   accessible.
  14184.  
  14185. %@AB@%EINVAL%@AE@%                            The %@AI@%stream%@AE@% value is invalid.
  14186.  
  14187. %@NL@%
  14188. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14189. %@NL@%
  14190. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14191. %@NL@%
  14192. %@NL@%
  14193. %@NL@%
  14194. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14195. %@NL@%
  14196. %@AB@%fsetpos%@AE@%  %@NL@%
  14197. %@NL@%
  14198. %@NL@%
  14199. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14200. %@NL@%
  14201. %@AS@%  /* FGETPOS.C: This program opens a file and reads bytes at several
  14202. %@AS@%   * different locations.
  14203. %@AS@%   */
  14204. %@AS@%  
  14205. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14206. %@NL@%
  14207. %@AS@%  void main()
  14208. %@AS@%  {
  14209. %@AS@%     FILE   *stream;
  14210. %@AS@%     fpos_t pos;
  14211. %@AS@%     int    val;
  14212. %@AS@%     char   buffer[20];
  14213. %@AS@%  
  14214. %@AS@%     if( (stream = fopen( "fgetpos.c", "rb" )) == NULL )
  14215. %@AS@%        printf( "Trouble opening file\n" );
  14216. %@AS@%     else
  14217. %@AS@%     {
  14218. %@AS@%        /* Read some data and then check the position. */
  14219. %@AS@%        fread( buffer, sizeof( char ), 10, stream );
  14220. %@AS@%        if( fgetpos( stream, &pos ) != 0 )
  14221. %@AS@%           perror( "fgetpos error" );
  14222. %@AS@%        else
  14223. %@AS@%        {
  14224. %@AS@%           fread( buffer, sizeof( char ), 10, stream );
  14225. %@AS@%           printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );
  14226. %@AS@%        }
  14227. %@AS@%  
  14228. %@AS@%        /* Set a new position and read more data */
  14229. %@AS@%        pos = 140;
  14230. %@AS@%        if( fsetpos( stream, &pos ) != 0 )
  14231. %@AS@%           perror( "fsetpos error" );
  14232. %@AS@%  
  14233. %@AS@%        fread( buffer, sizeof( char ), 10, stream );
  14234. %@AS@%           printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );
  14235. %@AS@%  
  14236. %@AS@%        fclose( stream );
  14237. %@AS@%     }
  14238. %@AS@%  }%@AE@%%@NL@%
  14239. %@NL@%
  14240. %@NL@%
  14241. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14242. %@NL@%
  14243. %@AS@%  
  14244. %@AS@%  
  14245. %@AS@%  10 bytes at byte 10: .C: This p
  14246. %@AS@%  10 bytes at byte 140:   FILE   *%@AE@%%@NL@%
  14247. %@NL@%
  14248. %@NL@%
  14249. %@NL@%
  14250. %@NL@%
  14251. %@QR:fgets@%%@NL@%
  14252. %@2@%%@CR:C6A01000516 @%%@AB@%fgets%@AE@%%@EH@%%@NL@%
  14253. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14254. %@NL@%
  14255. %@NL@%
  14256. %@3@%%@AB@%Description%@CR:C6A01000517 @%%@CR:C6A01000518 @% %@CR:C6A01000519 @%%@CR:C6A01000520 @%%@CR:C6A01000521 @%%@AE@%%@EH@%%@NL@%
  14257. %@NL@%
  14258. Gets a string from a stream.  %@NL@%
  14259. %@NL@%
  14260. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14261. %@NL@%
  14262. %@AS@%  char *fgets( char *string, int n, FILE *stream );%@AE@%%@NL@%
  14263. %@NL@%
  14264. %@AI@%string%@AE@%                            Storage location for data
  14265.  
  14266. %@AI@%n%@AE@%                                 Number of characters stored
  14267.  
  14268. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE %@AE@%structure
  14269.  
  14270. %@NL@%
  14271. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14272. %@NL@%
  14273. The %@AB@%fgets%@AE@% function reads a string from the input %@AI@%stream%@AE@% argument and stores
  14274. it in %@AI@%string%@AE@%. Characters are read from the current stream position up to and
  14275. including the first newline character (%@AB@%'\n'%@AE@%), up to the end of the stream,
  14276. or until the number of characters read is equal to %@AI@%n%@AE@% - 1, whichever comes
  14277. first. The result is stored in %@AI@%string%@AE@%, and a null character (%@AB@%'\0'%@AE@%) is
  14278. appended. The newline character, if read, is included in the string. If %@AI@%n%@AE@% is
  14279. equal to 1, %@AI@%string%@AE@% is empty (""). The %@AB@%fgets%@AE@% function is similar to the %@AB@%gets%@AE@%
  14280. function; however, %@AB@%gets%@AE@% replaces the newline character with %@AB@%NULL%@AE@%.  %@NL@%
  14281. %@NL@%
  14282. %@NL@%
  14283. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14284. %@NL@%
  14285. If successful, the %@AB@%fgets%@AE@% function returns %@AI@%string%@AE@%. It returns %@AB@%NULL%@AE@% to
  14286. indicate either an error or end-of-file condition. Use %@AB@%feof%@AE@% or %@AB@%ferror%@AE@% to
  14287. determine whether an error occurred.  %@NL@%
  14288. %@NL@%
  14289. %@NL@%
  14290. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14291. %@NL@%
  14292. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  14293. %@NL@%
  14294. %@NL@%
  14295. %@NL@%
  14296. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14297. %@NL@%
  14298. %@AB@%fputs%@AE@%, %@AB@%gets%@AE@%, %@AB@%puts%@AE@%  %@NL@%
  14299. %@NL@%
  14300. %@NL@%
  14301. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14302. %@NL@%
  14303. %@AS@%  /* FGETS.C: This program uses fgets to display a line from a file on the
  14304. %@AS@%   * screen.
  14305. %@AS@%   */
  14306. %@AS@%  
  14307. %@AS@%  #include <stdio.h>
  14308. %@AS@%  
  14309. %@AS@%  FILE *stream;
  14310. %@AS@%  
  14311. %@AS@%  void main()
  14312. %@AS@%  {
  14313. %@AS@%     char line[100], *result;%@AE@%%@NL@%
  14314. %@NL@%
  14315. %@AS@%  if( (stream = fopen( "fgets.c", "r" )) != NULL )
  14316. %@AS@%     {
  14317. %@AS@%        if( fgets( line, 100, stream ) == NULL)
  14318. %@AS@%           printf( "fgets error\n" );
  14319. %@AS@%        else
  14320. %@AS@%           printf( "%s", line);
  14321. %@AS@%        fclose( stream );
  14322. %@AS@%     }
  14323. %@AS@%  }%@AE@%%@NL@%
  14324. %@NL@%
  14325. %@NL@%
  14326. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14327. %@NL@%
  14328. %@AS@%  
  14329. %@AS@%  
  14330. %@AS@%  /* FGETS.C: This program uses fgets to display a line from a file on the%@AE@%%@NL@%
  14331. %@NL@%
  14332. %@NL@%
  14333. %@NL@%
  14334. %@NL@%
  14335. %@QR:fieeetomsbin@%%@QR:fmsbintoieee@%%@NL@%
  14336. %@2@%%@CR:C6A01010522 @%%@AB@%fieeetomsbin, fmsbintoieee%@AE@%%@EH@%%@NL@%
  14337. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14338. %@NL@%
  14339. %@NL@%
  14340. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  14341. %@NL@%
  14342. Convert floating-point numbers between IEEE and Microsoft binary formats.  %@NL@%
  14343. %@NL@%
  14344. %@AS@%  #include <math.h>%@AE@%%@NL@%
  14345. %@NL@%
  14346. %@AS@%  int fieeetomsbin( float *src4,  float *dst4 );%@AE@%%@NL@%
  14347. %@NL@%
  14348. %@AS@%  int fmsbintoieee(  float *src4,  float *dst4 );%@AE@%%@NL@%
  14349. %@NL@%
  14350. %@AI@%scr4 %@AE@%                             Value to be converted
  14351.  
  14352. %@AI@%dst4 %@AE@%                             Converted value
  14353.  
  14354. %@NL@%
  14355. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14356. %@NL@%
  14357. The %@AB@%fieeetomsbin%@AE@% routine converts a single-precision floating-point number
  14358. in IEEE (Institute of Electrical and Electronic Engineers) format to
  14359. Microsoft (MS) binary format.  %@NL@%
  14360. %@NL@%
  14361. The %@AB@%fmsbintoieee%@AE@% routine converts a floating-point number in Microsoft
  14362. binary format to IEEE format.  %@NL@%
  14363. %@NL@%
  14364. These routines allow C programs (which store floating-point numbers in the
  14365. IEEE format) to use numeric data in random-access data files created with
  14366. Microsoft BASIC (which stores floating-point numbers in the Microsoft binary
  14367. format), and vice versa.  %@NL@%
  14368. %@NL@%
  14369. The argument %@AI@%src4%@AE@% points to the %@AB@%float%@AE@% value to be converted. The result is
  14370. stored at the location given by %@AI@%dst4%@AE@%.  %@NL@%
  14371. %@NL@%
  14372. These routines do not handle IEEE NANs ("not a number") and infinities. IEEE
  14373. denormals are treated as 0 in the conversions.  %@NL@%
  14374. %@NL@%
  14375. %@NL@%
  14376. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14377. %@NL@%
  14378. These functions return 0 if the conversion is successful and 1 if the
  14379. conversion causes an overflow.  %@NL@%
  14380. %@NL@%
  14381. %@NL@%
  14382. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14383. %@NL@%
  14384.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14385. %@NL@%
  14386. %@NL@%
  14387. %@NL@%
  14388. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14389. %@NL@%
  14390. %@AB@%dieeetomsbin%@AE@%, %@AB@%dmsbintoieee%@AE@%  %@NL@%
  14391. %@NL@%
  14392. %@NL@%
  14393. %@NL@%
  14394. %@NL@%
  14395. %@QR:filelength@%%@NL@%
  14396. %@2@%%@CR:C6A01020523 @%%@AB@%filelength%@AE@%%@EH@%%@NL@%
  14397. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14398. %@NL@%
  14399. %@NL@%
  14400. %@3@%%@AB@%Description%@CR:C6A01020524 @%%@CR:C6A01020525 @% %@CR:C6A01020526 @%%@AE@%%@EH@%%@NL@%
  14401. %@NL@%
  14402. Gets the length of a file.  %@NL@%
  14403. %@NL@%
  14404. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  14405.  
  14406. %@AS@%  long filelength( int handle );%@AE@%%@NL@%
  14407. %@NL@%
  14408. %@AI@%handle%@AE@%                            Target file handle
  14409.  
  14410. %@NL@%
  14411. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14412. %@NL@%
  14413. The %@AB@%filelength%@AE@% function returns the length, in bytes, of the target file
  14414. associated with %@AI@%handle.%@AE@%  %@NL@%
  14415. %@NL@%
  14416. %@NL@%
  14417. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14418. %@NL@%
  14419. The %@AB@%filelength%@AE@% function returns the file length in bytes. A return value of
  14420. -1L indicates an error, and an invalid handle sets %@AB@%errno%@AE@% to %@AB@%EBADF%@AE@%.  %@NL@%
  14421. %@NL@%
  14422. %@NL@%
  14423. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14424. %@NL@%
  14425.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14426. %@NL@%
  14427. %@NL@%
  14428. %@NL@%
  14429. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14430. %@NL@%
  14431. %@AB@%chsize%@AE@%, %@AB@%fileno%@AE@%, %@AB@%fstat%@AE@%, %@AB@%stat%@AE@%  %@NL@%
  14432. %@NL@%
  14433. %@NL@%
  14434. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14435. %@NL@%
  14436. %@AS@%  /* CHSIZE.C: This program uses filelength to report the size of a
  14437. %@AS@%   * file before and after modifying it with chsize.
  14438. %@AS@%   */
  14439. %@AS@%  
  14440. %@AS@%  #include <io.h>
  14441. %@AS@%  #include <fcntl.h>
  14442. %@AS@%  #include <sys\types.h>
  14443. %@AS@%  #include <sys\stat.h>
  14444. %@AS@%  #include <stdio.h>
  14445. %@AS@%  
  14446. %@AS@%  void main()
  14447. %@AS@%  {
  14448. %@AS@%     int fh, result;
  14449. %@AS@%     unsigned int nbytes = BUFSIZ;%@AE@%%@NL@%
  14450. %@NL@%
  14451. %@AS@%  /* Open a file */
  14452. %@AS@%     if( (fh = open( "data", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 )
  14453. %@AS@%     {
  14454. %@AS@%        printf( "File length before: %ld\n", filelength( fh ) );
  14455. %@AS@%        if( chsize( fh, 329678 ) == 0 )
  14456. %@AS@%           printf( "Size successfully changed\n" );
  14457. %@AS@%        else
  14458. %@AS@%           printf( "Problem in changing the size\n" );
  14459. %@AS@%        printf( "File length after:  %ld\n", filelength( fh ) );
  14460. %@AS@%        close( fh );
  14461. %@AS@%     }
  14462. %@AS@%  }%@AE@%%@NL@%
  14463. %@NL@%
  14464. %@NL@%
  14465. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14466. %@NL@%
  14467. %@AS@%  
  14468. %@AS@%  
  14469. %@AS@%  File length before: 0
  14470. %@AS@%  Size successfully changed
  14471. %@AS@%  File length after:  329678%@AE@%%@NL@%
  14472. %@NL@%
  14473. %@NL@%
  14474. %@NL@%
  14475. %@NL@%
  14476. %@QR:fileno@%%@NL@%
  14477. %@2@%%@CR:C6A01030527 @%%@AB@%fileno%@AE@%%@EH@%%@NL@%
  14478. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14479. %@NL@%
  14480. %@NL@%
  14481. %@3@%%@AB@%Description%@CR:C6A01030528 @%%@CR:C6A01030529 @%%@CR:C6A01030530 @% %@CR:C6A01030531 @%%@AE@%%@EH@%%@NL@%
  14482. %@NL@%
  14483. Gets the file handle associated with a stream.  %@NL@%
  14484. %@NL@%
  14485. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14486. %@NL@%
  14487. %@AS@%  int fileno( FILE *stream );%@AE@%%@NL@%
  14488. %@NL@%
  14489. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  14490.  
  14491. %@NL@%
  14492. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14493. %@NL@%
  14494. The %@AB@%fileno%@AE@% routine returns the file handle currently associated with %@AI@%stream%@AE@%.
  14495. This routine is implemented as a macro.  %@NL@%
  14496. %@NL@%
  14497. %@NL@%
  14498. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14499. %@NL@%
  14500. The %@AB@%fileno%@AE@% routine returns the file handle. There is no error return. The
  14501. result is undefined if %@AI@%stream%@AE@% does not specify an open file.  %@NL@%
  14502. %@NL@%
  14503. %@NL@%
  14504. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14505. %@NL@%
  14506.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  14507. %@NL@%
  14508. %@NL@%
  14509. %@NL@%
  14510. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14511. %@NL@%
  14512. %@AB@%fdopen%@AE@%, %@AB@%filelength%@AE@%, %@AB@%fopen%@AE@%, %@AB@%freopen%@AE@%  %@NL@%
  14513. %@NL@%
  14514. %@NL@%
  14515. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14516. %@NL@%
  14517. %@AS@%  /* FILENO.C: This program uses fileno to obtain the file handle for
  14518. %@AS@%   * some standard C streams.
  14519. %@AS@%   */
  14520. %@AS@%  
  14521. %@AS@%  #include <stdio.h>
  14522. %@AS@%  
  14523. %@AS@%  void main()
  14524. %@AS@%  {
  14525. %@AS@%     printf( "The file handle for stdin is %d\n", fileno( stdin ) );
  14526. %@AS@%     printf( "The file handle for stdout is %d\n", fileno( stdout ) );
  14527. %@AS@%     printf( "The file handle for stderr is %d\n", fileno( stderr ) );
  14528. %@AS@%  }%@AE@%%@NL@%
  14529. %@NL@%
  14530. %@NL@%
  14531. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14532. %@NL@%
  14533. %@AS@%  
  14534. %@AS@%  
  14535. %@AS@%  The file handle for stdin is 0
  14536. %@AS@%  The file handle for stdout is 1
  14537. %@AS@%  The file handle for stderr is 2%@AE@%%@NL@%
  14538. %@NL@%
  14539. %@NL@%
  14540. %@NL@%
  14541. %@NL@%
  14542. %@QR:_floodfill@%%@QR:_floodfill_w@%%@NL@%
  14543. %@2@%%@CR:C6A01040532 @%%@AB@%_floodfill, _floodfill_w%@AE@%%@EH@%%@NL@%
  14544. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14545. %@NL@%
  14546. %@NL@%
  14547. %@3@%%@AB@%Description%@CR:C6A01040533 @%%@AE@%%@EH@%%@NL@%
  14548. %@NL@%
  14549. Fill an area of a display using the current color and fill mask  %@NL@%
  14550. %@NL@%
  14551. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  14552. %@NL@%
  14553. %@AS@%  short _far _floodfill( short x, short y, short boundary );%@AE@%%@NL@%
  14554. %@NL@%
  14555. %@AS@%  short _far _floodfill_w( double wx, double wy, short boundary );%@AE@%%@NL@%
  14556. %@NL@%
  14557. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Start point
  14558.  
  14559. %@AI@%wx%@AE@%, %@AI@%wy%@AE@%                            Start point
  14560.  
  14561. %@AI@%boundary%@AE@%                          Boundary color of area to be filled
  14562.  
  14563. %@NL@%
  14564. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14565. %@NL@%
  14566. The functions in the %@AB@%_floodfill%@AE@% family fill an area of the display, using
  14567. the current color and fill mask. The %@AB@%_floodfill%@AE@% routine begins filling at
  14568. the view-coordinate point (%@AI@%x%@AE@%, %@AI@%y%@AE@%). The %@AB@%_floodfill_w%@AE@% routine begins filling at
  14569. the window-coordinate point (%@AI@%wx%@AE@%, %@AI@%wy%@AE@%).  %@NL@%
  14570. %@NL@%
  14571. If this point lies inside the figure, the interior is filled; if it lies
  14572. outside the figure, the background is filled. The point must be inside or
  14573. outside the figure to be filled, not on the figure boundary itself. Filling
  14574. occurs in all directions, stopping at the color of %@AI@%boundary%@AE@%.  %@NL@%
  14575. %@NL@%
  14576. %@NL@%
  14577. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14578. %@NL@%
  14579. The %@AB@%_floodfill%@AE@% functions return a nonzero value if the fill is successful.
  14580. It returns 0 if the fill could not be completed, the starting point lies on
  14581. the %@AI@%boundary%@AE@% color, or the start point lies outside the clipping region.  %@NL@%
  14582. %@NL@%
  14583. %@NL@%
  14584. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14585. %@NL@%
  14586.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  14587. %@NL@%
  14588. %@NL@%
  14589. %@NL@%
  14590. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14591. %@NL@%
  14592. %@AB@%_ellipse%@AE@% functions, %@AB@% _getcolor%@AE@%, %@AB@% _getfillmask%@AE@%, %@AB@% _grstatus%@AE@%,%@AB@%  _pie%@AE@% functions, %@AB@%
  14593. %@AB@%_setfillmask%@AE@%, %@AB@%_setcliprgn%@AE@%, %@AB@% _setcolor%@AE@%  %@NL@%
  14594. %@NL@%
  14595. %@NL@%
  14596. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14597. %@NL@%
  14598. %@AS@%  /* FLOODFIL.C: This program draws a series of nested rectangles in
  14599. %@AS@%   * different colors, constantly changing the background color.
  14600. %@AS@%   */
  14601. %@AS@%  
  14602. %@AS@%  #include <conio.h>
  14603. %@AS@%  #include <stdlib.h>
  14604. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  14605. %@NL@%
  14606. %@AS@%  void main()
  14607. %@AS@%  {
  14608. %@AS@%     int loop;
  14609. %@AS@%     int xvar, yvar;
  14610. %@AS@%  
  14611. %@AS@%     /* find a valid graphics mode */
  14612. %@AS@%     if( !_setvideomode( _MAXCOLORMODE ) )
  14613. %@AS@%        exit( 1 );
  14614. %@AS@%  
  14615. %@AS@%     for( xvar = 163, loop = 0; xvar < 320; loop++, xvar += 3 )
  14616. %@AS@%     {
  14617. %@AS@%        _setcolor( loop % 16 );
  14618. %@AS@%        yvar = xvar * 5 / 8;
  14619. %@AS@%        _rectangle( _GBORDER, 320-xvar, 200-yvar, xvar, yvar );
  14620. %@AS@%        _setcolor( rand() % 16 );
  14621. %@AS@%        _floodfill( 0, 0, loop % 16 );
  14622. %@AS@%     }
  14623. %@AS@%     getch();
  14624. %@AS@%     _setvideomode( _DEFAULTMODE );
  14625. %@AS@%  }%@AE@%%@NL@%
  14626. %@NL@%
  14627. %@NL@%
  14628. %@NL@%
  14629. %@NL@%
  14630. %@QR:floor@%%@QR:floorl@%%@NL@%
  14631. %@2@%%@CR:C6A01050534 @%%@AB@%floor, floorl%@AE@%%@EH@%%@NL@%
  14632. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14633. %@NL@%
  14634. %@NL@%
  14635. %@3@%%@AB@%Description%@CR:C6A01050535 @%%@CR:C6A01050536 @%%@AE@%%@EH@%%@NL@%
  14636. %@NL@%
  14637. Calculate the floor of a value.  %@NL@%
  14638. %@NL@%
  14639. %@AS@%  #include <math.h>%@AE@%%@NL@%
  14640. %@NL@%
  14641. %@AS@%  double floor( double x );%@AE@%%@NL@%
  14642. %@NL@%
  14643. %@AS@%  long double floorl( long double x );%@AE@%%@NL@%
  14644. %@NL@%
  14645. %@AI@%x%@AE@%                                 Floating-point value
  14646.  
  14647. %@NL@%
  14648. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14649. %@NL@%
  14650. The %@AB@%floor%@AE@% and %@AB@%floorl%@AE@% functions return a floating-point value representing
  14651. the largest integer that is less than or equal to%@AB@% %@AE@%%@AI@%x%@AE@%.  %@NL@%
  14652. %@NL@%
  14653. The %@AB@%floorl%@AE@% function is the 80-bit counterpart, and it uses the 80-bit,
  14654. 10-byte coprocessor form of arguments and return values. See the reference
  14655. page on the long double functions for more details on this data type.  %@NL@%
  14656. %@NL@%
  14657. %@NL@%
  14658. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14659. %@NL@%
  14660. These functions return the floating-point result. There is no error return.
  14661. %@NL@%
  14662. %@NL@%
  14663. %@NL@%
  14664. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14665. %@NL@%
  14666. %@AB@%floor%@AE@%  %@NL@%
  14667. %@NL@%
  14668. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  14669. %@NL@%
  14670. %@NL@%
  14671. %@AB@%floorl%@AE@%  %@NL@%
  14672. %@NL@%
  14673.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14674. %@NL@%
  14675. %@NL@%
  14676. %@NL@%
  14677. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14678. %@NL@%
  14679. %@AB@%ceil%@AE@%, %@AB@%fmod%@AE@%  %@NL@%
  14680. %@NL@%
  14681. %@NL@%
  14682. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14683. %@NL@%
  14684. %@AS@%  /* FLOOR.C: This example displays the largest integers less than or equal
  14685. %@AS@%   * to the floating-point values 2.8 and -2.8. It then shows the smallest
  14686. %@AS@%   * integers greater than or equal to 2.8 and -2.8.
  14687. %@AS@%   */
  14688. %@AS@%  
  14689. %@AS@%  #include <math.h>
  14690. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14691. %@NL@%
  14692. %@AS@%  void main()
  14693. %@AS@%  {
  14694. %@AS@%     double y;
  14695. %@AS@%  
  14696. %@AS@%     y = floor( 2.8 );
  14697. %@AS@%     printf( "The floor of 2.8 is %f\n", y );
  14698. %@AS@%     y = floor( -2.8 );
  14699. %@AS@%     printf( "The floor of -2.8 is %f\n", y );
  14700. %@AS@%  
  14701. %@AS@%     y = ceil( 2.8 );
  14702. %@AS@%     printf( "The ceil of 2.8 is %f\n", y );
  14703. %@AS@%     y = ceil( -2.8 );
  14704. %@AS@%     printf( "The ceil of -2.8 is %f\n", y );
  14705. %@AS@%  }%@AE@%%@NL@%
  14706. %@NL@%
  14707. %@NL@%
  14708. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14709. %@NL@%
  14710. %@AS@%  
  14711. %@AS@%  
  14712. %@AS@%  The floor of 2.8 is 2.000000
  14713. %@AS@%  The floor of -2.8 is -3.000000
  14714. %@AS@%  The ceil of 2.8 is 3.000000
  14715. %@AS@%  The ceil of -2.8 is -2.000000%@AE@%%@NL@%
  14716. %@NL@%
  14717. %@NL@%
  14718. %@NL@%
  14719. %@NL@%
  14720. %@QR:flushall@%%@NL@%
  14721. %@2@%%@CR:C6A01060537 @%%@AB@%flushall%@AE@%%@EH@%%@NL@%
  14722. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14723. %@NL@%
  14724. %@NL@%
  14725. %@3@%%@AB@%Description%@CR:C6A01060538 @%%@CR:C6A01060539 @%%@CR:C6A01060540 @% %@CR:C6A01060541 @%%@AE@%%@EH@%%@NL@%
  14726. %@NL@%
  14727. Flushes all streams; clears all buffers.  %@NL@%
  14728. %@NL@%
  14729. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14730. %@NL@%
  14731. %@AS@%  int flushall( void );%@AE@%%@NL@%
  14732. %@NL@%
  14733. %@NL@%
  14734. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14735. %@NL@%
  14736. The %@AB@%flushall%@AE@% function writes to its associated files the contents of all
  14737. buffers associated with open output streams. All buffers associated with
  14738. open input streams are cleared of their current contents. The next read
  14739. operation (if there is one) then reads new data from the input files into
  14740. the buffers.  %@NL@%
  14741. %@NL@%
  14742. Buffers are automatically flushed when they are full, when streams are
  14743. closed, or when a program terminates normally without closing streams.  %@NL@%
  14744. %@NL@%
  14745. All streams remain open after the call to %@AB@%flushall%@AE@%.  %@NL@%
  14746. %@NL@%
  14747. %@NL@%
  14748. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14749. %@NL@%
  14750. The %@AB@%flushall%@AE@% function returns the number of open streams (input and output).
  14751. There is no error return.  %@NL@%
  14752. %@NL@%
  14753. %@NL@%
  14754. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14755. %@NL@%
  14756.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14757. %@NL@%
  14758. %@NL@%
  14759. %@NL@%
  14760. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14761. %@NL@%
  14762. %@AB@%fflush%@AE@%  %@NL@%
  14763. %@NL@%
  14764. %@NL@%
  14765. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14766. %@NL@%
  14767. %@AS@%  /* FLUSHALL.C: This program uses flushall to flush all open buffers. */
  14768. %@AS@%  
  14769. %@AS@%  #include <stdio.h>
  14770. %@AS@%  
  14771. %@AS@%  void main()
  14772. %@AS@%  {
  14773. %@AS@%     int numflushed;
  14774. %@AS@%  
  14775. %@AS@%     numflushed = flushall();
  14776. %@AS@%     printf( "There were %d streams flushed\n", numflushed );
  14777. %@AS@%  }%@AE@%%@NL@%
  14778. %@NL@%
  14779. %@NL@%
  14780. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14781. %@NL@%
  14782. %@AS@%  
  14783. %@AS@%  
  14784. %@AS@%  There were 3 streams flushed%@AE@%%@NL@%
  14785. %@NL@%
  14786. %@NL@%
  14787. %@NL@%
  14788. %@NL@%
  14789. %@QR:fmod@%%@QR:fmodl@%%@NL@%
  14790. %@2@%%@CR:C6A01070542 @%%@AB@%fmod, fmodl%@AE@%%@EH@%%@NL@%
  14791. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14792. %@NL@%
  14793. %@NL@%
  14794. %@3@%%@AB@%Description%@CR:C6A01070543 @%%@CR:C6A01070544 @%%@CR:C6A01070545 @%%@AE@%%@EH@%%@NL@%
  14795. %@NL@%
  14796. Calculates the floating-point remainder.  %@NL@%
  14797. %@NL@%
  14798. %@AS@%  #include <math.h>%@AE@%%@NL@%
  14799. %@NL@%
  14800. %@AS@%  double fmod( double x, double y );%@AE@%%@NL@%
  14801. %@NL@%
  14802. %@AS@%  long double fmodl( long double x, long double y );%@AE@%%@NL@%
  14803. %@NL@%
  14804. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Floating-point values
  14805.  
  14806. %@NL@%
  14807. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14808. %@NL@%
  14809. The %@AB@%fmod%@AE@% and %@AB@%fmodl%@AE@% functions calculate the floating-point remainder %@AI@%f%@AE@% of %@AI@%x%@AE@% /
  14810. %@AI@%y %@AE@% such that %@AI@%x%@AE@% = %@AI@%i %@AE@%* y + %@AI@%f%@AE@%, where %@AI@%i%@AE@% is an integer,  %@AI@%f%@AE@%  has the same sign as
  14811. %@AI@%x%@AE@%, and the absolute value of %@AI@% f%@AE@%  is less than the absolute value of %@AI@%y%@AE@%.  %@NL@%
  14812. %@NL@%
  14813. The %@AB@%fmodl%@AE@% function is the 80-bit counterpart; it uses the 80-bit, 10-byte
  14814. coprocessor form of arguments and return values. See the discussion of the
  14815. long double functions for more details on this data type.  %@NL@%
  14816. %@NL@%
  14817. %@NL@%
  14818. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14819. %@NL@%
  14820. These functions return the floating-point remainder. If %@AI@%y%@AE@% is 0, the function
  14821. returns 0.  %@NL@%
  14822. %@NL@%
  14823. %@NL@%
  14824. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14825. %@NL@%
  14826. %@AB@%fmod%@AE@%  %@NL@%
  14827. %@NL@%
  14828. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  14829. %@NL@%
  14830. %@NL@%
  14831. %@AB@%fmodl%@AE@%  %@NL@%
  14832. %@NL@%
  14833.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  14834. %@NL@%
  14835. %@NL@%
  14836. %@NL@%
  14837. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14838. %@NL@%
  14839. %@AB@%ceil%@AE@%, %@AB@%fabs%@AE@%, %@AB@%floor%@AE@%  %@NL@%
  14840. %@NL@%
  14841. %@NL@%
  14842. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14843. %@NL@%
  14844. %@AS@%  /* FMOD.C: This program displays a floating-point remainder. */
  14845. %@AS@%  
  14846. %@AS@%  #include <math.h>
  14847. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14848. %@NL@%
  14849. %@AS@%  void main()
  14850. %@AS@%  {
  14851. %@AS@%     double x = -10.0, y = 3.0, z;
  14852. %@AS@%  
  14853. %@AS@%     z = fmod( x, y );
  14854. %@AS@%     printf( "The remainder of %.2f / %.2f is %f\n", x, y, z );
  14855. %@AS@%  }%@AE@%%@NL@%
  14856. %@NL@%
  14857. %@NL@%
  14858. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  14859. %@NL@%
  14860. %@AS@%  
  14861. %@AS@%  
  14862. %@AS@%  The remainder of -10.00 / 3.00 is -1.000000%@AE@%%@NL@%
  14863. %@NL@%
  14864. %@NL@%
  14865. %@NL@%
  14866. %@NL@%
  14867. %@QR:fopen@%%@NL@%
  14868. %@2@%%@CR:C6A01080546 @%%@AB@%fopen%@AE@%%@EH@%%@NL@%
  14869. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14870. %@NL@%
  14871. %@NL@%
  14872. %@3@%%@AB@%Description%@CR:C6A01080547 @%%@CR:C6A01080548 @%%@CR:C6A01080549 @% %@CR:C6A01080550 @%%@CR:C6A01080551 @%%@CR:C6A01080552 @%%@CR:C6A01080553 @%%@AE@%%@EH@%%@NL@%
  14873. %@NL@%
  14874. Opens a file.  %@NL@%
  14875. %@NL@%
  14876. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14877. %@NL@%
  14878. %@AS@%  FILE *fopen( const char *filename, const char *mode );%@AE@%%@NL@%
  14879. %@NL@%
  14880. %@AI@%filename%@AE@%                          Path name of file
  14881.  
  14882. %@AI@%mode%@AE@%                              Type of access permitted
  14883.  
  14884. %@NL@%
  14885. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  14886. %@NL@%
  14887. The %@AB@%fopen%@AE@% function opens the file specified by %@AI@%filename%@AE@%. The character
  14888. string %@AI@%mode%@AE@% specifies the type of access requested for the file, as follows:
  14889. %@NL@%
  14890. %@NL@%
  14891. %@AB@%Type%@AE@%                              %@AB@%Description%@AE@%
  14892. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14893. %@AB@%"r"%@AE@%                               Opens for reading. If the file does not 
  14894.                                   exist or cannot be found, the %@AB@%fopen%@AE@% call
  14895.                                   will fail.
  14896.  
  14897. %@AB@%"w"%@AE@%                               Opens an empty file for writing. If the 
  14898.                                   given file exists, its contents are 
  14899.                                   destroyed. 
  14900.  
  14901. %@AB@%"a"%@AE@%                               Opens for writing at the end of the file
  14902.                                   (appending); creates the file first if 
  14903.                                   it doesn't exist.
  14904.  
  14905. %@AB@%"r+"%@AE@%                              Opens for both reading and writing. (The
  14906.                                   file must exist.)
  14907.  
  14908. %@AB@%"w+"%@AE@%                              Opens an empty file for both reading and
  14909.                                   writing. If the given file exists, its 
  14910.                                   contents are destroyed.
  14911.  
  14912. %@AB@%"a+"%@AE@%                              Opens for reading and appending; creates
  14913.                                   the file first if it doesn't exist.
  14914.  
  14915. When a file is opened with the %@AB@%"a"%@AE@% or %@AB@%"a+"%@AE@% access type, all write operations
  14916. occur at the end of the file. Although the file pointer can be repositioned
  14917. using %@AB@%fseek%@AE@% or%@AB@% rewind%@AE@%, the file pointer is always moved back to the end of
  14918. the file before any write operation is carried out. Thus, existing data
  14919. cannot be overwritten.  %@NL@%
  14920. %@NL@%
  14921. When the %@AB@%"r+"%@AE@%, %@AB@%"w+"%@AE@%, or %@AB@%"a+" %@AE@%access type is specified, both reading and
  14922. writing are allowed (the file is said to be open for "update"). However,
  14923. when you switch between reading and writing, there must be an intervening
  14924. %@AB@%fsetpos%@AE@%, %@AB@%fseek%@AE@%, or %@AB@%rewind%@AE@% operation. The current position can be specified
  14925. for the %@AB@%fsetpos%@AE@% or %@AB@%fseek%@AE@% operation, if desired.  %@NL@%
  14926. %@NL@%
  14927. In addition to the values listed above, one of the following characters can
  14928. be included in %@AI@%mode%@AE@% to specify the translation mode for newline characters: %@CR:C6A01080554 @%%@CR:C6A01080555 @%%@CR:C6A01080556 @%
  14929. %@NL@%
  14930. %@NL@%
  14931. %@AB@%Mode%@AE@%                              %@AB@%Meaning%@AE@%
  14932. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  14933. %@AB@%t%@AE@%                                 Open in text (translated) mode. In this 
  14934.                                   mode, carriage-return-line-feed (CR-LF) 
  14935.                                   combinations are translated into single 
  14936.                                   line feeds (LF) on input and LF 
  14937.                                   characters are translated to CR-LF 
  14938.                                   combinations on output. Also, CTRL+Z is 
  14939.                                   interpreted as an end-of-file character 
  14940.                                   on input. In files opened for reading or
  14941.                                   for reading/writing, %@AB@%fopen%@AE@% checks for a 
  14942.                                   CTRL+Z at the end of the file and 
  14943.                                   removes it, if possible. This is done 
  14944.                                   because using the %@AB@%fseek%@AE@% and %@AB@%ftell%@AE@% 
  14945.                                   functions to move within a file that 
  14946.                                   ends with a CTRL+Z may cause %@AB@%fseek%@AE@% to 
  14947.                                   behave improperly near the end of the 
  14948.                                   file.
  14949.  
  14950. %@AB@%b%@AE@%                                 Open in binary (untranslated) mode; the 
  14951.                                   above translations are suppressed.
  14952.  
  14953. If %@AB@%t%@AE@% or %@AB@%b%@AE@% is not given in %@AI@%mode%@AE@%, the translation mode is defined by the
  14954. default-mode variable %@AB@%_fmode%@AE@%. If %@AB@%t%@AE@% or %@AB@%b%@AE@% is prefixed to the argument, the
  14955. function will fail and return %@AB@%NULL%@AE@%.  %@NL@%
  14956. %@NL@%
  14957. See Section 2.7, "Input and Output," for a discussion of text and binary
  14958. modes.  %@NL@%
  14959. %@NL@%
  14960. %@NL@%
  14961. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  14962. %@NL@%
  14963. The %@AB@%fopen%@AE@% function returns a pointer to the open file. A null pointer value
  14964. indicates an error.  %@NL@%
  14965. %@NL@%
  14966. %@NL@%
  14967. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  14968. %@NL@%
  14969. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  14970. %@NL@%
  14971. %@NL@%
  14972. Note that the %@AB@%t%@AE@% option is not part of the ANSI standard for %@AB@%fopen%@AE@%; it is a
  14973. Microsoft extension and should not be used where ANSI portability is
  14974. desired.  %@NL@%
  14975. %@NL@%
  14976. %@NL@%
  14977. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  14978. %@NL@%
  14979. %@AB@%fclose%@AE@%, %@AB@%fcloseall%@AE@%, %@AB@%fdopen%@AE@%, %@AB@%ferror%@AE@%, %@AB@%fileno%@AE@%, %@AB@%freopen%@AE@%, %@AB@%open%@AE@%, %@AB@%setmode%@AE@%  %@NL@%
  14980. %@NL@%
  14981. %@NL@%
  14982. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  14983. %@NL@%
  14984. %@AS@%  /* FOPEN.C: This program opens files named "data" and "data2". It uses
  14985. %@AS@%   * fclose to close "data" and fcloseall to close all remaining files.
  14986. %@AS@%   */
  14987. %@AS@%  
  14988. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  14989. %@NL@%
  14990. %@AS@%  FILE *stream, *stream2;
  14991. %@AS@%  
  14992. %@AS@%  void main()
  14993. %@AS@%  {
  14994. %@AS@%     int numclosed;
  14995. %@AS@%  
  14996. %@AS@%     /* Open for read (will fail if 'data' does not exist) */
  14997. %@AS@%     if( (stream  = fopen( "data", "r" )) == NULL )
  14998. %@AS@%        printf( "The file 'data' was not opened\n" );
  14999. %@AS@%     else
  15000. %@AS@%        printf( "The file 'data' was opened\n" );
  15001. %@AS@%  
  15002. %@AS@%     /* Open for write */
  15003. %@AS@%     if( (stream2 = fopen( "data2", "w+" )) == NULL )
  15004. %@AS@%        printf( "The file 'data2' was not opened\n" );
  15005. %@AS@%     else
  15006. %@AS@%        printf( "The file 'data2' was opened\n" );
  15007. %@AS@%  
  15008. %@AS@%     /* Close stream */
  15009. %@AS@%     if( fclose( stream ) )
  15010. %@AS@%        printf( "The file 'data' was not closed\n" );
  15011. %@AS@%  
  15012. %@AS@%     /* All other files are closed: */
  15013. %@AS@%     numclosed = fcloseall( );
  15014. %@AS@%     printf( "Number of files closed by fcloseall: %u\n", numclosed );
  15015. %@AS@%  }%@AE@%%@NL@%
  15016. %@NL@%
  15017. %@NL@%
  15018. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15019. %@NL@%
  15020. %@AS@%  
  15021. %@AS@%  
  15022. %@AS@%  The file 'data' was opened
  15023. %@AS@%  The file 'data2' was opened
  15024. %@AS@%  Number of files closed by fcloseall: 1%@AE@%%@NL@%
  15025. %@NL@%
  15026. %@NL@%
  15027. %@NL@%
  15028. %@NL@%
  15029. %@QR:FP_OFF@%%@QR:FP_SEG@%%@NL@%
  15030. %@2@%%@CR:C6A01090557 @%%@AB@%FP_OFF, FP_SEG%@AE@%%@EH@%%@NL@%
  15031. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15032. %@NL@%
  15033. %@NL@%
  15034. %@3@%%@AB@%Description%@CR:C6A01090558 @%%@CR:C6A01090559 @%%@CR:C6A01090560 @%%@AE@%%@EH@%%@NL@%
  15035. %@NL@%
  15036. Get or set a far-pointer offset (%@AB@%FP_OFF%@AE@%) or a far-pointer segment (%@AB@%FP_SEG%@AE@%).
  15037. %@NL@%
  15038. %@NL@%
  15039. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  15040. %@NL@%
  15041. %@AS@%  unsigned FP_OFF( void _far *address );%@AE@%%@NL@%
  15042. %@NL@%
  15043. %@AS@%  unsigned FP_SEG( void _far *address );%@AE@%%@NL@%
  15044. %@NL@%
  15045. %@AI@%address%@AE@%                           Far pointer to memory address
  15046.  
  15047. %@NL@%
  15048. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15049. %@NL@%
  15050. The %@AB@%FP_OFF%@AE@% and %@AB@%FP_SEG%@AE@% macros can be used to set or get the offset and
  15051. segment, respectively, of the far pointer at %@AI@%address%@AE@%.  %@NL@%
  15052. %@NL@%
  15053. %@NL@%
  15054. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15055. %@NL@%
  15056. The %@AB@%FP_OFF%@AE@% macro returns an offset. The %@AB@%FP_SEG%@AE@% macro returns a segment
  15057. address.  %@NL@%
  15058. %@NL@%
  15059. %@NL@%
  15060. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15061. %@NL@%
  15062.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  15063. %@NL@%
  15064. %@NL@%
  15065. %@NL@%
  15066. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15067. %@NL@%
  15068. %@AS@%  /* FP_SEG.C: This program uses FP_SEG and FP_OFF to obtain
  15069. %@AS@%   * the segment and offset of the long pointer p.
  15070. %@AS@%   */
  15071. %@AS@%  
  15072. %@AS@%  #include <dos.h>
  15073. %@AS@%  #include <malloc.h>
  15074. %@AS@%  #include <stdio.h>
  15075. %@AS@%  
  15076. %@AS@%  
  15077. %@AS@%  void main()
  15078. %@AS@%  {
  15079. %@AS@%     void _far *p;
  15080. %@AS@%     unsigned int seg_val;
  15081. %@AS@%     unsigned int off_val;
  15082. %@AS@%  
  15083. %@AS@%     p = _fmalloc( 100 );        /* Points pointer at something */
  15084. %@AS@%  
  15085. %@AS@%     seg_val = FP_SEG( p );      /* Gets address pointed to */
  15086. %@AS@%     off_val = FP_OFF( p );
  15087. %@AS@%  
  15088. %@AS@%     printf( "Segment is %.4X; Offset is %.4X\n", seg_val, off_val );
  15089. %@AS@%  }%@AE@%%@NL@%
  15090. %@NL@%
  15091. %@NL@%
  15092. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15093. %@NL@%
  15094. %@AS@%  
  15095. %@AS@%  
  15096. %@AS@%  Segment is 00C7; Offset is 0016%@AE@%%@NL@%
  15097. %@NL@%
  15098. %@NL@%
  15099. %@NL@%
  15100. %@NL@%
  15101. %@QR:_fpreset@%%@NL@%
  15102. %@2@%%@CR:C6A01100561 @%%@AB@%_fpreset%@AE@%%@EH@%%@NL@%
  15103. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15104. %@NL@%
  15105. %@NL@%
  15106. %@3@%%@AB@%Description%@CR:C6A01100562 @%%@CR:C6A01100563 @% %@CR:C6A01100564 @%%@CR:C6A01100565 @%%@AE@%%@EH@%%@NL@%
  15107. %@NL@%
  15108. Resets the floating-point package.  %@NL@%
  15109. %@NL@%
  15110. %@AS@%  #include <float.h>%@AE@%%@NL@%
  15111. %@NL@%
  15112. %@AS@%  void _fpreset( void );%@AE@%%@NL@%
  15113. %@NL@%
  15114. %@NL@%
  15115. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15116. %@NL@%
  15117. The %@AB@%_fpreset%@AE@% function reinitializes the floating-point-math package. This
  15118. function is usually used in conjunction with %@AB@%signal%@AE@%, %@AB@%system%@AE@%, or the %@AB@%exec%@AE@% or
  15119. %@AB@%spawn%@AE@% functions.  %@NL@%
  15120. %@NL@%
  15121. If a program traps floating-point error signals (%@AB@%SIGFPE%@AE@%) with %@AB@%signal%@AE@%, it can
  15122. safely recover from floating-point errors by invoking %@AB@%_fpreset%@AE@% and using
  15123. %@AB@%longjmp%@AE@%.  %@NL@%
  15124. %@NL@%
  15125. In DOS versions prior to 3.0, a child process executed by %@AB@%exec%@AE@%, %@AB@%spawn%@AE@%, or
  15126. %@AB@%system%@AE@% may affect the floating-point state of the parent process if an 8087
  15127. or 80287 coprocessor is used. If you are using either coprocessor, the
  15128. following precautions are recommended:%@CR:C6A01100566 @%  %@NL@%
  15129. %@NL@%
  15130. %@NL@%
  15131.   ■   The %@AB@%exec%@AE@%, %@AB@%spawn%@AE@%, and %@AB@%system%@AE@% functions should not be called during the
  15132.       evaluation of a floating-point expression.%@NL@%
  15133. %@NL@%
  15134.   ■   The %@AB@%_fpreset%@AE@% function should be called after these routines if there
  15135.       is a possibility of the child process performing any floating-point
  15136.       operations.%@NL@%
  15137. %@NL@%
  15138. %@NL@%
  15139. %@NL@%
  15140. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15141. %@NL@%
  15142. None.  %@NL@%
  15143. %@NL@%
  15144. %@NL@%
  15145. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15146. %@NL@%
  15147.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  15148. %@NL@%
  15149. %@NL@%
  15150. %@NL@%
  15151. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15152. %@NL@%
  15153. %@AB@%exec%@AE@% functions, %@AB@%signal%@AE@%, %@AB@%spawn%@AE@% functions  %@NL@%
  15154. %@NL@%
  15155. %@NL@%
  15156. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15157. %@NL@%
  15158. %@AS@%  /* FPRESET.C: This program uses signal to set up a routine for handling
  15159. %@AS@%   * floating-point errors.
  15160. %@AS@%   */
  15161. %@AS@%  
  15162. %@AS@%  #include <stdio.h>
  15163. %@AS@%  #include <signal.h>
  15164. %@AS@%  #include <setjmp.h>
  15165. %@AS@%  #include <stdlib.h>
  15166. %@AS@%  #include <float.h>
  15167. %@AS@%  #include <math.h>
  15168. %@AS@%  #include <string.h>%@AE@%%@NL@%
  15169. %@NL@%
  15170. %@AS@%  jmp_buf mark;                       /* Address for long jump to jump to */
  15171. %@AS@%  int  fperr;                         /* Global error number */
  15172. %@AS@%  
  15173. %@AS@%  void fphandler( int sig, int num ); /* Prototypes */
  15174. %@AS@%  void fpcheck( void );
  15175. %@AS@%  
  15176. %@AS@%  void main()
  15177. %@AS@%  {
  15178. %@AS@%      double n1, n2, r;
  15179. %@AS@%      int jmpret;
  15180. %@AS@%  
  15181. %@AS@%      /* Set up floating point error handler. */
  15182. %@AS@%      if( signal( SIGFPE, fphandler ) == SIG_ERR )
  15183. %@AS@%      {
  15184. %@AS@%          fprintf( stderr, "Couldn't set SIGFPE\n" );
  15185. %@AS@%          abort();
  15186. %@AS@%      }
  15187. %@AS@%  
  15188. %@AS@%      /* Save stack environment for return in case of error. First time
  15189. %@AS@%       * through, jmpret is 0, so true conditional is executed. If an
  15190. %@AS@%       * error occurs, jmpret will be set to -1 and false conditional
  15191. %@AS@%       * will be executed.
  15192. %@AS@%       */
  15193. %@AS@%      jmpret = setjmp( mark );
  15194. %@AS@%      if( jmpret == 0 )
  15195. %@AS@%      {
  15196. %@AS@%          printf( "Test for invalid operation - " );
  15197. %@AS@%          printf( "enter two numbers: " );
  15198. %@AS@%          scanf( "%lf %lf", &n1, &n2 );
  15199. %@AS@%  
  15200. %@AS@%          r = n1 / n2;
  15201. %@AS@%          /* This won't be reached if error occurs. */
  15202. %@AS@%          printf( "\n\n%4.3g / %4.3g = %4.3g\n", n1, n2, r );
  15203. %@AS@%  
  15204. %@AS@%          r = n1 * n2;
  15205. %@AS@%          /* This won't be reached if error occurs. */
  15206. %@AS@%          printf( "\n\n%4.3g * %4.3g = %4.3g\n", n1, n2, r );
  15207. %@AS@%      }
  15208. %@AS@%      else
  15209. %@AS@%          fpcheck();
  15210. %@AS@%  }%@AE@%%@NL@%
  15211. %@NL@%
  15212. %@AS@%  /* Handles SIGFPE (floating point error) interrupt. */
  15213. %@AS@%  void fphandler( int sig, int num )
  15214. %@AS@%  {
  15215. %@AS@%      /* Set global for outside check since we don't want to do I/O in the
  15216. %@AS@%       * handler.
  15217. %@AS@%       */
  15218. %@AS@%      fperr = num;
  15219. %@AS@%  
  15220. %@AS@%      /* Initialize floating-point package. */
  15221. %@AS@%      _fpreset();
  15222. %@AS@%  
  15223. %@AS@%      /* Restore calling environment and jump back to setjmp. Return -1
  15224. %@AS@%       * so that setjmp will return false for conditional test.
  15225. %@AS@%       */
  15226. %@AS@%      longjmp( mark, -1 );
  15227. %@AS@%  }
  15228. %@AS@%  
  15229. %@AS@%  void fpcheck()
  15230. %@AS@%  {
  15231. %@AS@%      char fpstr[30];
  15232. %@AS@%  
  15233. %@AS@%      switch( fperr )
  15234. %@AS@%      {
  15235. %@AS@%          case FPE_INVALID:
  15236. %@AS@%              strcpy( fpstr, "Invalid number" );
  15237. %@AS@%              break;
  15238. %@AS@%  
  15239. %@AS@%          case FPE_OVERFLOW:
  15240. %@AS@%              strcpy( fpstr, "Overflow" );
  15241. %@AS@%              break;
  15242. %@AS@%  
  15243. %@AS@%          case FPE_UNDERFLOW:
  15244. %@AS@%              strcpy( fpstr, "Underflow" );
  15245. %@AS@%              break;
  15246. %@AS@%  
  15247. %@AS@%          case FPE_ZERODIVIDE:
  15248. %@AS@%              strcpy( fpstr, "Divide by zero" );
  15249. %@AS@%              break;
  15250. %@AS@%  
  15251. %@AS@%          default:
  15252. %@AS@%              strcpy( fpstr, "Other floating point error" );
  15253. %@AS@%              break;
  15254. %@AS@%      }
  15255. %@AS@%      printf( "Error %d: %s\n", fperr, fpstr );
  15256. %@AS@%  }%@AE@%%@NL@%
  15257. %@NL@%
  15258. %@NL@%
  15259. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15260. %@NL@%
  15261. %@AS@%  
  15262. %@AS@%  
  15263. %@AS@%  Test for invalid operation - enter two numbers: 5 0
  15264. %@AS@%  Error 131: Divide by zero%@AE@%%@NL@%
  15265. %@NL@%
  15266. %@NL@%
  15267. %@NL@%
  15268. %@NL@%
  15269. %@QR:fprintf@%%@NL@%
  15270. %@2@%%@CR:C6A01110567 @%%@AB@%fprintf%@AE@%%@EH@%%@NL@%
  15271. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15272. %@NL@%
  15273. %@NL@%
  15274. %@3@%%@AB@%Description%@CR:C6A01110568 @%%@CR:C6A01110569 @% %@CR:C6A01110570 @%%@CR:C6A01110571 @% %@CR:C6A01110572 @%%@AE@%%@EH@%%@NL@%
  15275. %@NL@%
  15276. Prints formatted data to a stream.  %@NL@%
  15277. %@NL@%
  15278. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  15279. %@NL@%
  15280. %@AS@%  int fprintf( FILE *stream, const char *format [[, argument]]... );%@AE@%%@NL@%
  15281. %@NL@%
  15282. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  15283.  
  15284. %@AI@%format%@AE@%                            Format-control string
  15285.  
  15286. %@AI@%argument%@AE@%                          Optional arguments
  15287.  
  15288. %@NL@%
  15289. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15290. %@NL@%
  15291. The %@AB@%fprintf%@AE@% function formats and prints a series of characters and values to
  15292. the output %@AI@%stream%@AE@%. Each %@AI@%argument%@AE@% (if any) is converted and output according
  15293. to the corresponding format specification in %@AI@%format%@AE@%.  %@NL@%
  15294. %@NL@%
  15295. The %@AI@%format%@AE@% argument has the same form and function that it does for the
  15296. %@AB@%printf%@AE@% function; see the Remarks section for the %@AB@%printf%@AE@% function for more
  15297. information on %@AI@%format%@AE@% and %@AI@%argument%@AE@%.  %@NL@%
  15298. %@NL@%
  15299. %@NL@%
  15300. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15301. %@NL@%
  15302. The %@AB@%fprintf%@AE@% function returns the number of characters printed, or a negative
  15303. value in the case of an output error.  %@NL@%
  15304. %@NL@%
  15305. %@NL@%
  15306. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15307. %@NL@%
  15308. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  15309. %@NL@%
  15310. %@NL@%
  15311. %@NL@%
  15312. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15313. %@NL@%
  15314. %@AB@%cprintf%@AE@%, %@AB@%fscanf%@AE@%, %@AB@%printf%@AE@%, %@AB@%sprintf%@AE@%  %@NL@%
  15315. %@NL@%
  15316. %@NL@%
  15317. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15318. %@NL@%
  15319. %@AS@%  /* FPRINTF.C: This program uses fprintf to format various data and
  15320. %@AS@%   * print them to the file named FPRINTF.OUT. It then displays
  15321. %@AS@%   * FPRINTF.OUT on the screen using the system function to invoke
  15322. %@AS@%   * the DOS TYPE command.
  15323. %@AS@%   */
  15324. %@AS@%  
  15325. %@AS@%  #include <stdio.h>
  15326. %@AS@%  #include <process.h>%@AE@%%@NL@%
  15327. %@NL@%
  15328. %@AS@%  FILE *stream;
  15329. %@AS@%  
  15330. %@AS@%  void main()
  15331. %@AS@%  {
  15332. %@AS@%     int    i = 10;
  15333. %@AS@%     double fp = 1.5;
  15334. %@AS@%     char   s[] = "this is a string";
  15335. %@AS@%     char   c = '\n';
  15336. %@AS@%  
  15337. %@AS@%     stream = fopen( "fprintf.out", "w" );
  15338. %@AS@%     fprintf( stream, "%s%c", s, c );
  15339. %@AS@%     fprintf( stream, "%d\n", i );
  15340. %@AS@%     fprintf( stream, "%f\n", fp );
  15341. %@AS@%     fclose( stream );
  15342. %@AS@%     system( "type fprintf.out" );
  15343. %@AS@%  }%@AE@%%@NL@%
  15344. %@NL@%
  15345. %@NL@%
  15346. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15347. %@NL@%
  15348. %@AS@%  
  15349. %@AS@%  
  15350. %@AS@%  this is a string
  15351. %@AS@%  10
  15352. %@AS@%  1.500000 %@AE@%%@NL@%
  15353. %@NL@%
  15354. %@NL@%
  15355. %@NL@%
  15356. %@NL@%
  15357. %@QR:fputc@%%@QR:fputchar@%%@NL@%
  15358. %@2@%%@CR:C6A01120573 @%%@AB@%fputc, fputchar%@AE@%%@EH@%%@NL@%
  15359. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15360. %@NL@%
  15361. %@NL@%
  15362. %@3@%%@AB@%Description%@CR:C6A01120574 @%%@CR:C6A01120575 @% %@CR:C6A01120576 @% %@CR:C6A01120577 @%%@CR:C6A01120578 @% %@CR:C6A01120579 @%%@AE@%%@EH@%%@NL@%
  15363. %@NL@%
  15364. Write a character to a stream (%@AB@%fputc%@AE@%) or to %@AB@%stdout %@AE@%(%@AB@%fputchar%@AE@%).  %@NL@%
  15365. %@NL@%
  15366. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  15367. %@NL@%
  15368. %@AS@%  int fputc( int c, FILE *stream );%@AE@%%@NL@%
  15369. %@NL@%
  15370. %@AS@%  int fputchar( int c );%@AE@%%@NL@%
  15371. %@NL@%
  15372. %@AI@%c%@AE@%                                 Character to be written
  15373.  
  15374. %@AI@%stream %@AE@%                           Pointer to %@AB@%FILE %@AE@%structure
  15375.  
  15376. %@NL@%
  15377. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15378. %@NL@%
  15379. The %@AB@%fputc%@AE@% function writes the single character %@AI@%c%@AE@% to the output %@AI@%stream%@AE@% at the
  15380. current position. The %@AB@%fputchar%@AE@% function is equivalent to %@AB@%fputc(%@AE@%%@AI@%c%@AE@%,%@AB@% stdout)%@AE@%.  %@NL@%
  15381. %@NL@%
  15382. The %@AB@%fputc%@AE@% and %@AB@%fputchar%@AE@% routines are similar to %@AB@%putc%@AE@% and %@AB@%putchar%@AE@%, but are
  15383. functions rather than macros.  %@NL@%
  15384. %@NL@%
  15385. %@NL@%
  15386. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15387. %@NL@%
  15388. The %@AB@%fputc%@AE@% and %@AB@%fputchar%@AE@% functions return the character written. A return
  15389. value of %@AB@%EOF%@AE@% indicates an error.  %@NL@%
  15390. %@NL@%
  15391. %@NL@%
  15392. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15393. %@NL@%
  15394. %@AB@%fputc%@AE@%  %@NL@%
  15395. %@NL@%
  15396. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  15397. %@NL@%
  15398. %@NL@%
  15399. %@AB@%fputchar%@AE@%  %@NL@%
  15400. %@NL@%
  15401.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  15402. %@NL@%
  15403. %@NL@%
  15404. %@NL@%
  15405. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15406. %@NL@%
  15407. %@AB@%fgetc%@AE@%, %@AB@%fgetchar%@AE@%, %@AB@%putc%@AE@%, %@AB@%putchar%@AE@%  %@NL@%
  15408. %@NL@%
  15409. %@NL@%
  15410. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15411. %@NL@%
  15412. %@AS@%  /* FPUTC.C: This program uses fputc and fputchar to send a character
  15413. %@AS@%   * array to stdout.
  15414. %@AS@%   */
  15415. %@AS@%  
  15416. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  15417. %@NL@%
  15418. %@AS@%  void main()
  15419. %@AS@%  {
  15420. %@AS@%     char strptr1[] = "This is a test of fputc!!\n";
  15421. %@AS@%     char strptr2[] = "This is a test of fputchar!!\n";
  15422. %@AS@%     char *p;
  15423. %@AS@%  
  15424. %@AS@%     /* Print line to stream using fputc. */
  15425. %@AS@%     p = strptr1;
  15426. %@AS@%     while( (*p != '\0') && fputc( *(p++), stdout ) != EOF )
  15427. %@AS@%        ;
  15428. %@AS@%  
  15429. %@AS@%     /* Print line to stream using fputchar. */
  15430. %@AS@%     p = strptr2;
  15431. %@AS@%     while( (*p != '\0') && fputchar( *(p++) ) != EOF )
  15432. %@AS@%        ;
  15433. %@AS@%  }%@AE@%%@NL@%
  15434. %@NL@%
  15435. %@NL@%
  15436. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15437. %@NL@%
  15438. %@AS@%  
  15439. %@AS@%  
  15440. %@AS@%  This is a test of fputc!!
  15441. %@AS@%  This is a test of fputchar!! %@AE@%%@NL@%
  15442. %@NL@%
  15443. %@NL@%
  15444. %@NL@%
  15445. %@NL@%
  15446. %@QR:fputs@%%@NL@%
  15447. %@2@%%@CR:C6A01130580 @%%@AB@%fputs%@AE@%%@EH@%%@NL@%
  15448. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15449. %@NL@%
  15450. %@NL@%
  15451. %@3@%%@AB@%Description%@CR:C6A01130581 @%%@CR:C6A01130582 @% %@CR:C6A01130583 @%%@CR:C6A01130584 @% %@CR:C6A01130585 @%%@AE@%%@EH@%%@NL@%
  15452. %@NL@%
  15453. Writes a string to a stream.  %@NL@%
  15454. %@NL@%
  15455. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  15456. %@NL@%
  15457. %@AS@%  int fputs( const char *string, FILE *stream );%@AE@%%@NL@%
  15458. %@NL@%
  15459. %@AI@%string%@AE@%                            String to be output
  15460.  
  15461. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  15462.  
  15463. %@NL@%
  15464. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15465. %@NL@%
  15466. The %@AB@%fputs%@AE@% function copies %@AI@%string%@AE@% to the output %@AI@%stream%@AE@% at the current
  15467. position. The terminating null character (%@AB@%'\0'%@AE@%) is not copied.  %@NL@%
  15468. %@NL@%
  15469. %@NL@%
  15470. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15471. %@NL@%
  15472. The %@AB@%fputs%@AE@% function returns a nonnegative value if it is successful. If an
  15473. error occurs, it returns %@AB@%EOF%@AE@%.%@CR:C6A01130586 @%  %@NL@%
  15474. %@NL@%
  15475. %@NL@%
  15476. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15477. %@NL@%
  15478. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  15479. %@NL@%
  15480. %@NL@%
  15481. %@NL@%
  15482. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15483. %@NL@%
  15484. %@AB@%fgets%@AE@%, %@AB@%gets%@AE@%, %@AB@%puts%@AE@%  %@NL@%
  15485. %@NL@%
  15486. %@NL@%
  15487. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15488. %@NL@%
  15489. %@AS@%  /* FPUTS.C: This program uses fputs to write a single line to the
  15490. %@AS@%   * stdout stream.
  15491. %@AS@%   */
  15492. %@AS@%  
  15493. %@AS@%  #include <stdio.h>
  15494. %@AS@%  
  15495. %@AS@%  void main()
  15496. %@AS@%  {
  15497. %@AS@%     fputs( "Hello world from fputs.\n", stdout );
  15498. %@AS@%  }%@AE@%%@NL@%
  15499. %@NL@%
  15500. %@NL@%
  15501. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15502. %@NL@%
  15503. %@AS@%  
  15504. %@AS@%  
  15505. %@AS@%  Hello world from fputs. %@AE@%%@NL@%
  15506. %@NL@%
  15507. %@NL@%
  15508. %@NL@%
  15509. %@NL@%
  15510. %@QR:fread@%%@NL@%
  15511. %@2@%%@CR:C6A01140587 @%%@AB@%fread%@AE@%%@EH@%%@NL@%
  15512. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15513. %@NL@%
  15514. %@NL@%
  15515. %@3@%%@AB@%Description%@CR:C6A01140588 @%%@CR:C6A01140589 @%%@CR:C6A01140590 @% %@CR:C6A01140591 @%%@AE@%%@EH@%%@NL@%
  15516. %@NL@%
  15517. Reads data from a stream.  %@NL@%
  15518. %@NL@%
  15519. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  15520. %@NL@%
  15521. %@AS@%  size_t fread( void *buffer, size_t size, size_t count, FILE *stream );%@AE@%%@NL@%
  15522. %@NL@%
  15523. %@AI@%buffer%@AE@%                            Storage location for data
  15524.  
  15525. %@AI@%size%@AE@%                              Item size in bytes
  15526.  
  15527. %@AI@%count%@AE@%                             Maximum number of items to be read
  15528.  
  15529. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  15530.  
  15531. %@NL@%
  15532. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15533. %@NL@%
  15534. The %@AB@%fread%@AE@% function reads up to %@AI@%count%@AE@% items of %@AI@%size%@AE@% bytes from the input
  15535. %@AI@%stream%@AE@% and stores them in %@AI@%buffer%@AE@%. The file pointer associated with %@AI@%stream%@AE@%
  15536. (if there is one) is increased by the number of bytes actually read.  %@NL@%
  15537. %@NL@%
  15538. If the given stream is opened in text mode, carriage-return-line-feed pairs
  15539. are replaced with single line-feed characters. The replacement has no effect
  15540. on the file pointer or the return value.  %@NL@%
  15541. %@NL@%
  15542. The file-pointer position is indeterminate if an error occurs. The value of
  15543. a partially read item cannot be determined.  %@NL@%
  15544. %@NL@%
  15545. %@NL@%
  15546. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15547. %@NL@%
  15548. The %@AB@%fread%@AE@% function returns the number of full items actually read, which may
  15549. be less than %@AI@%count%@AE@% if an error occurs or if the file end is encountered
  15550. before reaching %@AI@%count%@AE@%.  %@NL@%
  15551. %@NL@%
  15552. The %@AB@%feof%@AE@% or %@AB@%ferror%@AE@% function should be used to distinguish a read error from
  15553. an end-of-file condition. If %@AI@%size%@AE@% or %@AI@%count%@AE@% is 0, %@AB@%fread%@AE@% returns 0 and the
  15554. buffer contents are unchanged.  %@NL@%
  15555. %@NL@%
  15556. %@NL@%
  15557. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15558. %@NL@%
  15559. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  15560. %@NL@%
  15561. %@NL@%
  15562. %@NL@%
  15563. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15564. %@NL@%
  15565. %@AB@%fwrite%@AE@%, %@AB@%read%@AE@%  %@NL@%
  15566. %@NL@%
  15567. %@NL@%
  15568. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15569. %@NL@%
  15570. %@AS@%  /* FREAD.C: This program opens a file named FREAD.OUT and writes 25
  15571. %@AS@%   * characters to the file. It then tries to open FREAD.OUT and
  15572. %@AS@%   * read in 25 characters. If the attempt succeeds, the program
  15573. %@AS@%   * displays the number of actual items read.
  15574. %@AS@%   */%@AE@%%@NL@%
  15575. %@NL@%
  15576. %@AS@%  #include <stdio.h>
  15577. %@AS@%  
  15578. %@AS@%  void main()
  15579. %@AS@%  {
  15580. %@AS@%     FILE *stream;
  15581. %@AS@%     char list[30];
  15582. %@AS@%     int  i, numread, numwritten;
  15583. %@AS@%  
  15584. %@AS@%     /* Open file in text mode: */
  15585. %@AS@%     if( (stream = fopen( "fread.out", "w+t" )) != NULL )
  15586. %@AS@%     {
  15587. %@AS@%        for ( i = 0; i < 25; i++ )
  15588. %@AS@%           list[i] = 'z' - i;
  15589. %@AS@%        /* Write 25 characters to stream */
  15590. %@AS@%        numwritten = fwrite( list, sizeof( char ), 25, stream );
  15591. %@AS@%        printf( "Wrote %d items\n", numwritten );
  15592. %@AS@%        fclose( stream );
  15593. %@AS@%     }
  15594. %@AS@%     else
  15595. %@AS@%        printf( "Problem opening the file\n" );
  15596. %@AS@%  
  15597. %@AS@%     if( (stream = fopen( "fread.out", "r+t" )) != NULL )
  15598. %@AS@%     {
  15599. %@AS@%        /* Attempt to read in 25 characters */
  15600. %@AS@%        numread = fread( list, sizeof( char ), 25, stream );
  15601. %@AS@%        printf( "Number of items read = %d\n", numread );
  15602. %@AS@%        printf( "Contents of buffer = %.25s\n", list );
  15603. %@AS@%        fclose( stream );
  15604. %@AS@%     }
  15605. %@AS@%     else
  15606. %@AS@%        printf( "Was not able to open the file\n" );
  15607. %@AS@%  }%@AE@%%@NL@%
  15608. %@NL@%
  15609. %@NL@%
  15610. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15611. %@NL@%
  15612. %@AS@%  
  15613. %@AS@%  
  15614. %@AS@%  Wrote 25 items
  15615. %@AS@%  Number of items read = 25
  15616. %@AS@%  Contents of buffer = zyxwvutsrqponmlkjihgfedcb %@AE@%%@NL@%
  15617. %@NL@%
  15618. %@NL@%
  15619. %@NL@%
  15620. %@NL@%
  15621. %@QR:free@%%@NL@%
  15622. %@2@%%@CR:C6A01150592 @%%@AB@%free Functions%@AE@%%@EH@%%@NL@%
  15623. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15624. %@NL@%
  15625. %@NL@%
  15626. %@3@%%@AB@%Description%@CR:C6A01150593 @%%@CR:C6A01150594 @%%@CR:C6A01150595 @% %@CR:C6A01150596 @%%@CR:C6A01150597 @% %@CR:C6A01150598 @%%@CR:C6A01150599 @%%@CR:C6A01150600 @%%@AE@%%@EH@%%@NL@%
  15627. %@NL@%
  15628. Deallocate a memory block.  %@NL@%
  15629. %@NL@%
  15630. %@AB@%#include <stdlib.h>%@AE@%               For ANSI compatibility (%@AB@%free%@AE@% only)
  15631.  
  15632. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  15633.  
  15634. %@AS@%  void free( void *memblock );%@AE@%%@NL@%
  15635. %@NL@%
  15636. %@AS@%  void _bfree( _segment seg, void _based( void ) *memblock );%@AE@%%@NL@%
  15637. %@NL@%
  15638. %@AS@%  void _ffree( void _far *memblock );%@AE@%%@NL@%
  15639. %@NL@%
  15640. %@AS@%  void _nfree( void _near *memblock );%@AE@%%@NL@%
  15641. %@NL@%
  15642. %@AI@%memblock%@AE@%                          Allocated memory block
  15643.  
  15644. %@AI@%seg%@AE@%                               Based-heap segment selector
  15645.  
  15646. %@NL@%
  15647. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15648. %@NL@%
  15649. The %@AB@%free%@AE@% family of functions deallocates a memory block. The argument
  15650. %@AI@%memblock%@AE@% points to a memory block previously allocated through a call to
  15651. %@AB@%calloc%@AE@%, %@AB@%malloc%@AE@%, or %@AB@%realloc%@AE@%. The number of bytes freed is the number of bytes
  15652. specified when the block was allocated (or reallocated, in the case of
  15653. %@AB@%realloc%@AE@%). After the call, the freed block is available for allocation.  %@NL@%
  15654. %@NL@%
  15655. The %@AI@%seg%@AE@% argument specifies the based heap containing the memory block to be
  15656. freed by the %@AB@%_bfree%@AE@% function.  %@NL@%
  15657. %@NL@%
  15658. Attempting to free an invalid pointer may affect subsequent allocation and
  15659. cause errors. An invalid pointer is one not allocated with the appropriate
  15660. call.  %@NL@%
  15661. %@NL@%
  15662. The following restrictions apply to use of the %@AB@%free%@AE@%, %@AB@%_bfree%@AE@%, %@AB@%_ffree%@AE@%, and
  15663. %@AB@%_nfree%@AE@% functions:  %@NL@%
  15664. %@NL@%
  15665. %@AB@%Blocks allocated with:%@AE@%            %@AB@%Should be freed with:%@AE@%
  15666. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15667. %@AB@%calloc%@AE@%, %@AB@%malloc%@AE@%, %@AB@%realloc%@AE@%           %@AB@%free%@AE@%
  15668.  
  15669. %@AB@%_bcalloc%@AE@%,%@AB@% _bmalloc%@AE@%,%@AB@% _brealloc%@AE@%     %@AB@%_bfree%@AE@%
  15670.  
  15671. %@AB@%_fcalloc%@AE@%, %@AB@%_fmalloc%@AE@%, %@AB@%_frealloc%@AE@%     %@AB@%_ffree%@AE@%
  15672.  
  15673. %@AB@%_ncalloc%@AE@%,%@AB@% _nmalloc%@AE@%,%@AB@% _nrealloc%@AE@%     %@AB@%_nfree%@AE@%
  15674.  
  15675. A%@AB@% NULL%@AE@% pointer argument is ignored.  %@NL@%
  15676. %@NL@%
  15677. In large data models (compact-, large-, and huge-model programs), %@AB@%free%@AE@% maps
  15678. to %@AB@%_ffree%@AE@%. In small data models (tiny-, small-, and medium-model programs),
  15679. %@AB@%free%@AE@% maps to %@AB@%_nfree%@AE@%.  %@NL@%
  15680. %@NL@%
  15681. The various %@AB@%free%@AE@% functions deallocate a memory block in the segments shown
  15682. in the list below:  %@NL@%
  15683. %@NL@%
  15684. %@AB@%Function%@AE@%                          %@AB@%Data Segment%@AE@%
  15685. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15686. %@AB@%free%@AE@%                              Depends on data model of program
  15687.  
  15688. %@AB@%_bfree%@AE@%                            Based heap specified by %@AI@%seg%@AE@% value
  15689.  
  15690. %@AB@%_ffree%@AE@%                            Far heap (outside default data segment)
  15691.  
  15692. %@AB@%_nfree%@AE@%                            Near heap (inside default data segment)
  15693.  
  15694. %@NL@%
  15695. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15696. %@NL@%
  15697. None.  %@NL@%
  15698. %@NL@%
  15699. %@NL@%
  15700. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15701. %@NL@%
  15702. %@AB@%free%@AE@%  %@NL@%
  15703. %@NL@%
  15704. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  15705. %@NL@%
  15706. %@NL@%
  15707. %@AB@%_bfree, _ffree, _nfree%@AE@%  %@NL@%
  15708. %@NL@%
  15709.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  15710. %@NL@%
  15711. %@NL@%
  15712. %@NL@%
  15713. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15714. %@NL@%
  15715. %@AB@%calloc %@AE@%functions, %@AB@%malloc%@AE@% functions, %@AB@%realloc %@AE@%functions  %@NL@%
  15716. %@NL@%
  15717. %@NL@%
  15718. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15719. %@NL@%
  15720. %@AS@%  /* MALLOC.C: This program allocates memory with malloc, then frees
  15721. %@AS@%   * the memory with free.
  15722. %@AS@%   */
  15723. %@AS@%  
  15724. %@AS@%  #include <stdlib.h>         /* Definition of _MAX_PATH */
  15725. %@AS@%  #include <stdio.h>
  15726. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  15727. %@NL@%
  15728. %@AS@%  void main()
  15729. %@AS@%  {
  15730. %@AS@%     char *string;
  15731. %@AS@%  
  15732. %@AS@%     /* Allocate space for a path name */
  15733. %@AS@%     string = malloc( _MAX_PATH );
  15734. %@AS@%     if( string == NULL )
  15735. %@AS@%        printf( "Insufficient memory available\n" );
  15736. %@AS@%     else
  15737. %@AS@%        printf( "Memory space allocated for path name\n" );
  15738. %@AS@%     free( string );
  15739. %@AS@%     printf( "Memory freed\n" );
  15740. %@AS@%  }%@AE@%%@NL@%
  15741. %@NL@%
  15742. %@NL@%
  15743. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15744. %@NL@%
  15745. %@AS@%  
  15746. %@AS@%  
  15747. %@AS@%  Memory space allocated for path name
  15748. %@AS@%  Memory freed %@AE@%%@NL@%
  15749. %@NL@%
  15750. %@NL@%
  15751. %@NL@%
  15752. %@NL@%
  15753. %@QR:_freect@%%@NL@%
  15754. %@2@%%@CR:C6A01160601 @%%@AB@%_freect%@AE@%%@EH@%%@NL@%
  15755. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15756. %@NL@%
  15757. %@NL@%
  15758. %@3@%%@AB@%Description%@CR:C6A01160602 @%%@CR:C6A01160603 @% %@CR:C6A01160604 @%%@CR:C6A01160605 @%%@AE@%%@EH@%%@NL@%
  15759. %@NL@%
  15760. Returns the amount of memory available for memory allocation.  %@NL@%
  15761. %@NL@%
  15762. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  15763.  
  15764. %@AS@%  unsigned int _freect( size_t size );%@AE@%%@NL@%
  15765. %@NL@%
  15766. %@AI@%size%@AE@%                              Item size in bytes
  15767.  
  15768. %@NL@%
  15769. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15770. %@NL@%
  15771. The %@AB@%_freect%@AE@% function tells you how much memory is available for dynamic
  15772. memory allocation in the near heap. It does so by returning the approximate
  15773. number of times your program can call%@AB@% _nmalloc%@AE@% (or %@AB@%malloc%@AE@% in small data
  15774. models) to allocate an item %@AI@%size%@AE@% bytes long in the near heap (default data
  15775. segment).  %@NL@%
  15776. %@NL@%
  15777. %@NL@%
  15778. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15779. %@NL@%
  15780. The %@AB@%_freect%@AE@% function returns the number of calls as an unsigned integer.  %@NL@%
  15781. %@NL@%
  15782. %@NL@%
  15783. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15784. %@NL@%
  15785.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  15786. %@NL@%
  15787. %@NL@%
  15788. %@NL@%
  15789. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15790. %@NL@%
  15791. %@AB@%calloc%@AE@% functions,%@AB@% _expand%@AE@% functions, %@AB@%malloc%@AE@% functions, %@AB@%_memavl%@AE@%, %@AB@%_msize%@AE@%
  15792. functions, %@AB@% realloc%@AE@% functions  %@NL@%
  15793. %@NL@%
  15794. %@NL@%
  15795. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15796. %@NL@%
  15797. %@AS@%  /* FREECT.C: This program determines how much free space is available for
  15798. %@AS@%   * integers in the default data segment. Then it allocates space for
  15799. %@AS@%   * 1,000 integers and checks the space again, using _freect.
  15800. %@AS@%   */
  15801. %@AS@%  
  15802. %@AS@%  #include <malloc.h>
  15803. %@AS@%  #include <stdio.h>
  15804. %@AS@%  
  15805. %@AS@%  void main()
  15806. %@AS@%  {
  15807. %@AS@%     int i;
  15808. %@AS@%  
  15809. %@AS@%     /* First report on the free space: */
  15810. %@AS@%     printf( "Integers (approximate) available on heap: %u\n\n",
  15811. %@AS@%             _freect( sizeof( int ) ) );
  15812. %@AS@%  
  15813. %@AS@%     /* Allocate space for 1000 integers: */
  15814. %@AS@%     for( i = 0; i < 1000; ++i )
  15815. %@AS@%        malloc( sizeof( int ) );%@AE@%%@NL@%
  15816. %@NL@%
  15817. %@AS@%  /* Report again on the free space: */
  15818. %@AS@%     printf( "After allocating space for 1000 integers:\n" );
  15819. %@AS@%     printf( "Integers (approximate) available on heap: %u\n\n",
  15820. %@AS@%             _freect( sizeof( int ) ) );
  15821. %@AS@%  
  15822. %@AS@%  }%@AE@%%@NL@%
  15823. %@NL@%
  15824. %@NL@%
  15825. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15826. %@NL@%
  15827. %@AS@%  
  15828. %@AS@%  
  15829. %@AS@%  Integers (approximate) available on heap: 15212
  15830. %@AS@%  
  15831. %@AS@%  After allocating space for 1000 integers:
  15832. %@AS@%  Integers (approximate) available on heap: 14084 %@AE@%%@NL@%
  15833. %@NL@%
  15834. %@NL@%
  15835. %@NL@%
  15836. %@NL@%
  15837. %@QR:freopen@%%@NL@%
  15838. %@2@%%@CR:C6A01170606 @%%@AB@%freopen%@AE@%%@EH@%%@NL@%
  15839. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15840. %@NL@%
  15841. %@NL@%
  15842. %@3@%%@AB@%Description%@CR:C6A01170607 @%%@CR:C6A01170608 @%%@CR:C6A01170609 @% %@CR:C6A01170610 @%%@CR:C6A01170611 @%%@CR:C6A01170612 @%%@CR:C6A01170613 @% %@CR:C6A01170614 @%%@CR:C6A01170615 @%%@AE@%%@EH@%%@NL@%
  15843. %@NL@%
  15844. Reassigns a file pointer.  %@NL@%
  15845. %@NL@%
  15846. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  15847. %@NL@%
  15848. %@AS@%  FILE *freopen( const char *filename, const char *mode, FILE *stream );%@AE@%%@NL@%
  15849. %@NL@%
  15850. %@AI@%filename%@AE@%                          Path name of new file
  15851.  
  15852. %@AI@%mode%@AE@%                              Type of access permitted
  15853.  
  15854. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  15855.  
  15856. %@NL@%
  15857. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  15858. %@NL@%
  15859. The %@AB@%freopen%@AE@% function closes the file currently associated with %@AI@%stream%@AE@% and
  15860. reassigns %@AI@%stream%@AE@% to the file specified by %@AI@%filename%@AE@%. The %@AB@%freopen%@AE@% function is
  15861. typically used to redirect the pre-opened files %@AB@%stdin%@AE@%, %@AB@%stdout%@AE@%, and %@AB@%stderr %@AE@%to
  15862. files specified by the user. The new file associated with%@AB@% %@AE@%%@AI@%stream%@AE@% is opened
  15863. with %@AI@%mode%@AE@%, which is a character string specifying the type of access
  15864. requested for the file, as follows: %@CR:C6A01170616 @%  %@NL@%
  15865. %@NL@%
  15866. %@AB@%Type%@AE@%                              %@AB@%Description %@AE@%
  15867. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15868. %@AB@%"r"%@AE@%                               Opens for reading. If the file does not 
  15869.                                   exist or cannot be found, the %@AB@%freopen%@AE@% 
  15870.                                   call fails. 
  15871.  
  15872. %@AB@%"w"%@AE@%                               Opens an empty file for writing. If the 
  15873.                                   given file exists, its contents are 
  15874.                                   destroyed. 
  15875.  
  15876. %@AB@%"a"%@AE@%                               Opens for writing at the end of the file
  15877.                                   (appending); creates the file first if 
  15878.                                   it does not exist.
  15879.  
  15880. %@AB@%"r+"%@AE@%                              Opens for both reading and writing. (The
  15881.                                   file must exist.)
  15882.  
  15883. %@AB@%"w+"%@AE@%                              Opens an empty file for both reading and
  15884.                                   writing. If the given file exists, its 
  15885.                                   contents are destroyed.
  15886.  
  15887. %@AB@%"a+"%@AE@%                              Opens for reading and appending; creates
  15888.                                   the file first if it does not exist.
  15889.  
  15890. Use the %@AB@%"w" %@AE@%and%@AB@% "w+" %@AE@%types with care, as they can destroy existing files.  %@NL@%
  15891. %@NL@%
  15892. When a file is opened with the %@AB@%"a"%@AE@% or %@AB@%"a+"%@AE@% access type, all write operations
  15893. take place at the end of the file. Although the file pointer can be
  15894. repositioned using %@AB@%fseek%@AE@% or %@AB@%rewind%@AE@%, the file pointer is always moved back to
  15895. the end of the file before any write operation is carried out. Thus,
  15896. existing data cannot be overwritten.  %@NL@%
  15897. %@NL@%
  15898. When the %@AB@%"r+"%@AE@%, %@AB@%"w+"%@AE@%, or %@AB@%"a+"%@AE@% access type is specified, both reading and
  15899. writing are allowed (the file is said to be open for "update"). However,
  15900. when you switch between reading and writing, there must be an intervening
  15901. %@AB@%fsetpos%@AE@%, %@AB@%fseek%@AE@%, or %@AB@%rewind%@AE@% operation. The current position can be specified
  15902. for the %@AB@%fsetpos%@AE@% or %@AB@%fseek%@AE@% operation, if desired.  %@NL@%
  15903. %@NL@%
  15904. In addition to the values listed above, one of the following characters may
  15905. be included in the %@AI@%mode%@AE@% string to specify the translation mode for newlines.%@CR:C6A01170617 @%
  15906. %@NL@%
  15907. %@NL@%
  15908. %@AB@%Mode%@AE@%                              %@AB@%Meaning%@AE@%
  15909. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15910. %@AB@%t%@AE@%                                 Open in text (translated) mode; 
  15911.                                   carriage-return-line-feed
  15912.                                   (CR-LF) combinations are translated into
  15913.                                   single line-feed (LF) characters on 
  15914.                                   input; LF characters are translated to 
  15915.                                   CR-LF combinations on output. Also, 
  15916.                                   CTRL+Z is interpreted as an end-of-file 
  15917.                                   character on input. In files opened for 
  15918.                                   reading, or writing and reading, the 
  15919.                                   run-time library checks for a CTRL+Z at 
  15920.                                   the end of the file and removes it, if 
  15921.                                   possible. This is done because using the
  15922.                                   %@AB@%fseek%@AE@% and %@AB@%ftell%@AE@% functions to move within
  15923.                                   a file may cause %@AB@%fseek%@AE@% to behave 
  15924.                                   improperly near the end of the file.
  15925.  
  15926. %@AB@%b%@AE@%                                 Open in binary (untranslated) mode; the 
  15927.                                   above translations are suppressed.
  15928.  
  15929. If %@AB@%t%@AE@% or %@AB@%b%@AE@% is not given in the %@AI@%mode%@AE@% string, the translation mode is defined
  15930. by the default mode variable %@AB@%_fmode%@AE@%.  %@NL@%
  15931. %@NL@%
  15932. See Section 2.7, "Input and Output," for a discussion of text and binary
  15933. modes.  %@NL@%
  15934. %@NL@%
  15935. %@NL@%
  15936. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  15937. %@NL@%
  15938. The %@AB@%freopen%@AE@% function returns a pointer to the newly opened file. If an error
  15939. occurs, the original file is closed and the function returns a %@AB@%NULL%@AE@% pointer
  15940. value.  %@NL@%
  15941. %@NL@%
  15942. %@NL@%
  15943. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  15944. %@NL@%
  15945. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  15946. %@NL@%
  15947. %@NL@%
  15948. The %@AB@%t%@AE@% option is not part of the ANSI standard for %@AB@%freopen%@AE@%; it is a Microsoft
  15949. extension that should not be used where ANSI portability is desired.  %@NL@%
  15950. %@NL@%
  15951. %@NL@%
  15952. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  15953. %@NL@%
  15954. %@AB@%fclose%@AE@%, %@AB@%fcloseall%@AE@%, %@AB@%fdopen%@AE@%, %@AB@%fileno%@AE@%, %@AB@%fopen%@AE@%, %@AB@%open%@AE@%, %@AB@%setmode%@AE@%  %@NL@%
  15955. %@NL@%
  15956. %@NL@%
  15957. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  15958. %@NL@%
  15959. %@AS@%  /* FREOPEN.C: This program reassigns stdaux to the file
  15960. %@AS@%   * named FREOPEN.OUT and writes a line to that file.
  15961. %@AS@%   */%@AE@%%@NL@%
  15962. %@NL@%
  15963. %@AS@%  #include <stdio.h>
  15964. %@AS@%  #include <stdlib.h>
  15965. %@AS@%  
  15966. %@AS@%  FILE *stream;
  15967. %@AS@%  
  15968. %@AS@%  void main()
  15969. %@AS@%  {
  15970. %@AS@%  
  15971. %@AS@%     /* Reassign "stdaux" to "freopen.out": */
  15972. %@AS@%     stream = freopen( "freopen.out", "w", stdaux );
  15973. %@AS@%  
  15974. %@AS@%     if( stream == NULL )
  15975. %@AS@%        fprintf( stdout, "error on freopen\n" );
  15976. %@AS@%     else
  15977. %@AS@%     {
  15978. %@AS@%        fprintf( stream, "This will go to the file 'freopen.out'\n" );
  15979. %@AS@%        fprintf( stdout, "successfully reassigned\n" );
  15980. %@AS@%        fclose( stream );
  15981. %@AS@%     }
  15982. %@AS@%     system( "type freopen.out" );
  15983. %@AS@%  }%@AE@%%@NL@%
  15984. %@NL@%
  15985. %@NL@%
  15986. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  15987. %@NL@%
  15988. %@AS@%  
  15989. %@AS@%  
  15990. %@AS@%  successfully reassigned
  15991. %@AS@%  This will go to the file 'freopen.out' %@AE@%%@NL@%
  15992. %@NL@%
  15993. %@NL@%
  15994. %@NL@%
  15995. %@NL@%
  15996. %@QR:frexp@%%@QR:frexpl@%%@NL@%
  15997. %@2@%%@CR:C6A01180618 @%%@AB@%frexp, frexpl%@AE@%%@EH@%%@NL@%
  15998. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  15999. %@NL@%
  16000. %@NL@%
  16001. %@3@%%@AB@%Description%@CR:C6A01180619 @%%@CR:C6A01180620 @%%@CR:C6A01180621 @% %@CR:C6A01180622 @%%@AE@%%@EH@%%@NL@%
  16002. %@NL@%
  16003. Get the mantissa and exponent of a floating-point number.  %@NL@%
  16004. %@NL@%
  16005. %@AS@%  #include <math.h>%@AE@%%@NL@%
  16006. %@NL@%
  16007. %@AS@%  double frexp( double x, int *expptr );%@AE@%%@NL@%
  16008. %@NL@%
  16009. %@AS@%  long double frexpl( long double x, int *expptr );%@AE@%%@NL@%
  16010. %@NL@%
  16011. %@AI@%x%@AE@%                                 Floating-point value
  16012.  
  16013. %@AI@%expptr%@AE@%                            Pointer to stored integer exponent
  16014.  
  16015. %@NL@%
  16016. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16017. %@NL@%
  16018. The %@AB@%frexp%@AE@% and %@AB@%frexpl%@AE@% functions break down the floating-point value (%@AI@%x%@AE@%) into
  16019. a mantissa (%@AI@%m%@AE@%) and an exponent (%@AI@%n%@AE@%), such that the absolute value of %@AI@%m%@AE@% is
  16020. greater than or equal to 0.5 and less than 1.0, and %@AI@%x%@AE@% = %@AI@%m%@AE@%%@AB@%*%@AE@%2n. The integer
  16021. exponent %@AI@%n%@AE@% is stored at the location pointed to by %@AI@%expptr%@AE@%.  %@NL@%
  16022. %@NL@%
  16023. The %@AB@%frexpl%@AE@% function is the 80-bit counterpart and uses an 80-bit, 10-byte
  16024. coprocessor form of arguments and return values. See the reference page on
  16025. the long double functions for more details on this data type.  %@NL@%
  16026. %@NL@%
  16027. %@NL@%
  16028. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16029. %@NL@%
  16030. These functions return the mantissa. If %@AI@%x%@AE@% is 0, the function returns 0 for
  16031. both the mantissa and the exponent. There is no error return.  %@NL@%
  16032. %@NL@%
  16033. %@NL@%
  16034. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16035. %@NL@%
  16036. %@AB@%frexp%@AE@%  %@NL@%
  16037. %@NL@%
  16038. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  16039. %@NL@%
  16040. %@NL@%
  16041. %@AB@%frexpl%@AE@%  %@NL@%
  16042. %@NL@%
  16043.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  16044. %@NL@%
  16045. %@NL@%
  16046. %@NL@%
  16047. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16048. %@NL@%
  16049. %@AB@%ldexp%@AE@% functions, %@AB@%modf%@AE@%  %@NL@%
  16050. %@NL@%
  16051. %@NL@%
  16052. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16053. %@NL@%
  16054. %@AS@%  /* FREXP.C: This program calculates frexp( 16.4, &n ), then displays y
  16055. %@AS@%   * and n.
  16056. %@AS@%   */
  16057. %@AS@%  
  16058. %@AS@%  #include <math.h>
  16059. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16060. %@NL@%
  16061. %@AS@%  void main()
  16062. %@AS@%  {
  16063. %@AS@%     double x, y;
  16064. %@AS@%     int n;
  16065. %@AS@%  
  16066. %@AS@%     x = 16.4;
  16067. %@AS@%     y = frexp( x, &n );
  16068. %@AS@%     printf( "frexp( %f, &n ) = %f, n = %d\n", x, y, n );
  16069. %@AS@%  }%@AE@%%@NL@%
  16070. %@NL@%
  16071. %@NL@%
  16072. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16073. %@NL@%
  16074. %@AS@%  
  16075. %@AS@%  
  16076. %@AS@%  frexp( 16.400000, &n ) = 0.512500, n = 5 %@AE@%%@NL@%
  16077. %@NL@%
  16078. %@NL@%
  16079. %@NL@%
  16080. %@NL@%
  16081. %@QR:fscanf@%%@NL@%
  16082. %@2@%%@CR:C6A01190623 @%%@AB@%fscanf%@AE@%%@EH@%%@NL@%
  16083. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16084. %@NL@%
  16085. %@NL@%
  16086. %@3@%%@AB@%Description%@CR:C6A01190624 @%%@CR:C6A01190625 @% %@CR:C6A01190626 @%%@CR:C6A01190627 @% %@CR:C6A01190628 @%%@AE@%%@EH@%%@NL@%
  16087. %@NL@%
  16088. Reads formatted data from a stream.  %@NL@%
  16089. %@NL@%
  16090. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16091. %@NL@%
  16092. %@AS@%  int fscanf( FILE *stream, const char *format [[, argument]]...  )%@AE@%%@NL@%
  16093. %@NL@%
  16094. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  16095.  
  16096. %@AI@%format%@AE@%                            Format-control string
  16097.  
  16098. %@AI@%argument%@AE@%                          Optional arguments
  16099.  
  16100. %@NL@%
  16101. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16102. %@NL@%
  16103. The %@AB@%fscanf%@AE@% function reads data from the current position of %@AI@%stream%@AE@% into the
  16104. locations given by %@AI@%argument%@AE@% (if any). Each argument must be a pointer to a
  16105. variable with a type that corresponds to a type specifier in %@AI@%format%@AE@%. The
  16106. format controls the interpretation of the input fields and has the same form
  16107. and function as the %@AI@%format%@AE@% argument for the %@AB@%scanf%@AE@% function; see %@AB@%scanf%@AE@% for a
  16108. description of %@AI@%format%@AE@%.  %@NL@%
  16109. %@NL@%
  16110. %@NL@%
  16111. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16112. %@NL@%
  16113. The %@AB@%fscanf%@AE@% function returns the number of fields that were successfully
  16114. converted and assigned. The return value does not include fields that were
  16115. read but not assigned.  %@NL@%
  16116. %@NL@%
  16117. The return value is %@AB@%EOF%@AE@% for an error or end-of-file on %@AI@%stream%@AE@% before the
  16118. first conversion. A return value of 0 means that no fields were assigned.  %@NL@%
  16119. %@NL@%
  16120. %@NL@%
  16121. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16122. %@NL@%
  16123. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  16124. %@NL@%
  16125. %@NL@%
  16126. %@NL@%
  16127. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16128. %@NL@%
  16129. %@AB@%cscanf%@AE@%, %@AB@%fprintf%@AE@%, %@AB@%scanf%@AE@%, %@AB@%sscanf%@AE@%  %@NL@%
  16130. %@NL@%
  16131. %@NL@%
  16132. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16133. %@NL@%
  16134. %@AS@%  /* FSCANF.C: This program writes formatted data to a file. It
  16135. %@AS@%   * then uses fscanf to read the various data back from the file.
  16136. %@AS@%   */
  16137. %@AS@%  
  16138. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16139. %@NL@%
  16140. %@AS@%  FILE *stream;
  16141. %@AS@%  
  16142. %@AS@%  void main()
  16143. %@AS@%  {
  16144. %@AS@%     long l;
  16145. %@AS@%     float fp;
  16146. %@AS@%     char s[81];
  16147. %@AS@%     char c;
  16148. %@AS@%     int result;
  16149. %@AS@%  
  16150. %@AS@%     stream = fopen( "fscanf.out", "w+" );
  16151. %@AS@%     if( stream == NULL )
  16152. %@AS@%        printf( "The file fscanf.out was not opened\n" );
  16153. %@AS@%     else
  16154. %@AS@%     {
  16155. %@AS@%        fprintf( stream, "%s %ld %f%c", "a-string", 65000, 3.14159, 'x' );
  16156. %@AS@%  
  16157. %@AS@%        /* Set pointer to beginning of file: */
  16158. %@AS@%        fseek( stream, 0L, SEEK_SET );
  16159. %@AS@%  
  16160. %@AS@%        /* Read data back from file: */
  16161. %@AS@%        fscanf( stream, "%s", s );
  16162. %@AS@%        fscanf( stream, "%ld", &l );
  16163. %@AS@%        fscanf( stream, "%f", &fp );
  16164. %@AS@%        fscanf( stream, "%c", &c );
  16165. %@AS@%  
  16166. %@AS@%        /* Output data read: */
  16167. %@AS@%        printf( "%s\n", s );
  16168. %@AS@%        printf( "%ld\n", l );
  16169. %@AS@%        printf( "%f\n", fp );
  16170. %@AS@%        printf( "%c\n", c );
  16171. %@AS@%  
  16172. %@AS@%        fclose( stream );
  16173. %@AS@%     }
  16174. %@AS@%  }%@AE@%%@NL@%
  16175. %@NL@%
  16176. %@NL@%
  16177. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16178. %@NL@%
  16179. %@AS@%  
  16180. %@AS@%  
  16181. %@AS@%  a-string
  16182. %@AS@%  65000
  16183. %@AS@%  3.141590
  16184. %@AS@%  x %@AE@%%@NL@%
  16185. %@NL@%
  16186. %@NL@%
  16187. %@NL@%
  16188. %@NL@%
  16189. %@QR:fseek@%%@NL@%
  16190. %@2@%%@CR:C6A01200629 @%%@AB@%fseek%@AE@%%@EH@%%@NL@%
  16191. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16192. %@NL@%
  16193. %@NL@%
  16194. %@3@%%@AB@%Description%@CR:C6A01200630 @%%@CR:C6A01200631 @% %@CR:C6A01200632 @%%@CR:C6A01200633 @% %@CR:C6A01200634 @%%@AE@%%@EH@%%@NL@%
  16195. %@NL@%
  16196. Moves the file pointer to a specified location.  %@NL@%
  16197. %@NL@%
  16198. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16199. %@NL@%
  16200. %@AS@%  int fseek( FILE *stream, long offset, int origin );%@AE@%%@NL@%
  16201. %@NL@%
  16202. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  16203.  
  16204. %@AI@%offset%@AE@%                            Number of bytes from %@AI@%origin%@AE@%
  16205.  
  16206. %@AI@%origin%@AE@%                            Initial position
  16207.  
  16208. %@NL@%
  16209. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16210. %@NL@%
  16211. The %@AB@%fseek%@AE@% function moves the file pointer (if any) associated with %@AI@%stream%@AE@% to
  16212. a new location that is %@AI@%offset%@AE@% bytes from %@AI@%origin%@AE@%. The next operation on the
  16213. stream takes place at the new location. On a stream open for update, the
  16214. next operation can be either a read or a write.  %@NL@%
  16215. %@NL@%
  16216. The argument %@AI@%origin%@AE@% must be one of the following constants defined in
  16217. STDIO.H:  %@NL@%
  16218. %@NL@%
  16219. %@AB@%Origin%@AE@%                            %@AB@%Definition%@AE@%
  16220. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16221. %@AB@%SEEK_CUR%@AE@%                          Current position of file pointer
  16222.  
  16223. %@AB@%SEEK_END%@AE@%                          End of file
  16224.  
  16225. %@AB@%SEEK_SET%@AE@%                          Beginning of file
  16226.  
  16227. The %@AB@%fseek%@AE@% function can be used to reposition the pointer anywhere in a file.
  16228. The pointer can also be positioned beyond the end of the file. However, an
  16229. attempt to position the pointer in front of the beginning of the file causes
  16230. an error.  %@NL@%
  16231. %@NL@%
  16232. The %@AB@%fseek%@AE@% function clears the end-of-file indicator and negates the effect
  16233. of any prior %@AB@%ungetc%@AE@% calls against %@AI@%stream%@AE@%.  %@NL@%
  16234. %@NL@%
  16235. When a file is opened for appending data, the current file position is
  16236. determined by the last I/O operation, not by where the next write would
  16237. occur. If no I/O operation has yet occurred on a file opened for appending,
  16238. the file position is the start of the file.  %@NL@%
  16239. %@NL@%
  16240. For streams opened in text mode, %@AB@%fseek%@AE@% has limited use because
  16241. carriage-return-line-feed translations can cause %@AB@%fseek%@AE@% to produce unexpected
  16242. results. The only %@AB@%fseek%@AE@% operations guaranteed to work on streams opened in
  16243. text mode are the following:  %@NL@%
  16244. %@NL@%
  16245. %@NL@%
  16246.   ■   Seeking with an offset of 0 relative to any of the %@AI@%origin%@AE@% values%@NL@%
  16247. %@NL@%
  16248.   ■   Seeking from the beginning of the file with an offset value returned
  16249.       from a call to %@AB@%ftell%@AE@%%@NL@%
  16250. %@NL@%
  16251. %@NL@%
  16252. %@NL@%
  16253. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16254. %@NL@%
  16255. If successful, %@AB@%fseek%@AE@% returns 0. Otherwise, it returns a nonzero value. On
  16256. devices incapable of seeking, the return value is undefined.  %@NL@%
  16257. %@NL@%
  16258. %@NL@%
  16259. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16260. %@NL@%
  16261. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  16262. %@NL@%
  16263. %@NL@%
  16264. %@NL@%
  16265. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16266. %@NL@%
  16267. %@AB@%ftell%@AE@%, %@AB@%lseek%@AE@%, %@AB@%rewind%@AE@%  %@NL@%
  16268. %@NL@%
  16269. %@NL@%
  16270. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16271. %@NL@%
  16272. %@AS@%  /* FSEEK.C: This program opens the file FSEEK.OUT and
  16273. %@AS@%   * moves the pointer to the file's beginning.
  16274. %@AS@%   */
  16275. %@AS@%  
  16276. %@AS@%  #include <stdio.h>
  16277. %@AS@%  
  16278. %@AS@%  void main()
  16279. %@AS@%  {
  16280. %@AS@%     FILE *stream;
  16281. %@AS@%     char line[81];
  16282. %@AS@%     int  result;
  16283. %@AS@%  
  16284. %@AS@%     stream = fopen( "fseek.out", "w+" );
  16285. %@AS@%     if( stream == NULL )
  16286. %@AS@%        printf( "The file fseek.out was not opened\n" );
  16287. %@AS@%     else
  16288. %@AS@%     {
  16289. %@AS@%        fprintf( stream, "The fseek begins here: "
  16290. %@AS@%                         "This is the file 'fseek.out'.\n" );
  16291. %@AS@%        result = fseek( stream, 23L, SEEK_SET);
  16292. %@AS@%        if( result )
  16293. %@AS@%           perror( "Fseek failed" );
  16294. %@AS@%        else
  16295. %@AS@%        {
  16296. %@AS@%           printf( "File pointer is set to middle of first line.\n" );
  16297. %@AS@%           fgets( line, 80, stream );
  16298. %@AS@%           printf( "%s", line );
  16299. %@AS@%        }
  16300. %@AS@%        fclose( stream );
  16301. %@AS@%     }
  16302. %@AS@%  }%@AE@%%@NL@%
  16303. %@NL@%
  16304. %@NL@%
  16305. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16306. %@NL@%
  16307. %@AS@%  
  16308. %@AS@%  
  16309. %@AS@%  File pointer is set to middle of first line.
  16310. %@AS@%  This is the file 'fseek.out'. %@AE@%%@NL@%
  16311. %@NL@%
  16312. %@NL@%
  16313. %@NL@%
  16314. %@NL@%
  16315. %@QR:fsetpos@%%@NL@%
  16316. %@2@%%@CR:C6A01210635 @%%@AB@%fsetpos%@AE@%%@EH@%%@NL@%
  16317. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16318. %@NL@%
  16319. %@NL@%
  16320. %@3@%%@AB@%Description%@CR:C6A01210636 @%%@CR:C6A01210637 @% %@CR:C6A01210638 @%%@CR:C6A01210639 @% %@CR:C6A01210640 @%%@AE@%%@EH@%%@NL@%
  16321. %@NL@%
  16322. Sets the stream-position indicator.  %@NL@%
  16323. %@NL@%
  16324. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16325. %@NL@%
  16326. %@AS@%  int fsetpos( FILE *stream, const fpos_t *pos ) ;%@AE@%%@NL@%
  16327. %@NL@%
  16328. %@AI@%stream%@AE@%                            Target stream
  16329.  
  16330. %@AI@%pos%@AE@%                               Position-indicator storage
  16331.  
  16332. %@NL@%
  16333. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16334. %@NL@%
  16335. The %@AB@%fsetpos%@AE@% function sets the file-position indicator for %@AI@%stream%@AE@% to the
  16336. value of %@AI@%pos%@AE@%, which is obtained in a prior call to %@AB@%fgetpos%@AE@% against %@AI@%stream%@AE@%.  %@NL@%
  16337. %@NL@%
  16338. The function clears the end-of-file indicator and undoes any effects of the
  16339. %@AB@%ungetc%@AE@% function on %@AI@%stream%@AE@%. After calling %@AB@%fsetpos%@AE@%, the next operation on
  16340. %@AI@%stream%@AE@% may be either input or output.  %@NL@%
  16341. %@NL@%
  16342. %@NL@%
  16343. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16344. %@NL@%
  16345. If successful, the %@AB@%fsetpos%@AE@% function returns 0. On failure, the function
  16346. returns a nonzero value and sets %@AB@%errno%@AE@% to one of the following manifest
  16347. constants (defined in ERRNO.H):  %@NL@%
  16348. %@NL@%
  16349. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  16350. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16351. %@AB@%EBADF%@AE@%                             The object that %@AI@%stream%@AE@% points to is not 
  16352.                                   a valid file handle, or the file is not 
  16353.                                   accessible.
  16354.  
  16355. %@AB@%EINVAL%@AE@%                            An invalid %@AI@%stream%@AE@% value was passed.
  16356.  
  16357. %@NL@%
  16358. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16359. %@NL@%
  16360. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  16361. %@NL@%
  16362. %@NL@%
  16363. %@NL@%
  16364. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16365. %@NL@%
  16366. %@AB@%fgetpos%@AE@%  %@NL@%
  16367. %@NL@%
  16368. %@NL@%
  16369. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16370. %@NL@%
  16371. %@AS@%  /* FGETPOS.C: This program opens a file and reads bytes at several
  16372. %@AS@%   * different locations.
  16373. %@AS@%   */
  16374. %@AS@%  
  16375. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16376. %@NL@%
  16377. %@AS@%  void main()
  16378. %@AS@%  {
  16379. %@AS@%     FILE   *stream;
  16380. %@AS@%     fpos_t pos;
  16381. %@AS@%     int    val;
  16382. %@AS@%     char   buffer[20];
  16383. %@AS@%  
  16384. %@AS@%     if( (stream = fopen( "fgetpos.c", "rb" )) == NULL )
  16385. %@AS@%        printf( "Trouble opening file\n" );
  16386. %@AS@%     else
  16387. %@AS@%     {
  16388. %@AS@%        /* Read some data and then check the position. */
  16389. %@AS@%        fread( buffer, sizeof( char ), 10, stream );
  16390. %@AS@%        if( fgetpos( stream, &pos ) != 0 )
  16391. %@AS@%           perror( "fgetpos error" );
  16392. %@AS@%        else
  16393. %@AS@%        {
  16394. %@AS@%           fread( buffer, sizeof( char ), 10, stream );
  16395. %@AS@%           printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );
  16396. %@AS@%        }
  16397. %@AS@%  
  16398. %@AS@%        /* Set a new position and read more data. */
  16399. %@AS@%        pos = 140;
  16400. %@AS@%        if( fsetpos( stream, &pos ) != 0 )
  16401. %@AS@%           perror( "fsetpos error" );
  16402. %@AS@%  
  16403. %@AS@%        fread( buffer, sizeof( char ), 10, stream );
  16404. %@AS@%           printf( "10 bytes at byte %ld: %.10s\n", pos, buffer );
  16405. %@AS@%  
  16406. %@AS@%        fclose( stream );
  16407. %@AS@%     }
  16408. %@AS@%  }%@AE@%%@NL@%
  16409. %@NL@%
  16410. %@NL@%
  16411. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16412. %@NL@%
  16413. %@AS@%  
  16414. %@AS@%  
  16415. %@AS@%  10 bytes at byte 10: .C: This p
  16416. %@AS@%  10 bytes at byte 140:   FILE   * %@AE@%%@NL@%
  16417. %@NL@%
  16418. %@NL@%
  16419. %@NL@%
  16420. %@NL@%
  16421. %@QR:_fsopen@%%@NL@%
  16422. %@2@%%@CR:C6A01220641 @%%@AB@%_fsopen%@AE@%%@EH@%%@NL@%
  16423. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16424. %@NL@%
  16425. %@NL@%
  16426. %@3@%%@AB@%Description%@CR:C6A01220642 @%%@CR:C6A01220643 @% %@CR:C6A01220644 @%%@CR:C6A01220645 @%%@CR:C6A01220646 @%%@CR:C6A01220647 @% %@CR:C6A01220648 @%%@AE@%%@EH@%%@NL@%
  16427. %@NL@%
  16428. Opens a stream with file sharing.  %@NL@%
  16429. %@NL@%
  16430. %@AB@%#include <stdio.h>%@AE@%                
  16431.  
  16432. %@AB@%#include <share.h>%@AE@%                %@AI@%shflag%@AE@% constants
  16433.  
  16434. %@AS@%  FILE *_fsopen( const char *filename, const char *mode, int shflag );%@AE@%%@NL@%
  16435. %@NL@%
  16436. %@AI@%filename%@AE@%                          File name to open
  16437.  
  16438. %@AI@%mode%@AE@%                              Type of access permitted
  16439.  
  16440. %@AI@%shflag%@AE@%                            Type of sharing allowed
  16441.  
  16442. %@NL@%
  16443. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16444. %@NL@%
  16445. The %@AB@%_fsopen%@AE@% function opens the file specified by %@AI@%filename%@AE@% as a stream and
  16446. prepares the file for subsequent shared reading or writing, as defined by
  16447. the %@AI@%mode%@AE@% and %@AI@%shflag%@AE@% arguments.  %@NL@%
  16448. %@NL@%
  16449. The character string %@AI@%mode%@AE@% specifies the type of access requested for the
  16450. file, as follows:  %@NL@%
  16451. %@NL@%
  16452. %@AB@%Type%@AE@%                              %@AB@%Description%@AE@%
  16453. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16454. %@AB@%"r"%@AE@%                               Opens for reading. If the file does not 
  16455.                                   exist or cannot be found, the %@AB@%_fsopen%@AE@% 
  16456.                                   call will fail.
  16457.  
  16458. %@AB@%"w"%@AE@%                               Opens an empty file for writing. If the 
  16459.                                   given file exists, its contents are 
  16460.                                   destroyed. 
  16461.  
  16462. %@AB@%"a"%@AE@%                               Opens for writing at the end of the file
  16463.                                   (appending); creates the file first if 
  16464.                                   it does not exist.
  16465.  
  16466. %@AB@%"r+"%@AE@%                              Opens for both reading and writing. (The
  16467.                                   file must exist.)
  16468.  
  16469. %@AB@%"w+"%@AE@%                              Opens an empty file for both reading and
  16470.                                   writing. If the given file exists, its 
  16471.                                   contents are destroyed.
  16472.  
  16473. %@AB@%"a+"%@AE@%                              Opens for reading and appending; creates
  16474.                                   the file first if it does not exist.
  16475.  
  16476. Use the %@AB@%"w"%@AE@% and %@AB@%"w+"%@AE@% types with care, as they can destroy existing files.  %@NL@%
  16477. %@NL@%
  16478. When a file is opened with the %@AB@%"a"%@AE@% or %@AB@%"a+"%@AE@% access type, all write operations
  16479. occur at the end of the file. Although the file pointer can be repositioned
  16480. using %@AB@%fseek%@AE@% or%@AB@% rewind%@AE@%, the file pointer is always moved back to the end of
  16481. the file before any write operation is carried out. Thus, existing data
  16482. cannot be overwritten.  %@NL@%
  16483. %@NL@%
  16484. When the %@AB@%"r+"%@AE@%, %@AB@%"w+"%@AE@%, or %@AB@%"a+" %@AE@% access type is specified, both reading and
  16485. writing are allowed (the file is said to be open for "update"). However,
  16486. when switching between reading and writing, there must be an intervening
  16487. %@AB@%fsetpos%@AE@%, %@AB@%fseek%@AE@%, or %@AB@%rewind%@AE@% operation. The current position can be specified
  16488. for the %@AB@%fsetpos%@AE@% or %@AB@%fseek%@AE@% operation, if desired.  %@NL@%
  16489. %@NL@%
  16490. In addition to the values listed above, one of the following characters can
  16491. be included in %@AI@%mode%@AE@% to specify the translation mode for newlines: %@CR:C6A01220649 @%%@CR:C6A01220650 @%%@CR:C6A01220651 @%%@CR:C6A01220652 @%  %@NL@%
  16492. %@NL@%
  16493. %@AB@%Mode%@AE@%                              %@AB@%Meaning%@AE@%
  16494. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16495. %@AB@%t%@AE@%                                 Open in text (translated) mode. In this 
  16496.                                   mode, carriage-return-line-feed (CR-LF) 
  16497.                                   combinations are translated into single 
  16498.                                   line feeds (LF) on input and LF 
  16499.                                   characters are translated to CR-LF 
  16500.                                   combinations on output. Also, CTRL+Z is 
  16501.                                   interpreted as an end-of-file character 
  16502.                                   on input. In files opened for reading or
  16503.                                   reading/writing, %@AB@%_fsopen%@AE@% checks for a 
  16504.                                   CTRL+Z at the end of the file and 
  16505.                                   removes it, if possible. This is done 
  16506.                                   because using the %@AB@%fseek%@AE@% and %@AB@%ftell%@AE@% 
  16507.                                   functions to move within a file that 
  16508.                                   ends with a CTRL+Z may cause %@AB@%fseek%@AE@% to 
  16509.                                   behave improperly near the end of the 
  16510.                                   file.
  16511.  
  16512. %@AB@%b%@AE@%                                 Open in binary (untranslated) mode; the 
  16513.                                   above translations are suppressed.
  16514.  
  16515. If %@AB@%t%@AE@% or %@AB@%b%@AE@% is not given in %@AI@%mode%@AE@%, the translation mode is defined by the
  16516. default-mode variable %@AB@%_fmode%@AE@%. If %@AB@%t%@AE@% or %@AB@%b%@AE@% is prefixed to the argument, the
  16517. function will fail and will return %@AB@%NULL%@AE@%.  %@NL@%
  16518. %@NL@%
  16519. See Section 2.7, "Input and Output," for a discussion of text and binary
  16520. modes.  %@NL@%
  16521. %@NL@%
  16522. The argument %@AI@%shflag%@AE@% is a constant expression consisting of one of the
  16523. following manifest constants, defined in SHARE.H.  If SHARE.COM ─or
  16524. SHARE.EXE for some versions of DOS─ is not installed, DOS ignores the
  16525. sharing mode. (See your system documentation for detailed information about
  16526. sharing modes.)  %@NL@%
  16527. %@NL@%
  16528. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  16529. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16530. %@AB@%SH_COMPAT%@AE@%                         Sets compatibility mode (not available 
  16531.                                   in OS/2)
  16532.  
  16533. %@AB@%SH_DENYNO%@AE@%                         Permits read and write access
  16534.  
  16535. %@AB@%SH_DENYRD%@AE@%                         Denies read access to file
  16536.  
  16537. %@AB@%SH_DENYRW%@AE@%                         Denies read and write access to file
  16538.  
  16539. %@AB@%SH_DENYWR%@AE@%                         Denies write access to file
  16540.  
  16541. The %@AB@%_fsopen%@AE@% function should be used only under OS/2 and DOS versions 3.0 and
  16542. later. Under earlier versions of DOS, the %@AI@%shflag%@AE@% argument is ignored.  %@NL@%
  16543. %@NL@%
  16544. %@NL@%
  16545. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16546. %@NL@%
  16547. The %@AB@%_fsopen%@AE@% function returns a pointer to the stream. A %@AB@%NULL%@AE@% pointer value
  16548. indicates an error.  %@NL@%
  16549. %@NL@%
  16550. %@NL@%
  16551. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16552. %@NL@%
  16553.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  16554. %@NL@%
  16555. %@NL@%
  16556. %@NL@%
  16557. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16558. %@NL@%
  16559. %@AB@%fclose%@AE@%, %@AB@%fcloseall%@AE@%, %@AB@%fdopen%@AE@%, %@AB@%ferror%@AE@%, %@AB@%fileno%@AE@%, %@AB@%fopen%@AE@%, %@AB@%freopen%@AE@%, %@AB@%open%@AE@%, %@AB@%setmode%@AE@%,
  16560. %@AB@%sopen%@AE@%  %@NL@%
  16561. %@NL@%
  16562. %@NL@%
  16563. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16564. %@NL@%
  16565. %@AS@%  /* FSOPEN.C: This program opens files named "data" and "data2". It uses
  16566. %@AS@%   * fclose to close "data" and fcloseall to close all remaining files.
  16567. %@AS@%   */
  16568. %@AS@%  
  16569. %@AS@%  #include <stdio.h>
  16570. %@AS@%  #include <share.h>
  16571. %@AS@%  
  16572. %@AS@%  FILE *stream;
  16573. %@AS@%  
  16574. %@AS@%  void main()
  16575. %@AS@%  {
  16576. %@AS@%     FILE *stream;
  16577. %@AS@%  
  16578. %@AS@%     /* Open output file for writing. Using _fsopen allows us to ensure
  16579. %@AS@%      * that no one else writes to the file while we are writing to it.
  16580. %@AS@%      */
  16581. %@AS@%     if( (stream = _fsopen( "outfile", "wt", SH_DENYWR )) != NULL )
  16582. %@AS@%     {
  16583. %@AS@%        fprintf( stream, "No one else in the network can write "
  16584. %@AS@%                         "to this file until we are done.\n" );
  16585. %@AS@%        fclose( stream );
  16586. %@AS@%     }
  16587. %@AS@%     /* Now others can write to the file while we read it. */
  16588. %@AS@%     system( "type outfile" );
  16589. %@AS@%  }%@AE@%%@NL@%
  16590. %@NL@%
  16591. %@NL@%
  16592. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16593. %@NL@%
  16594. %@AS@%  
  16595. %@AS@%  
  16596. %@AS@%  No one else in the network can write to this file until we are done. %@AE@%%@NL@%
  16597. %@NL@%
  16598. %@NL@%
  16599. %@NL@%
  16600. %@NL@%
  16601. %@QR:fstat@%%@NL@%
  16602. %@2@%%@CR:C6A01230653 @%%@AB@%fstat%@AE@%%@EH@%%@NL@%
  16603. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16604. %@NL@%
  16605. %@NL@%
  16606. %@3@%%@AB@%Description%@CR:C6A01230654 @%%@CR:C6A01230655 @%%@CR:C6A01230656 @% %@CR:C6A01230657 @%%@AE@%%@EH@%%@NL@%
  16607. %@NL@%
  16608. Gets information about an open file.  %@NL@%
  16609. %@NL@%
  16610. %@AS@%  #include <sys\types.h>%@AE@%%@NL@%
  16611. %@NL@%
  16612. %@AS@%  #include <sys\stat.h>%@AE@%%@NL@%
  16613. %@NL@%
  16614. %@AS@%  int fstat( int handle, struct stat *buffer );%@AE@%%@NL@%
  16615. %@NL@%
  16616. %@AI@%handle%@AE@%                            Handle of open file
  16617.  
  16618. %@AI@%buffer%@AE@%                            Pointer to structure to store results
  16619.  
  16620. %@NL@%
  16621. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16622. %@NL@%
  16623. The %@AB@%fstat%@AE@% function obtains information about the open file associated with
  16624. %@AI@%handle%@AE@% and stores it in the structure pointed to by %@AI@%buffer%@AE@%. The structure,
  16625. whose type %@AB@%stat%@AE@% is defined in SYS\STAT.H, contains the following fields:   %@CR:C6A01230658 @%
  16626. %@NL@%
  16627. %@NL@%
  16628. %@AB@%Field%@AE@%                             %@AB@%Value%@AE@%
  16629. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16630. %@AB@%st_atime%@AE@%                          Time of last modification of file (same 
  16631.                                   as %@AB@%st_mtime%@AE@% and %@AB@%st_ctime%@AE@%).
  16632.  
  16633. %@AB@%st_ctime%@AE@%                          Time of last modification of file (same 
  16634.                                   as %@AB@%st_atime%@AE@% and %@AB@%st_mtime%@AE@%).
  16635.  
  16636. %@AB@%st_dev%@AE@%                            Either the drive number of the disk 
  16637.                                   containing the file, or %@AI@%handle%@AE@% in the 
  16638.                                   case of a device (same as %@AB@%st_rdev%@AE@%).
  16639.  
  16640. %@AB@%st_mode%@AE@%                           Bit mask for file-mode information. The %@AB@%%@AE@%
  16641.                                   %@AB@%S_IFCHR%@AE@% bit is set if%@AI@%%@AE@%
  16642.                                   %@AI@%handle%@AE@% refers to a device. The %@AB@%S_IFREG%@AE@% 
  16643.                                   bit is set if %@AI@%handle%@AE@% refers to an 
  16644.                                   ordinary file. The read/write bits are 
  16645.                                   set according to the file's permission 
  16646.                                   mode. (%@AB@%S_IFCHR%@AE@% and other constants are 
  16647.                                   defined in SYS\ STAT.H.)
  16648.  
  16649. %@AB@%st_mtime%@AE@%                          Time of last modification of file (same 
  16650.                                   as %@AB@%st_atime%@AE@% and %@AB@%st_ctime%@AE@%).
  16651.  
  16652. %@AB@%st_nlink%@AE@%                          Always 1.
  16653.  
  16654. %@AB@%st_rdev%@AE@%                           Either the drive number of the disk 
  16655.                                   containing the file, or %@AI@%handle%@AE@% in the 
  16656.                                   case of a device (same as %@AB@%st_dev%@AE@%).
  16657.  
  16658. %@AB@%st_size%@AE@%                           Size of the file in bytes.
  16659.  
  16660. If %@AI@%handle%@AE@% refers to a device, the size and time fields in the %@AB@%stat %@AE@%structure
  16661. are not meaningful.  %@NL@%
  16662. %@NL@%
  16663. %@NL@%
  16664. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16665. %@NL@%
  16666. The %@AB@%fstat%@AE@% function returns the value 0 if the file-status information is
  16667. obtained. A return value of -1 indicates an error; in this case, %@AB@%errno%@AE@% is
  16668. set to %@AB@%EBADF%@AE@%, indicating an invalid file handle.  %@NL@%
  16669. %@NL@%
  16670. %@NL@%
  16671. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16672. %@NL@%
  16673.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  16674. %@NL@%
  16675. %@NL@%
  16676. In OS/2, the %@AB@%st_dev%@AE@% field does not contain meaningful information. In fact,
  16677. it is set to zero. OS/2 provides no way to recover the host drive from just
  16678. the open file handle.  %@NL@%
  16679. %@NL@%
  16680. %@NL@%
  16681. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16682. %@NL@%
  16683. %@AB@%access, chmod, filelength%@AE@%, %@AB@%stat%@AE@%  %@NL@%
  16684. %@NL@%
  16685. %@NL@%
  16686. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16687. %@NL@%
  16688. %@AS@%  /* FSTAT.C: This program uses fstat to report the size of a file
  16689. %@AS@%   * named FSTAT.OUT.
  16690. %@AS@%   */
  16691. %@AS@%  
  16692. %@AS@%  #include <io.h>
  16693. %@AS@%  #include <fcntl.h>
  16694. %@AS@%  #include <time.h>
  16695. %@AS@%  #include <sys\types.h>
  16696. %@AS@%  #include <sys\stat.h>
  16697. %@AS@%  #include <stdio.h>
  16698. %@AS@%  #include <stdlib.h>
  16699. %@AS@%  #include <string.h>
  16700. %@AS@%  
  16701. %@AS@%  void main()
  16702. %@AS@%  {
  16703. %@AS@%     struct stat buf;
  16704. %@AS@%     int fh, result;
  16705. %@AS@%     char buffer[] = "A line to output";
  16706. %@AS@%  
  16707. %@AS@%     if( (fh = open( "fstat.out", O_CREAT | O_WRONLY | O_TRUNC )) == -1 )
  16708. %@AS@%        exit( 1 );
  16709. %@AS@%     write( fh, buffer, strlen( buffer ) );
  16710. %@AS@%  
  16711. %@AS@%     /* Get data associated with "fh": */
  16712. %@AS@%  
  16713. %@AS@%     result = fstat( fh, &buf );%@AE@%%@NL@%
  16714. %@NL@%
  16715. %@AS@%  /* Check if statistics are valid: */
  16716. %@AS@%     if( result != 0 )
  16717. %@AS@%        printf( "Bad file handle\n" );
  16718. %@AS@%     else
  16719. %@AS@%     {
  16720. %@AS@%        printf( "File size     : %ld\n", buf.st_size );
  16721. %@AS@%        printf( "Drive number  : %d\n", buf.st_dev );
  16722. %@AS@%        printf( "Time modified : %s", ctime( &buf.st_atime ) );
  16723. %@AS@%     }
  16724. %@AS@%     close( fh );
  16725. %@AS@%  }%@AE@%%@NL@%
  16726. %@NL@%
  16727. %@NL@%
  16728. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16729. %@NL@%
  16730. %@AS@%  
  16731. %@AS@%  
  16732. %@AS@%  File size     : 16
  16733. %@AS@%  Drive number  : 0
  16734. %@AS@%  Time modified : Thu Jun 15 21:38:46 1989 %@AE@%%@NL@%
  16735. %@NL@%
  16736. %@NL@%
  16737. %@NL@%
  16738. %@NL@%
  16739. %@QR:ftell@%%@NL@%
  16740. %@2@%%@CR:C6A01240659 @%%@AB@%ftell%@AE@%%@EH@%%@NL@%
  16741. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16742. %@NL@%
  16743. %@NL@%
  16744. %@3@%%@AB@%Description%@CR:C6A01240660 @%%@CR:C6A01240661 @% %@CR:C6A01240662 @%%@CR:C6A01240663 @% %@CR:C6A01240664 @%%@AE@%%@EH@%%@NL@%
  16745. %@NL@%
  16746. Gets the current position of a file pointer.  %@NL@%
  16747. %@NL@%
  16748. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  16749. %@NL@%
  16750. %@AS@%  long ftell( FILE *stream );%@AE@%%@NL@%
  16751. %@NL@%
  16752. %@AI@%stream%@AE@%                            Target %@AB@%FILE structure%@AE@%
  16753.  
  16754. %@NL@%
  16755. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16756. %@NL@%
  16757. The %@AB@%ftell%@AE@% function gets the current position of the file pointer (if any)
  16758. associated with %@AI@%stream%@AE@%. The position is expressed as an offset relative to
  16759. the beginning of the stream.  %@NL@%
  16760. %@NL@%
  16761. Note that when a file is opened for appending data, the current file
  16762. position is determined by the last I/O operation, not by where the next
  16763. write would occur. For example, if a file is opened for an append and the
  16764. last operation was a read, the file position is the point where the next
  16765. read operation would start, not where the next write would start. (When a
  16766. file is opened for appending, the file position is moved to end-of-file
  16767. before any write operation.) If no I/O operation has yet occurred on a file
  16768. opened for appending, the file position is the beginning of the file.  %@NL@%
  16769. %@NL@%
  16770. %@NL@%
  16771. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16772. %@NL@%
  16773. The %@AB@%ftell%@AE@% function returns the current file position. The value returned by
  16774. %@AB@%ftell%@AE@% may not reflect the physical byte offset for streams opened in text
  16775. mode, since text mode causes carriage-return-line-feed translation. Use
  16776. %@AB@%ftell%@AE@% in conjunction with the %@AB@%fseek%@AE@% function to return to file locations
  16777. correctly. On error, the function returns -1L and %@AB@%errno%@AE@% is set to one of the
  16778. following constants, defined in ERRNO.H:  %@NL@%
  16779. %@NL@%
  16780. %@AB@%Constant%@AE@%                          %@AB@%Description%@AE@%
  16781. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16782. %@AB@%EBADF%@AE@%                             Bad file number. The %@AI@%stream%@AE@% argument is 
  16783.                                   not a valid file-handle value or does 
  16784.                                   not refer to an open file.
  16785.  
  16786. %@AB@%EINVAL%@AE@%                            Invalid argument. An invalid %@AI@%stream%@AE@% 
  16787.                                   argument was passed to the function.
  16788.  
  16789. On devices incapable of seeking (such as terminals and printers), or when
  16790. %@AI@%stream%@AE@% does not refer to an open file, the return value is undefined.  %@NL@%
  16791. %@NL@%
  16792. %@NL@%
  16793. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16794. %@NL@%
  16795. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  16796. %@NL@%
  16797. %@NL@%
  16798. %@NL@%
  16799. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16800. %@NL@%
  16801. %@AB@%fgetpos%@AE@%, %@AB@%fseek%@AE@%, %@AB@%lseek%@AE@%, %@AB@%tell%@AE@%  %@NL@%
  16802. %@NL@%
  16803. %@NL@%
  16804. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16805. %@NL@%
  16806. %@AS@%  /* FTELL.C: This program opens a file named FTELL.C for reading and
  16807. %@AS@%   * tries to read 100 characters. It then uses ftell to determine the
  16808. %@AS@%   * position of the file pointer and displays this position.
  16809. %@AS@%   */
  16810. %@AS@%  
  16811. %@AS@%  #include <stdio.h>
  16812. %@AS@%  
  16813. %@AS@%  FILE *stream;
  16814. %@AS@%  
  16815. %@AS@%  void main()
  16816. %@AS@%  {
  16817. %@AS@%     long position;
  16818. %@AS@%     char list[100];
  16819. %@AS@%  
  16820. %@AS@%     if( (stream = fopen( "ftell.c", "rb" )) != NULL )
  16821. %@AS@%     {
  16822. %@AS@%        /* Move the pointer by reading data: */
  16823. %@AS@%        fread( list, sizeof( char ), 100, stream );
  16824. %@AS@%  
  16825. %@AS@%        /* Get position after read: */
  16826. %@AS@%        position = ftell( stream );
  16827. %@AS@%        printf( "Position after trying to read 100 bytes: %ld\n", position
  16828. %@AS@%);
  16829. %@AS@%        fclose( stream );
  16830. %@AS@%     }
  16831. %@AS@%  }%@AE@%%@NL@%
  16832. %@NL@%
  16833. %@NL@%
  16834. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16835. %@NL@%
  16836. %@AS@%  
  16837. %@AS@%  
  16838. %@AS@%  Position after trying to read 100 bytes: 100 %@AE@%%@NL@%
  16839. %@NL@%
  16840. %@NL@%
  16841. %@NL@%
  16842. %@NL@%
  16843. %@QR:ftime@%%@NL@%
  16844. %@2@%%@CR:C6A01250665 @%%@AB@%ftime%@AE@%%@EH@%%@NL@%
  16845. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16846. %@NL@%
  16847. %@NL@%
  16848. %@3@%%@AB@%Description%@CR:C6A01250666 @%%@CR:C6A01250667 @%%@CR:C6A01250668 @%%@AE@%%@EH@%%@NL@%
  16849. %@NL@%
  16850. Gets the current time.  %@NL@%
  16851. %@NL@%
  16852. %@AS@%  #include <sys\types.h>%@AE@%%@NL@%
  16853. %@NL@%
  16854. %@AS@%  #include <sys\timeb.h>%@AE@%%@NL@%
  16855. %@NL@%
  16856. %@AS@%  void ftime( struct timeb *timeptr );%@AE@%%@NL@%
  16857. %@NL@%
  16858. %@AI@%timeptr%@AE@%                           Pointer to structure defined in 
  16859.                                   SYS\TIMEB.H
  16860.  
  16861. %@NL@%
  16862. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16863. %@NL@%
  16864. The %@AB@%ftime%@AE@% function gets the current time and stores it in the structure
  16865. pointed to by %@AI@%timeptr%@AE@%. The %@AB@%timeb%@AE@% structure is defined in SYS\TIMEB.H. It
  16866. contains four fields (%@AB@%dstflag%@AE@%, %@AB@%millitm%@AE@%, %@AB@%time%@AE@%, and %@AB@%timezone%@AE@%), which have the
  16867. following values: %@CR:C6A01250669 @%%@CR:C6A01250670 @%  %@NL@%
  16868. %@NL@%
  16869. %@AB@%Field%@AE@%                             %@AB@%Value%@AE@%
  16870. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16871. %@AB@%dstflag%@AE@%                           Nonzero if daylight saving time is 
  16872.                                   currently in effect for the local time 
  16873.                                   zone. (See %@AB@%tzset%@AE@% for an explanation of 
  16874.                                   how daylight saving time is determined.)
  16875.  
  16876. %@AB@%millitm%@AE@%                           Fraction of a second in milliseconds. 
  16877.                                   The last digit is always 0 since %@AB@%millitm%@AE@%
  16878.                                   is incremented to the nearest 
  16879.                                   one-hundredth of a second.
  16880.  
  16881. %@AB@%time%@AE@%                              Time in seconds since 00:00:00 Greenwich
  16882.                                   mean time, January 1, 1970.
  16883.  
  16884. %@AB@%timezone%@AE@%                          Difference in minutes, moving westward, 
  16885.                                   between Greenwich mean time and local 
  16886.                                   time. The value of %@AB@%timezone%@AE@% is set from 
  16887.                                   the value of the global variable %@AB@%%@AE@%
  16888.                                   %@AB@%timezone%@AE@% (see %@AB@%tzset%@AE@%).
  16889.  
  16890. %@NL@%
  16891. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16892. %@NL@%
  16893. The %@AB@%ftime%@AE@% function gives values to the fields in the structure pointed to by
  16894. %@AI@%timeptr%@AE@%. It does not return a value.  %@NL@%
  16895. %@NL@%
  16896. %@NL@%
  16897. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16898. %@NL@%
  16899.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  16900. %@NL@%
  16901. %@NL@%
  16902. %@NL@%
  16903. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16904. %@NL@%
  16905. %@AB@%asctime%@AE@%, %@AB@%ctime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%time%@AE@%, %@AB@%tzset%@AE@%  %@NL@%
  16906. %@NL@%
  16907. %@NL@%
  16908. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16909. %@NL@%
  16910. %@AS@%  /* FTIME.C: This program uses ftime to obtain the current time
  16911. %@AS@%   * and then stores this time in timebuffer.
  16912. %@AS@%   */
  16913. %@AS@%  
  16914. %@AS@%  #include <stdio.h>
  16915. %@AS@%  #include <sys\timeb.h>
  16916. %@AS@%  #include <time.h>
  16917. %@AS@%  
  16918. %@AS@%  void main()
  16919. %@AS@%  {
  16920. %@AS@%  
  16921. %@AS@%     struct timeb timebuffer;
  16922. %@AS@%     char *timeline;
  16923. %@AS@%  
  16924. %@AS@%     ftime( &timebuffer );
  16925. %@AS@%     timeline = ctime( & ( timebuffer.time ) );
  16926. %@AS@%  
  16927. %@AS@%     printf( "The time is %.19s.%hu %s",
  16928. %@AS@%             timeline, timebuffer.millitm, &timeline[20] );
  16929. %@AS@%  }%@AE@%%@NL@%
  16930. %@NL@%
  16931. %@NL@%
  16932. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  16933. %@NL@%
  16934. %@AS@%  
  16935. %@AS@%  
  16936. %@AS@%  The time is Thu Jun 15 21:40:34.870 1989 %@AE@%%@NL@%
  16937. %@NL@%
  16938. %@NL@%
  16939. %@NL@%
  16940. %@NL@%
  16941. %@QR:_fullpath@%%@NL@%
  16942. %@2@%%@CR:C6A01260671 @%%@AB@%_fullpath%@AE@%%@EH@%%@NL@%
  16943. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  16944. %@NL@%
  16945. %@NL@%
  16946. %@3@%%@AB@%Description%@CR:C6A01260672 @%%@AE@%%@EH@%%@NL@%
  16947. %@NL@%
  16948. Makes an absolute path name from a relative path name.  %@NL@%
  16949. %@NL@%
  16950. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  16951. %@NL@%
  16952. %@AS@%  char *_fullpath( char *buffer, const char *pathname, size_t maxlen );%@AE@%%@NL@%
  16953. %@NL@%
  16954. %@AI@%buffer%@AE@%                            Full path-name buffer
  16955.  
  16956. %@AI@%pathname%@AE@%                          Relative path name
  16957.  
  16958. %@AI@%maxlen%@AE@%                            Length of the buffer pointed to by %@AI@%%@AE@%
  16959.                                   %@AI@%buffer%@AE@%
  16960.  
  16961. %@NL@%
  16962. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  16963. %@NL@%
  16964. The %@AB@%_fullpath%@AE@% routine converts the partial path stored in %@AI@%pathname%@AE@% to a
  16965. fully qualified path that is stored in %@AI@%buffer%@AE@%. Unlike %@AB@%_makepath%@AE@%, the
  16966. %@AB@%_fullpath%@AE@% routine can be used with %@AB@%.\%@AE@% and %@AB@%..\%@AE@% in the path.  %@NL@%
  16967. %@NL@%
  16968. If the length of the fully qualified path is greater than the value of
  16969. %@AI@%maxlen%@AE@%, then %@AB@%NULL%@AE@% is returned; otherwise, the address of %@AI@%buffer%@AE@% is returned.
  16970. %@NL@%
  16971. %@NL@%
  16972. If the %@AI@%buffer%@AE@% is %@AB@%NULL%@AE@%, %@AB@%_fullpath%@AE@% will allocate a buffer of %@AB@%MAX_PATH%@AE@% size and
  16973. the %@AI@%maxlen%@AE@% argument is ignored.  %@NL@%
  16974. %@NL@%
  16975. If the %@AI@%pathname%@AE@% argument specifies a disk drive, the current directory of
  16976. this drive is combined with the path. If the drive is not valid, %@AB@%_fullpath%@AE@%
  16977. returns %@AB@%NULL%@AE@%.  %@NL@%
  16978. %@NL@%
  16979. %@NL@%
  16980. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  16981. %@NL@%
  16982. The %@AB@%_fullpath%@AE@% function returns a pointer to the buffer containing the
  16983. absolute path (%@AI@%buffer%@AE@%). If there is an error, %@AB@%_fullpath%@AE@% returns %@AB@%NULL%@AE@%.  %@NL@%
  16984. %@NL@%
  16985. %@NL@%
  16986. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  16987. %@NL@%
  16988.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  16989. %@NL@%
  16990. %@NL@%
  16991. %@NL@%
  16992. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  16993. %@NL@%
  16994. %@AB@%getcwd%@AE@%, %@AB@% _getdcwd%@AE@%, %@AB@% _makepath%@AE@%,  %@AB@%_splitpath%@AE@%  %@NL@%
  16995. %@NL@%
  16996. %@NL@%
  16997. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  16998. %@NL@%
  16999. %@AS@%  /* FULLPATH.C: This program demonstrates how _fullpath creates a full
  17000. %@AS@%   * path from a partial path.
  17001. %@AS@%   */
  17002. %@AS@%  
  17003. %@AS@%  #include <stdio.h>
  17004. %@AS@%  #include <conio.h>
  17005. %@AS@%  #include <stdlib.h>
  17006. %@AS@%  #include <direct.h>%@AE@%%@NL@%
  17007. %@NL@%
  17008. %@AS@%  char full[_MAX_PATH], part[_MAX_PATH];
  17009. %@AS@%  
  17010. %@AS@%  void main()
  17011. %@AS@%  {
  17012. %@AS@%      while( 1 )
  17013. %@AS@%      {
  17014. %@AS@%          printf( "Enter partial path or ENTER to quit: " );
  17015. %@AS@%          gets( part );
  17016. %@AS@%          if( part[0] == 0 )
  17017. %@AS@%              break;
  17018. %@AS@%  
  17019. %@AS@%          if( _fullpath( full, part, _MAX_PATH ) != NULL )
  17020. %@AS@%              printf( "Full path is: %s\n", full );
  17021. %@AS@%          else
  17022. %@AS@%              printf( "Invalid path\n" );
  17023. %@AS@%      }
  17024. %@AS@%  }%@AE@%%@NL@%
  17025. %@NL@%
  17026. %@NL@%
  17027. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  17028. %@NL@%
  17029. %@AS@%  
  17030. %@AS@%  
  17031. %@AS@%  Enter partial path or ENTER to quit: ..
  17032. %@AS@%  Full path is: C:\
  17033. %@AS@%  Enter partial path or ENTER to quit: ..\include
  17034. %@AS@%  Full path is: C:\include
  17035. %@AS@%  Enter partial path or ENTER to quit: p:
  17036. %@AS@%  Full path is: P:\
  17037. %@AS@%  Enter partial path or ENTER to quit: fullpath.c
  17038. %@AS@%  Full path is: C:\LIBREF\fullpath.c
  17039. %@AS@%  Enter partial path or ENTER to quit: %@AE@%%@NL@%
  17040. %@NL@%
  17041. %@NL@%
  17042. %@NL@%
  17043. %@NL@%
  17044. %@QR:fwrite@%%@NL@%
  17045. %@2@%%@CR:C6A01270673 @%%@AB@%fwrite%@AE@%%@EH@%%@NL@%
  17046. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17047. %@NL@%
  17048. %@NL@%
  17049. %@3@%%@AB@%Description%@CR:C6A01270674 @%%@CR:C6A01270675 @% %@CR:C6A01270676 @%%@CR:C6A01270677 @% %@CR:C6A01270678 @%%@AE@%%@EH@%%@NL@%
  17050. %@NL@%
  17051. Writes data to a stream.  %@NL@%
  17052. %@NL@%
  17053. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  17054. %@NL@%
  17055. %@AS@%  size_t fwrite( const void *buffer, size_t size, size_t count, FILE *stream
  17056. %@AS@%  );%@AE@%%@NL@%
  17057. %@NL@%
  17058. %@AI@%buffer%@AE@%                            Pointer to data to be written
  17059.  
  17060. %@AI@%size%@AE@%                              Item size in bytes
  17061.  
  17062. %@AI@%count%@AE@%                             Maximum number of items to be written
  17063.  
  17064. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  17065.  
  17066. %@NL@%
  17067. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17068. %@NL@%
  17069. The %@AB@%fwrite%@AE@% function writes up to %@AI@%count%@AE@% items, of length %@AI@%size%@AE@% each, from
  17070. %@AI@%buffer%@AE@% to the output %@AI@%stream%@AE@%. The file pointer associated with %@AI@%stream%@AE@% (if
  17071. there is one) is incremented by the number of bytes actually written.  %@NL@%
  17072. %@NL@%
  17073. If %@AI@%stream%@AE@% is opened in text mode, each carriage return is replaced with a
  17074. carriage-return-line-feed pair. The replacement has no effect on the return
  17075. value.  %@NL@%
  17076. %@NL@%
  17077. %@NL@%
  17078. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17079. %@NL@%
  17080. The %@AB@%fwrite%@AE@% function returns the number of full items actually written, which
  17081. may be less than %@AI@%count%@AE@% if an error occurs. Also, if an error occurs, the
  17082. file-position indicator cannot be determined.  %@NL@%
  17083. %@NL@%
  17084. %@NL@%
  17085. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17086. %@NL@%
  17087. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  17088. %@NL@%
  17089. %@NL@%
  17090. %@NL@%
  17091. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17092. %@NL@%
  17093. %@AB@%fread%@AE@%, %@AB@%write%@AE@%  %@NL@%
  17094. %@NL@%
  17095. %@NL@%
  17096. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17097. %@NL@%
  17098. %@AS@%  /* FREAD.C: This program opens a file named FREAD.OUT and writes 25
  17099. %@AS@%   * characters to the file. It then tries to open FREAD.OUT and
  17100. %@AS@%   * read in 25 characters. If the attempt succeeds, the program
  17101. %@AS@%   * displays the number of actual items read.
  17102. %@AS@%   */
  17103. %@AS@%  
  17104. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  17105. %@NL@%
  17106. %@AS@%  %@AE@%%@NL@%
  17107. %@NL@%
  17108. %@AS@%  void main()
  17109. %@AS@%  {
  17110. %@AS@%     FILE *stream;
  17111. %@AS@%     char list[30];
  17112. %@AS@%     int  i, numread, numwritten;
  17113. %@AS@%  
  17114. %@AS@%     /* Open file in text mode: */
  17115. %@AS@%     if( (stream = fopen( "fread.out", "w+t" )) != NULL )
  17116. %@AS@%     {
  17117. %@AS@%        for ( i = 0; i < 25; i++ )
  17118. %@AS@%           list[i] = 'z' - i;
  17119. %@AS@%        /* Write 25 characters to stream */
  17120. %@AS@%        numwritten = fwrite( list, sizeof( char ), 25, stream );
  17121. %@AS@%        printf( "Wrote %d items\n", numwritten );
  17122. %@AS@%        fclose( stream );
  17123. %@AS@%     }
  17124. %@AS@%     else
  17125. %@AS@%        printf( "Problem opening the file\n" );
  17126. %@AS@%  
  17127. %@AS@%     if( (stream = fopen( "fread.out", "r+t" )) != NULL )
  17128. %@AS@%     {
  17129. %@AS@%        /* Attempt to read in 25 characters */
  17130. %@AS@%        numread = fread( list, sizeof( char ), 25, stream );
  17131. %@AS@%        printf( "Number of items read = %d\n", numread );
  17132. %@AS@%        printf( "Contents of buffer = %.25s\n", list );
  17133. %@AS@%        fclose( stream );
  17134. %@AS@%     }
  17135. %@AS@%     else
  17136. %@AS@%        printf( "Was not able to open the file\n" );
  17137. %@AS@%  }%@AE@%%@NL@%
  17138. %@NL@%
  17139. %@NL@%
  17140. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  17141. %@NL@%
  17142. %@AS@%  
  17143. %@AS@%  
  17144. %@AS@%  Wrote 25 items
  17145. %@AS@%  Number of items read = 25
  17146. %@AS@%  Contents of buffer = zyxwvutsrqponmlkjihgfedcb %@AE@%%@NL@%
  17147. %@NL@%
  17148. %@NL@%
  17149. %@NL@%
  17150. %@NL@%
  17151. %@QR:gcvt@%%@NL@%
  17152. %@2@%%@CR:C6A01280679 @%%@AB@%gcvt%@AE@%%@EH@%%@NL@%
  17153. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17154. %@NL@%
  17155. %@NL@%
  17156. %@3@%%@AB@%Description%@CR:C6A01280680 @%%@CR:C6A01280681 @% %@CR:C6A01280682 @% %@CR:C6A01280683 @%%@AE@%%@EH@%%@NL@%
  17157. %@NL@%
  17158. Converts a floating-point value to a string, which it stores in a buffer.  %@NL@%
  17159. %@NL@%
  17160. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  17161.  
  17162. %@AS@%  char *gcvt( double value, int digits, char *buffer );%@AE@%%@NL@%
  17163. %@NL@%
  17164. %@AI@%value%@AE@%                             Value to be converted
  17165.  
  17166. %@AI@%digits%@AE@%                            Number of significant digits stored
  17167.  
  17168. %@AI@%buffer%@AE@%                            Storage location for result
  17169.  
  17170. %@NL@%
  17171. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17172. %@NL@%
  17173. The %@AB@%gcvt%@AE@% function converts a floating-point %@AI@%value%@AE@% to a character string and
  17174. stores the string in %@AI@%buffer%@AE@%. The %@AI@%buffer%@AE@% should be large enough to
  17175. accommodate the converted value plus a terminating null character (%@AB@%'\0'%@AE@%),
  17176. which is appended automatically. There is no provision for overflow.  %@NL@%
  17177. %@NL@%
  17178. The %@AB@%gcvt%@AE@% function attempts to produce %@AI@%digits%@AE@% significant digits in decimal
  17179. format. If this is not possible, it produces %@AI@%digits%@AE@% significant digits in
  17180. exponential format. Trailing zeros may be suppressed in the conversion.  %@NL@%
  17181. %@NL@%
  17182. %@NL@%
  17183. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17184. %@NL@%
  17185. The %@AB@%gcvt%@AE@% function returns a pointer to the string of digits. There is no
  17186. error return.  %@NL@%
  17187. %@NL@%
  17188. %@NL@%
  17189. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17190. %@NL@%
  17191.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  17192. %@NL@%
  17193. %@NL@%
  17194. %@NL@%
  17195. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17196. %@NL@%
  17197. %@AB@%atof%@AE@%, %@AB@%atoi%@AE@%, %@AB@%atol%@AE@%, %@AB@%ecvt%@AE@%, %@AB@%fcvt%@AE@%  %@NL@%
  17198. %@NL@%
  17199. %@NL@%
  17200. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17201. %@NL@%
  17202. %@AS@%  /* GCVT.C: This program converts -3.1415e5 to its string representation.
  17203. %@AS@%  */
  17204. %@AS@%  
  17205. %@AS@%  #include <stdlib.h>
  17206. %@AS@%  #include <stdio.h>
  17207. %@AS@%  %@AE@%%@NL@%
  17208. %@NL@%
  17209. %@AS@%  void main()
  17210. %@AS@%  {
  17211. %@AS@%     char buffer[50];
  17212. %@AS@%     double source = -3.1415e5;
  17213. %@AS@%  
  17214. %@AS@%     gcvt( source, 7, buffer );
  17215. %@AS@%     printf( "source: %f  buffer: '%s'\n", source, buffer );
  17216. %@AS@%  }%@AE@%%@NL@%
  17217. %@NL@%
  17218. %@NL@%
  17219. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  17220. %@NL@%
  17221. %@AS@%  
  17222. %@AS@%  
  17223. %@AS@%  source: -314150.000000  buffer: '-314150.' %@AE@%%@NL@%
  17224. %@NL@%
  17225. %@NL@%
  17226. %@NL@%
  17227. %@NL@%
  17228. %@QR:_getactivepage@%%@NL@%
  17229. %@2@%%@CR:C6A01290684 @%%@AB@%_getactivepage%@AE@%%@EH@%%@NL@%
  17230. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17231. %@NL@%
  17232. %@NL@%
  17233. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  17234. %@NL@%
  17235. Gets the current active page number.  %@NL@%
  17236. %@NL@%
  17237. %@CR:C6A01290685 @%%@AS@%  #include <graph.h>%@AE@%%@NL@%
  17238. %@NL@%
  17239. %@AS@%  short _far _getactivepage( void );%@AE@%%@NL@%
  17240. %@NL@%
  17241. %@NL@%
  17242. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17243. %@NL@%
  17244. The %@AB@%_getactivepage%@AE@% function returns the number of the current active page.  %@NL@%
  17245. %@NL@%
  17246. %@NL@%
  17247. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17248. %@NL@%
  17249. The function returns the number of the current active page. All hardware
  17250. combinations support at least one page (page number 0). In OS/2, only page 0
  17251. is valid.  %@NL@%
  17252. %@NL@%
  17253. %@NL@%
  17254. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17255. %@NL@%
  17256.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  17257. %@NL@%
  17258. %@NL@%
  17259. %@NL@%
  17260. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17261. %@NL@%
  17262. %@AB@%_getactivepage%@AE@%,  %@AB@%_getvideoconfig%@AE@%,  %@AB@%_getvisualpage%@AE@%,  %@AB@%_grstatus%@AE@%,
  17263. %@AB@%_setactivepage%@AE@%, %@AB@%_setvideomode%@AE@%,  %@AB@%_setvisualpage%@AE@%  %@NL@%
  17264. %@NL@%
  17265. %@NL@%
  17266. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17267. %@NL@%
  17268. %@AS@%  /* PAGE.C illustrates video page functions including:
  17269. %@AS@%   *      _getactivepage  _getvisualpage  _setactivepage  _setvisualpage
  17270. %@AS@%   */
  17271. %@AS@%  
  17272. %@AS@%  #include <conio.h>
  17273. %@AS@%  #include <graph.h>
  17274. %@AS@%  #include <stdlib.h>
  17275. %@AS@%  
  17276. %@AS@%  void main()
  17277. %@AS@%  {
  17278. %@AS@%     short  oldvpage, oldapage, page, row, col, line;
  17279. %@AS@%     struct videoconfig vc;
  17280. %@AS@%     char   buf[80];
  17281. %@AS@%  
  17282. %@AS@%     _getvideoconfig( &vc );
  17283. %@AS@%     if( vc.numvideopages < 4 )
  17284. %@AS@%         exit( 1 );              /* Fail for OS/2 or monochrome. */
  17285. %@AS@%     oldapage  = _getactivepage();
  17286. %@AS@%     oldvpage  = _getvisualpage();
  17287. %@AS@%     _displaycursor( _GCURSOROFF );
  17288. %@AS@%  %@AE@%%@NL@%
  17289. %@NL@%
  17290. %@AS@%  /* Draw arrows in different place on each page. */
  17291. %@AS@%     for( page = 1; page < 4; page++ )
  17292. %@AS@%     {
  17293. %@AS@%        _setactivepage( page );
  17294. %@AS@%        _settextposition( 12, 16 * page );
  17295. %@AS@%        _outtext( ">>>>>>>>" );
  17296. %@AS@%     }
  17297. %@AS@%  
  17298. %@AS@%     while( !kbhit() )
  17299. %@AS@%        /* Cycle through pages 1 to 3 to show moving image. */
  17300. %@AS@%        for( page = 1; page < 4; page++ )
  17301. %@AS@%            _setvisualpage( page );
  17302. %@AS@%     getch();
  17303. %@AS@%  
  17304. %@AS@%     /* Restore original page (normally 0) to restore screen. */
  17305. %@AS@%     _setactivepage( oldapage );
  17306. %@AS@%     _setvisualpage( oldvpage );
  17307. %@AS@%     _displaycursor( _GCURSORON );
  17308. %@AS@%  }%@AE@%%@NL@%
  17309. %@NL@%
  17310. %@NL@%
  17311. %@NL@%
  17312. %@NL@%
  17313. %@QR:_getarcinfo@%%@NL@%
  17314. %@2@%%@CR:C6A01300686 @%%@AB@%_getarcinfo%@AE@%%@EH@%%@NL@%
  17315. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17316. %@NL@%
  17317. %@NL@%
  17318. %@3@%%@AB@%Description%@CR:C6A01300687 @% %@CR:C6A01300688 @%%@AE@%%@EH@%%@NL@%
  17319. %@NL@%
  17320. Determines the endpoints in viewport coordinates of the most recently drawn
  17321. arc or pie.  %@NL@%
  17322. %@NL@%
  17323. %@AS@%  #include  <graph.h>%@AE@%%@NL@%
  17324. %@NL@%
  17325. %@AS@%  short _far _getarcinfo( struct xycoord _far *start, struct xycoord _far
  17326. %@AS@%  *end, 
  17327. %@AS@%  struct xycoord _far *fillpoint );%@AE@%%@NL@%
  17328. %@NL@%
  17329. %@AI@%start%@AE@%                             Starting point of arc
  17330.  
  17331. %@AI@%end%@AE@%                               Ending point of arc
  17332.  
  17333. %@AI@%fillpoint%@AE@%                         Point at which pie fill will begin
  17334.  
  17335. %@NL@%
  17336. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17337. %@NL@%
  17338. The %@AB@%_getarcinfo%@AE@% function determines the endpoints in viewport coordinates of
  17339. the most recently drawn arc or pie.  %@NL@%
  17340. %@NL@%
  17341. If successful, the %@AB@%_getarcinfo%@AE@% function updates the %@AI@%start%@AE@% and %@AI@%end%@AE@% %@AB@%xycoord%@AE@%
  17342. structures to contain the endpoints (in viewport coordinates) of the arc
  17343. drawn by the most recent call to one of the %@AB@%_arc%@AE@% or %@AB@%_pie%@AE@% functions.  %@NL@%
  17344. %@NL@%
  17345. In addition, %@AI@%fillpoint%@AE@% specifies a point from which a pie can be filled.
  17346. This is useful for filling a pie in a color different from the border color.
  17347. After a call to %@AB@%_getarcinfo%@AE@%, change colors using the %@AB@%_setcolor %@AE@%function. Use
  17348. the color, along with the coordinates in %@AI@%fillpoint%@AE@%, as arguments for the
  17349. %@AI@%floodfill%@AE@% function.  %@NL@%
  17350. %@NL@%
  17351. %@NL@%
  17352. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17353. %@NL@%
  17354. The %@AB@%_getarcinfo%@AE@% function returns a nonzero value if successful. If neither
  17355. the %@AB@%_arc%@AE@% nor the %@AB@%_pie%@AE@% function has been successfully called since the last
  17356. time the screen was cleared or a new graphics mode or viewport was selected,
  17357. the %@AB@%_getarcinfo%@AE@% function returns 0.  %@NL@%
  17358. %@NL@%
  17359. %@NL@%
  17360. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17361. %@NL@%
  17362.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  17363. %@NL@%
  17364. %@NL@%
  17365. %@NL@%
  17366. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17367. %@NL@%
  17368. %@AB@%_arc%@AE@% functions,  %@AB@%_floodfill%@AE@%,  %@AB@%_getvideoconfig%@AE@%,  %@AB@%_grstatus%@AE@%,  %@AB@%_pie%@AE@% functions  %@NL@%
  17369. %@NL@%
  17370. %@NL@%
  17371. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17372. %@NL@%
  17373. See the example for %@AB@%_arc%@AE@%.  %@NL@%
  17374. %@NL@%
  17375. %@NL@%
  17376. %@NL@%
  17377. %@NL@%
  17378. %@QR:_getbkcolor@%%@NL@%
  17379. %@2@%%@CR:C6A01310689 @%%@AB@%_getbkcolor%@AE@%%@EH@%%@NL@%
  17380. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17381. %@NL@%
  17382. %@NL@%
  17383. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  17384. %@NL@%
  17385. Gets the current background color.  %@NL@%
  17386. %@NL@%
  17387. %@CR:C6A01310690 @%%@AS@%  #include <graph.h>%@AE@%%@NL@%
  17388. %@NL@%
  17389. %@AS@%  long _far _getbkcolor( void );%@AE@%%@NL@%
  17390. %@NL@%
  17391. %@NL@%
  17392. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17393. %@NL@%
  17394. The %@AB@%_getbkcolor%@AE@% function returns the current background color. The default
  17395. is 0.  %@NL@%
  17396. %@NL@%
  17397. In a color text mode such as %@AB@%_TEXTC80%@AE@%, %@AB@%_setbkcolor%@AE@% accepts, and %@AB@%_getbkcolor%@AE@%
  17398. returns, a color index. For example, %@AB@%_setbkcolor(2L)%@AE@% sets the background
  17399. color to color index 2. The actual color displayed depends on the palette
  17400. mapping for color index 2. The default for color index 2 is green in a color
  17401. text mode.  %@NL@%
  17402. %@NL@%
  17403. In a color graphics mode such as %@AB@%_ERESCOLOR%@AE@%, %@AB@%_setbkcolor%@AE@% accepts and
  17404. %@AB@%_getbkcolor%@AE@% returns a color value (as used in %@AB@%_remappalette%@AE@%). The value for
  17405. the simplest background colors is given by the manifest constants defined in
  17406. the GRAPH.H include file. For example, %@AB@%_setbkcolor( _GREEN)%@AE@% sets the
  17407. background color in a graphics mode to green. These manifest constants are
  17408. provided as a convenience in defining and manipulating the most common
  17409. colors. In general, the actual range of colors is much greater.  %@NL@%
  17410. %@NL@%
  17411. In most cases, whenever an argument is long, it refers to a color value, and
  17412. whenever it is short, it refers to a color index. The two exceptions are
  17413. %@AB@%_setbkcolor%@AE@% and %@AB@%_getbkcolor%@AE@%, described above. For a more complete discussion
  17414. of colors, see %@AB@%_remappalette%@AE@%.  %@NL@%
  17415. %@NL@%
  17416. %@NL@%
  17417. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17418. %@NL@%
  17419. The function returns the current background color value. There is no error
  17420. return.  %@NL@%
  17421. %@NL@%
  17422. %@NL@%
  17423. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17424. %@NL@%
  17425.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  17426. %@NL@%
  17427. %@NL@%
  17428. %@NL@%
  17429. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17430. %@NL@%
  17431. %@AB@%_remappalette%@AE@%,  %@AB@%_setbkcolor%@AE@%  %@NL@%
  17432. %@NL@%
  17433. %@NL@%
  17434. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17435. %@NL@%
  17436. See the example for %@AB@%_getcolor%@AE@%.  %@NL@%
  17437. %@NL@%
  17438. %@NL@%
  17439. %@NL@%
  17440. %@NL@%
  17441. %@QR:getc@%%@QR:getchar@%%@NL@%
  17442. %@2@%%@CR:C6A01320691 @%%@AB@%getc, getchar%@AE@%%@EH@%%@NL@%
  17443. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17444. %@NL@%
  17445. %@NL@%
  17446. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  17447. %@NL@%
  17448. Reads a character from a stream (%@AB@%getc%@AE@%), or gets a character from %@AB@%stdin%@AE@%
  17449. (%@AB@%getchar%@AE@%).%@CR:C6A01320692 @%%@CR:C6A01320693 @%%@CR:C6A01320694 @%%@CR:C6A01320695 @%%@CR:C6A01320696 @%%@CR:C6A01320697 @%  %@NL@%
  17450. %@NL@%
  17451. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  17452. %@NL@%
  17453. %@AS@%  int getc( FILE *stream );%@AE@%%@NL@%
  17454. %@NL@%
  17455. %@AS@%  int getchar( void );%@AE@%%@NL@%
  17456. %@NL@%
  17457. %@AI@%stream %@AE@%                           Current stream
  17458.  
  17459. %@NL@%
  17460. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17461. %@NL@%
  17462. The %@AB@%getc%@AE@% macro reads a single character from the %@AI@%stream%@AE@% position and
  17463. increments the associated file pointer (if there is one) to point to the
  17464. next character. The %@AB@%getchar%@AE@% macro is identical to %@AB@%getc%@AE@%(%@AB@%stdin%@AE@%).  %@NL@%
  17465. %@NL@%
  17466. The %@AB@%getc%@AE@% and %@AB@%getchar%@AE@% routines are similar to %@AB@%fgetc%@AE@% and %@AB@%fgetchar%@AE@%,
  17467. respectively, but are macros rather than functions.  %@NL@%
  17468. %@NL@%
  17469. %@NL@%
  17470. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17471. %@NL@%
  17472. The %@AB@%getc%@AE@% and %@AB@%getchar%@AE@% macros return the character read. A return value of %@AB@%EOF%@AE@%
  17473. indicates an error or end-of-file condition. Use %@AB@%ferror%@AE@% or %@AB@%feof%@AE@% to determine
  17474. whether an error or end-of-file occurred.  %@NL@%
  17475. %@NL@%
  17476. %@NL@%
  17477. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17478. %@NL@%
  17479. %@AB@%getc%@AE@%  %@NL@%
  17480. %@NL@%
  17481. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  17482. %@NL@%
  17483. %@NL@%
  17484. %@AB@%getchar%@AE@%  %@NL@%
  17485. %@NL@%
  17486. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  17487. %@NL@%
  17488. %@NL@%
  17489. %@NL@%
  17490. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17491. %@NL@%
  17492. %@AB@%fgetc%@AE@%, %@AB@%fgetchar%@AE@%, %@AB@%getch%@AE@%, %@AB@%getche%@AE@%, %@AB@%putc%@AE@%, %@AB@%putchar%@AE@%, %@AB@%ungetc%@AE@%  %@NL@%
  17493. %@NL@%
  17494. %@NL@%
  17495. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17496. %@NL@%
  17497. %@AS@%  /* GETC.C: This program uses getchar to read a single line of input
  17498. %@AS@%   * from stdin, places this input in buffer, then terminates the
  17499. %@AS@%   * string before printing it to the screen.
  17500. %@AS@%   */
  17501. %@AS@%  
  17502. %@AS@%  #include <stdio.h>
  17503. %@AS@%  %@AE@%%@NL@%
  17504. %@NL@%
  17505. %@AS@%  void main()
  17506. %@AS@%  {
  17507. %@AS@%     char buffer[81];
  17508. %@AS@%     int i, ch;
  17509. %@AS@%  
  17510. %@AS@%     printf( "Enter a line: " );
  17511. %@AS@%  
  17512. %@AS@%     /* Read in single line from "stdin": */
  17513. %@AS@%     for( i = 0; (i < 80) &&  ((ch = getchar()) != EOF) && (ch != '\n'); i++
  17514. %@AS@%)
  17515. %@AS@%        buffer[i] = ch;
  17516. %@AS@%  
  17517. %@AS@%     /* Terminate string with null character: */
  17518. %@AS@%     buffer[i] = '\0';
  17519. %@AS@%     printf( "%s\n", buffer );
  17520. %@AS@%  }%@AE@%%@NL@%
  17521. %@NL@%
  17522. %@NL@%
  17523. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  17524. %@NL@%
  17525. %@AS@%  
  17526. %@AS@%  
  17527. %@AS@%  Enter a line: This is a line of text.
  17528. %@AS@%  This is a line of text. %@AE@%%@NL@%
  17529. %@NL@%
  17530. %@NL@%
  17531. %@NL@%
  17532. %@NL@%
  17533. %@QR:getch@%%@QR:getche@%%@NL@%
  17534. %@2@%%@CR:C6A01330698 @%%@AB@%getch, getche%@AE@%%@EH@%%@NL@%
  17535. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17536. %@NL@%
  17537. %@NL@%
  17538. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  17539. %@NL@%
  17540. Get a character from the console without echo (%@AB@%getch%@AE@%) or with echo (%@AB@%getche%@AE@%).
  17541. %@NL@%
  17542. %@NL@%
  17543. %@CR:C6A01330699 @%%@CR:C6A01330700 @%%@CR:C6A01330701 @%%@CR:C6A01330702 @%  %@NL@%
  17544. %@NL@%
  17545. %@AB@%#include <conio.h> %@AE@%               Required only for function declarations
  17546.  
  17547. %@AS@%  int getch( void );%@AE@%%@NL@%
  17548. %@NL@%
  17549. %@AS@%  int getche( void );%@AE@%%@NL@%
  17550. %@NL@%
  17551. %@NL@%
  17552. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17553. %@NL@%
  17554. The %@AB@%getch%@AE@% function reads a single character from the console without
  17555. echoing. The %@AB@%getche%@AE@% function reads a single character from the console and
  17556. echoes the character read. Neither function can be used to read CTRL+C.  %@NL@%
  17557. %@NL@%
  17558. When reading a function key or cursor-moving key, the %@AB@%getch%@AE@% and %@AB@%getche%@AE@%
  17559. functions must be called twice; the first call returns 0 or 0xE0, and the
  17560. second call returns the actual key code.  %@NL@%
  17561. %@NL@%
  17562. %@NL@%
  17563. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17564. %@NL@%
  17565. The %@AB@%getch%@AE@% function returns the character read. There is no error return.  %@NL@%
  17566. %@NL@%
  17567. %@NL@%
  17568. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17569. %@NL@%
  17570.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  17571. %@NL@%
  17572. %@NL@%
  17573. %@NL@%
  17574. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17575. %@NL@%
  17576. %@AB@%cgets%@AE@%, %@AB@%getchar%@AE@%, %@AB@%ungetch%@AE@%  %@NL@%
  17577. %@NL@%
  17578. %@NL@%
  17579. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17580. %@NL@%
  17581. %@AS@%  /* GETCH.C: This program reads characters from the keyboard until it
  17582. %@AS@%   * receives a 'Y' or 'y'.
  17583. %@AS@%   */
  17584. %@AS@%  
  17585. %@AS@%  #include <conio.h>
  17586. %@AS@%  #include <ctype.h>
  17587. %@AS@%  %@AE@%%@NL@%
  17588. %@NL@%
  17589. %@AS@%  void main()
  17590. %@AS@%  {
  17591. %@AS@%     int ch;
  17592. %@AS@%  
  17593. %@AS@%     cputs( "Type 'Y' when finished typing keys: " );
  17594. %@AS@%     do
  17595. %@AS@%     {
  17596. %@AS@%        ch = getch();
  17597. %@AS@%        ch = toupper( ch );
  17598. %@AS@%     } while( ch != 'Y' );
  17599. %@AS@%  
  17600. %@AS@%     putch( ch );
  17601. %@AS@%     putch( '\r' );    /* Carriage return */
  17602. %@AS@%     putch( '\n' );    /* Line feed       */
  17603. %@AS@%  }%@AE@%%@NL@%
  17604. %@NL@%
  17605. %@NL@%
  17606. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  17607. %@NL@%
  17608. %@AS@%  
  17609. %@AS@%  
  17610. %@AS@%  Type 'Y' when finished typing keys: Y%@AE@%%@NL@%
  17611. %@NL@%
  17612. %@NL@%
  17613. %@NL@%
  17614. %@NL@%
  17615. %@QR:_getcolor@%%@NL@%
  17616. %@2@%%@CR:C6A01340703 @%%@AB@%_getcolor%@AE@%%@EH@%%@NL@%
  17617. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17618. %@NL@%
  17619. %@NL@%
  17620. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  17621. %@NL@%
  17622. Gets the current color.  %@NL@%
  17623. %@NL@%
  17624. %@CR:C6A01340704 @%%@AS@%  #include <graph.h>%@AE@%%@NL@%
  17625. %@NL@%
  17626. %@AS@%  short _far _getcolor( void );%@AE@%%@NL@%
  17627. %@NL@%
  17628. %@NL@%
  17629. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17630. %@NL@%
  17631. The %@AB@%_getcolor%@AE@% function returns the current graphics color index. The default
  17632. is the highest legal value of the current palette.  %@NL@%
  17633. %@NL@%
  17634. %@NL@%
  17635. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17636. %@NL@%
  17637. The %@AB@%_getcolor%@AE@% function returns the current color index.  %@NL@%
  17638. %@NL@%
  17639. %@NL@%
  17640. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17641. %@NL@%
  17642.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  17643. %@NL@%
  17644. %@NL@%
  17645. %@NL@%
  17646. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17647. %@NL@%
  17648. %@AB@%_setcolor%@AE@%  %@NL@%
  17649. %@NL@%
  17650. %@NL@%
  17651. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17652. %@NL@%
  17653. %@AS@%  /* OUTTXT.C: This example illustrates text output functions:
  17654. %@AS@%   *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
  17655. %@AS@%   *    _settextcolor   _setbkcolor   _settextposition
  17656. %@AS@%   */
  17657. %@AS@%  
  17658. %@AS@%  #include <conio.h>
  17659. %@AS@%  #include <stdio.h>
  17660. %@AS@%  #include <graph.h>
  17661. %@AS@%  
  17662. %@AS@%  char buffer [80];
  17663. %@AS@%  
  17664. %@AS@%  void main()
  17665. %@AS@%  {
  17666. %@AS@%  
  17667. %@AS@%     /* Save original foreground, background, and text position. */
  17668. %@AS@%     short blink, fgd, oldfgd;
  17669. %@AS@%     long  bgd, oldbgd;
  17670. %@AS@%     struct rccoord oldpos;
  17671. %@AS@%  
  17672. %@AS@%     /* Save original foreground, background, and text position. */
  17673. %@AS@%     oldfgd = _gettextcolor();
  17674. %@AS@%     oldbgd = _getbkcolor();
  17675. %@AS@%     oldpos = _gettextposition();
  17676. %@AS@%     _clearscreen( _GCLEARSCREEN );
  17677. %@AS@%  %@AE@%%@NL@%
  17678. %@NL@%
  17679. %@AS@%  /* First time no blink, second time blinking. */
  17680. %@AS@%     for( blink = 0; blink <= 16; blink += 16 )
  17681. %@AS@%     {
  17682. %@AS@%        /* Loop through 8 background colors. */
  17683. %@AS@%        for( bgd = 0; bgd < 8; bgd++ )
  17684. %@AS@%        {
  17685. %@AS@%           _setbkcolor( bgd );
  17686. %@AS@%           _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
  17687. %@AS@%           _settextcolor( 7 );
  17688. %@AS@%           sprintf(buffer, "Back: %d Fore:", bgd );
  17689. %@AS@%           _outtext( buffer );
  17690. %@AS@%  
  17691. %@AS@%           /* Loop through 16 foreground colors. */
  17692. %@AS@%           for( fgd = 0; fgd < 16; fgd++ )
  17693. %@AS@%           {
  17694. %@AS@%              _settextcolor( fgd + blink );
  17695. %@AS@%              sprintf( buffer, " %2d ", fgd + blink );
  17696. %@AS@%              _outtext( buffer );
  17697. %@AS@%           }
  17698. %@AS@%        }
  17699. %@AS@%     }
  17700. %@AS@%     getch();
  17701. %@AS@%  
  17702. %@AS@%     /* Restore original foreground, background, and text position. */
  17703. %@AS@%     _settextcolor( oldfgd );
  17704. %@AS@%     _setbkcolor( oldbgd );
  17705. %@AS@%     _clearscreen( _GCLEARSCREEN );
  17706. %@AS@%     _settextposition( oldpos.row, oldpos.col );
  17707. %@AS@%  }%@AE@%%@NL@%
  17708. %@NL@%
  17709. %@NL@%
  17710. %@NL@%
  17711. %@NL@%
  17712. %@QR:_getcurrentposition@%%@NL@%
  17713. %@2@%%@CR:C6A01350705 @%%@AB@%_getcurrentposition Functions%@AE@%%@EH@%%@NL@%
  17714. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17715. %@NL@%
  17716. %@NL@%
  17717. %@3@%%@AB@%Description %@CR:C6A01350706 @%%@AE@%%@EH@%%@NL@%
  17718. %@NL@%
  17719. Get the current position and return it as a structure.  %@NL@%
  17720. %@NL@%
  17721. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  17722. %@NL@%
  17723. %@AS@%  struct xycoord _far _getcurrentposition( void );%@AE@%%@NL@%
  17724. %@NL@%
  17725. %@AS@%  struct _wxycoord _far _getcurrentposition_w( void );%@AE@%%@NL@%
  17726. %@NL@%
  17727. %@NL@%
  17728. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17729. %@NL@%
  17730. The %@AB@%_getcurrentposition%@AE@% functions return the coordinates of the current
  17731. graphics output position. The %@AB@%_getcurrentposition%@AE@% function returns the
  17732. position as an %@AB@%xycoord%@AE@% structure, defined in GRAPH.H.  %@NL@%
  17733. %@NL@%
  17734. The %@AB@%xycoord%@AE@% structure contains the following elements:  %@NL@%
  17735. %@NL@%
  17736. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  17737. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17738. %@AB@%short xcoord%@AE@%                      %@AI@%x%@AE@% coordinate
  17739.  
  17740. %@AB@%short ycoord%@AE@%                      %@AI@%y%@AE@% coordinate
  17741.  
  17742. The %@AB@%_getcurrentposition_w%@AE@% function returns the position as an %@AB@%_wxycoord%@AE@%
  17743. structure, defined in GRAPH.H.  %@NL@%
  17744. %@NL@%
  17745. The %@AB@%_wxycoord%@AE@% structure contains the following elements:  %@NL@%
  17746. %@NL@%
  17747. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  17748. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17749. %@AB@%double wx%@AE@%                         window%@AI@% x%@AE@% coordinate
  17750.  
  17751. %@AB@%double wy%@AE@%                         window%@AI@% y%@AE@% coordinate
  17752.  
  17753. The current position can be changed by the %@AB@%_lineto%@AE@%, %@AB@%_moveto%@AE@%, and %@AB@%_outgtext%@AE@%
  17754. functions.  %@NL@%
  17755. %@NL@%
  17756. The default position, set by %@AB@%_setvideomode%@AE@%, %@AB@%_setvideomoderows%@AE@%, or
  17757. %@AB@%_setviewport%@AE@%, is the center of the viewport.  %@NL@%
  17758. %@NL@%
  17759. Only graphics output starts at the current position; these functions do not
  17760. affect text output, which begins at the current text position. (See
  17761. %@AB@%_settextposition%@AE@% for more information.)  %@NL@%
  17762. %@NL@%
  17763. %@NL@%
  17764. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17765. %@NL@%
  17766. The %@AB@%_getcurrentposition%@AE@% function returns the coordinates of the current
  17767. graphics output position. There is no error return.  %@NL@%
  17768. %@NL@%
  17769. %@NL@%
  17770. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17771. %@NL@%
  17772.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  17773. %@NL@%
  17774. %@NL@%
  17775. %@NL@%
  17776. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17777. %@NL@%
  17778. %@AB@%_grstatus%@AE@%,  %@AB@%_lineto%@AE@% functions,  %@AB@%_moveto%@AE@% functions,  %@AB@%_outgtext%@AE@%  %@NL@%
  17779. %@NL@%
  17780. %@NL@%
  17781. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17782. %@NL@%
  17783. %@AS@%  /* GCURPOS.C: This program sets a random current location, then gets that
  17784. %@AS@%   * location with _getcurrentposition.
  17785. %@AS@%   */
  17786. %@AS@%  
  17787. %@AS@%  #include <stdio.h>
  17788. %@AS@%  #include <stdlib.h>
  17789. %@AS@%  #include <conio.h>
  17790. %@AS@%  #include <graph.h>
  17791. %@AS@%  
  17792. %@AS@%  char   buffer[255];
  17793. %@AS@%  
  17794. %@AS@%  void main()
  17795. %@AS@%  {
  17796. %@AS@%     struct videoconfig vc;
  17797. %@AS@%     struct xycoord position;
  17798. %@AS@%  
  17799. %@AS@%     /* Find a valid graphics mode. */
  17800. %@AS@%     if( !_setvideomode( _MAXRESMODE ) )
  17801. %@AS@%        exit( 1 );
  17802. %@AS@%     _getvideoconfig( &vc );
  17803. %@AS@%  
  17804. %@AS@%     /* Move to random location and report that location. */
  17805. %@AS@%     _moveto( rand() % vc.numxpixels, rand() % vc.numypixels );
  17806. %@AS@%     position = _getcurrentposition();
  17807. %@AS@%     sprintf( buffer, "x = %d, y = %d", position.xcoord, position.ycoord );
  17808. %@AS@%     _settextposition( 1, 1 );
  17809. %@AS@%     _outtext( buffer );
  17810. %@AS@%  
  17811. %@AS@%     getch();
  17812. %@AS@%     _setvideomode( _DEFAULTMODE );
  17813. %@AS@%  }%@AE@%%@NL@%
  17814. %@NL@%
  17815. %@NL@%
  17816. %@NL@%
  17817. %@NL@%
  17818. %@QR:getcwd@%%@NL@%
  17819. %@2@%%@CR:C6A01360707 @%%@AB@%getcwd%@AE@%%@EH@%%@NL@%
  17820. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17821. %@NL@%
  17822. %@NL@%
  17823. %@3@%%@AB@%Description%@CR:C6A01360708 @%%@CR:C6A01360709 @% %@CR:C6A01360710 @%%@AE@%%@EH@%%@NL@%
  17824. %@NL@%
  17825. Gets the current working directory.  %@NL@%
  17826. %@NL@%
  17827. %@AB@%#include <direct.h>%@AE@%               Required only for function declarations
  17828.  
  17829. %@AS@%  char *getcwd( char *buffer, int maxlen );%@AE@%%@NL@%
  17830. %@NL@%
  17831. %@AI@%buffer%@AE@%                            Storage location for path name
  17832.  
  17833. %@AI@%maxlen%@AE@%                            Maximum length of path name
  17834.  
  17835. %@NL@%
  17836. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17837. %@NL@%
  17838. The %@AB@%getcwd%@AE@% function gets the full path name of the current working directory
  17839. and stores it at %@AI@%buffer%@AE@%. The integer argument %@AI@%maxlen%@AE@% specifies the maximum
  17840. length for the path name. An error occurs if the length of the path name
  17841. (including the terminating null character) exceeds %@AI@%maxlen.%@AE@%  %@NL@%
  17842. %@NL@%
  17843. The %@AI@%buffer%@AE@% argument can be %@AB@%NULL%@AE@%; a buffer of at least size %@AI@%maxlen%@AE@% (more only
  17844. if necessary) will automatically be allocated, using %@AB@%malloc%@AE@%, to store the
  17845. path name. This buffer can later be freed by calling %@AB@%free%@AE@% and passing it the
  17846. %@AB@%getcwd%@AE@% return value (a pointer to the allocated buffer).  %@NL@%
  17847. %@NL@%
  17848. %@NL@%
  17849. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17850. %@NL@%
  17851. The %@AB@%getcwd%@AE@% function returns a pointer to %@AI@%buffer%@AE@%. A %@AB@%NULL%@AE@% return value
  17852. indicates an error, and %@AB@%errno%@AE@% is set to one of the following values:  %@NL@%
  17853. %@NL@%
  17854. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  17855. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17856. %@AB@%ENOMEM%@AE@%                            Insufficient memory to allocate %@AI@%maxlen%@AE@% 
  17857.                                   bytes (when a %@AB@%NULL%@AE@% argument is given as %@AI@%%@AE@%
  17858.                                   %@AI@%buffer%@AE@%)
  17859.  
  17860. %@AB@%ERANGE%@AE@%                            Path name longer than %@AI@%maxlen%@AE@% characters
  17861.  
  17862. %@NL@%
  17863. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17864. %@NL@%
  17865.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  17866. %@NL@%
  17867. %@NL@%
  17868. %@NL@%
  17869. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17870. %@NL@%
  17871. %@AB@%chdir%@AE@%, %@AB@%mkdir%@AE@%, %@AB@%rmdir%@AE@%  %@NL@%
  17872. %@NL@%
  17873. %@NL@%
  17874. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17875. %@NL@%
  17876. %@AS@%  /* This program places the name of the current directory in the buffer
  17877. %@AS@%   * array, then displays the name of the current directory on the screen.
  17878. %@AS@%   * Specifying a length of _MAX_DIR leaves room for the longest legal
  17879. %@AS@%   * directory name.
  17880. %@AS@%   */%@AE@%%@NL@%
  17881. %@NL@%
  17882. %@AS@%  #include <direct.h>
  17883. %@AS@%  #include <stdlib.h>
  17884. %@AS@%  #include <stdio.h>
  17885. %@AS@%  
  17886. %@AS@%  void main()
  17887. %@AS@%  {
  17888. %@AS@%     char buffer[_MAX_DIR];
  17889. %@AS@%  
  17890. %@AS@%     /* Get the current working directory: */
  17891. %@AS@%     if( getcwd( buffer, _MAX_DIR ) == NULL )
  17892. %@AS@%        perror( "getcwd error" );
  17893. %@AS@%     else
  17894. %@AS@%        printf( "%s\n", buffer );
  17895. %@AS@%  }%@AE@%%@NL@%
  17896. %@NL@%
  17897. %@NL@%
  17898. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  17899. %@NL@%
  17900. %@AS@%  
  17901. %@AS@%  
  17902. %@AS@%  C:\LIBREF %@AE@%%@NL@%
  17903. %@NL@%
  17904. %@NL@%
  17905. %@NL@%
  17906. %@NL@%
  17907. %@QR:_getdcwd@%%@NL@%
  17908. %@2@%%@CR:C6A01370711 @%%@AB@%_getdcwd%@AE@%%@EH@%%@NL@%
  17909. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17910. %@NL@%
  17911. %@NL@%
  17912. %@3@%%@AB@%Description%@CR:C6A01370712 @%%@CR:C6A01370713 @% %@CR:C6A01370714 @%%@AE@%%@EH@%%@NL@%
  17913. %@NL@%
  17914. Gets full path name of current working directory, including disk drive.  %@NL@%
  17915. %@NL@%
  17916. %@AB@%#include <direct.h>%@AE@%               Required only for function declarations
  17917.  
  17918. %@AS@%  char *_getdcwd( int drive, char *buffer, int maxlen );%@AE@%%@NL@%
  17919. %@NL@%
  17920. %@AI@%drive%@AE@%                             Disk drive
  17921.  
  17922. %@AI@%buffer%@AE@%                            Storage location for path name
  17923.  
  17924. %@AI@%maxlen%@AE@%                            Maximum length of path name
  17925.  
  17926. %@NL@%
  17927. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  17928. %@NL@%
  17929. The %@AB@%_getdcwd%@AE@% function gets the full path name of the current working
  17930. directory, including disk drive specification, and stores it at %@AI@%buffer%@AE@%. The
  17931. argument %@AI@%maxlen%@AE@% specifies the maximum length for the path name. An error
  17932. occurs if the length of the path name (including the terminating null
  17933. character) exceeds %@AI@%maxlen%@AE@%.  %@NL@%
  17934. %@NL@%
  17935. The %@AI@%drive%@AE@% argument specifies the drive (0 = default drive, 1=A, 2=B, etc.).
  17936. The %@AI@%buffer%@AE@% argument can be %@AB@%NULL%@AE@%; a buffer of at least size %@AI@%maxlen%@AE@% (more only
  17937. if necessary) will automatically be allocated, using %@AB@%malloc%@AE@%, to store the
  17938. path name. This buffer can later be freed by calling %@AB@%free%@AE@% and passing it the
  17939. %@AB@%_getdcwd%@AE@% return value (a pointer to the allocated buffer).  %@NL@%
  17940. %@NL@%
  17941. %@NL@%
  17942. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  17943. %@NL@%
  17944. The %@AB@%_getdcwd%@AE@% function returns %@AI@%buffer%@AE@%. A %@AB@%NULL%@AE@% return value indicates an
  17945. error, and %@AB@%errno%@AE@% is set to one of the following values:  %@NL@%
  17946. %@NL@%
  17947. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  17948. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  17949. %@AB@%ENOMEM%@AE@%                            Insufficient memory to allocate %@AI@%maxlen%@AE@% 
  17950.                                   bytes (when a %@AB@%NULL%@AE@% argument is given as %@AI@%%@AE@%
  17951.                                   %@AI@%buffer%@AE@%)
  17952.  
  17953. %@AB@%ERANGE%@AE@%                            Path name longer than %@AI@%maxlen%@AE@% characters
  17954.  
  17955. %@NL@%
  17956. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  17957. %@NL@%
  17958.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  17959. %@NL@%
  17960. %@NL@%
  17961. %@NL@%
  17962. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  17963. %@NL@%
  17964. %@AB@%chdir%@AE@%, %@AB@%getcwd%@AE@%, %@AB@%_getdrive%@AE@%,%@AB@% mkdir%@AE@%, %@AB@%rmdir%@AE@%  %@NL@%
  17965. %@NL@%
  17966. %@NL@%
  17967. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  17968. %@NL@%
  17969. %@AS@%  /* GETDRIVE.C illustrates drive functions including:
  17970. %@AS@%   *      _getdrive       _chdrive        _getdcwd
  17971. %@AS@%   */%@AE@%%@NL@%
  17972. %@NL@%
  17973. %@AS@%  #include <stdio.h>
  17974. %@AS@%  #include <conio.h>
  17975. %@AS@%  #include <direct.h>
  17976. %@AS@%  #include <stdlib.h>
  17977. %@AS@%  
  17978. %@AS@%  void main()
  17979. %@AS@%  {
  17980. %@AS@%     int ch, drive, curdrive;
  17981. %@AS@%     static char path[_MAX_PATH];
  17982. %@AS@%  
  17983. %@AS@%     /* Save current drive. */
  17984. %@AS@%     curdrive = _getdrive();
  17985. %@AS@%  
  17986. %@AS@%     printf( "Available drives are: \n" );
  17987. %@AS@%  
  17988. %@AS@%     /* If we can switch to the drive, it exists. */
  17989. %@AS@%     for( drive = 1; drive <= 26; drive++ )
  17990. %@AS@%        if( !_chdrive( drive ) )
  17991. %@AS@%           printf( "%c: ", drive + 'A' - 1 );
  17992. %@AS@%  
  17993. %@AS@%     while( 1 )
  17994. %@AS@%     {
  17995. %@AS@%        printf( "\nType drive letter to check or ESC to quit: " );
  17996. %@AS@%        ch = getch();
  17997. %@AS@%        if( ch == 27 )
  17998. %@AS@%           break;
  17999. %@AS@%        if( isalpha( ch ) )
  18000. %@AS@%           putch( ch );
  18001. %@AS@%        if( _getdcwd( toupper( ch ) - 'A' + 1, path, _MAX_PATH ) != NULL )
  18002. %@AS@%           printf( "\nCurrent directory on that drive is %s\n", path );
  18003. %@AS@%     }
  18004. %@AS@%  
  18005. %@AS@%     /* Restore original drive. This is only necessary for DOS. Under OS/2
  18006. %@AS@%      * the current drive of the calling process is always restored.
  18007. %@AS@%      */
  18008. %@AS@%     _chdrive( curdrive );
  18009. %@AS@%     printf( "\n" );
  18010. %@AS@%  }%@AE@%%@NL@%
  18011. %@NL@%
  18012. %@NL@%
  18013. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  18014. %@NL@%
  18015. %@AS@%  
  18016. %@AS@%  
  18017. %@AS@%  Available drives are:
  18018. %@AS@%  A: B: C:
  18019. %@AS@%  Type drive letter to check or ESC to quit: q
  18020. %@AS@%  Type drive letter to check or ESC to quit: a
  18021. %@AS@%  Current directory on that drive is A:\
  18022. %@AS@%  
  18023. %@AS@%  Type drive letter to check or ESC to quit: c
  18024. %@AS@%  Current directory on that drive is C:\LIBREF
  18025. %@AS@%  
  18026. %@AS@%  Type drive letter to check or ESC to quit: %@AE@%%@NL@%
  18027. %@NL@%
  18028. %@NL@%
  18029. %@NL@%
  18030. %@NL@%
  18031. %@QR:_getdrive@%%@NL@%
  18032. %@2@%%@CR:C6A01380715 @%%@AB@%_getdrive%@AE@%%@EH@%%@NL@%
  18033. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18034. %@NL@%
  18035. %@NL@%
  18036. %@3@%%@AB@%Description%@CR:C6A01380716 @% %@CR:C6A01380717 @%%@AE@%%@EH@%%@NL@%
  18037. %@NL@%
  18038. Gets the current disk drive.  %@NL@%
  18039. %@NL@%
  18040. %@AS@%  #include <direct.h>%@AE@%%@NL@%
  18041. %@NL@%
  18042. %@AS@%  int _getdrive( void );%@AE@%%@NL@%
  18043. %@NL@%
  18044. %@NL@%
  18045. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18046. %@NL@%
  18047. The %@AB@%_getdrive%@AE@% function returns the current working drive (1=A, 2=B, etc.).  %@NL@%
  18048. %@NL@%
  18049. %@NL@%
  18050. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18051. %@NL@%
  18052. The return value is stated above. There is no error return.  %@NL@%
  18053. %@NL@%
  18054. %@NL@%
  18055. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18056. %@NL@%
  18057.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  18058. %@NL@%
  18059. %@NL@%
  18060. %@NL@%
  18061. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18062. %@NL@%
  18063. %@AB@%_chdrive%@AE@%,  %@AB@%_dos_getdrive%@AE@%,  %@AB@%_dos_setdrive%@AE@%,  %@AB@%_getcwd%@AE@%,  %@AB@%_getdcwd%@AE@%  %@NL@%
  18064. %@NL@%
  18065. %@NL@%
  18066. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18067. %@NL@%
  18068. See the example for %@AB@%_getdcwd%@AE@%.  %@NL@%
  18069. %@NL@%
  18070. %@NL@%
  18071. %@NL@%
  18072. %@NL@%
  18073. %@QR:getenv@%%@NL@%
  18074. %@2@%%@CR:C6A01390718 @%%@AB@%getenv%@AE@%%@EH@%%@NL@%
  18075. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18076. %@NL@%
  18077. %@NL@%
  18078. %@3@%%@AB@%Description%@CR:C6A01390719 @%%@AE@%%@EH@%%@NL@%
  18079. %@NL@%
  18080. Gets a value from the environment table.  %@NL@%
  18081. %@NL@%
  18082. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  18083.  
  18084. %@AS@%  char *getenv( const char *varname );%@AE@%%@NL@%
  18085. %@NL@%
  18086. %@AI@%varname%@AE@%                           Name of environment variable
  18087.  
  18088. %@NL@%
  18089. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18090. %@NL@%
  18091. The %@AB@%getenv%@AE@% function searches the list of environment variables for an entry
  18092. corresponding to %@AI@%varname%@AE@%. Environment variables define the environment in
  18093. which a process executes. (For example, the LIB environment variable defines
  18094. the default search path for libraries to be linked with a program.) Because
  18095. the %@AB@%getenv%@AE@% function is case sensitive, the %@AI@%varname%@AE@% variable should match the
  18096. case of the environment variable. %@CR:C6A01390720 @%  %@NL@%
  18097. %@NL@%
  18098. The %@AB@%getenv%@AE@% function returns a pointer to an entry in the environment table.
  18099. It is, however, only safe to retrieve the value of the environment variable
  18100. using the returned pointer. To modify the value of an environmental
  18101. variable, use the %@AB@%putenv%@AE@% function.  %@NL@%
  18102. %@NL@%
  18103. The %@AB@%getenv%@AE@% and %@AB@%putenv%@AE@% functions use the copy of the environment contained in
  18104. the global variable %@AB@%environ%@AE@% to access the environment. Programs that use the
  18105. %@AI@%envp%@AE@% argument to %@AB@%main%@AE@% and the %@AB@%putenv%@AE@% function may retrieve invalid
  18106. information. The safest programming practice is to use %@AB@%getenv%@AE@% and %@AB@%putenv%@AE@%.%@CR:C6A01390721 @%%@CR:C6A01390722 @%  %@NL@%
  18107. %@NL@%
  18108. %@NL@%
  18109. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18110. %@NL@%
  18111. The %@AB@%getenv%@AE@% function returns a pointer to the environment table entry
  18112. containing the current string value of %@AI@%varname%@AE@%. The return value is %@AB@%NULL%@AE@% if
  18113. the given variable is not currently defined.  %@NL@%
  18114. %@NL@%
  18115. %@NL@%
  18116. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18117. %@NL@%
  18118. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  18119. %@NL@%
  18120. %@NL@%
  18121. The %@AB@%getenv%@AE@% function operates only on the data structures accessible to the
  18122. run-time library and not on the environment "segment" created for a process
  18123. by DOS or OS/2.  %@NL@%
  18124. %@NL@%
  18125. %@NL@%
  18126. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18127. %@NL@%
  18128. %@AB@%putenv%@AE@%  %@NL@%
  18129. %@NL@%
  18130. %@NL@%
  18131. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18132. %@NL@%
  18133. %@AS@%  /* GETENV.C: This program uses getenv to retrieve the LIB environment
  18134. %@AS@%   * variable and then uses putenv to change it to a new value.
  18135. %@AS@%   */
  18136. %@AS@%  
  18137. %@AS@%  #include <stdlib.h>
  18138. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  18139. %@NL@%
  18140. %@AS@%  main()
  18141. %@AS@%  {
  18142. %@AS@%     char *libvar;
  18143. %@AS@%  
  18144. %@AS@%     /* Get the value of the LIB environment variable. */
  18145. %@AS@%     libvar = getenv( "LIB" );
  18146. %@AS@%     if( libvar != NULL )
  18147. %@AS@%        printf( "Original LIB variable is: %s\n", libvar );
  18148. %@AS@%  
  18149. %@AS@%     /* Attempt to change path. Note that this only affects the environment
  18150. %@AS@%      * variable of the current process. The command processor's environment
  18151. %@AS@%      * is not changed.
  18152. %@AS@%      */
  18153. %@AS@%     putenv( "LIB=c:\\mylib;c:\\yourlib" );
  18154. %@AS@%  
  18155. %@AS@%     /* Get new value. */
  18156. %@AS@%     libvar = getenv( "LIB" );
  18157. %@AS@%     if( libvar != NULL )
  18158. %@AS@%        printf( "New LIB variable is: %s\n", libvar );
  18159. %@AS@%  
  18160. %@AS@%  }%@AE@%%@NL@%
  18161. %@NL@%
  18162. %@NL@%
  18163. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  18164. %@NL@%
  18165. %@AS@%  
  18166. %@AS@%  
  18167. %@AS@%  Original LIB variable is: C:\LIB
  18168. %@AS@%  New LIB variable is: c:\mylib;c:\yourlib %@AE@%%@NL@%
  18169. %@NL@%
  18170. %@NL@%
  18171. %@NL@%
  18172. %@NL@%
  18173. %@QR:_getfillmask@%%@NL@%
  18174. %@2@%%@CR:C6A01400723 @%%@AB@%_getfillmask%@AE@%%@EH@%%@NL@%
  18175. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18176. %@NL@%
  18177. %@NL@%
  18178. %@3@%%@AB@%Description%@CR:C6A01400724 @%%@AE@%%@EH@%%@NL@%
  18179. %@NL@%
  18180. Gets the current fill mask for some graphics routines.  %@NL@%
  18181. %@NL@%
  18182. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18183. %@NL@%
  18184. %@AS@%  unsigned char _far * _far _getfillmask( unsigned char _far *mask );%@AE@%%@NL@%
  18185. %@NL@%
  18186. %@AI@%mask%@AE@%                              Mask array
  18187.  
  18188. %@NL@%
  18189. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18190. %@NL@%
  18191. Some graphics routines (%@AB@%_ellipse%@AE@%, %@AB@%_floodfill%@AE@%, %@AB@%_pie%@AE@%, %@AB@%_polygon%@AE@%, and%@AB@%
  18192. %@AB@%_rectangle%@AE@%) can fill part or all of the screen with the current color or
  18193. background color. The fill mask controls the pattern used for filling.  %@NL@%
  18194. %@NL@%
  18195. The %@AB@%_getfillmask%@AE@% function returns the current fill mask. The mask is an
  18196. 8-by-8-bit array, in which each bit represents a pixel. If the bit is 1, the
  18197. corresponding pixel is set to the current color; if the bit is 0, the pixel
  18198. is left unchanged. The mask is repeated over the entire fill area. If no
  18199. fill mask is set, or if %@AI@%mask%@AE@% is %@AB@%NULL%@AE@%, a solid (unpatterned) fill is
  18200. performed using the current color.  %@NL@%
  18201. %@NL@%
  18202. %@NL@%
  18203. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18204. %@NL@%
  18205. If no mask is set, the function returns %@AB@%NULL%@AE@%.  %@NL@%
  18206. %@NL@%
  18207. %@NL@%
  18208. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18209. %@NL@%
  18210.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18211. %@NL@%
  18212. %@NL@%
  18213. %@NL@%
  18214. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18215. %@NL@%
  18216. %@AB@%_ellipse%@AE@% functions,  %@AB@%_floodfill%@AE@%,  %@AB@%_pie%@AE@% functions,  %@AB@%_polygon%@AE@% functions,
  18217. %@AB@%_rectangle%@AE@% functions, %@AB@%_setfillmask%@AE@%  %@NL@%
  18218. %@NL@%
  18219. %@NL@%
  18220. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18221. %@NL@%
  18222. %@AS@%  /* GFILLMSK.C: This program illustrates _getfillmask and _setfillmask. */
  18223. %@AS@%  
  18224. %@AS@%  #include <conio.h>
  18225. %@AS@%  #include <stdlib.h>
  18226. %@AS@%  #include <graph.h>
  18227. %@AS@%  %@AE@%%@NL@%
  18228. %@NL@%
  18229. %@AS@%  void ellipsemask( short x1, short y1, short x2, short y2, char _far
  18230. %@AS@%  *newmask );
  18231. %@AS@%  
  18232. %@AS@%  unsigned char mask1[8] = { 0x43, 0x23, 0x7c, 0xf7, 0x8a, 0x4d, 0x78, 0x39
  18233. %@AS@%};
  18234. %@AS@%  unsigned char mask2[8] = { 0x18, 0xad, 0xc0, 0x79, 0xf6, 0xc4, 0xa8, 0x23
  18235. %@AS@%};
  18236. %@AS@%  char oldmask[8];
  18237. %@AS@%  
  18238. %@AS@%  void main()
  18239. %@AS@%  {
  18240. %@AS@%     int loop;
  18241. %@AS@%  
  18242. %@AS@%     /* Find a valid graphics mode. */
  18243. %@AS@%     if( !_setvideomode( _MAXRESMODE ) )
  18244. %@AS@%        exit( 1 );
  18245. %@AS@%  
  18246. %@AS@%     /* Set first fill mask and draw rectangle. */
  18247. %@AS@%     _setfillmask( mask1 );
  18248. %@AS@%     _rectangle( _GFILLINTERIOR, 20, 20, 100, 100 );
  18249. %@AS@%     getch();
  18250. %@AS@%  
  18251. %@AS@%     /* Call routine that saves and restores mask. */
  18252. %@AS@%     ellipsemask( 60, 60, 150, 150, mask2 );
  18253. %@AS@%     getch();
  18254. %@AS@%  
  18255. %@AS@%     /* Back to original mask. */
  18256. %@AS@%     _rectangle( _GFILLINTERIOR, 120, 120, 190, 190 );
  18257. %@AS@%     getch();
  18258. %@AS@%  
  18259. %@AS@%     _setvideomode( _DEFAULTMODE );
  18260. %@AS@%  }
  18261. %@AS@%  
  18262. %@AS@%  /* Draw an ellipse with a specified fill mask. */
  18263. %@AS@%  void ellipsemask( short x1, short y1, short x2, short y2, char _far
  18264. %@AS@%*newmask )
  18265. %@AS@%  {
  18266. %@AS@%     unsigned char savemask[8];
  18267. %@AS@%  
  18268. %@AS@%     _getfillmask( savemask );                    /* Save mask         */
  18269. %@AS@%     _setfillmask( newmask );                     /* Set new mask      */
  18270. %@AS@%     _ellipse( _GFILLINTERIOR, x1, y1, x2, y2 );  /* Use new mask      */
  18271. %@AS@%     _setfillmask( savemask );                    /* Restore original  */
  18272. %@AS@%  } %@AE@%%@NL@%
  18273. %@NL@%
  18274. %@NL@%
  18275. %@NL@%
  18276. %@NL@%
  18277. %@QR:_getfontinfo@%%@NL@%
  18278. %@2@%%@CR:C6A01410725 @%%@AB@%_getfontinfo%@AE@%%@EH@%%@NL@%
  18279. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18280. %@NL@%
  18281. %@NL@%
  18282. %@3@%%@AB@%Description%@CR:C6A01410726 @% %@CR:C6A01410727 @%%@AE@%%@EH@%%@NL@%
  18283. %@NL@%
  18284. Gets the current font characteristics.  %@NL@%
  18285. %@NL@%
  18286. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18287. %@NL@%
  18288. %@AS@%  short _far _getfontinfo( struct _fontinfo _far *fontbuffer );%@AE@%%@NL@%
  18289. %@NL@%
  18290. %@AI@%fontbuffer%@AE@%                        Buffer to hold font information
  18291.  
  18292. %@NL@%
  18293. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18294. %@NL@%
  18295. The %@AB@%_getfontinfo%@AE@% function gets the current font characteristics and stores
  18296. them in a%@AB@% _fontinfo%@AE@% structure, defined in GRAPH.H.  %@NL@%
  18297. %@NL@%
  18298. The %@AB@%_fontinfo%@AE@% structure contains the following elements:  %@NL@%
  18299. %@NL@%
  18300. %@AB@%Element%@AE@%                           %@AB@%Contents%@AE@%
  18301. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18302. %@AB@%int type%@AE@%                          Specifies vector (1) or bit-mapped (0) 
  18303.                                   font
  18304.  
  18305. %@AB@%int ascent%@AE@%                        Specifies pixel distance from top to 
  18306.                                   baseline
  18307.  
  18308. %@AB@%int pixwidth%@AE@%                      Specifies the character width in pixels;
  18309.                                   0 indicates a proportional font 
  18310.  
  18311. %@AB@%int pixheight%@AE@%                     Specifies the character height in pixels
  18312.  
  18313. %@AB@%int avgwidth%@AE@%                      Specifies the average character width in
  18314.                                   pixels
  18315.  
  18316. %@AB@%char filename [81]%@AE@%                Specifies the file name, including the 
  18317.                                   path
  18318.  
  18319. %@AB@%char facename%@AE@% %@AB@%[32]%@AE@%                Specifies the font name
  18320.  
  18321. %@NL@%
  18322. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18323. %@NL@%
  18324. The %@AB@%_getfontinfo%@AE@% function returns a negative number if a font has not been
  18325. registered or loaded.  %@NL@%
  18326. %@NL@%
  18327. %@NL@%
  18328. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18329. %@NL@%
  18330.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18331. %@NL@%
  18332. %@NL@%
  18333. %@NL@%
  18334. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18335. %@NL@%
  18336. %@AB@%_getgtextextent%@AE@%,  %@AB@%_outgtext%@AE@%,  %@AB@%_registerfonts%@AE@%,  %@AB@%_setfont%@AE@%,  %@AB@%_setgtextvector%@AE@%,
  18337. %@AB@%_unregisterfonts%@AE@%  %@NL@%
  18338. %@NL@%
  18339. %@NL@%
  18340. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18341. %@NL@%
  18342. See the example for %@AB@%_outgtext%@AE@%.  %@NL@%
  18343. %@NL@%
  18344. %@NL@%
  18345. %@NL@%
  18346. %@NL@%
  18347. %@QR:_getgtextextent@%%@NL@%
  18348. %@2@%%@CR:C6A01420728 @%%@AB@%_getgtextextent%@CR:C6A01420729 @%%@AE@%%@EH@%%@NL@%
  18349. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18350. %@NL@%
  18351. %@NL@%
  18352. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  18353. %@NL@%
  18354. Gets the width in pixels of font-based text.  %@NL@%
  18355. %@NL@%
  18356. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18357. %@NL@%
  18358. %@AS@%  short _far _getgtextextent( unsigned char _far *text );%@AE@%%@NL@%
  18359. %@NL@%
  18360. %@AI@%text%@AE@%                              Text to be analyzed
  18361.  
  18362. %@NL@%
  18363. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18364. %@NL@%
  18365. The %@AB@%_getgtextextent%@AE@% function returns the width in pixels that would be
  18366. required to print the %@AI@%text%@AE@% string using %@AB@%_outgtext %@AE@%with the current font.  %@NL@%
  18367. %@NL@%
  18368. This function is particularly useful for determining the size of text that
  18369. uses proportionally spaced fonts.  %@NL@%
  18370. %@NL@%
  18371. %@NL@%
  18372. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18373. %@NL@%
  18374. The %@AB@%_getgtextextent%@AE@% function returns the width in pixels. It returns -1 if a
  18375. font has not been registered.  %@NL@%
  18376. %@NL@%
  18377. %@NL@%
  18378. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18379. %@NL@%
  18380.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18381. %@NL@%
  18382. %@NL@%
  18383. %@NL@%
  18384. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18385. %@NL@%
  18386. %@AB@%_getfontinfo%@AE@%,  %@AB@%_outgtext%@AE@%,%@AB@%  _registerfonts%@AE@%,  %@AB@%_setfont%@AE@%, %@AB@% _unregisterfonts  %@AE@%%@NL@%
  18387. %@NL@%
  18388. %@NL@%
  18389. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18390. %@NL@%
  18391. See the example for %@AB@%_outgtext%@AE@%.  %@NL@%
  18392. %@NL@%
  18393. %@NL@%
  18394. %@NL@%
  18395. %@NL@%
  18396. %@QR:_getimage@%%@NL@%
  18397. %@2@%%@CR:C6A01430730 @%%@AB@%_getimage Functions%@AE@%%@EH@%%@NL@%
  18398. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18399. %@NL@%
  18400. %@NL@%
  18401. %@3@%%@AB@%Description%@CR:C6A01430731 @%%@AE@%%@EH@%%@NL@%
  18402. %@NL@%
  18403. Store images in buffers.  %@NL@%
  18404. %@NL@%
  18405. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18406. %@NL@%
  18407. %@AS@%  void _far _getimage( short x1, short y1, short x2, short y2, char _huge
  18408. %@AS@%  *image );%@AE@%%@NL@%
  18409. %@NL@%
  18410. %@AS@%  void _far _getimage_w( double wx1, double wy1, double wx2, double wy2, 
  18411. %@AS@%  char _huge *image );%@AE@%%@NL@%
  18412. %@NL@%
  18413. %@AS@%  void _far _getimage_wxy( struct_wxycoord _far *pwxy1,
  18414. %@AS@%  struct_wxycoord _far *pwxy2, char _huge *image );%@AE@%%@NL@%
  18415. %@NL@%
  18416. %@AI@%x1%@AE@%, %@AI@%y1%@AE@%                            Upper-left corner of bounding rectangle
  18417.  
  18418. %@AI@%x2%@AE@%, %@AI@%y2%@AE@%                            Lower-right corner of bounding rectangle
  18419.  
  18420. %@AI@%wx1%@AE@%, %@AI@%wy1%@AE@%                          Upper-left corner of bounding rectangle
  18421.  
  18422. %@AI@%wx2%@AE@%, %@AI@%wy2%@AE@%                          Lower-right corner of bounding rectangle
  18423.  
  18424. %@AI@%pwxy1%@AE@%                             Upper-left corner of bounding rectangle
  18425.  
  18426. %@AI@%pwxy2%@AE@%                             Lower-right corner of bounding rectangle
  18427.  
  18428. %@AI@%image%@AE@%                             Storage buffer for screen image
  18429.  
  18430. %@NL@%
  18431. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18432. %@NL@%
  18433. The %@AB@%_getimage%@AE@% functions store the screen image defined by a specified
  18434. bounding rectangle into the buffer pointed to by %@AI@%image%@AE@%.  %@NL@%
  18435. %@NL@%
  18436. The %@AB@%_getimage%@AE@% function defines the bounding rectangle with the view
  18437. coordinates (%@AI@%x1%@AE@%, %@AI@%y1%@AE@%) and (%@AI@%x2%@AE@%, %@AI@%y2%@AE@%).  %@NL@%
  18438. %@NL@%
  18439. The %@AB@%_getimage_w%@AE@% function defines the bounding rectangle with the window
  18440. coordinates (%@AI@%wx1%@AE@%, %@AI@%wy1%@AE@%) and (%@AI@%wx2%@AE@%, %@AI@%wy2%@AE@%).  %@NL@%
  18441. %@NL@%
  18442. The %@AB@%_getimage_wxy%@AE@% function defines the bounding rectangle with the
  18443. window-coordinate pairs %@AI@%pwxy1%@AE@% and %@AI@%pwxy2%@AE@%.  %@NL@%
  18444. %@NL@%
  18445. The buffer must be large enough to hold the image. You can determine the
  18446. size by calling the appropriate %@AB@%_imagesize%@AE@% function at run time, or by using
  18447. the formula described on the %@AB@%_imagesize%@AE@% reference page.  %@NL@%
  18448. %@NL@%
  18449. %@NL@%
  18450. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18451. %@NL@%
  18452. None. Use %@AB@%_grstatus%@AE@% to check success.  %@NL@%
  18453. %@NL@%
  18454. %@NL@%
  18455. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18456. %@NL@%
  18457.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18458. %@NL@%
  18459. %@NL@%
  18460. %@NL@%
  18461. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18462. %@NL@%
  18463. %@AB@%_grstatus%@AE@%,  %@AB@%_imagesize%@AE@% functions,  %@AB@%_putimage%@AE@% functions  %@NL@%
  18464. %@NL@%
  18465. %@NL@%
  18466. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18467. %@NL@%
  18468. %@AS@%  /* GIMAGE.C: This example illustrates animation routines including:
  18469. %@AS@%   *          _imagesize     _getimage     _putimage
  18470. %@AS@%   */
  18471. %@AS@%  
  18472. %@AS@%  #include <conio.h>
  18473. %@AS@%  #include <stddef.h>
  18474. %@AS@%  #include <stdlib.h>
  18475. %@AS@%  #include <malloc.h>
  18476. %@AS@%  #include <graph.h>
  18477. %@AS@%  
  18478. %@AS@%  short action[5]  = { _GPSET,   _GPRESET, _GXOR,    _GOR,     _GAND     };
  18479. %@AS@%  char *descrip[5] = {  "PSET  ", "PRESET", "XOR   ", "OR    ", "AND   " };
  18480. %@AS@%  
  18481. %@AS@%  void exitfree( char _huge *buffer );
  18482. %@AS@%  
  18483. %@AS@%  void main()
  18484. %@AS@%  {
  18485. %@AS@%      char  _huge *buffer;   /* Far pointer (with _fmalloc) could be used.
  18486. %@AS@%*/
  18487. %@AS@%      long  imsize;
  18488. %@AS@%      short i, x, y = 30;
  18489. %@AS@%  
  18490. %@AS@%      if( !_setvideomode( _MAXRESMODE ) )
  18491. %@AS@%          exit( 1 );
  18492. %@AS@%  
  18493. %@AS@%      /* Measure the image to be drawn and allocate memory for it. */
  18494. %@AS@%      imsize = (size_t)_imagesize( -16, -16, +16, +16 );
  18495. %@AS@%      buffer = halloc( imsize, sizeof( char ) );
  18496. %@AS@%      if ( buffer == (char _far *)NULL )
  18497. %@AS@%          exit( 1 );
  18498. %@AS@%  
  18499. %@AS@%      _setcolor( 3 );
  18500. %@AS@%      for ( i = 0; i < 5; i++ )
  18501. %@AS@%      {
  18502. %@AS@%          /* Draw ellipse at new position and get a copy of it. */
  18503. %@AS@%          x = 50; y += 40;
  18504. %@AS@%          _ellipse( _GFILLINTERIOR, x - 15, y - 15, x + 15, y + 15 );
  18505. %@AS@%          _getimage( x - 16, y - 16, x + 16, y + 16, buffer );
  18506. %@AS@%          if( _grstatus() )
  18507. %@AS@%              exitfree( buffer );        /* Quit on error
  18508. %@AS@%*/
  18509. %@AS@%  %@AE@%%@NL@%
  18510. %@NL@%
  18511. %@AS@%  /* Display action type and copy a row of ellipses with that type. */
  18512. %@AS@%          _settextposition( 1, 1 );
  18513. %@AS@%          _outtext( descrip[i] );
  18514. %@AS@%          while( x < 260 )
  18515. %@AS@%          {
  18516. %@AS@%              x += 5;
  18517. %@AS@%              _putimage( x - 16, y - 16, buffer, action[i] );
  18518. %@AS@%              if( _grstatus() < 0 )      /* Ignore warnings, quit on errors.
  18519. %@AS@%*/
  18520. %@AS@%                  exitfree( buffer );
  18521. %@AS@%          }
  18522. %@AS@%          getch();
  18523. %@AS@%      }
  18524. %@AS@%      exitfree( buffer );
  18525. %@AS@%  }
  18526. %@AS@%  
  18527. %@AS@%  void exitfree( char _huge *buffer )
  18528. %@AS@%  {
  18529. %@AS@%      hfree( buffer );
  18530. %@AS@%      exit( !_setvideomode( _DEFAULTMODE ) );
  18531. %@AS@%  }%@AE@%%@NL@%
  18532. %@NL@%
  18533. %@NL@%
  18534. %@NL@%
  18535. %@NL@%
  18536. %@QR:_getlinestyle@%%@NL@%
  18537. %@2@%%@CR:C6A01440732 @%%@AB@%_getlinestyle%@AE@%%@EH@%%@NL@%
  18538. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18539. %@NL@%
  18540. %@NL@%
  18541. %@3@%%@AB@%Description%@CR:C6A01440733 @%%@AE@%%@EH@%%@NL@%
  18542. %@NL@%
  18543. Gets the current line style.  %@NL@%
  18544. %@NL@%
  18545. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18546. %@NL@%
  18547. %@AS@%  unsigned short _far _getlinestyle( void );%@AE@%%@NL@%
  18548. %@NL@%
  18549. %@NL@%
  18550. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18551. %@NL@%
  18552. Some graphics routines ( _lineto, %@AB@%_polygon%@AE@%, and %@AB@%_rectangle%@AE@%) output straight
  18553. lines to the screen. The type of line can be controlled with the current
  18554. line-style mask.  %@NL@%
  18555. %@NL@%
  18556. The %@AB@%_getlinestyle%@AE@% function returns the current line-style mask. The mask is
  18557. a 16-bit array in which each bit represents a pixel in the line being drawn.
  18558. If the bit is 1, the corresponding pixel is set to the color of the line
  18559. (the current color). If the bit is 0, the corresponding pixel is left
  18560. unchanged. The mask is repeated over the length of the line. The default
  18561. mask is 0xFFFF (a solid line).  %@NL@%
  18562. %@NL@%
  18563. %@NL@%
  18564. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18565. %@NL@%
  18566. If no mask has been set, %@AB@%_getlinestyle%@AE@% returns the default mask.  %@NL@%
  18567. %@NL@%
  18568. %@NL@%
  18569. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18570. %@NL@%
  18571.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18572. %@NL@%
  18573. %@NL@%
  18574. %@NL@%
  18575. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18576. %@NL@%
  18577. %@AB@%_lineto%@AE@% functions,  %@AB@%_polygon%@AE@% functions,  %@AB@%_rectangle%@AE@% functions,
  18578. %@AB@%_setlinestyle%@AE@%, %@AB@%_setwritemode%@AE@%  %@NL@%
  18579. %@NL@%
  18580. %@NL@%
  18581. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18582. %@NL@%
  18583. %@AS@%  /* GLINESTY.C: This program illustrates _setlinestyle and _getlinestyle.
  18584. %@AS@%  */
  18585. %@AS@%  
  18586. %@AS@%  #include <conio.h>
  18587. %@AS@%  #include <stdlib.h>
  18588. %@AS@%  #include <graph.h>
  18589. %@AS@%  
  18590. %@AS@%  void zigzag( short x1, short y1, short size );
  18591. %@AS@%  
  18592. %@AS@%  void main()
  18593. %@AS@%  {
  18594. %@AS@%  
  18595. %@AS@%     /* Find a valid graphics mode. */
  18596. %@AS@%     if( !_setvideomode( _MAXCOLORMODE ) )
  18597. %@AS@%        exit( 1 );
  18598. %@AS@%  
  18599. %@AS@%     /* Set line style and draw rectangle. */
  18600. %@AS@%     _setlinestyle( 0x4d );
  18601. %@AS@%     _rectangle( _GBORDER, 10, 10, 60, 60 );
  18602. %@AS@%     getch();%@AE@%%@NL@%
  18603. %@NL@%
  18604. %@AS@%  
  18605. %@AS@%     /* Draw figure with function that changes and restores line style. */
  18606. %@AS@%     zigzag( 100, 100, 90 );
  18607. %@AS@%     getch();
  18608. %@AS@%  
  18609. %@AS@%     /* Original style reused. */
  18610. %@AS@%     _rectangle( _GBORDER, 190, 190, 130, 130 );
  18611. %@AS@%     getch();
  18612. %@AS@%  
  18613. %@AS@%     _setvideomode( _DEFAULTMODE );
  18614. %@AS@%  }
  18615. %@AS@%  
  18616. %@AS@%  /* Draw box with changing line styles. Restore original style. */
  18617. %@AS@%  void zigzag( short x1, short y1, short size )
  18618. %@AS@%  {
  18619. %@AS@%     short x, y, oldcolor;
  18620. %@AS@%     unsigned short oldstyle;
  18621. %@AS@%     unsigned short style[16] = { 0x0001, 0x0003, 0x0007, 0x000f,
  18622. %@AS@%                                  0x001f, 0x003f, 0x007f, 0x00ff,
  18623. %@AS@%                                  0x01ff, 0x03ff, 0x07ff, 0x0fff,
  18624. %@AS@%                                  0x1fff, 0x3fff, 0x7fff, 0xffff };
  18625. %@AS@%  
  18626. %@AS@%     oldcolor = _getcolor();
  18627. %@AS@%     oldstyle = _getlinestyle();            /* Save old line style.
  18628. %@AS@%*/
  18629. %@AS@%     for( x = 3, y = 3; x < size; x += 3, y += 3 )
  18630. %@AS@%     {
  18631. %@AS@%        _setcolor( x % 16 );
  18632. %@AS@%        _setlinestyle( style[x % 16] );     /* Set and use new line styles
  18633. %@AS@%*/
  18634. %@AS@%        _rectangle( _GBORDER, x1 - x, y1 - y, x1 + x, y1 + y );
  18635. %@AS@%     }
  18636. %@AS@%     _setlinestyle( oldstyle );             /* Restore old line style.
  18637. %@AS@%*/
  18638. %@AS@%     _setcolor( oldcolor );
  18639. %@AS@%  }%@AE@%%@NL@%
  18640. %@NL@%
  18641. %@NL@%
  18642. %@NL@%
  18643. %@NL@%
  18644. %@QR:_getphyscoord@%%@NL@%
  18645. %@2@%%@CR:C6A01450734 @%%@AB@%_getphyscoord%@AE@%%@EH@%%@NL@%
  18646. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18647. %@NL@%
  18648. %@NL@%
  18649. %@3@%%@AB@%Description%@CR:C6A01450735 @%%@AE@%%@EH@%%@NL@%
  18650. %@NL@%
  18651. Gets physical coordinates.  %@NL@%
  18652. %@NL@%
  18653. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18654. %@NL@%
  18655. %@AS@%  struct xycoord _far _getphyscoord( short x, short y );%@AE@%%@NL@%
  18656. %@NL@%
  18657. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              View coordinates to translate
  18658.  
  18659. %@NL@%
  18660. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18661. %@NL@%
  18662. The %@AB@%_getphyscoord%@AE@% function translates the view coordinates (%@AI@%x%@AE@%, %@AI@%y%@AE@%) to
  18663. physical coordinates and returns them in an %@AB@%xycoord%@AE@% structure, defined in
  18664. GRAPH.H.  %@NL@%
  18665. %@NL@%
  18666. The %@AB@%xycoord%@AE@% structure contains the following elements:  %@NL@%
  18667. %@NL@%
  18668. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  18669. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18670. %@AB@%short xcoord%@AE@%                      %@AI@%x %@AE@%coordinate
  18671.  
  18672. %@AB@%short ycoord%@AE@%                      %@AI@%y %@AE@%coordinate
  18673.  
  18674. %@NL@%
  18675. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18676. %@NL@%
  18677. None.  %@NL@%
  18678. %@NL@%
  18679. %@NL@%
  18680. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18681. %@NL@%
  18682.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18683. %@NL@%
  18684. %@NL@%
  18685. %@NL@%
  18686. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18687. %@NL@%
  18688. %@AB@%_getviewcoord%@AE@% functions,  %@AB@%_grstatus%@AE@%,  %@AB@%_setvieworg%@AE@%,  %@AB@%_setviewport%@AE@%  %@NL@%
  18689. %@NL@%
  18690. %@NL@%
  18691. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18692. %@NL@%
  18693. See the example for %@AB@%_setwindow%@AE@%.  %@NL@%
  18694. %@NL@%
  18695. %@NL@%
  18696. %@NL@%
  18697. %@NL@%
  18698. %@QR:getpid@%%@NL@%
  18699. %@2@%%@CR:C6A01460736 @%%@AB@%getpid%@AE@%%@EH@%%@NL@%
  18700. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18701. %@NL@%
  18702. %@NL@%
  18703. %@3@%%@AB@%Description%@CR:C6A01460737 @%%@CR:C6A01460738 @%%@CR:C6A01460739 @%%@AE@%%@EH@%%@NL@%
  18704. %@NL@%
  18705. Gets the process identification.  %@NL@%
  18706. %@NL@%
  18707. %@AB@%#include <process.h>%@AE@%              Required only for function declarations
  18708.  
  18709. %@AS@%  int getpid( void );%@AE@%%@NL@%
  18710. %@NL@%
  18711. %@NL@%
  18712. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18713. %@NL@%
  18714. The %@AB@%getpid%@AE@% function returns the process ID, an integer that uniquely
  18715. identifies the calling process.  %@NL@%
  18716. %@NL@%
  18717. %@NL@%
  18718. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18719. %@NL@%
  18720. The %@AB@%getpid%@AE@% function returns the process ID. There is no error return.  %@NL@%
  18721. %@NL@%
  18722. %@NL@%
  18723. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18724. %@NL@%
  18725.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  18726. %@NL@%
  18727. %@NL@%
  18728. %@NL@%
  18729. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18730. %@NL@%
  18731. %@AB@%mktemp%@AE@%  %@NL@%
  18732. %@NL@%
  18733. %@NL@%
  18734. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18735. %@NL@%
  18736. %@AS@%  /* GETPID.C: This program uses getpid to obtain the process ID and
  18737. %@AS@%   * then prints the ID.
  18738. %@AS@%   */
  18739. %@AS@%  
  18740. %@AS@%  #include <stdio.h>
  18741. %@AS@%  #include <process.h>
  18742. %@AS@%  
  18743. %@AS@%  void main( )
  18744. %@AS@%  {
  18745. %@AS@%     /* If run from DOS, shows different ID for DOS than for DOS shell.
  18746. %@AS@%      * If execed or spawned, shows ID of parent.
  18747. %@AS@%      */
  18748. %@AS@%     printf( "\nProcess id of parent: %d\n", getpid() );
  18749. %@AS@%  }%@AE@%%@NL@%
  18750. %@NL@%
  18751. %@NL@%
  18752. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  18753. %@NL@%
  18754. %@AS@%  
  18755. %@AS@%  
  18756. %@AS@%  
  18757. %@AS@%  Process id of parent: 828%@AE@%%@NL@%
  18758. %@NL@%
  18759. %@NL@%
  18760. %@NL@%
  18761. %@NL@%
  18762. %@QR:_getpixel@%%@NL@%
  18763. %@2@%%@CR:C6A01470740 @%%@AB@%_getpixel Functions%@AE@%%@EH@%%@NL@%
  18764. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18765. %@NL@%
  18766. %@NL@%
  18767. %@3@%%@AB@%Description%@CR:C6A01470741 @%%@AE@%%@EH@%%@NL@%
  18768. %@NL@%
  18769. Get pixel values.  %@NL@%
  18770. %@NL@%
  18771. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18772. %@NL@%
  18773. %@AS@%  short _far _getpixel( short x, short y );%@AE@%%@NL@%
  18774. %@NL@%
  18775. %@AS@%  short _far _getpixel_w( double wx, double wy );%@AE@%%@NL@%
  18776. %@NL@%
  18777. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Pixel position
  18778.  
  18779. %@AI@%wx%@AE@%, %@AI@%wy %@AE@%                           Pixel position
  18780.  
  18781. %@NL@%
  18782. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18783. %@NL@%
  18784. The functions in the %@AB@%_getpixel%@AE@% family return the pixel value (a color index)
  18785. at a specified location. The %@AB@%_getpixel%@AE@% function uses the view coordinate (%@AI@%x%@AE@%,
  18786. %@AI@%y%@AE@%). The %@AB@%_getpixel_w%@AE@% function uses the window coordinate (%@AI@%wx%@AE@%, %@AI@%wy%@AE@%). The range
  18787. of possible pixel values is determined by the current video mode. The color
  18788. translation of pixel values is determined by the current palette.  %@NL@%
  18789. %@NL@%
  18790. %@NL@%
  18791. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18792. %@NL@%
  18793. If successful, the function returns the color index. If the function fails
  18794. (for example, the point lies outside the clipping region, or the program is
  18795. in a text mode), it returns -1.  %@NL@%
  18796. %@NL@%
  18797. %@NL@%
  18798. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18799. %@NL@%
  18800.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  18801. %@NL@%
  18802. %@NL@%
  18803. %@NL@%
  18804. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18805. %@NL@%
  18806. %@AB@%_getvideoconfig%@AE@%,  %@AB@%_grstatus%@AE@%,  %@AB@%_remapallpalette%@AE@%,  %@AB@%_remappalette%@AE@%,
  18807. %@AB@%_selectpalette%@AE@%, %@AB@% _setpixel%@AE@% functions,  %@AB@%_setvideomode%@AE@%  %@NL@%
  18808. %@NL@%
  18809. %@NL@%
  18810. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18811. %@NL@%
  18812. %@AS@%  /* GPIXEL.C: This program assigns different colors to randomly
  18813. %@AS@%   * selected pixels.
  18814. %@AS@%   */
  18815. %@AS@%  
  18816. %@AS@%  #include <conio.h>
  18817. %@AS@%  #include <stdlib.h>
  18818. %@AS@%  #include <graph.h>
  18819. %@AS@%  
  18820. %@AS@%  void main()
  18821. %@AS@%  {
  18822. %@AS@%     short xvar, yvar;
  18823. %@AS@%     struct videoconfig vc;
  18824. %@AS@%  %@AE@%%@NL@%
  18825. %@NL@%
  18826. %@AS@%  /* Find a valid graphics mode. */
  18827. %@AS@%     if( !_setvideomode( _MAXCOLORMODE ) )
  18828. %@AS@%        exit( 1 );
  18829. %@AS@%     _getvideoconfig( &vc );
  18830. %@AS@%  
  18831. %@AS@%     /* Draw filled ellipse to turn on certain pixels. */
  18832. %@AS@%     _ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6,
  18833. %@AS@%                               vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5
  18834. %@AS@%                                             );
  18835. %@AS@%  
  18836. %@AS@%     /* Draw random pixels in random colors... */
  18837. %@AS@%     while( !kbhit() )
  18838. %@AS@%     {
  18839. %@AS@%        /* ...but only if they are already on (inside the ellipse). */
  18840. %@AS@%        xvar = rand() % vc.numxpixels;
  18841. %@AS@%        yvar = rand() % vc.numypixels;
  18842. %@AS@%        if( _getpixel( xvar, yvar ) != 0 )
  18843. %@AS@%        {
  18844. %@AS@%           _setcolor( rand() % 16 );
  18845. %@AS@%           _setpixel( xvar, yvar );
  18846. %@AS@%        }
  18847. %@AS@%     }
  18848. %@AS@%  
  18849. %@AS@%     getch();          /* Throw away the keystroke. */
  18850. %@AS@%     _setvideomode( _DEFAULTMODE );
  18851. %@AS@%  } %@AE@%%@NL@%
  18852. %@NL@%
  18853. %@NL@%
  18854. %@NL@%
  18855. %@NL@%
  18856. %@QR:gets@%%@NL@%
  18857. %@2@%%@CR:C6A01480742 @%%@AB@%gets%@AE@%%@EH@%%@NL@%
  18858. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18859. %@NL@%
  18860. %@NL@%
  18861. %@3@%%@AB@%Description%@CR:C6A01480743 @%%@CR:C6A01480744 @% %@CR:C6A01480745 @%%@CR:C6A01480746 @%%@CR:C6A01480747 @%%@AE@%%@EH@%%@NL@%
  18862. %@NL@%
  18863. Gets a line from the %@AB@%stdin %@AE@%stream.  %@NL@%
  18864. %@NL@%
  18865. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  18866. %@NL@%
  18867. %@AS@%  char *gets( char *buffer );%@AE@%%@NL@%
  18868. %@NL@%
  18869. %@AI@%buffer%@AE@%                            Storage location for input string
  18870.  
  18871. %@NL@%
  18872. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18873. %@NL@%
  18874. The %@AB@%gets%@AE@% function reads a line from the standard input stream %@AB@%stdin%@AE@% and
  18875. stores it in %@AI@%buffer%@AE@%. The line consists of all characters up to and including
  18876. the first newline character (%@AB@%\n%@AE@%). The %@AB@%gets%@AE@% function then replaces the
  18877. newline character with a null character (%@AB@%'\0'%@AE@%) before returning the line. In
  18878. contrast, the %@AB@%fgets%@AE@% function retains the newline character.  %@NL@%
  18879. %@NL@%
  18880. %@NL@%
  18881. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18882. %@NL@%
  18883. If successful, the %@AB@%gets%@AE@% function returns its argument. A %@AB@%NULL%@AE@% pointer
  18884. indicates an error or end-of-file condition. Use %@AB@%ferror%@AE@% or %@AB@%feof%@AE@% to determine
  18885. which one has occurred.  %@NL@%
  18886. %@NL@%
  18887. %@NL@%
  18888. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18889. %@NL@%
  18890. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  18891. %@NL@%
  18892. %@NL@%
  18893. %@NL@%
  18894. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18895. %@NL@%
  18896. %@AB@%fgets%@AE@%, %@AB@%fputs%@AE@%, %@AB@%puts%@AE@%  %@NL@%
  18897. %@NL@%
  18898. %@NL@%
  18899. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18900. %@NL@%
  18901. %@AS@%  /* GETS.C */
  18902. %@AS@%  
  18903. %@AS@%  #include <stdio.h>
  18904. %@AS@%  
  18905. %@AS@%  void main()
  18906. %@AS@%  {
  18907. %@AS@%     char line[81];
  18908. %@AS@%  
  18909. %@AS@%     printf( "Input a string: " );
  18910. %@AS@%     gets( line );
  18911. %@AS@%     printf( "The line entered was: %s\n", line );
  18912. %@AS@%  }%@AE@%%@NL@%
  18913. %@NL@%
  18914. %@NL@%
  18915. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  18916. %@NL@%
  18917. %@AS@%  
  18918. %@AS@%  
  18919. %@AS@%  Input a string: This is a string
  18920. %@AS@%  The line entered was: This is a string %@AE@%%@NL@%
  18921. %@NL@%
  18922. %@NL@%
  18923. %@NL@%
  18924. %@NL@%
  18925. %@QR:_gettextcolor@%%@NL@%
  18926. %@2@%%@CR:C6A01490748 @%%@AB@%_gettextcolor%@AE@%%@EH@%%@NL@%
  18927. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18928. %@NL@%
  18929. %@NL@%
  18930. %@3@%%@AB@%Description%@CR:C6A01490749 @%%@AE@%%@EH@%%@NL@%
  18931. %@NL@%
  18932. Gets the current text color.  %@NL@%
  18933. %@NL@%
  18934. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18935. %@NL@%
  18936. %@AS@%  short _far _gettextcolor( void );%@AE@%%@NL@%
  18937. %@NL@%
  18938. %@NL@%
  18939. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18940. %@NL@%
  18941. The %@AB@%_gettextcolor%@AE@% function returns the color index of the current text
  18942. color. The text color is set by the %@AB@%_settextcolor%@AE@% function and affects text
  18943. output with the %@AB@%_outtext%@AE@% and %@AB@%_outmem%@AE@% functions only. The %@AB@%_setcolor%@AE@% function
  18944. sets the color for font text output using the %@AB@% _outgtext%@AE@% function.  %@NL@%
  18945. %@NL@%
  18946. The default is 7 in test modes; it is the highest legal color index of the
  18947. current palette in graphics modes.  %@NL@%
  18948. %@NL@%
  18949. %@NL@%
  18950. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18951. %@NL@%
  18952. The %@AB@%_gettextcolor%@AE@% function returns the color index of the current text
  18953. color.  %@NL@%
  18954. %@NL@%
  18955. %@NL@%
  18956. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  18957. %@NL@%
  18958.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  18959. %@NL@%
  18960. %@NL@%
  18961. %@NL@%
  18962. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  18963. %@NL@%
  18964. %@AB@%_getvideoconfig%@AE@%,  %@AB@%_remappalette%@AE@%,  %@AB@%_selectpalette%@AE@%,  %@AB@%_setcolor%@AE@%,  %@AB@%_settextcolor%@AE@%
  18965. %@NL@%
  18966. %@NL@%
  18967. %@NL@%
  18968. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  18969. %@NL@%
  18970. See the example for %@AB@%_gettextposition%@AE@%.  %@NL@%
  18971. %@NL@%
  18972. %@NL@%
  18973. %@NL@%
  18974. %@NL@%
  18975. %@QR:_gettextcursor@%%@NL@%
  18976. %@2@%%@CR:C6A01500750 @%%@AB@%_gettextcursor%@AE@%%@EH@%%@NL@%
  18977. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  18978. %@NL@%
  18979. %@NL@%
  18980. %@3@%%@AB@%Description%@CR:C6A01500751 @%%@AE@%%@EH@%%@NL@%
  18981. %@NL@%
  18982. Gets the current cursor attribute.  %@NL@%
  18983. %@NL@%
  18984. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  18985. %@NL@%
  18986. %@AS@%  short _far _gettextcursor( void );%@AE@%%@NL@%
  18987. %@NL@%
  18988. %@NL@%
  18989. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  18990. %@NL@%
  18991. The %@AB@%_gettextcursor%@AE@% function returns the current cursor attribute (i.e., the
  18992. shape). This function works only in text video modes.  %@NL@%
  18993. %@NL@%
  18994. %@NL@%
  18995. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  18996. %@NL@%
  18997. The function returns the current cursor attribute, or -1 if an error occurs
  18998. (such as a call to the function in a graphics mode).  %@NL@%
  18999. %@NL@%
  19000. %@NL@%
  19001. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19002. %@NL@%
  19003.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19004. %@NL@%
  19005. %@NL@%
  19006. %@NL@%
  19007. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19008. %@NL@%
  19009. %@AB@%_displaycursor%@AE@%,  %@AB@%_grstatus%@AE@%,  %@AB@%_settextcursor%@AE@%  %@NL@%
  19010. %@NL@%
  19011. %@NL@%
  19012. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19013. %@NL@%
  19014. See the example for %@AB@%_settextcursor%@AE@%.  %@NL@%
  19015. %@NL@%
  19016. %@NL@%
  19017. %@NL@%
  19018. %@NL@%
  19019. %@QR:_gettextposition@%%@NL@%
  19020. %@2@%%@CR:C6A01510752 @%%@AB@%_gettextposition%@AE@%%@EH@%%@NL@%
  19021. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19022. %@NL@%
  19023. %@NL@%
  19024. %@3@%%@AB@%Description%@CR:C6A01510753 @%%@AE@%%@EH@%%@NL@%
  19025. %@NL@%
  19026. Gets the current text position.  %@NL@%
  19027. %@NL@%
  19028. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19029. %@NL@%
  19030. %@AS@%  struct rccoord _far _gettextposition( void );%@AE@%%@NL@%
  19031. %@NL@%
  19032. %@NL@%
  19033. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19034. %@NL@%
  19035. The %@AB@%_gettextposition%@AE@% function returns the current text position as an
  19036. %@AB@%rccoord%@AE@% structure, defined in GRAPH.H.  %@NL@%
  19037. %@NL@%
  19038. The %@AB@%rccoord%@AE@% structure contains the following elements:  %@NL@%
  19039. %@NL@%
  19040. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  19041. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19042. %@AB@%short row%@AE@%                         Row coordinate
  19043.  
  19044. %@AB@%short col%@AE@%                         Column coordinate
  19045.  
  19046. %@NL@%
  19047. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19048. %@NL@%
  19049. The text position given by the coordinates (1,1) is defined as the
  19050. upper-left corner of the text window.  %@NL@%
  19051. %@NL@%
  19052. Text output from the %@AB@%_outtext%@AE@% and %@AB@%_outmem%@AE@% functions begins at the current
  19053. text position. Font text is not affected by the current text position. Font
  19054. text output begins at the current graphics output position, which is a
  19055. separate position.  %@NL@%
  19056. %@NL@%
  19057. %@NL@%
  19058. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19059. %@NL@%
  19060. None.  %@NL@%
  19061. %@NL@%
  19062. %@NL@%
  19063. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19064. %@NL@%
  19065.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19066. %@NL@%
  19067. %@NL@%
  19068. %@NL@%
  19069. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19070. %@NL@%
  19071. %@AB@%_getcurrentposition%@AE@% functions,  %@AB@%_moveto%@AE@% functions,  %@AB@%_outmem%@AE@%,%@AB@%  _outtext%@AE@%,
  19072. %@AB@%_settextposition%@AE@%,  %@AB@%_settextwindow%@AE@%,  %@AB@%_wrapon%@AE@%  %@NL@%
  19073. %@NL@%
  19074. %@NL@%
  19075. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19076. %@NL@%
  19077. %@AS@%  /* OUTTXT.C: This example illustrates text output functions:
  19078. %@AS@%   *    _gettextcolor   _getbkcolor   _gettextposition   _outtext
  19079. %@AS@%   *    _settextcolor   _setbkcolor   _settextposition
  19080. %@AS@%   */
  19081. %@AS@%  
  19082. %@AS@%  #include <conio.h>
  19083. %@AS@%  #include <stdio.h>
  19084. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19085. %@NL@%
  19086. %@AS@%  char buffer [80];
  19087. %@AS@%  
  19088. %@AS@%  void main()
  19089. %@AS@%  {
  19090. %@AS@%  
  19091. %@AS@%     /* Save original foreground, background, and text position. */
  19092. %@AS@%     short blink, fgd, oldfgd;
  19093. %@AS@%     long  bgd, oldbgd;
  19094. %@AS@%     struct rccoord oldpos;
  19095. %@AS@%  
  19096. %@AS@%     /* Save original foreground, background, and text position. */
  19097. %@AS@%     oldfgd = _gettextcolor();
  19098. %@AS@%     oldbgd = _getbkcolor();
  19099. %@AS@%     oldpos = _gettextposition();
  19100. %@AS@%     _clearscreen( _GCLEARSCREEN );
  19101. %@AS@%  
  19102. %@AS@%     /* First time no blink, second time blinking. */
  19103. %@AS@%     for( blink = 0; blink <= 16; blink += 16 )
  19104. %@AS@%     {
  19105. %@AS@%        /* Loop through 8 background colors. */
  19106. %@AS@%        for( bgd = 0; bgd < 8; bgd++ )
  19107. %@AS@%        {
  19108. %@AS@%           _setbkcolor( bgd );
  19109. %@AS@%           _settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 );
  19110. %@AS@%           _settextcolor( 7 );
  19111. %@AS@%           sprintf(buffer, "Back: %d Fore:", bgd );
  19112. %@AS@%           _outtext( buffer );
  19113. %@AS@%  
  19114. %@AS@%           /* Loop through 16 foreground colors. */
  19115. %@AS@%           for( fgd = 0; fgd < 16; fgd++ )
  19116. %@AS@%           {
  19117. %@AS@%              _settextcolor( fgd + blink );
  19118. %@AS@%              sprintf( buffer, " %2d ", fgd + blink );
  19119. %@AS@%              _outtext( buffer );
  19120. %@AS@%           }
  19121. %@AS@%        }
  19122. %@AS@%     }
  19123. %@AS@%     getch();
  19124. %@AS@%  
  19125. %@AS@%     /* Restore original foreground, background, and text position. */
  19126. %@AS@%     _settextcolor( oldfgd );
  19127. %@AS@%     _setbkcolor( oldbgd );
  19128. %@AS@%     _clearscreen( _GCLEARSCREEN );
  19129. %@AS@%     _settextposition( oldpos.row, oldpos.col );
  19130. %@AS@%  }%@AE@%%@NL@%
  19131. %@NL@%
  19132. %@NL@%
  19133. %@NL@%
  19134. %@NL@%
  19135. %@QR:_gettextwindow@%%@NL@%
  19136. %@2@%%@CR:C6A01520754 @%%@AB@%_gettextwindow%@AE@%%@EH@%%@NL@%
  19137. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19138. %@NL@%
  19139. %@NL@%
  19140. %@3@%%@AB@%Description%@CR:C6A01520755 @% %@CR:C6A01520756 @%%@AE@%%@EH@%%@NL@%
  19141. %@NL@%
  19142. Gets the boundaries of the current text window.  %@NL@%
  19143. %@NL@%
  19144. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19145. %@NL@%
  19146. %@AS@%  void _far _gettextwindow( short _far *r1, short _far *c1, short _far *r2, 
  19147. %@AS@%  short _far *c2 );%@AE@%%@NL@%
  19148. %@NL@%
  19149. %@AI@%r1%@AE@%                                Top row of current text window
  19150.  
  19151. %@AI@%c1%@AE@%                                Leftmost column of current text window
  19152.  
  19153. %@AI@%r2%@AE@%                                Bottom row of current text window
  19154.  
  19155. %@AI@%c2%@AE@%                                Rightmost column of current text window
  19156.  
  19157. %@NL@%
  19158. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19159. %@NL@%
  19160. The %@AB@%_gettextwindow%@AE@% function finds the boundaries of the current text window.
  19161. The text window is the region of the screen to which output from the
  19162. %@AB@%_outtext%@AE@% and %@AB@%_outmem%@AE@% functions is limited. By default, this is the entire
  19163. screen, unless it has been redefined by the %@AB@%_settextwindow%@AE@% function.  %@NL@%
  19164. %@NL@%
  19165. The window defined by %@AB@%_settextwindow %@AE@%has no effect on output from the%@AB@%
  19166. %@AB@%_outgtext%@AE@% function. Text displayed with %@AB@%_outgtext%@AE@% is limited to the current
  19167. viewport.  %@NL@%
  19168. %@NL@%
  19169. %@NL@%
  19170. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19171. %@NL@%
  19172. None.  %@NL@%
  19173. %@NL@%
  19174. %@NL@%
  19175. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19176. %@NL@%
  19177.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19178. %@NL@%
  19179. %@NL@%
  19180. %@NL@%
  19181. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19182. %@NL@%
  19183. %@AB@%_gettextposition%@AE@%,  %@AB@%_outmem%@AE@%,  %@AB@%_outtext%@AE@%,  %@AB@%_scrolltextwindow%@AE@%,
  19184. %@AB@%_settextposition%@AE@%, %@AB@%_settextwindow%@AE@%,  %@AB@%_wrapon%@AE@%  %@NL@%
  19185. %@NL@%
  19186. %@NL@%
  19187. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19188. %@NL@%
  19189. See the example for %@AB@%_scrolltextwindow%@AE@%.  %@NL@%
  19190. %@NL@%
  19191. %@NL@%
  19192. %@NL@%
  19193. %@NL@%
  19194. %@QR:_getvideoconfig@%%@NL@%
  19195. %@2@%%@CR:C6A01530757 @%%@AB@%_getvideoconfig%@AE@%%@EH@%%@NL@%
  19196. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19197. %@NL@%
  19198. %@NL@%
  19199. %@3@%%@AB@%Description%@CR:C6A01530758 @%%@AE@%%@EH@%%@NL@%
  19200. %@NL@%
  19201. Gets graphics video configuration information.  %@NL@%
  19202. %@NL@%
  19203. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19204. %@NL@%
  19205. %@AS@%  struct videoconfig _far * _far _getvideoconfig( struct videoconfig _far
  19206. %@AS@%  *config );%@AE@%%@NL@%
  19207. %@NL@%
  19208. %@AI@%config%@AE@%                            Configuration information
  19209.  
  19210. %@NL@%
  19211. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19212. %@NL@%
  19213. The %@AB@%_getvideoconfig%@AE@% function returns the current graphics environment
  19214. configuration in a %@AB@%videoconfig%@AE@% structure, defined in GRAPH.H.  %@NL@%
  19215. %@NL@%
  19216. The values returned reflect the currently active video adapter and monitor,
  19217. as well as the current video mode.  %@NL@%
  19218. %@NL@%
  19219. The %@AB@%videoconfig%@AE@% structure contains the following members, each of which is
  19220. of type %@AB@%short%@AE@%:  %@NL@%
  19221. %@NL@%
  19222. %@AB@%Member%@AE@%                            %@AB@%Contents%@AE@%
  19223. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19224. %@AB@%adapter%@AE@%                           Active display adapter
  19225.  
  19226. %@AB@%bitsperpixel%@AE@%                      Number of bits per pixel
  19227.  
  19228. %@AB@%memory%@AE@%                            Adapter video memory in kilobytes
  19229.  
  19230. %@AB@%mode%@AE@%                              Current video mode
  19231.  
  19232. %@AB@%monitor%@AE@%                           Active display monitor
  19233.  
  19234. %@AB@%numcolors%@AE@%                         Number of color indices
  19235.  
  19236. %@AB@%numtextcols%@AE@%                       Number of text columns available
  19237.  
  19238. %@AB@%numtextrows%@AE@%                       Number of text rows available
  19239.  
  19240. %@AB@%numvideopages%@AE@%                     Number of available video pages
  19241.  
  19242. %@AB@%numxpixels%@AE@%                        Number of pixels on the %@AI@%x%@AE@% axis
  19243.  
  19244. %@AB@%numypixels%@AE@%                        Number of pixels on the %@AI@%y%@AE@% axis
  19245.  
  19246. %@AB@%  %@AE@%%@NL@%
  19247. %@NL@%
  19248. The values for the %@AB@%adapter%@AE@% member of the %@AB@%videoconfig%@AE@% structure are given by
  19249. the manifest constants shown in the list below. For any applicable adapter (
  19250. %@AB@%_CGA%@AE@%, %@AB@%_EGA%@AE@%, or %@AB@%_VGA%@AE@%), the corresponding Olivetti(R) adapter ( %@AB@%_OCGA%@AE@%, %@AB@%_OEGA%@AE@%,
  19251. or %@AB@%_OVGA%@AE@%) represents a superset of graphics capabilities.  %@NL@%
  19252. %@NL@%
  19253. %@AB@%Adapter Constant%@AE@%                  %@AB@%Meaning%@AE@%
  19254. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19255. %@AB@%_CGA%@AE@%                              Color Graphics Adapter
  19256.  
  19257. %@AB@%_EGA%@AE@%                              Enhanced Graphics Adapter
  19258.  
  19259. %@AB@%_HGC%@AE@%                              Hercules(R) Graphics Card
  19260.  
  19261. %@AB@%_MCGA%@AE@%                             Multicolor Graphics Array
  19262.  
  19263. %@AB@%_MDPA%@AE@%                             Monochrome Display Printer Adapter
  19264.  
  19265. %@AB@%_OCGA%@AE@%                             Olivetti (AT&T(R)) Color Graphics 
  19266.                                   Adapter
  19267.  
  19268. %@AB@%_OEGA%@AE@%                             Olivetti (AT&T) Enhanced Graphics 
  19269.                                   Adapter
  19270.  
  19271. %@AB@%_OVGA%@AE@%                             Olivetti (AT&T) Video Graphics Array
  19272.  
  19273. %@AB@%_VGA%@AE@%                              Video Graphics Array
  19274.  
  19275. The values for the %@AB@%monitor%@AE@% member of the %@AB@%videoconfig%@AE@% structure are given by
  19276. the manifest constants listed below:  %@NL@%
  19277. %@NL@%
  19278. %@AB@%Monitor Constant%@AE@%                  %@AB@%Meaning%@AE@%
  19279. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19280. %@AB@%_ANALOG%@AE@%                           Analog monochrome and color
  19281.  
  19282. %@AB@%_ANALOGCOLOR%@AE@%                      Analog color only
  19283.  
  19284. %@AB@%_ANALOGMONO%@AE@%                       Analog monochrome only
  19285.  
  19286. %@AB@%_COLOR%@AE@%                            Color (or enhanced monitor emulating a 
  19287.                                   color monitor)
  19288.  
  19289. %@AB@%_ENHCOLOR%@AE@%                         Enhanced color
  19290.  
  19291. %@AB@%_MONO%@AE@%                             Monochrome monitor
  19292.  
  19293. In every text mode, including monochrome, the %@AB@%_getvideoconfig%@AE@% function
  19294. returns the value 32 for the number of available colors. The value 32
  19295. indicates the range of values (0 -31) accepted by the %@AB@%_settextcolor%@AE@%
  19296. function. This includes 16 normal colors (0 -15) and 16 blinking colors (16
  19297. -31). Blinking is selected by adding 16 to the normal color index. Because
  19298. monochrome text mode has fewer unique display attributes, some color indices
  19299. are redundant. However, because blinking is selected in the same manner,
  19300. monochrome text mode has the same range (0 -31) as other text modes.  %@NL@%
  19301. %@NL@%
  19302. %@NL@%
  19303. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19304. %@NL@%
  19305. The %@AB@%_getvideoconfig%@AE@% function returns the video configuration information in
  19306. a structure, as noted above. There is no error return.  %@NL@%
  19307. %@NL@%
  19308. %@NL@%
  19309. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19310. %@NL@%
  19311.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19312. %@NL@%
  19313. %@NL@%
  19314. %@NL@%
  19315. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19316. %@NL@%
  19317. %@AB@%_setvideomode%@AE@%,  %@AB@%_setvideomoderows%@AE@%  %@NL@%
  19318. %@NL@%
  19319. %@NL@%
  19320. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19321. %@NL@%
  19322. %@AS@%  /* GVIDCFG.C: This program displays information about the current
  19323. %@AS@%   * video configuration.
  19324. %@AS@%   */
  19325. %@AS@%  
  19326. %@AS@%  #include <stdio.h>
  19327. %@AS@%  #include <graph.h>
  19328. %@AS@%  
  19329. %@AS@%  void main()
  19330. %@AS@%  {
  19331. %@AS@%     struct videoconfig vc;
  19332. %@AS@%     short  c;
  19333. %@AS@%     char   b[500];                        /* Buffer for string */
  19334. %@AS@%  
  19335. %@AS@%     _getvideoconfig( &vc );
  19336. %@AS@%  
  19337. %@AS@%     /* Write all information to a string, then output string. */
  19338. %@AS@%     c  = sprintf( b,     "X pixels:     %d\n", vc.numxpixels );
  19339. %@AS@%     c += sprintf( b + c, "Y pixels:     %d\n", vc.numypixels );
  19340. %@AS@%     c += sprintf( b + c, "Text columns: %d\n", vc.numtextcols );
  19341. %@AS@%     c += sprintf( b + c, "Text rows:    %d\n", vc.numtextrows );
  19342. %@AS@%     c += sprintf( b + c, "Colors:       %d\n", vc.numcolors );
  19343. %@AS@%     c += sprintf( b + c, "Bits/pixel:   %d\n", vc.bitsperpixel );
  19344. %@AS@%     c += sprintf( b + c, "Video pages:  %d\n", vc.numvideopages );
  19345. %@AS@%     c += sprintf( b + c, "Mode:         %d\n", vc.mode );
  19346. %@AS@%     c += sprintf( b + c, "Adapter:      %d\n", vc.adapter );
  19347. %@AS@%     c += sprintf( b + c, "Monitor:      %d\n", vc.monitor );
  19348. %@AS@%     c += sprintf( b + c, "Memory:       %d\n", vc.memory );
  19349. %@AS@%     _outtext( b );
  19350. %@AS@%  }%@AE@%%@NL@%
  19351. %@NL@%
  19352. %@NL@%
  19353. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  19354. %@NL@%
  19355. %@AS@%  
  19356. %@AS@%  
  19357. %@AS@%  X pixels:     0
  19358. %@AS@%  Y pixels:     0
  19359. %@AS@%  Text columns: 80
  19360. %@AS@%  Text rows:    25
  19361. %@AS@%  Colors:       32
  19362. %@AS@%  Bits/pixel:   0
  19363. %@AS@%  Video pages:  1
  19364. %@AS@%  Mode:         3
  19365. %@AS@%  Adapter:      8
  19366. %@AS@%  Monitor:      24
  19367. %@AS@%  Memory:       256%@AE@%%@NL@%
  19368. %@NL@%
  19369. %@NL@%
  19370. %@NL@%
  19371. %@NL@%
  19372. %@QR:_getviewcoord@%%@NL@%
  19373. %@2@%%@CR:C6A01540759 @%%@AB@%_getviewcoord Functions%@AE@%%@EH@%%@NL@%
  19374. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19375. %@NL@%
  19376. %@NL@%
  19377. %@3@%%@AB@%Description %@CR:C6A01540760 @%%@AE@%%@EH@%%@NL@%
  19378. %@NL@%
  19379. Translate coordinates to view coordinates.  %@NL@%
  19380. %@NL@%
  19381. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19382. %@NL@%
  19383. %@AS@%  struct xycoord _far _getviewcoord( short x, short y );%@AE@%%@NL@%
  19384. %@NL@%
  19385. %@AS@%  struct xycoord _far _getviewcoord_w( double wx, double wy );%@AE@%%@NL@%
  19386. %@NL@%
  19387. %@AS@%  struct xycoord _far _getviewcoord_wxy( struct _wxycoord _far *pwxy1 );%@AE@%%@NL@%
  19388. %@NL@%
  19389. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Physical point to translate
  19390.  
  19391. %@AI@%wx%@AE@%, %@AI@%wy%@AE@%                            Window point to translate
  19392.  
  19393. %@AI@%pwxy1%@AE@%                             Window point to translate
  19394.  
  19395. %@NL@%
  19396. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19397. %@NL@%
  19398. The %@AB@%_getviewcoord%@AE@% routines translate the specified coordinates (%@AI@%x%@AE@%, %@AI@%y%@AE@%) from
  19399. one coordinate system to view coordinates and then return them in an %@AB@%xycoord%@AE@%
  19400. structure, defined in GRAPH.H. The %@AB@%xycoord %@AE@%structure contains the following
  19401. elements:  %@NL@%
  19402. %@NL@%
  19403. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  19404. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19405. %@AB@%short xcoord%@AE@%                      %@AI@%x%@AE@% coordinate
  19406.  
  19407. %@AB@%short ycoord%@AE@%                      %@AI@%y%@AE@% coordinate
  19408.  
  19409. The various %@AB@%_getviewcoord%@AE@% routines translate in the following manner:  %@NL@%
  19410. %@NL@%
  19411. %@AB@%Routine%@AE@%                           %@AB@%Translation%@AE@%
  19412. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19413. %@AB@%_getviewcoord%@AE@%                     Physical coordinates (%@AI@%x%@AE@%, %@AI@%y%@AE@%) to view 
  19414.                                   coordinates
  19415.  
  19416. %@AB@%_getviewcoord_w%@AE@%                   Window coordinates (%@AI@%wx%@AE@%, %@AI@%wy%@AE@%) to view 
  19417.                                   coordinates
  19418.  
  19419. %@AB@%_getviewcoord_wxy%@AE@%                 Window coordinates structure (%@AI@%pwxy1%@AE@%) to 
  19420.                                   view coordinates
  19421.  
  19422. ────────────────────────────────────────────────────────────────────────────%@NL@%
  19423. C 5.1 Version Difference
  19424. %@AI@%%@AI@%In Microsoft C version 5.1, the function %@AE@%%@AI@%%@AB@%_getviewcoord%@AE@%%@AE@%%@AI@% was called %@AE@%%@AI@%%@AB@%
  19425. %@AB@%_getlogcoord%@AE@%%@AE@%%@AI@%.%@AE@%%@AE@%%@NL@%
  19426. ────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  19427. %@NL@%
  19428. %@NL@%
  19429. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19430. %@NL@%
  19431. The %@AB@%_getviewcoord%@AE@% function returns the coordinates as noted above. There is
  19432. no error  return.  %@NL@%
  19433. %@NL@%
  19434. %@NL@%
  19435. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19436. %@NL@%
  19437.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  19438. %@NL@%
  19439. %@NL@%
  19440. %@NL@%
  19441. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19442. %@NL@%
  19443. %@AB@%_getphyscoord%@AE@%,  %@AB@%_getwindowcoord,  _grstatus  %@AE@%%@NL@%
  19444. %@NL@%
  19445. %@NL@%
  19446. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19447. %@NL@%
  19448. See the example for %@AB@%_setwindow%@AE@%.%@AB@%  %@AE@%%@NL@%
  19449. %@NL@%
  19450. %@NL@%
  19451. %@NL@%
  19452. %@NL@%
  19453. %@QR:_getvisualpage@%%@NL@%
  19454. %@2@%%@CR:C6A01550761 @%%@AB@%_getvisualpage%@AE@%%@EH@%%@NL@%
  19455. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19456. %@NL@%
  19457. %@NL@%
  19458. %@3@%%@AB@%Description%@CR:C6A01550762 @%%@AE@%%@EH@%%@NL@%
  19459. %@NL@%
  19460. Gets the current visual page number.  %@NL@%
  19461. %@NL@%
  19462. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19463. %@NL@%
  19464. %@AS@%  short _far _getvisualpage( void );%@AE@%%@NL@%
  19465. %@NL@%
  19466. %@NL@%
  19467. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19468. %@NL@%
  19469. The %@AB@%_getvisualpage%@AE@% function returns the current visual page number.  %@NL@%
  19470. %@NL@%
  19471. %@NL@%
  19472. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19473. %@NL@%
  19474. The function returns the number of the current visual page. All hardware
  19475. combinations support at least one page (page number 0). In OS/2, only page 0
  19476. is available.  %@NL@%
  19477. %@NL@%
  19478. %@NL@%
  19479. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19480. %@NL@%
  19481.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19482. %@NL@%
  19483. %@NL@%
  19484. %@NL@%
  19485. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19486. %@NL@%
  19487. %@AB@%_getactivepage%@AE@%,  %@AB@%_gettextcolor%@AE@%,  %@AB@%_gettextposition%@AE@%,  %@AB@%_outtext%@AE@%,
  19488. %@AB@%_setactivepage%@AE@%, %@AB@%_settextcolor%@AE@%,  %@AB@%_settextposition%@AE@%, %@AB@% _settextwindow%@AE@%,
  19489. %@AB@%_setvideomode%@AE@%, %@AB@%_setvisualpage%@AE@%,  %@AB@%_wrapon%@AE@%  %@NL@%
  19490. %@NL@%
  19491. %@NL@%
  19492. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19493. %@NL@%
  19494. See the example for %@AB@%_getactivepage%@AE@%.  %@NL@%
  19495. %@NL@%
  19496. %@NL@%
  19497. %@NL@%
  19498. %@NL@%
  19499. %@QR:getw@%%@NL@%
  19500. %@2@%%@CR:C6A01560763 @%%@AB@%getw%@AE@%%@EH@%%@NL@%
  19501. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19502. %@NL@%
  19503. %@NL@%
  19504. %@3@%%@AB@%Description%@CR:C6A01560764 @%%@CR:C6A01560765 @% %@CR:C6A01560766 @%%@CR:C6A01560767 @% %@CR:C6A01560768 @%%@AE@%%@EH@%%@NL@%
  19505. %@NL@%
  19506. Gets an integer from a stream.  %@NL@%
  19507. %@NL@%
  19508. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  19509. %@NL@%
  19510. %@AS@%  int getw( FILE *stream );%@AE@%%@NL@%
  19511. %@NL@%
  19512. %@AI@%stream%@AE@%                            Pointer to %@AB@%FILE structure%@AE@%
  19513.  
  19514. %@NL@%
  19515. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19516. %@NL@%
  19517. The %@AB@%getw%@AE@% function reads the next binary value of type %@AB@%int%@AE@% from the file
  19518. associated with %@AI@%stream%@AE@% and increments the associated file pointer (if there
  19519. is one) to point to the next unread character. The %@AB@%getw%@AE@% function does not
  19520. assume any special alignment of items in the stream.  %@NL@%
  19521. %@NL@%
  19522. %@NL@%
  19523. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19524. %@NL@%
  19525. The %@AB@%getw%@AE@% function returns the integer value read. A return value of %@AB@%EOF may
  19526. %@AB@%indicate an error or end-of-file. However, since the EOF valu%@AE@%e is also a
  19527. legitimate integer value, %@AB@%feof%@AE@% or %@AB@%ferror%@AE@% should be used to verify an
  19528. end-of-file or error condition.  %@NL@%
  19529. %@NL@%
  19530. %@NL@%
  19531. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19532. %@NL@%
  19533.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  19534. %@NL@%
  19535. %@NL@%
  19536. The %@AB@%getw%@AE@% function is provided primarily for compatibility with previous
  19537. libraries. Note that portability problems may occur with %@AB@%getw%@AE@%, since the
  19538. size of the %@AB@%int%@AE@% type and the ordering of bytes within the %@AB@%int%@AE@% type differ
  19539. across systems.  %@NL@%
  19540. %@NL@%
  19541. %@NL@%
  19542. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19543. %@NL@%
  19544. %@AB@%putw%@AE@%  %@NL@%
  19545. %@NL@%
  19546. %@NL@%
  19547. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19548. %@NL@%
  19549. %@AS@%  /* GETW.C: This program uses getw to read a word from a stream,
  19550. %@AS@%   * then performs an error check.
  19551. %@AS@%   */
  19552. %@AS@%  
  19553. %@AS@%  #include <stdio.h>
  19554. %@AS@%  #include <stdlib.h>
  19555. %@AS@%  
  19556. %@AS@%  void main()
  19557. %@AS@%  {
  19558. %@AS@%  
  19559. %@AS@%     FILE *stream;
  19560. %@AS@%     int i;
  19561. %@AS@%  %@AE@%%@NL@%
  19562. %@NL@%
  19563. %@AS@%  if( (stream = fopen( "getw.c", "rb" )) == NULL )
  19564. %@AS@%        printf( "Couldn't open file\n" );
  19565. %@AS@%     else
  19566. %@AS@%     {
  19567. %@AS@%        /* Read a word from the stream: */
  19568. %@AS@%        i = getw( stream );
  19569. %@AS@%  
  19570. %@AS@%        /* If there is an error... */
  19571. %@AS@%        if( ferror( stream ) )
  19572. %@AS@%        {
  19573. %@AS@%           printf( "getw failed\n" );
  19574. %@AS@%           clearerr( stream );
  19575. %@AS@%        }
  19576. %@AS@%        else
  19577. %@AS@%           printf( "First data word in file: 0x%.4x\n", i );
  19578. %@AS@%        fclose( stream );
  19579. %@AS@%     }
  19580. %@AS@%  }%@AE@%%@NL@%
  19581. %@NL@%
  19582. %@NL@%
  19583. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  19584. %@NL@%
  19585. %@AS@%  
  19586. %@AS@%  
  19587. %@AS@%  First data word in file: 0x2a2f %@AE@%%@NL@%
  19588. %@NL@%
  19589. %@NL@%
  19590. %@NL@%
  19591. %@NL@%
  19592. %@QR:_getwindowcoord@%%@NL@%
  19593. %@2@%%@CR:C6A01570769 @%%@AB@%_getwindowcoord%@AE@%%@EH@%%@NL@%
  19594. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19595. %@NL@%
  19596. %@NL@%
  19597. %@3@%%@AB@%Description%@CR:C6A01570770 @%%@AE@%%@EH@%%@NL@%
  19598. %@NL@%
  19599. Translates view coordinates to window coordinates.  %@NL@%
  19600. %@NL@%
  19601. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  19602. %@NL@%
  19603. %@AS@%  struct _wxycoord _far _getwindowcoord( short x, short y );%@AE@%%@NL@%
  19604. %@NL@%
  19605. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Physical point to translate
  19606.  
  19607. %@NL@%
  19608. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19609. %@NL@%
  19610. The %@AB@%_getwindowcoord%@AE@% function translates the view coordinates (%@AI@%x%@AE@%, %@AI@%y%@AE@%) to
  19611. window coordinates and returns them in the %@AB@%_wxycoord%@AE@% structure, defined in
  19612. GRAPH.H.  %@NL@%
  19613. %@NL@%
  19614. The %@AB@%_wxycoord %@AE@%structure contains the following elements:  %@NL@%
  19615. %@NL@%
  19616. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  19617. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19618. %@AB@%double wx%@AE@%                         %@AI@%x%@AE@% coordinate
  19619.  
  19620. %@AB@%double wy%@AE@%                         %@AI@%y%@AE@% coordinate
  19621.  
  19622. %@NL@%
  19623. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19624. %@NL@%
  19625. The function returns the coordinates in the %@AB@%_wxycoord%@AE@% structure. There is no
  19626. error return.  %@NL@%
  19627. %@NL@%
  19628. %@NL@%
  19629. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19630. %@NL@%
  19631.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  19632. %@NL@%
  19633. %@NL@%
  19634. %@NL@%
  19635. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19636. %@NL@%
  19637. %@AB@%_getphyscoord%@AE@%,  %@AB@%_getviewcoord%@AE@% functions, %@AB@% _moveto%@AE@% functions,  %@AB@%_setwindow%@AE@%  %@NL@%
  19638. %@NL@%
  19639. %@NL@%
  19640. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19641. %@NL@%
  19642. See the example for %@AB@%_setwindow%@AE@%.  %@NL@%
  19643. %@NL@%
  19644. %@NL@%
  19645. %@NL@%
  19646. %@NL@%
  19647. %@QR:_getwritemode@%%@NL@%
  19648. %@2@%%@CR:C6A01580771 @%%@AB@%_getwritemode%@AE@%%@EH@%%@NL@%
  19649. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19650. %@NL@%
  19651. %@NL@%
  19652. %@3@%%@AB@%Description%@CR:C6A01580772 @% %@CR:C6A01580773 @%%@AE@%%@EH@%%@NL@%
  19653. %@NL@%
  19654. Gets the current logical mode for line drawing.  %@NL@%
  19655. %@NL@%
  19656. %@AS@%  #include  <graph.h>%@AE@%%@NL@%
  19657. %@NL@%
  19658. %@AS@%  short _far _getwritemode( void );%@AE@%%@NL@%
  19659. %@NL@%
  19660. %@NL@%
  19661. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19662. %@NL@%
  19663. The %@AB@%_getwritemode%@AE@% function returns the current logical write mode, which is
  19664. used when drawing lines with the %@AB@%_lineto%@AE@%,%@AB@% _polygon%@AE@%, and%@AB@% _rectangle%@AE@%
  19665. functions.  %@NL@%
  19666. %@NL@%
  19667. The default value is %@AB@%_GPSET%@AE@%, which causes lines to be drawn in the current
  19668. graphics color. The other possible return values are %@AB@%_GXOR%@AE@%, %@AB@%_GAND%@AE@%, %@AB@%_GOR%@AE@%, and
  19669. %@AB@%_GPRESET%@AE@%. See %@AB@%_putimage%@AE@% for more details on these manifest constants.  %@NL@%
  19670. %@NL@%
  19671. %@NL@%
  19672. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19673. %@NL@%
  19674. The %@AB@%_getwritemode%@AE@% function returns the current logical write mode, or -1 if
  19675. not in graphics mode.  %@NL@%
  19676. %@NL@%
  19677. %@NL@%
  19678. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19679. %@NL@%
  19680.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  19681. %@NL@%
  19682. %@NL@%
  19683. %@NL@%
  19684. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19685. %@NL@%
  19686. %@AB@%_grstatus%@AE@%,  %@AB@%_lineto%@AE@% functions,  %@AB@%_putimage%@AE@% functions,  %@AB@%_rectangle%@AE@% functions,
  19687. %@AB@%_setcolor%@AE@%,  %@AB@%_setlinestyle%@AE@%,  %@AB@%_setwritemode%@AE@%  %@NL@%
  19688. %@NL@%
  19689. %@NL@%
  19690. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19691. %@NL@%
  19692. %@AS@%  /* GWRMODE.C: This program illustrates _getwritemode and _setwritemode. */
  19693. %@AS@%  
  19694. %@AS@%  #include <conio.h>
  19695. %@AS@%  #include <stdlib.h>
  19696. %@AS@%  #include <graph.h>
  19697. %@AS@%  
  19698. %@AS@%  short wmodes[5]  = { _GPSET,   _GPRESET, _GXOR,    _GOR,     _GAND    };
  19699. %@AS@%  char *wmstr[5]   = { "PSET  ", "PRESET", "XOR   ", "OR    ", "AND   " };
  19700. %@AS@%  
  19701. %@AS@%  void box( short x, short y, short size, short writemode, short fillmode );
  19702. %@AS@%  
  19703. %@AS@%  void main()
  19704. %@AS@%  {
  19705. %@AS@%     short i, x, y;
  19706. %@AS@%  %@AE@%%@NL@%
  19707. %@NL@%
  19708. %@AS@%  /* Find a valid graphics mode. */
  19709. %@AS@%     if( !_setvideomode( _MAXCOLORMODE ) )
  19710. %@AS@%        exit( 1 );
  19711. %@AS@%  
  19712. %@AS@%     x = y = 70;
  19713. %@AS@%     box( x, y, 50, _GPSET, _GFILLINTERIOR );
  19714. %@AS@%     _setcolor( 2 );
  19715. %@AS@%     box( x, y, 40, _GPSET, _GFILLINTERIOR );
  19716. %@AS@%     for( i = 0; i < 5; i++ )
  19717. %@AS@%     {
  19718. %@AS@%        _settextposition( 1, 1 );
  19719. %@AS@%        _outtext( wmstr[i] );
  19720. %@AS@%        box( x += 12, y += 12, 50, wmodes[i], _GBORDER );
  19721. %@AS@%        getch();
  19722. %@AS@%     }
  19723. %@AS@%     _setvideomode( _DEFAULTMODE );
  19724. %@AS@%  }
  19725. %@AS@%  
  19726. %@AS@%  void box( short x, short y, short size, short writemode, short fillmode )
  19727. %@AS@%  {
  19728. %@AS@%      short wm, side;
  19729. %@AS@%  
  19730. %@AS@%      wm = _getwritemode();           /* Save write mode and set new. */
  19731. %@AS@%      _setwritemode( writemode );
  19732. %@AS@%      _rectangle( fillmode, x - size, y - size, x + size, y + size );
  19733. %@AS@%      _setwritemode( wm );            /* Restore original write mode. */
  19734. %@AS@%  }%@AE@%%@NL@%
  19735. %@NL@%
  19736. %@NL@%
  19737. %@NL@%
  19738. %@NL@%
  19739. %@QR:gmtime@%%@NL@%
  19740. %@2@%%@CR:C6A01590774 @%%@AB@%gmtime%@AE@%%@EH@%%@NL@%
  19741. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19742. %@NL@%
  19743. %@NL@%
  19744. %@3@%%@AB@%Description%@CR:C6A01590775 @%%@CR:C6A01590776 @%%@CR:C6A01590777 @% %@CR:C6A01590778 @%%@CR:C6A01590779 @%%@AE@%%@EH@%%@NL@%
  19745. %@NL@%
  19746. Converts a time value to a structure.  %@NL@%
  19747. %@NL@%
  19748. %@AS@%  #include <time.h>%@AE@%%@NL@%
  19749. %@NL@%
  19750. %@AS@%  struct tm *gmtime( const time_t *timer );%@AE@%%@NL@%
  19751. %@NL@%
  19752. %@AI@%timer%@AE@%                             Pointer to stored time
  19753.  
  19754. %@NL@%
  19755. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19756. %@NL@%
  19757. The %@AB@%gmtime%@AE@% function converts the %@AI@%timer%@AE@% value to a structure. The %@AI@%timer%@AE@%
  19758. argument represents the seconds elapsed since 00:00:00, January 1, 1970,
  19759. Greenwich mean time. This value is usually obtained from a call to the %@AB@%timer
  19760. %@AB@%%@AE@%function.%@AB@%  %@AE@%%@NL@%
  19761. %@NL@%
  19762. The %@AB@%gmtime%@AE@% function breaks down the %@AI@%timer%@AE@% value and stores it in a structure
  19763. of type %@AB@%tm%@AE@%, defined in TIME.H. (See %@AB@%asctime%@AE@% for a description of the
  19764. structure members.) The structure result reflects Greenwich mean time, not
  19765. local time.  %@NL@%
  19766. %@NL@%
  19767. The fields of the structure type %@AB@%tm%@AE@% store the following values, each of
  19768. which is an %@AB@%int%@AE@%:  %@NL@%
  19769. %@NL@%
  19770. %@AB@%Field%@AE@%                             %@AB@%Value Stored%@AE@%
  19771. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19772. %@AB@%tm_sec%@AE@%                            Seconds
  19773.  
  19774. %@AB@%tm_min%@AE@%                            Minutes
  19775.  
  19776. %@AB@%tm_hour%@AE@%                           Hours (0-24)
  19777.  
  19778. %@AB@%tm_mday%@AE@%                           Day of month (1-31)
  19779.  
  19780. %@AB@%tm_mon%@AE@%                            Month (0-11; January = 0)
  19781.  
  19782. %@AB@%tm_year%@AE@%                           Year (current year minus 1900)
  19783.  
  19784. %@AB@%tm_wday%@AE@%                           Day of week (0-6; Sunday = 0)
  19785.  
  19786. %@AB@%tm_yday%@AE@%                           Day of year (0-365; January 1 = 0)
  19787.  
  19788. %@AB@%tm_isdst%@AE@%                          Always 0 for %@AB@%gmtime%@AE@%
  19789.  
  19790. The %@AB@%gmtime, mktime, %@AE@%and%@AB@% localtime%@AE@% functions use a single statically
  19791. allocated structure to hold the result. Each call to one of these routines
  19792. destroys the result of any previous call.  %@NL@%
  19793. %@NL@%
  19794. DOS and OS/2 do not accommodate dates prior to 1980. If %@AI@%timer%@AE@% represents a
  19795. date prior to 1980, %@AB@%gmtime%@AE@% returns %@AB@%NULL%@AE@%.    %@NL@%
  19796. %@NL@%
  19797. %@NL@%
  19798. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19799. %@NL@%
  19800. The %@AB@%gmtime%@AE@% function returns a pointer to the structure result. There is no
  19801. error return.  %@NL@%
  19802. %@NL@%
  19803. %@NL@%
  19804. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19805. %@NL@%
  19806. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  19807. %@NL@%
  19808. %@NL@%
  19809. %@NL@%
  19810. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19811. %@NL@%
  19812. %@AB@%asctime%@AE@%, %@AB@%ctime%@AE@%, %@AB@%ftime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%time  %@AE@%%@NL@%
  19813. %@NL@%
  19814. %@NL@%
  19815. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19816. %@NL@%
  19817. %@AS@%  /* GMTIME.C: This program uses gmtime to convert a long-integer
  19818. %@AS@%   * representation of Greenwich mean time to a structure named newtime,
  19819. %@AS@%   * then uses asctime to convert this structure to an output string.
  19820. %@AS@%   */
  19821. %@AS@%  
  19822. %@AS@%  #include <time.h>
  19823. %@AS@%  #include <stdio.h>
  19824. %@AS@%  
  19825. %@AS@%  void main()
  19826. %@AS@%  {
  19827. %@AS@%     struct tm *newtime;
  19828. %@AS@%     long ltime;
  19829. %@AS@%  
  19830. %@AS@%     time( <ime );
  19831. %@AS@%  
  19832. %@AS@%     /* Obtain Greenwich mean time: */
  19833. %@AS@%     newtime = gmtime( <ime );
  19834. %@AS@%     printf( "Greenwich mean time is %s\n", asctime( newtime ) );
  19835. %@AS@%  }%@AE@%%@NL@%
  19836. %@NL@%
  19837. %@NL@%
  19838. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  19839. %@NL@%
  19840. %@AS@%  
  19841. %@AS@%  
  19842. %@AS@%  Greenwich mean time is Fri Jun 16 16:37:53 1989 %@AE@%%@NL@%
  19843. %@NL@%
  19844. %@NL@%
  19845. %@NL@%
  19846. %@NL@%
  19847. %@QR:_grstatus@%%@NL@%
  19848. %@2@%%@CR:C6A01600780 @%%@AB@%_grstatus%@AE@%%@EH@%%@NL@%
  19849. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19850. %@NL@%
  19851. %@NL@%
  19852. %@3@%%@AB@%Description%@CR:C6A01600781 @% %@CR:C6A01600782 @%%@AE@%%@EH@%%@NL@%
  19853. %@NL@%
  19854. Returns the status of the most recent graphics function call.  %@NL@%
  19855. %@NL@%
  19856. %@AS@%  #include  <graph.h>%@AE@%%@NL@%
  19857. %@NL@%
  19858. %@AS@%  short _far _grstatus( void );%@AE@%%@NL@%
  19859. %@NL@%
  19860. %@NL@%
  19861. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19862. %@NL@%
  19863. The %@AB@%_grstatus%@AE@% function returns the status of the most recently used graphics
  19864. function. The %@AB@%_grstatus%@AE@% function can be used immediately following a call to
  19865. a graphics routine to determine if errors or warnings were generated. Return
  19866. values less than 0 are errors, and values greater than 0 are warnings.  %@NL@%
  19867. %@NL@%
  19868. The following manifest constants are defined in the GRAPH.H header file for
  19869. use with the %@AB@%_grstatus%@AE@% function:  %@NL@%
  19870. %@NL@%
  19871. %@TH:  34  1511 02 07 23 48 @%%@AB@%Value%@AE@%  %@AB@%Constant%@AE@%               %@AB@%Meaning%@AE@%%@AB@%──────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%0      %@AB@%_GROK%@AE@%                  Success-1     %@AB@%_GRERROR%@AE@%               Graphics error-2     %@AB@%_GRMODENOTSUPPORTED%@AE@%    Requested video mode not supported-3     %@AB@%_GRNOTINPROPERMODE%@AE@%     Requested routine only works in certain video                               modes-4     %@AB@%_GRINVALIDPARAMETER%@AE@%    One or more parameters invalid-5     %@AB@%_GRFONTFILENOTFOUND%@AE@%    No matching font file found-6     %@AB@%_GRINVALIDFONTFILE%@AE@%     One or more font files invalid-7     %@AB@%_GRCORRUPTEDFONTFILE%@AE@%   One or more font files inconsistent-8     %@AB@%_GRINSUFFICIENTMEMORY%@AE@%  Not enough memory to allocate buffer or to                               complete a %@AB@%_floodfill%@AE@% operation-9     %@AB@%_GRINVALIDIMAGEBUFFER%@AE@%  Image buffer data inconsistent1      %@AB@%_GRMOOUTPUT%@AE@%            No action taken2      %@AB@%_GRCLIPPED%@AE@%             Output was clipped to viewport3      %@AB@%_GRPARAMETERALTERED%@AE@%    One or more input parameters was altered to be                              within range, or pairs of parameters were                               interchanged to be in the proper order%@AB@%──────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE:  34  1511 02 07 23 48 @%
  19872.  
  19873. After a graphics call, use an %@AB@%if %@AE@%statement to compare the return value of
  19874. %@AB@%_grstatus%@AE@% to %@AB@%_GROK%@AE@%. For example:  %@NL@%
  19875. %@NL@%
  19876. %@AS@%  if( _grstatus < _GROK )
  19877. %@AS@%      /*handle graphics error*/ ;%@AE@%%@NL@%
  19878. %@NL@%
  19879. The functions listed below cannot cause errors, and they all set %@AB@%_grstatus%@AE@%
  19880. to %@AB@%GROK%@AE@%:  %@NL@%
  19881. %@NL@%
  19882. %@TH:   9   456 01 17 18 41 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_displaycursor%@AE@%   %@AB@%_gettextposition%@AE@%  %@AB@%_outmem%@AE@%%@AB@%_getactivepage%@AE@%   %@AB@%_gettextwindow%@AE@%    %@AB@%_outtext%@AE@%%@AB@%_getgtextvector%@AE@%  %@AB@%_getvideoconfig%@AE@%   %@AB@%_unregisterfonts%@AE@%%@AB@%_gettextcolor%@AE@%    %@AB@%_getvisualpage%@AE@%    %@AB@%_wrapon%@AE@%%@TE:   9   456 01 17 18 41 @%
  19883.  
  19884.  See the list below for the graphics functions that affect %@AB@%_grstatus%@AE@%. The
  19885. list shows error or warning messages that can be set by the graphics
  19886. function. In addition to the error codes listed, all of these functions can
  19887. produce the %@AB@%_GRERROR%@AE@% error code.  %@NL@%
  19888. %@NL@%
  19889. %@TH: 126  9075 03 36 83 33 @%%@AB@%Function%@AE@%                            Possible _grstatus                                                                 %@AB@%Possible _grstatus%@AE@%%@AB@%G%@AE@%                                   Error Codes                                                                        %@AB@%Warning Codes%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%_arc%@AE@% functions                      %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRNOOUTPUT,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%                                                                %@AB@%_GRCLIPPED%@AE@%%@AB@%_clearscreen%@AE@%                        %@AB@%_GRNOTINPROPERMODE,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%_ellipse%@AE@% functions                  %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRNOOUTPUT,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER,%@AE@%                                                               %@AB@%_GRCLIPPED%@AE@%                                    %@AB@%_GRINSUFFICIENTMEMORY%@AE@%                                                              %@AB@%_getarcinfo %@AE@%                        %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_getcurrentposition%@AE@%                 %@AB@%_GRNOTINPROPERMODE%@AE@%functions                           %@AB@%_getfontinfo%@AE@%                        (%@AB@% _GRERROR%@AE@% only)%@AB@%_getgtextextent%@AE@%                     (%@AB@% _GRERROR%@AE@% only)%@AB@%_getgtextvector%@AE@%                     %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_getimage%@AE@%                           %@AB@%_GRNOTINPROPERMODE%@AE@%                                                                 %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_getphyscoord%@AE@%                       %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_getpixel%@AE@%                           %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_gettextcursor%@AE@%                      %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_getviewcoord %@AE@%functions             %@AB@%_GRNOTINPROPERMODE%@AE@%%@AI@%Continued on next page%@AE@%              %@AB@%_getwindowcoord %@AE@%                    %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_getwritemode%@AE@%                       %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_imagesize%@AE@% functions                %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_lineto%@AE@% functions                   %@AB@%_GRNOTINPROPERMODE%@AE@%                                                                 %@AB@%_GRNOOUTPUT,%@AE@%                                                                                                                       %@AB@%_GRCLIPPED%@AE@%%@AB@%_moveto%@AE@% functions                   %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_outgtex%@AE@%t                           %@AB@%_GRNOTINPROPERMODE%@AE@%                                                                 %@AB@%_GRCLIPPED,%@AE@%                                                                                                                       %@AB@%_GRNOOUTPUT%@AE@%%@AB@%_pie%@AE@% functions                      %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRNOOUTPUT,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER,%@AE@%                                                               %@AB@%_GRCLIPPED%@AE@%                                    %@AB@%_GRINSUFFICIENTMEMORY%@AE@%                                                              %@AB@%_polygon%@AE@% functions                  %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRNOOUTPUT,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER,%@AE@%                                                               %@AB@%_GRCLIPPED%@AE@%                                    %@AB@%_GRINSUFFICIENTMEMORY%@AE@%                                                              %@AB@%_putimage%@AE@% functions                 %@AB@%_GRERROR,%@AE@%                                                                          %@AB@%_GRPARAMETERALTERED,%@AE@%                                    %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRNOOUTPUT%@AE@%                                    %@AB@%_GRINVALIDPARAMETER,%@AE@%                                                                                                   %@AB@%_GRINVALIDIMAGEBUFFER%@AE@%                                                              %@AB@%_rectangle%@AE@% functions                %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRNOOUTPUT,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER,%@AE@%                                                               %@AB@%_GRCLIPPED%@AE@%                                    %@AB@%_GRINSUFFICIENTMEMORY%@AE@%                                                              %@AB@%_registerfonts%@AE@%                      %@AB@%_GRCORRUPTEDFONTFILE,%@AE@%                                    %@AB@%_GRFONTFILENOTFOUND,%@AE@%                                    %@AB@%_GRINSUFFICIENTMEMORY,%@AE@%                                    %@AB@%_GRINVALIDFONTFILE%@AE@%%@AB@%_scrolltextwindow%@AE@%                                                                                                      %@AB@%_GRNOOUTPUT%@AE@%%@AB@%_selectpalette%@AE@%                      %@AB@%_GRNOTINPROPERMODE,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%_setactivepage%@AE@%                      %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%_setbkcolor%@AE@%                         %@AB@%_GRINVALIDPARAMETER%@AE@%                                                                %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_setcliprgn%@AE@%                         %@AB@%_GRNOTINPROPERMODE%@AE@%                                                                 %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_setcolor%@AE@%                           %@AB@%_GRNOTINPROPERMODE%@AE@%                                                                 %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_setfont%@AE@%                            %@AB@%_GRERROR,%@AE@%                                    %@AB@%_GRFONTFILENOTFOUND,%@AE@%                                    %@AB@%_GRINSUFFICIENTMEMORY,%@AE@%                                    %@AB@%_GRPARAMETERALTERED%@AE@%%@AI@%Continued on next page%@AE@%              %@AB@%_setgtextvector%@AE@%                     %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_settextcolor%@AE@%                                                                                                          %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_settextcursor%@AE@%                      %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_settextposition%@AE@%                                                                                                       %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_settextrows%@AE@%                        %@AB@%_GRINVALIDPARAMETER%@AE@%                                                                %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_settextwindow%@AE@%                                                                                                         %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_setvideomode%@AE@%                       %@AB@%_GRERROR,%@AE@%                                    %@AB@%_GRMODENOTSUPPORTED,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%_setvideomoderows%@AE@%                   %@AB@%_GRERROR,%@AE@%                                    %@AB@%_GRMODENOTSUPPORTED,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%_setvieworg%@AE@%                         %@AB@%_GRNOTINPROPERMODE%@AE@%%@AB@%_setviewport%@AE@%                        %@AB@%_GRNOTINPROPERMODE%@AE@%                                                                 %@AB@%_GRPARAMETERALTERED%@AE@%%@AB@%_setvisualpage%@AE@%                      %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%_setwindow%@AE@%                          %@AB@%_GRNOTINPROPERMODE,%@AE@%                                                                %@AB@%_GRPARAMETERALTERED%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%                                                                %@AB@%_setwritemode%@AE@%                       %@AB@%_GRNOTINPROPERMODE,%@AE@%                                    %@AB@%_GRINVALIDPARAMETER%@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 126  9075 03 36 83 33 @%
  19890.  
  19891. %@NL@%
  19892. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19893. %@NL@%
  19894. The %@AB@%_grstatus%@AE@% function returns the status of the most recently used graphics
  19895. function.  %@NL@%
  19896. %@NL@%
  19897. %@NL@%
  19898. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19899. %@NL@%
  19900. %@AB@%_arc%@AE@% functions,  %@AB@%_ellipse%@AE@% functions,  %@AB@%_floodfill%@AE@%,  %@AB@%_lineto%@AE@% functions,  %@AB@%_pie%@AE@%
  19901. functions, %@AB@%_remapallpalette%@AE@%,  %@AB@%_setactivepage%@AE@%,  %@AB@%_setbkcolor%@AE@%,  %@AB@%_setcolor%@AE@%,
  19902. %@AB@%_setpixel%@AE@% functions, %@AB@%_settextcolor%@AE@%,  %@AB@%_settextcursor%@AE@%,  %@AB@%_setvisualpage%@AE@%,
  19903. %@AB@%_setwindow%@AE@%,  %@AB@%_setwritemode%@AE@%  %@NL@%
  19904. %@NL@%
  19905. %@NL@%
  19906. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19907. %@NL@%
  19908.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19909. %@NL@%
  19910. %@NL@%
  19911. %@NL@%
  19912. %@NL@%
  19913. %@NL@%
  19914. %@QR:halloc@%%@NL@%
  19915. %@2@%%@CR:C6A01610783 @%%@AB@%halloc%@AE@%%@EH@%%@NL@%
  19916. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19917. %@NL@%
  19918. %@NL@%
  19919. %@3@%%@AB@%Description%@CR:C6A01610784 @%%@CR:C6A01610785 @%%@AE@%%@EH@%%@NL@%
  19920. %@NL@%
  19921. Allocates a huge memory block.  %@NL@%
  19922. %@NL@%
  19923. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  19924.  
  19925. %@AS@%  void _huge *halloc( long num, size_t size );%@AE@%%@NL@%
  19926. %@NL@%
  19927. %@AI@%num%@AE@%                               Number of elements
  19928.  
  19929. %@AI@%size%@AE@%                              Length in bytes of each element
  19930.  
  19931. %@NL@%
  19932. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  19933. %@NL@%
  19934. The %@AB@%halloc%@AE@% function allocates a huge array from the operating system
  19935. consisting of %@AI@%num%@AE@% elements, each of which is %@AI@%size%@AE@% bytes long. Each element
  19936. is initialized to 0. If the size of the array is greater than 128K (131,072
  19937. bytes), the size of an array element must then be a power of 2.  %@NL@%
  19938. %@NL@%
  19939. %@NL@%
  19940. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  19941. %@NL@%
  19942. The %@AB@%halloc%@AE@% function returns a %@AB@%void huge%@AE@% pointer to the allocated space,
  19943. which is guaranteed to be suitably aligned for storage of any type of
  19944. object. To get a pointer to a type other than %@AB@%void huge%@AE@%, use a type cast on
  19945. the return value. If the request cannot be satisfied, the return value is
  19946. %@AB@%NULL%@AE@%.  %@NL@%
  19947. %@NL@%
  19948. %@NL@%
  19949. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  19950. %@NL@%
  19951.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  19952. %@NL@%
  19953. %@NL@%
  19954. %@NL@%
  19955. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  19956. %@NL@%
  19957. %@AB@%calloc%@AE@% functions, %@AB@%free%@AE@% functions, %@AB@%hfree%@AE@%, %@AB@%malloc%@AE@% functions  %@NL@%
  19958. %@NL@%
  19959. %@NL@%
  19960. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  19961. %@NL@%
  19962. %@AS@%  /* HALLOC.C: This program uses halloc to allocate space for 30,000 long
  19963. %@AS@%   * integers, then uses hfree to deallocate the memory.
  19964. %@AS@%   */
  19965. %@AS@%  
  19966. %@AS@%  #include <stdio.h>
  19967. %@AS@%  #include <stdlib.h>
  19968. %@AS@%  #include <malloc.h>
  19969. %@AS@%  
  19970. %@AS@%  void main()
  19971. %@AS@%  {
  19972. %@AS@%     long _huge *hbuf;%@AE@%%@NL@%
  19973. %@NL@%
  19974. %@AS@%  /* Allocate huge buffer */
  19975. %@AS@%     hbuf = (long _huge *)halloc( 30000L, sizeof( long ) );
  19976. %@AS@%     if ( hbuf == NULL )
  19977. %@AS@%        printf( "Insufficient memory available\n" );
  19978. %@AS@%     else
  19979. %@AS@%        printf( "Memory successfully allocated\n" );
  19980. %@AS@%  
  19981. %@AS@%     /* Free huge buffer */
  19982. %@AS@%     hfree( hbuf );
  19983. %@AS@%  }%@AE@%%@NL@%
  19984. %@NL@%
  19985. %@NL@%
  19986. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  19987. %@NL@%
  19988. %@AS@%  
  19989. %@AS@%  
  19990. %@AS@%  Memory successfully allocated %@AE@%%@NL@%
  19991. %@NL@%
  19992. %@NL@%
  19993. %@NL@%
  19994. %@NL@%
  19995. %@QR:_hard@%%@NL@%
  19996. %@2@%%@CR:C6A01620786 @%%@AB@%_hard Functions%@AE@%%@EH@%%@NL@%
  19997. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  19998. %@NL@%
  19999. %@NL@%
  20000. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  20001. %@NL@%
  20002. Handle critical error conditions.  %@NL@%
  20003. %@NL@%
  20004. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  20005. %@NL@%
  20006. %@AS@%  void _harderr( void( _far *handler )());%@AE@%%@NL@%
  20007. %@NL@%
  20008. %@AS@%  void _hardresume( int result );%@AE@%%@NL@%
  20009. %@NL@%
  20010. %@AS@%  void _hardretn( int error );%@AE@%%@NL@%
  20011. %@NL@%
  20012. %@AI@%handler %@AE@%%@AB@%( )%@AE@%                       New INT 0x24 handler
  20013.  
  20014. %@AI@%result %@AE@%                           Handler return parameter
  20015.  
  20016. %@AI@%error%@AE@%                             Error to return from
  20017.  
  20018. %@NL@%
  20019. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20020. %@NL@%
  20021. These three functions are used to handle critical error conditions that use
  20022. DOS interrupt 0x24. The %@AB@%_harderr%@AE@% function installs a new critical-error
  20023. handler for interrupt 0x24.  %@NL@%
  20024. %@NL@%
  20025. The %@AB@%_hardresume%@AE@% and %@AB@%_hardreturn%@AE@% functions control how the program will
  20026. return from the new critical-error handler installed by %@AB@%_harderr%@AE@%. The
  20027. %@AB@%_hardresume%@AE@% function returns to DOS from a user-installed critical-error
  20028. handler, and the %@AB@%_hardreturn%@AE@% function returns directly to the application
  20029. program from a user-installed critical-error handler.  %@NL@%
  20030. %@NL@%
  20031. The %@AB@%_harderr%@AE@% function does not directly install the handler pointed to by
  20032. %@AI@%handler%@AE@%; instead, %@AB@%_harderr%@AE@% installs a handler that calls the function
  20033. referenced by %@AI@%handler%@AE@%. The handler calls the function with the following
  20034. parameters:   %@NL@%
  20035. %@NL@%
  20036. %@AS@%  handler(unsigned deverror, unsigned errcode, unsigned far *devhdr);
  20037. %@AS@%   %@AE@%%@NL@%
  20038. %@NL@%
  20039. The %@AI@%deverror%@AE@% argument is the device error code. It contains the AX register
  20040. value passed by DOS to the INT 0x24 handler. The %@AI@%errcode%@AE@% argument is the DI
  20041. register value that DOS passes to the handler. The low-order byte of %@AI@%errcode%@AE@%
  20042. can be one of the following values:  %@NL@%
  20043. %@NL@%
  20044. %@AB@%Code%@AE@%                              %@AB@%Meaning%@AE@%
  20045. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20046. %@AB@%0%@AE@%                                 Attempt to write to a write-protected 
  20047.                                   disk
  20048.  
  20049. %@AB@%1%@AE@%                                 Unknown unit
  20050.  
  20051. %@AB@%2%@AE@%                                 Drive not ready
  20052.  
  20053. %@AB@%3%@AE@%                                 Unknown command
  20054.  
  20055. %@AB@%4%@AE@%                                 Cyclic-redundancy-check error in data
  20056.  
  20057. %@AB@%5%@AE@%                                 Bad drive-request structure length
  20058.  
  20059. %@AB@%6%@AE@%                                 Seek error
  20060.  
  20061. %@AB@%7%@AE@%                                 Unknown media type
  20062.  
  20063. %@AB@%8%@AE@%                                 Sector not found
  20064.  
  20065. %@AB@%9%@AE@%                                 Printer out of paper
  20066.  
  20067. %@AB@%10%@AE@%                                Write fault
  20068.  
  20069. %@AB@%11%@AE@%                                Read fault
  20070.  
  20071. %@AB@%12%@AE@%                                General failure
  20072.  
  20073. The %@AI@%devhdr%@AE@% argument is a far pointer to a device header that contains
  20074. descriptive information about the device on which the error occurred. The
  20075. user-defined handler must not change the information in the device-header
  20076. control block.  %@NL@%
  20077. %@NL@%
  20078. %@NL@%
  20079. %@4@%%@AB@%Errors on Disk Devices%@AE@%%@EH@%%@NL@%
  20080. %@NL@%
  20081. If the error occurred on a disk device, the high-order bit (bit 15) of the
  20082. %@AI@%deverror%@AE@% argument will be set to 0, and the %@AI@%deverror%@AE@% argument will indicate
  20083. the following:  %@NL@%
  20084. %@NL@%
  20085. %@AB@%Bit%@AE@%                               %@AB@%Meaning%@AE@%
  20086. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20087. %@AB@%15%@AE@%                                Disk error if false (0).
  20088.  
  20089. %@AB@%14%@AE@%                                Not used.
  20090.  
  20091. %@AB@%13%@AE@%                                "Ignore" response not allowed if false 
  20092.                                   (0).
  20093.  
  20094. %@AB@%12%@AE@%                                "Retry" response not allowed if false 
  20095.                                   (0).
  20096.  
  20097. %@AB@%11%@AE@%                                "Fail" response not allowed if false 
  20098.                                   (0). Note that DOS changes "fail" to 
  20099.                                   "abort".
  20100.  
  20101. %@AB@%10, 9%@AE@%
  20102.  
  20103.                                   %@AB@%Code%@AE@%      %@AB@%Location%@AE@%
  20104. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20105.                                   %@AB@%00%@AE@%          DOS
  20106.  
  20107.                                   %@AB@%01%@AE@%          File allocation table
  20108.  
  20109.                                   %@AB@%10%@AE@%          Directory
  20110.  
  20111.                                   %@AB@%11%@AE@%          Data area
  20112.  
  20113. %@AB@%%@AE@%                                  
  20114. %@AB@%8%@AE@%                                 Read error if false; write error if 
  20115.                                   true.
  20116.  
  20117. The low-order byte of %@AI@%deverror%@AE@% indicates the drive in which the error
  20118. occurred (0 = drive A, 1 = drive B, etc.).  %@NL@%
  20119. %@NL@%
  20120. %@NL@%
  20121. %@4@%%@AB@%Errors on Other Devices%@AE@%%@EH@%%@NL@%
  20122. %@NL@%
  20123. If the error occurs on a device other than a disk drive, the high-order bit
  20124. (bit 15) of the %@AI@%deverror%@AE@% argument is 1. The attribute word located at offset
  20125. 4 in the device-header block indicates the type of device that had the
  20126. error. If bit 15 of the attribute word is 0, the error is a bad memory image
  20127. of the file allocation table. If the bit is 1, the error occurred on a
  20128. character device and bits 0-3 of the attribute word indicate the type of
  20129. device, as shown in the following list:  %@NL@%
  20130. %@NL@%
  20131. %@AB@%Bit%@AE@%                               %@AB@%Meaning%@AE@%
  20132. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20133. %@AB@%0%@AE@%                                 Current standard input
  20134.  
  20135. %@AB@%1%@AE@%                                 Current standard output
  20136.  
  20137. %@AB@%2%@AE@%                                 Current null device
  20138.  
  20139. %@AB@%3%@AE@%                                 Current clock device
  20140.  
  20141. %@NL@%
  20142. %@4@%%@AB@%Restrictions on Handler Functions%@AE@%%@EH@%%@NL@%
  20143. %@NL@%
  20144. The user-defined handler function can issue only system calls 0x01 through
  20145. 0x0C, or 0x59. Thus, many of the standard C run-time functions (such as
  20146. stream I/O and low-level I/O) cannot be used in a hardware error handler.
  20147. Function 0x59 can be used to obtain further information about the error that
  20148. occurred.  %@NL@%
  20149. %@NL@%
  20150. %@NL@%
  20151. %@4@%%@AB@%Using _hardresume and _harderr%@AE@%%@EH@%%@NL@%
  20152. %@NL@%
  20153. %@AB@%If the handler returns, it can do so%@AE@% - %@NL@%
  20154.   1.  From the %@AB@%return%@AE@% statement%@NL@%
  20155. %@NL@%
  20156.   2.  From the %@AB@%_hardresume%@AE@% function%@NL@%
  20157. %@NL@%
  20158.   3.  From the %@AB@%_hardretn%@AE@% function%@NL@%
  20159. %@NL@%
  20160. %@NL@%
  20161.  
  20162. If the handler returns from %@AB@%_hardresume%@AE@% or from a %@AB@%return%@AE@% statement, the
  20163. handler returns to DOS.  %@NL@%
  20164. %@NL@%
  20165. The %@AB@%_hardresume%@AE@% function should be called only from within the user-defined
  20166. hardware error-handler function. The result supplied to %@AB@%_hardresume%@AE@% must be
  20167. one of the following constants:  %@NL@%
  20168. %@NL@%
  20169. %@AB@%Constant%@AE@%                          %@AB@%Action%@AE@%
  20170. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20171. %@AB@%_HARDERR_ABORT%@AE@%                    Abort the program by issuing INT 0x23
  20172.  
  20173. %@AB@%_HARDERR_FAIL%@AE@%                     Fail the system call that is in progress
  20174.                                   (this is not supported on DOS 2. x)
  20175.  
  20176. %@AB@%_HARDERR_IGNORE%@AE@%                   Ignore the error
  20177.  
  20178. %@AB@%_HARDERR_RETRY%@AE@%                    Retry the operation
  20179.  
  20180. The %@AB@%_hardretn%@AE@% function allows the user-defined hardware error handler to
  20181. return directly to the application program rather than returning to DOS. The
  20182. application resumes at the point just after the failing I/O function
  20183. request. The %@AB@%_hardretn%@AE@% function should be called only from within a
  20184. user-defined hardware error-handler function.  %@NL@%
  20185. %@NL@%
  20186. The error parameter of %@AB@%_hardretn%@AE@% should be a DOS error code, as opposed to
  20187. the XENIX-style error code that is available in %@AB@%errno%@AE@%. Refer to %@AI@%MS-DOS
  20188. %@AI@%Encyclopedia%@AE@% (Duncan, ed.; Redmond, Wa.: Microsoft Press, 1988) or%@AI@%
  20189. %@AI@%Programmer's PC Sourcebook%@AE@% (Hogan; Redmond, Wa.: Microsoft Press, 1988) for
  20190. information about the DOS error codes that may be returned by a given DOS
  20191. function call.  %@NL@%
  20192. %@NL@%
  20193. If the failing I/O function request is an INT 0x21 function greater than or
  20194. equal to function 0x38, %@AB@%_hardretn%@AE@% will then return to the application with
  20195. the carry flag set and the AX register set to the %@AB@%_hardretn%@AE@% %@AI@%error%@AE@% parameter.
  20196. If the failing INT 0x21 function request is less than function 0x38 and the
  20197. function can return an error, the AL register will be set to 0xFF on return
  20198. to the application. If the failing INT 0x21 does not have a way of returning
  20199. an error condition (which is true of certain INT 0x21 functions below 0x38),
  20200. the error parameter of %@AB@%_hardretn%@AE@% is not used, and no error code is returned
  20201. to the application.  %@NL@%
  20202. %@NL@%
  20203. %@NL@%
  20204. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20205. %@NL@%
  20206. None.  %@NL@%
  20207. %@NL@%
  20208. %@NL@%
  20209. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20210. %@NL@%
  20211.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  20212. %@NL@%
  20213. %@NL@%
  20214. %@NL@%
  20215. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20216. %@NL@%
  20217. %@AB@%_chain_intr%@AE@%, %@AB@% _dos_getvect%@AE@%, %@AB@% _dos_setvect%@AE@%  %@NL@%
  20218. %@NL@%
  20219. %@NL@%
  20220. %@NL@%
  20221. %@NL@%
  20222. %@QR:_heapadd@%%@NL@%
  20223. %@2@%%@CR:C6A01630787 @%%@AB@%_heapadd Functions%@AE@%%@EH@%%@NL@%
  20224. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20225. %@NL@%
  20226. %@NL@%
  20227. %@3@%%@AB@%Description%@CR:C6A01630788 @%%@CR:C6A01630789 @% %@CR:C6A01630790 @% %@CR:C6A01630791 @%%@AE@%%@EH@%%@NL@%
  20228. %@NL@%
  20229. Add memory to the heap %@AB@%(_heapadd)%@AE@% or to the based heap %@AB@%(_bheapadd)%@AE@%.  %@NL@%
  20230. %@NL@%
  20231. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  20232.  
  20233. %@AS@%  int _heapadd( void _far *memblock, size_t size );%@AE@%%@NL@%
  20234. %@NL@%
  20235. %@AS@%  int _bheapadd( _segment seg, void _based (void) *memblock, size_t size );%@AE@%%@NL@%
  20236. %@NL@%
  20237. %@AI@%seg%@AE@%                               Based-heap segment selector
  20238.  
  20239. %@AI@%buffer%@AE@%                            Pointer to heap memory
  20240.  
  20241. %@AI@%size%@AE@%                              Size in bytes of memory to add
  20242.  
  20243. %@NL@%
  20244. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20245. %@NL@%
  20246. The %@AB@%_heapadd%@AE@% and %@AB@%_bheapadd%@AE@% functions add an unused piece of memory to the
  20247. heap. The %@AB@%_bheapadd%@AE@% function adds the memory to the based heap specified by
  20248. %@AI@%seg%@AE@%. The %@AB@%_heapadd%@AE@% function looks at the segment value and, if it is DGROUP,
  20249. adds the memory to the near heap. Otherwise, %@AB@%_heapadd%@AE@% adds the memory to the
  20250. far heap.  %@NL@%
  20251. %@NL@%
  20252. %@NL@%
  20253. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20254. %@NL@%
  20255. These functions return 0 if successful, or -1 if an error occurred.  %@NL@%
  20256. %@NL@%
  20257. %@NL@%
  20258. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20259. %@NL@%
  20260.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  20261. %@NL@%
  20262. %@NL@%
  20263. %@NL@%
  20264. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20265. %@NL@%
  20266. %@AB@%free%@AE@% functions, %@AB@%halloc%@AE@%, %@AB@%hfree%@AE@%, %@AB@%malloc%@AE@% functions, %@AB@%realloc%@AE@% functions  %@NL@%
  20267. %@NL@%
  20268. %@NL@%
  20269. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  20270. %@NL@%
  20271. %@AS@%  /* HEAPMIN.C: This program illustrates heap management using
  20272. %@AS@%   * _heapadd and _heapmin.
  20273. %@AS@%   */
  20274. %@AS@%  
  20275. %@AS@%  #include <stdio.h>
  20276. %@AS@%  #include <conio.h>
  20277. %@AS@%  #include <process.h>
  20278. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  20279. %@NL@%
  20280. %@AS@%  void heapdump( char *msg );     /* Prototype */
  20281. %@AS@%  
  20282. %@AS@%  char s1[] = { "Here are some strings that we use at first, then don't\n"
  20283. %@AS@%};
  20284. %@AS@%  char s2[] = { "need any more. We'll give their space to the heap.\n" };
  20285. %@AS@%  
  20286. %@AS@%  void main()
  20287. %@AS@%  {
  20288. %@AS@%      int *p[3], i;
  20289. %@AS@%  
  20290. %@AS@%      printf( "%s%s", s1, s2 );
  20291. %@AS@%      heapdump( "Initial heap" );
  20292. %@AS@%  
  20293. %@AS@%      /* Give space of used strings to heap. */
  20294. %@AS@%      _heapadd( s1, sizeof( s1 ) );
  20295. %@AS@%      _heapadd( s2, sizeof( s2 ) );
  20296. %@AS@%      heapdump( "After adding used strings" );
  20297. %@AS@%  
  20298. %@AS@%      /* Allocate some blocks. Some may use string blocks from _heapadd. */
  20299. %@AS@%      for( i = 0; i < 2; i++ )
  20300. %@AS@%          if( (p[i] = (int *)calloc( 10 * (i + 1), sizeof( int ) )) == NULL
  20301. %@AS@%)
  20302. %@AS@%          {
  20303. %@AS@%              --i;
  20304. %@AS@%              break;
  20305. %@AS@%          }
  20306. %@AS@%      heapdump( "After allocating memory" );
  20307. %@AS@%  
  20308. %@AS@%      /* Free some of the blocks. */
  20309. %@AS@%      free( p[1] );
  20310. %@AS@%      free( p[2] );
  20311. %@AS@%      heapdump( "After freeing memory" );
  20312. %@AS@%  
  20313. %@AS@%      /* Minimize heap. */
  20314. %@AS@%      _heapmin();
  20315. %@AS@%      heapdump( "After compacting heap" );
  20316. %@AS@%  }
  20317. %@AS@%  
  20318. %@AS@%  /* Walk through heap entries, displaying information about each block. */
  20319. %@AS@%  void heapdump( char *msg )
  20320. %@AS@%  {
  20321. %@AS@%      struct _heapinfo hi;
  20322. %@AS@%  
  20323. %@AS@%      printf( "%s\n", msg );
  20324. %@AS@%      hi._pentry = NULL;
  20325. %@AS@%      while( _heapwalk( &hi ) == _HEAPOK )
  20326. %@AS@%          printf( "\t%s block at %Fp of size %u\t\n",
  20327. %@AS@%                  hi._useflag == _USEDENTRY ? "USED" : "FREE",
  20328. %@AS@%                  hi._pentry,
  20329. %@AS@%                  hi._size );
  20330. %@AS@%      getch();
  20331. %@AS@%  }%@AE@%%@NL@%
  20332. %@NL@%
  20333. %@NL@%
  20334. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  20335. %@NL@%
  20336. %@AS@%  
  20337. %@AS@%  
  20338. %@AS@%  Here are some strings that we use at first, then don't
  20339. %@AS@%  need any more. We'll give their space to the heap.
  20340. %@AS@%  Initial heap
  20341. %@AS@%     USED block at 2D39:0E9C of size 364   
  20342. %@AS@%     USED block at 2D39:100A of size 36   
  20343. %@AS@%     USED block at 2D39:1030 of size 512   
  20344. %@AS@%     FREE block at 2D39:1232 of size 460   
  20345. %@AS@%  After adding used strings
  20346. %@AS@%     FREE block at 2D39:0044 of size 52   
  20347. %@AS@%     FREE block at 2D39:007A of size 50   
  20348. %@AS@%     USED block at 2D39:00AE of size 3564   
  20349. %@AS@%     USED block at 2D39:0E9C of size 364   
  20350. %@AS@%     USED block at 2D39:100A of size 36   
  20351. %@AS@%     USED block at 2D39:1030 of size 512   
  20352. %@AS@%     FREE block at 2D39:1232 of size 460   
  20353. %@AS@%  After allocating memory
  20354. %@AS@%     USED block at 2D39:0044 of size 20   
  20355. %@AS@%     USED block at 2D39:005A of size 40   
  20356. %@AS@%     FREE block at 2D39:0084 of size 40   
  20357. %@AS@%     USED block at 2D39:00AE of size 3564   
  20358. %@AS@%     USED block at 2D39:0E9C of size 364   
  20359. %@AS@%     USED block at 2D39:100A of size 36   
  20360. %@AS@%     USED block at 2D39:1030 of size 512   
  20361. %@AS@%     FREE block at 2D39:1232 of size 460   
  20362. %@AS@%  After freeing memory
  20363. %@AS@%     USED block at 2D39:0044 of size 20   
  20364. %@AS@%     FREE block at 2D39:005A of size 40   
  20365. %@AS@%     FREE block at 2D39:0084 of size 40   
  20366. %@AS@%     USED block at 2D39:00AE of size 3564   
  20367. %@AS@%     USED block at 2D39:0E9C of size 364   
  20368. %@AS@%     USED block at 2D39:100A of size 36   
  20369. %@AS@%     USED block at 2D39:1030 of size 512   
  20370. %@AS@%     FREE block at 2D39:1232 of size 460   
  20371. %@AS@%  After compacting heap
  20372. %@AS@%     USED block at 2D39:0044 of size 20   
  20373. %@AS@%     FREE block at 2D39:005A of size 82   
  20374. %@AS@%     USED block at 2D39:00AE of size 3564   
  20375. %@AS@%     USED block at 2D39:0E9C of size 364   
  20376. %@AS@%     USED block at 2D39:100A of size 36   
  20377. %@AS@%     USED block at 2D39:1030 of size 512   
  20378. %@AS@%     FREE block at 2D39:1232 of size 12   %@AE@%%@NL@%
  20379. %@NL@%
  20380. %@NL@%
  20381. %@NL@%
  20382. %@NL@%
  20383. %@QR:_heapchk@%%@NL@%
  20384. %@2@%%@CR:C6A01640792 @%%@AB@%_heapchk Functions%@AE@%%@EH@%%@NL@%
  20385. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20386. %@NL@%
  20387. %@NL@%
  20388. %@3@%%@AB@%Description%@CR:C6A01640793 @%%@CR:C6A01640794 @% %@CR:C6A01640795 @% %@CR:C6A01640796 @% %@CR:C6A01640797 @% %@CR:C6A01640798 @% %@CR:C6A01640799 @%%@CR:C6A01640800 @% %@CR:C6A01640801 @% %@CR:C6A01640802 @%%@AE@%%@EH@%%@NL@%
  20389. %@NL@%
  20390. Run consistency checks on the heap.  %@NL@%
  20391. %@NL@%
  20392. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  20393. %@NL@%
  20394. %@AS@%  int _heapchk( void );%@AE@%%@NL@%
  20395. %@NL@%
  20396. %@AS@%  int _bheapchk( _segment seg );%@AE@%%@NL@%
  20397. %@NL@%
  20398. %@AS@%  int _fheapchk( void );%@AE@%%@NL@%
  20399. %@NL@%
  20400. %@AS@%  int _nheapchk( void );%@AE@%%@NL@%
  20401. %@NL@%
  20402. %@AI@%seg %@AE@%                              Specified base heap
  20403.  
  20404. %@NL@%
  20405. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20406. %@NL@%
  20407. The %@AB@%_heapchk%@AE@% routines help to debug heap-related problems by checking for
  20408. minimal consistency of the heap.  %@NL@%
  20409. %@NL@%
  20410. Each function checks a particular heap, as listed below:  %@NL@%
  20411. %@NL@%
  20412. %@AB@%Function%@AE@%                          %@AB@%Heap Checked%@AE@%
  20413. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20414. %@AB@%_heapchk%@AE@%                          Depends on data model of program
  20415.  
  20416. %@AB@%_bheapchk%@AE@%                         Based heap specified by %@AI@%seg%@AE@% value
  20417.  
  20418. %@AB@%_fheapchk%@AE@%                         Far heap (outside the default data 
  20419.                                   segment)
  20420.  
  20421. %@AB@%_nheapchk%@AE@%                         Near heap (inside the default data 
  20422.                                   segment)
  20423.  
  20424. In large data models (that is, compact-, large-, and huge-model programs),
  20425. %@AB@%_heapchk%@AE@% maps to %@AB@%_fheapchk%@AE@%. In small data models (tiny-, small-, and
  20426. medium-model programs), %@AB@%_heapchk%@AE@% maps to %@AB@%_nheapchk%@AE@%.  %@NL@%
  20427. %@NL@%
  20428. %@NL@%
  20429. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20430. %@NL@%
  20431. All four routines return an integer value that is one of the following
  20432. manifest constants (defined in MALLOC.H):  %@NL@%
  20433. %@NL@%
  20434. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  20435. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20436. %@AB@%_HEAPBADBEGIN%@AE@%                     Initial header information cannot be 
  20437.                                   found, or it is bad
  20438.  
  20439. %@AB@%_HEAPBADNODE%@AE@%                      Bad node has been found, or the heap is 
  20440.                                   damaged
  20441.  
  20442. %@AB@%_HEAPEMPTY%@AE@%                        Heap has not been initialized
  20443.  
  20444. %@AB@%_HEAPOK%@AE@%                           Heap appears to be consistent
  20445.  
  20446. %@NL@%
  20447. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20448. %@NL@%
  20449.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  20450. %@NL@%
  20451. %@NL@%
  20452. %@NL@%
  20453. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20454. %@NL@%
  20455. %@AB@%_heapset%@AE@% functions,  %@AB@%_heapwalk%@AE@% functions  %@NL@%
  20456. %@NL@%
  20457. %@NL@%
  20458. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  20459. %@NL@%
  20460. %@AS@%  /* HEAPCHK.C: This program checks the heap for consistency
  20461. %@AS@%   * and prints an appropriate message.
  20462. %@AS@%   */
  20463. %@AS@%  
  20464. %@AS@%  #include <malloc.h>
  20465. %@AS@%  #include <stdio.h>
  20466. %@AS@%  
  20467. %@AS@%  void main()
  20468. %@AS@%  {
  20469. %@AS@%     int  heapstatus;
  20470. %@AS@%     char *buffer;
  20471. %@AS@%  
  20472. %@AS@%     /* Allocate and deallocate some memory */
  20473. %@AS@%     if( (buffer = (char *)malloc( 100 )) != NULL )
  20474. %@AS@%        free( buffer );
  20475. %@AS@%  
  20476. %@AS@%     /* Check heap status */
  20477. %@AS@%     heapstatus = _heapchk();
  20478. %@AS@%     switch( heapstatus )
  20479. %@AS@%     {
  20480. %@AS@%        case _HEAPOK:
  20481. %@AS@%           printf(" OK - heap is fine\n" );
  20482. %@AS@%           break;
  20483. %@AS@%        case _HEAPEMPTY:
  20484. %@AS@%           printf(" OK - heap is empty\n" );
  20485. %@AS@%           break;
  20486. %@AS@%        case _HEAPBADBEGIN:
  20487. %@AS@%           printf( "ERROR - bad start of heap\n" );
  20488. %@AS@%           break;
  20489. %@AS@%        case _HEAPBADNODE:
  20490. %@AS@%           printf( "ERROR - bad node in heap\n" );
  20491. %@AS@%           break;
  20492. %@AS@%     }
  20493. %@AS@%  }%@AE@%%@NL@%
  20494. %@NL@%
  20495. %@NL@%
  20496. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  20497. %@NL@%
  20498. %@AS@%  
  20499. %@AS@%  
  20500. %@AS@%   OK - heap is fine %@AE@%%@NL@%
  20501. %@NL@%
  20502. %@NL@%
  20503. %@NL@%
  20504. %@NL@%
  20505. %@QR:_heapmin@%%@NL@%
  20506. %@2@%%@CR:C6A01650803 @%%@AB@%_heapmin Functions%@AE@%%@EH@%%@NL@%
  20507. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20508. %@NL@%
  20509. %@NL@%
  20510. %@3@%%@AB@%Description%@CR:C6A01650804 @%%@CR:C6A01650805 @% %@CR:C6A01650806 @% %@CR:C6A01650807 @% %@CR:C6A01650808 @% %@CR:C6A01650809 @% %@CR:C6A01650810 @% %@CR:C6A01650811 @%%@CR:C6A01650812 @% %@CR:C6A01650813 @%%@AE@%%@EH@%%@NL@%
  20511. %@NL@%
  20512. Release unused heap memory to the operating system.  %@NL@%
  20513. %@NL@%
  20514. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  20515. %@NL@%
  20516. %@AS@%  int _heapmin( void );%@AE@%%@NL@%
  20517. %@NL@%
  20518. %@AS@%  int _bheapmin( _segment seg )%@AE@%%@NL@%
  20519. %@NL@%
  20520. %@AS@%  int _fheapmin( void );%@AE@%%@NL@%
  20521. %@NL@%
  20522. %@AS@%  int _nheapmin( void );%@AE@%%@NL@%
  20523. %@NL@%
  20524. %@AI@%seg%@AE@%                               Specified based-heap selector
  20525.  
  20526. %@NL@%
  20527. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20528. %@NL@%
  20529. The %@AB@%_heapmin%@AE@% functions minimize the heap by releasing unused heap memory to
  20530. the operating system.  %@NL@%
  20531. %@NL@%
  20532. The various %@AB@%_heapmin%@AE@% functions release unused memory in these heaps:  %@NL@%
  20533. %@NL@%
  20534. %@AB@%Function %@AE@%                         %@AB@%Heap Minimized%@AE@%
  20535. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20536. %@AB@%_heapmin%@AE@%                          Depends on data model of program
  20537.  
  20538. %@AB@%_bheapmin%@AE@%                         Based heap specified by %@AI@%seg%@AE@% value; %@AB@%%@AE@%
  20539.                                   %@AB@%_NULLSEG%@AE@% specifies all based heaps
  20540.  
  20541. %@AB@%_fheapmin%@AE@%                         Far heap (outside default data segment)
  20542.  
  20543. %@AB@%_nheapmin%@AE@%                         Near heap (inside default data segment)
  20544.  
  20545. In large data models (that is, compact-, large-, and huge-model programs),
  20546. %@AB@%_heapmin%@AE@% maps to %@AB@%_fheapmin%@AE@%. In small data models (tiny-, small-, and
  20547. medium-model programs), %@AB@%_heapmin%@AE@% maps to %@AB@%_nheapmin%@AE@%.  %@NL@%
  20548. %@NL@%
  20549. Based-heap segments are never freed (i.e., unlinked from the based heap list
  20550. and released back to the operating system) by the %@AB@%_bheapmin%@AE@% function. The
  20551. %@AB@%_bfreeseg%@AE@% function is used for that purpose.  %@NL@%
  20552. %@NL@%
  20553. %@NL@%
  20554. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20555. %@NL@%
  20556. The %@AB@%_heapmin%@AE@% functions return 0 if the function completed successfully, or
  20557. -1 in the case of an error.  %@NL@%
  20558. %@NL@%
  20559. %@NL@%
  20560. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20561. %@NL@%
  20562.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  20563. %@NL@%
  20564. %@NL@%
  20565. %@NL@%
  20566. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20567. %@NL@%
  20568. %@AB@%_bfreeseg%@AE@%, %@AB@%free%@AE@% functions, %@AB@%malloc%@AE@% functions  %@NL@%
  20569. %@NL@%
  20570. %@NL@%
  20571. %@NL@%
  20572. %@NL@%
  20573. %@QR:_heapset@%%@NL@%
  20574. %@2@%%@CR:C6A01660814 @%%@AB@%_heapset Functions%@AE@%%@EH@%%@NL@%
  20575. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20576. %@NL@%
  20577. %@NL@%
  20578. %@3@%%@AB@%Description%@CR:C6A01660815 @% %@CR:C6A01660816 @% %@CR:C6A01660817 @%%@CR:C6A01660818 @% %@CR:C6A01660819 @%%@CR:C6A01660820 @% %@CR:C6A01660821 @%%@CR:C6A01660822 @%%@AE@%%@EH@%%@NL@%
  20579. %@NL@%
  20580. Check heaps for minimal consistency and set the free entries to a specified
  20581. value.  %@NL@%
  20582. %@NL@%
  20583. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  20584. %@NL@%
  20585. %@AS@%  int _heapset( unsigned int fill );%@AE@%%@NL@%
  20586. %@NL@%
  20587. %@AS@%  int _bheapset( _segment seg, unsigned int fill );%@AE@%%@NL@%
  20588. %@NL@%
  20589. %@AS@%  int _fheapset( unsigned int fill );%@AE@%%@NL@%
  20590. %@NL@%
  20591. %@AS@%  int _nheapset( unsigned int fill );%@AE@%%@NL@%
  20592. %@NL@%
  20593. %@AI@%fill%@AE@%                              Fill character
  20594.  
  20595. %@AI@%seg%@AE@%                               Specified based-heap segment selector
  20596.  
  20597. %@NL@%
  20598. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20599. %@NL@%
  20600. The %@AB@%_heapset%@AE@% family of routines helps debug heap-related problems in
  20601. programs by showing free memory locations or nodes unintentionally
  20602. overwritten.  %@NL@%
  20603. %@NL@%
  20604. The %@AB@%_heapset%@AE@% routines first check for minimal consistency on the heap in a
  20605. manner identical to that of the %@AB@%_heapchk%@AE@% functions. After the consistency
  20606. check, the %@AB@%_heapset%@AE@% functions set each byte of the heap's free entries to
  20607. the %@AI@%fill%@AE@% value. This known value shows which memory locations of the heap
  20608. contain free nodes and which locations contain data that were
  20609. unintentionally written to freed memory.  %@NL@%
  20610. %@NL@%
  20611. The various %@AB@%_heapset%@AE@% functions check and fill these heaps:  %@NL@%
  20612. %@NL@%
  20613. %@AB@%Function%@AE@%                          %@AB@%Heap Filled%@AE@%
  20614. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20615. %@AB@%_heapset%@AE@%                          Depends on data model of program
  20616.  
  20617. %@AB@%_bheapset%@AE@%                         Based heap specified by %@AI@%seg%@AE@% value; %@AB@%%@AE@%
  20618.                                   %@AB@%_NULLSEG %@AE@%specifies all based heaps
  20619.  
  20620. %@AB@%_fheapset%@AE@%                         Far heap (outside default data segment)
  20621.  
  20622. %@AB@%_nheapset%@AE@%                         Near heap (inside default data segment)
  20623.  
  20624. In large data models (that is, compact-, large-, and huge-model programs),
  20625. %@AB@%_heapset%@AE@% maps to %@AB@%_fheapset%@AE@%. In small data models (tiny-, small-, and
  20626. medium-model programs), %@AB@%_heapset%@AE@% maps to %@AB@%_nheapset%@AE@%.  %@NL@%
  20627. %@NL@%
  20628. %@NL@%
  20629. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20630. %@NL@%
  20631. All four routines return an %@AB@%int%@AE@% whose value is one of the following manifest
  20632. constants (defined in MALLOC.H):  %@NL@%
  20633. %@NL@%
  20634. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  20635. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20636. %@AB@%_HEAPBADBEGIN%@AE@%                     Initial header information cannot be 
  20637.                                   found, or it is invalid 
  20638.  
  20639. %@AB@%_HEAPBADNODE%@AE@%                      Bad node has been found, or the heap is 
  20640.                                   damaged
  20641.  
  20642. %@AB@%_HEAPEMPTY%@AE@%                        Heap has not been initialized 
  20643.  
  20644. %@AB@%_HEAPOK%@AE@%                           Heap appears to be consistent
  20645.  
  20646. %@AB@%%@AE@%
  20647.  
  20648. %@NL@%
  20649. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20650. %@NL@%
  20651.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  20652. %@NL@%
  20653. %@NL@%
  20654. %@NL@%
  20655. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20656. %@NL@%
  20657. %@AB@%_heapchk%@AE@% functions,  %@AB@%_heapwalk%@AE@% functions  %@NL@%
  20658. %@NL@%
  20659. %@NL@%
  20660. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  20661. %@NL@%
  20662. %@AS@%  /* HEAPSET.C: This program checks the heap and fills in free entries
  20663. %@AS@%   * with the character 'Z'.
  20664. %@AS@%   */
  20665. %@AS@%  
  20666. %@AS@%  #include <malloc.h>
  20667. %@AS@%  #include <stdio.h>
  20668. %@AS@%  #include <stdlib.h>
  20669. %@AS@%  
  20670. %@AS@%  void main()
  20671. %@AS@%  {
  20672. %@AS@%     int heapstatus;
  20673. %@AS@%     char *buffer;%@AE@%%@NL@%
  20674. %@NL@%
  20675. %@AS@%  if( (buffer = malloc( 1 )) == NULL )   /* Make sure heap is initialized */
  20676. %@AS@%        exit( 0 );
  20677. %@AS@%     heapstatus = _heapset( 'Z' );          /* Fill in free entries */
  20678. %@AS@%     switch( heapstatus )
  20679. %@AS@%     {
  20680. %@AS@%        case _HEAPOK:
  20681. %@AS@%           printf( "OK - heap is fine\n" );
  20682. %@AS@%           break;
  20683. %@AS@%        case _HEAPEMPTY:
  20684. %@AS@%           printf( "OK - heap is empty\n" );
  20685. %@AS@%           break;
  20686. %@AS@%        case _HEAPBADBEGIN:
  20687. %@AS@%           printf( "ERROR - bad start of heap\n" );
  20688. %@AS@%           break;
  20689. %@AS@%        case _HEAPBADNODE:
  20690. %@AS@%           printf( "ERROR - bad node in heap\n" );
  20691. %@AS@%           break;
  20692. %@AS@%     }
  20693. %@AS@%     free( buffer );
  20694. %@AS@%  }%@AE@%%@NL@%
  20695. %@NL@%
  20696. %@NL@%
  20697. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  20698. %@NL@%
  20699. %@AS@%  
  20700. %@AS@%  
  20701. %@AS@%  OK - heap is fine %@AE@%%@NL@%
  20702. %@NL@%
  20703. %@NL@%
  20704. %@NL@%
  20705. %@NL@%
  20706. %@QR:_heapwalk@%%@NL@%
  20707. %@2@%%@CR:C6A01670823 @%%@AB@%_heapwalk Functions%@AE@%%@EH@%%@NL@%
  20708. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20709. %@NL@%
  20710. %@NL@%
  20711. %@3@%%@AB@%Description%@CR:C6A01670824 @%%@CR:C6A01670825 @% %@CR:C6A01670826 @%%@CR:C6A01670827 @% %@CR:C6A01670828 @% %@CR:C6A01670829 @%%@CR:C6A01670830 @% %@CR:C6A01670831 @%%@AE@%%@EH@%%@NL@%
  20712. %@NL@%
  20713. Traverse the heap and return information about the next entry.  %@NL@%
  20714. %@NL@%
  20715. %@AS@%  include <malloc.h>%@AE@%%@NL@%
  20716. %@NL@%
  20717. %@AS@%  int _heapwalk( _HEAPINFO *entryinfo );%@AE@%%@NL@%
  20718. %@NL@%
  20719. %@AS@%  int _bheapwalk( _segment seg, _HEAPINFO *entryinfo );%@AE@%%@NL@%
  20720. %@NL@%
  20721. %@AS@%  int _fheapwalk( _HEAPINFO *entryinfo );%@AE@%%@NL@%
  20722. %@NL@%
  20723. %@AS@%  int _nheapwalk(_HEAPINFO *entryinfo);%@AE@%%@NL@%
  20724. %@NL@%
  20725. %@AI@%entryinfo%@AE@%                         Buffer to contain heap information
  20726.  
  20727. %@AI@%seg%@AE@%                               Based-heap segment selector
  20728.  
  20729. %@NL@%
  20730. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20731. %@NL@%
  20732. The %@AB@%_heapwalk%@AE@% family of routines helps debug heap-related problems in
  20733. programs.  %@NL@%
  20734. %@NL@%
  20735. The %@AB@%_heapwalk%@AE@% routines walk through the heap, traversing one entry per call,
  20736. and return a pointer to a %@AB@%_heapinfo%@AE@% structure that contains information
  20737. about the next heap entry. The %@AB@%_heapinfo%@AE@% structure, defined in MALLOC.H,
  20738. contains the following elements:  %@NL@%
  20739. %@NL@%
  20740. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  20741. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20742. %@AB@%int far *_pentry%@AE@%                  Heap entry pointer
  20743.  
  20744. %@AB@%size_t  _size%@AE@%                     Size of heap entry
  20745.  
  20746. %@AB@%int _useflag%@AE@%                      Entry "in use" flag
  20747.  
  20748. A call to %@AB@%_heapwalk%@AE@% that returns %@AB@%_HEAPOK%@AE@% stores the size of the entry in the
  20749. %@AB@%_size%@AE@% field and sets the %@AB@%_useflag%@AE@% field to either %@AB@%_FREEENTRY%@AE@% or %@AB@%_USEDENTRY%@AE@%
  20750. (both are constants defined in MALLOC.H). To obtain this information about
  20751. the first entry in the heap, pass the %@AB@%_heapwalk%@AE@% routine a pointer to a
  20752. %@AB@%_heapinfo%@AE@% structure whose %@AB@%_pentry%@AE@% field is %@AB@%NULL%@AE@%.  %@NL@%
  20753. %@NL@%
  20754. The various %@AB@%_heapwalk%@AE@% functions walk through and gather information on these
  20755. heaps:  %@NL@%
  20756. %@NL@%
  20757. %@AB@%Function%@AE@%                          %@AB@%Heap Walked%@AE@%
  20758. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20759. %@AB@%_heapwalk%@AE@%                         Depends on data model of program
  20760.  
  20761. %@AB@%_bheapwalk%@AE@%                        Based heap specified by %@AI@%seg%@AE@% value; %@AB@%%@AE@%
  20762.                                   %@AB@%_NULLSEG%@AE@% specifies all based heaps
  20763.  
  20764. %@AB@%_fheapwalk%@AE@%                        Far heap (outside default data segment)
  20765.  
  20766. %@AB@%_nheapwalk%@AE@%                        Near heap (inside default data segment)
  20767.  
  20768. In large data models (that is, compact-, large-, and huge-model programs),
  20769. %@AB@%_heapwalk%@AE@% maps to %@AB@%_fheapwalk%@AE@%. In small data models (tiny-, small-, and
  20770. medium-model programs), %@AB@%_heapwalk%@AE@% maps to %@AB@%_nheapwalk%@AE@%.  %@NL@%
  20771. %@NL@%
  20772. %@NL@%
  20773. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20774. %@NL@%
  20775. All three routines return one of the following manifest constants (defined
  20776. in MALLOC.H):  %@NL@%
  20777. %@NL@%
  20778. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  20779. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20780. %@AB@%_HEAPBADBEGIN%@AE@%                     The initial header information cannot be
  20781.                                   found, or it is invalid.
  20782.  
  20783. %@AB@%_HEAPBADNODE%@AE@%                      A bad node has been found, or the heap 
  20784.                                   is damaged.
  20785.  
  20786. %@AB@%_HEAPBADPTR%@AE@%                       The %@AB@%_pentry%@AE@% field of the %@AB@%_heapinfo%@AE@% 
  20787.                                   structure does not contain a valid 
  20788.                                   pointer into the heap.
  20789.  
  20790. %@AB@%_HEAPEND%@AE@%                          The end of the heap has been reached 
  20791.                                   successfully.
  20792.  
  20793. %@AB@%_HEAPEMPTY%@AE@%                        The heap has not been initialized.
  20794.  
  20795. %@AB@%_HEAPOK%@AE@%                           No errors so far; the %@AB@%_heapinfo%@AE@% 
  20796.                                   structure contains information about the
  20797.                                   next entry.
  20798.  
  20799. %@NL@%
  20800. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20801. %@NL@%
  20802.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  20803. %@NL@%
  20804. %@NL@%
  20805. %@NL@%
  20806. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20807. %@NL@%
  20808. %@AB@%_heapchk%@AE@% functions,  %@AB@%_heapset%@AE@% functions  %@NL@%
  20809. %@NL@%
  20810. %@NL@%
  20811. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  20812. %@NL@%
  20813. %@AS@%  /* HEAPWALK.C: This program "walks" the heap, starting at the beginning
  20814. %@AS@%   * (_pentry = NULL). It prints out each heap entry's use, location,
  20815. %@AS@%   * and size. It also prints out information about the overall state
  20816. %@AS@%   * of the heap as soon as _heapwalk returns a value other than _HEAPOK.
  20817. %@AS@%   */
  20818. %@AS@%  
  20819. %@AS@%  #include <stdio.h>
  20820. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  20821. %@NL@%
  20822. %@AS@%  void heapdump( void );
  20823. %@AS@%  
  20824. %@AS@%  void main()
  20825. %@AS@%  {
  20826. %@AS@%     char *buffer;
  20827. %@AS@%  
  20828. %@AS@%     heapdump();
  20829. %@AS@%     if( (buffer = malloc( 59 )) != NULL )
  20830. %@AS@%     {
  20831. %@AS@%        heapdump();
  20832. %@AS@%        free( buffer );
  20833. %@AS@%     }
  20834. %@AS@%     heapdump();
  20835. %@AS@%  }
  20836. %@AS@%  
  20837. %@AS@%  void heapdump( void )
  20838. %@AS@%  {
  20839. %@AS@%     struct _heapinfo hinfo;
  20840. %@AS@%     int heapstatus;
  20841. %@AS@%  
  20842. %@AS@%     hinfo._pentry = NULL;
  20843. %@AS@%     while( ( heapstatus = _heapwalk( &hinfo ) ) == _HEAPOK )
  20844. %@AS@%     {
  20845. %@AS@%        printf( "%6s block at %Fp of size %4.4X\n",
  20846. %@AS@%           ( hinfo._useflag == _USEDENTRY ? "USED" : "FREE" ),
  20847. %@AS@%           hinfo._pentry, hinfo._size );
  20848. %@AS@%     }
  20849. %@AS@%  
  20850. %@AS@%     switch( heapstatus )
  20851. %@AS@%     {
  20852. %@AS@%        case _HEAPEMPTY:
  20853. %@AS@%           printf( "OK - empty heap\n" );
  20854. %@AS@%           break;
  20855. %@AS@%        case _HEAPEND:
  20856. %@AS@%           printf( "OK - end of heap\n" );
  20857. %@AS@%           break;
  20858. %@AS@%        case _HEAPBADPTR:
  20859. %@AS@%           printf( "ERROR - bad pointer to heap\n" );
  20860. %@AS@%           break;
  20861. %@AS@%        case _HEAPBADBEGIN:
  20862. %@AS@%           printf( "ERROR - bad start of heap\n" );
  20863. %@AS@%           break;
  20864. %@AS@%        case _HEAPBADNODE:
  20865. %@AS@%           printf( "ERROR - bad node in heap\n" );
  20866. %@AS@%           break;
  20867. %@AS@%     }
  20868. %@AS@%  }%@AE@%%@NL@%
  20869. %@NL@%
  20870. %@NL@%
  20871. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  20872. %@NL@%
  20873. %@AS@%  
  20874. %@AS@%  
  20875. %@AS@%    USED block at 0067:103E of size 000E
  20876. %@AS@%    USED block at 0067:104E of size 01F4
  20877. %@AS@%    USED block at 0067:1244 of size 0026
  20878. %@AS@%    USED block at 0067:126C of size 0200
  20879. %@AS@%    FREE block at 0067:146E of size 0B90
  20880. %@AS@%  OK - end of heap
  20881. %@AS@%    USED block at 0067:103E of size 000E
  20882. %@AS@%    USED block at 0067:104E of size 01F4
  20883. %@AS@%    USED block at 0067:1244 of size 0026
  20884. %@AS@%    USED block at 0067:126C of size 0200
  20885. %@AS@%    USED block at 0067:146E of size 003C
  20886. %@AS@%    FREE block at 0067:14AC of size 0B52
  20887. %@AS@%  OK - end of heap
  20888. %@AS@%    USED block at 0067:103E of size 000E
  20889. %@AS@%    USED block at 0067:104E of size 01F4
  20890. %@AS@%    USED block at 0067:1244 of size 0026
  20891. %@AS@%    USED block at 0067:126C of size 0200
  20892. %@AS@%    FREE block at 0067:146E of size 003C
  20893. %@AS@%    FREE block at 0067:14AC of size 0B52
  20894. %@AS@%  OK - end of heap %@AE@%%@NL@%
  20895. %@NL@%
  20896. %@NL@%
  20897. %@NL@%
  20898. %@NL@%
  20899. %@QR:hfree@%%@NL@%
  20900. %@2@%%@CR:C6A01680832 @%%@AB@%hfree%@AE@%%@EH@%%@NL@%
  20901. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20902. %@NL@%
  20903. %@NL@%
  20904. %@3@%%@AB@%Description%@CR:C6A01680833 @%%@CR:C6A01680834 @%%@AE@%%@EH@%%@NL@%
  20905. %@NL@%
  20906. Frees a huge memory block.  %@NL@%
  20907. %@NL@%
  20908. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  20909.  
  20910. %@AS@%  void hfree( void _huge *memblock );%@AE@%%@NL@%
  20911. %@NL@%
  20912. %@AI@%memblock%@AE@%                          Pointer to allocated memory block
  20913.  
  20914. %@NL@%
  20915. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20916. %@NL@%
  20917. The %@AB@%hfree%@AE@% function deallocates a memory block; the freed memory is returned
  20918. to the operating system. The %@AI@%memblock%@AE@% argument points to a memory block
  20919. previously allocated through a call to %@AB@%halloc%@AE@%. The number of bytes freed is
  20920. the number of bytes specified when the block was allocated.  %@NL@%
  20921. %@NL@%
  20922. Note that attempting to free an invalid %@AI@%memblock%@AE@% argument (one not allocated
  20923. with %@AB@%halloc%@AE@%) may affect subsequent allocation and cause errors.  %@NL@%
  20924. %@NL@%
  20925. %@NL@%
  20926. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  20927. %@NL@%
  20928. None.  %@NL@%
  20929. %@NL@%
  20930. %@NL@%
  20931. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  20932. %@NL@%
  20933.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  20934. %@NL@%
  20935. %@NL@%
  20936. %@NL@%
  20937. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  20938. %@NL@%
  20939. %@AB@%halloc%@AE@%  %@NL@%
  20940. %@NL@%
  20941. %@NL@%
  20942. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  20943. %@NL@%
  20944. %@AS@%  /* HALLOC.C: This program uses halloc to allocate space for 30,000 long
  20945. %@AS@%   * integers, then uses hfree to deallocate the memory.
  20946. %@AS@%   */
  20947. %@AS@%  
  20948. %@AS@%  #include <stdio.h>
  20949. %@AS@%  #include <stdlib.h>
  20950. %@AS@%  #include <malloc.h>
  20951. %@AS@%  
  20952. %@AS@%  void main()
  20953. %@AS@%  {
  20954. %@AS@%     long _huge *hbuf;
  20955. %@AS@%  
  20956. %@AS@%     /* Allocate huge buffer */
  20957. %@AS@%     hbuf = (long _huge *)halloc( 30000L, sizeof( long ) );
  20958. %@AS@%     if ( hbuf == NULL )
  20959. %@AS@%        printf( "Insufficient memory available\n" );
  20960. %@AS@%     else
  20961. %@AS@%        printf( "Memory successfully allocated\n" );%@AE@%%@NL@%
  20962. %@NL@%
  20963. %@AS@%  /* Free huge buffer */
  20964. %@AS@%     hfree( hbuf );
  20965. %@AS@%  }%@AE@%%@NL@%
  20966. %@NL@%
  20967. %@NL@%
  20968. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  20969. %@NL@%
  20970. %@AS@%  
  20971. %@AS@%  
  20972. %@AS@%  Memory successfully allocated %@AE@%%@NL@%
  20973. %@NL@%
  20974. %@NL@%
  20975. %@NL@%
  20976. %@NL@%
  20977. %@QR:hypot@%%@QR:hypotl@%%@NL@%
  20978. %@2@%%@CR:C6A01690835 @%%@AB@%hypot, hypotl%@AE@%%@EH@%%@NL@%
  20979. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  20980. %@NL@%
  20981. %@NL@%
  20982. %@3@%%@AB@%Description%@CR:C6A01690836 @%%@CR:C6A01690837 @%%@CR:C6A01690838 @% %@CR:C6A01690839 @%%@CR:C6A01690840 @% %@CR:C6A01690841 @%%@AE@%%@EH@%%@NL@%
  20983. %@NL@%
  20984. Calculate the hypotenuse.  %@NL@%
  20985. %@NL@%
  20986. %@AS@%  #include <math.h>%@AE@%%@NL@%
  20987. %@NL@%
  20988. %@AS@%  double hypot( double x, double y );%@AE@%%@NL@%
  20989. %@NL@%
  20990. %@AS@%  long double hypotl( long double x, long double y );%@AE@%%@NL@%
  20991. %@NL@%
  20992. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              Floating-point values
  20993.  
  20994. %@NL@%
  20995. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  20996. %@NL@%
  20997. The %@AB@%hypot%@AE@% and %@AB@%hypotl%@AE@% functions calculate the length of the hypotenuse of a
  20998. right triangle, given the length of the two sides %@AI@%x%@AE@% and %@AI@%y%@AE@% (or %@AI@%xl%@AE@% and %@AI@%yl%@AE@%). A
  20999. call to %@AB@%hypot%@AE@% is equivalent to the following:   %@NL@%
  21000. %@NL@%
  21001. %@AS@%  sqrt(x*x + y*y);
  21002. %@AS@%   %@AE@%%@NL@%
  21003. %@NL@%
  21004. The %@AB@%hypotl%@AE@% function uses the 80-bit, 10-byte coprocessor form of arguments
  21005. and return values. See the reference page on the long double functions for
  21006. more details on this data type.  %@NL@%
  21007. %@NL@%
  21008. %@NL@%
  21009. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21010. %@NL@%
  21011. The functions return the length of the hypotenuse. If an overflow results,
  21012. the functions return %@AB@%HUGE_VAL%@AE@% and set %@AB@%errno%@AE@% to %@AB@%ERANGE.%@AE@%  %@NL@%
  21013. %@NL@%
  21014. %@NL@%
  21015. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21016. %@NL@%
  21017. %@AB@%hypot%@AE@%  %@NL@%
  21018. %@NL@%
  21019.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  21020. %@NL@%
  21021. %@NL@%
  21022. %@AB@%hypotl%@AE@%  %@NL@%
  21023. %@NL@%
  21024.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  21025. %@NL@%
  21026. %@NL@%
  21027. %@NL@%
  21028. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21029. %@NL@%
  21030. %@AB@%cabs%@AE@%  %@NL@%
  21031. %@NL@%
  21032. %@NL@%
  21033. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21034. %@NL@%
  21035. %@AS@%  /* HYPOT.C: This program prints the hypotenuse of a right triangle. */
  21036. %@AS@%  
  21037. %@AS@%  #include <math.h>
  21038. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  21039. %@NL@%
  21040. %@AS@%  void main()
  21041. %@AS@%  {
  21042. %@AS@%     double x = 3.0, y = 4.0;
  21043. %@AS@%  
  21044. %@AS@%     printf( "If a right triangle has sides %2.1f and %2.1f, "
  21045. %@AS@%             "its hypotenuse is %2.1f\n", x, y, hypot( x, y ) );
  21046. %@AS@%  }%@AE@%%@NL@%
  21047. %@NL@%
  21048. %@NL@%
  21049. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21050. %@NL@%
  21051. %@AS@%  
  21052. %@AS@%  
  21053. %@AS@%  If a right triangle has sides 3.0 and 4.0, its hypotenuse is 5.0%@AE@%%@NL@%
  21054. %@NL@%
  21055. %@NL@%
  21056. %@NL@%
  21057. %@NL@%
  21058. %@QR:_imagesize@%%@NL@%
  21059. %@2@%%@CR:C6A01700842 @%%@AB@%_imagesize Functions%@AE@%%@EH@%%@NL@%
  21060. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21061. %@NL@%
  21062. %@NL@%
  21063. %@3@%%@AB@%Description%@CR:C6A01700843 @%%@AE@%%@EH@%%@NL@%
  21064. %@NL@%
  21065. Get amount of memory required to store graphics images.  %@NL@%
  21066. %@NL@%
  21067. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  21068. %@NL@%
  21069. %@AS@%  long _far _imagesize( short x1, short y1, short x2, short y2 );%@AE@%%@NL@%
  21070. %@NL@%
  21071. %@AS@%  long _far _imagesize_w( double wx1, double wy1, double wx2, double wy2 );%@AE@%%@NL@%
  21072. %@NL@%
  21073. %@AS@%  long _far _imagesize_wxy( struct _wxycoord _far *pwxy1, 
  21074. %@AS@%  struct _wxycoord _far *pwxy2 );%@AE@%%@NL@%
  21075. %@NL@%
  21076. %@AI@%x1%@AE@%, %@AI@%y1%@AE@%                            Upper-left corner of bounding rectangle
  21077.  
  21078. %@AI@%x2%@AE@%, %@AI@%y2%@AE@%                            Lower-right corner of bounding rectangle
  21079.  
  21080. %@AI@%wx1%@AE@%, %@AI@%wy1%@AE@%                          Upper-left corner of bounding rectangle
  21081.  
  21082. %@AI@%wx2%@AE@%, %@AI@%wy2%@AE@%                          Lower-right corner of bounding rectangle
  21083.  
  21084. %@AI@%pwxy1%@AE@%                             Upper-left corner of bounding rectangle
  21085.  
  21086. %@AI@%pwxy2%@AE@%                             Lower-right corner of bounding rectangle
  21087.  
  21088. %@NL@%
  21089. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21090. %@NL@%
  21091. The functions in the %@AB@%_imagesize%@AE@% family return the number of bytes needed to
  21092. store the image defined by the bounding rectangle and specified by the
  21093. coordinates given in the function call.  %@NL@%
  21094. %@NL@%
  21095. The %@AB@%_imagesize%@AE@% function defines the bounding rectangle in terms of
  21096. view-coordinate points (%@AI@%x1%@AE@%, %@AI@%y1%@AE@%) and (%@AI@%x2%@AE@%, %@AI@%y2%@AE@%).  %@NL@%
  21097. %@NL@%
  21098. The %@AB@%_imagesize_w%@AE@% function defines the bounding rectangle in terms of
  21099. window-coordinate points (%@AI@%x1%@AE@%, %@AI@%y1%@AE@%) and (%@AI@%x2%@AE@%, %@AI@%y2%@AE@%).  %@NL@%
  21100. %@NL@%
  21101. The %@AB@%_imagesize_wxy%@AE@% function defines the bounding rectangle in terms of the
  21102. window-coordinate pairs %@AI@%pwxy1%@AE@% and %@AI@%pwxy2%@AE@%.  %@NL@%
  21103. %@NL@%
  21104. The number of bytes needed to store the image is determined by the following
  21105. formula:  %@NL@%
  21106. %@NL@%
  21107. %@AS@%  xwid = abs(x1-x2)+1;
  21108. %@AS@%  ywid = abs(y1-y2)+1;
  21109. %@AS@%  size = 4+((long)((xwid*bits_per_pixel+7)/8)*(long)ywid);%@AE@%%@NL@%
  21110. %@NL@%
  21111. A call to %@AB@%_getvideoconfig%@AE@% stores the %@AS@% bits_per_pixel %@AE@% information in the
  21112. %@AB@%bitsperpixel%@AE@% field of a %@AB@%videoconfig%@AE@% structure.  %@NL@%
  21113. %@NL@%
  21114. %@NL@%
  21115. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21116. %@NL@%
  21117. The function returns the storage size of the image in bytes. There is no
  21118. error return.  %@NL@%
  21119. %@NL@%
  21120. %@NL@%
  21121. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21122. %@NL@%
  21123.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  21124. %@NL@%
  21125. %@NL@%
  21126. %@NL@%
  21127. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21128. %@NL@%
  21129. %@AB@%_getimage %@AE@%functions,  %@AB@%_getvideoconfig%@AE@%,  %@AB@%_putimage%@AE@% functions  %@NL@%
  21130. %@NL@%
  21131. %@NL@%
  21132. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21133. %@NL@%
  21134. See the example for %@AB@%_getimage%@AE@%.  %@NL@%
  21135. %@NL@%
  21136. %@NL@%
  21137. %@NL@%
  21138. %@NL@%
  21139. %@QR:inp@%%@QR:inpw@%%@NL@%
  21140. %@2@%%@CR:C6A01710844 @%%@AB@%inp, inpw%@AE@%%@EH@%%@NL@%
  21141. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21142. %@NL@%
  21143. %@NL@%
  21144. %@3@%%@AB@%Description%@CR:C6A01710845 @%%@CR:C6A01710846 @% %@CR:C6A01710847 @%%@CR:C6A01710848 @%%@AE@%%@EH@%%@NL@%
  21145. %@NL@%
  21146. Input a byte (%@AB@%inp%@AE@%) or a word (%@AB@%inpw%@AE@%) from a port.  %@NL@%
  21147. %@NL@%
  21148. %@AB@%#include <conio.h>%@AE@%                Required only for function declarations
  21149.  
  21150. %@AS@%  int inp( unsigned port );%@AE@%%@NL@%
  21151. %@NL@%
  21152. %@AS@%  unsigned inpw( unsigned port );%@AE@%%@NL@%
  21153. %@NL@%
  21154. %@AI@%port%@AE@%                              Port number
  21155.  
  21156. %@NL@%
  21157. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21158. %@NL@%
  21159. The %@AB@%inp%@AE@% and %@AB@%inpw%@AE@% functions read a byte and a word, respectively, from the
  21160. specified input port. The input value can be any unsigned integer in the
  21161. range 0 - 65,535.  %@NL@%
  21162. %@NL@%
  21163. To use %@AB@%inp%@AE@% and %@AB@%inpw%@AE@% in OS/2 protected mode, you must use a .DEF file to
  21164. declare the IOSEG segment that the run-time library uses to perform
  21165. input/output on the port. In addition, the intrinsic (/Oi) versions of these
  21166. functions do not work unless you put the code in a segment that is marked
  21167. with the %@AB@%IOPL%@AE@% keyword in the .DEF file.  %@NL@%
  21168. %@NL@%
  21169. Because you cannot do IOPL from a regular code segment, the run-time library
  21170. declares a separate code segment called %@AB@%_IOSEG%@AE@%. In order to use %@AB@%inp%@AE@%, %@AB@%inpw%@AE@%,
  21171. %@AB@%outp%@AE@%, or %@AB@%outpw%@AE@% in any of the protected-mode run-time libraries (?LIBCP,
  21172. LLIBCDLL, LLIBCMT, or CDLLOBJS-based DLL), you must have a .DEF file
  21173. containing this line:  %@NL@%
  21174. %@NL@%
  21175. %@AS@%  SEGMENTS _IOSEG CLASS 'IOSEG_CODE' IOPL%@AE@%%@NL@%
  21176. %@NL@%
  21177. %@NL@%
  21178. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21179. %@NL@%
  21180. The functions return the byte or word read from %@AI@%port%@AE@%. There is no error
  21181. return.  %@NL@%
  21182. %@NL@%
  21183. %@NL@%
  21184. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21185. %@NL@%
  21186.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS2   UNIX   XENIX%@NL@%
  21187. %@NL@%
  21188. %@NL@%
  21189. %@NL@%
  21190. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21191. %@NL@%
  21192. %@AB@%outp%@AE@%, %@AB@%outpw%@AE@%  %@NL@%
  21193. %@NL@%
  21194. %@NL@%
  21195. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21196. %@NL@%
  21197. See the example for %@AB@%outp%@AE@%.  %@NL@%
  21198. %@NL@%
  21199. %@NL@%
  21200. %@NL@%
  21201. %@NL@%
  21202. %@QR:int86@%%@NL@%
  21203. %@2@%%@CR:C6A01720849 @%%@AB@%int86%@AE@%%@EH@%%@NL@%
  21204. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21205. %@NL@%
  21206. %@NL@%
  21207. %@3@%%@AB@%Description%@CR:C6A01720850 @%%@CR:C6A01720851 @% %@CR:C6A01720852 @% %@CR:C6A01720853 @%%@AE@%%@EH@%%@NL@%
  21208. %@NL@%
  21209. Executes the 8086 interrupt.  %@NL@%
  21210. %@NL@%
  21211. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  21212. %@NL@%
  21213. %@AS@%  int int86( int intnum, union REGS *inregs, union REGS *outregs );%@AE@%%@NL@%
  21214. %@NL@%
  21215. %@AI@%intnum%@AE@%                            Interrupt number
  21216.  
  21217. %@AI@%inregs%@AE@%                            Register values on call
  21218.  
  21219. %@AI@%outregs%@AE@%                           Register values on return
  21220.  
  21221. %@NL@%
  21222. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21223. %@NL@%
  21224. The %@AB@%int86%@AE@% function executes the 8086-processor-family interrupt specified by
  21225. the interrupt number %@AI@%intnum%@AE@%. Before executing the interrupt, %@AB@%int86%@AE@% copies
  21226. the contents of %@AI@%inregs%@AE@% to the corresponding registers. After the interrupt
  21227. returns, the function copies the current register values to %@AI@%outregs%@AE@%. It also
  21228. copies the status of the system carry flag to the %@AB@%cflag%@AE@% field in the %@AI@%outregs%@AE@%
  21229. argument. The %@AI@%inregs%@AE@% and %@AI@%outregs%@AE@% arguments are unions of type %@AB@%REGS%@AE@%. The
  21230. union type is defined in the include file DOS.H.  %@NL@%
  21231. %@NL@%
  21232. Do not use the %@AB@%int86%@AE@% function to call interrupts that modify the DS
  21233. register. Instead, use the %@AB@%int86x%@AE@% function. The %@AB@%int86x%@AE@% function loads the DS
  21234. and ES registers from the %@AI@%segregs%@AE@% parameter and also stores the DS and ES
  21235. registers into %@AI@%segregs%@AE@% after the function call.  %@NL@%
  21236. %@NL@%
  21237. The %@AB@%REGS%@AE@% type is defined in the include file DOS.H.  %@NL@%
  21238. %@NL@%
  21239. %@NL@%
  21240. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21241. %@NL@%
  21242. The return value is the value in the AX register after the interrupt
  21243. returns. If the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@% is nonzero, an error has occurred; in
  21244. such cases, the %@AB@%_doserrno%@AE@% variable is also set to the corresponding error
  21245. code.  %@NL@%
  21246. %@NL@%
  21247. %@NL@%
  21248. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21249. %@NL@%
  21250.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  21251. %@NL@%
  21252. %@NL@%
  21253. %@NL@%
  21254. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21255. %@NL@%
  21256. %@AB@%bdos%@AE@%, %@AB@%int86x%@AE@%,%@AB@% intdos%@AE@%, %@AB@%intdosx%@AE@%  %@NL@%
  21257. %@NL@%
  21258. %@NL@%
  21259. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21260. %@NL@%
  21261. %@AS@%  /* INT86.C: This program uses int86 to call the BIOS video service
  21262. %@AS@%   * (INT 10H) to get information about the cursor.
  21263. %@AS@%   */
  21264. %@AS@%  
  21265. %@AS@%  #include <dos.h>
  21266. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  21267. %@NL@%
  21268. %@AS@%  void main()
  21269. %@AS@%  {
  21270. %@AS@%     union REGS inregs, outregs;
  21271. %@AS@%  
  21272. %@AS@%     /* Set up to get cursor information. */
  21273. %@AS@%     inregs.h.ah = 3;       /* Get Cursor Position function */
  21274. %@AS@%     inregs.h.bh = 0;       /* Page 0 */
  21275. %@AS@%  
  21276. %@AS@%     /* Execute video interrupt: */
  21277. %@AS@%     int86( 0x10, &inregs, &outregs );
  21278. %@AS@%  
  21279. %@AS@%     /* Display results. */
  21280. %@AS@%     printf( "Cursor position\n\tRow: %d\n\tColumn: %d\n",
  21281. %@AS@%             outregs.h.dh, outregs.h.dl );
  21282. %@AS@%     printf( "Cursor shape\n\tStart: %d\n\tEnd: %d\n",
  21283. %@AS@%             outregs.h.ch, outregs.h.cl );
  21284. %@AS@%  }%@AE@%%@NL@%
  21285. %@NL@%
  21286. %@NL@%
  21287. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21288. %@NL@%
  21289. %@AS@%  
  21290. %@AS@%  
  21291. %@AS@%  Cursor position
  21292. %@AS@%          Row: 2
  21293. %@AS@%          Column: 0
  21294. %@AS@%  Cursor shape
  21295. %@AS@%          Start: 6
  21296. %@AS@%          End: 7%@AE@%%@NL@%
  21297. %@NL@%
  21298. %@NL@%
  21299. %@NL@%
  21300. %@NL@%
  21301. %@QR:int86x@%%@NL@%
  21302. %@2@%%@CR:C6A01730854 @%%@AB@%int86x%@AE@%%@EH@%%@NL@%
  21303. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21304. %@NL@%
  21305. %@NL@%
  21306. %@3@%%@AB@%Description%@CR:C6A01730855 @%%@CR:C6A01730856 @% %@CR:C6A01730857 @%%@CR:C6A01730858 @%%@AE@%%@EH@%%@NL@%
  21307. %@NL@%
  21308. Executes the 8086 interrupt; accepts segment-register values.  %@NL@%
  21309. %@NL@%
  21310. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  21311. %@NL@%
  21312. %@AS@%  int int86x( int intnum, union REGS *inregs, union REGS *outregs, 
  21313. %@AS@%  struct SREGS *segregs );%@AE@%%@NL@%
  21314. %@NL@%
  21315. %@AI@%intnum%@AE@%                            Interrupt number
  21316.  
  21317. %@AI@%inregs%@AE@%                            Register values on call
  21318.  
  21319. %@AI@%outregs%@AE@%                           Register values on return
  21320.  
  21321. %@AI@%segregs%@AE@%                           Segment-register values on call
  21322.  
  21323. %@NL@%
  21324. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21325. %@NL@%
  21326. The %@AB@%int86x%@AE@% function executes the 8086-processor-family interrupt specified
  21327. by the interrupt number %@AI@%intnum%@AE@%. Unlike the %@AB@%int86%@AE@% function, %@AB@%int86x%@AE@% accepts
  21328. segment-register values in %@AI@%segregs%@AE@%, enabling programs that use large-model
  21329. data segments or far pointers to specify which segment or pointer should be
  21330. used during the system call.  %@NL@%
  21331. %@NL@%
  21332. Before executing the specified interrupt, %@AB@%int86x%@AE@% copies the contents of
  21333. %@AI@%inregs%@AE@% and %@AI@%segregs%@AE@% to the corresponding registers. Only the DS and ES
  21334. register values in %@AI@%segregs%@AE@% are used. After the interrupt returns, the
  21335. function copies the current register values to %@AI@%outregs%@AE@%, cop-ies the current
  21336. ES and DS values to %@AI@%segregs%@AE@%, and restores DS. It also copies the status of
  21337. the system carry flag to the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@%.  %@NL@%
  21338. %@NL@%
  21339. The %@AB@%REGS%@AE@% and %@AB@%SREGS%@AE@% types are defined in the include file DOS.H.  %@NL@%
  21340. %@NL@%
  21341. Segment values for the %@AI@%segregs%@AE@% argument can be obtained by using either the
  21342. %@AB@%segread%@AE@% function or the %@AB@%FP_SEG%@AE@% macro.  %@NL@%
  21343. %@NL@%
  21344. %@NL@%
  21345. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21346. %@NL@%
  21347. The return value is the value in the AX register after the interrupt
  21348. returns. If the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@% is nonzero, an error has occurred; in
  21349. such cases, the %@AB@%_doserrno%@AE@% variable is also set to the corresponding error
  21350. code.  %@NL@%
  21351. %@NL@%
  21352. %@NL@%
  21353. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21354. %@NL@%
  21355.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  21356. %@NL@%
  21357. %@NL@%
  21358. %@NL@%
  21359. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21360. %@NL@%
  21361. %@AB@%bdos, FP_SEG%@AE@%, %@AB@%int86%@AE@%,%@AB@% intdos%@AE@%, %@AB@%intdosx%@AE@%, %@AB@%segread%@AE@%  %@NL@%
  21362. %@NL@%
  21363. %@NL@%
  21364. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21365. %@NL@%
  21366. %@AS@%  /* INT86X.C: In this program, int86x executes an INT 21H instruction
  21367. %@AS@%   * to invoke DOS system call 43H (change file attributes). The program
  21368. %@AS@%   * uses int86x because the file, which is referenced with a far pointer,
  21369. %@AS@%   * may be in a segment other than the default data segment. Thus, the
  21370. %@AS@%   * program must explicitly set the DS register with the SREGS structure.
  21371. %@AS@%   */
  21372. %@AS@%  
  21373. %@AS@%  #include <signal.h>
  21374. %@AS@%  #include <dos.h>
  21375. %@AS@%  #include <stdio.h>
  21376. %@AS@%  #include <process.h>
  21377. %@AS@%  
  21378. %@AS@%  char _far *filename = "int86x.c";
  21379. %@AS@%  
  21380. %@AS@%  void main()
  21381. %@AS@%  {
  21382. %@AS@%     union  REGS inregs, outregs;
  21383. %@AS@%     struct SREGS segregs;
  21384. %@AS@%     int    result;
  21385. %@AS@%  
  21386. %@AS@%     inregs.h.ah = 0x43;      /* DOS function to change attributes    */
  21387. %@AS@%     inregs.h.al = 0;         /* Subfunction 0 to get attributes)     */
  21388. %@AS@%     inregs.x.dx = FP_OFF( filename );   /* DS:DX points to file name */
  21389. %@AS@%     segregs.ds  = FP_SEG( filename );
  21390. %@AS@%     result = int86x( 0x21, &inregs, &outregs, &segregs );
  21391. %@AS@%     if( outregs.x.cflag )
  21392. %@AS@%        printf( "Can't get file attributes; error no. %d\n", result);
  21393. %@AS@%     else
  21394. %@AS@%        printf( "Attribs = 0x%.4x\n", outregs.x.cx );
  21395. %@AS@%  }%@AE@%%@NL@%
  21396. %@NL@%
  21397. %@NL@%
  21398. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21399. %@NL@%
  21400. %@AS@%  
  21401. %@AS@%  
  21402. %@AS@%  Attribs = 0x0020%@AE@%%@NL@%
  21403. %@NL@%
  21404. %@NL@%
  21405. %@NL@%
  21406. %@NL@%
  21407. %@QR:intdos@%%@NL@%
  21408. %@2@%%@CR:C6A01740859 @%%@AB@%intdos%@AE@%%@EH@%%@NL@%
  21409. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21410. %@NL@%
  21411. %@NL@%
  21412. %@3@%%@AB@%Description%@CR:C6A01740860 @%%@CR:C6A01740861 @% %@CR:C6A01740862 @%%@CR:C6A01740863 @%%@AE@%%@EH@%%@NL@%
  21413. %@NL@%
  21414. Executes the DOS system call.  %@NL@%
  21415. %@NL@%
  21416. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  21417. %@NL@%
  21418. %@AS@%  int intdos( union REGS *inregs, union REGS *outregs );%@AE@%%@NL@%
  21419. %@NL@%
  21420. %@AI@%inregs%@AE@%                            Register values on call
  21421.  
  21422. %@AI@%outregs%@AE@%                           Register values on return
  21423.  
  21424. %@NL@%
  21425. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21426. %@NL@%
  21427. The %@AB@%intdos%@AE@% function invokes the DOS system call specified by register values
  21428. defined in %@AI@%inregs%@AE@% and returns the effect of the system call in %@AI@%outregs%@AE@%. The
  21429. %@AI@%inregs%@AE@% and %@AI@%outregs%@AE@% arguments are unions of type %@AB@%REGS%@AE@%. The %@AB@%REGS %@AE@%type is
  21430. defined in the include file DOS.H.  %@NL@%
  21431. %@NL@%
  21432. To invoke a system call, %@AB@%intdos%@AE@% executes an INT 21H instruction. Before
  21433. executing the instruction, the function copies the contents of %@AI@%inregs%@AE@% to the
  21434. corresponding registers. After the INT instruction returns, %@AB@%intdos%@AE@% copies
  21435. the current register values to %@AI@%outregs%@AE@%. It also copies the status of the
  21436. system carry flag to the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@%. A nonzero %@AB@%cflag%@AE@% field
  21437. indicates the flag was set by the system call and also indicates an error
  21438. condition.  %@NL@%
  21439. %@NL@%
  21440. The %@AB@%intdos%@AE@% function is used to invoke DOS system calls that take arguments
  21441. for input or output in registers other than DX (DH/DL) and AL. The %@AB@%intdos%@AE@%
  21442. function is also used to invoke system calls that indicate errors by setting
  21443. the carry flag. Under any other conditions, the %@AB@%bdos%@AE@% function can be used.  %@NL@%
  21444. %@NL@%
  21445. Do not use the %@AB@%intdos%@AE@% function to call interrupts that modify the DS
  21446. register. Instead, use the %@AB@%intdosx%@AE@% or %@AB@%int86x%@AE@% function.  %@NL@%
  21447. %@NL@%
  21448. %@NL@%
  21449. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21450. %@NL@%
  21451. The %@AB@%intdos%@AE@% function returns the value of the AX register after the system
  21452. call is completed. If the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@% is nonzero, an error has
  21453. occurred and %@AB@%_doserrno%@AE@% is also set to the corresponding error code.  %@NL@%
  21454. %@NL@%
  21455. %@NL@%
  21456. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21457. %@NL@%
  21458.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  21459. %@NL@%
  21460. %@NL@%
  21461. %@NL@%
  21462. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21463. %@NL@%
  21464. %@AB@%bdos%@AE@%, %@AB@%intdosx%@AE@%  %@NL@%
  21465. %@NL@%
  21466. %@NL@%
  21467. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21468. %@NL@%
  21469. %@AS@%  /* INTDOS.C: This program uses intdos to invoke DOS system call 2AH
  21470. %@AS@%   * (gets the current date).
  21471. %@AS@%   */
  21472. %@AS@%  
  21473. %@AS@%  #include <dos.h>
  21474. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  21475. %@NL@%
  21476. %@AS@%  void main()
  21477. %@AS@%  {
  21478. %@AS@%     union REGS inregs, outregs;
  21479. %@AS@%  
  21480. %@AS@%     inregs.h.ah = 0x2a;           /* DOS Get Date function: */
  21481. %@AS@%     intdos( &inregs, &outregs );
  21482. %@AS@%     printf( "Date: %d/%d/%d\n", outregs.h.dh, outregs.h.dl, outregs.x.cx );
  21483. %@AS@%  }%@AE@%%@NL@%
  21484. %@NL@%
  21485. %@NL@%
  21486. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21487. %@NL@%
  21488. %@AS@%  
  21489. %@AS@%  
  21490. %@AS@%  Date: 6/16/1989%@AE@%%@NL@%
  21491. %@NL@%
  21492. %@NL@%
  21493. %@NL@%
  21494. %@NL@%
  21495. %@QR:intdosx@%%@NL@%
  21496. %@2@%%@CR:C6A01750864 @%%@AB@%intdosx%@AE@%%@EH@%%@NL@%
  21497. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21498. %@NL@%
  21499. %@NL@%
  21500. %@3@%%@AB@%Description%@CR:C6A01750865 @%%@CR:C6A01750866 @% %@CR:C6A01750867 @%%@CR:C6A01750868 @%%@AE@%%@EH@%%@NL@%
  21501. %@NL@%
  21502. Executes the DOS system call; accepts segment-register values.  %@NL@%
  21503. %@NL@%
  21504. %@AS@%  #include <dos.h>%@AE@%%@NL@%
  21505. %@NL@%
  21506. %@AS@%  int intdosx( union REGS *inregs, union REGS *outregs, struct SREGS
  21507. %@AS@%  *segregs );%@AE@%%@NL@%
  21508. %@NL@%
  21509. %@AI@%inregs%@AE@%                            Register values on call
  21510.  
  21511. %@AI@%outregs%@AE@%                           Register values on return
  21512.  
  21513. %@AI@%segregs%@AE@%                           Segment-register values on call
  21514.  
  21515. %@NL@%
  21516. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21517. %@NL@%
  21518. The %@AB@%intdosx%@AE@% function invokes the DOS system call specified by register
  21519. values defined in %@AI@%inregs%@AE@% and returns the results of the system call in
  21520. %@AI@%outregs%@AE@%. Unlike the %@AB@%intdos%@AE@% function, %@AB@%intdosx%@AE@% accepts segment-register values
  21521. in %@AI@%segregs%@AE@%, enabling programs that use large-model data segments or far
  21522. pointers to specify which segment or pointer should be used during the
  21523. system call. The %@AB@%REGS%@AE@% and %@AB@%SREGS%@AE@% types are defined in the include file DOS.H.
  21524. %@NL@%
  21525. %@NL@%
  21526. To invoke a system call, %@AB@%intdosx%@AE@% executes an INT 21H instruction. Before
  21527. executing the instruction, the function copies the contents of %@AI@%inregs%@AE@% and
  21528. %@AI@%segregs%@AE@% to the corresponding registers. Only the DS and ES register values
  21529. in %@AI@%segregs%@AE@% are used. After the INT instruction returns, %@AB@%intdosx%@AE@% copies the
  21530. current register values to %@AI@%outregs%@AE@% and restores DS. It also copies the
  21531. status of the system carry flag to the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@%. A nonzero
  21532. %@AB@%cflag%@AE@% field indicates the flag was set by the system call and also indicates
  21533. an error condition.  %@NL@%
  21534. %@NL@%
  21535. The %@AB@%intdosx%@AE@% function is used to invoke DOS system calls that take an
  21536. argument in the ES register or that take a DS register value different from
  21537. the default data segment.  %@NL@%
  21538. %@NL@%
  21539. Segment values for the %@AI@%segregs%@AE@% argument can be obtained by using either the
  21540. %@AB@%segread %@AE@%function or the %@AB@%FP_SEG%@AE@% macro.  %@NL@%
  21541. %@NL@%
  21542. %@NL@%
  21543. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21544. %@NL@%
  21545. The %@AB@%intdosx%@AE@% function returns the value of the AX register after the system
  21546. call is completed. If the %@AB@%cflag%@AE@% field in %@AI@%outregs%@AE@% is nonzero, an error has
  21547. occurred; in such cases, %@AB@%_doserrno%@AE@% is also set to the corresponding error
  21548. code.  %@NL@%
  21549. %@NL@%
  21550. %@NL@%
  21551. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21552. %@NL@%
  21553.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  21554. %@NL@%
  21555. %@NL@%
  21556. %@NL@%
  21557. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21558. %@NL@%
  21559. %@AB@%bdos%@AE@%, %@AB@%FP_SEG%@AE@%, %@AB@%intdos%@AE@%, %@AB@%segread%@AE@%  %@NL@%
  21560. %@NL@%
  21561. %@NL@%
  21562. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21563. %@NL@%
  21564. %@AS@%  /* INTDOSX.C */
  21565. %@AS@%  #include <dos.h>
  21566. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  21567. %@NL@%
  21568. %@AS@%  char _far *buffer = "Dollar-sign terminated string\n\r\n\r$";
  21569. %@AS@%  
  21570. %@AS@%  void main()
  21571. %@AS@%  {
  21572. %@AS@%     union  REGS inregs, outregs;
  21573. %@AS@%     struct SREGS segregs;
  21574. %@AS@%  
  21575. %@AS@%     /* Print a $-terminated string on the screen using DOS function 0x09.
  21576. %@AS@%*/
  21577. %@AS@%     inregs.h.ah = 0x9;
  21578. %@AS@%     inregs.x.dx = FP_OFF( buffer );
  21579. %@AS@%     segregs.ds  = FP_SEG( buffer );
  21580. %@AS@%     intdosx( &inregs, &outregs, &segregs );
  21581. %@AS@%  }%@AE@%%@NL@%
  21582. %@NL@%
  21583. %@NL@%
  21584. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21585. %@NL@%
  21586. %@AS@%  
  21587. %@AS@%  
  21588. %@AS@%  Dollar-sign terminated string%@AE@%%@NL@%
  21589. %@NL@%
  21590. %@NL@%
  21591. %@NL@%
  21592. %@NL@%
  21593. %@QR:is@%%@NL@%
  21594. %@2@%%@CR:C6A01760869 @%%@AB@%is Functions%@AE@%%@EH@%%@NL@%
  21595. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21596. %@NL@%
  21597. %@NL@%
  21598. %@3@%%@AB@%Description%@CR:C6A01760870 @%%@CR:C6A01760871 @% %@CR:C6A01760872 @% %@CR:C6A01760873 @%%@CR:C6A01760874 @%%@CR:C6A01760875 @%%@CR:C6A01760876 @% %@CR:C6A01760877 @%%@CR:C6A01760878 @% %@CR:C6A01760879 @% %@CR:C6A01760880 @% %@EH@%
  21599. %@AB@%%@CR:C6A01760881 @% %@CR:C6A01760882 @% %@CR:C6A01760883 @% %@CR:C6A01760884 @% %@CR:C6A01760885 @%%@CR:C6A01760886 @%%@AE@%%@NL@%
  21600. %@NL@%
  21601. Test characters for specified conditions.  %@NL@%
  21602. %@NL@%
  21603. %@AS@%  #include <ctype.h>%@AE@%%@NL@%
  21604. %@NL@%
  21605. %@AS@%  int isalnum( int c );%@AE@%%@NL@%
  21606. %@NL@%
  21607. %@AS@%  int isalpha( int c );%@AE@%%@NL@%
  21608. %@NL@%
  21609. %@AS@%  int isascii( int c );%@AE@%%@NL@%
  21610. %@NL@%
  21611. %@AS@%  int iscntrl( int c );%@AE@%%@NL@%
  21612. %@NL@%
  21613. %@AS@%  int isdigit( int c );%@AE@%%@NL@%
  21614. %@NL@%
  21615. %@AS@%  int isgraph( int c );%@AE@%%@NL@%
  21616. %@NL@%
  21617. %@AS@%  int islower( int c );%@AE@%%@NL@%
  21618. %@NL@%
  21619. %@AS@%  int isprint( int c );%@AE@%%@NL@%
  21620. %@NL@%
  21621. %@AS@%  int ispunct( int c );%@AE@%%@NL@%
  21622. %@NL@%
  21623. %@AS@%  int isspace( int c );%@AE@%%@NL@%
  21624. %@NL@%
  21625. %@AS@%  int isupper( int c );%@AE@%%@NL@%
  21626. %@NL@%
  21627. %@AS@%  int isxdigit( int c );%@AE@%%@NL@%
  21628. %@NL@%
  21629. %@AI@%c%@AE@%                                 Integer to be tested
  21630.  
  21631. %@NL@%
  21632. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21633. %@NL@%
  21634. Each function in the %@AB@%is%@AE@% family tests a given integer value, returning a
  21635. nonzero value if the integer satisfies the test condition and 0 if it does
  21636. not. The ASCII character set is assumed.  %@NL@%
  21637. %@NL@%
  21638. The %@AB@%is%@AE@% functions and their test conditions are listed below:  %@NL@%
  21639. %@NL@%
  21640. %@AB@%Function%@AE@%                          %@AB@%Test Condition%@AE@%
  21641. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21642. %@AB@%isalnum%@AE@%                           Alphanumeric ('A'-'Z', 'a'-'z', or 
  21643.                                   '0'-'9')
  21644.  
  21645. %@AB@%isalpha%@AE@%                           Letter ('A'-'Z' or 'a'-'z')
  21646.  
  21647. %@AB@%isascii%@AE@%                           ASCII character (0x00 - 0x7F)
  21648.  
  21649. %@AB@%iscntrl%@AE@%                           Control character (0x00 - 0x1F or 0x7F)
  21650.  
  21651. %@AB@%isdigit%@AE@%                           Digit ('0'-'9')
  21652.  
  21653. %@AB@%isgraph%@AE@%                           Printable character except space (' ')
  21654.  
  21655. %@AB@%islower%@AE@%                           Lowercase letter ('a'-'z')
  21656.  
  21657. %@AB@%isprint%@AE@%                           Printable character (0x20 - 0x7E)
  21658.  
  21659. %@AB@%ispunct%@AE@%                           Punctuation character
  21660.  
  21661. %@AB@%isspace%@AE@%                           White-space character (0x09 - 0x0D or 
  21662.                                   0x20)
  21663.  
  21664. %@AB@%isupper%@AE@%                           Uppercase letter ('A'-'Z')
  21665.  
  21666. %@AB@%isxdigit%@AE@%                          Hexadecimal digit ('A'-'F','a'-'f', or 
  21667.                                   '0'-'9')
  21668.  
  21669. The %@AB@%isascii%@AE@% routine produces meaningful results for all integer values.
  21670. However, the remaining routines produce a defined result only for integer
  21671. values corresponding to the ASCII character set (that is, only where %@AB@%isascii%@AE@%
  21672. holds true) or for the non-ASCII value %@AB@%EOF%@AE@% (defined in STDIO.H).  %@NL@%
  21673. %@NL@%
  21674. These routines are implemented both as functions and as macros. For details
  21675. on choosing a function or a macro implementation, see Section 1.4, "Choosing
  21676. Between Functions and Macros."  %@NL@%
  21677. %@NL@%
  21678. %@NL@%
  21679. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21680. %@NL@%
  21681. These routines return a nonzero value if the integer satisfies the test
  21682. condition and 0 if it does not.  %@NL@%
  21683. %@NL@%
  21684. %@NL@%
  21685. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21686. %@NL@%
  21687. %@AB@%isalnum%@AE@%,%@AB@% isalpha%@AE@%, %@AB@%iscntrl%@AE@%, %@AB@%isdigit%@AE@%, %@AB@%isgraph%@AE@%, %@AB@%islower%@AE@%, %@AB@%isprint%@AE@%, %@AB@%ispunct%@AE@%,
  21688. %@AB@%isspace%@AE@%, %@AB@%isupper%@AE@%, %@AB@%isxdigit%@AE@%  %@NL@%
  21689. %@NL@%
  21690. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  21691. %@NL@%
  21692. %@NL@%
  21693. %@AB@%isascii%@AE@%  %@NL@%
  21694. %@NL@%
  21695.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  21696. %@NL@%
  21697. %@NL@%
  21698. %@NL@%
  21699. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21700. %@NL@%
  21701. %@AB@%toascii%@AE@%, %@AB@%tolower%@AE@%,%@AB@% toupper %@AE@%functions%@AB@%  %@AE@%%@NL@%
  21702. %@NL@%
  21703. %@NL@%
  21704. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21705. %@NL@%
  21706. %@AS@%  /* ISFAM.C: This program tests all characters between 0x0 and 0x7F,
  21707. %@AS@%   * then displays each character with abbreviations for the character-type
  21708. %@AS@%   * codes that apply.
  21709. %@AS@%   */
  21710. %@AS@%  
  21711. %@AS@%  #include <stdio.h>
  21712. %@AS@%  #include <ctype.h>%@AE@%%@NL@%
  21713. %@NL@%
  21714. %@AS@%  void main()
  21715. %@AS@%  {
  21716. %@AS@%     int ch;
  21717. %@AS@%     for( ch = 0; ch <= 0x7F; ch++ )
  21718. %@AS@%     {
  21719. %@AS@%        printf( "%.2x ", ch );
  21720. %@AS@%        printf( " %c", isprint( ch )  ? ch   : '\0' );
  21721. %@AS@%        printf( "%4s", isalnum( ch )  ? "AN" : "" );
  21722. %@AS@%        printf( "%3s", isalpha( ch )  ? "A"  : "" );
  21723. %@AS@%        printf( "%3s", isascii( ch )  ? "AS" : "" );
  21724. %@AS@%        printf( "%3s", iscntrl( ch )  ? "C"  : "" );
  21725. %@AS@%        printf( "%3s", isdigit( ch )  ? "D"  : "" );
  21726. %@AS@%        printf( "%3s", isgraph( ch )  ? "G"  : "" );
  21727. %@AS@%        printf( "%3s", islower( ch )  ? "L"  : "" );
  21728. %@AS@%        printf( "%3s", ispunct( ch )  ? "PU" : "" );
  21729. %@AS@%        printf( "%3s", isspace( ch )  ? "S"  : "" );
  21730. %@AS@%        printf( "%3s", isprint( ch )  ? "PR" : "" );
  21731. %@AS@%        printf( "%3s", isupper( ch )  ? "U"  : "" );
  21732. %@AS@%        printf( "%3s", isxdigit( ch ) ? "X"  : "" );
  21733. %@AS@%        printf( "\n" );
  21734. %@AS@%     }
  21735. %@AS@%  }%@AE@%%@NL@%
  21736. %@NL@%
  21737. %@NL@%
  21738. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21739. %@NL@%
  21740. %@AS@%  
  21741. %@AS@%  
  21742. %@AS@%  00          AS  C
  21743. %@AS@%  01          AS  C
  21744. %@AS@%  02          AS  C
  21745. %@AS@%  .
  21746. %@AS@%  .
  21747. %@AS@%  .
  21748. %@AS@%  38  8  AN    AS     D  G          PR     X
  21749. %@AS@%  39  9  AN    AS     D  G          PR     X
  21750. %@AS@%  3a  :        AS        G    PU    PR
  21751. %@AS@%  3b  ;        AS        G    PU    PR
  21752. %@AS@%  3c  <        AS        G    PU    PR
  21753. %@AS@%  3d  =        AS        G    PU    PR
  21754. %@AS@%  3e  >        AS        G    PU    PR
  21755. %@AS@%  3f  ?        AS        G    PU    PR
  21756. %@AS@%  40  @        AS        G    PU    PR
  21757. %@AS@%  41  A  AN  A AS        G          PR  U  X
  21758. %@AS@%  42  B  AN  A AS        G          PR  U  X
  21759. %@AS@%  .
  21760. %@AS@%  .
  21761. %@AS@%  .%@AE@%%@NL@%
  21762. %@NL@%
  21763. %@NL@%
  21764. %@NL@%
  21765. %@NL@%
  21766. %@QR:isatty@%%@NL@%
  21767. %@2@%%@CR:C6A01770887 @%%@AB@%isatty%@AE@%%@EH@%%@NL@%
  21768. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21769. %@NL@%
  21770. %@NL@%
  21771. %@3@%%@AB@%Description%@CR:C6A01770888 @%%@CR:C6A01770889 @%%@CR:C6A01770890 @% %@CR:C6A01770891 @%%@AE@%%@EH@%%@NL@%
  21772. %@NL@%
  21773. Checks for a character device.  %@NL@%
  21774. %@NL@%
  21775. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  21776.  
  21777. %@AS@%  int isatty( int handle );%@AE@%%@NL@%
  21778. %@NL@%
  21779. %@AI@%handle%@AE@%                            Handle referring to device to be tested
  21780.  
  21781. %@NL@%
  21782. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21783. %@NL@%
  21784. The %@AB@%isatty%@AE@% function determines whether %@AI@%handle%@AE@% is associated with a character
  21785. device (a terminal, console, printer, or serial port).  %@NL@%
  21786. %@NL@%
  21787. %@NL@%
  21788. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21789. %@NL@%
  21790. The %@AB@%isatty%@AE@% function returns a nonzero value if the device is a character
  21791. device. Otherwise, the return value is 0.  %@NL@%
  21792. %@NL@%
  21793. %@NL@%
  21794. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21795. %@NL@%
  21796.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  21797. %@NL@%
  21798. %@NL@%
  21799. %@NL@%
  21800. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21801. %@NL@%
  21802. %@AS@%  /* ISATTY.C: This program checks to see whether stdout has been
  21803. %@AS@%   * redirected to a file.
  21804. %@AS@%   */
  21805. %@AS@%  
  21806. %@AS@%  #include <stdio.h>
  21807. %@AS@%  #include <io.h>
  21808. %@AS@%  
  21809. %@AS@%  void main()
  21810. %@AS@%  {
  21811. %@AS@%     if( isatty( fileno( stdout ) ) )
  21812. %@AS@%        printf( "stdout has not been redirected to a file\n" );
  21813. %@AS@%     else
  21814. %@AS@%        printf( "stdout has been redirected to a file\n");
  21815. %@AS@%  }%@AE@%%@NL@%
  21816. %@NL@%
  21817. %@NL@%
  21818. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21819. %@NL@%
  21820. %@AS@%  
  21821. %@AS@%  
  21822. %@AS@%  stdout has not been redirected to a file%@AE@%%@NL@%
  21823. %@NL@%
  21824. %@NL@%
  21825. %@NL@%
  21826. %@NL@%
  21827. %@QR:itoa@%%@NL@%
  21828. %@2@%%@CR:C6A01780892 @%%@AB@%itoa%@AE@%%@EH@%%@NL@%
  21829. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21830. %@NL@%
  21831. %@NL@%
  21832. %@3@%%@AB@%Description%@CR:C6A01780893 @%%@CR:C6A01780894 @% %@CR:C6A01780895 @%%@CR:C6A01780896 @%%@AE@%%@EH@%%@NL@%
  21833. %@NL@%
  21834. Converts an integer to a string.  %@NL@%
  21835. %@NL@%
  21836. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  21837.  
  21838. %@AS@%  char *itoa( int value, char *string, int radix );%@AE@%%@NL@%
  21839. %@NL@%
  21840. %@AI@%value%@AE@%                             Number to be converted
  21841.  
  21842. %@AI@%string%@AE@%                            String result
  21843.  
  21844. %@AI@%radix%@AE@%                             Base of %@AI@%value%@AE@%
  21845.  
  21846. %@NL@%
  21847. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21848. %@NL@%
  21849. The %@AB@%itoa%@AE@% function converts the digits of the given %@AI@%value%@AE@% argument to a
  21850. null-terminated character string and stores the result (up to 17 bytes) in
  21851. %@AI@%string.%@AE@% The %@AI@%radix%@AE@% argument specifies the base of %@AI@%value%@AE@%; it must be in the
  21852. range 2-36. If %@AI@%radix%@AE@% equals 10 and %@AI@%value%@AE@% is negative, the first character of
  21853. the stored string is the minus sign (-).  %@NL@%
  21854. %@NL@%
  21855. %@NL@%
  21856. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21857. %@NL@%
  21858. The %@AB@%itoa%@AE@% function returns a pointer to %@AI@%string%@AE@%. There is no error return.  %@NL@%
  21859. %@NL@%
  21860. %@NL@%
  21861. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21862. %@NL@%
  21863.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  21864. %@NL@%
  21865. %@NL@%
  21866. %@NL@%
  21867. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  21868. %@NL@%
  21869. %@AB@%ltoa%@AE@%, %@AB@%ultoa%@AE@%  %@NL@%
  21870. %@NL@%
  21871. %@NL@%
  21872. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21873. %@NL@%
  21874. %@AS@%  /* ITOA.C: This program converts integers of various sizes to strings
  21875. %@AS@%   * in various radixes.
  21876. %@AS@%   */
  21877. %@AS@%  
  21878. %@AS@%  #include <stdlib.h>
  21879. %@AS@%  #include <stdio.h>
  21880. %@AS@%  
  21881. %@AS@%  void main()
  21882. %@AS@%  {
  21883. %@AS@%     char buffer[20];
  21884. %@AS@%     int  i = 3445;
  21885. %@AS@%     long l = -344115L;
  21886. %@AS@%     unsigned long ul = 1234567890UL;%@AE@%%@NL@%
  21887. %@NL@%
  21888. %@AS@%  itoa( i, buffer, 10 );
  21889. %@AS@%     printf( "String of integer %d (radix 10): %s\n", i, buffer );
  21890. %@AS@%     itoa( i, buffer, 16 );
  21891. %@AS@%     printf( "String of integer %d (radix 16): 0x%s\n", i, buffer );
  21892. %@AS@%     itoa( i, buffer, 2  );
  21893. %@AS@%     printf( "String of integer %d (radix 2): %s\n", i, buffer );
  21894. %@AS@%  
  21895. %@AS@%     ltoa( l, buffer, 16 );
  21896. %@AS@%     printf( "String of long int %ld (radix 16): 0x%s\n", l, buffer );
  21897. %@AS@%  
  21898. %@AS@%     ultoa( ul, buffer, 16 );
  21899. %@AS@%     printf( "String of unsigned long %lu (radix 16): 0x%s\n", ul, buffer );
  21900. %@AS@%  }%@AE@%%@NL@%
  21901. %@NL@%
  21902. %@NL@%
  21903. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21904. %@NL@%
  21905. %@AS@%  
  21906. %@AS@%  
  21907. %@AS@%  String of integer 3445 (radix 10): 3445
  21908. %@AS@%  String of integer 3445 (radix 16): 0xd75
  21909. %@AS@%  String of integer 3445 (radix 2): 110101110101
  21910. %@AS@%  String of long int -344115 (radix 16): 0xfffabfcd
  21911. %@AS@%  String of unsigned long 1234567890 (radix 16): 0x499602d2%@AE@%%@NL@%
  21912. %@NL@%
  21913. %@NL@%
  21914. %@NL@%
  21915. %@NL@%
  21916. %@QR:kbhit@%%@NL@%
  21917. %@2@%%@CR:C6A01790897 @%%@AB@%kbhit%@AE@%%@EH@%%@NL@%
  21918. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21919. %@NL@%
  21920. %@NL@%
  21921. %@3@%%@AB@%Description %@CR:C6A01790898 @%%@CR:C6A01790899 @% %@CR:C6A01790900 @% %@CR:C6A01790901 @%%@AE@%%@EH@%%@NL@%
  21922. %@NL@%
  21923. Checks the console for keyboard input.  %@NL@%
  21924. %@NL@%
  21925. %@AB@%#include <conio.h>%@AE@%                Required only for function declarations
  21926.  
  21927. %@AS@%  int kbhit( void );%@AE@%%@NL@%
  21928. %@NL@%
  21929. %@NL@%
  21930. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  21931. %@NL@%
  21932. The %@AB@%kbhit%@AE@% function checks the console for a recent keystroke. If the
  21933. function returns a nonzero value, a keystroke is waiting in the buffer. The
  21934. program can then call %@AB@%getch%@AE@% or %@AB@%getche%@AE@% to get the keystroke.  %@NL@%
  21935. %@NL@%
  21936. %@NL@%
  21937. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  21938. %@NL@%
  21939. The %@AB@%kbhit%@AE@% function returns a nonzero value if a key has been pressed.
  21940. Otherwise, it re-turns 0.  %@NL@%
  21941. %@NL@%
  21942. %@NL@%
  21943. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  21944. %@NL@%
  21945.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  21946. %@NL@%
  21947. %@NL@%
  21948. %@NL@%
  21949. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  21950. %@NL@%
  21951. %@AS@%  /* KBHIT.C: This program loops until the user presses a key.
  21952. %@AS@%   * If kbhit returns nonzero, a keystroke is waiting in the buffer.
  21953. %@AS@%   * The program can call getch or getche to get the keystroke.
  21954. %@AS@%   */
  21955. %@AS@%  
  21956. %@AS@%  #include <conio.h>
  21957. %@AS@%  #include <stdio.h>
  21958. %@AS@%  
  21959. %@AS@%  void main()
  21960. %@AS@%  {
  21961. %@AS@%     /* Display message until key is pressed. */
  21962. %@AS@%     while( !kbhit() )
  21963. %@AS@%        cputs( "Hit me!! " );
  21964. %@AS@%  
  21965. %@AS@%     /* Use getch to throw key away. */
  21966. %@AS@%     printf( "\nKey struck was '%c'\n", getch() );
  21967. %@AS@%     getch();
  21968. %@AS@%  }%@AE@%%@NL@%
  21969. %@NL@%
  21970. %@NL@%
  21971. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  21972. %@NL@%
  21973. %@AS@%  
  21974. %@AS@%  
  21975. %@AS@%  Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!!
  21976. %@AS@%  Key struck was 'k'%@AE@%%@NL@%
  21977. %@NL@%
  21978. %@NL@%
  21979. %@NL@%
  21980. %@NL@%
  21981. %@QR:labs@%%@NL@%
  21982. %@2@%%@CR:C6A01800902 @%%@AB@%labs%@AE@%%@EH@%%@NL@%
  21983. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  21984. %@NL@%
  21985. %@NL@%
  21986. %@3@%%@AB@%Description%@CR:C6A01800903 @%%@CR:C6A01800904 @%%@AE@%%@EH@%%@NL@%
  21987. %@NL@%
  21988. Calculates the absolute value of a long integer.  %@NL@%
  21989. %@NL@%
  21990. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  21991.  
  21992. %@AB@%#include <math.h>%@AE@%                 
  21993.  
  21994. %@AS@%  long labs( long n );%@AE@%%@NL@%
  21995. %@NL@%
  21996. %@AI@%n%@AE@%                                 Long-integer value
  21997.  
  21998. %@NL@%
  21999. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22000. %@NL@%
  22001. The %@AB@%labs%@AE@% function produces the absolute value of its long-integer argument
  22002. %@AI@%n%@AE@%.  %@NL@%
  22003. %@NL@%
  22004. %@NL@%
  22005. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22006. %@NL@%
  22007. The %@AB@%labs%@AE@% function returns the absolute value of its argument. There is no
  22008. error return.  %@NL@%
  22009. %@NL@%
  22010. %@NL@%
  22011. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22012. %@NL@%
  22013. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  22014. %@NL@%
  22015. %@NL@%
  22016. %@NL@%
  22017. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22018. %@NL@%
  22019. %@AB@%abs%@AE@%, %@AB@%cabs%@AE@%, %@AB@%fabs%@AE@%  %@NL@%
  22020. %@NL@%
  22021. %@NL@%
  22022. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22023. %@NL@%
  22024. %@AS@%  /* ABS.C: This program computes and displays the absolute values of
  22025. %@AS@%   * several numbers.
  22026. %@AS@%   */
  22027. %@AS@%  
  22028. %@AS@%  #include <stdio.h>
  22029. %@AS@%  #include <math.h>
  22030. %@AS@%  #include <stdlib.h>
  22031. %@AS@%  
  22032. %@AS@%  void main()
  22033. %@AS@%  {
  22034. %@AS@%     int    ix = -4, iy;
  22035. %@AS@%     long   lx = -41567L, ly;
  22036. %@AS@%     double dx = -3.141593, dy;
  22037. %@AS@%  
  22038. %@AS@%     iy = abs( ix );
  22039. %@AS@%     printf( "The absolute value of %d is %d\n", ix, iy);
  22040. %@AS@%  
  22041. %@AS@%     ly = labs( lx );
  22042. %@AS@%     printf( "The absolute value of %ld is %ld\n", lx, ly);
  22043. %@AS@%  
  22044. %@AS@%     dy = fabs( dx );
  22045. %@AS@%     printf( "The absolute value of %f is %f\n", dx, dy );
  22046. %@AS@%  }%@AE@%%@NL@%
  22047. %@NL@%
  22048. %@NL@%
  22049. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22050. %@NL@%
  22051. %@AS@%  
  22052. %@AS@%  
  22053. %@AS@%  The absolute value of -4 is 4
  22054. %@AS@%  The absolute value of -41567 is 41567
  22055. %@AS@%  The absolute value of -3.141593 is 3.141593%@AE@%%@NL@%
  22056. %@NL@%
  22057. %@NL@%
  22058. %@NL@%
  22059. %@NL@%
  22060. %@QR:ldexp@%%@QR:ldexpl@%%@NL@%
  22061. %@2@%%@CR:C6A01810905 @%%@AB@%ldexp, ldexpl%@AE@%%@EH@%%@NL@%
  22062. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22063. %@NL@%
  22064. %@NL@%
  22065. %@3@%%@AB@%Description%@CR:C6A01810906 @%%@CR:C6A01810907 @%%@CR:C6A01810908 @% %@CR:C6A01810909 @%%@AE@%%@EH@%%@NL@%
  22066. %@NL@%
  22067. Compute a real number from the mantissa and exponent.  %@NL@%
  22068. %@NL@%
  22069. %@AS@%  #include <math.h>%@AE@%%@NL@%
  22070. %@NL@%
  22071. %@AS@%  double ldexp( double x, int exp );%@AE@%%@NL@%
  22072. %@NL@%
  22073. %@AS@%  long double ldexpl( long double x, int exp );%@AE@%%@NL@%
  22074. %@NL@%
  22075. %@AI@%x%@AE@%                                 Floating-point value
  22076.  
  22077. %@AI@%exp%@AE@%                               Integer exponent
  22078.  
  22079. %@NL@%
  22080. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22081. %@NL@%
  22082. The %@AB@%ldexp%@AE@% and %@AB@%ldexpl%@AE@% functions calculate the value of %@AI@%x%@AE@% * 2exp.  %@NL@%
  22083. %@NL@%
  22084. %@NL@%
  22085. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22086. %@NL@%
  22087. The %@AB@%ldexp%@AE@% and %@AB@%ldexpl%@AE@% functions return %@AI@%x *%@AE@% 2exp. If an overflow results, the
  22088. functions return ± HUGE_VAL (depending on the sign of %@AI@%x%@AE@%) and set%@AB@% errno%@AE@% to
  22089. %@AB@%ERANGE%@AE@%.  %@NL@%
  22090. %@NL@%
  22091. The %@AB@%ldexpl %@AE@%function uses the 80-bit, 10-byte coprocessor form of arguments
  22092. and return values. See the reference page on the long double functions for
  22093. more details on this data type. %@AB@%  %@AE@%%@NL@%
  22094. %@NL@%
  22095. %@NL@%
  22096. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22097. %@NL@%
  22098. %@AB@%ldexp%@AE@%  %@NL@%
  22099. %@NL@%
  22100. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  22101. %@NL@%
  22102. %@NL@%
  22103. %@AB@%ldexpl%@AE@%  %@NL@%
  22104. %@NL@%
  22105.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  22106. %@NL@%
  22107. %@NL@%
  22108. %@NL@%
  22109. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22110. %@NL@%
  22111. %@AB@%frexp%@AE@%, %@AB@%modf%@AE@%  %@NL@%
  22112. %@NL@%
  22113. %@NL@%
  22114. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22115. %@NL@%
  22116. %@AS@%  /* LDEXP.C */
  22117. %@AS@%  #include <math.h>
  22118. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  22119. %@NL@%
  22120. %@AS@%  void main()
  22121. %@AS@%  {
  22122. %@AS@%     double x = 4.0, y;
  22123. %@AS@%     int p = 3;
  22124. %@AS@%  
  22125. %@AS@%     y = ldexp( x, p );
  22126. %@AS@%     printf( "%2.1f times two to the power of %d is %2.1f\n", x, p, y );
  22127. %@AS@%  }%@AE@%%@NL@%
  22128. %@NL@%
  22129. %@NL@%
  22130. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22131. %@NL@%
  22132. %@AS@%  
  22133. %@AS@%  
  22134. %@AS@%  4.0 times two to the power of 3 is 32.0 %@AE@%%@NL@%
  22135. %@NL@%
  22136. %@NL@%
  22137. %@NL@%
  22138. %@NL@%
  22139. %@QR:ldiv@%%@NL@%
  22140. %@2@%%@CR:C6A01820910 @%%@AB@%ldiv%@AE@%%@EH@%%@NL@%
  22141. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22142. %@NL@%
  22143. %@NL@%
  22144. %@3@%%@AB@%Description%@CR:C6A01820911 @%%@CR:C6A01820912 @%%@AE@%%@EH@%%@NL@%
  22145. %@NL@%
  22146. Computes the quotient and remainder of a long integer.  %@NL@%
  22147. %@NL@%
  22148. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  22149. %@NL@%
  22150. %@AS@%  ldiv_t ldiv ( long int numer, long int denom );%@AE@%%@NL@%
  22151. %@NL@%
  22152. %@AI@%numer%@AE@%                             Numerator
  22153.  
  22154. %@AI@%denom%@AE@%                             Denominator
  22155.  
  22156. %@NL@%
  22157. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22158. %@NL@%
  22159. The %@AB@%ldiv%@AE@% function divides %@AI@%numer%@AE@% by %@AI@%denom%@AE@%, computing the quotient and the
  22160. remainder. The sign of the quotient is the same as that of the mathematical
  22161. quotient. Its absolute value is the largest integer that is less than the
  22162. absolute value of the mathematical quotient. If the denominator is 0, the
  22163. program will terminate with an error message.  %@NL@%
  22164. %@NL@%
  22165. The %@AB@%ldiv%@AE@% function is similar to the %@AB@%div%@AE@% function, with the difference being
  22166. that the arguments and the members of the returned structure are all of type
  22167. %@AB@%long int%@AE@%.  %@NL@%
  22168. %@NL@%
  22169. The %@AB@%ldiv_t%@AE@% structure, defined in STDLIB.H, contains the following elements:
  22170. %@NL@%
  22171. %@NL@%
  22172. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  22173. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22174. %@AB@%long int quot%@AE@%                     Quotient
  22175.  
  22176. %@AB@%long int rem%@AE@%                      Remainder
  22177.  
  22178. %@NL@%
  22179. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22180. %@NL@%
  22181. The %@AB@%ldiv%@AE@% function returns a structure of type %@AB@%ldiv_t%@AE@%, comprising both the
  22182. quotient and the remainder.  %@NL@%
  22183. %@NL@%
  22184. %@NL@%
  22185. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22186. %@NL@%
  22187. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  22188. %@NL@%
  22189. %@NL@%
  22190. %@NL@%
  22191. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22192. %@NL@%
  22193. %@AB@%div%@AE@%  %@NL@%
  22194. %@NL@%
  22195. %@NL@%
  22196. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22197. %@NL@%
  22198. %@AS@%  /* LDIV.C: This program takes two long integers as command-line
  22199. %@AS@%   * arguments and displays the results of the integer division.
  22200. %@AS@%   */
  22201. %@AS@%  
  22202. %@AS@%  #include <stdlib.h>
  22203. %@AS@%  #include <math.h>
  22204. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  22205. %@NL@%
  22206. %@AS@%  void main()
  22207. %@AS@%  {
  22208. %@AS@%     long x = 5149627, y = 234879;
  22209. %@AS@%     ldiv_t div_result;
  22210. %@AS@%  
  22211. %@AS@%     div_result = ldiv( x, y );
  22212. %@AS@%     printf( "For %ld / %ld, the quotient is %ld, and the remainder is
  22213. %@AS@%%ld\n",
  22214. %@AS@%             x, y, div_result.quot, div_result.rem );
  22215. %@AS@%  }%@AE@%%@NL@%
  22216. %@NL@%
  22217. %@NL@%
  22218. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22219. %@NL@%
  22220. %@AS@%  
  22221. %@AS@%  
  22222. %@AS@%  For 5149627 / 234879, the quotient is 21, and the remainder is 217168%@AE@%%@NL@%
  22223. %@NL@%
  22224. %@NL@%
  22225. %@NL@%
  22226. %@NL@%
  22227. %@QR:lfind@%%@NL@%
  22228. %@2@%%@CR:C6A01830913 @%%@AB@%lfind%@AE@%%@EH@%%@NL@%
  22229. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22230. %@NL@%
  22231. %@NL@%
  22232. %@3@%%@AB@%Description%@CR:C6A01830914 @%%@CR:C6A01830915 @%%@CR:C6A01830916 @%%@AE@%%@EH@%%@NL@%
  22233. %@NL@%
  22234. Performs a linear search for the specified key.  %@NL@%
  22235. %@NL@%
  22236. %@AB@%#include <search.h>%@AE@%               Required only for function declarations
  22237.  
  22238. %@AS@%  char *lfind( const void *key, const void *base, unsigned int *num,
  22239. %@AS@%  unsigned int width, 
  22240. %@AS@%  int ( *compare )( const void *elem1, const void *elem2 ) );%@AE@%%@NL@%
  22241. %@NL@%
  22242. %@AI@%key%@AE@%                               Object to search for
  22243.  
  22244. %@AI@%base%@AE@%                              Pointer to base of search data
  22245.  
  22246. %@AI@%num%@AE@%                               Number of array elements
  22247.  
  22248. %@AI@%width%@AE@%                             Width of array elements
  22249.  
  22250. %@AI@%compare%@AE@%%@AB@%(%@AE@% %@AB@%)%@AE@%                        Pointer to comparison routine
  22251.  
  22252. %@AI@%elem1%@AE@%                             Pointer to the key for the search
  22253.  
  22254. %@AI@%elem2%@AE@%                             Pointer to the array element to be 
  22255.                                   compared with the key
  22256.  
  22257. %@NL@%
  22258. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22259. %@NL@%
  22260. The %@AB@%lfind%@AE@% function performs a linear search for the value %@AI@%key%@AE@% in an array of
  22261. %@AI@%num%@AE@% elements; each element is %@AI@%width%@AE@% bytes in size. (Unlike %@AB@%bsearch%@AE@%, %@AB@%lfind%@AE@%
  22262. does not require the array to be sorted.) The%@AI@% base%@AE@% argument is a pointer to
  22263. the base of the array to be searched.  %@NL@%
  22264. %@NL@%
  22265. The%@AI@% compare %@AE@%argument is a pointer to a user-supplied routine that compares
  22266. two array elements and then returns a value specifying their relationship.
  22267. The %@AB@%lfind%@AE@% function calls the %@AI@%compare%@AE@% routine one or more times during the
  22268. search, passing pointers to two array elements on each call. This routine
  22269. must compare the elements, then return one of the following values:  %@NL@%
  22270. %@NL@%
  22271. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  22272. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22273. Nonzero                           Elements are different
  22274.  
  22275. 0                                 Elements are identical
  22276.  
  22277. %@NL@%
  22278. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22279. %@NL@%
  22280. If the key is found, %@AB@%lfind%@AE@% returns a pointer to the element of the array at
  22281. %@AI@%base%@AE@% that matches %@AI@%key%@AE@%. If the key is not found, %@AB@%lfind%@AE@% returns %@AB@%NULL%@AE@%.  %@NL@%
  22282. %@NL@%
  22283. %@NL@%
  22284. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22285. %@NL@%
  22286.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  22287. %@NL@%
  22288. %@NL@%
  22289. %@NL@%
  22290. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22291. %@NL@%
  22292. %@AB@%bsearch%@AE@%, %@AB@%lsearch%@AE@%, %@AB@%qsort%@AE@%  %@NL@%
  22293. %@NL@%
  22294. %@NL@%
  22295. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22296. %@NL@%
  22297. %@AS@%  /* LFIND.C: This program uses lfind to search for the word "hello"
  22298. %@AS@%   * in the command-line arguments.
  22299. %@AS@%   */
  22300. %@AS@%  
  22301. %@AS@%  #include <search.h>
  22302. %@AS@%  #include <string.h>
  22303. %@AS@%  #include <stdio.h>
  22304. %@AS@%  
  22305. %@AS@%  int compare( char **arg1, char **arg2 );
  22306. %@AS@%  
  22307. %@AS@%  void main( int argc, char **argv )
  22308. %@AS@%  {
  22309. %@AS@%     char **result;
  22310. %@AS@%     char *key = "hello";
  22311. %@AS@%  
  22312. %@AS@%     result = (char **)lfind( (char *)&key, (char *)argv,
  22313. %@AS@%                              &argc, sizeof( char * ), compare );
  22314. %@AS@%     if( result )
  22315. %@AS@%        printf( "%s found\n", *result );
  22316. %@AS@%     else
  22317. %@AS@%        printf( "hello not found!\n" );
  22318. %@AS@%  }
  22319. %@AS@%  
  22320. %@AS@%  int compare(char ** arg1, char **arg2 )
  22321. %@AS@%  {
  22322. %@AS@%     return( strcmpi( *arg1, *arg2 ) );
  22323. %@AS@%  }%@AE@%%@NL@%
  22324. %@NL@%
  22325. %@NL@%
  22326. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22327. %@NL@%
  22328. %@NL@%
  22329. %@3@%%@AB@%%@AE@%%@EH@%%@NL@%
  22330. %@NL@%
  22331. %@AS@%  
  22332. %@AS@%  
  22333. %@AS@%  [C:\LIBREF] lfind What if I said Hello world
  22334. %@AS@%  Hello found%@AE@%%@NL@%
  22335. %@NL@%
  22336. %@NL@%
  22337. %@NL@%
  22338. %@NL@%
  22339. %@QR:_lineto@%%@NL@%
  22340. %@2@%%@CR:C6A01840917 @%%@AB@%_lineto Functions%@AE@%%@EH@%%@NL@%
  22341. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22342. %@NL@%
  22343. %@NL@%
  22344. %@3@%%@AB@%Description%@CR:C6A01840918 @%%@CR:C6A01840919 @%%@CR:C6A01840920 @% %@CR:C6A01840921 @%%@AE@%%@EH@%%@NL@%
  22345. %@NL@%
  22346. Draw lines to specified points.  %@NL@%
  22347. %@NL@%
  22348. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  22349. %@NL@%
  22350. %@AS@%  short _far _lineto( short x, short y );%@AE@%%@NL@%
  22351. %@NL@%
  22352. %@AS@%  short _far _lineto_w( double wx, double wy );%@AE@%%@NL@%
  22353. %@NL@%
  22354. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              End point
  22355.  
  22356. %@AI@%wx%@AE@%, %@AI@%wy%@AE@%                            End point
  22357.  
  22358. %@NL@%
  22359. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22360. %@NL@%
  22361. The functions in the %@AB@%_lineto%@AE@% family draw a line from the current graphics
  22362. position up to and including the destination point. The destination point
  22363. for the %@AB@%_lineto%@AE@% function is given by the view-coordinate point (%@AI@%x%@AE@%, %@AI@%y%@AE@%). The
  22364. destination point for the %@AB@%_lineto_w%@AE@% function is given by the
  22365. window-coordinate point (%@AI@%wx%@AE@%, %@AI@%wy%@AE@%).  %@NL@%
  22366. %@NL@%
  22367. The line is drawn using the current color, logical write mode, and line
  22368. style. If no error occurs, %@AB@%_lineto%@AE@% sets the current graphics position to the
  22369. view-coordinate point (%@AI@%x%@AE@%, %@AI@%y%@AE@%); %@AB@%_lineto_w%@AE@% sets the current position to the
  22370. window-coordinate point (%@AI@%wx%@AE@%, %@AI@%wy%@AE@%).  %@NL@%
  22371. %@NL@%
  22372. If you use%@AB@% _floodfill%@AE@% to fill in a closed figure drawn with %@AB@%_lineto%@AE@% calls,
  22373. the figure must be%@AI@% %@AE@%drawn with a solid line-style pattern.%@AI@%  %@AE@%%@NL@%
  22374. %@NL@%
  22375. %@NL@%
  22376. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22377. %@NL@%
  22378. The %@AB@%_lineto%@AE@% and %@AB@%_lineto_w%@AE@% routines return a nonzero value if anything is
  22379. drawn; otherwise, they return 0.  %@NL@%
  22380. %@NL@%
  22381. %@NL@%
  22382. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22383. %@NL@%
  22384.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  22385. %@NL@%
  22386. %@NL@%
  22387. %@NL@%
  22388. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22389. %@NL@%
  22390. %@AB@%_getcurrentposition%@AE@% functions,  %@AB@%_moveto%@AE@% functions,  %@AB@%_setlinestyle%@AE@%  %@NL@%
  22391. %@NL@%
  22392. %@NL@%
  22393. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22394. %@NL@%
  22395. %@AS@%  /* MOVETO.C: This program draws line segments of different colors. */
  22396. %@AS@%  
  22397. %@AS@%  #include <graph.h>
  22398. %@AS@%  #include <stdlib.h>
  22399. %@AS@%  #include <conio.h>%@AE@%%@NL@%
  22400. %@NL@%
  22401. %@AS@%  void main()
  22402. %@AS@%  {
  22403. %@AS@%     short x, y, xinc, yinc, color = 1;
  22404. %@AS@%     struct videoconfig v;
  22405. %@AS@%  
  22406. %@AS@%     /* Find a valid graphics mode. */
  22407. %@AS@%     if( !_setvideomode( _MAXCOLORMODE ) )
  22408. %@AS@%        exit( 1 );
  22409. %@AS@%     _getvideoconfig( &v );
  22410. %@AS@%     xinc = v.numxpixels / 50;
  22411. %@AS@%     yinc = v.numypixels / 50;
  22412. %@AS@%  
  22413. %@AS@%     for( x = 0, y = v.numypixels - 1; x < v.numxpixels; x += xinc, y -=
  22414. %@AS@%yinc )
  22415. %@AS@%     {
  22416. %@AS@%        _setcolor( color++ % 16 );
  22417. %@AS@%        _moveto( x, 0 );
  22418. %@AS@%        _lineto( 0, y );
  22419. %@AS@%     }
  22420. %@AS@%     getch();
  22421. %@AS@%  
  22422. %@AS@%     _setvideomode( _DEFAULTMODE );
  22423. %@AS@%  }%@AE@%%@NL@%
  22424. %@NL@%
  22425. %@NL@%
  22426. %@NL@%
  22427. %@NL@%
  22428. %@QR:localeconv@%%@NL@%
  22429. %@2@%%@CR:C6A01850922 @%%@AB@%localeconv%@AE@%%@EH@%%@NL@%
  22430. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22431. %@NL@%
  22432. %@NL@%
  22433. %@3@%%@AB@%Description%@CR:C6A01850923 @%%@CR:C6A01850924 @%%@AE@%%@EH@%%@NL@%
  22434. %@NL@%
  22435. Gets detailed information on locale settings.  %@NL@%
  22436. %@NL@%
  22437. %@AS@%  #include <locale.h>%@AE@%%@NL@%
  22438. %@NL@%
  22439. %@AS@%  struct lconv *localeconv( void );%@AE@%%@NL@%
  22440. %@NL@%
  22441. %@NL@%
  22442. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22443. %@NL@%
  22444. The %@AB@%localeconv%@AE@% function gets detailed information on the locale-specific
  22445. settings for numeric formatting of the program's current locale. This
  22446. information is stored in a structure of type %@AB@%lconv%@AE@%.  %@NL@%
  22447. %@NL@%
  22448. The %@AB@%lconv%@AE@% structure, defined in LOCALE.H, contains the following elements:  %@NL@%
  22449. %@NL@%
  22450. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  22451. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22452. %@AB@%char *decimal_point%@AE@%               Decimal-point character for nonmonetary 
  22453.                                   quantities.
  22454.  
  22455. %@AB@%char *thousands_sep%@AE@%               Character used to separate groups of 
  22456.                                   digits to the left of the decimal point 
  22457.                                   for non-monetary quantities.
  22458.  
  22459. %@AB@%char *grouping%@AE@%                    Size of each group of digits in 
  22460.                                   non-monetary quantities.
  22461.  
  22462. %@AB@%char *int_curr_symbol%@AE@%             International currency symbol for the 
  22463.                                   current locale. The first three 
  22464.                                   characters specify the alphabetic 
  22465.                                   international currency symbol as defined
  22466.                                   in the %@AI@%ISO 4217 Codes for the %@AE@%
  22467.                                   %@AI@%Representation of Currency and Funds%@AE@% 
  22468.                                   standard. The fourth character 
  22469.                                   (immediately preceding the null 
  22470.                                   character) is used to separate the 
  22471.                                   international currency symbol from the 
  22472.                                   monetary quantity.
  22473.  
  22474. %@AB@%char *currency_symbol%@AE@%             Local currency symbol for the current
  22475.                                   locale.
  22476.  
  22477. %@AB@%char *mon_decimal_point%@AE@%           Decimal-point character for monetary 
  22478.                                   quantities.
  22479.  
  22480. %@AB@%char *mon_thousands_sep%@AE@%           Separator for groups of digits to the 
  22481.                                   left of the decimal place in monetary 
  22482.                                   quantities.
  22483.  
  22484. %@AB@%char *mon_grouping%@AE@%                Size of each group of digits in monetary
  22485.                                   quantities.
  22486.  
  22487. %@AB@%char *positive_sign%@AE@%               String denoting sign for nonnegative 
  22488.                                   monetary quantities.
  22489.  
  22490. %@AB@%char *negative_sign%@AE@%               String denoting sign for negative 
  22491.                                   monetary
  22492.                                   quantities.
  22493.  
  22494. %@AB@%char int_frac_digits%@AE@%              Number of digits to the right of the 
  22495.                                   decimal point in internationally 
  22496.                                   formatted
  22497.                                   monetary quantities.
  22498.  
  22499. %@AB@%char frac_digits%@AE@%                  Number of digits to the right of the 
  22500.                                   decimal point in formatted monetary
  22501.                                   quantities.
  22502.  
  22503. %@AB@%char p_cs_precedes%@AE@%                Set to 1 if the currency symbol precedes
  22504.                                   the value for a nonnegative formatted 
  22505.                                   monetary quantity. Set to 0 if the 
  22506.                                   symbol follows the value.
  22507.  
  22508. %@AB@%char p_sep_by_space%@AE@%               Set to 1 if the currency symbol is 
  22509.                                   separated by a space from the value for 
  22510.                                   a non-negative formatted monetary 
  22511.                                   quantity. Set to 0 if there is no space 
  22512.                                   separation.
  22513.  
  22514. %@AB@%char n_cs_precedes%@AE@%                Set to 1 if the currency symbol precedes
  22515.                                   the value for a negative formatted 
  22516.                                   monetary quantity. Set to 0 if the 
  22517.                                   symbol succeeds the value.
  22518.  
  22519. %@AB@%char n_sep_by_space%@AE@%               Set to 1 if the currency symbol is 
  22520.                                   separated by a space from the value for 
  22521.                                   a negative formatted monetary quantity. 
  22522.                                   Set to 0 if there is no space 
  22523.                                   separation.
  22524.  
  22525. %@AB@%char p_sign_posn%@AE@%                  Position of positive sign in nonnegative
  22526.                                   formatted monetary quantities.
  22527.  
  22528. %@AB@%char n_sign_posn%@AE@%                  Position of positive sign in negative 
  22529.                                   formatted monetary quantities.
  22530.  
  22531. The elements of %@AB@%grouping%@AE@% and %@AB@%mon%@AE@%_%@AB@%grouping%@AE@% are interpreted according to the
  22532. following rules:  %@NL@%
  22533. %@NL@%
  22534. %@AB@%Value%@AE@%                             %@AB@%Interpretation%@AE@%
  22535. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22536. %@AB@%CHAR_MAX%@AE@%                          No further grouping is to be performed.
  22537.  
  22538. 0                                 The previous element is to be repeatedly
  22539.                                   used for the remainder of the digits.
  22540.  
  22541. %@AI@%n%@AE@%                                 The integer value %@AI@%n%@AE@% is the number of 
  22542.                                   digits that make up the current group. 
  22543.                                   The next element is examined to 
  22544.                                   determine the size of the next group of 
  22545.                                   digits before the current group.
  22546.  
  22547. The values for %@AB@%p_sign_posn%@AE@% and %@AB@%n_sign_posn%@AE@% are interpreted according to the
  22548. following rules:  %@NL@%
  22549. %@NL@%
  22550. %@AB@%Value%@AE@%                             %@AB@%Interpretation%@AE@%
  22551. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22552. 0                                 Parentheses surround the quantity and 
  22553.                                   currency symbol
  22554.  
  22555. 1                                 Sign string precedes the quantity and 
  22556.                                   currency symbol
  22557.  
  22558. 2                                 Sign string follows the quantity and 
  22559.                                   currency symbol
  22560.  
  22561. 3                                 Sign string immediately precedes the 
  22562.                                   currency symbol
  22563.  
  22564. 4                                 Sign string immediately follows the 
  22565.                                   currency symbol
  22566.  
  22567. %@NL@%
  22568. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22569. %@NL@%
  22570. The %@AB@%localeconv%@AE@% function returns a pointer to a structure of %@AB@%lconv%@AE@% type.
  22571. Calls to the %@AB@%setlocale%@AE@% function with %@AI@%category%@AE@% values of %@AB@%LC_ALL%@AE@%, %@AB@%LC_MONETARY,%@AE@%
  22572. or %@AB@%LC_NUMERIC%@AE@% will overwrite the contents of the structure.  %@NL@%
  22573. %@NL@%
  22574. %@NL@%
  22575. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22576. %@NL@%
  22577. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  22578. %@NL@%
  22579. %@NL@%
  22580. %@NL@%
  22581. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22582. %@NL@%
  22583. %@AB@%setlocale%@AE@%, %@AB@%strcoll%@AE@%, %@AB@%strftime%@AE@%, %@AB@%strxfrm%@AE@%  %@NL@%
  22584. %@NL@%
  22585. %@NL@%
  22586. %@NL@%
  22587. %@NL@%
  22588. %@QR:localtime@%%@NL@%
  22589. %@2@%%@CR:C6A01860925 @%%@AB@%localtime%@AE@%%@EH@%%@NL@%
  22590. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22591. %@NL@%
  22592. %@NL@%
  22593. %@3@%%@AB@%Description%@CR:C6A01860926 @%%@CR:C6A01860927 @% %@CR:C6A01860928 @%%@CR:C6A01860929 @% %@CR:C6A01860930 @%%@AE@%%@EH@%%@NL@%
  22594. %@NL@%
  22595. Converts a time value and corrects for the local time zone.  %@NL@%
  22596. %@NL@%
  22597. %@AS@%  #include <time.h>%@AE@%%@NL@%
  22598. %@NL@%
  22599. %@AS@%  struct tm *localtime( const time_t *timer );%@AE@%%@NL@%
  22600. %@NL@%
  22601. %@AI@%timer%@AE@%                             Pointer to stored time
  22602.  
  22603. %@NL@%
  22604. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22605. %@NL@%
  22606. The %@AB@%localtime%@AE@% function converts a time stored as a %@AB@%time_t%@AE@% value and stores
  22607. the result in a structure of type %@AB@%tm%@AE@%. The %@AB@%long%@AE@% value %@AI@%timer%@AE@% represents the
  22608. seconds elapsed since 00:00:00, January 1, 1970, Greenwich mean time; this
  22609. value is usually obtained from the %@AB@%time%@AE@% function.  %@NL@%
  22610. %@NL@%
  22611. The fields of the structure type %@AB@%tm%@AE@% store the following values:  %@NL@%
  22612. %@NL@%
  22613. %@AB@%Element%@AE@%                           %@AB@%Value Stored%@AE@%
  22614. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22615. %@AB@%int tm_sec%@AE@%                        Seconds
  22616.  
  22617. %@AB@%int tm_min%@AE@%                        Minutes
  22618.  
  22619. %@AB@%int tm_hour%@AE@%                       Hours (0 -24)
  22620.  
  22621. %@AB@%int tm_mday%@AE@%                       Day of month (1-31)
  22622.  
  22623. %@AB@%int tm_mon%@AE@%                        Month (0 -11; January = 0)
  22624.  
  22625. %@AB@%int tm_year%@AE@%                       Year (current year minus 1900)
  22626.  
  22627. %@AB@%int tm_wday%@AE@%                       Day of week (0 - 6; Sunday = 0)
  22628.  
  22629. %@AB@%int tm_yday%@AE@%                       Day of year (0 -365; January 1 = 0)
  22630.  
  22631. %@AB@%int tm_isdst%@AE@%                      Nonzero if daylight saving time is in 
  22632.                                   effect, otherwise 0
  22633.  
  22634. Note that the %@AB@%gmtime, mktime, %@AE@%and%@AB@% localtime%@AE@% functions use a single
  22635. statically allocated %@AB@%tm%@AE@% structure for the conversion. Each call to one of
  22636. these routines destroys the result of the previous call.  %@NL@%
  22637. %@NL@%
  22638. The %@AB@%localtime%@AE@% function makes corrections for the local time zone if the user
  22639. first sets the environment variable TZ. When TZ is set, three other
  22640. environment variables (%@AB@%timezone%@AE@%, %@AB@%daylight%@AE@%, and %@AB@%tzname%@AE@%) are automatically set
  22641. as well. See %@AB@%tzset%@AE@% for a description of these variables.%@CR:C6A01860931 @%  %@NL@%
  22642. %@NL@%
  22643. The TZ variable is not part of the ANSI standard definition of %@AB@%localtime%@AE@% but
  22644. is a Microsoft extension.  %@NL@%
  22645. %@NL@%
  22646. %@NL@%
  22647. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22648. %@NL@%
  22649. The %@AB@%localtime%@AE@% function returns a pointer to the structure result. DOS and
  22650. OS/2 do not accommodate dates prior to 1980. If the value in %@AI@%timer%@AE@%
  22651. represents a date prior to January 1, 1980, the function returns %@AB@%NULL%@AE@%.  %@NL@%
  22652. %@NL@%
  22653. %@NL@%
  22654. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22655. %@NL@%
  22656. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  22657. %@NL@%
  22658. %@NL@%
  22659. %@NL@%
  22660. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22661. %@NL@%
  22662. %@AB@%asctime%@AE@%, %@AB@%ctime%@AE@%, %@AB@%ftime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%time%@AE@%, %@AB@%tzset%@AE@%  %@NL@%
  22663. %@NL@%
  22664. %@NL@%
  22665. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22666. %@NL@%
  22667. %@AS@%  /* LOCALTIM.C: This program uses time to get the current time and
  22668. %@AS@%   * then uses localtime to convert this time to a structure representing 
  22669. %@AS@%   * the local time. The program converts the result from a 24-hour clock
  22670. %@AS@%   * to a 12-hour clock and determines the proper extension (AM or PM).
  22671. %@AS@%   */
  22672. %@AS@%  
  22673. %@AS@%  #include <stdio.h>
  22674. %@AS@%  #include <string.h>
  22675. %@AS@%  #include <time.h>
  22676. %@AS@%  
  22677. %@AS@%  void main()
  22678. %@AS@%  {
  22679. %@AS@%     struct tm *newtime;
  22680. %@AS@%     char  am_pm[] = "AM";
  22681. %@AS@%     time_t long_time;
  22682. %@AS@%  
  22683. %@AS@%     time( &long_time );                 /* Get time as long integer. */
  22684. %@AS@%     newtime = localtime( &long_time );  /* Convert to local time. */
  22685. %@AS@%  
  22686. %@AS@%     if( newtime->tm_hour < 12 )         /* Set up extension. */
  22687. %@AS@%        strcpy( am_pm, "AM" );
  22688. %@AS@%     if( newtime->tm_hour > 12 )         /* Convert from 24-hour */
  22689. %@AS@%        newtime->tm_hour -=12;           /*   to 12-hour clock.  */
  22690. %@AS@%  
  22691. %@AS@%     printf( "%.19s %s\n", asctime( newtime ), am_pm );
  22692. %@AS@%  }%@AE@%%@NL@%
  22693. %@NL@%
  22694. %@NL@%
  22695. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22696. %@NL@%
  22697. %@AS@%  
  22698. %@AS@%  
  22699. %@AS@%  Fri Jun 16 06:27:02 AM %@AE@%%@NL@%
  22700. %@NL@%
  22701. %@NL@%
  22702. %@NL@%
  22703. %@NL@%
  22704. %@QR:locking@%%@NL@%
  22705. %@2@%%@CR:C6A01870932 @%%@AB@%locking%@AE@%%@EH@%%@NL@%
  22706. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22707. %@NL@%
  22708. %@NL@%
  22709. %@3@%%@AB@%Description%@CR:C6A01870933 @%%@CR:C6A01870934 @%%@CR:C6A01870935 @%%@AE@%%@EH@%%@NL@%
  22710. %@NL@%
  22711. Locks or unlocks bytes of a file.  %@NL@%
  22712. %@NL@%
  22713. %@AS@%  #include <sys\locking.h>%@AE@%%@NL@%
  22714. %@NL@%
  22715. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  22716.  
  22717. %@AS@%  int locking( int handle, int mode, long nbytes );%@AE@%%@NL@%
  22718. %@NL@%
  22719. %@AI@%handle%@AE@%                            File handle
  22720.  
  22721. %@AI@%mode%@AE@%                              File-locking mode
  22722.  
  22723. %@AI@%nbytes%@AE@%                            Number of bytes to lock
  22724.  
  22725. %@NL@%
  22726. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22727. %@NL@%
  22728. The%@AB@% locking%@AE@% function locks or unlocks %@AI@%nbytes%@AE@% bytes of the file specified by
  22729. %@AI@%handle%@AE@%. Locking bytes in a file prevents access to those bytes by other
  22730. processes. All locking or unlocking begins at the current position of the
  22731. file pointer and proceeds for the next %@AI@%nbytes%@AE@% bytes. It is possible to lock
  22732. bytes past the end of the file.  %@NL@%
  22733. %@NL@%
  22734. The %@AI@%mode%@AE@% argument specifies the locking action to be performed. It must be
  22735. one of the following manifest constants:  %@NL@%
  22736. %@NL@%
  22737. %@AB@%Constant%@AE@%                          %@AB@%Action%@AE@%
  22738. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22739. %@AB@%LK_LOCK%@AE@%                           Locks the specified bytes. If the bytes 
  22740.                                   cannot be locked, immediately tries 
  22741.                                   again after 1 second. If, after 10 
  22742.                                   attempts, the bytes cannot be locked, 
  22743.                                   returns an error.
  22744.  
  22745. %@AB@%LK_NBLCK%@AE@%                          Locks the specified bytes. If bytes 
  22746.                                   cannot be locked, returns an error.
  22747.  
  22748. %@AB@%LK_NBRLCK%@AE@%                         Same as %@AB@%LK_NBLCK%@AE@%.
  22749.  
  22750. %@AB@%LK_RLCK%@AE@%                           Same as%@AB@% LK_LOCK%@AE@%.
  22751.  
  22752. %@AB@%LK_UNLCK%@AE@%                          Unlocks the specified bytes. (The bytes 
  22753.                                   must have been previously locked.)
  22754.  
  22755. More than one region of a file can be locked, but no overlapping regions are
  22756. allowed.  %@NL@%
  22757. %@NL@%
  22758. When a region of a file is being unlocked, it must correspond to a region
  22759. that was previously locked. The %@AB@%locking%@AE@% function does not merge adjacent
  22760. regions; if two locked regions are adjacent, each region must be unlocked
  22761. separately.  %@NL@%
  22762. %@NL@%
  22763. Regions should be locked only briefly and should be unlocked before closing
  22764. a file or exiting the program.  %@NL@%
  22765. %@NL@%
  22766. The %@AB@%locking%@AE@% function should be used only under OS/2 or under DOS versions
  22767. 3.0 and later; it has no effect under earlier versions of DOS. Also, file
  22768. sharing must be loaded to use the %@AB@%locking %@AE@%function. Note that under DOS
  22769. versions 3.0 and 3.1, the files locked by parent processes may become
  22770. unlocked when child processes exit.  %@NL@%
  22771. %@NL@%
  22772. %@NL@%
  22773. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22774. %@NL@%
  22775. The %@AB@%locking%@AE@% function returns 0 if successful. A return value of -1 indicates
  22776. failure, and %@AB@%errno%@AE@% is set to one of the following values:  %@NL@%
  22777. %@NL@%
  22778. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  22779. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22780. %@AB@%EACCES%@AE@%                            Locking violation (file already locked 
  22781.                                   or unlocked).
  22782.  
  22783. %@AB@%EBADF%@AE@%                             Invalid file handle.
  22784.  
  22785. %@AB@%EDEADLOCK%@AE@%                         Locking violation. This is returned when
  22786.                                   the %@AB@%LK_LOCK%@AE@% or %@AB@%LK_RLCK%@AE@% flag is specified
  22787.                                   and the file cannot be locked after 10 
  22788.                                   attempts.
  22789.  
  22790. %@AB@%EINVAL%@AE@%                            An invalid argument was given to the 
  22791.                                   function.
  22792.  
  22793. %@NL@%
  22794. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22795. %@NL@%
  22796.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  22797. %@NL@%
  22798. %@NL@%
  22799. %@NL@%
  22800. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22801. %@NL@%
  22802. %@AB@%creat%@AE@%, %@AB@%open%@AE@%  %@NL@%
  22803. %@NL@%
  22804. %@NL@%
  22805. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22806. %@NL@%
  22807. %@AS@%  /* LOCKING.C: This program opens a file with sharing. It locks some
  22808. %@AS@%   * bytes before reading them, then unlocks them. Note that the program
  22809. %@AS@%   * works correctly only if the following conditions are met:
  22810. %@AS@%   *     - The file exists
  22811. %@AS@%   *     - The program is run under OS/2, under DOS 3.0 or later
  22812. %@AS@%   *       with file sharing installed (SHARE.COM or SHARE.EXE), or 
  22813. %@AS@%   *       if a Microsoft Networks compatible network is running
  22814. %@AS@%   */
  22815. %@AS@%  
  22816. %@AS@%  #include <io.h>
  22817. %@AS@%  #include <sys\types.h>
  22818. %@AS@%  #include <sys\stat.h>
  22819. %@AS@%  #include <sys\locking.h>
  22820. %@AS@%  #include <share.h>
  22821. %@AS@%  #include <fcntl.h>
  22822. %@AS@%  #include <stdio.h>
  22823. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  22824. %@NL@%
  22825. %@AS@%  void main()
  22826. %@AS@%  {
  22827. %@AS@%     int  fh, numread;
  22828. %@AS@%     long pos, result;
  22829. %@AS@%     char buffer[40];
  22830. %@AS@%  
  22831. %@AS@%     /* Quit if can't open file or DOS version doesn't support sharing. */
  22832. %@AS@%     fh = sopen( "locking.c", O_RDWR, SH_DENYNO, S_IREAD | S_IWRITE );
  22833. %@AS@%     if( (fh == -1) || (_osmajor < 3) )
  22834. %@AS@%        exit( 1 );
  22835. %@AS@%  
  22836. %@AS@%     /* Lock some bytes and read them. Then unlock. */
  22837. %@AS@%     if( locking( fh, LK_NBLCK, 30L ) != -1 )
  22838. %@AS@%     {
  22839. %@AS@%        printf( "No one can change these bytes while I'm reading them\n" );
  22840. %@AS@%        numread = read( fh, buffer, 30 );
  22841. %@AS@%        printf( "%d bytes read: %.30s\n", numread, buffer );
  22842. %@AS@%        locking( fh, LK_UNLCK, 30L );
  22843. %@AS@%        printf( "Now I'm done. Do what you will with them\n" );
  22844. %@AS@%     }
  22845. %@AS@%     else
  22846. %@AS@%        perror( "Locking failed\n" );
  22847. %@AS@%  
  22848. %@AS@%     close( fh );
  22849. %@AS@%  }%@AE@%%@NL@%
  22850. %@NL@%
  22851. %@NL@%
  22852. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22853. %@NL@%
  22854. %@AS@%  
  22855. %@AS@%  
  22856. %@AS@%  No one can change these bytes while I'm reading them
  22857. %@AS@%  30 bytes read: /* LOCKING.C: This program ope
  22858. %@AS@%  Now I'm done. Do what you will with them %@AE@%%@NL@%
  22859. %@NL@%
  22860. %@NL@%
  22861. %@NL@%
  22862. %@NL@%
  22863. %@QR:log@%%@NL@%
  22864. %@2@%%@CR:C6A01880936 @%%@AB@%log Functions%@AE@%%@EH@%%@NL@%
  22865. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22866. %@NL@%
  22867. %@NL@%
  22868. %@3@%%@AB@%Description%@CR:C6A01880937 @%%@CR:C6A01880938 @% %@CR:C6A01880939 @%%@CR:C6A01880940 @% %@CR:C6A01880941 @%%@AE@%%@EH@%%@NL@%
  22869. %@NL@%
  22870. Calculate logarithms.  %@NL@%
  22871. %@NL@%
  22872. %@AS@%  #include <math.h>%@AE@%%@NL@%
  22873. %@NL@%
  22874. %@AS@%  double log( double x );%@AE@%%@NL@%
  22875. %@NL@%
  22876. %@AS@%  double log10( double x );%@AE@%%@NL@%
  22877. %@NL@%
  22878. %@AS@%  long double logl( long double x );%@AE@%%@NL@%
  22879. %@NL@%
  22880. %@AS@%  long double log10l( long double x );%@AE@%%@NL@%
  22881. %@NL@%
  22882. %@AI@%x%@AE@%                                 Value whose logarithm is to be found
  22883.  
  22884. %@NL@%
  22885. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  22886. %@NL@%
  22887. The %@AB@%log%@AE@% and %@AB@%log10%@AE@% functions calculate the natural logarithm and the base-10
  22888. logarithm, respectively, of %@AI@%x%@AE@%. The %@AB@%logl%@AE@% and %@AB@%log10l%@AE@% functions are the 80-bit
  22889. counterparts and use the 80-bit, 10-byte coprocessor form of arguments and
  22890. return values. See the reference page on the long double functions for more
  22891. details on this data type.  %@NL@%
  22892. %@NL@%
  22893. %@NL@%
  22894. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  22895. %@NL@%
  22896. The%@AB@% log%@AE@% functions return the logarithm of the argument %@AI@%x%@AE@%. If %@AI@%x%@AE@% is negative,
  22897. the functions print a %@AB@%DOMAIN%@AE@% error message to %@AB@%stderr%@AE@%, return the value
  22898. -%@AB@%HUGE_VAL%@AE@%, and set %@AB@%errno%@AE@% to %@AB@%EDOM%@AE@%. If %@AI@%x%@AE@% is 0, the functions print a%@AB@% SING%@AE@%
  22899. error message to %@AB@%stderr%@AE@%, return the value -%@AB@%HUGE_VAL%@AE@%, and set %@AB@%errno%@AE@% to
  22900. %@AB@%ERANGE.%@AE@%  %@NL@%
  22901. %@NL@%
  22902. Error handling can be modified by using the %@AB@%matherr%@AE@% or %@AB@%_matherrl%@AE@% routine.  %@NL@%
  22903. %@NL@%
  22904. %@NL@%
  22905. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  22906. %@NL@%
  22907. %@AB@%log%@AE@%, %@AB@%log10%@AE@%  %@NL@%
  22908. %@NL@%
  22909. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  22910. %@NL@%
  22911. %@NL@%
  22912. %@AB@%logl%@AE@%, %@AB@%log10l%@AE@%  %@NL@%
  22913. %@NL@%
  22914.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  22915. %@NL@%
  22916. %@NL@%
  22917. %@NL@%
  22918. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  22919. %@NL@%
  22920. %@AB@%exp%@AE@%,%@AB@% matherr%@AE@%,%@AB@% pow%@AE@% functions  %@NL@%
  22921. %@NL@%
  22922. %@NL@%
  22923. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  22924. %@NL@%
  22925. %@AS@%  /* LOG.C: This program uses log and log10 to calculate the natural
  22926. %@AS@%   * logarithm and the base-10 logarithm of 9,000.
  22927. %@AS@%   */
  22928. %@AS@%  
  22929. %@AS@%  #include <math.h>
  22930. %@AS@%  #include <stdio.h>
  22931. %@AS@%  
  22932. %@AS@%  void main()
  22933. %@AS@%  {
  22934. %@AS@%     double x = 9000.0;
  22935. %@AS@%     double y;
  22936. %@AS@%  
  22937. %@AS@%     y = log( x );
  22938. %@AS@%     printf( "log( %.2f ) = %f\n", x, y );
  22939. %@AS@%     y = log10( x );
  22940. %@AS@%     printf( "log10( %.2f ) = %f\n", x, y );
  22941. %@AS@%  }%@AE@%%@NL@%
  22942. %@NL@%
  22943. %@NL@%
  22944. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  22945. %@NL@%
  22946. %@AS@%  
  22947. %@AS@%  
  22948. %@AS@%  log( 9000.00 ) = 9.104980
  22949. %@AS@%  log10( 9000.00 ) = 3.954243%@AE@%%@NL@%
  22950. %@NL@%
  22951. %@NL@%
  22952. %@NL@%
  22953. %@NL@%
  22954. %@QR:long@%%@QR:double@%%@NL@%
  22955. %@2@%%@CR:C6A01890942 @%%@AB@%long double Functions%@AE@%%@EH@%%@NL@%
  22956. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22957. %@NL@%
  22958. The 8087 family of numeric coprocessor chips supports the 80-bit precision
  22959. floating-point data type. In Microsoft C, version 6.0, the long double
  22960. functions, whose names end with%@AB@% l%@AE@%, map the C %@AB@%long double%@AE@% type into this
  22961. 80-bit, 10-byte form. Unlike the regular floating-point functions (such as
  22962. %@AB@%acos%@AE@%), which return values of type %@AB@%double%@AE@%, these long double functions (such
  22963. as %@AB@%acosl%@AE@%) return values of type %@AB@%long double%@AE@%. The long double functions also
  22964. return their values on the coprocessor stack for all calling conventions.  %@NL@%
  22965. %@NL@%
  22966. The long double type is also supported by the addition of the "L" prefix for
  22967. a floating-point format specification in the %@AB@%printf%@AE@% and %@AB@%scanf%@AE@% family of
  22968. functions.  %@NL@%
  22969. %@NL@%
  22970. The long double versions are described on the reference pages for their
  22971. regular counterparts. These are the regular C run-time math functions with
  22972. corresponding long double equivalents:  %@NL@%
  22973. %@NL@%
  22974. %@AB@%Regular Function%@AE@%                  %@AB@%Long Double Form%@AE@%
  22975. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  22976. %@AB@%acos%@AE@%                              %@AB@%acosl%@AE@%
  22977.  
  22978. %@AB@%asin%@AE@%                              %@AB@%asinl%@AE@%
  22979.  
  22980. %@AB@%atan%@AE@%                              %@AB@%atanl%@AE@%
  22981.  
  22982. %@AB@%atan2%@AE@%                             %@AB@%atan2l%@AE@%
  22983.  
  22984. %@AB@%atof%@AE@%                              %@AB@%_atold%@AE@%
  22985.  
  22986. %@AB@%cabs%@AE@%                              %@AB@%cabsl%@AE@%
  22987.  
  22988. %@AB@%ceil%@AE@%                              %@AB@%ceill%@AE@%
  22989.  
  22990. %@AB@%cos%@AE@%                               %@AB@%cosl%@AE@%
  22991.  
  22992. %@AB@%cosh%@AE@%                              %@AB@%coshl%@AE@%
  22993.  
  22994. %@AB@%exp%@AE@%                               %@AB@%expl%@AE@%
  22995.  
  22996. %@AB@%fabs%@AE@%                              %@AB@%fabsl%@AE@%
  22997.  
  22998. %@AB@%floor%@AE@%                             %@AB@%floorl%@AE@%
  22999.  
  23000. %@AB@%fmod%@AE@%                              %@AB@%fmodl%@AE@%
  23001.  
  23002. %@AB@%frexp%@AE@%                             %@AB@%frexpl%@AE@%
  23003.  
  23004. %@AB@%hypot%@AE@%                             %@AB@%hypotl%@AE@%
  23005.  
  23006. %@AB@%ldexp%@AE@%                             %@AB@%ldexpl%@AE@%
  23007.  
  23008. %@AB@%log%@AE@%                               %@AB@%logl%@AE@%
  23009.  
  23010. %@AB@%log10%@AE@%                             %@AB@%log10l%@AE@%
  23011.  
  23012. %@AB@%matherr%@AE@%                           %@AB@%_matherrl%@AE@%
  23013.  
  23014. %@AB@%modf%@AE@%                              %@AB@%modfl%@AE@%
  23015.  
  23016. %@AB@%pow%@AE@%                               %@AB@%powl%@AE@%
  23017.  
  23018. %@AB@%sin%@AE@%                               %@AB@%sinl%@AE@%
  23019.  
  23020. %@AB@%sinh%@AE@%                              %@AB@%sinhl%@AE@%
  23021.  
  23022. %@AB@%sqrt%@AE@%                              %@AB@%sqrtl%@AE@%
  23023.  
  23024. %@AB@%tan%@AE@%                               %@AB@%tanl%@AE@%
  23025.  
  23026. %@AB@%tanh%@AE@%                              %@AB@%tanhl%@AE@%
  23027.  
  23028. %@NL@%
  23029. %@NL@%
  23030. %@NL@%
  23031. %@QR:longjmp@%%@NL@%
  23032. %@2@%%@CR:C6A01900943 @%%@AB@%longjmp%@AE@%%@EH@%%@NL@%
  23033. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23034. %@NL@%
  23035. %@NL@%
  23036. %@3@%%@AB@%Description%@CR:C6A01900944 @%%@CR:C6A01900945 @%%@CR:C6A01900946 @% %@CR:C6A01900947 @%%@AE@%%@EH@%%@NL@%
  23037. %@NL@%
  23038. Restores stack environment and execution locale.  %@NL@%
  23039. %@NL@%
  23040. %@AS@%  #include <setjmp.h>%@AE@%%@NL@%
  23041. %@NL@%
  23042. %@AS@%  void longjmp( jmp_buf env, int value );%@AE@%%@NL@%
  23043. %@NL@%
  23044. %@AI@%env%@AE@%                               Variable in which environment is stored
  23045.  
  23046. %@AI@%value%@AE@%                             Value to be returned to %@AB@%setjmp%@AE@% call
  23047.  
  23048. %@NL@%
  23049. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23050. %@NL@%
  23051. The %@AB@%longjmp%@AE@% function restores a stack environment and execution locale
  23052. previously saved in %@AI@%env%@AE@% by %@AB@%setjmp%@AE@%. The %@AB@%setjmp%@AE@% and %@AB@%longjmp%@AE@% functions provide
  23053. a way to execute a nonlocal %@AB@%goto%@AE@%; they are typically used to pass execution
  23054. control to error handling or recovery code in a previously called routine
  23055. without using the normal call and return conventions.  %@NL@%
  23056. %@NL@%
  23057. A call to %@AB@%setjmp%@AE@% causes the current stack environment to be saved in %@AI@%env.%@AE@% A
  23058. subsequent call to %@AB@%longjmp%@AE@% restores the saved environment and returns
  23059. control to the point immediately following the corresponding %@AB@%setjmp%@AE@% call.
  23060. Execution resumes as if %@AI@%value%@AE@% had just been returned by the %@AB@%setjmp%@AE@% call. The
  23061. values of all variables (except register variables) that are accessible to
  23062. the routine receiving control contain the values they had when %@AB@%longjmp%@AE@% was
  23063. called. The values of register variables are unpredictable.  %@NL@%
  23064. %@NL@%
  23065. The %@AB@%longjmp%@AE@% function must be called before the function that called %@AB@%setjmp%@AE@%
  23066. returns. If %@AB@%longjmp%@AE@% is called after the function calling %@AB@%setjmp%@AE@% returns,
  23067. unpredictable program behavior results.  %@NL@%
  23068. %@NL@%
  23069. The value returned by %@AB@%setjmp%@AE@% must be nonzero. If %@AI@%value%@AE@% is passed as 0, the
  23070. value 1 is substituted in the actual return.  %@NL@%
  23071. %@NL@%
  23072. Observe the following three restrictions when using %@AB@%longjmp%@AE@%:  %@NL@%
  23073. %@NL@%
  23074. %@NL@%
  23075.   1.  Do not assume that the values of the register variables will remain
  23076.       the same. The values of register variables in the routine calling
  23077.       %@AB@%setjmp%@AE@% may not be restored to the proper values after %@AB@%longjmp%@AE@% is
  23078.       executed.%@NL@%
  23079. %@NL@%
  23080.   2.  Do not use %@AB@%longjmp%@AE@% to transfer control from within one overlay to
  23081.       within another. The overlay manager keeps the overlay in memory after
  23082.       a call to %@AB@%longjmp%@AE@%.%@NL@%
  23083. %@NL@%
  23084.   3.  Do not use %@AB@%longjmp%@AE@% to transfer control out of an interrupt-handling
  23085.       routine unless the interrupt is caused by a floating-point exception.
  23086.       In this case, a program may return from an interrupt handler via
  23087.       %@AB@%longjmp%@AE@% if it first reinitializes the floating-point math package by
  23088.       calling %@AB@%_fpreset%@AE@%.%@NL@%
  23089. %@NL@%
  23090. %@NL@%
  23091. %@NL@%
  23092. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23093. %@NL@%
  23094. None.  %@NL@%
  23095. %@NL@%
  23096. %@NL@%
  23097. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23098. %@NL@%
  23099. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  23100. %@NL@%
  23101. %@NL@%
  23102. %@NL@%
  23103. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23104. %@NL@%
  23105. %@AB@%setjmp%@AE@%  %@NL@%
  23106. %@NL@%
  23107. %@NL@%
  23108. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23109. %@NL@%
  23110. See the example for %@AB@%_fpreset%@AE@%.  %@NL@%
  23111. %@NL@%
  23112. %@NL@%
  23113. %@NL@%
  23114. %@NL@%
  23115. %@QR:_lrotl@%%@QR:_lrotr@%%@NL@%
  23116. %@2@%%@CR:C6A01910948 @%%@AB@%_lrotl, _lrotr%@AE@%%@EH@%%@NL@%
  23117. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23118. %@NL@%
  23119. %@NL@%
  23120. %@3@%%@AB@%Description %@CR:C6A01910949 @%%@CR:C6A01910950 @%%@AE@%%@EH@%%@NL@%
  23121. %@NL@%
  23122. Rotate bits to the left (%@AB@%_lrotl%@AE@%) or right (%@AB@%_lrotr%@AE@%).  %@NL@%
  23123. %@NL@%
  23124. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  23125. %@NL@%
  23126. %@AS@%  unsigned long _lrotl( unsigned long value, int shift );%@AE@%%@NL@%
  23127. %@NL@%
  23128. %@AS@%  unsigned long _lrotr( unsigned long value, int shift );%@AE@%%@NL@%
  23129. %@NL@%
  23130. %@AI@%value%@AE@%                             Value to be rotated
  23131.  
  23132. %@AI@%shift%@AE@%                             Number of bits to shift
  23133.  
  23134. %@NL@%
  23135. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23136. %@NL@%
  23137. The %@AB@%_lrotl%@AE@% and %@AB@%_lrotr%@AE@% functions rotate %@AI@%value%@AE@% by %@AI@%shift%@AE@% bits. The %@AB@%_lrotl%@AE@%
  23138. function rotates the value left. The %@AB@%_lrotr%@AE@% function rotates the value
  23139. right. Both functions "wrap" bits rotated off one end of %@AI@%value%@AE@% to the other
  23140. end.  %@NL@%
  23141. %@NL@%
  23142. %@NL@%
  23143. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23144. %@NL@%
  23145. Both functions return the rotated value. There is no error return.  %@NL@%
  23146. %@NL@%
  23147. %@NL@%
  23148. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23149. %@NL@%
  23150.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  23151. %@NL@%
  23152. %@NL@%
  23153. %@NL@%
  23154. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23155. %@NL@%
  23156. %@AB@%_rotl%@AE@%,  %@AB@%_rotr%@AE@%  %@NL@%
  23157. %@NL@%
  23158. %@NL@%
  23159. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23160. %@NL@%
  23161. %@AS@%  /* LROT.C */
  23162. %@AS@%  #include <stdlib.h>
  23163. %@AS@%  #include <stdio.h>
  23164. %@AS@%  
  23165. %@AS@%  void main()
  23166. %@AS@%  {
  23167. %@AS@%     unsigned long val = 0x0fac35791;
  23168. %@AS@%  
  23169. %@AS@%     printf( "0x%8.8lx rotated left eight times is 0x%8.8lx\n",
  23170. %@AS@%             val, _lrotl( val, 8 ) );
  23171. %@AS@%     printf( "0x%8.8lx rotated right four times is 0x%8.8lx\n",
  23172. %@AS@%             val, _lrotr( val, 4 ) );
  23173. %@AS@%  }%@AE@%%@NL@%
  23174. %@NL@%
  23175. %@NL@%
  23176. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  23177. %@NL@%
  23178. %@AS@%  
  23179. %@AS@%  
  23180. %@AS@%  0xfac35791 rotated left eight times is 0xc35791fa
  23181. %@AS@%  0xfac35791 rotated right four times is 0x1fac3579 %@AE@%%@NL@%
  23182. %@NL@%
  23183. %@NL@%
  23184. %@NL@%
  23185. %@NL@%
  23186. %@QR:lsearch@%%@NL@%
  23187. %@2@%%@CR:C6A01920951 @%%@AB@%lsearch%@AE@%%@EH@%%@NL@%
  23188. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23189. %@NL@%
  23190. %@NL@%
  23191. %@3@%%@AB@%Description%@CR:C6A01920952 @%%@CR:C6A01920953 @%%@CR:C6A01920954 @%%@AE@%%@EH@%%@NL@%
  23192. %@NL@%
  23193. Performs a linear search for a value; adds to end of list if not found.  %@NL@%
  23194. %@NL@%
  23195. %@AB@%#include <search.h>%@AE@%               Required only for function declarations
  23196.  
  23197. %@AS@%  char *lsearch( const void *key, const void *base, unsigned int *num, 
  23198. %@AS@%  unsigned int width, int ( *compare )( const void *elem1, const void *elem2
  23199. %@AS@%) );%@AE@%%@NL@%
  23200. %@NL@%
  23201. %@AI@%key%@AE@%                               Object to search for
  23202.  
  23203. %@AI@%base%@AE@%                              Pointer to base of search data
  23204.  
  23205. %@AI@%num%@AE@%                               Number of elements
  23206.  
  23207. %@AI@%width%@AE@%                             Width of elements
  23208.  
  23209. %@AI@%compare%@AE@%                           Pointer to comparison routine
  23210.  
  23211. %@AI@%elem1%@AE@%                             Pointer to the key for the search
  23212.  
  23213. %@AI@%elem2%@AE@%                             Pointer to the array element to be 
  23214.                                   compared with the key
  23215.  
  23216. %@NL@%
  23217. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23218. %@NL@%
  23219. The %@AB@%lsearch%@AE@% function performs a linear search for the value %@AI@%key%@AE@% in an array
  23220. of %@AI@%num%@AE@% elements, each of %@AI@%width%@AE@% bytes in size. (Unlike %@AB@%bsearch%@AE@%, %@AB@%lsearch%@AE@% does
  23221. not require the array to be sorted.) The %@AI@%base%@AE@% argument is a pointer to the
  23222. base of the array to be searched.  %@NL@%
  23223. %@NL@%
  23224. If %@AI@%key%@AE@% is not found, %@AB@%lsearch%@AE@% adds it to the end of the array.  %@NL@%
  23225. %@NL@%
  23226. The %@AI@%compare%@AE@% argument is a pointer to a user-supplied routine that compares
  23227. two array elements and returns a value specifying their relationship. The
  23228. %@AB@%lsearch%@AE@% function calls the %@AI@%compare%@AE@% routine one or more times during the
  23229. search, passing pointers to two array elements on each call. This routine
  23230. must compare the elements, then return one of the following values:  %@NL@%
  23231. %@NL@%
  23232. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  23233. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23234. Nonzero                           Elements are different
  23235.  
  23236. 0                                 Elements are identical
  23237.  
  23238. %@NL@%
  23239. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23240. %@NL@%
  23241. If the key is found, %@AB@%lsearch%@AE@% returns a pointer to the element of the array
  23242. at %@AI@%base%@AE@% that matches %@AI@%key%@AE@%. If the key is not found, %@AB@%lsearch%@AE@% returns a pointer
  23243. to the newly added item at the end of the array.  %@NL@%
  23244. %@NL@%
  23245. %@NL@%
  23246. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23247. %@NL@%
  23248.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  23249. %@NL@%
  23250. %@NL@%
  23251. %@NL@%
  23252. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23253. %@NL@%
  23254. %@AB@%bsearch%@AE@%, %@AB@%lfind%@AE@%  %@NL@%
  23255. %@NL@%
  23256. %@NL@%
  23257. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23258. %@NL@%
  23259. See the example for %@AB@%lfind%@AE@%.  %@NL@%
  23260. %@NL@%
  23261. %@NL@%
  23262. %@NL@%
  23263. %@NL@%
  23264. %@QR:lseek@%%@NL@%
  23265. %@2@%%@CR:C6A01930955 @%%@AB@%lseek%@AE@%%@EH@%%@NL@%
  23266. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23267. %@NL@%
  23268. %@NL@%
  23269. %@3@%%@AB@%Description%@CR:C6A01930956 @%%@CR:C6A01930957 @% %@CR:C6A01930958 @%%@CR:C6A01930959 @%%@AE@%%@EH@%%@NL@%
  23270. %@NL@%
  23271. Moves a file pointer to the specified location.  %@NL@%
  23272. %@NL@%
  23273. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  23274.  
  23275. %@AB@%#include <stdio.h>%@AE@%                
  23276.  
  23277. %@AS@%  long lseek( int handle, long offset, int origin );%@AE@%%@NL@%
  23278. %@NL@%
  23279. %@AI@%handle%@AE@%                            Handle referring to open file
  23280.  
  23281. %@AI@%offset%@AE@%                            Number of bytes from %@AI@%origin%@AE@%
  23282.  
  23283. %@AI@%origin%@AE@%                            Initial position
  23284.  
  23285. %@NL@%
  23286. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23287. %@NL@%
  23288. The %@AB@%lseek%@AE@% function moves the file pointer associated with %@AI@%handle%@AE@% to a new
  23289. location that is %@AI@%offset%@AE@% bytes from %@AI@%origin%@AE@%. The next operation on the file
  23290. occurs at the new location. The %@AI@%origin%@AE@% argument must be one of the following
  23291. constants, which are defined in STDIO.H:  %@NL@%
  23292. %@NL@%
  23293. %@AB@%Origin%@AE@%                            %@AB@%Definition%@AE@%
  23294. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23295. %@AB@%SEEK_SET%@AE@%                          Beginning of file
  23296.  
  23297. %@AB@%SEEK_CUR%@AE@%                          Current position of file pointer
  23298.  
  23299. %@AB@%SEEK_END%@AE@%                          End of file
  23300.  
  23301. The %@AB@%lseek%@AE@% function can be used to reposition the pointer anywhere in a file.
  23302. The pointer can also be positioned beyond the end of the file. However, an
  23303. attempt to position the pointer before the beginning of the file causes an
  23304. error.  %@NL@%
  23305. %@NL@%
  23306. %@NL@%
  23307. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23308. %@NL@%
  23309. The %@AB@%lseek%@AE@% function returns the offset, in bytes, of the new position from
  23310. the beginning of the file. The function returns -1L to indicate an error and
  23311. sets %@AB@%errno%@AE@% to one of the following values:  %@NL@%
  23312. %@NL@%
  23313. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  23314. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23315. %@AB@%EBADF%@AE@%                             Invalid file handle
  23316.  
  23317. %@AB@%EINVAL%@AE@%                            Invalid value for %@AI@%origin%@AE@%, or position 
  23318.                                   specified by %@AI@%offset%@AE@% is before the 
  23319.                                   beginning of the file
  23320.  
  23321. On devices incapable of seeking (such as terminals and printers), the return
  23322. value is undefined.  %@NL@%
  23323. %@NL@%
  23324. %@NL@%
  23325. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23326. %@NL@%
  23327.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  23328. %@NL@%
  23329. %@NL@%
  23330. %@NL@%
  23331. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23332. %@NL@%
  23333. %@AB@%fseek, tell%@AE@%  %@NL@%
  23334. %@NL@%
  23335. %@NL@%
  23336. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23337. %@NL@%
  23338. %@AS@%  /* LSEEK.C: This program first opens a file named LSEEK.C.
  23339. %@AS@%   * It then uses lseek to find the beginning of the file,
  23340. %@AS@%   * to find the current position in the file, and to find
  23341. %@AS@%   * the end of the file.
  23342. %@AS@%   */
  23343. %@AS@%  
  23344. %@AS@%  #include <io.h>
  23345. %@AS@%  #include <fcntl.h>
  23346. %@AS@%  #include <stdlib.h>
  23347. %@AS@%  #include <stdio.h>
  23348. %@AS@%  
  23349. %@AS@%  
  23350. %@AS@%  void main()
  23351. %@AS@%  {
  23352. %@AS@%     int fh;
  23353. %@AS@%     long pos;               /* Position of file pointer */
  23354. %@AS@%     char buffer[10];
  23355. %@AS@%  
  23356. %@AS@%     fh = open( "lseek.c", O_RDONLY );
  23357. %@AS@%  
  23358. %@AS@%     /* Seek the beginning of the file: */
  23359. %@AS@%     pos = lseek( fh, 0L, SEEK_SET );
  23360. %@AS@%     if( pos == -1L )
  23361. %@AS@%        perror( "lseek to beginning failed" );
  23362. %@AS@%     else
  23363. %@AS@%        printf( "Position for beginning of file seek = %ld\n", pos );
  23364. %@AS@%  
  23365. %@AS@%     /* Move file pointer a little */
  23366. %@AS@%     read( fh, buffer, 10 );
  23367. %@AS@%  
  23368. %@AS@%     /* Find current position: */
  23369. %@AS@%     pos = lseek( fh, 0L, SEEK_CUR );
  23370. %@AS@%     if( pos == -1L )
  23371. %@AS@%        perror( "lseek to current position failed" );
  23372. %@AS@%     else
  23373. %@AS@%        printf( "Position for current position seek = %ld\n", pos );
  23374. %@AS@%  %@AE@%%@NL@%
  23375. %@NL@%
  23376. %@AS@%  /* Set the end of the file: */
  23377. %@AS@%     pos = lseek( fh, 0L, SEEK_END );
  23378. %@AS@%     if( pos == -1L )
  23379. %@AS@%        perror( "lseek to end failed" );
  23380. %@AS@%     else
  23381. %@AS@%        printf( "Position for end of file seek = %ld\n", pos );
  23382. %@AS@%  
  23383. %@AS@%     close( fh );
  23384. %@AS@%  }%@AE@%%@NL@%
  23385. %@NL@%
  23386. %@NL@%
  23387. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  23388. %@NL@%
  23389. %@AS@%  
  23390. %@AS@%  
  23391. %@AS@%  Position for beginning of file seek = 0
  23392. %@AS@%  Position for current position seek = 10
  23393. %@AS@%  Position for end of file seek = 1183%@AE@%%@NL@%
  23394. %@NL@%
  23395. %@NL@%
  23396. %@NL@%
  23397. %@NL@%
  23398. %@QR:ltoa@%%@NL@%
  23399. %@2@%%@CR:C6A01940960 @%%@AB@%ltoa%@AE@%%@EH@%%@NL@%
  23400. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23401. %@NL@%
  23402. %@NL@%
  23403. %@3@%%@AB@%Description%@CR:C6A01940961 @%%@CR:C6A01940962 @% %@CR:C6A01940963 @%%@CR:C6A01940964 @% %@CR:C6A01940965 @%%@AE@%%@EH@%%@NL@%
  23404. %@NL@%
  23405. Converts a long integer to a string.  %@NL@%
  23406. %@NL@%
  23407. %@AB@%#include <stdlib.h>%@AE@%               Required only for function declarations
  23408.  
  23409. %@AS@%  char *ltoa( long value, char *string, int radix );%@AE@%%@NL@%
  23410. %@NL@%
  23411. %@AI@%value%@AE@%                             Number to be converted
  23412.  
  23413. %@AI@%string%@AE@%                            String result
  23414.  
  23415. %@AI@%radix%@AE@%                             Base of %@AI@%value%@AE@%
  23416.  
  23417. %@NL@%
  23418. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23419. %@NL@%
  23420. The %@AB@%ltoa%@AE@% function converts the digits of %@AI@%value%@AE@% to a null-terminated
  23421. character string and stores the result (up to 33 bytes) in %@AI@%string%@AE@%. The %@AI@%radix%@AE@%
  23422. argument specifies the base of %@AI@%value%@AE@%, which must be in the range 2-36. If
  23423. %@AI@%radix%@AE@% equals 10 and %@AI@%value%@AE@% is negative, the first character of the stored
  23424. string is the minus sign (-).  %@NL@%
  23425. %@NL@%
  23426. %@NL@%
  23427. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23428. %@NL@%
  23429. The %@AB@%ltoa%@AE@% function returns a pointer to %@AI@%string%@AE@%. There is no error return.  %@NL@%
  23430. %@NL@%
  23431. %@NL@%
  23432. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23433. %@NL@%
  23434.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  23435. %@NL@%
  23436. %@NL@%
  23437. %@NL@%
  23438. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23439. %@NL@%
  23440. %@AB@%itoa%@AE@%,%@AB@% ultoa%@AE@%  %@NL@%
  23441. %@NL@%
  23442. %@NL@%
  23443. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23444. %@NL@%
  23445. %@AS@%  /* ITOA.C: This program converts integers of various sizes to strings
  23446. %@AS@%   * in various radixes.
  23447. %@AS@%   */
  23448. %@AS@%  
  23449. %@AS@%  #include <stdlib.h>
  23450. %@AS@%  #include <stdio.h>
  23451. %@AS@%  
  23452. %@AS@%  void main()
  23453. %@AS@%  {
  23454. %@AS@%     char buffer[20];
  23455. %@AS@%     int  i = 3445;
  23456. %@AS@%     long l = -344115L;
  23457. %@AS@%     unsigned long ul = 1234567890UL;
  23458. %@AS@%  %@AE@%%@NL@%
  23459. %@NL@%
  23460. %@AS@%  itoa( i, buffer, 10 );
  23461. %@AS@%     printf( "String of integer %d (radix 10): %s\n", i, buffer );
  23462. %@AS@%     itoa( i, buffer, 16 );
  23463. %@AS@%     printf( "String of integer %d (radix 16): 0x%s\n", i, buffer );
  23464. %@AS@%     itoa( i, buffer, 2  );
  23465. %@AS@%     printf( "String of integer %d (radix 2): %s\n", i, buffer );
  23466. %@AS@%  
  23467. %@AS@%     ltoa( l, buffer, 16 );
  23468. %@AS@%     printf( "String of long int %ld (radix 16): 0x%s\n", l, buffer );
  23469. %@AS@%  
  23470. %@AS@%     ultoa( ul, buffer, 16 );
  23471. %@AS@%     printf( "String of unsigned long %lu (radix 16): 0x%s\n", ul, buffer );
  23472. %@AS@%  }%@AE@%%@NL@%
  23473. %@NL@%
  23474. %@NL@%
  23475. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  23476. %@NL@%
  23477. %@AS@%  
  23478. %@AS@%  
  23479. %@AS@%  String of integer 3445 (radix 10): 3445
  23480. %@AS@%  String of integer 3445 (radix 16): 0xd75
  23481. %@AS@%  String of integer 3445 (radix 2): 110101110101
  23482. %@AS@%  String of long int -344115 (radix 16): 0xfffabfcd
  23483. %@AS@%  String of unsigned long 1234567890 (radix 16): 0x499602d2 %@AE@%%@NL@%
  23484. %@NL@%
  23485. %@NL@%
  23486. %@NL@%
  23487. %@NL@%
  23488. %@QR:_makepath@%%@NL@%
  23489. %@2@%%@CR:C6A01950966 @%%@AB@%_makepath%@AE@%%@EH@%%@NL@%
  23490. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23491. %@NL@%
  23492. %@NL@%
  23493. %@3@%%@AB@%Description%@CR:C6A01950967 @%%@AE@%%@EH@%%@NL@%
  23494. %@NL@%
  23495. Creates a single path name.  %@NL@%
  23496. %@NL@%
  23497. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  23498. %@NL@%
  23499. %@AS@%  void _makepath( char *path, char *drive, char *dir, char *fname, char *ext
  23500. %@AS@%  );%@AE@%%@NL@%
  23501. %@NL@%
  23502. %@AI@%path%@AE@%                              Full path-name buffer
  23503.  
  23504. %@AI@%drive%@AE@%                             Drive letter
  23505.  
  23506. %@AI@%dir%@AE@%                               Directory path
  23507.  
  23508. %@AI@%fname%@AE@%                             File name
  23509.  
  23510. %@AI@%ext%@AE@%                               File extension
  23511.  
  23512. %@NL@%
  23513. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23514. %@NL@%
  23515. The %@AB@%_makepath%@AE@% routine creates a single path name, composed of a drive
  23516. letter, directory path, file name, and file-name extension. The %@AI@%path%@AE@%
  23517. argument should point to an empty buffer large enough to hold the complete
  23518. path name. The constant %@AB@%_MAX_PATH%@AE@%, defined in STDLIB.H, specifies the
  23519. maximum size %@AI@%path%@AE@% that the %@AB@%_makepath%@AE@% function can handle. The other
  23520. arguments point to buffers containing the path-name elements:  %@NL@%
  23521. %@NL@%
  23522. %@AB@%Buffer%@AE@%                            %@AB@%Description%@AE@%
  23523. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23524. %@AI@%drive%@AE@%                             The %@AI@%drive%@AE@% argument contains a letter (A,
  23525.                                   B, etc.) corresponding to the desired 
  23526.                                   drive and an optional trailing colon. 
  23527.                                   The %@AB@%_makepath%@AE@% routine will insert the 
  23528.                                   colon automatically in the composite 
  23529.                                   path name if it is missing. If %@AI@%drive%@AE@% is 
  23530.                                   a null character or an empty string, no 
  23531.                                   drive letter and colon will appear in 
  23532.                                   the composite %@AI@%path%@AE@% string.
  23533.  
  23534. %@AI@%dir%@AE@%                               The %@AI@%dir%@AE@% argument contains the path of 
  23535.                                   directories, not including the drive 
  23536.                                   designator or the actual file name. The 
  23537.                                   trailing slash is optional, and either 
  23538.                                   forward slashes ( %@AB@%/%@AE@% ) or backslashes ( \
  23539.                                   ) or both may be used in a single %@AI@%dir%@AE@% 
  23540.                                   argument. If a trailing slash ( %@AB@%/%@AE@% or \ )
  23541.                                   is not specified, it will be inserted 
  23542.                                   automatically. If %@AI@%dir%@AE@% is a null 
  23543.                                   character or an empty string, no slash 
  23544.                                   is inserted in the composite %@AI@%path%@AE@% 
  23545.                                   string.
  23546.  
  23547. %@AI@%fname%@AE@%                             The %@AI@%fname%@AE@% argument contains the base 
  23548.                                   file name without any extensions. If %@AI@%%@AE@%
  23549.                                   %@AI@%fname%@AE@% is %@AB@%NULL%@AE@% or points to an empty 
  23550.                                   string, no file name is inserted in the 
  23551.                                   composite %@AI@%path%@AE@% string.
  23552.  
  23553. %@AI@%ext%@AE@%                               The %@AI@%ext%@AE@% argument contains the actual 
  23554.                                   file-name extension, with or without a 
  23555.                                   leading period (%@AB@%.%@AE@%). The %@AB@%_makepath%@AE@% 
  23556.                                   routine will insert the period 
  23557.                                   automatically if it does not appear in %@AI@%%@AE@%
  23558.                                   %@AI@%ext%@AE@%. If %@AI@%ext%@AE@% is a null character or an 
  23559.                                   empty string, no period is inserted in 
  23560.                                   the composite %@AI@%path%@AE@% string.
  23561.  
  23562. There are no size limits on any of the above four fields. However, the
  23563. composite path must be no larger than the %@AB@%_MAX_PATH%@AE@% constant. The %@AB@%_MAX_PATH%@AE@%
  23564. limit permits a path name much larger than any of the current versions of
  23565. DOS or OS/2 will handle.  %@NL@%
  23566. %@NL@%
  23567. %@NL@%
  23568. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23569. %@NL@%
  23570. None.  %@NL@%
  23571. %@NL@%
  23572. %@NL@%
  23573. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23574. %@NL@%
  23575.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  23576. %@NL@%
  23577. %@NL@%
  23578. %@NL@%
  23579. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23580. %@NL@%
  23581. %@AB@%_fullpath%@AE@%,  %@AB@%_splitpath%@AE@%  %@NL@%
  23582. %@NL@%
  23583. %@NL@%
  23584. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23585. %@NL@%
  23586. %@AS@%  /* MAKEPATH.C */
  23587. %@AS@%  #include <stdlib.h>
  23588. %@AS@%  #include <stdio.h>
  23589. %@AS@%  
  23590. %@AS@%  void main()
  23591. %@AS@%  {
  23592. %@AS@%     char path_buffer[_MAX_PATH];
  23593. %@AS@%     char drive[_MAX_DRIVE];
  23594. %@AS@%     char dir[_MAX_DIR];
  23595. %@AS@%     char fname[_MAX_FNAME];
  23596. %@AS@%     char ext[_MAX_EXT];
  23597. %@AS@%  
  23598. %@AS@%     _makepath( path_buffer, "c", "\\c60\\clibref\\", "makepath", "c" );
  23599. %@AS@%     printf( "Path created with _makepath: %s\n\n", path_buffer );
  23600. %@AS@%     _splitpath( path_buffer, drive, dir, fname, ext );
  23601. %@AS@%     printf( "Path extracted with _splitpath:\n" );
  23602. %@AS@%     printf( "  Drive: %s\n", drive );
  23603. %@AS@%     printf( "  Dir: %s\n", dir );
  23604. %@AS@%     printf( "  Filename: %s\n", fname );
  23605. %@AS@%     printf( "  Ext: %s\n", ext );
  23606. %@AS@%  }%@AE@%%@NL@%
  23607. %@NL@%
  23608. %@NL@%
  23609. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  23610. %@NL@%
  23611. %@AS@%  
  23612. %@AS@%  
  23613. %@AS@%  Path created with _makepath: c:\c60\clibref\makepath.c
  23614. %@AS@%  
  23615. %@AS@%  Path extracted with _splitpath:
  23616. %@AS@%    Drive: c:
  23617. %@AS@%    Dir: \c60\clibref\
  23618. %@AS@%    Filename: makepath
  23619. %@AS@%    Ext: .c %@AE@%%@NL@%
  23620. %@NL@%
  23621.  %@NL@%
  23622. %@NL@%
  23623. %@NL@%
  23624. %@QR:malloc@%%@NL@%
  23625. %@2@%%@CR:C6A01960968 @%%@AB@%malloc Functions%@AE@%%@EH@%%@NL@%
  23626. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23627. %@NL@%
  23628. %@NL@%
  23629. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  23630. %@NL@%
  23631. Allocate memory blocks.  %@NL@%
  23632. %@NL@%
  23633. %@CR:C6A01960969 @%%@CR:C6A01960970 @%%@CR:C6A01960971 @%%@CR:C6A01960972 @%%@CR:C6A01960973 @%%@CR:C6A01960974 @%%@CR:C6A01960975 @%%@CR:C6A01960976 @%  %@NL@%
  23634. %@NL@%
  23635. %@AB@%#include <stdlib.h>%@AE@%               For ANSI compatibility (%@AB@%malloc%@AE@% only)
  23636.  
  23637. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  23638.  
  23639. %@AS@%  void *malloc( size_t size );%@AE@%%@NL@%
  23640. %@NL@%
  23641. %@AS@%  void _based(void) *_bmalloc( _segment seg, size_t size );%@AE@%%@NL@%
  23642. %@NL@%
  23643. %@AS@%  void _far *_fmalloc( size_t size );%@AE@%%@NL@%
  23644. %@NL@%
  23645. %@AS@%  void _near *_nmalloc( size_t size );%@AE@%%@NL@%
  23646. %@NL@%
  23647. %@AI@%size%@AE@%                              Bytes to allocate
  23648.  
  23649. %@AI@%seg%@AE@%                               Based heap segment selector
  23650.  
  23651. %@NL@%
  23652. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23653. %@NL@%
  23654. Functions in the %@AB@%malloc%@AE@% family allocate a memory block of at least %@AI@%size%@AE@%
  23655. bytes. The block may be larger than %@AI@%size%@AE@% bytes because of space required for
  23656. alignment and maintenance information. If %@AI@%size%@AE@% is 0, each of these functions
  23657. allocates a zero-length item in the heap and returns a valid pointer to that
  23658. item.  %@NL@%
  23659. %@NL@%
  23660. The storage space pointed to by the return value is guaranteed to be
  23661. suitably aligned for storage of any type of object. To get a pointer to a
  23662. type other than %@AB@%void%@AE@%, use a type cast on the return value.  %@NL@%
  23663. %@NL@%
  23664. In large data models (compact-, large-, and huge-model programs), %@AB@%malloc%@AE@%
  23665. maps to %@AB@%_fmalloc%@AE@%. In small data models (tiny-, small-, and medium-model
  23666. programs), %@AB@%malloc%@AE@% maps to %@AB@%_nmalloc%@AE@%.  %@NL@%
  23667. %@NL@%
  23668. The %@AB@%_fmalloc%@AE@% function allocates a memory block of at least %@AI@%size%@AE@% bytes in the
  23669. far heap, which is outside the default data segment. The return value is a
  23670. far pointer to %@AB@%void%@AE@%.  %@NL@%
  23671. %@NL@%
  23672. The %@AB@%_bmalloc%@AE@% function allocates a memory block of at least %@AI@%size%@AE@% bytes in the
  23673. based heap segment specified by the segment selector %@AI@%seg%@AE@%.  %@NL@%
  23674. %@NL@%
  23675. The %@AB@%malloc%@AE@% functions allocate memory in the heap segment specified below.  %@NL@%
  23676. %@NL@%
  23677. %@AB@%Function%@AE@%                          %@AB@%Heap Segment%@AE@%
  23678. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23679. %@AB@%malloc%@AE@%                            Depends on data model of program
  23680.  
  23681. %@AB@%_bmalloc%@AE@%                          Based heap segment specified by %@AI@%seg%@AE@% 
  23682.                                   value
  23683.  
  23684. %@AB@%_fmalloc%@AE@%                          Far heap (outside default data segment)
  23685.  
  23686. %@AB@%_nmalloc%@AE@%                          Near heap (within default data segment)
  23687.  
  23688. If you are creating programs to run in both real mode and protected mode,
  23689. you should probably bind with APILMR.OBJ as well as API.LIB and OS2.LIB.
  23690. This is necessary if a program will use the %@AB@%_nmalloc%@AE@% function.  %@NL@%
  23691. %@NL@%
  23692. The functions listed below call the %@AB@%malloc%@AE@% family of routines. In addition,
  23693. the C start-up code uses %@AB@%malloc%@AE@% to allocate storage for the%@AB@% environ%@AE@%/%@AB@%envp%@AE@% and
  23694. %@AB@%argv%@AE@% strings and arrays.  %@NL@%
  23695. %@NL@%
  23696. The following routines call %@AB@%malloc%@AE@%:  %@NL@%
  23697. %@NL@%
  23698. %@TH:  37  1242 01 10 10 56 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%calloc%@AE@%    fseek     %@AB@%_searchenv%@AE@%%@AB@%execv%@AE@%     %@AB@%fsetpos%@AE@%   %@AB@%spawnv%@AE@%%@AB@%execve%@AE@%    %@AB@%fullpath%@AE@%  %@AB@%spawnve%@AE@%%@AB@%execvp%@AE@%    %@AB@%fwrite%@AE@%    %@AB@%spawnvp%@AE@%%@AB@%execvpe%@AE@%   %@AB@%getc%@AE@%      %@AB@%spawnvpe%@AE@%%@AB@%execl%@AE@%     %@AB@%getchar%@AE@%   %@AB@%spawnl%@AE@%%@AB@%execle%@AE@%    %@AB@%getcwd%@AE@%    %@AB@%spawnle%@AE@%%@AB@%execlp%@AE@%    %@AB@%_getcwd%@AE@%   %@AB@%spawnlp%@AE@%%@AB@%execlpe%@AE@%   %@AB@%gets%@AE@%      %@AB@%spawnlpe%@AE@%%@AB@%fgetc%@AE@%     %@AB@%getw%@AE@%      %@AB@%strdup%@AE@%%@AB@%fgetchar%@AE@%  %@AB@%_popen%@AE@%    %@AB@%system%@AE@%%@AB@%fgets%@AE@%     %@AB@%printf%@AE@%    %@AB@%scanf%@AE@%%@AB@%fprint%@AE@%    %@AB@%putc%@AE@%      %@AB@%setvbuf%@AE@%%@AB@%fputc%@AE@%     %@AB@%putchar%@AE@%   %@AB@%tempnam%@AE@%%@AB@%fputchar%@AE@%  %@AB@%putenv%@AE@%    %@AB@%ungetc%@AE@%%@AB@%fputs%@AE@%     %@AB@%puts%@AE@%      %@AB@%vfprintf%@AE@%%@AB@%fread%@AE@%     %@AB@%putw%@AE@%      %@AB@%vprintf%@AE@%%@AB@%fscanf%@AE@%    %@TE:  37  1242 01 10 10 56 @%
  23699.  
  23700. The following routines call %@AB@%malloc %@AE@%only in the multithread run-time
  23701. libraries (LLIBCMT, LLIBCDLL, CDLLOBJS), not in the regular run-time
  23702. libraries:  %@NL@%
  23703. %@NL@%
  23704. %@TH:   9   365 01 14 11 51 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%asctime%@AE@%       %@AB@%localtime%@AE@%  %@AB@%_strerrpr%@AE@%%@AB@%_beginthread%@AE@%  %@AB@%mktime%@AE@%     %@AB@%tmpfile%@AE@%%@AB@%ctime%@AE@%         %@AB@%sterror%@AE@%    %@AB@%tmpnam%@AE@%%@AB@%gmtime%@AE@%        %@TE:   9   365 01 14 11 51 @%
  23705.  
  23706. The following routines call %@AB@%_nmalloc%@AE@%:  %@NL@%
  23707. %@NL@%
  23708. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23709. %@AB@%_nrealloc%@AE@%
  23710.  
  23711. %@AB@%_ncalloc%@AE@%
  23712.  
  23713. %@AB@%_nstrdup%@AE@%
  23714.  
  23715. %@AB@%realloc%@AE@% (in small data models)
  23716.  
  23717.  
  23718. The following routines call %@AB@%_fmalloc%@AE@%:  %@NL@%
  23719. %@NL@%
  23720. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23721. %@AB@%_frealloc%@AE@%
  23722.  
  23723. %@AB@%_fcalloc%@AE@%
  23724.  
  23725. %@AB@%_fstrdup%@AE@%
  23726.  
  23727. %@AB@%realloc%@AE@% (in large data models)
  23728.  
  23729.  
  23730. ────────────────────────────────────────────────────────────────────────────%@NL@%
  23731. %@AB@%C5.1 Differences%@AE@%%@AI@%%@AE@%%@AI@%%@AB@%
  23732. %@AB@%%@AI@%In Microsoft C version 5%@AI@%.1, the %@AE@%%@AI@%_fmalloc%@AE@%%@AI@% function would retry all%@AE@%%@AI@%ocating
  23733. %@AI@%within the default data segment (i.e., in the near heap) if sufficient
  23734. %@AI@%memory was not available outside the default data segment. Version 6.0
  23735. %@AI@%ret%@AE@%%@AI@%urns %@AE@%%@AI@%NULL%@AE@%%@AI@% under t%@AE@%%@AI@%hese conditions.%@AE@%%@AE@%%@NL@%
  23736. %@AI@%In version 5.1, the s%@AI@%tart-up code used %@AE@%%@AI@%malloc%@AE@%%@AI@% only if wild-card expansion
  23737. %@AI@%was used.%@AE@%%@AI@%%@AE@%%@AE@%%@NL@%
  23738.  
  23739. %@AI@%%@AI@%The %@AE@%%@AI@%_freect%@AE@%%@AI@%, %@AE@%%@AI@%_memavl%@AE@%%@AI@%, and%@AE@%%@AI@% _memmax%@AE@%%@AI@% functions called %@AE@%%@AI@%malloc%@AE@%%@AI@% in version 5.1 b%@AE@%%@AI@%ut
  23740. %@AI@%do not do so in version 6.0.%@AE@%%@AE@%%@NL@%
  23741. %@AE@%%@AE@%────────────────────────────────────────────────────────────────────────────%@NL@%%@NL@%
  23742. %@NL@%
  23743. %@NL@%
  23744. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23745. %@NL@%
  23746. The %@AB@%malloc%@AE@% function returns a %@AB@%void%@AE@% pointer to the allocated space. The
  23747. %@AB@%_nmalloc%@AE@% function returns a %@AB@%( void _near * )%@AE@% and %@AB@%_fmalloc%@AE@% returns a %@AB@%( void
  23748. %@AB@%_far * )%@AE@%. The %@AB@%_bmalloc%@AE@% function returns a %@AB@%( void _based( void ) * )%@AE@%.  %@NL@%
  23749. %@NL@%
  23750. The %@AB@%_malloc%@AE@%, %@AB@%_fmalloc%@AE@% and %@AB@%_nmalloc%@AE@% functions return %@AB@%NULL%@AE@% if there is
  23751. insufficient memory available. The %@AB@%_bmalloc%@AE@% function returns %@AB@%_NULLOFF%@AE@% if
  23752. there is insufficient memory available.  %@NL@%
  23753. %@NL@%
  23754. Always check the return from the %@AB@%malloc%@AE@% function, even if the amount of
  23755. memory requested is small.  %@NL@%
  23756. %@NL@%
  23757. %@NL@%
  23758. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23759. %@NL@%
  23760. %@AB@%malloc%@AE@%  %@NL@%
  23761. %@NL@%
  23762. %@AB@%%@AE@% ANSI  %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX%@NL@%
  23763. %@NL@%
  23764. %@NL@%
  23765. %@AB@%_bmalloc, _fmalloc, _nmalloc%@AE@%  %@NL@%
  23766. %@NL@%
  23767.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  23768. %@NL@%
  23769. %@NL@%
  23770. %@NL@%
  23771. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23772. %@NL@%
  23773. %@AB@%calloc%@AE@% functions, %@AB@%free%@AE@% functions, %@AB@%realloc%@AE@% functions   %@NL@%
  23774. %@NL@%
  23775. %@NL@%
  23776. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23777. %@NL@%
  23778. %@AS@%  /* MALLOC.C: This program allocates memory with malloc, then frees
  23779. %@AS@%   * the memory with free.
  23780. %@AS@%   */
  23781. %@AS@%  
  23782. %@AS@%  #include <stdlib.h>         /* Definition of _MAX_PATH */
  23783. %@AS@%  #include <stdio.h>
  23784. %@AS@%  #include <malloc.h>
  23785. %@AS@%  
  23786. %@AS@%  void main()
  23787. %@AS@%  {
  23788. %@AS@%     char *string;
  23789. %@AS@%  
  23790. %@AS@%     /* Allocate space for a path name */
  23791. %@AS@%     string = malloc( _MAX_PATH );
  23792. %@AS@%     if( string == NULL )
  23793. %@AS@%        printf( "Insufficient memory available\n" );
  23794. %@AS@%     else
  23795. %@AS@%        printf( "Memory space allocated for pathname\n" );
  23796. %@AS@%     free( string );
  23797. %@AS@%     printf( "Memory freed\n" );
  23798. %@AS@%  }%@AE@%%@NL@%
  23799. %@NL@%
  23800. %@NL@%
  23801. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  23802. %@NL@%
  23803. %@AS@%  
  23804. %@AS@%  
  23805. %@AS@%  Memory space allocated for pathname
  23806. %@AS@%  Memory freed %@AE@%%@NL@%
  23807. %@NL@%
  23808. %@NL@%
  23809. %@NL@%
  23810. %@NL@%
  23811. %@QR:matherr@%%@QR:_matherrl@%%@NL@%
  23812. %@2@%%@CR:C6A01970977 @%%@AB@%matherr, _matherrl%@AE@%%@EH@%%@NL@%
  23813. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23814. %@NL@%
  23815. %@NL@%
  23816. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  23817. %@NL@%
  23818. Handle math errors.  %@NL@%
  23819. %@NL@%
  23820. %@CR:C6A01970978 @%%@CR:C6A01970979 @%%@AS@%  #include <math.h>%@AE@%%@NL@%
  23821. %@NL@%
  23822. %@AS@%  int matherr( struct exception *except );%@AE@%%@NL@%
  23823. %@NL@%
  23824. %@AS@%  int _matherrl( struct _exceptionl *except );%@AE@%%@NL@%
  23825. %@NL@%
  23826. %@AI@%except%@AE@%                            Pointer to structure containing error 
  23827.                                   information
  23828.  
  23829. %@NL@%
  23830. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  23831. %@NL@%
  23832. The %@AB@%matherr%@AE@% functions process errors generated by the functions of the math
  23833. library. The math functions call the appropriate %@AB@%matherr%@AE@% routine whenever an
  23834. error is detected. The %@AB@%_matherrl%@AE@% function uses the 80-bit, 10-byte
  23835. coprocessor form of arguments and return values. See the reference page on
  23836. the long double functions for more details on this data type.  %@NL@%
  23837. %@NL@%
  23838. The user can provide a different definition of the %@AB@%matherr%@AE@% or %@AB@%_matherrl%@AE@%
  23839. function to carry out special error handling.  %@NL@%
  23840. %@NL@%
  23841. When an error occurs in a math routine, %@AB@%matherr%@AE@% is called with a pointer to
  23842. an %@AB@%exception%@AE@% type structure (defined in%@AB@% %@AE@%MATH.H) as an argument.%@CR:C6A01970980 @%%@CR:C6A01970981 @%  %@NL@%
  23843. %@NL@%
  23844. The %@AB@%exception%@AE@% structure contains the following elements:  %@NL@%
  23845. %@NL@%
  23846. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  23847. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23848. %@AB@%int type%@AE@%                          Exception type
  23849.  
  23850. %@AB@%char *name%@AE@%                        Name of function where error occurred
  23851.  
  23852. %@AB@%double arg1%@AE@%, %@AB@%arg2%@AE@%                 First and second (if any) argument to 
  23853.                                   function
  23854.  
  23855. %@AB@%double%@AE@%%@AI@% %@AE@%%@AB@%retval%@AE@%                     Value to be returned by function
  23856.  
  23857. The%@AB@% type%@AE@% specifies the type of math error. It is one of the following
  23858. values, defined in MATH.H:  %@NL@%
  23859. %@NL@%
  23860. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  23861. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23862. %@AB@%DOMAIN%@AE@%                            Argument domain error %@CR:C6A01970982 @%
  23863.  
  23864. %@AB@%SING%@AE@%                              Argument singularity %@CR:C6A01970983 @%%@CR:C6A01970984 @%
  23865.  
  23866. %@AB@%OVERFLOW%@AE@%                          Overflow range error %@CR:C6A01970985 @%
  23867.  
  23868. %@AB@%PLOSS%@AE@%                             Partial loss of significance %@CR:C6A01970986 @%
  23869.  
  23870. %@AB@%TLOSS%@AE@%                             Total loss of significance %@CR:C6A01970987 @%
  23871.  
  23872. %@AB@%UNDERFLOW%@AE@%                         Underflow range error %@CR:C6A01970988 @%
  23873.  
  23874. The structure member%@AB@% name%@AE@% is a pointer to a null-terminated string
  23875. containing the name of the function that caused the error. The structure
  23876. members %@AB@%arg1%@AE@% and %@AB@%arg2%@AE@% specify the values that caused the error. (If only one
  23877. argument is given, it is stored in %@AB@%arg1%@AE@%.)  %@NL@%
  23878. %@NL@%
  23879. The default return value for the given error is %@AB@%retval%@AE@%. If you change the
  23880. return value, remember that the return value must specify whether an error
  23881. actually occurred. If the %@AB@%matherr%@AE@% function returns 0, an error message is
  23882. displayed and %@AB@%errno%@AE@% is set to an appropriate error value. If %@AB@%matherr%@AE@% returns
  23883. a nonzero value, no error message is displayed, and %@AB@%errno%@AE@% remains unchanged.
  23884. %@NL@%
  23885. %@NL@%
  23886. %@NL@%
  23887. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  23888. %@NL@%
  23889. The %@AB@%matherr%@AE@% functions should return 0 to indicate an error, and a nonzero
  23890. value to indicate successful corrective action.  %@NL@%
  23891. %@NL@%
  23892. %@NL@%
  23893. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  23894. %@NL@%
  23895. %@AB@%matherr%@AE@%  %@NL@%
  23896. %@NL@%
  23897.  ANSI  %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX%@NL@%
  23898. %@NL@%
  23899. %@NL@%
  23900. %@AB@%_matherrl%@AE@%  %@NL@%
  23901. %@NL@%
  23902.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  23903. %@NL@%
  23904. %@NL@%
  23905. %@NL@%
  23906. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  23907. %@NL@%
  23908. %@AB@%acos%@AE@% functions, %@AB@%asin%@AE@% functions, %@AB@%atan%@AE@% functions, %@AB@%bessel%@AE@% functions, %@AB@%cabs%@AE@%, %@AB@%cos%@AE@%
  23909. functions, %@AB@%exp%@AE@%, %@AB@%hypot%@AE@%, %@AB@%log%@AE@% functions, %@AB@%pow%@AE@%, %@AB@%sin%@AE@% functions, %@AB@%sqrt%@AE@%, %@AB@%tan%@AE@%
  23910. functions  %@NL@%
  23911. %@NL@%
  23912. %@NL@%
  23913. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  23914. %@NL@%
  23915. %@AS@%  /* MATHERR.C: To use matherr, you must turn off the Extended Dictionary
  23916. %@AS@%   * flag within the Microsoft Programmer's WorkBench environment, or use
  23917. %@AS@%the 
  23918. %@AS@%   * /NOE linker option outside the environment. For example:
  23919. %@AS@%   *      CL matherr.c /link /NOE
  23920. %@AS@%   */
  23921. %@AS@%  
  23922. %@AS@%  #include <math.h>
  23923. %@AS@%  #include <string.h>
  23924. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  23925. %@NL@%
  23926. %@AS@%  void main()
  23927. %@AS@%  {
  23928. %@AS@%     /* Do several math operations that cause errors. The matherr
  23929. %@AS@%      * routine handles DOMAIN errors, but lets the system handle
  23930. %@AS@%      * other errors normally.
  23931. %@AS@%      */
  23932. %@AS@%     printf( "log( -2.0 ) = %e\n", log( -2.0 ) );
  23933. %@AS@%     printf( "log10( -5.0 ) = %e\n", log10( -5.0 ) );
  23934. %@AS@%     printf( "log( 0.0 ) = %e\n", log( 0.0 ) );
  23935. %@AS@%  }
  23936. %@AS@%  
  23937. %@AS@%  /* Handle several math errors caused by passing a negative argument
  23938. %@AS@%   * to log or log10 (DOMAIN errors). When this happens, matherr returns
  23939. %@AS@%   * the natural or base-10 logarithm of the absolute value of the
  23940. %@AS@%   * argument and suppresses the usual error message.
  23941. %@AS@%   */
  23942. %@AS@%  int matherr( struct exception *except )
  23943. %@AS@%  {
  23944. %@AS@%      /* Handle DOMAIN errors for log or log10. */
  23945. %@AS@%      if( except->type == DOMAIN )
  23946. %@AS@%      {
  23947. %@AS@%          if( strcmp( except->name, "log" ) == 0 )
  23948. %@AS@%          {
  23949. %@AS@%              except->retval = log( -(except->arg1) );
  23950. %@AS@%              printf( "Special: using absolute value: %s: DOMAIN error\n",
  23951. %@AS@%                      except->name );
  23952. %@AS@%              return 1;
  23953. %@AS@%          }
  23954. %@AS@%          else if( strcmp( except->name, "log10" ) == 0 )
  23955. %@AS@%          {
  23956. %@AS@%              except->retval = log10( -(except->arg1) );
  23957. %@AS@%              printf( "Special: using absolute value: %s: DOMAIN error\n",
  23958. %@AS@%                      except->name );
  23959. %@AS@%              return 1;
  23960. %@AS@%          }
  23961. %@AS@%      }
  23962. %@AS@%      else
  23963. %@AS@%      {
  23964. %@AS@%          printf( "Normal: " );
  23965. %@AS@%          return 0;    /* Else use the default actions */
  23966. %@AS@%      }
  23967. %@AS@%  }%@AE@%%@NL@%
  23968. %@NL@%
  23969. %@NL@%
  23970. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  23971. %@NL@%
  23972. %@AS@%  
  23973. %@AS@%  
  23974. %@AS@%  Special: using absolute value: log: DOMAIN error
  23975. %@AS@%  log( -2.0 ) = 6.931472e-001
  23976. %@AS@%  Special: using absolute value: log10: DOMAIN error
  23977. %@AS@%  log10( -5.0 ) = 6.989700e-001
  23978. %@AS@%  Normal: log: SING error
  23979. %@AS@%  log( 0.0 ) = -1.797693e+308 %@AE@%%@NL@%
  23980. %@NL@%
  23981. %@NL@%
  23982. %@NL@%
  23983. %@NL@%
  23984. %@QR:max@%%@NL@%
  23985. %@2@%%@CR:C6A01980989 @%%@AB@%max%@AE@%%@EH@%%@NL@%
  23986. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  23987. %@NL@%
  23988. %@NL@%
  23989. %@3@%%@AB@%Description%@CR:C6A01980990 @%%@CR:C6A01980991 @%%@AE@%%@EH@%%@NL@%
  23990. %@NL@%
  23991. Returns the larger of two values.  %@NL@%
  23992. %@NL@%
  23993. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  23994. %@NL@%
  23995. %@AS@%  type max( type a, type b );%@AE@%%@NL@%
  23996. %@NL@%
  23997. %@AI@%type%@AE@%                              Any numeric data type
  23998.  
  23999. %@AI@%a%@AE@%,%@AI@% b%@AE@%                              Values of any numeric type to be 
  24000.                                   compared
  24001.  
  24002. %@NL@%
  24003. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24004. %@NL@%
  24005. The %@AB@%max%@AE@% macro compares two values and returns the value of the larger one.
  24006. The arguments can be of any numeric data type, signed or unsigned. Both
  24007. arguments and the return value must be of the same data type.  %@NL@%
  24008. %@NL@%
  24009. %@NL@%
  24010. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24011. %@NL@%
  24012. The macro returns the larger of the two arguments.  %@NL@%
  24013. %@NL@%
  24014. %@NL@%
  24015. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24016. %@NL@%
  24017.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24018. %@NL@%
  24019. %@NL@%
  24020. %@NL@%
  24021. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24022. %@NL@%
  24023. %@AB@%min%@AE@%  %@NL@%
  24024. %@NL@%
  24025. %@NL@%
  24026. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24027. %@NL@%
  24028. %@AS@%  /* MINMAX.C */
  24029. %@AS@%  #include <stdlib.h>
  24030. %@AS@%  #include <stdio.h>
  24031. %@AS@%  
  24032. %@AS@%  void main()
  24033. %@AS@%  {
  24034. %@AS@%     int a = 10;
  24035. %@AS@%     int b = 21;
  24036. %@AS@%  
  24037. %@AS@%     printf( "The larger of %d and %d is %d\n",  a, b, max( a, b ) );
  24038. %@AS@%     printf( "The smaller of %d and %d is %d\n", a, b, min( a, b ) );
  24039. %@AS@%  }%@AE@%%@NL@%
  24040. %@NL@%
  24041. %@NL@%
  24042. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24043. %@NL@%
  24044. %@AS@%  
  24045. %@AS@%  
  24046. %@AS@%  The larger of 10 and 21 is 21
  24047. %@AS@%  The smaller of 10 and 21 is 10%@AE@%%@NL@%
  24048. %@NL@%
  24049. %@NL@%
  24050. %@NL@%
  24051. %@NL@%
  24052. %@QR:_memavl@%%@NL@%
  24053. %@2@%%@CR:C6A01990992 @%%@AB@%_memavl%@AE@%%@EH@%%@NL@%
  24054. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24055. %@NL@%
  24056. %@NL@%
  24057. %@3@%%@AB@%Description%@CR:C6A01990993 @%%@CR:C6A01990994 @%%@AE@%%@EH@%%@NL@%
  24058. %@NL@%
  24059. Returns the size of memory available.  %@NL@%
  24060. %@NL@%
  24061. %@AS@%  #include <malloc.h> Required only for function declarations%@AE@%%@NL@%
  24062. %@NL@%
  24063. %@AS@%  size_t _memavl( void );%@AE@%%@NL@%
  24064. %@NL@%
  24065. %@NL@%
  24066. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24067. %@NL@%
  24068. The %@AB@%_memavl%@AE@% function returns the approximate size, in bytes, of the memory
  24069. available for dynamic memory allocation in the near heap (default data
  24070. segment). The %@AB@%_memavl%@AE@% function can be used with %@AB@%calloc%@AE@%, %@AB@%malloc%@AE@%, or %@AB@%realloc%@AE@%
  24071. in tiny, small, and medium memory models and with %@AB@%_ncalloc%@AE@%, %@AB@%_nmalloc%@AE@% or
  24072. %@AB@%_nrealloc%@AE@% in any memory model.  %@NL@%
  24073. %@NL@%
  24074. The number returned by the %@AB@%_memavl%@AE@% function may not be the number of
  24075. contiguous bytes. Consequently, a call to %@AB@%malloc%@AE@% requesting allocation of
  24076. the size returned by %@AB@%_memavl%@AE@% may not succeed. Use the %@AB@%_memmax%@AE@% function to
  24077. find the size of the largest available contiguous block of memory.  %@NL@%
  24078. %@NL@%
  24079. %@NL@%
  24080. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24081. %@NL@%
  24082. The %@AB@%_memavl%@AE@% function returns the size in bytes as an unsigned integer.  %@NL@%
  24083. %@NL@%
  24084. %@NL@%
  24085. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24086. %@NL@%
  24087.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24088. %@NL@%
  24089. %@NL@%
  24090. %@NL@%
  24091. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24092. %@NL@%
  24093. %@AB@%calloc%@AE@% functions,  %@AB@%_freect%@AE@%, %@AB@%malloc%@AE@% functions,  %@AB@%_memmax%@AE@%, %@AB@%realloc%@AE@% functions  %@NL@%
  24094. %@NL@%
  24095. %@NL@%
  24096. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24097. %@NL@%
  24098. %@AS@%  /* MEMAVL.C: This program uses _memavl to determine the amount of
  24099. %@AS@%   * memory available for dynamic allocation. It then uses malloc to
  24100. %@AS@%   * allocate space for 5,000 long integers and uses _memavl again to
  24101. %@AS@%   * determine the new amount of available memory.
  24102. %@AS@%   */
  24103. %@AS@%  
  24104. %@AS@%  #include <malloc.h>
  24105. %@AS@%  #include <stdio.h>
  24106. %@AS@%  
  24107. %@AS@%  void main()
  24108. %@AS@%  {
  24109. %@AS@%     long *longptr;
  24110. %@AS@%  
  24111. %@AS@%     printf( "Memory available before _nmalloc = %u\n", _memavl() );
  24112. %@AS@%     if( (longptr = _nmalloc( 5000 * sizeof( long ) )) != NULL )
  24113. %@AS@%     {
  24114. %@AS@%        printf( "Memory available after _nmalloc = %u\n", _memavl() );
  24115. %@AS@%        _nfree( longptr );
  24116. %@AS@%     }
  24117. %@AS@%  }%@AE@%%@NL@%
  24118. %@NL@%
  24119. %@NL@%
  24120. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24121. %@NL@%
  24122. %@AS@%  
  24123. %@AS@%  
  24124. %@AS@%  Memory available before _nmalloc = 60906
  24125. %@AS@%  Memory available after _nmalloc = 40390%@AE@%%@NL@%
  24126. %@NL@%
  24127. %@NL@%
  24128. %@NL@%
  24129. %@NL@%
  24130. %@QR:memccpy@%%@QR:_fmemccpy@%%@NL@%
  24131. %@2@%%@CR:C6A02000995 @%%@AB@%memccpy, _fmemccpy%@AE@%%@EH@%%@NL@%
  24132. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24133. %@NL@%
  24134. %@NL@%
  24135. %@3@%%@AB@%Description%@CR:C6A02000996 @%%@CR:C6A02000997 @% %@CR:C6A02000998 @%%@CR:C6A02000999 @%%@AE@%%@EH@%%@NL@%
  24136. %@NL@%
  24137. Copy characters from a buffer.  %@NL@%
  24138. %@NL@%
  24139. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations
  24140.  
  24141. %@AB@%#include <string.h>%@AE@%               Use either STRING.H or MEMORY.H
  24142.  
  24143. %@AS@%  void *memccpy( void *dest, void *src, int c, unsigned int count );%@AE@%%@NL@%
  24144. %@NL@%
  24145. %@AS@%  void _far * _far _fmemccpy( void _far *dest, void _far *src, int c,
  24146. %@AS@%  unsigned int count );%@AE@%%@NL@%
  24147. %@NL@%
  24148. %@AI@%dest%@AE@%                              Pointer to destination
  24149.  
  24150. %@AI@%src%@AE@%                               Pointer to source
  24151.  
  24152. %@AI@%c%@AE@%                                 Last character to copy
  24153.  
  24154. %@AI@%count%@AE@%                             Number of characters
  24155.  
  24156. %@NL@%
  24157. %@3@%%@AB@%Remarks%@CR:C6A02001000 @%%@AE@%%@EH@%%@NL@%
  24158. %@NL@%
  24159. The %@AB@%memccpy%@AE@% and %@AB@%_fmemccpy %@AE@%functions copy 0 or more bytes of%@AB@% %@AE@%%@AI@%src%@AE@% to %@AI@%dest%@AE@%,
  24160. halting when the character %@AI@%c%@AE@% has been copied or when %@AI@%count%@AE@% bytes have been
  24161. copied, whichever comes first.  %@NL@%
  24162. %@NL@%
  24163. The %@AB@%_fmemccpy%@AE@% function is a model-independent (large-model) form of the
  24164. %@AB@%memccpy%@AE@% function. It can be called from any point in any program.  %@NL@%
  24165. %@NL@%
  24166. %@NL@%
  24167. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24168. %@NL@%
  24169. If the character %@AI@%c%@AE@% is copied, %@AB@%memccpy%@AE@% or %@AB@%_fmemccpy%@AE@% returns a pointer (or far
  24170. pointer) to the byte in %@AI@%dest%@AE@% that immediately follows the character. If %@AI@%c%@AE@% is
  24171. not copied, %@AB@%memccpy%@AE@% returns %@AB@%NULL%@AE@%.  %@NL@%
  24172. %@NL@%
  24173. %@NL@%
  24174. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24175. %@NL@%
  24176. %@AB@%memccpy%@AE@%  %@NL@%
  24177. %@NL@%
  24178.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   UNIX    XENIX %@NL@%
  24179. %@NL@%
  24180. %@NL@%
  24181. %@AB@%_fmemccpy%@AE@%  %@NL@%
  24182. %@NL@%
  24183.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24184. %@NL@%
  24185. %@NL@%
  24186. %@NL@%
  24187. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24188. %@NL@%
  24189. %@AB@%memchr%@AE@%,%@AB@% memcmp%@AE@%,%@AB@% memcpy%@AE@%,%@AB@% memset%@AE@%  %@NL@%
  24190. %@NL@%
  24191. %@NL@%
  24192. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24193. %@NL@%
  24194. %@AS@%  /* MEMCCPY.C */
  24195. %@AS@%  #include <memory.h>
  24196. %@AS@%  #include <stdio.h>
  24197. %@AS@%  #include <string.h>
  24198. %@AS@%  
  24199. %@AS@%  char string1[60] = "The quick brown dog jumps over the lazy fox";
  24200. %@AS@%  
  24201. %@AS@%  void main()
  24202. %@AS@%  {
  24203. %@AS@%     char buffer[61];
  24204. %@AS@%     char *pdest;
  24205. %@AS@%  
  24206. %@AS@%     printf( "Function:\tmemccpy 60 characters or to character 's'\n" );
  24207. %@AS@%     printf( "Source:\t\t%s\n", string1 );
  24208. %@AS@%     pdest = memccpy( buffer, string1, 's', 60 );
  24209. %@AS@%     *pdest = '\0';
  24210. %@AS@%     printf( "Result:\t\t%s\n", buffer );
  24211. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( buffer ) );
  24212. %@AS@%  }%@AE@%%@NL@%
  24213. %@NL@%
  24214. %@NL@%
  24215. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24216. %@NL@%
  24217. %@AS@%  
  24218. %@AS@%  
  24219. %@AS@%  Function:       memccpy 60 characters or to character 's'
  24220. %@AS@%  Source:         The quick brown dog jumps over the lazy fox
  24221. %@AS@%  Result:         The quick brown dog jumps
  24222. %@AS@%  Length:         25 characters %@AE@%%@NL@%
  24223. %@NL@%
  24224. %@NL@%
  24225. %@NL@%
  24226. %@NL@%
  24227. %@QR:memchr@%%@QR:_fmemchr@%%@NL@%
  24228. %@2@%%@CR:C6A02011001 @%%@AB@%memchr, _fmemchr%@AE@%%@EH@%%@NL@%
  24229. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24230. %@NL@%
  24231. %@NL@%
  24232. %@3@%%@AB@%Description%@CR:C6A02011002 @%%@CR:C6A02011003 @% %@CR:C6A02011004 @%%@CR:C6A02011005 @%%@AE@%%@EH@%%@NL@%
  24233. %@NL@%
  24234. Find characters in a buffer.  %@NL@%
  24235. %@NL@%
  24236. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations
  24237.  
  24238. %@AB@%#include <string.h>%@AE@%               Use either STRING.H (for ANSI 
  24239.                                   compatibility) or MEMORY.H
  24240.  
  24241. %@AS@%  void *memchr( const void *buf, int c, size_t count );%@AE@%%@NL@%
  24242. %@NL@%
  24243. %@AS@%  void _far * _far _fmemchr( const void _far *buf, int c, size_t count );%@AE@%%@NL@%
  24244. %@NL@%
  24245. %@AI@%buf%@AE@%                               Pointer to buffer
  24246.  
  24247. %@AI@%c%@AE@%                                 Character to look for
  24248.  
  24249. %@AI@%count%@AE@%                             Number of characters
  24250.  
  24251. %@NL@%
  24252. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24253. %@NL@%
  24254. The %@AB@%memchr%@AE@% and %@AB@%_fmemchr%@AE@% functions look for the first occurrence of %@AI@%c%@AE@% in the
  24255. first %@AI@%count%@AE@% bytes of %@AI@%buf%@AE@%. They stop when they find %@AI@%c%@AE@% or when they have
  24256. checked the first %@AI@%count%@AE@% bytes. %@CR:C6A02011006 @%  %@NL@%
  24257. %@NL@%
  24258. The %@AB@%_fmemchr%@AE@% function is a model-independent (large-model) form of the
  24259. %@AB@%memchr%@AE@% function. It can be called from any point in any program.  %@NL@%
  24260. %@NL@%
  24261. %@NL@%
  24262. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24263. %@NL@%
  24264. If successful, %@AB@%memchr%@AE@% or %@AB@%_fmemchr%@AE@% returns a pointer (or a far pointer) to
  24265. the first location of %@AI@%c%@AE@% in %@AI@%buf%@AE@%. Otherwise, they return %@AB@%NULL%@AE@%.  %@NL@%
  24266. %@NL@%
  24267. %@NL@%
  24268. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24269. %@NL@%
  24270. %@AB@%memchr%@AE@%  %@NL@%
  24271. %@NL@%
  24272. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  24273. %@NL@%
  24274. %@NL@%
  24275. %@AB@%_fmemchr%@AE@%  %@NL@%
  24276. %@NL@%
  24277.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24278. %@NL@%
  24279. %@NL@%
  24280. %@NL@%
  24281. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24282. %@NL@%
  24283. %@AB@%memccpy%@AE@%,%@AB@% memcmp%@AE@%,%@AB@% memcpy%@AE@%,%@AB@% memset%@AE@%,%@AB@% strchr%@AE@%  %@NL@%
  24284. %@NL@%
  24285. %@NL@%
  24286. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24287. %@NL@%
  24288. %@AS@%  /* MEMCHR.C */
  24289. %@AS@%  #include <memory.h>
  24290. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  24291. %@NL@%
  24292. %@AS@%  int  ch = 'r';
  24293. %@AS@%  char str[] =    "lazy";
  24294. %@AS@%  char string[] = "The quick brown dog jumps over the lazy fox";
  24295. %@AS@%  char fmt1[] =   "         1         2         3         4         5";
  24296. %@AS@%  char fmt2[] =   "12345678901234567890123456789012345678901234567890";
  24297. %@AS@%  
  24298. %@AS@%  void main()
  24299. %@AS@%  {
  24300. %@AS@%     char *pdest;
  24301. %@AS@%     int result;
  24302. %@AS@%  
  24303. %@AS@%     printf( "String to be searched:\n\t\t%s\n", string );
  24304. %@AS@%     printf( "\t\t%s\n\t\t%s\n\n", fmt1, fmt2 );
  24305. %@AS@%  
  24306. %@AS@%     printf( "Search char:\t%c\n", ch );
  24307. %@AS@%     pdest = memchr( string, ch, sizeof( string ) );
  24308. %@AS@%     result = pdest - string + 1;
  24309. %@AS@%     if( pdest != NULL )
  24310. %@AS@%        printf( "Result:\t\t%c found at position %d\n\n", ch, result );
  24311. %@AS@%     else
  24312. %@AS@%        printf( "Result:\t\t%c not found\n" );
  24313. %@AS@%  }%@AE@%%@NL@%
  24314. %@NL@%
  24315. %@NL@%
  24316. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24317. %@NL@%
  24318. %@AS@%  
  24319. %@AS@%  
  24320. %@AS@%  String to be searched:
  24321. %@AS@%                  The quick brown dog jumps over the lazy fox
  24322. %@AS@%                           1         2         3         4         5
  24323. %@AS@%                  12345678901234567890123456789012345678901234567890
  24324. %@AS@%  
  24325. %@AS@%  Search char:    r
  24326. %@AS@%  Result:         r found at position 12 %@AE@%%@NL@%
  24327. %@NL@%
  24328. %@NL@%
  24329. %@NL@%
  24330. %@NL@%
  24331. %@QR:memcmp@%%@QR:_fmemcmp@%%@NL@%
  24332. %@2@%%@CR:C6A02021007 @%%@AB@%memcmp, _fmemcmp%@AE@%%@EH@%%@NL@%
  24333. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24334. %@NL@%
  24335. %@NL@%
  24336. %@3@%%@AB@%Description%@CR:C6A02021008 @%%@CR:C6A02021009 @% %@CR:C6A02021010 @%%@CR:C6A02021011 @%%@AE@%%@EH@%%@NL@%
  24337. %@NL@%
  24338. Compare characters in two buffers.  %@NL@%
  24339. %@NL@%
  24340. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations
  24341.  
  24342. %@AB@%#include <string.h>%@AE@%               Use either STRING.H (for ANSI 
  24343.                                   compatibility) or MEMORY.H
  24344.  
  24345. %@AS@%  int memcmp( const void *buf1, const void *buf2, size_t count );%@AE@%%@NL@%
  24346. %@NL@%
  24347. %@AS@%  int _far _fmemcmp( const void _far *buf1, const void _far *buf2, size_t
  24348. %@AS@%  count );%@AE@%%@NL@%
  24349. %@NL@%
  24350. %@AI@%buf1%@AE@%                              First buffer
  24351.  
  24352. %@AI@%buf2%@AE@%                              Second buffer
  24353.  
  24354. %@AI@%count%@AE@%                             Number of characters
  24355.  
  24356. %@NL@%
  24357. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24358. %@NL@%
  24359. The %@AB@%memcmp%@AE@% and %@AB@%_fmemcmp%@AE@% functions compare the first %@AI@%count%@AE@% bytes of %@AI@%buf1%@AE@% and
  24360. %@AI@%buf2%@AE@% and return a value indicating their relationship, as follows: %@CR:C6A02021012 @%  %@NL@%
  24361. %@NL@%
  24362. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  24363. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24364. < 0                               %@AI@%buf1%@AE@% less than %@AI@%buf2%@AE@%
  24365.  
  24366. = 0                               %@AI@%buf1%@AE@% identical to %@AI@%buf2%@AE@%
  24367.  
  24368. > 0                               %@AI@%buf1%@AE@% greater than %@AI@%buf2%@AE@%
  24369.  
  24370. The %@AB@%_fmemcmp%@AE@% function is a model-independent (large-model) form of the
  24371. %@AB@%memcmp%@AE@% function. It can be called from any point in program.  %@NL@%
  24372. %@NL@%
  24373. There is a semantic difference between the function version of %@AB@%memcmp %@AE@%and
  24374. its intrinsic version. The function version supports huge pointers in
  24375. compact-, large-, and huge-model programs, but the intrinsic version does
  24376. not.  %@NL@%
  24377. %@NL@%
  24378. %@NL@%
  24379. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24380. %@NL@%
  24381. The %@AB@%memcmp%@AE@% function returns an integer value, as described above.  %@NL@%
  24382. %@NL@%
  24383. %@NL@%
  24384. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24385. %@NL@%
  24386. %@AB@%memcmp%@AE@%  %@NL@%
  24387. %@NL@%
  24388. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  24389. %@NL@%
  24390. %@NL@%
  24391. %@AB@%_fmemcmp%@AE@%  %@NL@%
  24392. %@NL@%
  24393.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24394. %@NL@%
  24395. %@NL@%
  24396. %@NL@%
  24397. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24398. %@NL@%
  24399. %@AB@%memccpy%@AE@%, %@AB@%memchr%@AE@%, %@AB@%memcpy%@AE@%, %@AB@%memset%@AE@%, %@AB@%strcmp%@AE@%, %@AB@%strncmp%@AE@%  %@NL@%
  24400. %@NL@%
  24401. %@NL@%
  24402. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24403. %@NL@%
  24404. %@AS@%  /* MEMCMP.C: This program uses memcmp to compare the strings named
  24405. %@AS@%   * first and second. If the first 19 bytes of the strings are
  24406. %@AS@%   * equal, the program considers the strings to be equal.
  24407. %@AS@%   */
  24408. %@AS@%  
  24409. %@AS@%  #include <string.h>
  24410. %@AS@%  #include <stdio.h>
  24411. %@AS@%  
  24412. %@AS@%  void main()
  24413. %@AS@%  {
  24414. %@AS@%     char first[]  = "12345678901234567890";
  24415. %@AS@%     char second[] = "12345678901234567891";
  24416. %@AS@%     int result;
  24417. %@AS@%  
  24418. %@AS@%     printf( "Compare '%.19s' to '%.19s':\n", first, second );
  24419. %@AS@%     result = memcmp( first, second, 19 );
  24420. %@AS@%     if( result < 0 )
  24421. %@AS@%        printf( "First is less than second.\n" );
  24422. %@AS@%     else if( result == 0 )
  24423. %@AS@%        printf( "First is equal to second.\n" );
  24424. %@AS@%     else if( result > 0 )
  24425. %@AS@%        printf( "First is greater than second.\n" );
  24426. %@AS@%     printf( "Compare '%.20s' to '%.20s':\n", first, second );
  24427. %@AS@%     result = memcmp( first, second, 20 );
  24428. %@AS@%     if( result < 0 )
  24429. %@AS@%        printf( "First is less than second.\n" );
  24430. %@AS@%     else if( result == 0 )
  24431. %@AS@%        printf( "First is equal to second.\n" );
  24432. %@AS@%     else if( result > 0 )
  24433. %@AS@%        printf( "First is greater than second.\n" );
  24434. %@AS@%  }%@AE@%%@NL@%
  24435. %@NL@%
  24436. %@NL@%
  24437. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24438. %@NL@%
  24439. %@AS@%  
  24440. %@AS@%  
  24441. %@AS@%  Compare '1234567890123456789' to '1234567890123456789':
  24442. %@AS@%  First is equal to second.
  24443. %@AS@%  Compare '12345678901234567890' to '12345678901234567891':
  24444. %@AS@%  First is less than second. %@AE@%%@NL@%
  24445. %@NL@%
  24446. %@NL@%
  24447. %@NL@%
  24448. %@NL@%
  24449. %@QR:memcpy@%%@QR:_fmemcpy@%%@NL@%
  24450. %@2@%%@CR:C6A02031013 @%%@AB@%memcpy, _fmemcpy%@AE@%%@EH@%%@NL@%
  24451. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24452. %@NL@%
  24453. %@NL@%
  24454. %@3@%%@AB@%Description%@CR:C6A02031014 @%%@CR:C6A02031015 @% %@CR:C6A02031016 @%%@CR:C6A02031017 @%%@AE@%%@EH@%%@NL@%
  24455. %@NL@%
  24456. Copy characters between buffers.  %@NL@%
  24457. %@NL@%
  24458. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations%@AB@%%@AE@%
  24459.  
  24460. %@AB@%#include <string.h>%@AE@%               Use either STRING.H (for ANSI 
  24461.                                   compatibility) or MEMORY.H
  24462.  
  24463. %@AS@%  void *memcpy( void *dest, const void *src, size_t count );%@AE@%%@NL@%
  24464. %@NL@%
  24465. %@AS@%  void _far  * _far _fmemcpy( void _far *dest, const void _far *src, size_t
  24466. %@AS@%  count );%@AE@%%@NL@%
  24467. %@NL@%
  24468. %@AI@%dest%@AE@%                              New buffer
  24469.  
  24470. %@AI@%src%@AE@%                               Buffer to copy from
  24471.  
  24472. %@AI@%count%@AE@%                             Number of characters to copy
  24473.  
  24474. %@NL@%
  24475. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24476. %@NL@%
  24477. The %@AB@%memcpy%@AE@% and %@AB@%_fmemcpy%@AE@% functions copy %@AI@%count%@AE@% bytes of %@AI@%src%@AE@% to %@AI@%dest%@AE@%. If the
  24478. source and destination overlap, these functions do not ensure that the
  24479. original source bytes in the overlapping region are copied before being
  24480. overwritten. Use %@AB@%memmove%@AE@% to handle overlapping regions. %@CR:C6A02031018 @%%@CR:C6A02031019 @%  %@NL@%
  24481. %@NL@%
  24482. The %@AB@%_fmemcpy%@AE@% function is a model-independent (large-model) form of the
  24483. %@AB@%memcpy%@AE@% function. It can be called from any point in any program.  %@NL@%
  24484. %@NL@%
  24485. There is a semantic difference between the function version of %@AB@%memcpy%@AE@% and
  24486. its intrinsic version. The function version supports huge pointers in
  24487. compact-, large-, and huge-model programs, but the intrinsic version does
  24488. not.  %@NL@%
  24489. %@NL@%
  24490. %@NL@%
  24491. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24492. %@NL@%
  24493. The %@AB@%memcpy%@AE@% and %@AB@%_fmemcpy%@AE@% functions return a pointer to %@AI@%dest%@AE@%.  %@NL@%
  24494. %@NL@%
  24495. %@NL@%
  24496. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24497. %@NL@%
  24498. %@AB@%memcpy%@AE@%  %@NL@%
  24499. %@NL@%
  24500. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  24501. %@NL@%
  24502. %@NL@%
  24503. %@AB@%_fmemcpy%@AE@%  %@NL@%
  24504. %@NL@%
  24505.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24506. %@NL@%
  24507. %@NL@%
  24508. %@NL@%
  24509. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24510. %@NL@%
  24511. %@AB@%memccpy%@AE@%, %@AB@%memchr%@AE@%, %@AB@%memcmp%@AE@%, %@AB@%memmove%@AE@%, %@AB@%memset%@AE@%, %@AB@%strcpy%@AE@%, %@AB@%strncpy%@AE@%  %@NL@%
  24512. %@NL@%
  24513. %@NL@%
  24514. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24515. %@NL@%
  24516. %@AS@%  /* MEMCPY.C. Illustrate overlapping copy: memmove handles it
  24517. %@AS@%   * correctly; memcpy does not.
  24518. %@AS@%   */
  24519. %@AS@%  #include <memory.h>
  24520. %@AS@%  #include <string.h>
  24521. %@AS@%  #include <stdio.h>
  24522. %@AS@%  
  24523. %@AS@%  char string1[60] = "The quick brown dog jumps over the lazy fox";
  24524. %@AS@%  char string2[60] = "The quick brown fox jumps over the lazy dog";
  24525. %@AS@%  /*                           1         2         3         4         5 
  24526. %@AS@%   *                  12345678901234567890123456789012345678901234567890 
  24527. %@AS@%   */
  24528. %@AS@%  void main()
  24529. %@AS@%  {
  24530. %@AS@%     printf( "Function:\tmemcpy without overlap\n" );
  24531. %@AS@%     printf( "Source:\t\t%s\n", string1 + 40 );
  24532. %@AS@%     printf( "Destination:\t%s\n", string1 + 16 );
  24533. %@AS@%     memcpy( string1 + 16, string1 + 40, 3 );
  24534. %@AS@%     printf( "Result:\t\t%s\n", string1 );
  24535. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );
  24536. %@AS@%  
  24537. %@AS@%     /* Restore string1 to original contents */
  24538. %@AS@%     memcpy( string1 + 16, string2 + 40, 3 );
  24539. %@AS@%  
  24540. %@AS@%     printf( "Function:\tmemmove with overlap\n" );
  24541. %@AS@%     printf( "Source:\t\t%s\n", string2 + 4 );
  24542. %@AS@%     printf( "Destination:\t%s\n", string2 + 10 );
  24543. %@AS@%     memmove( string2 + 10, string2 + 4, 40 );
  24544. %@AS@%     printf( "Result:\t\t%s\n", string2 );
  24545. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( string2 ) );
  24546. %@AS@%  
  24547. %@AS@%     printf( "Function:\tmemcpy with overlap\n" );
  24548. %@AS@%     printf( "Source:\t\t%s\n", string1 + 4 );
  24549. %@AS@%     printf( "Destination:\t%s\n", string1 + 10 );
  24550. %@AS@%     memcpy( string1 + 10, string1 + 4, 40 );
  24551. %@AS@%     printf( "Result:\t\t%s\n", string1 );
  24552. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );
  24553. %@AS@%  
  24554. %@AS@%  }%@AE@%%@NL@%
  24555. %@NL@%
  24556. %@NL@%
  24557. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24558. %@NL@%
  24559. %@AS@%  
  24560. %@AS@%  
  24561. %@AS@%  Function:       memcpy without overlap
  24562. %@AS@%  Source:         fox
  24563. %@AS@%  Destination:    dog jumps over the lazy fox
  24564. %@AS@%  Result:         The quick brown fox jumps over the lazy fox
  24565. %@AS@%  Length:         43 characters
  24566. %@AS@%  
  24567. %@AS@%  Function:       memmove with overlap
  24568. %@AS@%  Source:         quick brown fox jumps over the lazy dog
  24569. %@AS@%  Destination:    brown fox jumps over the lazy dog
  24570. %@AS@%  Result:         The quick quick brown fox jumps over the lazy dog
  24571. %@AS@%  Length:         49 characters
  24572. %@AS@%  
  24573. %@AS@%  Function:       memcpy with overlap
  24574. %@AS@%  Source:         quick brown dog jumps over the lazy fox
  24575. %@AS@%  Destination:    brown dog jumps over the lazy fox
  24576. %@AS@%  Result:         The quick quick quick quick quick quick quick quic
  24577. %@AS@%  Length:         50 characters %@AE@%%@NL@%
  24578. %@NL@%
  24579. %@NL@%
  24580. %@NL@%
  24581. %@NL@%
  24582. %@QR:memicmp@%%@QR:_fmemicmp@%%@NL@%
  24583. %@2@%%@CR:C6A02041020 @%%@AB@%memicmp, _fmemicmp%@AE@%%@EH@%%@NL@%
  24584. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24585. %@NL@%
  24586. %@NL@%
  24587. %@3@%%@AB@%Description%@CR:C6A02041021 @%%@CR:C6A02041022 @% %@CR:C6A02041023 @%%@CR:C6A02041024 @%%@AE@%%@EH@%%@NL@%
  24588. %@NL@%
  24589. Compare characters in two buffers (case-insensitive).  %@NL@%
  24590. %@NL@%
  24591. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations
  24592.  
  24593. %@AB@%#include <string.h>%@AE@%               Use either STRING.H or MEMORY.H
  24594.  
  24595. %@AS@%  int memicmp( void *buf1, void *buf2, unsigned int count );%@AE@%%@NL@%
  24596. %@NL@%
  24597. %@AS@%  int _far _fmemicmp( void _far *buf1, void _far *buf2, unsigned int count
  24598. %@AS@%  );%@AE@%%@NL@%
  24599. %@NL@%
  24600. %@AI@%buf1%@AE@%                              First buffer
  24601.  
  24602. %@AI@%buf2%@AE@%                              Second buffer
  24603.  
  24604. %@AI@%count%@AE@%                             Number of characters
  24605.  
  24606. %@NL@%
  24607. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24608. %@NL@%
  24609. The %@AB@%memicmp%@AE@% and %@AB@%_fmemicmp%@AE@% functions compare the first %@AI@%count%@AE@% characters of
  24610. the two buffers %@AI@%buf1%@AE@% and %@AI@%buf2%@AE@% byte-by-byte. The comparison is made without
  24611. regard to the case of letters in the two buffers; that is, uppercase and
  24612. lowercase letters are considered equivalent. The %@AB@%memicmp%@AE@% and %@AB@%_fmemicmp%@AE@%
  24613. functions return a value indicating the relationship of the two buffers, as
  24614. follows: %@CR:C6A02041025 @%  %@NL@%
  24615. %@NL@%
  24616. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  24617. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24618. < 0                               %@AI@%buf1%@AE@% less than %@AI@%buf2%@AE@%
  24619.  
  24620. = 0                               %@AI@%buf1%@AE@% identical to %@AI@%buf2%@AE@%
  24621.  
  24622. > 0                               %@AI@%buf1%@AE@% greater than %@AI@%buf2%@AE@%
  24623.  
  24624. The %@AB@%_fmemicmp%@AE@% function is a model-independent (large-model) form of the
  24625. %@AB@%memicmp%@AE@% function. It can be called from any point in any program.  %@NL@%
  24626. %@NL@%
  24627. %@NL@%
  24628. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24629. %@NL@%
  24630. The %@AB@%memicmp%@AE@% and %@AB@%_fmemicmp%@AE@% functions return an integer value, as described
  24631. above.  %@NL@%
  24632. %@NL@%
  24633. %@NL@%
  24634. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24635. %@NL@%
  24636. %@AB@%memicmp%@AE@%  %@NL@%
  24637. %@NL@%
  24638.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  24639. %@NL@%
  24640. %@NL@%
  24641. %@AB@%_fmemicmp%@AE@%  %@NL@%
  24642. %@NL@%
  24643.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24644. %@NL@%
  24645. %@NL@%
  24646. %@NL@%
  24647. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24648. %@NL@%
  24649. %@AB@%memccpy%@AE@%, %@AB@%memchr%@AE@%, %@AB@%memcmp%@AE@%, %@AB@%memcpy%@AE@%, %@AB@%memset%@AE@%, %@AB@%stricmp%@AE@%, %@AB@%strnicmp%@AE@%  %@NL@%
  24650. %@NL@%
  24651. %@NL@%
  24652. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24653. %@NL@%
  24654. %@AS@%  /* MEMICMP.C: This program uses memicmp to compare the first
  24655. %@AS@%   * 29 letters of the strings named first and second without
  24656. %@AS@%   * regard to the case of the letters.
  24657. %@AS@%   */
  24658. %@AS@%  
  24659. %@AS@%  #include <memory.h>
  24660. %@AS@%  #include <stdio.h>
  24661. %@AS@%  #include <string.h>
  24662. %@AS@%  
  24663. %@AS@%  void main()
  24664. %@AS@%  {
  24665. %@AS@%     int result;
  24666. %@AS@%     char first[]  = "Those Who Will Not Learn from History";
  24667. %@AS@%     char second[] = "THOSE WHO WILL NOT LEARN FROM their mistakes";
  24668. %@AS@%     /* Note that the 29th character is right here ^ */
  24669. %@AS@%  
  24670. %@AS@%     printf( "Compare '%.29s' to '%.29s'\n", first, second );
  24671. %@AS@%     result = memicmp( first, second, 29 );
  24672. %@AS@%     if( result < 0 )
  24673. %@AS@%        printf( "First is less than second.\n" );
  24674. %@AS@%     else if( result == 0 )
  24675. %@AS@%        printf( "First is equal to second.\n" );
  24676. %@AS@%     else if( result > 0 )
  24677. %@AS@%        printf( "First is greater than second.\n" );
  24678. %@AS@%  }%@AE@%%@NL@%
  24679. %@NL@%
  24680. %@NL@%
  24681. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24682. %@NL@%
  24683. %@AS@%  
  24684. %@AS@%  
  24685. %@AS@%  Compare 'Those Who Will Not Learn from' to 'THOSE WHO WILL NOT LEARN FROM'
  24686. %@AS@%  First is equal to second. %@AE@%%@NL@%
  24687. %@NL@%
  24688. %@NL@%
  24689. %@NL@%
  24690. %@NL@%
  24691. %@QR:_memmax@%%@NL@%
  24692. %@2@%%@CR:C6A02051026 @%%@AB@%_memmax%@AE@%%@EH@%%@NL@%
  24693. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24694. %@NL@%
  24695. %@NL@%
  24696. %@3@%%@AB@%Description%@CR:C6A02051027 @%%@CR:C6A02051028 @%%@AE@%%@EH@%%@NL@%
  24697. %@NL@%
  24698. Finds the size of the largest contiguous memory block.  %@NL@%
  24699. %@NL@%
  24700. %@AS@%  #include <malloc.h>%@AE@%%@NL@%
  24701. %@NL@%
  24702. %@AS@%  size_t _memmax( void );%@AE@%%@NL@%
  24703. %@NL@%
  24704. %@NL@%
  24705. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24706. %@NL@%
  24707. The %@AB@%_memmax%@AE@% function returns the size (in bytes) of the largest contiguous
  24708. block of memory that can be allocated from the near heap (i.e., the default
  24709. data segment). Calling %@AB@%_nmalloc%@AE@% with the value returned by the %@AB@%_memmax%@AE@%
  24710. function will succeed as long as %@AB@%_memmax%@AE@% returns a nonzero value.  %@NL@%
  24711. %@NL@%
  24712. %@NL@%
  24713. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24714. %@NL@%
  24715. The function returns the block size, if successful. Otherwise, it returns 0,
  24716. indicating that nothing more can be allocated from the near heap.  %@NL@%
  24717. %@NL@%
  24718. %@NL@%
  24719. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24720. %@NL@%
  24721.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24722. %@NL@%
  24723. %@NL@%
  24724. %@NL@%
  24725. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24726. %@NL@%
  24727. %@AB@%malloc%@AE@% functions, %@AB@%msize%@AE@% functions  %@NL@%
  24728. %@NL@%
  24729. %@NL@%
  24730. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24731. %@NL@%
  24732. %@AS@%  /* MEMMAX.C: This program uses _memmax and _nmalloc to allocate
  24733. %@AS@%   * the largest block of memory available in the near heap.
  24734. %@AS@%   */
  24735. %@AS@%  
  24736. %@AS@%  #include <stddef.h>
  24737. %@AS@%  #include <malloc.h>
  24738. %@AS@%  #include <stdio.h>
  24739. %@AS@%  
  24740. %@AS@%  void main()
  24741. %@AS@%  {
  24742. %@AS@%     size_t contig;
  24743. %@AS@%     char *p;%@AE@%%@NL@%
  24744. %@NL@%
  24745. %@AS@%  /* Determine contiguous memory size */
  24746. %@AS@%     contig = _memmax();
  24747. %@AS@%     printf( "Largest block of available memory is %u bytes long\n", contig
  24748. %@AS@%);
  24749. %@AS@%     if( contig )
  24750. %@AS@%     {
  24751. %@AS@%        p = _nmalloc( contig * sizeof( int ) );
  24752. %@AS@%        if( p == NULL )
  24753. %@AS@%           printf( "Error with malloc (should never occur)\n" );
  24754. %@AS@%        else
  24755. %@AS@%        {
  24756. %@AS@%           printf( "Maximum allocation succeeded\n" );
  24757. %@AS@%           free( p );
  24758. %@AS@%        }
  24759. %@AS@%     }
  24760. %@AS@%     else
  24761. %@AS@%        printf( "Near heap is already full\n" );
  24762. %@AS@%  }%@AE@%%@NL@%
  24763. %@NL@%
  24764. %@NL@%
  24765. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24766. %@NL@%
  24767. %@AS@%  
  24768. %@AS@%  
  24769. %@AS@%  Largest block of available memory is 60844 bytes long
  24770. %@AS@%  Maximum allocation succeeded%@AE@%%@NL@%
  24771. %@NL@%
  24772. %@NL@%
  24773. %@NL@%
  24774. %@NL@%
  24775. %@QR:memmove@%%@QR:_fmemmove@%%@NL@%
  24776. %@2@%%@CR:C6A02061029 @%%@AB@%memmove, _fmemmove%@AE@%%@EH@%%@NL@%
  24777. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24778. %@NL@%
  24779. %@NL@%
  24780. %@3@%%@AB@%Description%@CR:C6A02061030 @%%@CR:C6A02061031 @% %@CR:C6A02061032 @%%@CR:C6A02061033 @%%@AE@%%@EH@%%@NL@%
  24781. %@NL@%
  24782. Move one buffer to another.  %@NL@%
  24783. %@NL@%
  24784. %@AS@%  #include <string.h>%@AE@%%@NL@%
  24785. %@NL@%
  24786. %@AS@%  void *memmove( void *dest, const void *src, size_t count );%@AE@%%@NL@%
  24787. %@NL@%
  24788. %@AS@%  void _far * _far _fmemmove( void _far *dest, const void _far *src, size_t
  24789. %@AS@%  count );%@AE@%%@NL@%
  24790. %@NL@%
  24791. %@AI@%dest%@AE@%                              Destination object
  24792.  
  24793. %@AI@%src%@AE@%                               Source object
  24794.  
  24795. %@AI@%count%@AE@%                             Number of characters to copy
  24796.  
  24797. %@NL@%
  24798. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24799. %@NL@%
  24800. The %@AB@%memmove%@AE@% and %@AB@%_fmemmove%@AE@% functions copy %@AI@%count%@AE@% characters from the source
  24801. (%@AI@%src%@AE@%) to the destination (%@AI@%dest%@AE@%). If some regions of the source area and the
  24802. destination overlap, the %@AB@%memmove%@AE@% and %@AB@%_fmemmove%@AE@% functions ensure that the
  24803. original source bytes in the overlapping region are copied before being
  24804. overwritten.  %@NL@%
  24805. %@NL@%
  24806. The %@AB@%_fmemmove%@AE@% function is a model-independent (large-model) form of the
  24807. %@AB@%memmove%@AE@% function. It can be called from any point in any program.  %@NL@%
  24808. %@NL@%
  24809. %@NL@%
  24810. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24811. %@NL@%
  24812. The %@AB@%memmove%@AE@% and %@AB@%_fmemmove%@AE@% functions return the value of %@AI@%dest%@AE@%.  %@NL@%
  24813. %@NL@%
  24814. %@NL@%
  24815. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24816. %@NL@%
  24817. %@AB@%memmove%@AE@%  %@NL@%
  24818. %@NL@%
  24819. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24820. %@NL@%
  24821. %@NL@%
  24822. %@AB@%_fmemmove%@AE@%  %@NL@%
  24823. %@NL@%
  24824.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  24825. %@NL@%
  24826. %@NL@%
  24827. %@NL@%
  24828. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24829. %@NL@%
  24830. %@AB@%memccpy%@AE@%, %@AB@%memcpy%@AE@%, %@AB@%strccpy%@AE@%, %@AB@%strncpy%@AE@%  %@NL@%
  24831. %@NL@%
  24832. %@NL@%
  24833. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24834. %@NL@%
  24835. %@AS@%  /* MEMCPY.C. Illustrate overlapping copy: memmove handles it
  24836. %@AS@%   * correctly; memcpy does not.
  24837. %@AS@%   */
  24838. %@AS@%  #include <memory.h>
  24839. %@AS@%  #include <string.h>
  24840. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  24841. %@NL@%
  24842. %@AS@%  char string1[60] = "The quick brown dog jumps over the lazy fox";
  24843. %@AS@%  char string2[60] = "The quick brown fox jumps over the lazy dog";
  24844. %@AS@%  /*                           1         2         3         4         5 
  24845. %@AS@%   *                  12345678901234567890123456789012345678901234567890 
  24846. %@AS@%   */
  24847. %@AS@%  void main()
  24848. %@AS@%  {
  24849. %@AS@%     printf( "Function:\tmemcpy without overlap\n" );
  24850. %@AS@%     printf( "Source:\t\t%s\n", string1 + 40 );
  24851. %@AS@%     printf( "Destination:\t%s\n", string1 + 16 );
  24852. %@AS@%     memcpy( string1 + 16, string1 + 40, 3 );
  24853. %@AS@%     printf( "Result:\t\t%s\n", string1 );
  24854. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );
  24855. %@AS@%  
  24856. %@AS@%     /* Restore string1 to original contents */
  24857. %@AS@%     memcpy( string1 + 16, string2 + 40, 3 );
  24858. %@AS@%  
  24859. %@AS@%     printf( "Function:\tmemmove with overlap\n" );
  24860. %@AS@%     printf( "Source:\t\t%s\n", string2 + 4 );
  24861. %@AS@%     printf( "Destination:\t%s\n", string2 + 10 );
  24862. %@AS@%     memmove( string2 + 10, string2 + 4, 40 );
  24863. %@AS@%     printf( "Result:\t\t%s\n", string2 );
  24864. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( string2 ) );
  24865. %@AS@%  
  24866. %@AS@%     printf( "Function:\tmemcpy with overlap\n" );
  24867. %@AS@%     printf( "Source:\t\t%s\n", string1 + 4 );
  24868. %@AS@%     printf( "Destination:\t%s\n", string1 + 10 );
  24869. %@AS@%     memcpy( string1 + 10, string1 + 4, 40 );
  24870. %@AS@%     printf( "Result:\t\t%s\n", string1 );
  24871. %@AS@%     printf( "Length:\t\t%d characters\n\n", strlen( string1 ) );
  24872. %@AS@%  
  24873. %@AS@%  }%@AE@%%@NL@%
  24874. %@NL@%
  24875. %@NL@%
  24876. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24877. %@NL@%
  24878. %@AS@%  
  24879. %@AS@%  
  24880. %@AS@%  Function:       memcpy without overlap
  24881. %@AS@%  Source:         fox
  24882. %@AS@%  Destination:    dog jumps over the lazy fox
  24883. %@AS@%  Result:         The quick brown fox jumps over the lazy fox
  24884. %@AS@%  Length:         43 characters
  24885. %@AS@%  
  24886. %@AS@%  Function:       memmove with overlap
  24887. %@AS@%  Source:         quick brown fox jumps over the lazy dog
  24888. %@AS@%  Destination:    brown fox jumps over the lazy dog
  24889. %@AS@%  Result:         The quick quick brown fox jumps over the lazy dog
  24890. %@AS@%  Length:         49 characters%@AE@%%@NL@%
  24891. %@NL@%
  24892. %@AS@%  Function:       memcpy with overlap
  24893. %@AS@%  Source:         quick brown dog jumps over the lazy fox
  24894. %@AS@%  Destination:    brown dog jumps over the lazy fox
  24895. %@AS@%  Result:         The quick quick quick quick quick quick quick quic
  24896. %@AS@%  Length:         50 characters %@AE@%%@NL@%
  24897. %@NL@%
  24898. %@NL@%
  24899. %@NL@%
  24900. %@NL@%
  24901. %@QR:memset@%%@QR:_fmemset@%%@NL@%
  24902. %@2@%%@CR:C6A02071034 @%%@AB@%memset, _fmemset%@AE@%%@EH@%%@NL@%
  24903. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24904. %@NL@%
  24905. %@NL@%
  24906. %@3@%%@AB@%Description%@CR:C6A02071035 @%%@CR:C6A02071036 @% %@CR:C6A02071037 @%%@CR:C6A02071038 @%%@AE@%%@EH@%%@NL@%
  24907. %@NL@%
  24908. Set buffers to a specified character.  %@NL@%
  24909. %@NL@%
  24910. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations
  24911.  
  24912. %@AB@%#include <string.h>%@AE@%               Use either STRING.H (for ANSI 
  24913.                                   compatibility) or MEMORY.H
  24914.  
  24915. %@AS@%  void *memset( void *dest, int c, size_t count );%@AE@%%@NL@%
  24916. %@NL@%
  24917. %@AS@%  void _far * _far _fmemset( void _far *dest, int c, size_t count );%@AE@%%@NL@%
  24918. %@NL@%
  24919. %@AI@%dest%@AE@%                              Pointer to destination
  24920.  
  24921. %@AI@%c%@AE@%                                 Character to set
  24922.  
  24923. %@AI@%count%@AE@%                             Number of characters
  24924.  
  24925. %@NL@%
  24926. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  24927. %@NL@%
  24928. The %@AB@%memset%@AE@% and %@AB@%_fmemset%@AE@% functions set the first %@AI@%count%@AE@% bytes of %@AI@%dest%@AE@% to the
  24929. character %@AI@%c%@AE@%.%@CR:C6A02071039 @%  %@NL@%
  24930. %@NL@%
  24931. The %@AB@%_fmemset%@AE@% function is a model-independent (large-model) form of the
  24932. %@AB@%memset%@AE@% function. It can be called from any point in any program.  %@NL@%
  24933. %@NL@%
  24934. There is a semantic difference between the function version of %@AB@%memset%@AE@% and
  24935. its intrinsic version. The function version supports huge pointers in
  24936. compact-, large-, and huge-model programs, but the intrinsic version does
  24937. not.  %@NL@%
  24938. %@NL@%
  24939. %@NL@%
  24940. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  24941. %@NL@%
  24942. The %@AB@%memset%@AE@% and %@AB@%_fmemset%@AE@% functions return a pointer to %@AI@%dest%@AE@%.  %@NL@%
  24943. %@NL@%
  24944. %@NL@%
  24945. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  24946. %@NL@%
  24947. %@AB@%memset%@AE@%  %@NL@%
  24948. %@NL@%
  24949. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  24950. %@NL@%
  24951. %@NL@%
  24952. %@AB@%_fmemset%@AE@%  %@NL@%
  24953. %@NL@%
  24954.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   UNIX    XENIX %@NL@%
  24955. %@NL@%
  24956. %@NL@%
  24957. %@NL@%
  24958. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  24959. %@NL@%
  24960. %@AB@%memccpy%@AE@%, %@AB@%memchr%@AE@%, %@AB@%memcmp%@AE@%, %@AB@%memcpy%@AE@%, %@AB@%strnset%@AE@%  %@NL@%
  24961. %@NL@%
  24962. %@NL@%
  24963. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  24964. %@NL@%
  24965. %@AS@%  /* MEMSET.C: This program uses memset to set the first four bytes
  24966. %@AS@%   * of buffer to "*".
  24967. %@AS@%   */%@AE@%%@NL@%
  24968. %@NL@%
  24969. %@AS@%  #include <memory.h>
  24970. %@AS@%  #include <stdio.h>
  24971. %@AS@%  
  24972. %@AS@%  void main()
  24973. %@AS@%  {
  24974. %@AS@%     char buffer[] = "This is a test of the memset function";
  24975. %@AS@%  
  24976. %@AS@%     printf( "Before: %s\n", buffer );
  24977. %@AS@%     memset( buffer, '*', 4 );
  24978. %@AS@%     printf( "After:  %s\n", buffer );
  24979. %@AS@%  }%@AE@%%@NL@%
  24980. %@NL@%
  24981. %@NL@%
  24982. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  24983. %@NL@%
  24984. %@AS@%  
  24985. %@AS@%  
  24986. %@AS@%  Before: This is a test of the memset function
  24987. %@AS@%  After:  **** is a test of the memset function %@AE@%%@NL@%
  24988. %@NL@%
  24989. %@NL@%
  24990. %@NL@%
  24991. %@NL@%
  24992. %@QR:min@%%@NL@%
  24993. %@2@%%@CR:C6A02081040 @%%@AB@%min%@AE@%%@EH@%%@NL@%
  24994. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  24995. %@NL@%
  24996. %@NL@%
  24997. %@3@%%@AB@%Description%@CR:C6A02081041 @%%@CR:C6A02081042 @%%@AE@%%@EH@%%@NL@%
  24998. %@NL@%
  24999. Returns the smaller of two values.  %@NL@%
  25000. %@NL@%
  25001. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  25002. %@NL@%
  25003. %@AS@%  type min( type a, type b );%@AE@%%@NL@%
  25004. %@NL@%
  25005. %@AI@%type%@AE@%                              Any numeric data type
  25006.  
  25007. %@AI@%a%@AE@%,%@AI@% b%@AE@%                              Values of any numeric type to be 
  25008.                                   compared
  25009.  
  25010. %@NL@%
  25011. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25012. %@NL@%
  25013. The %@AB@%min%@AE@% macro compares two values and returns the value of the smaller one.
  25014. The arguments can be of any numeric data type, signed or unsigned. Both
  25015. arguments and the return value must be of the same data type.  %@NL@%
  25016. %@NL@%
  25017. %@NL@%
  25018. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25019. %@NL@%
  25020. The macro returns the smaller of the two arguments.  %@NL@%
  25021. %@NL@%
  25022. %@NL@%
  25023. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25024. %@NL@%
  25025.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  25026. %@NL@%
  25027. %@NL@%
  25028. %@NL@%
  25029. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25030. %@NL@%
  25031. %@AB@%max%@AE@%  %@NL@%
  25032. %@NL@%
  25033. %@NL@%
  25034. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25035. %@NL@%
  25036. %@AS@%  /* MINMAX.C */
  25037. %@AS@%  #include <stdlib.h>
  25038. %@AS@%  #include <stdio.h>
  25039. %@AS@%  
  25040. %@AS@%  void main()
  25041. %@AS@%  {
  25042. %@AS@%     int a = 10;
  25043. %@AS@%     int b = 21;
  25044. %@AS@%  
  25045. %@AS@%     printf( "The larger of %d and %d is %d\n",  a, b, max( a, b ) );
  25046. %@AS@%     printf( "The smaller of %d and %d is %d\n", a, b, min( a, b ) );
  25047. %@AS@%  }%@AE@%%@NL@%
  25048. %@NL@%
  25049. %@NL@%
  25050. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25051. %@NL@%
  25052. %@AS@%  
  25053. %@AS@%  
  25054. %@AS@%  The larger of 10 and 21 is 21
  25055. %@AS@%  The smaller of 10 and 21 is 10%@AE@%%@NL@%
  25056. %@NL@%
  25057. %@NL@%
  25058. %@NL@%
  25059. %@NL@%
  25060. %@QR:mkdir@%%@NL@%
  25061. %@2@%%@CR:C6A02091043 @%%@AB@%mkdir%@AE@%%@EH@%%@NL@%
  25062. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25063. %@NL@%
  25064. %@NL@%
  25065. %@3@%%@AB@%Description%@CR:C6A02091044 @%%@CR:C6A02091045 @%%@CR:C6A02091046 @%%@AE@%%@EH@%%@NL@%
  25066. %@NL@%
  25067. Creates a new directory.  %@NL@%
  25068. %@NL@%
  25069. %@AB@%#include <direct.h>%@AE@%               Required only for function declarations
  25070.  
  25071. %@AS@%  int mkdir( char *dirname );%@AE@%%@NL@%
  25072. %@NL@%
  25073. %@AI@%dirname%@AE@%                           Path name for new directory
  25074.  
  25075. %@NL@%
  25076. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25077. %@NL@%
  25078. The %@AB@%mkdir%@AE@% function creates a new directory with the specified %@AI@%dirname%@AE@%. Only
  25079. one directory can be created at a time, so only the last component of
  25080. %@AI@%dirname%@AE@% can name a new directory.  %@NL@%
  25081. %@NL@%
  25082. The %@AB@%mkdir%@AE@% function does not do any translation of path-name delimiters. Both
  25083. DOS and OS/ 2 accept either " \" or "/ "  internally as valid delimiters
  25084. within path names.  %@NL@%
  25085. %@NL@%
  25086. %@NL@%
  25087. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25088. %@NL@%
  25089. The %@AB@%mkdir%@AE@% function returns the value 0 if the new directory was created. A
  25090. return value of -1 indicates an error, and %@AB@%errno%@AE@% is set to one of the
  25091. following values:  %@NL@%
  25092. %@NL@%
  25093. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  25094. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25095. %@AB@%EACCES%@AE@%                            Directory not created. The given name is
  25096.                                   the name of an
  25097.                                   existing file, directory, or device.
  25098.  
  25099. %@AB@%ENOENT%@AE@%                            Path name not found.
  25100.  
  25101. %@NL@%
  25102. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25103. %@NL@%
  25104.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  25105. %@NL@%
  25106. %@NL@%
  25107. %@NL@%
  25108. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25109. %@NL@%
  25110. %@AB@%chdir%@AE@%, %@AB@%rmdir%@AE@%  %@NL@%
  25111. %@NL@%
  25112. %@NL@%
  25113. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25114. %@NL@%
  25115. %@AS@%  /* MAKEDIR.C */
  25116. %@AS@%  #include <direct.h>
  25117. %@AS@%  #include <stdlib.h>
  25118. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  25119. %@NL@%
  25120. %@AS@%  void main()
  25121. %@AS@%  {
  25122. %@AS@%     int result;
  25123. %@AS@%  
  25124. %@AS@%     if( mkdir( "\\testtmp" ) == 0 )
  25125. %@AS@%     {
  25126. %@AS@%        printf( "Directory '\\testtmp' was successfully created\n" );
  25127. %@AS@%        system( "dir \\testtmp" );
  25128. %@AS@%        if( rmdir( "\\testtmp" ) == 0 )
  25129. %@AS@%           printf( "Directory '\\testtmp' was successfully removed\n"  );
  25130. %@AS@%        else
  25131. %@AS@%           printf( "Problem removing directory '\\testtmp'\n" );
  25132. %@AS@%     }
  25133. %@AS@%     else
  25134. %@AS@%        printf( "Problem creating directory '\\testtmp'\n" );
  25135. %@AS@%  }%@AE@%%@NL@%
  25136. %@NL@%
  25137. %@NL@%
  25138. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25139. %@NL@%
  25140. %@AS@%  
  25141. %@AS@%  
  25142. %@AS@%  Directory '\testtmp' was successfully created
  25143. %@AS@%  
  25144. %@AS@%   The volume label in drive C is OS2.
  25145. %@AS@%   Directory of C:\TESTTMP
  25146. %@AS@%  
  25147. %@AS@%  .            <DIR>      6-19-89  11:20a
  25148. %@AS@%  ..           <DIR>      6-19-89  11:20a
  25149. %@AS@%       2 File(s)   12730368 bytes free
  25150. %@AS@%  Directory '\testtmp' was successfully removed %@AE@%%@NL@%
  25151. %@NL@%
  25152. %@NL@%
  25153. %@NL@%
  25154. %@NL@%
  25155. %@QR:mktemp@%%@NL@%
  25156. %@2@%%@CR:C6A02101047 @%%@AB@%mktemp%@AE@%%@EH@%%@NL@%
  25157. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25158. %@NL@%
  25159. %@NL@%
  25160. %@3@%%@AB@%Description%@CR:C6A02101048 @%%@CR:C6A02101049 @%%@CR:C6A02101050 @%%@AE@%%@EH@%%@NL@%
  25161. %@NL@%
  25162. Creates a unique file name.  %@NL@%
  25163. %@NL@%
  25164. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  25165.  
  25166. %@AS@%  char *mktemp( char *template );%@AE@%%@NL@%
  25167. %@NL@%
  25168. %@AI@%template%@AE@%                          File-name pattern
  25169.  
  25170. %@NL@%
  25171. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25172. %@NL@%
  25173. The %@AB@%mktemp%@AE@% function creates a unique file name by modifying the given
  25174. %@AI@%template%@AE@% argument. The %@AI@%template%@AE@% argument has the form:  %@NL@%
  25175. %@NL@%
  25176. %@AI@%base%@AE@%%@AB@%XXXXXX%@AE@%  %@NL@%
  25177. %@NL@%
  25178. where %@AI@%base%@AE@% is the part of the new file name that you supply, and the %@AB@%X%@AE@%'s are
  25179. placeholders for the part supplied by %@AB@%mktemp%@AE@%; %@AB@%mktemp%@AE@% preserves %@AI@%base%@AE@% and
  25180. replaces the six trailing%@AB@% X%@AE@%'s with an alphanumeric character followed by a
  25181. five-digit value. The five-digit value is a unique number identifying the
  25182. calling process. The alphanumeric character is 0 ('%@AB@%0%@AE@%') the first time %@AB@%mktemp%@AE@%
  25183. is called with a given template.  %@NL@%
  25184. %@NL@%
  25185. In subsequent calls from the same process with copies of the same template,
  25186. %@AB@%mktemp%@AE@% checks to see if previously returned names have been used to create
  25187. files. If no file exists for a given name, %@AB@%mktemp%@AE@% returns that name. If
  25188. files exist for all previously returned names, %@AB@%mktemp%@AE@% creates a new name by
  25189. replacing the alphanumeric character in the name with the next available
  25190. lowercase letter. For example, if the first name returned is %@AS@% t012345 %@AE@% and
  25191. this name is used to create a file, the next name returned will be %@AS@% ta12345%@AE@%.
  25192. When creating new names, %@AB@%mktemp%@AE@% uses, in order, '0' and then the lowercase
  25193. letters 'a' through 'z'.  %@NL@%
  25194. %@NL@%
  25195. Note that the original template is modified by the first call to %@AB@%mktemp%@AE@%. If
  25196. you then call the %@AB@%mktemp%@AE@% function again with the same template (i.e., the
  25197. original one), you will get an error.  %@NL@%
  25198. %@NL@%
  25199. The %@AB@%mktemp%@AE@% function generates unique file names but does not create or open
  25200. files.  %@NL@%
  25201. %@NL@%
  25202. %@NL@%
  25203. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25204. %@NL@%
  25205. The %@AB@%mktemp%@AE@% function returns a pointer to the modified template. The return
  25206. value is %@AB@%NULL%@AE@% if the %@AI@%template%@AE@% argument is badly formed or no more unique
  25207. names can be created from the given template.  %@NL@%
  25208. %@NL@%
  25209. %@NL@%
  25210. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25211. %@NL@%
  25212.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  25213. %@NL@%
  25214. %@NL@%
  25215. %@NL@%
  25216. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25217. %@NL@%
  25218. %@AB@%fopen%@AE@%, %@AB@%getpid%@AE@%, %@AB@%open%@AE@%, %@AB@%tempnam%@AE@%, %@AB@%tmpfile%@AE@%  %@NL@%
  25219. %@NL@%
  25220. %@NL@%
  25221. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25222. %@NL@%
  25223. %@AS@%  /* MKTEMP.C: The program uses mktemp to create five unique file names.
  25224. %@AS@%   * It opens each file name to ensure that the next name is unique.
  25225. %@AS@%   */
  25226. %@AS@%  
  25227. %@AS@%  #include <io.h>
  25228. %@AS@%  #include <string.h>
  25229. %@AS@%  #include <stdio.h>
  25230. %@AS@%  
  25231. %@AS@%  char *template = "fnXXXXXX";
  25232. %@AS@%  char *result;
  25233. %@AS@%  char names[5][9];
  25234. %@AS@%  
  25235. %@AS@%  void main()
  25236. %@AS@%  {
  25237. %@AS@%     int i;
  25238. %@AS@%     FILE *fp;
  25239. %@AS@%  
  25240. %@AS@%     for( i = 0; i < 5; i++ )
  25241. %@AS@%     {
  25242. %@AS@%        strcpy( names[i], template );
  25243. %@AS@%  
  25244. %@AS@%        /* Attempt to find a unique file name: */
  25245. %@AS@%        result = mktemp( names[i] );
  25246. %@AS@%        if( result == NULL )
  25247. %@AS@%           printf( "Problem creating the template" );
  25248. %@AS@%        else
  25249. %@AS@%        {
  25250. %@AS@%           if( (fp = fopen( result, "w" )) != NULL )
  25251. %@AS@%               printf( "Unique file name is %s\n", result );
  25252. %@AS@%           else
  25253. %@AS@%               printf( "Cannot open %s\n", result );
  25254. %@AS@%           fclose( fp );
  25255. %@AS@%        }
  25256. %@AS@%     }
  25257. %@AS@%  }%@AE@%%@NL@%
  25258. %@NL@%
  25259. %@NL@%
  25260. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25261. %@NL@%
  25262. %@AS@%  
  25263. %@AS@%  
  25264. %@AS@%  Unique file name is fn000686
  25265. %@AS@%  Unique file name is fna00686
  25266. %@AS@%  Unique file name is fnb00686
  25267. %@AS@%  Unique file name is fnc00686
  25268. %@AS@%  Unique file name is fnd00686%@AE@%%@NL@%
  25269. %@NL@%
  25270. %@NL@%
  25271. %@NL@%
  25272. %@NL@%
  25273. %@QR:mktime@%%@NL@%
  25274. %@2@%%@CR:C6A02111051 @%%@AB@%mktime%@AE@%%@EH@%%@NL@%
  25275. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25276. %@NL@%
  25277. %@NL@%
  25278. %@3@%%@AB@%Description%@CR:C6A02111052 @%%@CR:C6A02111053 @%%@AE@%%@EH@%%@NL@%
  25279. %@NL@%
  25280. Converts the local time to a calendar value.  %@NL@%
  25281. %@NL@%
  25282. %@AS@%  #include <time.h>%@AE@%%@NL@%
  25283. %@NL@%
  25284. %@AS@%  time_t mktime( struct tm *timeptr );%@AE@%%@NL@%
  25285. %@NL@%
  25286. %@AI@%timeptr%@AE@%                           Pointer to time structure
  25287.  
  25288. %@NL@%
  25289. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25290. %@NL@%
  25291. The %@AB@%mktime%@AE@% function converts the supplied time structure (possibly
  25292. incomplete) pointed to by %@AI@%timeptr%@AE@% into a fully defined structure with
  25293. "normalized" values and then converts it to a %@AB@%time_t%@AE@% calendar time value.
  25294. The structure for the %@AB@%tm%@AE@% is described in the reference page for %@AB@%asctime%@AE@%.  %@NL@%
  25295. %@NL@%
  25296. The converted time has the same encoding as the values returned by the %@AB@%time%@AE@%
  25297. function. The original values of the %@AB@%tm_wday%@AE@% and %@AB@%tm_yday%@AE@% components of the
  25298. %@AI@%timeptr%@AE@% structure are ignored, and the original values of the other
  25299. components are not restricted to their normal ranges.  %@NL@%
  25300. %@NL@%
  25301. If successful, %@AB@%mktime%@AE@% sets the values of %@AB@%tm_wday%@AE@% and %@AB@%tm_yday%@AE@% appropriately,
  25302. and sets the other components to represent the specified calendar time, but
  25303. with their values forced to the normal ranges; the final value of %@AB@%tm_mday%@AE@% is
  25304. not set until %@AB@%tm_mon%@AE@% and %@AB@%tm_year%@AE@% are determined.  %@NL@%
  25305. %@NL@%
  25306. DOS and OS/2 do not accommodate dates prior to 1980. If %@AI@%timeptr%@AE@% references a
  25307. date before January 1, 1980, %@AB@%mktime%@AE@% returns -1.  %@NL@%
  25308. %@NL@%
  25309. Note that the %@AB@%gmtime%@AE@% and %@AB@%localtime%@AE@% functions use a single statically
  25310. allocated buffer for the conversion. If you supply this buffer to %@AB@%mktime%@AE@%,
  25311. the previous contents will be destroyed.  %@NL@%
  25312. %@NL@%
  25313. %@NL@%
  25314. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25315. %@NL@%
  25316. The %@AB@%mktime%@AE@% function returns the specified calendar time encoded as a value
  25317. of type %@AB@%time_t%@AE@%. If the calendar time cannot be represented, the function
  25318. returns the value -1 cast as type %@AB@%time_t%@AE@%.  %@NL@%
  25319. %@NL@%
  25320. %@NL@%
  25321. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25322. %@NL@%
  25323. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  25324. %@NL@%
  25325. %@NL@%
  25326. %@NL@%
  25327. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25328. %@NL@%
  25329. %@AB@%asctime%@AE@%, %@AB@%gmtime%@AE@%, %@AB@%localtime%@AE@%, %@AB@%time%@AE@%  %@NL@%
  25330. %@NL@%
  25331. %@NL@%
  25332. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25333. %@NL@%
  25334. %@AS@%  /* MKTIME.C: The example takes a number of days as input and returns
  25335. %@AS@%   * the time, the current date, and the specified number of days.
  25336. %@AS@%   */%@AE@%%@NL@%
  25337. %@NL@%
  25338. %@AS@%  #include <time.h>
  25339. %@AS@%  #include <stdio.h>
  25340. %@AS@%  
  25341. %@AS@%  void main()
  25342. %@AS@%  {
  25343. %@AS@%     struct tm when;
  25344. %@AS@%     time_t now, result;
  25345. %@AS@%     int    days;
  25346. %@AS@%  
  25347. %@AS@%     time( &now );
  25348. %@AS@%     when = *localtime( &now );
  25349. %@AS@%     printf( "Current time is %s\n", asctime( &when ) );
  25350. %@AS@%     printf( "How many days to look ahead: " );
  25351. %@AS@%     scanf( "%d", &days );
  25352. %@AS@%  
  25353. %@AS@%     when.tm_mday = when.tm_mday + days;
  25354. %@AS@%     if( (result = mktime( &when )) != (time_t)-1 )
  25355. %@AS@%        printf( "In %d days the time will be %s\n",
  25356. %@AS@%                days, asctime( &when ) );
  25357. %@AS@%     else
  25358. %@AS@%        perror( "mktime failed" );
  25359. %@AS@%  }%@AE@%%@NL@%
  25360. %@NL@%
  25361. %@NL@%
  25362. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25363. %@NL@%
  25364. %@AS@%  
  25365. %@AS@%  
  25366. %@AS@%  Current time is Mon Jun 19 11:45:20 1989
  25367. %@AS@%  
  25368. %@AS@%  How many days to look ahead: 23
  25369. %@AS@%  In 23 days the time will be Wed Jul 12 11:45:20 1989 %@AE@%%@NL@%
  25370. %@NL@%
  25371. %@NL@%
  25372. %@NL@%
  25373. %@NL@%
  25374. %@QR:modf@%%@QR:modfl@%%@NL@%
  25375. %@2@%%@CR:C6A02121054 @%%@AB@%modf, modfl%@AE@%%@EH@%%@NL@%
  25376. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25377. %@NL@%
  25378. %@NL@%
  25379. %@3@%%@AB@%Description%@CR:C6A02121055 @% %@CR:C6A02121056 @%%@CR:C6A02121057 @%%@AE@%%@EH@%%@NL@%
  25380. %@NL@%
  25381. Split a floating-point value into a mantissa and an exponent.  %@NL@%
  25382. %@NL@%
  25383. %@AS@%  #include <math.h>%@AE@%%@NL@%
  25384. %@NL@%
  25385. %@AS@%  double modf( double x, double *intptr );%@AE@%%@NL@%
  25386. %@NL@%
  25387. %@AS@%  long double modfl( long double x, long double *intptr );%@AE@%%@NL@%
  25388. %@NL@%
  25389. %@AI@%x%@AE@%                                 Floating-point value
  25390.  
  25391. %@AI@%intptr%@AE@%                            Pointer to stored integer portion
  25392.  
  25393. %@NL@%
  25394. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25395. %@NL@%
  25396. The %@AB@%modf%@AE@% functions break down the floating-point value %@AI@%x%@AE@% into fractional and
  25397. integer parts, each of which has the same sign as %@AI@%x%@AE@%. The signed fractional
  25398. portion of %@AI@%x%@AE@% is returned. The integer portion is stored as a floating-point
  25399. value at  %@AI@%intptr%@AE@%.  %@NL@%
  25400. %@NL@%
  25401. The %@AB@%modfl%@AE@% function uses the 80-bit, 10-byte coprocessor form of arguments
  25402. and return values. See the reference page on the long double functions for
  25403. more details on this data type.  %@NL@%
  25404. %@NL@%
  25405. %@NL@%
  25406. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25407. %@NL@%
  25408. The %@AB@%modf%@AE@% and %@AB@%modfl%@AE@% functions return the signed fractional portion of %@AI@%x%@AE@%.
  25409. There is no error return.  %@NL@%
  25410. %@NL@%
  25411. %@NL@%
  25412. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25413. %@NL@%
  25414. %@AB@%modf%@AE@%  %@NL@%
  25415. %@NL@%
  25416. %@AB@%%@AE@% ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2   %@AB@%%@AE@% UNIX   %@AB@%%@AE@% XENIX %@NL@%
  25417. %@NL@%
  25418. %@NL@%
  25419. %@AB@%modfl%@AE@%  %@NL@%
  25420. %@NL@%
  25421.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  25422. %@NL@%
  25423. %@NL@%
  25424. %@NL@%
  25425. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25426. %@NL@%
  25427. %@AB@%frexp%@AE@%, %@AB@%ldexp%@AE@%  %@NL@%
  25428. %@NL@%
  25429. %@NL@%
  25430. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25431. %@NL@%
  25432. %@AS@%  /* MODF.C */
  25433. %@AS@%  #include <math.h>
  25434. %@AS@%  #include <stdio.h>%@AE@%%@NL@%
  25435. %@NL@%
  25436. %@AS@%  void main()
  25437. %@AS@%  {
  25438. %@AS@%     double x, y, n;
  25439. %@AS@%  
  25440. %@AS@%     x = -14.87654321;       /* Divide x into its fractional */
  25441. %@AS@%     y = modf( x, &n );      /* and integer parts            */
  25442. %@AS@%  
  25443. %@AS@%     printf( "For %f, the fraction is %f and the integer is %.f\n", x, y, n
  25444. %@AS@%);
  25445. %@AS@%  }%@AE@%%@NL@%
  25446. %@NL@%
  25447. %@NL@%
  25448. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25449. %@NL@%
  25450. %@AS@%  
  25451. %@AS@%  
  25452. %@AS@%  For -14.876543, the fraction is -0.876543 and the integer is -14 %@AE@%%@NL@%
  25453. %@NL@%
  25454. %@NL@%
  25455. %@NL@%
  25456. %@NL@%
  25457. %@QR:movedata@%%@NL@%
  25458. %@2@%%@CR:C6A02131058 @%%@AB@%movedata%@AE@%%@EH@%%@NL@%
  25459. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25460. %@NL@%
  25461. %@NL@%
  25462. %@3@%%@AB@%Description%@CR:C6A02131059 @%%@CR:C6A02131060 @%%@AE@%%@EH@%%@NL@%
  25463. %@NL@%
  25464. Moves characters to another segment.  %@NL@%
  25465. %@NL@%
  25466. %@AB@%#include <memory.h>%@AE@%               Required only for function declarations%@AB@%%@AE@%
  25467.  
  25468. %@AB@%#include <string.h>%@AE@%               Use either STRING.H (for ANSI 
  25469.                                   compatibility) or MEMORY.H
  25470.  
  25471. %@AS@%  void movedata( unsigned int srcseg, unsigned int srcoff, unsigned int
  25472. %@AS@%  destseg, 
  25473. %@AS@%  unsigned int destoff, unsigned int count );%@AE@%%@NL@%
  25474. %@NL@%
  25475. %@AI@%srcseg%@AE@%                            Segment address of source
  25476.  
  25477. %@AI@%srcoff%@AE@%                            Segment offset of source
  25478.  
  25479. %@AI@%destseg%@AE@%                           Segment address of destination
  25480.  
  25481. %@AI@%destoff%@AE@%                           Segment offset of destination
  25482.  
  25483. %@AI@%count%@AE@%                             Number of bytes
  25484.  
  25485. %@NL@%
  25486. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25487. %@NL@%
  25488. The %@AB@%movedata%@AE@% function copies %@AI@%count%@AE@% bytes from the source address specified
  25489. by %@AI@%srcseg%@AE@%:%@AI@%srcoff%@AE@% to the destination address specified by %@AI@%destseg%@AE@%:%@AI@%destoff%@AE@%.%@CR:C6A02131061 @%  %@NL@%
  25490. %@NL@%
  25491. The %@AB@%movedata%@AE@% function was intended to move far data in small-data-model
  25492. programs. The newer model-independent %@AB@%_fmemcpy%@AE@% and %@AB@%_fmemmove%@AE@% functions
  25493. should be used instead of the %@AB@%movedata%@AE@% function. In large-data-model
  25494. programs, the %@AB@%memcpy%@AE@% and %@AB@%memmove%@AE@% functions can also be used.  %@NL@%
  25495. %@NL@%
  25496. Segment values for the %@AI@%srcseg%@AE@% and %@AI@%destseg%@AE@% arguments can be obtained by using
  25497. either the %@AB@%segread%@AE@% function or the %@AB@%FP_SEG%@AE@% macro.  %@NL@%
  25498. %@NL@%
  25499. The %@AB@%movedata%@AE@% function does not handle all cases of overlapping moves
  25500. correctly. These occur when part of the destination is the same memory area
  25501. as part of the source. The %@AB@%memmove%@AE@% function correctly handles overlapping
  25502. moves.  %@NL@%
  25503. %@NL@%
  25504. %@NL@%
  25505. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25506. %@NL@%
  25507. None.  %@NL@%
  25508. %@NL@%
  25509. %@NL@%
  25510. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25511. %@NL@%
  25512.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  25513. %@NL@%
  25514. %@NL@%
  25515. %@NL@%
  25516. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25517. %@NL@%
  25518. %@AB@%%@AE@%FP_OFF, FP_SEG, %@AB@%memcpy%@AE@%, %@AB@%memmove%@AE@%, %@AB@%segread%@AE@%  %@NL@%
  25519. %@NL@%
  25520. %@NL@%
  25521. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25522. %@NL@%
  25523. %@AS@%  /* MOVEDATA.C */
  25524. %@AS@%  #include <memory.h>
  25525. %@AS@%  #include <stdio.h>
  25526. %@AS@%  #include <string.h>
  25527. %@AS@%  #include <dos.h>
  25528. %@AS@%  #include <malloc.h>
  25529. %@AS@%  
  25530. %@AS@%  char _far *src = "This is a test.";
  25531. %@AS@%  
  25532. %@AS@%  void main()
  25533. %@AS@%  {
  25534. %@AS@%     char _far *dest;
  25535. %@AS@%  
  25536. %@AS@%     if( (dest = _fmalloc( 80 )) != NULL )
  25537. %@AS@%     {
  25538. %@AS@%        movedata( FP_SEG( src ),  FP_OFF( src ),
  25539. %@AS@%                  FP_SEG( dest ), FP_OFF( dest ), _fstrlen( src ) + 1 );
  25540. %@AS@%        printf( "The source data at %Fp is '%Fs'\n", src, src );
  25541. %@AS@%        printf( "The destination data at %Fp is '%Fs'\n", dest, dest );
  25542. %@AS@%        _ffree( dest );
  25543. %@AS@%     }
  25544. %@AS@%  }%@AE@%%@NL@%
  25545. %@NL@%
  25546. %@NL@%
  25547. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25548. %@NL@%
  25549. %@AS@%  
  25550. %@AS@%  
  25551. %@AS@%  The source data at 2D0A:02B8 is 'This is a test.'
  25552. %@AS@%  The destination data at 3D0B:0016 is 'This is a test.'%@AE@%%@NL@%
  25553. %@NL@%
  25554. %@NL@%
  25555. %@NL@%
  25556. %@NL@%
  25557. %@QR:_moveto@%%@NL@%
  25558. %@2@%%@CR:C6A02141062 @%%@AB@%_moveto Functions%@AE@%%@EH@%%@NL@%
  25559. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25560. %@NL@%
  25561. %@NL@%
  25562. %@3@%%@AB@%Description%@AE@%%@EH@%%@NL@%
  25563. %@NL@%
  25564. Move current graphics positions.  %@NL@%
  25565. %@NL@%
  25566. %@CR:C6A02141063 @%%@CR:C6A02141064 @%%@CR:C6A02141065 @%%@AS@%  #include <graph.h>%@AE@%%@NL@%
  25567. %@NL@%
  25568. %@AS@%  struct xycoord _far _moveto( short x, short y );%@AE@%%@NL@%
  25569. %@NL@%
  25570. %@AS@%  struct _wxycoord _far _moveto_w( double wx, double wy );%@AE@%%@NL@%
  25571. %@NL@%
  25572. %@AI@%x%@AE@%, %@AI@%y%@AE@%                              View-coordinate point
  25573.  
  25574. %@AI@%wx%@AE@%, %@AI@%wy%@AE@%                            Window-coordinate point
  25575.  
  25576. %@NL@%
  25577. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25578. %@NL@%
  25579. The %@AB@%_moveto%@AE@% functions move the current position to the specified point. The
  25580. %@AB@%_moveto%@AE@% function uses the view-coordinate point (%@AI@%x%@AE@%, %@AI@%y%@AE@%) as the current
  25581. position. The %@AB@%_moveto_w%@AE@% function uses the window-coordinate point (%@AI@%wx%@AE@%, %@AI@%wy%@AE@%)
  25582. as the current position. No drawing takes place.  %@NL@%
  25583. %@NL@%
  25584. %@NL@%
  25585. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25586. %@NL@%
  25587. The function returns the coordinates of the previous position. The %@AB@%_moveto%@AE@%
  25588. function returns the coordinates in an %@AB@%xycoord%@AE@% structure. The %@AB@%xycoord%@AE@%
  25589. structure, defined in GRAPH.H, contains the following elements:  %@NL@%
  25590. %@NL@%
  25591. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  25592. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25593. %@AB@%short xcoord%@AE@%                      %@AI@%x%@AE@% coordinate
  25594.  
  25595. %@AB@%short ycoord%@AE@%                      %@AI@%y%@AE@% coordinate
  25596.  
  25597. The %@AB@%_moveto_w%@AE@% function returns the coordinates in an %@AB@%_wxycoord%@AE@% structure,
  25598. defined in GRAPH.H. The %@AB@%_wxycoord%@AE@% structure contains the following elements:
  25599. %@NL@%
  25600. %@NL@%
  25601. %@AB@%Element%@AE@%                           %@AB@%Description%@AE@%
  25602. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25603. %@AB@%double wx%@AE@%                         %@AI@%x%@AE@% window coordinate
  25604.  
  25605. %@AB@%double wy%@AE@%                         %@AI@%y%@AE@% window coordinate
  25606.  
  25607. %@NL@%
  25608. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25609. %@NL@%
  25610.  ANSI   %@AB@%%@AE@% DOS    OS/2    UNIX    XENIX %@NL@%
  25611. %@NL@%
  25612. %@NL@%
  25613. %@NL@%
  25614. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25615. %@NL@%
  25616. %@AB@%_lineto%@AE@% functions  %@NL@%
  25617. %@NL@%
  25618. %@NL@%
  25619. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25620. %@NL@%
  25621. %@AS@%  /* MOVETO.C: This program draws line segments of different colors. */
  25622. %@AS@%  
  25623. %@AS@%  #include <graph.h>
  25624. %@AS@%  #include <stdlib.h>
  25625. %@AS@%  #include <conio.h>
  25626. %@AS@%  
  25627. %@AS@%  void main()
  25628. %@AS@%  {
  25629. %@AS@%     short x, y, xinc, yinc, color = 1;
  25630. %@AS@%     struct videoconfig v;
  25631. %@AS@%  
  25632. %@AS@%     /* Find a valid graphics mode. */
  25633. %@AS@%     if( !_setvideomode( _MAXCOLORMODE ) )
  25634. %@AS@%        exit( 1 );
  25635. %@AS@%     _getvideoconfig( &v );
  25636. %@AS@%     xinc = v.numxpixels / 50;
  25637. %@AS@%     yinc = v.numypixels / 50;
  25638. %@AS@%  
  25639. %@AS@%     for( x = 0, y = v.numypixels - 1; x < v.numxpixels; x += xinc, y -=
  25640. %@AS@%yinc )
  25641. %@AS@%     {
  25642. %@AS@%        _setcolor( color++ % 16 );
  25643. %@AS@%        _moveto( x, 0 );
  25644. %@AS@%        _lineto( 0, y );
  25645. %@AS@%     }
  25646. %@AS@%     getch();
  25647. %@AS@%  
  25648. %@AS@%     _setvideomode( _DEFAULTMODE );
  25649. %@AS@%  }
  25650. %@AS@%  %@AE@%%@NL@%
  25651. %@NL@%
  25652. %@NL@%
  25653. %@NL@%
  25654. %@NL@%
  25655. %@QR:_msize@%%@NL@%
  25656. %@2@%%@CR:C6A02151066 @%%@AB@%_msize Functions%@AE@%%@EH@%%@NL@%
  25657. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25658. %@NL@%
  25659. %@NL@%
  25660. %@3@%%@AB@%Description%@CR:C6A02151067 @%%@CR:C6A02151068 @%%@CR:C6A02151069 @% %@CR:C6A02151070 @%%@CR:C6A02151071 @% %@CR:C6A02151072 @%%@CR:C6A02151073 @% %@CR:C6A02151074 @%%@AE@%%@EH@%%@NL@%
  25661. %@NL@%
  25662. Return the size of a memory block allocated in the heap.  %@NL@%
  25663. %@NL@%
  25664. %@AB@%#include <malloc.h>%@AE@%               Required only for function declarations
  25665.  
  25666. %@AS@%  size_t  _msize( void *memblock );%@AE@%%@NL@%
  25667. %@NL@%
  25668. %@AS@%  size_t _bmsize( _segment seg, void _based( void ) *memblock );%@AE@%%@NL@%
  25669. %@NL@%
  25670. %@AS@%  size_t _fmsize( void _far *memblock );%@AE@%%@NL@%
  25671. %@NL@%
  25672. %@AS@%  size_t _nmsize( void _near *memblock );%@AE@%%@NL@%
  25673. %@NL@%
  25674. %@AI@%memblock%@AE@%                          Pointer to memory block 
  25675.  
  25676. %@AI@%seg%@AE@%                               Based-heap segment selector
  25677.  
  25678. %@NL@%
  25679. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25680. %@NL@%
  25681. The %@AB@%_msize%@AE@% family of functions returns the size, in bytes, of the memory
  25682. block allocated by a call to the appropriate version of the %@AB@%calloc%@AE@%, %@AB@%malloc%@AE@%,
  25683. or %@AB@%realloc%@AE@% functions.  %@NL@%
  25684. %@NL@%
  25685. In large data models (compact-, large-, and huge-model programs), %@AB@%_msize%@AE@%
  25686. maps to %@AB@%_fmsize%@AE@%. In small data models (tiny-, small-, and medium-model
  25687. programs), %@AB@%_msize%@AE@% maps to %@AB@%_nmsize%@AE@%.  %@NL@%
  25688. %@NL@%
  25689. The %@AB@%_nmsize%@AE@% function returns the size (in bytes) of the memory block
  25690. allocated by a call to %@AB@%_nmalloc%@AE@%, and the %@AB@%_fmsize%@AE@% function returns the size
  25691. (in bytes) of the memory block allocated by a call to %@AB@%_fmalloc%@AE@% or %@AB@%_frealloc%@AE@%.
  25692. The %@AB@%_bmsize%@AE@% function returns the size of a block allocated in segment %@AI@%seg%@AE@% by
  25693. a call to %@AB@%_bmalloc%@AE@%, %@AB@%_bcalloc%@AE@%, or %@AB@%_brealloc%@AE@%.  %@NL@%
  25694. %@NL@%
  25695. The location of the memory block is indicated below:  %@NL@%
  25696. %@NL@%
  25697. %@AB@%Function%@AE@%                          %@AB@%Data Segment%@AE@%
  25698. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25699. %@AB@%_msize%@AE@%                            Depends on data model of program
  25700.  
  25701. %@AB@%_bmsize%@AE@%                           Based heap segment specified by %@AI@%seg%@AE@% 
  25702.                                   value
  25703.  
  25704. %@AB@%_fmsize%@AE@%                           Far heap segment (outside default data 
  25705.                                   segment)
  25706.  
  25707. %@AB@%_nmsize%@AE@%                           Default data segment (inside near heap)
  25708.  
  25709. %@NL@%
  25710. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25711. %@NL@%
  25712. All four functions return the size (in bytes) as an unsigned integer.  %@NL@%
  25713. %@NL@%
  25714. %@NL@%
  25715. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25716. %@NL@%
  25717.  ANSI   %@AB@%%@AE@% DOS   %@AB@%%@AE@% OS/2    UNIX    XENIX %@NL@%
  25718. %@NL@%
  25719. %@NL@%
  25720. %@NL@%
  25721. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25722. %@NL@%
  25723. %@AB@%calloc%@AE@% functions,  %@AB@%_expand%@AE@% functions, %@AB@%malloc%@AE@% functions, %@AB@%realloc%@AE@% functions  %@NL@%
  25724. %@NL@%
  25725. %@NL@%
  25726. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25727. %@NL@%
  25728. %@AS@%  /* REALLOC.C: This program allocates a block of memory for buffer
  25729. %@AS@%   * and then uses _msize to display the size of that block. Next, it
  25730. %@AS@%   * uses realloc to expand the amount of memory used by buffer
  25731. %@AS@%   * and then calls _msize again to display the new amount of
  25732. %@AS@%   * memory allocated to buffer.
  25733. %@AS@%   */
  25734. %@AS@%  
  25735. %@AS@%  #include <stdio.h>
  25736. %@AS@%  #include <malloc.h>
  25737. %@AS@%  #include <stdlib.h>
  25738. %@AS@%  
  25739. %@AS@%  void main()
  25740. %@AS@%  {
  25741. %@AS@%     long *buffer;
  25742. %@AS@%     size_t size;
  25743. %@AS@%  
  25744. %@AS@%     if( (buffer = (long *)malloc( 1000 * sizeof( long ) )) == NULL )
  25745. %@AS@%        exit( 1 );
  25746. %@AS@%  
  25747. %@AS@%     size = _msize( buffer );
  25748. %@AS@%     printf( "Size of block after malloc of 1000 longs: %u\n", size );
  25749. %@AS@%  
  25750. %@AS@%     /* Reallocate and show new size: */
  25751. %@AS@%     if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) ==
  25752. %@AS@%NULL )
  25753. %@AS@%        exit( 1 );
  25754. %@AS@%     size = _msize( buffer );
  25755. %@AS@%     printf( "Size of block after realloc of 1000 more longs: %u\n", size );
  25756. %@AS@%  
  25757. %@AS@%     free( buffer );
  25758. %@AS@%  }%@AE@%%@NL@%
  25759. %@NL@%
  25760. %@NL@%
  25761. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25762. %@NL@%
  25763. %@AS@%  
  25764. %@AS@%  
  25765. %@AS@%  Size of block after malloc of 1000 longs: 4000
  25766. %@AS@%  Size of block after realloc of 1000 more longs: 8000 %@AE@%%@NL@%
  25767. %@NL@%
  25768. %@NL@%
  25769. %@NL@%
  25770. %@NL@%
  25771. %@QR:onexit@%%@NL@%
  25772. %@2@%%@CR:C6A02161075 @%%@AB@%onexit%@AE@%%@EH@%%@NL@%
  25773. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25774. %@NL@%
  25775. %@NL@%
  25776. %@3@%%@AB@%Description%@CR:C6A02161076 @%%@CR:C6A02161077 @%%@AE@%%@EH@%%@NL@%
  25777. %@NL@%
  25778. Registers a routine to be called at exit time.  %@NL@%
  25779. %@NL@%
  25780. %@AS@%  #include <stdlib.h>%@AE@%%@NL@%
  25781. %@NL@%
  25782. %@AS@%  onexit_t onexit( onexit_t func );%@AE@%%@NL@%
  25783. %@NL@%
  25784. %@AI@%func%@AE@%                              Pointer to function to be called at exit
  25785.  
  25786. %@NL@%
  25787. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25788. %@NL@%
  25789. The %@AB@%onexit%@AE@% function is passed the address of a function (%@AI@%func%@AE@%) to be called
  25790. when the program terminates normally. Successive calls to %@AB@%onexit%@AE@% create a
  25791. register of functions that is executed in LIFO (last-in-first-out) order. No
  25792. more than 32 functions can be registered with %@AB@%onexit%@AE@%; %@AB@%onexit%@AE@% returns the
  25793. value%@AB@% NULL%@AE@% if the number of functions exceeds 32. The functions passed to
  25794. %@AB@%onexit%@AE@% cannot take parameters.  %@NL@%
  25795. %@NL@%
  25796. The %@AB@%onexit%@AE@% function is not part of the ANSI definition, but is instead a
  25797. Microsoft extension. The ANSI-standard %@AB@%atexit %@AE@%function does the same thing
  25798. as%@AB@% onexit%@AE@%, and should be used instead of %@AB@%onexit %@AE@%when ANSI portability is
  25799. desired.  %@NL@%
  25800. %@NL@%
  25801. All routines passed to %@AB@%onexit%@AE@% should have the %@AB@%_loadds%@AE@% attribute if used in
  25802. multithread dynamic-link libraries.  %@NL@%
  25803. %@NL@%
  25804. %@NL@%
  25805. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25806. %@NL@%
  25807. The %@AB@%onexit%@AE@% function returns a pointer to the function if successful and
  25808. returns %@AB@%NULL%@AE@% if there is no space left to store the function pointer.  %@NL@%
  25809. %@NL@%
  25810. %@NL@%
  25811. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  25812. %@NL@%
  25813.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  25814. %@NL@%
  25815. %@NL@%
  25816. %@NL@%
  25817. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  25818. %@NL@%
  25819. %@AB@%exit%@AE@%  %@NL@%
  25820. %@NL@%
  25821. %@NL@%
  25822. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  25823. %@NL@%
  25824. %@AS@%  /* ONEXIT.C */
  25825. %@AS@%  #include <stdlib.h>
  25826. %@AS@%  #include <stdio.h>
  25827. %@AS@%  
  25828. %@AS@%  /* Prototypes */
  25829. %@AS@%  void fn1( void ), fn2( void ), fn3( void ),  fn4( void );%@AE@%%@NL@%
  25830. %@NL@%
  25831. %@AS@%  void main()
  25832. %@AS@%  {
  25833. %@AS@%     onexit( fn1 );
  25834. %@AS@%     onexit( fn2 );
  25835. %@AS@%     onexit( fn3 );
  25836. %@AS@%     onexit( fn4 );
  25837. %@AS@%     printf( "This is executed first.\n" );
  25838. %@AS@%  }
  25839. %@AS@%  
  25840. %@AS@%  void fn1()
  25841. %@AS@%  {
  25842. %@AS@%     printf( "next.\n" );
  25843. %@AS@%  }
  25844. %@AS@%  
  25845. %@AS@%  void fn2()
  25846. %@AS@%  {
  25847. %@AS@%     printf( "executed " );
  25848. %@AS@%  }
  25849. %@AS@%  
  25850. %@AS@%  void fn3()
  25851. %@AS@%  {
  25852. %@AS@%     printf( "is " );
  25853. %@AS@%  }
  25854. %@AS@%  
  25855. %@AS@%  void fn4()
  25856. %@AS@%  {
  25857. %@AS@%     printf( "This " );
  25858. %@AS@%  }%@AE@%%@NL@%
  25859. %@NL@%
  25860. %@NL@%
  25861. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  25862. %@NL@%
  25863. %@AS@%  
  25864. %@AS@%  
  25865. %@AS@%  This is executed first.
  25866. %@AS@%  This is executed next. %@AE@%%@NL@%
  25867. %@NL@%
  25868. %@NL@%
  25869. %@NL@%
  25870. %@NL@%
  25871. %@QR:open@%%@NL@%
  25872. %@2@%%@CR:C6A02171078 @%%@AB@%open%@AE@%%@EH@%%@NL@%
  25873. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25874. %@NL@%
  25875. %@NL@%
  25876. %@3@%%@AB@%Description%@CR:C6A02171079 @%%@CR:C6A02171080 @%%@CR:C6A02171081 @% %@CR:C6A02171082 @%%@CR:C6A02171083 @%%@AE@%%@EH@%%@NL@%
  25877. %@NL@%
  25878. Opens a file.  %@NL@%
  25879. %@NL@%
  25880. %@AB@%#include <fcntl.h>%@AE@%                
  25881.  
  25882. %@AB@%#include <sys\types.h>%@AE@%            
  25883.  
  25884. %@AB@%#include <sys\stat.h>%@AE@%             
  25885.  
  25886. %@AB@%#include <io.h>%@AE@%                   Required only for function declarations
  25887.  
  25888. %@AS@%  int open( char *filename, int oflag [[, int pmode]] );%@AE@%%@NL@%
  25889. %@NL@%
  25890. %@AI@%filename%@AE@%                          File name
  25891.  
  25892. %@AI@%oflag%@AE@%                             Type of operations allowed
  25893.  
  25894. %@AI@%pmode%@AE@%                             Permission mode
  25895.  
  25896. %@NL@%
  25897. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  25898. %@NL@%
  25899. The %@AB@%open%@AE@% function opens the file specified by %@AI@%filename%@AE@% and prepares the file
  25900. for subsequent reading or writing, as defined by %@AI@%oflag%@AE@%. The %@AI@%oflag%@AE@% argument
  25901. is an integer expression formed from one or more of the manifest constants
  25902. defined in FCNTL.H (listed below). When two or more manifest constants are
  25903. used to form the %@AI@%oflag%@AE@% argument, the constants are combined with the
  25904. bitwise-OR operator ( | ). See Section 2.5, "File Handling," for a
  25905. discussion of binary and text modes.  %@NL@%
  25906. %@NL@%
  25907. The FCNTL.H file defines the following manifest constants:%@CR:C6A02171084 @%%@CR:C6A02171085 @%%@CR:C6A02171086 @%%@CR:C6A02171087 @%%@CR:C6A02171088 @%  %@NL@%
  25908. %@NL@%
  25909. %@AB@%Constant%@AE@%                          %@AB@%Meaning%@AE@%
  25910. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25911. %@AB@%O_APPEND%@AE@%                          Repositions the file pointer to the end 
  25912.                                   of the file before every write 
  25913.                                   operation.
  25914.  
  25915. %@AB@%O_BINARY%@AE@%                          Opens file in binary (untranslated) 
  25916.                                   mode.
  25917.  
  25918. %@AB@%O_CREAT%@AE@%                           Creates and opens a new file for 
  25919.                                   writing; this has no effect if the file 
  25920.                                   specified by %@AI@%filename%@AE@% exists.
  25921.  
  25922. %@AB@%O_EXCL%@AE@%                            Returns an error value if the file 
  25923.                                   specified by %@AI@%filename%@AE@% exists. Only 
  25924.                                   applies when used with %@AB@%O_CREAT%@AE@%.
  25925.  
  25926. %@AB@%O_RDONLY%@AE@%                          Opens file for reading only; if this 
  25927.                                   flag is given, neither %@AB@%O_RDWR%@AE@% nor %@AB@%%@AE@%
  25928.                                   %@AB@%O_WRONLY%@AE@% can be given.
  25929.  
  25930. %@AB@%O_RDWR%@AE@%                            Opens file for both reading and writing;
  25931.                                   if this flag is given, neither %@AB@%O_RDONLY%@AE@% 
  25932.                                   nor%@AB@% O_WRONLY%@AE@% can be given.
  25933.  
  25934. %@AB@%O_TEXT%@AE@%                            Opens file in text (translated) mode.
  25935.  
  25936. %@AB@%O_TRUNC%@AE@%                           Opens and truncates an existing file to 
  25937.                                   zero length; the file must have write 
  25938.                                   permission. The contents of the file are
  25939.                                   destroyed. If this flag is given, you 
  25940.                                   cannot specify %@AB@%O_RDONLY%@AE@%.
  25941.  
  25942. %@AB@%O_WRONLY%@AE@%                          Opens file for writing only; if this 
  25943.                                   flag is given, neither %@AB@%O_RDONLY%@AE@% nor %@AB@%%@AE@%
  25944.                                   %@AB@%O_RDWR%@AE@% can be given.
  25945.  
  25946. ────────────────────────────────────────────────────────────────────────────%@NL@%
  25947. %@AU@%WARNING%@AE@%%@NL@%
  25948. %@NL@%
  25949. %@AI@%Use the O_TRUNC flag with care, as it destroys the complete contents of an
  25950. %@AI@%existing file.%@AE@%%@NL@%
  25951. ────────────────────────────────────────────────────────────────────────────%@NL@%
  25952. %@NL@%
  25953. Either %@AB@%O_RDONLY%@AE@%, %@AB@%O_RDWR%@AE@%, or%@AB@% O_WRONLY%@AE@% must be given to specify the access
  25954. mode. There is no default value for the access mode.  %@NL@%
  25955. %@NL@%
  25956. The %@AI@%pmode%@AE@% argument is required only when %@AB@%O_CREAT%@AE@% is specified. If the file
  25957. exists, %@AI@%pmode%@AE@% is ignored. Otherwise, %@AI@%pmode%@AE@% specifies the file's permission
  25958. settings, which are set when the new file is closed for the first time. The
  25959. %@AI@%pmode%@AE@% is an integer expression containing one or both of the manifest
  25960. constants %@AB@%S_IWRITE%@AE@% and %@AB@%S_IREAD%@AE@%, defined in SYS\STAT.H. When both constants
  25961. are given, they are joined with the bitwise-OR operator ( | ). The meaning
  25962. of the %@AI@%pmode%@AE@% argument is as follows:  %@NL@%
  25963. %@NL@%
  25964. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  25965. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  25966. %@AB@%S_IWRITE%@AE@%                          Writing permitted
  25967.  
  25968. %@AB@%S_IREAD%@AE@%                           Reading permitted
  25969.  
  25970. %@AB@%S_IREAD |  S_IWRITE%@AE@%               Reading and writing permitted
  25971.  
  25972. If write permission is not given, the file is read-only. Under DOS and OS/2,
  25973. all files are readable; it is not possible to give write-only permission.
  25974. Thus the modes %@AB@%S_IWRITE%@AE@% and %@AB@%S_IREAD | S_IWRITE%@AE@% are equivalent.  %@NL@%
  25975. %@NL@%
  25976. The %@AB@%open%@AE@% function applies the current file-permission mask to %@AI@%pmode%@AE@% before
  25977. setting the permissions (see %@AB@%umask%@AE@%).  %@NL@%
  25978. %@NL@%
  25979. The %@AI@%filename%@AE@% argument used in the %@AB@%open%@AE@% function is affected by the DOS
  25980. APPEND command.  %@NL@%
  25981. %@NL@%
  25982. Note that under DOS versions 3.0 and later, a problem occurs when %@AB@%SHARE%@AE@% is
  25983. installed and a new file is opened with %@AI@%oflag%@AE@% set to %@AB@%O_CREAT%@AE@% | %@AB@%O_RDONLY%@AE@% or%@AB@%
  25984. %@AB@%O_CREAT%@AE@% | %@AB@%O _WRONLY%@AE@% and %@AI@%pmode%@AE@% set to %@AB@%S_IREAD%@AE@%. Under these conditions, the
  25985. operating system prematurely closes the file during system calls made within
  25986. %@AB@%open%@AE@%. This problem does not occur under OS/2.  %@NL@%
  25987. %@NL@%
  25988. To work around the problem, open the file with the %@AI@%pmode%@AE@% argument set to
  25989. %@AB@%S_IWRITE%@AE@%. Then close the file and use %@AB@%chmod%@AE@% to change the access mode back
  25990. to %@AB@%S_IREAD%@AE@%. Another work-around is to open the file with %@AI@%pmode%@AE@% set to
  25991. %@AB@%S_IREAD%@AE@% and %@AI@%oflag%@AE@% set to %@AB@%O_CREAT%@AE@% | %@AB@%O_RDWR%@AE@%.  %@NL@%
  25992. %@NL@%
  25993. %@NL@%
  25994. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  25995. %@NL@%
  25996. The %@AB@%open%@AE@% function returns a file handle for the opened file. A return value
  25997. of -1 indicates an error, and %@AB@%errno%@AE@% is set to one of the following values:  %@NL@%
  25998. %@NL@%
  25999. %@AB@%Value%@AE@%                             %@AB@%Meaning%@AE@%
  26000. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  26001. %@AB@%EACCES%@AE@%                            Given path name is a directory; or an 
  26002.                                   attempt was made to open a read-only 
  26003.                                   file for writing; or a sharing violation
  26004.                                   occurred (the file's sharing mode does 
  26005.                                   not allow the specified operations).
  26006.  
  26007. %@AB@%EEXIST%@AE@%                            The %@AB@%O_CREAT%@AE@% and %@AB@%O_EXCL%@AE@% flags are 
  26008.                                   specified, but the named file already 
  26009.                                   exists.
  26010.  
  26011. %@AB@%EINVAL%@AE@%                            An invalid %@AI@%oflag%@AE@% or %@AI@%pmode%@AE@% argument was 
  26012.                                   given.
  26013.  
  26014. %@AB@%EMFILE%@AE@%                            No more file handles available (too many
  26015.                                   open files).
  26016.  
  26017. %@AB@%ENOENT%@AE@%                            File or path name not found.
  26018.  
  26019. %@NL@%
  26020. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  26021. %@NL@%
  26022.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2  %@AB@%%@AE@% UNIX  %@AB@%%@AE@% XENIX%@NL@%
  26023. %@NL@%
  26024. %@NL@%
  26025. %@NL@%
  26026. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  26027. %@NL@%
  26028. %@AB@%access%@AE@%, %@AB@%chmod%@AE@%, %@AB@%close%@AE@%, %@AB@%creat%@AE@%, %@AB@%dup%@AE@%, %@AB@%dup2%@AE@%, %@AB@%fopen%@AE@%, %@AB@%sopen%@AE@%, %@AB@%umask%@AE@%  %@NL@%
  26029. %@NL@%
  26030. %@NL@%
  26031. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  26032. %@NL@%
  26033. %@AS@%  /* OPEN.C: This program uses open to open a file named OPEN.C for input
  26034. %@AS@%   * and a file named OPEN.OUT for output. The files are then closed.
  26035. %@AS@%   */
  26036. %@AS@%  
  26037. %@AS@%  #include <fcntl.h>
  26038. %@AS@%  #include <sys\types.h>
  26039. %@AS@%  #include <sys\stat.h>
  26040. %@AS@%  #include <io.h>
  26041. %@AS@%  #include <stdio.h>
  26042. %@AS@%  
  26043. %@AS@%  void main()
  26044. %@AS@%  {
  26045. %@AS@%     int fh1, fh2;%@AE@%%@NL@%
  26046. %@NL@%
  26047. %@AS@%  fh1 = open( "OPEN.C", O_RDONLY );
  26048. %@AS@%     if( fh1 == -1 )
  26049. %@AS@%        perror( "open failed on input file" );
  26050. %@AS@%     else
  26051. %@AS@%     {
  26052. %@AS@%        printf( "open succeeded on input file\n" );
  26053. %@AS@%        close( fh1 );
  26054. %@AS@%     }
  26055. %@AS@%  
  26056. %@AS@%     fh2 = open( "OPEN.OUT", O_WRONLY | O_CREAT, S_IREAD | S_IWRITE );
  26057. %@AS@%     if( fh2 == -1 )
  26058. %@AS@%        perror( "open failed on output file" );
  26059. %@AS@%     else
  26060. %@AS@%     {
  26061. %@AS@%        printf( "open succeeded on output file\n" );
  26062. %@AS@%        close( fh2 );
  26063. %@AS@%     }
  26064. %@AS@%  }%@AE@%%@NL@%
  26065. %@NL@%
  26066. %@NL@%
  26067. %@3@%%@AB@%Output%@AE@%%@EH@%%@NL@%
  26068. %@NL@%
  26069. %@AS@%  
  26070. %@AS@%  
  26071. %@AS@%  open succeeded on input file
  26072. %@AS@%  open succeeded on output file%@AE@%%@NL@%
  26073. %@NL@%
  26074. %@NL@%
  26075. %@NL@%
  26076. %@NL@%
  26077. %@QR:_outgtext@%%@NL@%
  26078. %@2@%%@CR:C6A02181089 @%%@AB@%_outgtext%@AE@%%@EH@%%@NL@%
  26079. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  26080. %@NL@%
  26081. %@NL@%
  26082. %@3@%%@AB@%Description%@CR:C6A02181090 @%%@AE@%%@EH@%%@NL@%
  26083. %@NL@%
  26084. Prints font-based text in graphics mode.  %@NL@%
  26085. %@NL@%
  26086. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  26087. %@NL@%
  26088. %@AS@%  void _far_outgtext( unsigned char_far *text );%@AE@%%@NL@%
  26089. %@NL@%
  26090. %@AI@%text%@AE@%                              Text string to output
  26091.  
  26092. %@NL@%
  26093. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  26094. %@NL@%
  26095. The %@AB@%_outgtext%@AE@% function outputs on the screen the null-terminated string that
  26096. %@AI@%text%@AE@% points to. The text is output using the current font at the current
  26097. graphics position and in the current color.  %@NL@%
  26098. %@NL@%
  26099. No formatting is provided, in contrast to the standard console I/O library
  26100. routines such as %@AB@%printf%@AE@%.  %@NL@%
  26101. %@NL@%
  26102. After it outputs the text, %@AB@%_outgtext%@AE@% updates the current graphics position.
  26103. %@NL@%
  26104. %@NL@%
  26105. The %@AB@%_outgtext%@AE@% function operates only in graphics video modes (e.g.,
  26106. %@AB@%_MRES4COLOR%@AE@%). Because it is a graphics function, the color of text is set by
  26107. the %@AB@%_setcolor%@AE@% function, not by the %@AB@%_settextcolor%@AE@% function.  %@NL@%
  26108. %@NL@%
  26109. %@NL@%
  26110. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  26111. %@NL@%
  26112. None.  %@NL@%
  26113. %@NL@%
  26114. %@NL@%
  26115. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  26116. %@NL@%
  26117.  ANSI  %@AB@%%@AE@% DOS   OS/2   UNIX   XENIX%@NL@%
  26118. %@NL@%
  26119. %@NL@%
  26120. %@NL@%
  26121. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  26122. %@NL@%
  26123. %@AB@%_moveto%@AE@% functions,  %@AB@%_setcolor%@AE@%, %@AB@% _setfont%@AE@%  %@NL@%
  26124. %@NL@%
  26125. %@NL@%
  26126. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  26127. %@NL@%
  26128. %@AS@%  /* OUTGTXT.C illustrates font output using functions:
  26129. %@AS@%   *   _registerfonts        _setfont            _outgtext
  26130. %@AS@%   *   _unregisterfonts      _getfontinfo        _getgtextextent
  26131. %@AS@%   *   _setgtextvector
  26132. %@AS@%   */
  26133. %@AS@%  
  26134. %@AS@%  #include <conio.h>
  26135. %@AS@%  #include <stdio.h>
  26136. %@AS@%  #include <stdlib.h>
  26137. %@AS@%  #include <string.h>
  26138. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  26139. %@NL@%
  26140. %@AS@%  #define NFONTS 6
  26141. %@AS@%  
  26142. %@AS@%  unsigned char *face[NFONTS] =
  26143. %@AS@%  {
  26144. %@AS@%      "Courier", "Helvetica", "Times Roman", "Modern", "Script", "Roman"
  26145. %@AS@%  };
  26146. %@AS@%  unsigned char *options[NFONTS] =
  26147. %@AS@%  {
  26148. %@AS@%      "courier", "helv", "tms rmn", "modern", "script", "roman"
  26149. %@AS@%  };
  26150. %@AS@%  
  26151. %@AS@%  void main()
  26152. %@AS@%  {
  26153. %@AS@%      unsigned char list[20];
  26154. %@AS@%      char fondir[_MAX_PATH];
  26155. %@AS@%      struct videoconfig vc;
  26156. %@AS@%      struct _fontinfo fi;
  26157. %@AS@%      short fontnum, x, y;
  26158. %@AS@%  
  26159. %@AS@%      /* Read header info from all .FON files in current or given directory.
  26160. %@AS@%*/
  26161. %@AS@%      if( _registerfonts( "*.FON" ) <= 0 )
  26162. %@AS@%      {
  26163. %@AS@%          _outtext( "Enter full path where .FON files are located: " );
  26164. %@AS@%          gets( fondir );
  26165. %@AS@%          strcat( fondir, "\\*.FON" );
  26166. %@AS@%          if( _registerfonts( fondir ) <= 0 )
  26167. %@AS@%          {
  26168. %@AS@%              _outtext( "Error: can't register fonts" );
  26169. %@AS@%              exit( 1 );
  26170. %@AS@%          }
  26171. %@AS@%      }
  26172. %@AS@%  
  26173. %@AS@%      /* Set highest available graphics mode and get configuration. */
  26174. %@AS@%      if( !_setvideomode( _MAXRESMODE ) )
  26175. %@AS@%          exit( 1 );
  26176. %@AS@%      _getvideoconfig( &vc );
  26177. %@AS@%  
  26178. %@AS@%      /* Display each font name centered on screen. */
  26179. %@AS@%      for( fontnum = 0; fontnum < NFONTS; fontnum++ )
  26180. %@AS@%      {
  26181. %@AS@%          /* Build options string. */
  26182. %@AS@%          strcat( strcat( strcpy( list, "t'" ), options[fontnum] ), "'");
  26183. %@AS@%          strcat( list, "h30w24b" );
  26184. %@AS@%  
  26185. %@AS@%          _clearscreen( _GCLEARSCREEN );
  26186. %@AS@%          if( _setfont( list ) >= 0 )
  26187. %@AS@%          {%@AE@%%@NL@%
  26188. %@NL@%
  26189. %@AS@%  /* Use length of text and height of font to center text. */
  26190. %@AS@%              x = (vc.numxpixels / 2) - (_getgtextextent( face[fontnum] ) /
  26191. %@AS@%2);
  26192. %@AS@%              y = (vc.numypixels / 2) + (_getgtextextent( face[fontnum] ) /
  26193. %@AS@%2);
  26194. %@AS@%              if( _getfontinfo( &fi ) )
  26195. %@AS@%              {
  26196. %@AS@%                  _outtext( "Error: Can't get font information" );
  26197. %@AS@%                  break;
  26198. %@AS@%              }
  26199. %@AS@%              _moveto( x, y );
  26200. %@AS@%              if( vc.numcolors > 2 )
  26201. %@AS@%                  _setcolor( fontnum + 2 );
  26202. %@AS@%  
  26203. %@AS@%              /* Rotate and display text. */
  26204. %@AS@%              _setgtextvector( 1, 0 );
  26205. %@AS@%              _outgtext( face[fontnum] );
  26206. %@AS@%              _setgtextvector( 0, 1 );
  26207. %@AS@%              _outgtext( face[fontnum] );
  26208. %@AS@%              _setgtextvector( -1, 0 );
  26209. %@AS@%              _outgtext( face[fontnum] );
  26210. %@AS@%              _setgtextvector( 0, -1 );
  26211. %@AS@%              _outgtext( face[fontnum] );
  26212. %@AS@%          }
  26213. %@AS@%          else
  26214. %@AS@%          {
  26215. %@AS@%              _outtext( "Error: Can't set font: " );
  26216. %@AS@%              _outtext( list );
  26217. %@AS@%          }
  26218. %@AS@%          getch();
  26219. %@AS@%      }
  26220. %@AS@%      _unregisterfonts();
  26221. %@AS@%      _setvideomode( _DEFAULTMODE );
  26222. %@AS@%  }%@AE@%%@NL@%
  26223. %@NL@%
  26224. %@NL@%
  26225. %@NL@%
  26226. %@NL@%
  26227. %@QR:_outmem@%%@NL@%
  26228. %@2@%%@CR:C6A02191091 @%%@AB@%_outmem%@AE@%%@EH@%%@NL@%
  26229. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  26230. %@NL@%
  26231. %@NL@%
  26232. %@3@%%@AB@%Description%@CR:C6A02191092 @%%@AE@%%@EH@%%@NL@%
  26233. %@NL@%
  26234. Prints text of a specified length in graphics mode.  %@NL@%
  26235. %@NL@%
  26236. %@AS@%  #include <graph.h>%@AE@%%@NL@%
  26237. %@NL@%
  26238. %@AS@%  void _far_outmem( unsigned char_far *text, short length );%@AE@%%@NL@%
  26239. %@NL@%
  26240. %@AI@%text%@AE@%                              Text string to output
  26241.  
  26242. %@AI@%length%@AE@%                            Length of string to output
  26243.  
  26244. %@NL@%
  26245. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  26246. %@NL@%
  26247. The %@AB@%_outmem%@AE@% function outputs the string that %@AI@%text%@AE@% points to. The %@AI@%length%@AE@%
  26248. argument specifies the number of characters to output.  %@NL@%
  26249. %@NL@%
  26250. Unlike %@AB@%_outtext%@AE@%, the %@AB@%_outmem%@AE@% function prints all characters literally,
  26251. including ASCII 10, 13, and 0 as the equivalent graphics characters. No
  26252. formatting is provided. Text is printed using the current text color,
  26253. starting at the current text position.  %@NL@%
  26254. %@NL@%
  26255. To output text using special fonts, you must use the %@AB@%_outgtext%@AE@% function.  %@NL@%
  26256. %@NL@%
  26257. %@NL@%
  26258. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  26259. %@NL@%
  26260. None.  %@NL@%
  26261. %@NL@%
  26262. %@NL@%
  26263. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  26264. %@NL@%
  26265.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  26266. %@NL@%
  26267. %@NL@%
  26268. %@NL@%
  26269. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  26270. %@NL@%
  26271. %@AB@%_outtext%@AE@%,  %@AB@%_settextcolor%@AE@%,  %@AB@%_settextposition%@AE@%,  %@AB@%_settextwindow%@AE@%  %@NL@%
  26272. %@NL@%
  26273. %@NL@%
  26274. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  26275. %@NL@%
  26276. %@AS@%  /* OUTMEM.C illustrates:
  26277. %@AS@%   *    _outmem
  26278. %@AS@%   */
  26279. %@AS@%  
  26280. %@AS@%  #include <stdio.h>
  26281. %@AS@%  #include <graph.h>
  26282. %@AS@%  
  26283. %@AS@%  void main()
  26284. %@AS@%  {
  26285. %@AS@%      int  i, len;
  26286. %@AS@%      char tmp[10];%@AE@%%@NL@%
  26287. %@NL@%
  26288. %@AS@%  _clearscreen( _GCLEARSCREEN );
  26289. %@AS@%      for( i = 0; i < 256; i++ )
  26290. %@AS@%      {
  26291. %@AS@%          _settextposition( (i % 24) + 1, (i / 24) * 7 );
  26292. %@AS@%          len = sprintf( tmp, "%3d %c", i, i );
  26293. %@AS@%          _outmem( tmp, len );
  26294. %@AS@%      }
  26295. %@AS@%      _settextposition( 24, 1 );
  26296. %@AS@%  }%@AE@%%@NL@%
  26297. %@NL@%
  26298. %@NL@%
  26299. %@NL@%
  26300. %@NL@%
  26301. %@QR:outp@%%@QR:outpw@%%@NL@%
  26302. %@2@%%@CR:C6A02201093 @%%@AB@%outp, outpw%@AE@%%@EH@%%@NL@%
  26303. %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%
  26304. %@NL@%
  26305. %@NL@%
  26306. %@3@%%@AB@%Description%@CR:C6A02201094 @%%@CR:C6A02201095 @% %@CR:C6A02201096 @%%@CR:C6A02201097 @%%@AE@%%@EH@%%@NL@%
  26307. %@NL@%
  26308. Outputs a byte (%@AB@%outp%@AE@%) or a word (%@AB@%outpw%@AE@%) at a port.  %@NL@%
  26309. %@NL@%
  26310. %@AS@%  #include <conio.h>    Required only for function declarations%@AE@%%@NL@%
  26311. %@NL@%
  26312. %@AS@%  int outp( unsigned port, int databyte );%@AE@%%@NL@%
  26313. %@NL@%
  26314. %@AS@%  unsigned outpw( unsigned port, unsigned dataword );%@AE@%%@NL@%
  26315. %@NL@%
  26316. %@AI@%port%@AE@%                              Port number
  26317.  
  26318. %@AI@%databyte%@AE@%                          Output value
  26319.  
  26320. %@AI@%dataword%@AE@%                          Output value
  26321.  
  26322. %@NL@%
  26323. %@3@%%@AB@%Remarks%@AE@%%@EH@%%@NL@%
  26324. %@NL@%
  26325. The %@AB@%outp%@AE@% and %@AB@%outpw%@AE@% functions write a byte and a word, respectively, to the
  26326. specified output port. The %@AI@%port%@AE@% argument can be any unsigned integer in the
  26327. range 0 - 65,535; %@AI@%byte%@AE@%  can be any integer in the range 0 - 255; and
  26328. %@AI@%dataword%@AE@% can be any value in the range 0 - 65,535.  %@NL@%
  26329. %@NL@%
  26330. Both %@AB@%outp%@AE@% and %@AB@%outpw%@AE@% are supported in OS/2. You must use a .DEF file to
  26331. declare the IOSEG segment the run-time library uses to perform input/output
  26332. on the port. In addition, the intrinsic (/Oi) versions of these functions do
  26333. not work unless you put the code in a segment that is marked with the %@AB@%IOPL%@AE@%
  26334. keyword in the .DEF file.  %@NL@%
  26335. %@NL@%
  26336. You cannot do IOPL from a regular code segment, so the run-time library has
  26337. declared a separate code segment called %@AB@%_IOSEG%@AE@%. In order to use %@AB@%inp%@AE@%, %@AB@%inpw%@AE@%,
  26338. %@AB@%outp%@AE@%, or %@AB@%outp%@AE@% in any of the protected mode run-time libraries (?LIBCP,
  26339. LLIBCDLL, LLIBCMT, or CDLLOBJS-based DLL), you must have a .DEF file with
  26340. this line in it:  %@NL@%
  26341. %@NL@%
  26342. %@AS@%  SEGMENTS _IOSEG CLASS 'IOSEG_CODE' IOPL%@AE@%%@NL@%
  26343. %@NL@%
  26344. %@NL@%
  26345. %@3@%%@AB@%Return Value%@AE@%%@EH@%%@NL@%
  26346. %@NL@%
  26347. The functions return the data output. There is no error return.  %@NL@%
  26348. %@NL@%
  26349. %@NL@%
  26350. %@3@%%@AB@%Compatibility%@AE@%%@EH@%%@NL@%
  26351. %@NL@%
  26352.  ANSI  %@AB@%%@AE@% DOS  %@AB@%%@AE@% OS/2   UNIX   XENIX%@NL@%
  26353. %@NL@%
  26354. %@NL@%
  26355. %@NL@%
  26356. %@3@%%@AB@%See Also%@AE@%%@EH@%%@NL@%
  26357. %@NL@%
  26358. %@AB@%inp%@AE@%, %@AB@%inpw%@AE@%  %@NL@%
  26359. %@NL@%
  26360. %@NL@%
  26361. %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@%
  26362. %@NL@%
  26363. %@AS@%  /* OUTP.C: This program uses inp and outp to make sound of variable tone
  26364. %@AS@%   * and duration.
  26365. %@AS@%   */%@AE@%%@NL@%
  26366. %@NL@%
  26367. %@AS@%  #include <conio.h>
  26368. %@AS@%  #include <stdio.h>
  26369. %@AS@%  #include <time.h>
  26370. %@AS@%  
  26371. %@AS@%  void Beep( unsigned duration, unsigned frequency ); /* Prototypes */
  26372. %@AS@%  void Sleep( clock_t wait );
  26373. %@AS@%  
  26374. %@AS@%  void main ()
  26375. %@AS@%  {
  26376. %@AS@%      Beep( 698, 700 );
  26377. %@AS@%      Beep( 523, 500 );
  26378. %@AS@%  }
  26379. %@AS@%  
  26380. %@AS@%  /* Sounds the speaker for a time specified in microseconds by duration
  26381. %@AS@%   * at a pitch specified in hertz by frequency.
  26382. %@AS@%   */
  26383. %@AS@%  void Beep( unsigned frequency, unsigned duration )
  26384. %@AS@%  {
  26385. %@AS@%      int control;
  26386. %@AS@%  
  26387. %@AS@%      /* If frequency is 0, Beep doesn't try to make a sound. */
  26388. %@AS@%      if( frequency )
  26389. %@AS@%