Runtime Library
Reference
· Constants
· Data types
Standard C
· assert.h
· complex.h
· ctype.h
· fenv.h
· float.h
· locale.h
· math.h
· setjmp.h
· signal.h
· stdarg.h
· stddef.h
· stdio.h
· stdlib.h
· string.h
· time.h
Standard C++
· IOstream
· new
Win32
· gc.h
DOS, DOS32, Win16
· bios.h
· cerror.h
· disp.h
· dos.h
· dos.h part 2
· emm.h
· handle.h
· int.h
· msmouse.h
· sound.h
· swap.h
· tsr.h
· winio.h
Other C
· bitops.h
· conio.h
· controlc.h
· direct.h
· fltpnt.h
· io.h
· page.h
· process.h
· search.h
· sys\stat.h
· tabsize.h
· trace.h
· utime.h
· unmangle.h
· util.h
Other C++
· regexp.h
· class complex
|
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
- 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
- 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:\SC\EXAMPLES> profile edit profile.c
- Code Segment
- Number of hits
- ff6d
- 1
- 6f6e
- 1
- c000
- 4
- d28f
- 5
- 638f
- 721
- e003
- 2
- 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
- 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
- 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
- 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:\SC\EXAMPLES
- 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
- 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);
}
- 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
- 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
- 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, 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
- 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
- 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.
- 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
- 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
- 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
- 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
- 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 Functions
farcoreleft
farfree
farmalloc
farcalloc
free Functions
malloc Functions
realloc Functions
_FP Functions
- 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 Functions
farfree
farmalloc
farcalloc
farrealloc
free Functions
malloc Functions
realloc Functions
_FP Functions
- 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 Functions
farcoreleft
farfree
farmalloc
farcalloc
farrealloc
free Functions
malloc Functions
realloc Functions
_FP Functions
- 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 Functions
farcoreleft
farfree
farmalloc
farcalloc
farrealloc
free Functions
malloc Functions
realloc Functions
_FP Functions
- 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 Functions
farcoreleft
farfree
farmalloc
farcalloc
free Functions
malloc Functions
realloc Functions
_FP Functions
- 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
- 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:\SC\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
- 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 Functions
_dos_allocmem
_dos_freemem
- 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
- 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
- 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:\SC\EXAMPLES> cwd n
\#\RELEASE\SRC
- 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
- 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
- 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
- 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:\SC\EXAMPLES> getfat a
number of clusters: 2847
sectors per cluster: 1
bytes per sector: 512
FAT id number: F0
C:\SC\EXAMPLES> getfat
number of clusters: 65371
sectors per cluster: 16
bytes per sector: 512
FAT id number: 74
- 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
- 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:\SC\EXAMPLES> getpsp
This program's psp is 1DD8
C:\SC\EXAMPLES> command /c getpsp
This program's psp is 1EAC
- 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
- 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
- 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 "
- 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();
}
- 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
- 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
- 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
- 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:\SC\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
- 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
- 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:\SC\EXAMPLES> setcbrk +
C:\SC\EXAMPLES> break
BREAK is on
C:\SC\EXAMPLES> setcbrk -C:\
SC\EXAMPLES> break
BREAK is off
- 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
- 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
- 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
| Search
| CTG
| RTL
| IDDE
| STL
| C/C++ Compiler
| D