home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c221 / 1.ddi / DOC / README.LIB < prev    next >
Encoding:
Text File  |  1992-08-20  |  29.2 KB  |  926 lines
  1.        Copyright (C) 1992 MetaWare Incorporated; All Rights Reserved.
  2.  
  3.                           High C/C++ Version 3.0
  4.                        Globally Optimizing Compiler
  5.                 for Extended DOS 80386/486 and Windows 3.0
  6.                                 August 1992
  7.  
  8.                       +------------------------------+
  9.                       |  Notes on Library Functions  |
  10.                       +------------------------------+
  11.  
  12.  
  13. About terminology:
  14.  
  15.    GOC (Globally Optimizing Compiler) refers to v2.x and v3.0 libraries.
  16.    LOC (Locally Optimizing Compiler) refers to v1.7x and earlier libraries.
  17.  
  18.  
  19. Table of Contents
  20. -----------------
  21. 1. GOC Library Functions NOT Implemented in the LOC Library
  22. 2. Additions/Corrections to Printed Documentation
  23. 3. Undocumented Functions
  24.  
  25.  
  26. 1. GOC Library Functions NOT Implemented in the LOC Library
  27. -----------------------------------------------------------
  28.  
  29. long double           _atold(const char *__nptr);
  30. unsigned short int    _clear87(void);
  31. unsigned short int    _control87(unsigned short int __cw,
  32.                                  unsigned short int __mask);
  33. int                    cscanf(char *, ...);
  34. int                   _dieeetomsbin(double *__x, double *__x1);
  35. int                   _dmsbintoieee(double *__x, double *__x1);
  36. char *                 ecvt(double, int, int *, int *);
  37. int                    fclosall(void);
  38. char *                 fcvt(double, int, int *, int *);
  39. int                   _fieeetomsbin(float *__x, float *__x1);
  40. int                    flushall(void);
  41. int                   _fmsbintoieee(float *__x, float *__x1);
  42.                        fstat(int __handle, struct stat * __buffer);
  43. char *                 gcvt(double, int, char *);
  44. short                 _getfontinfo( struct _fontinfo * );
  45. short                 _getpixel_w(double, double);
  46. short                 _gettextcursor(void);
  47. short                 _getgtextextent( const char * );
  48. struct xycoord        _getgtextvector(void);
  49. struct _xycoord       _getviewcoord_w(double,double);
  50. struct _xycoord       _getviewcoord_wxy(struct _wxycoord * pwxy1);
  51. int                    getw(FILE *_stream);
  52. struct _wxycoord      _getwindowcoord(short,short);
  53. int                   _isodigit(int __c);
  54. double                 j0(double __x);
  55. double                 j1(double __x);
  56. double                 jn(int __n, double __x);
  57. short                 _lineto_w(double, double);
  58. int                    matherr (struct exception *__s);
  59. int                    matherrx (struct exception *__s);
  60. void                  _outgtext( const unsigned char * );
  61. int                    putw(int _int1, FILE * _stream);
  62. short                 _rectangle_w(short, double, double, double, double);
  63. short                 _rectangl_wxy(short, struct _wxycoord *,
  64.                                            struct _wxycoord *);
  65. short                 _registerfonts( const char *);
  66. short                 _setfont( const unsigned char * );
  67. struct xycoord        _setgtextvector( short, short );
  68. short                 _setpixel_w(double x, double y);
  69. short                 _settextcursor(short attr);
  70. short                 _settextrows(short rows);
  71. short                 _setwindow(short,double,double,double,double);
  72. void                  _stkdmp(int __filehandle);
  73. char *                 tempnam(char *dir,char *prefix);
  74. int                    unlink(const char *__pathname);
  75. void                  _unregisterfonts( void );
  76. double                 yn(int __n, double __x);
  77. double                 y0(double __x);
  78. double                 y1(double __x);
  79.  
  80.  
  81. 2.  Additions/Corrections to Printed Documentation
  82. --------------------------------------------------
  83.  
  84. log(), log10()
  85.  
  86.    The log() and log10() functions are documented to return -HUGE_VAL if
  87.    passed a value <= 0.0; in fact, the functions return 0.0.  This behavior is
  88.    outside ANSI specifications ("A domain error occurs if the argument is
  89.    negative.  A range error may occur if the argument is zero.") and should
  90.    not be relied upon.
  91.  
  92. _setlogorg()
  93.  
  94.    This function was incorrectly documented to take void as its argument.
  95.    The proper usage is:
  96.  
  97.    struct xycoord{ short xcoord, short ycoord } _setlogorg(short x, short y);
  98.  
  99.    The return value is the previous logical coordinate of the origin.
  100.  
  101. _setvideomode()
  102.  
  103.    The macro _ERESCOLOR was incorrectly documented to supply 64 colors and
  104.    640x480 resolution.  The correct attributes are 16 colors and 640x350
  105.    resolution.
  106.  
  107.  
  108. 3. Undocumented Functions
  109. -------------------------
  110.  
  111. _bios_disk     Configuration and status information for a floppy- or hard-
  112.                   disk drive.  Real mode only.
  113. _bios_memsize  Determines the amount of DOS-accessible memory installed.
  114. _fdopen        Associate a stream with an open handle.
  115. _fgetchar      Get a character from standard input.
  116. _getpvect      Get the current protected-mode interrupt handler.
  117. _getrvect      Get the real-mode vector.
  118. _setactivepage Current active screen page.
  119. _setpixel      Color value of a single graphics pixel.
  120. _setrpvectp    Set both the protected- and real-mode vectors to point
  121.                   to a protected-mode handler.
  122. _setpvect      Set the protected mode vector.
  123. _setrvect      Set the real-mode handler.
  124. _strdate       Report the date as a string.
  125.  
  126. ---------------------------------------------------------------------------
  127. _bios_disk     Configuration and status information for a floppy- or hard-
  128.                   disk drive.  Real mode only.
  129. ---------------------------------------------------------------------------
  130.  
  131. DOS Only
  132. Reentrant
  133.  
  134. SYNOPSIS
  135.  
  136.    #include <stdio.h>
  137.    #include <bios.h>                                         /* Required */
  138.    unsigned _bios_disk(
  139.       unsigned service,     /* (See below for table.)                    */
  140.       struct diskinfo_t{    /*  Structure to hold arguments.             */
  141.          unsigned drive;    /*  Drive number (add 80H for hard disk).    */
  142.          unsigned head;     /*  Head number.                             */
  143.          unsigned track;    /*  Track number.                            */
  144.          unsigned sector;   /*  Starting sector.                         */
  145.          unsigned nsectors; /*  # sectors to read, write, or compare     */
  146.          void far *buffer   /*  Buffer to read, write, or compare.       */
  147.          } *info);
  148.  
  149. DESCRIPTION
  150.  
  151.    The _bios_disk routine uses BIOS INT 13h to provide access to several
  152.    disk functions.  service selects the function desired, and info holds
  153.    the agruments necessary to identify the area of the disk to be accessed.
  154.  
  155.    service can be set to one of the following manifest constants found in
  156.    bios.h:
  157.  
  158.    Constant         Function performed
  159.    --------         ------------------
  160.    _DISK_RESET      Causes the disk controller to perform a hard reset,
  161.                     preparing for floppy-disk I/O.  This is useful after an
  162.                     error occurs in another operation, such as a read.  If
  163.                     this service is specified, info is ignored.
  164.  
  165.    _DISK_STATUS     Returns the status of the last disk operation.  info is
  166.                     ignored and the status is returned in the high-order
  167.                     byte of the return value as:
  168.  
  169.                        Value     Meaning
  170.                        -----     -------
  171.                        0x00      No error.
  172.                        0x01      Invalid function.
  173.                        0x02      Bad address mark.
  174.                        0x03      Write-protect violation.
  175.                        0x04      Sector not found.
  176.                        0x05      Reset failed.
  177.                        0x06      Media removed.
  178.                        0x07      Initialization error.
  179.                        0x08      DMA failure.
  180.                        0x09      DMA address error.
  181.                        0x0A      Bad sector encountered.
  182.                        0x10      Parity error.
  183.                        0x11      Corrected parity error.
  184.                        0x20      Controller failure.
  185.                        0x40      Seek failure.
  186.                        0x80      Time-out.
  187.                        0xAA      Drive not ready.
  188.                        0xBB      Unknown error.
  189.                        0xCC      Write fault.
  190.                        0xE0      Status error.
  191.                        0xFF      Sense failure.
  192.  
  193.    _DISK_READ       Reads one or more disk sectors into memory.  This
  194.                     service uses all fields of the structure that info
  195.                     points to.  If no error occurs, the function returns
  196.                     zero in the high-order byte and the number of sectors
  197.                     read in the low-order byte.  If there is an error, the
  198.                     high-order byte will contain a value as defined under
  199.                     _DISK_STATUS.
  200.  
  201.    _DISK_WRITE      Writes data from memory to one or more disk sectors.
  202.                     This service uses all fields of the structure that info
  203.                     points to.  If no error occurs, the function return
  204.                     zero in the high-order byte and the number of sectors
  205.                     read in the low-order byte.  If there is an error, the
  206.                     high-order byte will contain a value as defined under
  207.                     _DISK_STATUS.
  208.  
  209.    _DISK_VERIFY     Checks the disk to be sure the specified sectors exist
  210.                     and can be read.  Also runs a cyclical redundancy test.
  211.                     This service uses all fields of the structure that info
  212.                     points to except buffer.  If no error occurs, the func-
  213.                     tion returns zero in the high-order byte and the number
  214.                     of sectors read in the low-order byte.  If there is an
  215.                     error, the high-order byte will contain a value as
  216.                     defined under _DISK_STATUS.
  217.  
  218.    _DISK_FORMAT     Formats the track specified by info.  Only one track
  219.                     can be formatted in a single call.  buffer points to a
  220.                     set of sector markers.  The format of those markers
  221.                     depends on the type of disk drive being formatted.  See
  222.                     the appropriate Technical Reference Manual for your
  223.                     drive to determine the correct marker format.  There is
  224.                     no return value for this service.
  225.  
  226. CAUTIONS
  227.  
  228.    _bios_disk() provides raw disk I/O which was originally intended only for
  229.    floppy disks.  Reads and writes are from/to actual physical disk sectors.
  230.    It is possible to damage your system and destroy data while using this
  231.    function.  Refer to a good DOS technical manual for complete explanations
  232.    of error codes.
  233.  
  234. RETURN VALUE
  235.  
  236.    Return values are specific to each service as indicated above.
  237.  
  238.    /*
  239.       This program tests status of Drive C.
  240.       Assumes High C users will always have a hard disk drive.
  241.    */
  242.  
  243.    #include <stdio.h>
  244.    #include <bios.h>
  245.  
  246.    void main() {
  247.       unsigned status = 0;
  248.       struct diskinfo_t info;
  249.  
  250.       info.drive    = 0x80;  /* Drive C:                                 */
  251.       info.head     = 0;     /* Use the boot sector.                     */
  252.       info.track    = 0;
  253.       info.sector   = 1;
  254.       info.nsectors = 1;
  255.       info.buffer   = 0;
  256.  
  257.       status = _bios_disk(_DISK_STATUS, &info);
  258.       printf("Status of disk drive C: is %x",status);
  259.       }
  260.  
  261.  
  262.    prints:
  263.  
  264.    Status of disk drive C: is 0
  265.  
  266.  
  267. ---------------------------------------------------------------------------
  268. _bios_memsize  Determines the amount of DOS-accessible memory installed.
  269. ---------------------------------------------------------------------------
  270.  
  271. DOS Only
  272. Reentrant
  273.  
  274. SYNOPSIS
  275.  
  276.    #include <bios.h>
  277.    unsigned _bios_memsize (void);
  278.  
  279. DESCRIPTION
  280.  
  281.    _bios_memsize() uses  BIOS  INT 12h to determine the amount of DOS-
  282.    accessible memory installed.  The return value is the number of 1K blocks,
  283.    with a maximum possible value of 640.
  284.  
  285. RETURN VALUE
  286.  
  287.    Amount of DOS-accessible memory in 1K blocks.
  288.  
  289. EXAMPLE
  290.  
  291. /*
  292.    This program prints the amount of system memory.
  293. */
  294.  
  295. #include <stdio.h>
  296. #include <bios.h>
  297.  
  298. void main() {
  299.    unsigned memsize;
  300.  
  301.    memsize = _bios_memsize();
  302.    printf("The amount of system memory "
  303.           "is %uKB \n", memsize);
  304.    }
  305.  
  306.  
  307. prints (may vary):
  308.  
  309. The amount of system memory is 640KB
  310.  
  311.  
  312. --------------------------------------------------------
  313. _fdopen       Associate a stream with an open handle.
  314. --------------------------------------------------------
  315.  
  316. DOS Only
  317. Not Reentrant
  318.  
  319. SYNOPSIS
  320.  
  321.    #include <fcntl.h>                         /* Required for constants. */
  322.    #include <stdio.h>
  323.    FILE *_fdopen(int handle, char *mode);
  324.  
  325. DESCRIPTION
  326.  
  327.    _fdopen() associates a stream  with  handle, and returns a pointer to that
  328.    stream.  handle must be a valid open  file  handle.    Furthermore, mode
  329.    must match the  mode in which handle was opened.  If mode does not match
  330.    the actual opening mode of the handle, the behavior  that  results  from
  331.    using the stream is undefined.
  332.  
  333. RETURN VALUE
  334.  
  335.    _fdopen returns NULL on error, and sets errno appropriately.
  336.  
  337. CAUTIONS
  338.  
  339.    The opening mode of the stream is not validated against the opening mode
  340.    of the handle.  If the two do not match, the results of using the stream
  341.    are undefined.
  342.  
  343. SEE ALSO
  344.  
  345.    fopen for a description of the mode string.
  346.    _fsopen, _open, _sopen
  347.  
  348. EXAMPLE
  349.  
  350. #include <fcntl.h>
  351. #include <io.h>
  352. #include <share.h>
  353. #include <stdio.h>
  354. #include <stdlib.h>
  355.  
  356. void main(void) {
  357.    FILE *fp;
  358.    int pan;
  359.    char c;
  360.  
  361. _fdopen= _sopen("test.dat",
  362.                 O_RDONLY | O_TEXT,
  363.                 _SH_DENYWR
  364.                 );
  365.    if (pan != -1)
  366.       printf("File test.dat exists, handle=%d\n", pan);
  367.    else
  368.       printf("File test.dat cannot be sopened,"
  369.              " error code=%d\n",pan);
  370.    if((fp = _fdopen(pan, "r")) == NULL) {
  371.       perror("Error opening test.dat");
  372.       return;
  373.       }
  374.    /* Get and print characters until the end of file. */
  375.    while((c = fgetc(fp)) != EOF)
  376.       printf("%c", c);
  377.  
  378.    /* Close the file.  Now any other process can read and write to the file
  379.       test.dat until some other process puts a lock on it. */
  380.    fclose(fp);
  381.    }
  382.  
  383.  
  384. Given that the contents of test.dat are:
  385.  
  386.    testing 1 abcd
  387.    testing=2 efgh
  388.    testing=3 ijkl
  389.    testing=4 mnop
  390.    testing=5 qrst
  391.    testing=6 uvwx
  392.    testing=7 yzAB
  393.    testing=8 CDEF
  394.  
  395. the program prints:
  396.  
  397.    File test.dat exists, handle=5
  398.    testing 1 abcd
  399.    testing=2 efgh
  400.    testing=3 ijkl
  401.    testing=4 mnop
  402.    testing=5 qrst
  403.    testing=6 uvwx
  404.    testing=7 yzAB
  405.    testing=8 CDEF
  406.  
  407.  
  408. ------------------------------------------------------
  409. _fgetchar      Get a character from standard input.
  410. ------------------------------------------------------
  411.  
  412. Not Reentrant
  413.  
  414. SYNOPSIS
  415.  
  416.    #include <stdio.h>
  417.    int fgetchar(void);
  418.  
  419. DESCRIPTION
  420.  
  421.    fgetchar() is equivalent to fgetc(stdin); see fgetc().
  422.  
  423.    The function fgetchar() performs a getc(stdin).
  424.  
  425. SEE ALSO
  426.  
  427.    fgetc, fgets, fputc, fputs,  getc,  getchar,  gets, putc, putchar, puts,
  428.    ungetc.
  429.  
  430.    For short descriptions of the listed functions, see the SEE ALSO section
  431.    for fgetc.
  432.  
  433. EXAMPLE
  434.  
  435. /*
  436.    This program copies standard input character by character to
  437.    fgetchar.tmp and to standard output.  Similar examples are given for
  438.    fgetc and getc, pointing out the differences among the functions.
  439. */
  440.    #include <stdio.h>
  441.  
  442.    void main() {
  443.       FILE *FP1;
  444.  
  445.       if ((FP1 = fopen("fgetchar.tmp", "w")) == NULL)
  446.          perror("Cannot open fgetchar.tmp.");
  447.       printf("Please enter text, ending"
  448.              " with the ENTER key.\n\n");
  449.       while ('\n' != fputc(fputchar(fgetchar()), FP1));
  450.       }
  451.  
  452.  
  453. ------------------------------------------------------------------
  454. _getpvect     Get the current protected-mode interrupt handler.
  455. ------------------------------------------------------------------
  456.  
  457. DOS Only
  458. Not Reentrant
  459.  
  460. SYNOPSIS
  461.  
  462.    #include <dos.h>                                         /* Required. */
  463.    _Far _INTERRPT void (* _getpvect(int intno))();
  464.  
  465. DESCRIPTION
  466.  
  467.    _getpvect() returns a 48-bit pointer to a function that returns void.
  468.  
  469.    This is one of several functions (see the SEE ALSO section)  intended to
  470.    provide 80386/486 support  similar  to that provided by _dos_setvect() and
  471.    _dos_getvect() in the 80x86 16-bit library.
  472.  
  473.    Because protected-mode DOS  extenders handle interrupts differently from
  474.    normal DOS, _dos_setvect() and _dos_getvect() cannot be used in protected
  475.    mode.
  476.  
  477. RETURN VALUE
  478.  
  479.    Returns the address of the  current protected-mode handler for intno, or
  480.    -1 if the operation fails.
  481.  
  482. CAUTIONS
  483.  
  484.    Under OS/386 _getpvect does, in fact, mirror the usage of _dos_getvect.
  485.  
  486.    If you install your own interrupt  handler,  be sure to save and restore
  487.    the previous handler.  If you  do  not restore the original handler, the
  488.    machine may exhibit unexpected behavior after the program exits.
  489.  
  490. SYSTEM DEPENDENCIES
  491.  
  492.    This  function detects the DOS extender  currently  installed  and  acts
  493.    accordingly.  You can determine which environment the program is running
  494.    in by testing  the value of the extern char variable _mwenv.  A value of
  495.    2 indicates Phar Lap's 386|DOS-Extender, 3 indicates Ergo's OS/386.
  496.  
  497. SEE ALSO
  498.  
  499.      _getrvect    To get the real-mode vector.
  500.  
  501.      _setrpvectp  To set both the protected- and real-mode vectors to point
  502.                   to a protected-mode handler.
  503.  
  504.      _setpvect    To set the protected mode vector.
  505.  
  506.      _setrvect    To set the real-mode handler.
  507.  
  508. EXAMPLE
  509.  
  510.  
  511.    See the example provided for _setrpvectp.
  512.  
  513.  
  514. -------------------------------------------------------------
  515. _getrvect     Get the current real-mode interrupt handler.
  516. -------------------------------------------------------------
  517.  
  518. DOS Only
  519. Not Reentrant
  520.  
  521. SYNOPSIS
  522.  
  523.    #include <dos.h>
  524.    _real_int_handler_t _getrvect(int intno);
  525.  
  526. DESCRIPTION
  527.  
  528.    This is one of several functions (see the SEE ALSO section)  intended to
  529.    provide 80386/486 support similar to that provided by _dos_setvect() and
  530.    _dos_getvect() in the 80x86 16-bit library.
  531.  
  532.    Because protected-mode DOS extenders handle interrupts differently from
  533.    normal DOS, _dos_setvect() and _dos_getvect() cannot be used in protected
  534.    mode.
  535.  
  536. RETURN VALUE
  537.  
  538.    _getrvect() returns the address of the current real-mode handler for
  539.    intno, or -1 if the operation fails.
  540.  
  541. CAUTIONS
  542.  
  543.    If you install your own interrupt  handler,  be sure to save and restore
  544.    the previous handler.  If you  do  not restore the original handler, the
  545.    machine may exhibit unexpected behavior after the program exits.
  546.  
  547. SYSTEM DEPENDENCIES
  548.  
  549.    This function is not supported for  OS/386.   The function returns -1 if
  550.    it is called under OS/386.
  551.  
  552.    This  function detects the DOS extender  currently  installed  and  acts
  553.    accordingly.  You can determine which environment the program is running
  554.    in by testing  the value of the extern char variable _mwenv.  A value of
  555.    2 indicates Phar Lap's 386|DOS-Extender, 3 indicates Ergo's OS/386.
  556.  
  557.      _getpvect    To get the protected-mode vector.
  558.  
  559.      _setrpvectp  To set both the protected- and real-mode vectors to point
  560.                   to a protected-mode handler.
  561.  
  562.      _setpvect    To set the protected-mode vector.
  563.  
  564.      _setrvect    To set the real-mode handler.
  565.  
  566. EXAMPLE
  567.  
  568.    See the example provided for _setrpvectp.
  569.  
  570.  
  571. ---------------------------------------------
  572. _setactivepage Current active screen page.
  573. ---------------------------------------------
  574.  
  575. DOS Only
  576. Not Reentrant
  577.  
  578. SYNOPSIS
  579.  
  580.    #include <graph.h>
  581.    short _setactivepage(short page);
  582.  
  583. DESCRIPTION
  584.  
  585.    _setactivepage() allows you to set the current active screen page to an
  586.    alternate page.  The default page is page zero.
  587.  
  588.    Consult a standard DOS reference for more information on how many pages
  589.    are available under different display modes on different video cards.
  590.  
  591. RETURN VALUE
  592.  
  593.    _setactivepage returns the previous active page.
  594.  
  595. SEE ALSO
  596.  
  597.    _getvideoconfig, _setvideomode, _setvisualpage
  598.  
  599.  
  600. --------------------------------------------------------
  601. _setpixel     Color value of a single graphics pixel.
  602. --------------------------------------------------------
  603.  
  604. DOS Only
  605. Not Reentrant
  606.  
  607. SYNOPSIS
  608.  
  609.    #include <graph.h>
  610.    short _setpixel(short x, short y);
  611.  
  612. DESCRIPTION
  613.  
  614.    _setpixel() sets the pixel at (x, y) to the current color, and returns the
  615.    previous color value of the pixel.
  616.  
  617. SEE ALSO
  618.  
  619.    _getpixel
  620.  
  621.  
  622. ----------------------------------------------------------
  623. _setpvect     Set the protected-mode interrupt handler.
  624. ----------------------------------------------------------
  625.  
  626. DOS Only
  627. Not Reentrant
  628.  
  629. SYNOPSIS
  630.  
  631.    #include <dos.h>
  632.    int _setpvect(int intno,
  633.                  _Far _INTERRPT void(* handler)()
  634.                 );
  635.  
  636. DESCRIPTION
  637.  
  638.    _setpvect() installs handler as the protected-mode  interrupt  handler for
  639.    intno.  This is one of several functions (see the SEE ALSO section)
  640.    intended to provide 80386/486 support similar to that provided by
  641.    _dos_setvect() and _dos_getvect() in the 80x86 16-bit library.
  642.  
  643.    Because protected-mode DOS extenders handle interrupts differently from
  644.    real-mode DOS, _dos_setvect() and _dos_getvect() cannot be used in
  645.    protected mode.
  646.  
  647. RETURN VALUE
  648.  
  649.    The  function returns -1 if the operation fails.    If  successful,  the
  650.    function returns zero.
  651.  
  652. CAUTIONS
  653.  
  654.    If you install your own interrupt  handler,  be sure to save and restore
  655.    the previous handler.  If you  do  not restore the original handler, the
  656.    machine may exhibit unexpected behavior after the program exits.
  657.  
  658. SYSTEM DEPENDENCIES
  659.  
  660.    This function is not supported for  OS/386.   The function returns -1 if
  661.    it is called under OS/386.
  662.  
  663.    This  function detects the DOS extender  currently  installed  and  acts
  664.    accordingly.  You can determine which environment the program is running
  665.    in by testing  the value of the extern char variable _mwenv.  A value of
  666.    2 indicates Phar Lap's 386|DOS-Extender, 3 indicates Ergo's OS/386.
  667.  
  668. SEE ALSO
  669.  
  670.      _getpvect    To get the protected-mode vector.
  671.  
  672.      _getrvect    To get the real-mode vector.
  673.  
  674.      _setrpvectp  To set both the protected- and real-mode vectors to point
  675.                   to a protected-mode handler.
  676.  
  677.      _setrvect    To set the real-mode handler.
  678.  
  679. EXAMPLE
  680.  
  681.    See the example provided for _setrpvectp.
  682.  
  683.  
  684. --------------------------------------------------------------------------
  685. _setrpvectp    Set the real-mode and protected-mode interrupt handlers.
  686. --------------------------------------------------------------------------
  687.  
  688. DOS Only
  689. Not Reentrant
  690.  
  691. SYNOPSIS
  692.  
  693.    #include <dos.h>
  694.    int _setrpvectp(int intno,
  695.                    _Far _INTERRPT void(* pmhandler)()
  696.                   );
  697.  
  698. DESCRIPTION
  699.  
  700.    _setrpvectp() installs handler as the real-mode interrupt handler for
  701.    intno.  Both real-mode and protected-mode vectors point to the
  702.    protected-mode handler pmhandler.
  703.  
  704.    This is one of several functions (see the SEE ALSO section) intended to
  705.    provide 80386/486 support similar to that provided by _dos_setvect() and
  706.    _dos_getvect() in the 80x86 16-bit library.
  707.  
  708.    Because protected-mode DOS extenders handle interrupts differently from
  709.    real-mode DOS, _dos_setvect() and _dos_getvect() cannot be used in
  710.    protected mode.
  711.  
  712. RETURN VALUE
  713.  
  714.    The  function returns -1 if the operation fails.    If  successful,  the
  715.    function returns zero.
  716.  
  717. CAUTIONS
  718.  
  719.    Note that under OS/386 _setrpvectp() does, in fact, mirror the usage of
  720.    _dos_setvect().
  721.  
  722.    If you install your own interrupt  handler,  be sure to save and restore
  723.    the previous handler.  If you  do  not restore the original handler, the
  724.    machine may exhibit unexpected behavior after the program exits.
  725.  
  726. SYSTEM DEPENDENCIES
  727.  
  728.    This  function detects the DOS extender  currently  installed  and  acts
  729.    accordingly.  You can determine which environment the program is running
  730.    in by testing  the value of the extern char variable _mwenv.  A value of
  731.    2 indicates Phar Lap's 386|DOS-Extender, 3 indicates Ergo's OS/386.
  732.  
  733. SEE ALSO
  734.  
  735.      _getpvect    To get the protected-mode vector.
  736.  
  737.      _getrvect    To get the real-mode vector.
  738.  
  739.      _setpvect    To set the protected-mode handler.
  740.  
  741.      _setrvect    To set the real-mode handler.
  742.  
  743. EXAMPLE
  744.  
  745. #include <dos.h>
  746. #include <stdio.h>
  747. #include <stdlib.h>
  748.  
  749. int Num_Ctrl_Cs = 0;
  750.  
  751. _Far void _INTERRPT handler(void) {
  752.    Num_Ctrl_Cs++;
  753.    }
  754.  
  755. void main(void) {
  756.    int i, intno = 0x23;              /* 0x23 is the Control-C interrupt. */
  757.    _real_int_handler_t saver;
  758.    _Far _INTERRPT void (* savep)() = (_Far) NULL;
  759.  
  760.    saver = _getrvect(intno);                    /* Get original vectors. */
  761.    savep = _getpvect(intno);
  762.  
  763.    /*
  764.       Set both vectors to point to protected-mode handler.
  765.    */
  766.  
  767.    if(_setrpvectp(intno, handler) == -1 ) {
  768.       fprintf(stderr, "Failed to install handler\n");
  769.       return;
  770.       }
  771.  
  772.    printf("Hit Control-C for a little while.\n");
  773.    for(i = 0; i < 5000; i++)
  774.       printf("\r%5d", i);
  775.    printf("Number of Control C's = %d.\n", Num_Ctrl_Cs);
  776.  
  777.    /* Restore real-mode handler. */
  778.    if(_setrvect(intno, saver) == -1 ) {
  779.       fprintf(stderr, "Failed to restore"
  780.               " real-mode handler.\n");
  781.       return;
  782.       }
  783.  
  784.    /* Restore protected-mode handler. */
  785.    if(_setpvect(intno, savep) == -1 ) {
  786.       fprintf(stderr, "Failed to restore"
  787.               " protected-mode handler.\n");
  788.       return;
  789.       }
  790.    return;
  791.    }
  792.  
  793.  
  794. prints (will vary):
  795.  
  796.    Hit Control-C for a little while.
  797.    ^C215
  798.      ^C3
  799.     ^C19
  800.    ^C868
  801.     2444^C
  802.     ^C49
  803.     41^C
  804.     ^C78
  805.     4999
  806.    Number of Control C's = 8.
  807.  
  808.  
  809. -----------------------------------------------------
  810. _setrvect     Set the real-mode interrupt handler.
  811. -----------------------------------------------------
  812.  
  813. DOS Only
  814. Not Reentrant
  815.  
  816. SYNOPSIS
  817.  
  818.    #include <dos.h>
  819.    int _setrvect(int intno,
  820.                  _real_int_handler_t rmhandler
  821.                 );
  822.  
  823. DESCRIPTION
  824.  
  825.    _setrvect() installs handler as the real-mode interrupt handler for intno.
  826.    _setrvect() can be used only to restore the vector to a handler previously
  827.    read with _getrvect().  No provision is made for directly setting the
  828.    real-mode vector to an arbitrary routine.
  829.  
  830.    It is possible to set the real-mode handler to an arbitrary routine.  To
  831.    do so, you must write some code to convert the protected-mode address of
  832.    the  handler  to  a real-mode address.  Under Phar Lap, this is possible
  833.    using INT 21h, function 250Fh.  See the Phar Lap 386|DOS-Extender manual
  834.    for details.
  835.  
  836.    This is one of several functions (see the SEE ALSO section)  intended to
  837.    provide 80386/486 support similar to that provided by _dos_setvect() and
  838.    _dos_getvect() in the 80x86 16-bit library.
  839.  
  840.    Because protected-mode DOS  extenders handle interrupts differently from
  841.    real-mode DOS, _dos_setvect() and _dos_getvect() cannot be used in
  842.    protected mode.
  843.  
  844. RETURN VALUE
  845.  
  846.    The  function returns -1 if the operation fails.    If  successful,  the
  847.    function returns zero.
  848.  
  849. CAUTIONS
  850.  
  851.    If you install your own interrupt  handler,  be sure to save and restore
  852.    the previous handler.  If you  do  not restore the original handler, the
  853.    machine may exhibit unexpected behavior after the program exits.
  854.  
  855. SYSTEM DEPENDENCIES
  856.  
  857.    This function is not supported for  OS/386.   The function returns -1 if
  858.    it is called under OS/386.
  859.  
  860.    This  function detects the DOS extender  currently  installed  and  acts
  861.    accordingly.  You can determine which environment the program is running
  862.    in by testing  the value of the extern char variable _mwenv.  A value of
  863.    2 indicates Phar Lap's 386|DOS-Extender, 3 indicates Ergo's OS/386.
  864.  
  865. SEE ALSO
  866.  
  867.      _getpvect    To get the protected-mode vector.
  868.  
  869.      _getrvect    To get the real-mode vector.
  870.  
  871.      _setpvect    To set the protected-mode handler.
  872.  
  873.      _setrpvectp  To set both the protected- and real-mode vectors to point
  874.                   to a protected-mode handler.
  875.  
  876.    See the example provided for _setrpvectp.
  877.  
  878.  
  879. --------------------------------------------
  880. _strdate     Report the date as a string.
  881. --------------------------------------------
  882.  
  883. DOS Only
  884. Not Reentrant
  885.  
  886. SYNOPSIS
  887.  
  888.    #include <time.h>                                        /* Required. */
  889.    char *_strdate(char *sptr);
  890.  
  891. DESCRIPTION
  892.  
  893.    _strdate() obtains the current date, converts it to character format, and
  894.    places it in the string pointed to by sptr.  The date is formatted as
  895.    mm/dd/yy: mm is the month, dd is the day, and yy is the year.  Each part of
  896.    the date is two digits, and the string that sptr points to must be at least
  897.    nine bytes long.  The function places a terminating NUL character at the
  898.    end of the date string.
  899.  
  900. RETURN VALUE
  901.  
  902.    The function returns a pointer to the string.
  903.  
  904. SEE ALSO
  905.  
  906.    asctime, ctime, gmtime, localtime, mktime, time, _tzset
  907.  
  908. EXAMPLE
  909.  
  910.    #include <time.h>
  911.    #include <stdio.h>
  912.    void main() {
  913.       char a[15];
  914.  
  915.       _strdate(&a[0]);
  916.       puts("The date is --");
  917.       puts(a);
  918.       }
  919.  
  920.  
  921.    prints:
  922.  
  923.    The date is --
  924.    4/23/92
  925.  
  926.