digitalmars.com                      
Last update Sun Mar 4 12:00:58 2018

dos.h part 2

_bdos
_chain_intr
_disable
_enable
_FP_OFF, _FP_SEG
_getdcwd
_harderr, _hardresume, _hardretn
_inp, _inpw, _inpl
_intdos
_intdosx
_MK_FP
_osversion
_outp, _outpw, _outpl
_segread
allocmem
bdosptr
bdosx
farcalloc
farcoreleft
farfree
farmalloc
farrealloc
findfirst
findnext
freemem
geninterrupt
getcbrk
getcurdir
getdate
getdisk
getdta
getfat
getfatd
getpsp
gettime
getverify
parsfnm
peek
peekb
poke
pokeb
response_expand
setblock
setcbrk
setdisk
setdta
setverify

_bdos

Header
dos.h
Prototype
int _bdos(int dosfunc, unsigned DX, unsigned AL);
Description
_bdos invokes a DOS system call via interrupt 0x21, where dosfunc is the desired DOS system call. DX and AL are values to be loaded into the DX and AL registers prior to calling the specified DOS function. For DOS 0x21 functions that require loading registers other than DX and AL prior to call, use either _intdos or _intdosx.

Under the X and P memory models _bdos and bdosx carry out some filtering of parameters sent to the real mode interrupt. This enables MS-DOS functions running in real mode to access data stored in extended memory. Some DOS functions are partially or unsupported in the 32-bit memory models. See the _int86 function.

Do not use _bdos() to invoke system calls that indicate errors by setting the carry flag. C programs do not have access to this flag and cannot determine whether the return value is an error code.

Synonym
Function: bdos
Return Value
The value in the AX register, as set by the system call.
Compatibility
DOS, Windows 3.x, Phar Lap, DOSX
See Also
bdosptr bdosx _intdos _intdosx _int86 _int86x int86_real int86x_real
Example
/* Example of _bdos */

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

#define I21HDISPCHAR   0x02
#define I21HSETVERIFY  0x2e
#define I21HGETDOSVERS 0x30

/* This Example assumes sizeof(int) == 2 */

int lowbytes(int tomask)
{
 return (tomask & 0x00FF);
}

int highbytes(int toshift)
{
 return (toshift >> 8);
}

void main()
{
 int result;
 unsigned DX, AL;

 /* get DOS version number */

 result = _bdos(I21HGETDOSVERS, DX, AL);
 printf("Running DOS %d.%d\n", lowbytes(result), highbytes(result));

 /* Print a character on the screen */

 DX = 'Z';
 _bdos(I21HDISPCHAR, DX, AL);

 /* Turn DOS verify off */

 DX = 0x00;
 AL = 0x00;
 _bdos(I21HSETVERIFY, DX, AL);
 printf("\nDOS Verify disabled\n");

}
Output
Running DOS 6.20
Z
DOS Verify disabled

_chain_intr

Header
dos.h
Prototype
void _chain_intr(void(__cdecl __interrupt __far *target)());
Description
_chain_intr transfers control from one interrupt handler to another, specified by target, allowing the target handler to return as if it were called directly.

Use _chain_intr only with functions that have been declared with __interrupt, ensuring the procedure's entry and exit sequence is appropriate for an interrupt handler.

Return Value
Does not return to the caller.
Compatibility
DOS Windows 3.x Phar Lap DOSX
See Also
_dos_getvect _dos_setvect
Example
/* Example for _chain_intr
   Also demonstrates _dos_getvect,
   _dos_setvect, _spawn

   PROFILE.C

Shows how much time is being spent in each code
segment running on the machine. Produces a more
interesting result when not run in a Windows DOS
box.
*/

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

#define MAX_SEGS 128

static struct seg_profile {
   unsigned code_segment;
   unsigned number_of_hits;
} prof_table[MAX_SEGS];

static void (__interrupt __far *old_handler)();

static void __interrupt __far timer_handler (
   unsigned saved_es,
   unsigned saved_ds,
   unsigned saved_di,
   unsigned saved_si,
   unsigned saved_bp,
   unsigned saved_sp,
   unsigned saved_bx,
   unsigned saved_dx,
   unsigned saved_cx,
   unsigned saved_ax,
   unsigned saved_ip,
   unsigned saved_cs,
   unsigned saved_flags)
{
 struct seg_profile *p;

 for (p = prof_table; p < prof_table +
      MAX_SEGS; p += 1)

 {
    if (p->code_segment == saved_cs)
    {
      p->number_of_hits += 1;
      break;
    }
    if (p->code_segment == 0)
    {
       p->code_segment = saved_cs;
       p->number_of_hits += 1;
       break;
    }
 }
 _chain_intr (old_handler);
}
static void print_profile()
{
 struct seg_profile *p;

 printf("Code Segment Number of hits\n");
 for (p = prof_table; p < prof_table +
     MAX_SEGS; p += 1)
 {
    if (p->code_segment == 0)
       break;
    printf("%12x %14d\n", p->code_segment,
            p->number_of_hits);
 }
}
void main (int argc, char const *const argv[])
{
 if (argc < 2)
 {
    fprintf(stderr, "Usage: PROFILE executable-file arguments...\n");
    exit(EXIT_FAILURE);
 }
 old_handler = _dos_getvect(0x8);
 _dos_setvect(0x8, (void (__interrupt __far *)(void)) timer_handler);
 _spawnvp(_P_WAIT, argv[1], argv + 1);
 _dos_setvect(0x8, old_handler);
 print_profile();
}
Output
c:\dm\examples> profile edit profile.c
Code Segment Number of hits
ff6d 1
6f6e 1
c000 4
d28f 5
638f 721
e003 2

_disable

Header
dos.h
Prototype
void _disable(void);
Description
_disable disables interrupts by executing an 8086 CLI machine instruction. You should disable interrupts before modifying an interrupt vector.
Synonym
Function: disable
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_enable

_enable

Header
dos.h
Prototype
void _enable(void);
Description
Enables hardware interrupts by executing an 8086 STI machine instruction.
Synonym
Function: enable
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_disable

_FP

Header
dos.h
Prototype
unsigned _FP_OFF(void __far *fpointer);
unsigned _FP_SEG(void __far *fpointer);
Description
_FP_OFF and _FP_SEG split far pointers into their offset and segment parts. These functions are implemented as macros.
Return Value
_FP_SEG returns the 16-bit offset value of the far pointer. _FP_OFF returns the 16-bit segment value of the far pointer.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Synonym
Functions: FP_OFF and FP_SEG
See Also
_MK_FP
Example
/* Example for _FP_OFF
   Also demonstrates _FP_SEG
*/

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

char __far * farstr = "This is a test.";

void main()
{
 unsigned seg, off;
 seg = _FP_SEG(farstr);
 off = _FP_OFF(farstr);

 printf("Far string at segment %04X, and
        offset %04X\n", seg, off);
}
Output
Far string at segment 2305, and offset 0060

_getdcwd

Header
direct.h
Prototype
char *_getdcwd(int drive, char *buffer, int length);
Description
The _getdcwd function gets the name of the current working directory on the specified drive and stores the drive and path name in buffer. Argument length is the maximum length of the path name (including the terminating null character.) If the current directory is the root, the returned string will end with a backslash. Otherwise, the string ends with the directory name, not a backslash.

To specify a drive, 0 indicates the default drive, 1 indicates drive A, 2 indicates drive B, and so on. If buffer is specified as NULL, _getdcwd will malloc enough bytes to hold the path (including the terminating 0). At least length bytes will be allocated. To deallocate the buffer, use the free function.

Return Value
If successful, _getdcwd returns a pointer to buffer. A return value of NULL indicates an error and errno is set to ENOMEM (insufficient memory to allocate length bytes) or ERANGE (path name longer than length characters).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_getcwd
Example
/* Example for _getdcwd */

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

void main()
{
 char path[_MAX_DIR];

 _getdcwd(3, path, _MAX_DIR);
 printf("Current directory on drive C: is: %s", path);
}
Output
Current directory on drive C: is: c:\dm\examples

_hard

Header
dos.h
Prototype
void _harderr(void(__far *handler)(unsigned, unsigned, unsigned));
void _hardresume(int result);
void _hardretn(int error);
Description
The _harderr, _hardresume, and _hardretn functions handle critical error conditions occuring from hardware devices that cause a DOS interrupt 0x24.

The function specified as the handler in the _harderr call will be called when a critical interrupt occurs. The function might call either of the following functions:

  • _hardresume, which returns to DOS with a result of abort, retry, ignore, or fail.
  • _hardretn, which skips DOS and returns directly to the routine that originally made the DOS call.
The _harderr function calls the user-defined routine, referenced by handler, using the following parameters:

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

Argument deverror, the device error code, contains the value of register variable AX that DOS passes to the interrupt 0x24 handler. If bit 15 is zero, indicating a disk device error, the bits have the following meaning:

Bits Value = Meaning
15 0 = disk device error
13 0 = "ignore" response is not allowed
12 0 = "retry" iesponse is not allowed
11 0 = "fail" response is not allowed. "fail" will be changed to "abort"
9 and 10 00 = error occured in DOS
01 = error occured in file allocation table
10 = error occured in a directory
11 = error occured in a data area
8 0 = read error
1 = write error
Low-order byte 0 = drive A
1 = drive B
2 = drive C
etc.
For errors on devices other than disk drives, bit 15 of the deverror argument is set to 1. The type of device that had the error is indicated by the attribute word, located at offset 4 in the device header block (which is pointed to by devhdr):

Bit in attribute word Meaning
15 0 = error in memory image of file allocation table
1 = error in character device. Bits 0-3 specify which device.
3 Current clock device
2 current null device
1 Current standard output
0 Current standard input
Argument errcode contains the value of register variable DI that DOS passes to the handler. The error code's low-order byte can be:

Code Meaning
0 Attempt to write to write-protected disk
1 Unknown unit
2 Drive not ready
3 Unknown command
4 Cyclic-redundancy-check error in data
5 Bad drive-request structure length
6 Seek error
7 Unknown media type
8 Sector not found
9 Printer out of paper
10 Write fault
11 Read fault
12 General failure
Argument devhdr is a far pointer to a device header. It describes the device that has the error. The user-defined handler must not change this information.

Function _hardresume must be called with one of these results:

Constant Action
_HARDERR_ABORT Aborts the program
_HARDERR_FAIL Fails the system call in progress
_HARDERR_IGNORE Ignores the error
_HARDERR_RETRY Retries the operation
The _hardretn function returns directly to the application program just after the failing I/O function request according to these criteria:

If failing interrupt 0x21 is: Then...
Greater than or equal to 0x38 the _hardretn function returns to the application with the carry flag set and the AX register set to the error parameter.
Less than 0x38 and the function can return an error the AL register is set to 0xFF on return to the application.
Less than 0x38 but cannot return an error the error parameter is not used and no error code is returned to the application.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for _harderr
   Also demonstrates _dos_creat
*/

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

static unsigned the_deverror, the_errcode, __far
*the_devhdr;

static void __far my_handler(
       unsigned deverror,
       unsigned errcode,
       unsigned  __far *devhdr)
{
 the_deverror = deverror;
 the_errcode = errcode;
 the_devhdr = devhdr;
 _hardresume(_HARDERR_FAIL);
}

void main()
{
 int handle;

 printf("Please be sure no disk is in
         the A drive.\n"
        "Press a key to continue:\n");
 getch();
 _harderr(my_handler);
 the_deverror = -1;
 the_errcode = -1;
 the_devhdr = NULL;
 if (_dos_creat("a: anything", _A_NORMAL,
      &handle) != 0)
    printf("create failed, error code was %d\n",
       the_errcode);
}
Output
Please be sure no disk is in the A drive.
Press a key to continue:
create failed, error code was 2

_inp

Header
dos.h
Prototype
int _inp(unsigned port_address);
int _inpw(unsigned port_address);
int _inpl(unsigned port_address);
Description
This is a C interface to the hardware ports using the IN 80x86 I/O instructions. _inp reads a byte from the specified port, and _inpw reads a word from the specified port. The compiler generates inline code for them. The real library functions can be called with #undef inpw and #undef inp in the source file after including .
Synonym
Functions: inp, inpw
Return Value
The value read from the port is returned.
Compatibility
DOS, Windows 3.x, Phar Lap, DOSX, Win32
See Also
_outp
Example
The following two examples turn off and turn on the MDA cursor 
/* Example for _inp
   Turns off the MDA cursor.
 */

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

void main()
{
 char result;
 result = _inpw(0x3b4);
 printf("The value from port 3B4h is %xh\n",
        result);
 _outp(0x3b4, 10);
 _outp(0x3b5, 32);
}

/* Turns on the MDA cursor
*/
#include <dos.h>
#include <stdlib.h>

void main()
{
 _outp(0x3b4, 10);
 _outp(0x3b5, 11);
}

_intdos

Header
dos.h
Prototype
int _intdos(union _REGS *regsin, union _REGS *regsout);
Description
The _intdos and intdos functions perform a MS-DOS system call (int 0x21). Consult an MS-DOS manual for specific function and calling conventions. regsin is a pointer to a structure containing the values of the registers AX, BX, CX, DX, SI and DI to be passed to the interrupt. regsout is a pointer to a structure into which the return values of the registers will be written. The state of the carry flag can be determined from x.cflag in regsout. The union _REGS is defined in dos.h.

Under the 32-bit memory models intdos and indosx carry out some filtering of parameters sent to the real mode interrupt. This enables MS-DOS functions running in real mode to access data stored in extended memory. Some of the available DOS functions are not supported or only partially supported in the 32-bit memory models. Refer to the entry for int86 for more information.

Synonym
Function: intdos
Return Value
The value that was in AX at the end of the interrupt. For _intdos, if an error occurs, the cflag field in regsout is non-zero and _doserrno is set to the corresponding error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_int86 int86_real _int86x int86x_real _intdosx
Example
See intdosx

_intdosx

Header
dos.h
Prototype
int _intdosx(union _REGS *regsin, union _REGS *regsout, struct _SREGS *segregs);
Description
The _intdosx function performs an MS-DOS system call (int 0x21). Consult a DOS manual for specific function and calling conventions. regsin is a pointer to a structure containing values of the registers AX, BX, CX, DX, SI and DI to be passed to the interrupt. regsout is a pointer to a structure into which return values of the registers will be written. The state of the carry flag can be determined from x.cflag in regsout. The segregs structure contains segment register values passed to the interrupt for intdosx. It also returns their values after the interrupt is processed. Union _REGS and structure _SREGS are defined in dos.h. See int86 for an explanation of function filtering under the 32-bit memory models.
Synonym
Function: intdosx
Return Value
The value that was in AX at the end of the interrupt. If an error occurs, the cflag field in regsout is non-zero and _doserrno is set to the corresponding error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_int86 int86_real _int86x int86_real

_MK_FP

Header
dos.h
Prototype
void __far *_MK_FP(unsigned seg, unsigned off);
Description
Converts the unsigned segment and offset values to a far pointer.
Synonym
Function: MK_FP
Return Value
Returns a far pointer.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_FP Functions
Example
/* Example of _MK_FP */

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

void main()
{
 char far *p;
 unsigned int segment = 0xb800;
 unsigned int offset = 0;

 p = _MK_FP(segment, offset);
 printf("The CGA video buffer is at %lp\n", p);
}
Output
The CGA video buffer is at B800:0000

_osversion

Header
dos.h
Prototype
extern unsigned int _osversion;
Description
This variable holds both the major and minor version numbers of the operating system. The low byte holds the major version number; the high byte holds the minor version number. This is the reverse of _osver.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32

_outp

Header
dos.h
Prototype
unsigned char _outp(unsigned port_address, unsigned char value);
unsigned short _outpw(unsigned port_address, unsigned short value);
unsigned long _outpl(unsigned port_address, unsigned long value);
Description
These functions write to the hardware I/O ports using the OUT 80x86 instruction.
Synonym
Functions: outp, outpw
Return Value
The value that is sent to the I/O port.
Compatibility
DOS, Windows 3.x, Phar Lap, DOSX
See Also
_inp
Example
See _inp.

_segread

Header
dos.h
Prototype
void _segread(struct _SREGS *segregs);
Description
The _segread function reads the contents of the segment register and puts them in _SREGS. In the 32-bit memory models, this function returns protected mode segment selectors, not real mode segment values. The elements in structure _SREGS are:
Element Meaning
unsigned short cs; Code segment
unsigned short ds; Data segment
unsigned short es; Extra segment
unsigned short ss; Stack segment
unsigned short fs; 32-bit platform only
unsigned short gs; 32-bit platform only
Synonym
Function: segread
Structure: SREGS
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_intdosx _int86x int86x_real getDS
Example
/* Example of _segread */

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

void main()
{
 struct _SREGS sregs;
 unsigned cs, ss, ds, es;

 _segread (&sregs);
 cs = sregs.cs;
 ss = sregs.ss;
 ds = sregs.ds;
 es = sregs.es;
 printf("Segment registers currently contain:\n");
 printf("CS: %04x\nSS: %04x\nDS: %04x\nES: %04x\n",
    cs, ss, ds, es);
}
Output
Segment registers currently contain:
CS: 1f04
SS: 2055
DS: 2055
ES: 1eda

allocmem

Header
dos.h
Prototype
int allocmem(unsigned size, unsigned *segp);
Description
Allocates a DOS memory segment, using the DOS system call 0x48. The allocated memory block has the number of paragraphs specified in the size argument. (There are 16 bytes in a paragraph.) The segp argument points to the word that contains the segment address of the allocated memory block.

Do not use allocmem and malloc functions in the same program.

Return Value
Returns -1 if the memory is successfully allocated. If unsuccessful, the number of paragraphs available in the largest memory block is returned. In addition, the global variable _doserrno is set and the global variable errno is set to ENOMEM, for not enough memory.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_allocmem freemem
Example
/* Example for allocmem Also demonstrates _MK_FP
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>
void main()
{
 int largest;
 unsigned segment, size;
 char __far *pointer;

 size = 0xffff;
 largest = allocmem(size, &segment);
 if (largest != -1)
 {
    printf("The largest available block is %u bytes\n",
           largest);
    size = largest / 2;
    largest = allocmem(size, &segment);
    if (largest != -1)
    {
      fprintf(stderr,
              "Error allocating %u bytes\n",
              size);
      exit(EXIT_FAILURE);
    }
 }
 pointer = _MK_FP(segment, 0);
 printf("The beginning of the %u bytes is at %Fp\n",
        size, pointer);
}
Output
The largest available block is 28675 bytes
The beginning of the 14337 bytes is at 34FD:0000

bdosptr

Header
dos.h
Prototype
int bdosptr(int dosfun, void *argument, unsigned dosal);
Description
The bdosptr function invokes the DOS system call specified in the dosfun argument. In small data models, argument specifies the DX register; in large data models, argument specifies the DS: DX values to be used by the system call. The dosal argument specifies the value of the AL register.

For system calls that require a pointer argument, use the bdosptr function. Otherwise, use bdos.

Return Value
The value of the AX register, as set by the system call. If unsuccessful, -1 is returned and the global variables errno and _doserrno are set appropriately.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_bdos bdosx _intdos _intdosx _int86 int86_real
Example
See _bdos

bdosx

Header
dos.h
Prototype
int bdosx(char int21func, void* DS_DX, char AL);
Description
bdosx is used to invoke DOS system calls that require a pointer argument. The bdosx function calls the specified DOS function int21func, placing the pointer argument DS_DX in the DS:DX register pair, and the argument AL in register AL. The DS_DX argument is a standard near or far pointer, depending on memory model, and must match the default pointer type for that model. For system calls that require only an integer value in DX, use the function bdos.

Under the 32-bit memory models bdos and bdosx carry out some filtering of parameters sent to the real mode interrupt. This filtering allows data stored in extended memory to be passed to the DOS function so that, for instance, much larger buffers than normal can be used with the DOS disk functions. Where pointers are passed to bdosx, they are assumed to contain protected mode addresses. The filtering routine used for these functions assumes that all far pointers passed in registers to DOS have a segment address of DGROUP. If you use bdosx and specify a selector other that DGROUP the results will be unpredictable.

Some of the available DOS functions are not supported or only partially supported in the 32-bit memory models. Refer to the entry for int86 for more information.

Return Value
The value in AX after the system call.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_bdos bdosptr _intdos _intdosx _int86 int86_real _int86x int86x_real other dos_functions
Example
See _bdos

farcalloc

Header
dos.h
Prototype
void __far *farcalloc(unsigned long numelems, unsigned long size);
Description
farcalloc allocates memory from the far heap for an array containing numelems elements, each size bytes long. This function is very similar to calloc because it initializes a new memory block to NULL. In the small and medium memory models, calloc allocates memory within the near heap whereas farcalloc allocates memory in the far heap. In the large memory model, both functions allocate memory from the far heap. This function is not implemented for the 32-bit memory models.
Return Value
farcalloc returns a far pointer to the allocated memory block, or NULL if not enough space exists.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
calloc farcoreleft farfree farmalloc farcalloc free malloc realloc _FP Functions

farcoreleft

Header
dos.h
Prototype
unsigned long farcoreleft(void);
Description
farcoreleft returns the size of largest contiguous block of unused memory in the operating system's heap. This function is not implemented for the 32-bit memory models.
Return Value
Returns the size of the largest contiguous block of memory in the far heap which has not been used, between the highest allocated block and the end of memory. This is the amount of memory still available for allocation by farmalloc or farcalloc.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
calloc farfree farmalloc farcalloc farrealloc free malloc realloc _FP Functions

farfree

Header
dos.h
Prototype
int farfree(void __far *memblock);
Description
farfree releases a block of previously allocated far memory pointed to by the far pointer memblock. The memblock argument must point to a memory block previously allocated by farcalloc, farmalloc, or farrealloc. This function is not implemented for the 32-bit memory models.
Return Value
An integer
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
calloc farcoreleft farfree farmalloc farcalloc farrealloc free malloc realloc _FP Functions

farmalloc

Header
dos.h
Prototype
void __far *farmalloc(unsigned long sizebytes);
Description
farmalloc allocates a memory block sizebytes long from the far heap. This function is not implemented for the 32-bit memory models.
Return Value
farmalloc returns a far pointer to the allocated memory block, or NULL if not enough space exists.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
calloc farcoreleft farfree farmalloc farcalloc farrealloc free malloc realloc _FP Functions

farrealloc

Header
dos.h
Prototype
void __far *farrealloc(void __far *memblock, unsigned long newsize);
Description
farrealloc adjusts the size of a previously allocated memblock to newsize. This function is not implemented for the 32-bit memory models.
Return Value
farrealloc returns the address of the reallocated memory block. This may be different from the original memory block.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
calloc farcoreleft farfree farmalloc farcalloc free malloc realloc _FP Functions

findfirst

Header
dos.h
Prototype
struct FIND *findfirst(const char *pathname, int attribute);
Description
The findfirst function finds the first file matching a file description possibly containing wild cards (i.e. '*' or '?'). The wild cards can be in the file name or extension, but not the path. The attribute argument is the file attribute of the file to be found. More than one attribute bit can be passed in the findfirst call. The attribute values, defined in dos.h, are:

_A_RDONLY Read only
_A_HIDDEN Hidden file
_A_SYSTEM System file
_A_VOLID Label
_A_SUBDIR Directory
_A_ARCH Archive
A value of 0 for the attribute finds all normal files. If a program specifies any combination of _A_HIDDEN, _A_SYSTEM, _A_SUBDIR, the function returns normal files in addition to the specified files. The program must examine the attribute to determine the type of file found.
Return Value
A pointer to a static structure FIND as defined in dos.h. A NULL pointer indicates the end of filename matches or an error (such as no matching files). The FIND structure has exactly the same fields as the find_t structure used by _dos_findfirst.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
findnext

findnext

Header
dos.h
Prototype
struct FIND *findnext(void);
Description
The findnext function is used to find the next match of the file specified in the preceding findfirst call. findnext can be called only after a findfirst call.
Return Value
A pointer to a static struct FIND as defined in dos.h is returned on success. Because this structure is static, you must copy the information to another buffer if you need the information after a call to findnext. A NULL pointer indicates the end of filename matches or an error.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
findfirst
Example
/* Example for findnext
   Also demonstrates findfirst, printf

   FILES.C
*/

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

void main(int argc, char *argv[])
{
 struct FIND *entry;
 char *path;
 struct time_format
 {
    unsigned two_seconds: 5;
    unsigned minutes: 6;
    unsigned hours: 5;
 } time;
 struct date_format
 {
    unsigned day: 5;
    unsigned month: 4;
    unsigned year: 7;
 } date;
 if (argc < 2)
    path = "*.*";
 else
    path = argv[1];
 entry = findfirst (path,
    _A_RDONLY | _A_HIDDEN | _A_SYSTEM |
    _A_VOLID | _A_SUBDIR | _A_ARCH);
 while (entry != NULL)
 {
    time = *(struct time_format *)&entry->time;
    date = *(struct date_format *)&entry->date;
    printf("%-13s %10lu %02d-%02d-%02d %02d:
     %02d.%02d %c%c%c%c%c%c\n",
     entry->name, entry->size,
     date.month, date.day, date.year + 80,
     time.hours, time.minutes,
     time.two_seconds << 1,
     entry->attribute & _A_RDONLY? 'r': ' ',
     entry->attribute & _A_HIDDEN? 'h': ' ',
     entry->attribute & _A_SYSTEM? 's': ' ',
     entry->attribute & _A_VOLID? 'v': ' ',
     entry->attribute & _A_SUBDIR? 'd': ' ',
     entry->attribute & _A_ARCH? 'a': ' ');
    entry = findnext();
 }
}
Output
c:\dm\examples>files \*.*
IO.SYS           40566 09-30-93 06:20.00 rhs
MSDOS.SYS        38138 09-30-93 06:20.00 rhs
MS-DOS_6             0 03-03-94 11:54.14    v a
DOS                  0 03-03-94 11:54.14     d
WINDOWS              0 03-03-94 12:05.32     d
NET                  0 03-15-94 11:49.04     d
SC                   0 06-21-94 10:07.34     d
DIGIMARS             0 03-22-94 17:01.32     d
NDW                  0 03-22-94 17:14.18     d
DOC                  0 04-04-94 10:49.00     d
COMMAND.COM      54619 09-30-93 06:20.00 r
DBLSPACE.BIN     64246 09-30-93 06:20.00 rhs
WINA20.386        9349 09-30-93 06:20.00      a
AUTOEXEC.BAT       437 06-21-94 14:39.58      a
386SPART.PAR  60809216 06-28-94 08:58.36  hs  a
CONFIG.SYS         209 05-24-94 10:44.32      a

freemem

Header
dos.h
Prototype
int freemem(unsigned segx);
Description
The freemem function frees the DOS memory block associated with the segment address in the segx argument. This address was returned by a previous call to the allocmem function.
Return Value
If successful, a zero is returned. If unsuccessful, -1 is returned and errno is set to ENOMEM (insufficient memory).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
allocmem free _dos_allocmem _dos_freemem

geninterrupt

Header
dos.h
Prototype
void geninterrupt(int intr_num);
Description
The geninterrupt function generates the software interrupt specified in the intr_num argument.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_disable _enable

getcbrk

Header
dos.h
Prototype
int getcbrk(void);
Description
The getcbrk function invokes the DOS system call 0x33, which gets the current setting for control-break checking.
Return Value
The value of the control-break setting (0 for off, 1 for on).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
ctrlbrk setcbrk
Example
/* Example for getcbrk */

#include <stdio.h>
#include <dos.h>

void main()
{
 printf("Control-break is %s\n",
   getcbrk() ? "on" : "off");
}
Output
Control-break is on

getcurdir

Header
direct.h
Prototype
int getcurdir(int drive, char *dir)
Description
The getcurdir function gets the current working directory for the drive specified in the drive argument. To specify the drive argument, use an integer value, where 0 represents the current drive, 1 represents drive A, 2 represents drive B, and so on. The dir argument points to a buffer where the name will be placed. The directory name is not stored with the drive specification and does not begin with a backslash.
Return Value
Returns 0 if successful, otherwise returns -1.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_chdir _mkdir _rmdir _getcwd
Example
/* Example for getcurdir
   CWD.C */

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

void main(int argc, char *argv[])
{
 char *path;
 int drive;

 if (argc < 2)
    drive = 0;
 else
 {
    drive = toupper(* argv[1]) -'A' + 1;
    if (drive <= 0 || drive > 26)
    {
       fprintf(stderr,
	  "Usage: CWD [drive-letter]\n");
       exit(EXIT_FAILURE);
    }
 }
 if (getcurdir(drive, path) != 0)
 {
    fprintf(stderr,
	"Error accessing current directory\n");
    exit(EXIT_FAILURE);
 }
 printf("\\%s\n", path);
}
Output
c:\dm\examples> cwd n
\#\RELEASE\SRC

getdate

Header
dos.h
Prototype
void getdate(struct date *datep);
Description
The getdate function obtains the current system date and places it in the structure pointed to by the datep argument. The date structure is: 
struct date
{
 int da_year; /* year            */
 char da_day; /* day of the month */
 char da_mon; /* month, 1 for Jan */
};
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
setdate
Example
/* Example for getdate */

#include <dos.h>
#include <stdio.h>

void main()
{
 struct date the_date;
 char *holiday;

 getdate(&the_date);
 printf("The date is %d-%d-%d",
        the_date.da_mon,
        the_date.da_day,
        the_date.da_year);
 holiday = NULL;
 if (the_date.da_mon == 12 &&
           the_date.da_day == 25)
    holiday = "Christmas day";
 else if (the_date.da_mon == 10 &&
          the_date.da_day == 31)
    holiday = "Halloween";
 else if (the_date.da_mon == 7 &&
          the_date.da_day == 4)
    holiday = "Independence Day";
 else if (the_date.da_mon == 6 &&
          the_date.da_day == 28)
    holiday = "The anniversary of the writing of this program";
 if (holiday != NULL)
    printf(": %s", holiday);
 printf("\n");
}
Output
The date is 6-28-1994: The anniversary of the writing of this program

getdisk

Header
dos.h
Prototype
int getdisk(void);
Description
The getdisk function calls DOS function 0x19 to return the current drive number. 0 represents drive A, 1 represents drive B, and so on.
Return Value
The current drive number.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_getdrive
Example
/* Example for getdisk */

#include <stdio.h>
#include <dos.h>

void main()
{
 printf("The current disk drive is %c\n",
        getdisk() + 'A');
}
Output
The current disk drive is C

getdta

Header
dos.h
Prototype
char __far *getdta(void);
Description
The getdta function returns the disk transfer address.
Return Value
A far pointer to the current disk transfer address.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
setdta
Example
/* Example for getdta */

#include <stdio.h>
#include <dos.h>

void main()
{
 printf("The current disk transfer address is %Fp\n",
    getdta());
}
Output
The current disk transfer address is 1DD8:0080

getfat

Header
dos.h
Prototype
void getfat(unsigned char drive, struct fatinfo *dtable);
Description
The getfat function obtains the file allocation table information for the drive specified in the drive argument. 0 represents the default drive, 1 represents drive A, 2 represents drive B, and so on.

The file allocation table information is placed in the structure pointed to by the dtable argument. This structure is of type fatinfo, which is defined as follows:

struct fatinfo
{
  char fi_sclus;    /* sectors per cluster */
  char fi_fatid;    /* the FAT id number */
  unsigned fi_nclus;/* number of clusters */
  int fi_bysec;     /* bytes per sector */
};
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getfatd
Example
/* Example for getfat

   GETFAT.C
*/
#include <stdio.h>
#include <dos.h>
#include <stdlib.h>

void main(int argc, char *argv[])
{
 struct fatinfo fat;
 int drive;

 if (argc < 2)
    drive = 0;
 else
 {
    drive = toupper(*argv[1]) - 'A' + 1;
    if (drive <= 0 || drive > 26)
    {
       fprintf(stderr, "Usage: GETFAT [drive-letter]\n");
       exit(EXIT_FAILURE);
    }
 }
 getfat (drive, &fat);
 printf("number of clusters: %u\n",
        fat.fi_nclus);
 printf("sectors per cluster: %d\n",
        fat. fi_sclus);
 printf("bytes per sector: %d\n",
        fat.fi_bysec);
 printf("FAT id number: %X\n",
        (unsigned char) fat.fi_fatid);
}
Output
c:\dm\examples> getfat a
number of clusters: 2847
sectors per cluster: 1
bytes per sector: 512
FAT id number: F0

c:\dm\examples> getfat
number of clusters: 65371
sectors per cluster: 16
bytes per sector: 512
FAT id number: 74

getfatd

Header
dos.h
Prototype
void getfatd(struct fatinfo *dtable);
Description
The getfatd function obtains the file allocation table information for the default drive. This information is placed in the structure pointed to by the dtable argument.

Example
The dtable structure is of type fatinfo, which is defined as: 
struct fatinfo
{
 char fi_sclus;     /* sectors per cluster */
 char fi_fatid;     /* the FAT id number   */
 unsigned fi_nclus; /* number of clusters  */
 int fi_bysec;      /* bytes per sector    */
};
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getfat

getpsp

Header
dos.h
Prototype
unsigned getpsp(void);
Description
The getpsp function uses DOS system call 0x62 to return the segment address of the program segment prefix.
Return Value
The program segment prefix.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getenv _getpid
Example
/* Example for getpsp */

#include <stdio.h>
#include <dos.h>

void main()
{
 printf("This program's psp is %X\n",
        getpsp());
}
Output
c:\dm\examples> getpsp
This program's psp is 1DD8

c:\dm\examples> command /c getpsp
This program's psp is 1EAC

gettime

Header
dos.h
Prototype
void gettime(struct time *timep);
Description
The gettime function copies the current system time into the structure pointed to by the timep argument. This structure is of type time, which has the following format:
struct time
{
  unsigned char ti_min;   /* minutes */
  unsigned char ti_hour;  /* hours */
  unsigned char ti_hund;  /* hundredths of a second */
  unsigned char ti_sec;   /* seconds */
};
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getftime
Example
See settime

getverify

Header
dos.h
Prototype
int getverify(void);
Description
The getverify function returns the current status of the DOS verify flag. A verify flag of 0 means verification is off, writing is not verified. A verify flag of 1 means verification is on, writing is verified.
Return Value
The status of the verify flag (0 or 1).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
setverify
Example
/* Example for getverify */

#include <stdio.h>
#include <dos.h>

void main()
{
 printf("DOS verify is %s\n",
    getverify()? "on": "off");
}
Output
DOS verify is off

parsfnm

Header
dos.h
Prototype
char *parsfnm(const char *cmdline, struct fcb *fcb, int opt);
Description
The parsfnm function locates a filename by parsing argument cmdline. The file control block for the associated file is stored in the structure pointed to by argument fcb. Argument opt is the AL value for DOS parse system call 29h. The format of structure fcb is: 
struct fcb
{
 char fcb_drive;/* 0= default, 1= A, etc */
 char fcb_name[8];/* File name */
 char fcb_ext[3];/* File extension */
 short fcb_curblk;/* Current block number */
 short fcb_filesize;/* File size in bytes */
 short fcb_date;/* Date last written */
 char fcb_resv[10];/* Reserved for DOS */
 char fcb_crrec;/* Current record in block */
 long fcb_random;/* Random record number */
};
The pointer to the next byte of the command line, after the end of the filename. Null is returned when unsuccessful.
Return Value
The pointer to the next byte of the command line, after the end of the filename. Null is returned when unsuccessful.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
fnmerge fnsplit full_fullpathpath searchpath
Example
/* Example for parsfnm */

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

void main()
{
 char line[80];
 struct fcb block;

 printf("Enter a filename: ");
 gets(line);
 if (parsfnm(line, &block, 1) == NULL)
 {
  perror("parsfnm failed");
  exit(EXIT_FAILURE);
 }
 else
   printf("Drive: %d, name: \"%.8s\",
           extension \"%.3s\"\n",
           block.fcb_drive,
           block.fcb_name,
           block.fcb_ext);
}
Output
Enter a filename: c:parsfnm.c
Drive: 3, name: "PARSFNM", extension "C"

peek

Header
dos.h
Prototype
int peek(unsigned seg, unsigned offset);
Description
Returns the integer value located at the given seg: offset address.
Return Value
The value at the given seg: offset address.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
poke peekb
Example
/* Example for peek
   Also demonstrates peekb, poke, pokeb
*/

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

#define KBCTRLBYTEADDR 0x417
#define NUMLOCKBIT 0x20

void syntax()
{
 printf("Usage: NUMLOCK <+|->\n");
 exit(EXIT_FAILURE);
}

void main(int argc, char *argv[])
{
 char state;

 if (argc <> 2)
    syntax();

 if (argv[1][0] == '+ ')
 {
    state = peekb(0, KBCTRLBYTEADDR);
    state |= NUMLOCKBIT;
    pokeb(0, KBCTRLBYTEADDR, state);
 }
 else if (argv[1][0] == '-')
 {
    state = peekb(0, KBCTRLBYTEADDR);
    state &= ~NUMLOCKBIT;
    pokeb(0, KBCTRLBYTEADDR, state);
 }
 else
    syntax();
}

peekb

Header
dos.h
Prototype
char peekb(unsigned segment, unsigned offset);
Description
The peekb function returns the byte at the memory location specified by the segment and offset arguments.
Return Value
The specified byte.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
peek pokeb
Example
See peek

poke

Header
dos.h
Prototype
void poke(unsigned seg, unsigned offset);
Description
Copies the int value to the given seg: offset address.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
peek pokeb
Example
See peek

pokeb

Header
dos.h
Prototype
void pokeb(unsigned segment, unsigned offset, char value);
Description
The pokeb function copies the byte in the value argument to the location specified by the segment and offset arguments.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
peekb poke
Example
See peek

response_expand

Header
dos.h
Prototype
int __pascal response_expand(int *argc, char *** argv);
Description
The response_expand function expands an argument list read from a response file. The response file must be passed in the form @filename. Any existing command line arguments are preserved. Response files can be nested. response_expand will also expand command line arguments based on environment variables rather than response file names.
Return Value
0 if successful, otherwise non-zero, in which case argc and argv are unchanged.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for _response_expand */

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

void main(int argc, char *argv[])
{
 int i;

 response_expand(&argc, &argv);
 printf("There are %d command line
        parameters\n", argc -1);

 for (i = 1; i < argc; i++)
 {
   puts(argv[i]);
 }
}
Output
c:\dm\examples> redumpar 1 2 3 @in 4 5 6
There are 12 command line parameters
1
2
3
One
Two
Three
Four
Five
Six
4
5
6

setblock

Header
dos.h
Prototype
int setblock(unsigned segx, unsigned newsize);
Description
The setblock function changes the size of the memory block specified in the segx argument to be the size, in paragraphs, specified in the newsize argument. The segx argument contains a value returned by a previous call to allocmem.
Return Value
If successful, -1 is returned. Otherwise, the size of the largest possible block, in paragraphs, is returned and errno and _doserrno are set.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
allocmem
Example
/* Example for setblock */

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

void main()
{
 unsigned int size, segp;
 int stat;

 size = 1024; /* This is is paragraphs,
                 1024 * 16 = 16384 */
 stat = allocmem (size, &segp);
 if (stat != -1)
 {
    printf("Unable to allocate memory\n");
    exit(EXIT_FAILURE);
 }
 printf("Allocated 16384 bytes with
	 allocmem() at segment %04X\n",
        segp);

 stat = setblock(segp, size / 2);
 if (stat != -1)
 {
    printf("Unable to reallocate memory,
           maximum size is %d\n",
           stat);
    exit(EXIT_FAILURE);
 }
 printf("Shrunk the memory block at segment %04X\n",
        segp);
 freemem(segp);
}
Output
Allocated 16384 bytes with allocmem() at
segment 33F2
Shrunk the memory block at segment 33F2

setcbrk

Header
dos.h
Prototype
int setcbrk(int cbrkvalue);
Description
The setcbrk function uses DOS system call 0x33 to set the control-break setting to the value specified in the cbrkvalue argument. A value of 0 limits checking to device communications such as console I/O and printer I/O. A value of 1 checks at every system call.
Return Value
The value of the cbrkvalue argument.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getcbrk
Example
/* Example for setcbrk */

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

void syntax()
{
 printf("Usage: setcbrk <+|->\n");
 exit(EXIT_FAILURE);
}
void main(int argc, char *argv[])
{
 char state;

 if (argc != 2)
    syntax();

 if (argv[1][0] == '+ ')
 {
    setcbrk(1);
 }
 else if (argv[1][0] == '-')
 {
    setcbrk(0);
 }
 else
    syntax();
}
Output
c:\dm\examples> setcbrk +

c:\dm\examples> break
BREAK is on

c:\dm\examples> setcbrk -C:\

SC\EXAMPLES> break
BREAK is off

setdisk

Header
direct.h
Prototype
int setdisk(int drive);
Description
The setdisk function sets the current drive to the one specified in the drive argument. 0 indicates drive A, 1 indicates drive B, and so on.
Return Value
The number of drives available.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getdisk
Example
See getdisk

setdta

Header
dos.h
Prototype
void setdta(char far *dta);
Description
The setdta function sets the disk transfer address to the value specified in the dta argument.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getdta

setverify

Header
dos.h
Prototype
void setverify(int value);
Description
The setverify function sets the verify flag to the value specified in the value argument. A value of 0 indicates that the verify flag is off and writes to disk are not verified. A value of 1 indicates that the verify flag is on and all writes to disk are verified.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getverify
Example
/* Example for setverify */

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

void syntax()
{
 printf("Usage: setver <+|->\n");
 exit(EXIT_FAILURE);
}

void main(int argc, char *argv[])
{
 char state;

 if (argc != 2)
    syntax();

 if (argv[1][0] == '+ ')
 {
    setverify(1);
 }
 else if (argv[1][0] == '-')
 {
    setverify(0);
 }
 else
    syntax();
}
Output
C:\DM\EXAMPLES> setver +

C:\DM\EXAMPLES> verify VERIFY is on

C:\DM\EXAMPLES> setver -

C:\DM\EXAMPLES> verify VERIFY is off
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums