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

dos.h part 1

These are interfaces to the DOS operating system. They generally correspond directly to DOS API calls. They are not portable to operating systems other than DOS.
absread
abswrite
dos_abs_disk_read
dos_abs_disk_write
dos_alloc
_dos_allocmem
dos_calloc
_dos_close
_dos_commit
dos_creat
_dos_creat
_dos_creatnew
_doserrno
_dosexterr
_dos_findfirst
_dos_findnext
dos_free
_dos_freemem
dos_get_ctrl_break
dos_get_verify
_dos_getdate
_dos_getdiskfree, _getdiskfree
dos_getdiskfreespace
_dos_getdrive
_dos_getfileattr
_dos_getftime
_dos_gettime
_dos_getvect
_dos_keep
_dos_lock
_dos_open
dos_open
_dos_read
_dos_seek
_dos_setblock
dos_setblock
dos_set_ctrl_break
_dos_setdate
_dos_setdrive
_dos_setfileattr
_dos_setftime
_dos_settime
_dos_setvect
dos_set_verify
_dos_write
These interface to services provided by the 32 bit DOS extenders.
_x386_coreleft
_x386_free_protected_ptr
_x386_get_abs_address
_x386_map_physical_address
_x386_memlock
_x386_memunlock
_x386_mk_protected_ptr

absread

Header
dos.h
Prototype
int absread(int drive, int nsects, long lsect, char *buffer);
Description
Reads specific disk sectors from a drive. drive is the drive to read from. nsects is the number of sectors to read; this can be a maximum of either 64K or the buffer size, whichever is smaller. lsect defines the beginning logical sector number. buffer indicates where the data should be placed.

This function is exactly the same as dos_abs_disk_read.

Return Value
0 if successful, otherwise the DOS error code.
Compatibility
DOS, Windows 3.x, Phar Lap, DOSX
See Also
abswrite dos_abs_disk_read

abswrite

Header
dos.h
Prototype
int abswrite(int drive, int nsects, long lsect, const char *buffer);
Description
abswrite writes to the drive specified by drive. nsects defines the number of sectors to write; this must be either 64K or the size of the buffer, whichever is smaller. buffer specifies the address in memory where the data will be written from.

This function is exactly the same as dos_abs_disk_write.

Return Value
0 if successful, otherwise the DOS error code.
Compatibility
DOS, Windows 3.x, Phar Lap, DOSX
See Also
absread dos_abs_disk_write
Example
See dos_abs_disk_write

dos_abs_disk_read

Header
dos.h
Prototype
int dos_abs_disk_read(int drive, int num_sec, long start_sec, char *buffer);
Description
Transfers control directly to BIOS to perform disk read. Use 0 to specify drive A, 1 for B, and so on to 25. The number of sectors to read is num_sec. start_sec defines the first sector for operation. Argument buffer is the operation's destination memory address. The buffer must be large enough to hold the requested sectors.
Return Value
Returns a 0 on success. Non-zero indicates an error; the lower byte contains the DOS error code; the higher byte contains the specific BIOS error. The BIOS error codes are:
0x01 Bad command
0x02 Bad address mark
0x03 Write protect error
0x04 Sector not found
0x08 DMA (direct memory access) failure
0x10 Data error (bad CRC)
0x20 Controller failure
0x40 Seek operation failed
0x80 Device failed to respond
Compatibility
DOS Windows 3.x Win32
See Also
dos_abs_disk_write
Example
/* Example for dos_abs_disk_read
   Also demonstrates absread
   (which is just like it),
   atoi, toupper and isprint

   DISKDUMP.C

   Reads logical sector 1 from drive A
   and prints a hex and
   ascii dump of it.
*/

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

static unsigned char buffer[512];

void main(int argc, const char *const argv[])
{
 int i, drive, sector;
 unsigned char *p;
 unsigned code;

 if (argc < 3)
    goto usage_error;
 drive = toupper(*argv[1]) - 'A';
 if (drive < 0 || drive > 25)
    goto usage_error;
 sector = atoi(argv[2]);
 code = dos_abs_disk_read(drive, 1, sector, (char *)buffer);
 if (code != 0)
 {
   fprintf(stderr, "Error, dos code %02x, bios code %02x\n",
           code & 0xff, code >> 8);
   exit(EXIT_FAILURE);
 }
 printf("Drive %c, logical sector %d:\n",
         drive + 'A', sector);
 for (p = buffer; p < buffer + sizeof buffer; p += 16)
 {
   for (i = 0; i < 16; i += 1)
      printf("%02x ", p[i]);
   printf(" ");
   for (i = 0; i < 16; i += 1)
      if (isprint(p[i]))
         printf("%c", p[i]);
      else
         printf(".");
   printf("\n");
 }
 exit(EXIT_SUCCESS);

usage_error:
 fprintf(stderr,"Usage: DISKDUMP drive-letter sector-number\n");
 exit(EXIT_FAILURE);
}
Output
Drive C, logical sector 0:

eb 3c 90 4d 53 44 4f 53 35 2e 30 00 02 10 01 00 .<. MSDOS5.0.....
02 00 02 00 00 f8 00 01 20 00 40 00 20 00 00 00 ........ .@. ...
e0 f7 0f 00 80 00 29 c7 5e 63 1c 4d 53 2d 44 4f .......^ c. MS-DO
53 5f 36 20 20 20 46 41 54 31 36 20 20 20 fa 33 S_6 FAT16 .3
c0 8e d0 bc 00 7c 16 07 bb 78 00 36 c5 37 1e 56 .....|... x. 6.7. V
16 53 bf 3e 7c b9 0b 00 fc f3 a4 06 1f c6 45 fe .S.>|......... E.
0f 8b 0e 18 7c 88 4d f9 89 47 02 c7 07 3e 7c fb ....|. M.. G...>|.
cd 13 72 79 33 c0 39 06 13 7c 74 08 8b 0e 13 7c .. ry3.9..| t....|
89 0e 20 7c a0 10 7c f7 26 16 7c 03 06 1c 7c 13 .. |..|.&.|...|.
16 1e 7c 03 06 0e 7c 83 d2 00 a3 50 7c 89 16 52 ..|...|.... P|.. R
7c a3 49 7c 89 16 4b 7c b8 20 00 f7 26 11 7c 8b |. I|.. K|. ..&.|.
1e 0b 7c 03 c3 48 f7 f3 01 06 49 7c 83 16 4b 7c ..|.. H.... I|.. K|
00 bb 00 05 8b 16 52 7c a1 50 7c e8 92 00 72 1d ...... R|. P|... r.
b0 01 e8 ac 00 72 16 8b fb b9 0b 00 be e6 7d f3 ..... r........}.
a6 75 0a 8d 7f 20 b9 0b 00 f3 a6 74 18 be 9e 7d .u... ..... t...}
e8 5f 00 33 c0 cd 16 5e 1f 8f 04 8f 44 02 cd 19 ._. 3...^.... D...
58 58 58 eb e8 8b 47 1a 48 48 8a 1e 0d 7c 32 ff XXX... G. HH...| 2.
f7 e3 03 06 49 7c 13 16 4b 7c bb 00 07 b9 03 00 .... I|.. K|......
50 52 51 e8 3a 00 72 d8 b0 01 e8 54 00 59 5a 58 PRQ.:. r.... T. YZX
72 bb 05 01 00 83 d2 00 03 1e 0b 7c e2 e2 8a 2e r..........|....
15 7c 8a 16 24 7c 8b 1e 49 7c a1 4b 7c ea 00 00 .|..$|.. I|. K|...
70 00 ac 0a c0 74 29 b4 0e bb 07 00 cd 10 eb f2 p.... t).........
3b 16 18 7c 73 19 f7 36 18 7c fe c2 88 16 4f 7c ;..| s.. 6.|.... O|
33 d2 f7 36 1a 7c 88 16 25 7c a3 4d 7c f8 c3 f9 3.. 6.|..%|. M|...
c3 b4 02 8b 16 4d 7c b1 06 d2 e6 0a 36 4f 7c 8b ..... M|..... 6O|.
ca 86 e9 8a 16 24 7c 8a 36 25 7c cd 13 c3 0d 0a .....$|. 6%|.....
4e 6f 6e 2d 53 79 73 74 65 6d 20 64 69 73 6b 20 Non-System disk
6f 72 20 64 69 73 6b 20 65 72 72 6f 72 0d 0a 52 or disk error.. R
65 70 6c 61 63 65 20 61 6e 64 20 70 72 65 73 73 eplace and press
20 61 6e 79 20 6b 65 79 20 77 68 65 6e 20 72 65 any key when re
61 64 79 0d 0a 00 49 4f 20 20 20 20 20 20 53 59 ady... IO SY
53 4d 53 44 4f 53 20 20 20 53 59 53 00 00 55 aa SMSDOS SYS.. U.

dos_abs_disk_write

Header
dos.h
Prototype
int dos_abs_disk_write( int drive, int num_sec, long start_sec, const char *buffer):

Description
The dos_abs_disk_write function transfers control directly to BIOS to perform the disk write. The drive should contain a 0 for A, a 1 for B, and so on, up to 25. The number of sectors to write is specified in num_sec. start_sec defines the first sector for operation. Buffer is the source memory address for the operation.

Writing to a disk using this function could cause irretrievable loss of data, and may damage the file structure of the disk. For this reason no example is given. Use this function if you are fully conversant with the organization of MS-DOS disks and their file structures.

Return Value
See dos_abs_disk_read
Compatibility
DOS Windows 3.x Win32
See Also
dos_abs_disk_read
Example
See dos_abs_disk_read

dos_alloc

Header
dos.h
Prototype
unsigned dos_alloc( unsigned para);

Description
The dos_alloc function allocates memory from the heap by a direct call to MS-DOS. The argument para contains the number of paragraphs required; a paragraph contains 16 bytes. Memory allocated with dos_alloc should only be freed with dos_free.
Return Value
Returns the segment of the allocated block. If unsuccessful, returns zero, sets _doserrno to the OS error number, and sets errno to the corresponding standard code.
Compatibility
DOS Windows 3.x Win32
See Also
dos_free
Example
/* Example for dos_alloc, dos_free, _MK_FP
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 unsigned newseg;
 void __far *pointer;

 newseg = dos_alloc(20);
 if (newseg == 0)
 {
    perror("dos_alloc failed");
    exit(EXIT_FAILURE);
 }
 pointer = _MK_FP(newseg, 0);
 printf("Memory allocated successfully at %Fp\n", pointer);
 if (dos_free(newseg) == -1)
 {
    perror("Unable to free memory\n");
    exit(EXIT_FAILURE);
 }
}
Output
Memory allocated successfully at 2FF5:0000

_dos_allocmem

Header
dos.h errno.h
Prototype
unsigned _dos_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 by size. (There are 16 bytes in a paragraph.) segp points to the word that contains the segment descriptor of the allocated memory block.

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

Return Value
Returns 0 if the memory is successfully allocated. If unsuccessful, -1 DOS error code is returned and the word pointed to by segp is set to the size (in paragraphs) of the largest available block. 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
See Also
_dos_freemem
Example
/*      Example for _dos_allocmem
        Also demonstrates _dos_freemem
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 unsigned largest;
 int size = 64;
 unsigned segp;

 largest = _dos_allocmem(size, &segp);
 if (largest != -1)
 {
   printf("Address of segment: %p\n", segp);
   printf("Allocated memory at segment:% x\n", &segp);
   _dos_freemem(segp);
 }
 else
   printf("Unable to allocate memory\n");
}
Output
Address of segment: 3690
Allocated memory at segment: 17e0

dos_calloc

Header
dos.h
Prototype
unsigned dos_calloc( unsigned para);
Description
The dos_calloc function allocates memory from the heap by a direct call to MS-DOS. If successful, the allocated memory is cleared (all bytes zero). The argument para contains the number of paragraphs required; each paragraph contains 16 bytes. Memory allocated with dos_calloc should only be freed by dos_free.
Return Value
If successful, dos_calloc returns the segment of the allocated block, otherwise zero is returned, _doserrno is set to the OS error number, and errno is set to the corresponding standard error code.
Compatibility
DOS Windows 3.x
See Also
dos_alloc
Example
See dos_alloc

_dos_close

Header
dos.h
errno.h
Prototype
int _dos_close( int handle);
Description
The _dos_close function uses system call 0x3E to close the file indicated by the handle argument. (The handle is a descriptor returned by the call that created or last opened the file.)
Synonym
dos_close
Return Value
Returns 0 if successful. Otherwise, _doc_close returns the DOS error code and sets errno to EBADF, indicating an invalid file handle.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_open
Example
See _dos_open

_dos_commit

Header
dos.h
errno.h
Prototype
unsigned _dos_commit( int handle);
Description
The _dos_commit function uses system call 0x68 to flush to disk the DOS buffers associated with the file indicated by handle. This function also forces an update on the corresponding disk directory and file allocation table. In addition, the function ensures that the file is flushed directly to disk (not at the operating system's discretion.)
Return Value
Returns 0 if successful. Otherwise, it returns the DOS error code and sets errno to EBADF, indicating an invalid file handle.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_read _dos_write
Example
/* Example for _dos_commit
   Also demonstrates _dos_close, _dos_creat,
   _dos_read and _dos_write
*/
#include <dos.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void main()
{
 int fd;
 int result;
 unsigned count;
 char buf[32] = "Hello from Digital Mars\0" ;
 char newbuf[50];
 fd = 0;
 result = _dos_creat("temp.dat", _A_NORMAL, &fd);
 if (result != 0)
   perror("_dos_creat failed");
 else
 {
   _dos_write(fd, buf, strlen(buf), &count);
   _dos_commit(fd);
   _dos_read(fd, newbuf, 50, &count);
   _dos_close(fd);
 }
}
Output
This program will overwrite the contents of the file temp.dat with the
string "Hello from Digital Mars".

dos_creat

Header
dos.h
Prototype
int dos_creat(const char *name, int attrib);
Description
The dos_creat function opens a new file named name with attributes specified in attrib. It returns the new file's handle (whereas _dos_creat copies the new file's handle to the location pointed to by handle). The file is opened for read and write access. If the specified file exists, the file keeps its original attributes, the size is reset to 0, and the contents of the file are lost. If the specified file does not exist, a new file is created.

The attribute byte is the same as described in the reference manual for MS-DOS. Use the following attribute values defined in dos.h:

_A_NORMAL 0x00 Normal File
_A_RDONLY 0x01 Read Only
_A_HIDDEN 0x02 Hidden file
_A_SYSTEM 0x04 System file
_A_ARCH 0x20 Archive bit
Synonym
Attribute values: FA_NORMAL, FA_RDONLY, FA_HIDDEN, FA_SYSTEM, FA_ARCH
Return Value
Returns a DOS handle if the file is successfully created. If unsuccessful, it returns -1, and errno is set to the corresponding error code, and _doserrno is set to the OS error number.
Compatibility
DOS Windows 3.x Phar Lap DOSX
See Also
_dos_creat _dos_creatnew

_dos_creat

Header
dos.h
errno.h
Prototype
int _dos_creat( const char *name, unsigned attrib, int *handle);
Description
This function opens a new file named name with attributes specified in attrib. The _dos_creat function copies the new file's handle to the location pointed to by handle. The file is opened for read and write access.

If the specified file exists, the file keeps its original attributes, the size is reset to 0, and the contents of the file are lost. If the specified file does not exist, a new file is created.

The attribute byte is the same as described in the reference manual for MS-DOS. Use the following attribute values defined in dos.h:
_A_NORMAL 0x00 Normal File
_A_RDONLY 0x01 Read Only
_A_HIDDEN 0x02 Hidden file
_A_SYSTEM 0x04 System file
_A_ARCH 0x20 Archive bit
Return Value
0 if successful. Otherwise returns the DOS error code and errno is set to one of the following values:

EACCES Access denied because the directory is full
EMFILE Too many open file handles
ENOENT Path or file not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_creatnew
Example
/* Example for _dos_creat
   Also demonstrates _dos_close
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int handle;
 int result;

 result = _dos_creat("temp.dat",
       _A_NORMAL, &handle);
 if (result != 0)
   perror ("_dos_creat failed");
 else
 {
   printf("File successfully created\n");
   _dos_close( handle);
 }
}
Output
File successfully created

_dos_creatnew

Header
dos.h
Prototype
unsigned _dos_creatnew( const char *path, unsigned attrib, int *handle);
Description
The _dos_creatnew function creates a file using the 0x5B system call. This function opens a new file named name with attributes specified in attrib. The new file's handle is copied into the location pointed to by handle. The file is opened for both read and write access. If the file already exists, _dos_creatnew fails.
Return Value
Returns 0 if successful. Otherwise, the DOS error code is returned and errno is set to one of the following values:

EACCES Access denied because the directory is full
EEXIST File already exists
EMFILE Too many open file handles
ENOENT Path or file not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_creat
Example
/* Example for _dos_creatnew
   Also demonstrates _dos_close
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int handle;
 int result;

 result = _dos_creatnew("temp.dat", _A_NORMAL, &handle);

 if (result != 0)
    perror("_dos_creatnew failed");
 else
 {
    printf("File created\n");
    _dos_close(handle);
 }
}
Output
If the file temp.dat does not exist: 
File created
If the file temp.dat exists: 
_dos_creatnew failed: File exists

_doserrno

Header
stdlib.h
Prototype
extern int _doserrno;
Description
This variable contains the operating system error code for the last error that occurred. For DOS, Windows 3.x, and Phar Lap, the error code is a DOS error code; for Win32 it is a Win32 error code.

When errno is set, _doserrno is also set. If the error did not originate from an operating system call, _doserrno is undefined.

Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
errno _sys_errlist _sys_nerr

_dosexterr

Header
dos.h
Prototype
int _dosexterr(struct _DOSERROR *err);
Description
_dosexterr uses system call 0x59 to retrieve DOS error information on a failed DOS call. The returned error information is stored in the structure pointed to by err. The _dosexterr function returns information in a structure of type _DOSERROR.

_DOSERROR struct fields
int exterror AX register contents (extended error)
char eclass BH register contents (error class)
char action BL register contents (action)
char locus CH register contents (error locus)

If err is NULL, _dosexterr will return immediately with the extended error number. _dosexterr is only available with MS-DOS 3.x and above.

Synonym
Function: dos_exterr, dosexterr
Structure: DOSERROR
Return Value
Returns the DOS extended error number, which is the exterror field of the _DOSERROR structure. A value of 0 means that no error occurred in the previous operation.
Compatibility
DOS 3.x and above, Windows 3.x, Phar Lap, DOSX, Win32
See Also
_dos_creat
Example
/* Example for _dos_exterr
   Also demonstrates _dos_close, _dos_creat
   and _dos_creatnew
*/
#include <dos.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

int main()
{
 int handle;
 int result;
 struct _DOSERROR p;

 /* These calls in this order should */
 /* guarantee an error occurs */

 result = _dos_creat("temp.dat", _A_NORMAL, &handle);
 result = _dos_creatnew("temp.dat", _A_NORMAL, &handle);
 if (result != 0)
 {
    _dosexterr(&p);
    printf("Exterror = %d\n", p.exterror);
    printf("Class = %d\n", p.errclass);
    printf("Action = %d\n", p.action);
    printf("Locus = %d\n", p.locus);
    perror("Create new file error");
 }
 else
    printf("No file error");

 _dos_close(handle);
 return 0;
}
Output
Exterror = 80
Class = 12
Action = 3
Locus = 2
Create new file error: File exists

_dos_findfirst

Header
dos.h
errno.h
Prototype
unsigned _dos_findfirst( const char *name, unsigned attr, struct find_t *fileinfo);
Description
The _dos_findfirst function uses system call 0x4E to return information about the first instance of a file whose name and attributes match name and attr. The file information is returned in the structure pointed to by fileinfo.

The name argument can contain wildcards. The attr argument can be one or more of the following attributes. To specify more than one value, join them with the bitwise OR operator.

_A_ARCH Archive
_A_HIDDEN Hidden file
_A_NORMAL Normal file
_A_RDONLY Read only
_A_SUBDIR Subdirectory
_A_SYSTEM System file
_A_VOLID Volume ID
If a program specifies any combination of _A_HIDDEN, _A_SUBDIR or _A_SYSTEM, then _dos_findfirst returns normal files in addition to the specified files. The program must examine the attribute contained in the DTA to determine the type of file found.

File information is returned in a find_t structure. This type, which is defined in the dos.h header file, has the following elements:
char reserved[21] Reserved for use by DOS
char attrib Attribute byte for matched path
unsigned short wr_time Time of last write to file
unsigned short wr_date Date of last write to file
unsigned long size Length of file in bytes
char name[13] Null-terminated name of matched file/directory, without the path
The formats for the wr_time and wr_date are in DOS format and are not for use by other C run-time functions. The time format is:
Bits 0-4 Number of 2-second increments (0-29)
Bits 5-10 Minutes (0-59)
Bits 11-15 Hours (0-23)
The date format is:

Bits 0-4 Day of month (1-31)
Bits 5-8 Month (1-12)
Bits 9-15 Year (relative to 1980)
The primary difference between this routine and findfirst is that this routine allows recursion through the use of different file information structures for each invocation of _dos_findfirst.
Return Value
Returns 0 if a file is found. Otherwise, returns the DOS error code and sets errno to ENOENT, indicating that name was not found.
Compatibility
DOS Windows 3.x
See Also
_dos_findnext
Example

_dos_findnext

Header
dos.h
errno.h
Prototype
unsigned _dos_findnext( struct find_t *fileinfo);
Description
The _dos_findnext function uses system call 0x4F to return information about the next instance of a file whose file information block was returned by a previous _dos_findfirst call. Argument fileinfo specifies a previously returned file information block.

File information is stored in a _find_t structure. This type is defined in the dos.h header file. For a description of the _find_t structure, see the _dos_findfirst reference page.

The primary difference between this function and findnext is that it allows recursion through the use of different file information structures for each time the _dos_findfirst function is called.
Return Value
Returns 0 if a file is found. Otherwise, it returns the DOS error code and sets errno to ENOENT, indicating that no file could be found.
Compatibility
DOS Windows 3.x
See Also
_dos_findfirst

dos_free

Header
dos.h
Prototype
int dos_free( unsigned seg);
Description
Frees (releases back to the operating system) memory previously allocated with dos_alloc or dos_calloc. Argument seg is the segment address of the memory to be freed.
Return Value
Returns 0 if the memory was sucessfully freed; if the memory could not be freed, the return value is -1.
Compatibility
DOS Windows 3.x
See Also
dos_alloc

_dos_freemem

Header
dos.h
errno.h
Prototype
unsigned _dos_freemem( unsigned seg);
Description
The _dos_freemem function uses system call 0x49 to free memory previously allocated with _dos_allocmem. Argument seg is the segment address of the memory to be freed, which was returned by a previous call to _dos_allocmem.
Return Value
Returns 0 if the memory was sucessfully freed. If the memory could not be freed, the return value is -1 and errno is set to ENOMEM.
Compatibility
DOS Windows 3.x
See Also
_dos_allocmem
Example
See _dos_allocmem

dos_get_ctrl_break

Header
dos.h
Prototype
int dos_get_ctrl_break( void);
Description
Returns the state of the DOS control break status. Returns a non-zero value if BREAK checking is on and a zero value if BREAK checking is off. For additional information, see the BREAK command in the reference manual for your MS-DOS system.
Return Value
Return non-zero if the status is on and a zero if the status is off.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
dos_set_ctrl_break

dos_get_verify

Header
dos.h
Prototype
int dos_get_verify( void);
Description
Returns the state of the DOS verify status. This function will return a non-zero value if VERIFY is on and a zero if the VERIFY is off. For additional information, see the VERIFY command in the technical reference manual for your DOS system.
Return Value
Return non-zero if the status is on and a zero if the status is off.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
dos_set_verify

_dos_getdate

Header
dos.h
Prototype
void _dos_getdate( struct _dosdate_t *date);
Description
The dos_getdate function obtains the current system date via a call to DOS function 0x2A and places it in the structure pointed to by the date argument.

The format of the _dosdate_t structure is:

struct _dosdate_t
{
 unsigned char day;  /* day of month( 1-31)*/
 unsigned char month; /* month (1-12)*/
 unsigned int year; /* year (1980-2099)*/
 unsigned char dayofweek; /* 0-6 (0= Sunday)*/
}
Synonym
Function: dos_getdate
Type: dos_date_t
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_setdate
Example
/* Example for _dos_getdate and _dos_setdate
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 struct _dosdate_t date;
 unsigned int oldyear;

 _dos_getdate(&date);
 printf("Date : %2d/%2d/%d\n",
    date.month,
    date.day,
    date.year);

 oldyear = date.year;
 date.year = 1990;
 _dos_setdate(&date);
 _dos_getdate(&date);

 printf("Date : %2d/%2d/%d\n",
     date.month,
     date.day,
     date.year);
 date.year = oldyear;
 _dos_setdate(& date);
 _dos_getdate(& date);
 printf("Date : %2d/%2d/%d\n",
   date.month,
   date.day,
   date.year);
}
Output
Date : 6/22/1994
Date : 6/22/1990
Date : 6/22/1994

_dos_getdiskfree

Header
dos.h
errno.h
Prototype
unsigned _dos_getdiskfree( unsigned drive, struct _diskfree_t *diskspace);
unsigned _getdiskfree( unsigned drive, struct _diskfree_t *diskspace);
Description
The _dos_getdiskfree function obtains information on the disk drive specified by drive, using system call 0x36. The default drive is 0, drive A is 1, drive B is 2, and so on. Disk information is returned in _diskfree_t structure pointed to by diskspace.

The format of the _diskfree_t structure is:
struct _diskfree_t
{
   unsigned total_clusters; /* on disk*/
   unsigned avail_clusters; /* on disk*/
   unsigned sectors_per_clusters;
   unsigned bytes_per_sector;
}
Synonym
Type: diskfree_t
Return Value
Returns 0 if successful. Otherwise, returns non-zero and sets errno to EINVAL to indicate that an invalid drive was specified.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_setdrive
Example
/* Example for _dos_getdiskfree
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 unsigned ret;
 struct diskfree_t free;

 ret = _dos_getdiskfree(0, &free);
 if (ret != 0)
    perror("_dos_getdiskfree");
 else
 {
  printf("% u avaliable clusters\n",
         free.avail_clusters);
  printf("out of %u clusters.\n",
         free.total_clusters);
  printf("% u sectors per cluster,\n",
         free.sectors_per_cluster);
  printf("% u bytes per sector.\n",
         free.bytes_per_sector);
 }
}
Output
14437 avaliable clusters
out of a total of 32914 clusters.
16 sectors per cluster,
512 bytes per sector.

dos_getdiskfreespace

Header
dos.h
Prototype
long dos_getdiskfreespace( int drive);
Description
Returns a long integer of available disk space. drive is an integer value where the default drive is 0; drive A is 1, drive B is 2, and so on.
Return Value
Returns the number of free bytes on the disk.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_getdiskfree
Example
/*      Example for dos_getdiskfreespace
        DISKFREE. C
*/

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

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

 if (argc < 2)
    drive = 0;
 else
    drive = toupper(*argv[1]) -'A' + 1;
 if (drive < 0 || drive > 26)
 {
    fprintf(stderr,
           "Usage: DISKFREE [drive-letter]\ n");
    exit(EXIT_FAILURE);
 }
 printf("Free space is %ld bytes\n",
        dos_getdiskfreespace(drive));
}
Output
C:\SC\EXAMPLES> diskfree j
Free space is 28119040 bytes

_dos_getdrive

Header
dos.h
Prototype
void _dos_getdrive( unsigned *driveptr);
Description
The _dos_getdrive function uses system call 0x19 to get the identity of the current disk drive and stores it in the unsigned integer pointed to by driveptr. The drive is reported as an integer number where 1 =A, 2 = B, 3 = C, and so on.
Synonym
Function: dos_getdrive
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_setdrive
Example
/* Example for _dos_getdrive */

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

void main()
{
 unsigned driveno;

 _dos_getdrive(&driveno);
 printf("The current drive is %c\n",
        driveno - 1 + 'a');
}
Output
The current drive is c

_dos_getfileattr

Header
dos.h
errno.h
Prototype
unsigned _dos_getfileattr( const char *filepath, unsigned *att);
Description
The _dos_getfileattr function gets the current file attributes of the named file and places them in the unsigned integer pointed to by att. The char pointer filepath references a standard DOS path and filename as a null terminated string. Individual file attributes can be checked by logically ANDing them with the appropriate masks.

File attributes are listed in the dos_setfileattr description.
Synonym
Function: dos_getfileattr
Return Value
0 if succesful. Otherwise returns the DOS error code. In addtion, _dos_getfileattr sets errno to ENOENT, indicating that the target file or directory was not found.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_setfileattr
Example
/* Example for _dos_getfileattr,
   and _dos_setfileattr
   Also demonstrates _dos_creat
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int handle, result;
 unsigned attrib;

 result = _dos_creat("temp.dat",
       _A_RDONLY, &handle);
 if (result == 0)
 {
    _dos_getfileattr("temp.dat", &attrib);
    if (attrib & _A_RDONLY)
       printf("File is read only\n");
    else
       printf("File is not read only\n");
    if (attrib & _A_ARCH)
       printf("File has archive bit set\n");
    else
       printf("File does not have archive bit
	      set\n");

    _dos_setfileattr("temp.dat", _A_NORMAL);
    _dos_getfileattr("temp.dat", &attrib);

    if (attrib & _A_RDONLY)
       printf("File is read only\n");
    else
       printf("File is not read only\n");

    if (attrib & _A_ARCH)
       printf("File has archive bit set\n");
    else
       printf("File does not have archive bit set\n");

    _dos_close(handle);
 }
 else
    perror("Error creating file");
}
Output
File is read only
File has archive bit set
File is not read only
File does not have archive bit set

_dos_getftime

Header
dos.h
errno.h
Prototype
unsigned _dos_getftime( int fd, unsigned *date, unsigned *time);
Description
The _dos_getftime function gets the time and date of when the file (belonging to the file descriptor fd) was last written, and places these values in the unsigned integers pointed to by arguments date and time. The format of these arguments is:

date:
bits 0 to 4 Day of month (0-31)
bits 5 to 8 Month (0-12)
bits 9 to 15 (relative to 1980)
time:
bits 0 to 4 Number of 2 second increments (0-29)
bits 5 to 10 Minutes (0-59)
bits 11 to 15 Hours (0-23)
Return Value
0 if successful. Otherwise, returns the DOS error code and set errno to EBADF.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_setftime
Example
/* Example for _dos_getftime and _dos_setftime
   Also demonstrates _dos_open and _dos_close
*/
#include <dos.h>
#include <fcntl.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int handle, result;
 int d, m, y, h, mi, s;
 unsigned date, time, oldtime;

 result = _dos_open("temp.dat",
         _O_RDONLY, &handle);
 if (result == 0)
 {
    _dos_getftime(handle, &date, &time);

    d = date & 0x01F;
    m = (date >> 5) & 0x0F;
    y = (( date >> 9) & 0x7F) + 1980;
    s = (time & 0x1F)* 2;
    mi = (time >> 5) & 0x3F;
    h = (time >> 11) & 0x1F;

    printf("temp.dat date = %2d/%2d/%4d\n",
	      m, d, y);
    printf("temp.dat time = %2d:%2d:%2d\n",
	      h, mi, s);

    oldtime = time;
    time = 6;
    _dos_setftime(handle, date, time);
    _dos_getftime(handle, &date, &time);

    s = (time & 0x1F) * 2;
    mi = (time >> 5) & 0x3F;
    h = (time >> 11) & 0x1F;

    printf("\ntemp.dat time =
	    %2d:%2d:%2d\n\n", h, mi, s);

    time = oldtime;
    _dos_setftime(handle, date, time);
    _dos_getftime(handle, &date, &time);

    d = date & 0x01F;
    m = (date >> 5) & 0x0F;
    y = (( date >> 9) & 0x7F) + 1980;
    s = (time & 0x1F)* 2;
    mi = (time >> 5) & 0x3F;
    h = (time >> 11) & 0x1F;

    printf("temp.dat date = %2d/%2d/%4d\n",
	      m, d, y);
    printf("temp.dat time = %2d:%2d:%2d\n",
	      h, mi, s);

    _dos_close(handle);
 }
 else
    perror("Error creating file");
}
Output
temp.dat date = 6/27/1994
temp.dat time = 11:22:36

temp.dat time = 0:0:12

temp.dat date = 6/27/1994
temp.dat time = 11:22:36

_dos_gettime

Header
dos.h
Prototype
void _dos_gettime( struct dos_time_t *time);
Description
The _dos_gettime function gets the current system time via system call 0x2C and place it in the structure pointed to by time. The format of the time structure is: 

struct dos_time_t
{
 unsigned char hour; /* hours (0-23)*/
 unsigned char minute; /* minutes (0-59)*/
 unsigned char second; /* seconds (0-59) */
 unsigned char hsecond; /* seconds/ 100 (0-99)*/
}
Synonym
Function: dos_gettime
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_settime
Example
/* Example for _dos_gettime, _dos_settime */

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

void main()
{
 struct _dostime_t time;
 char oh;

 _dos_gettime(&time);

 printf("Time is %02d:% 02d:% 02d\n",
        time.hour, time.minute, time.second);

 oh = time.hour;
 time.hour = 4;

 _dos_settime(&time);
 _dos_gettime(&time);

 printf("Time is %02d:% 02d:% 02d\n",
        time.hour, time.minute, time.second);

 time.hour = oh;
 _dos_settime(&time);
 _dos_gettime(&time);

 printf("Time is %02d:% 02d:% 02d\n",
        time.hour, time.minute, time.second);
}
Output
Time is 11: 49: 21
Time is 04: 49: 21
Time is 11: 49: 21

_dos_getvect

Header
dos.h
Prototype
void (__cdecl __interrupt __far *_dos_getvect( unsigned intnum))();
Description
The _dos_getvect function gets the current value of the target interrupt vector specified by intnum. The function uses DOS system call 0x35. To replace an interrupt vector:

  1. Save the interrupt's current vector using _dos_getvect.
  2. Set the vector to a user-defined interrupt routine using _dos_setvect.

If necessary, restore the saved vector by using _dos_setvect.
Return Value
A far pointer for the target interrupt vector to the current handler, if one exists.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_setvect _chain_intr

_dos_keep

Header
dos.h
Prototype
void _dos_keep( unsigned retcode, unsigned memsize);
Description
The _dos_keep function uses system call 0x31 to install a TSR (terminate and stay resident program). This causes the current calling process to exit, while keeping it resident in memory. The retcode is the low order byte of the exit status code. The memsize specifies the amount of resident memory (in 16-byte paragraphs) that _dos_keep allocates for the program.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_c_exit, _cexit _exit

_dos_lock

Header
dos.h
Prototype
unsigned _dos_lock( int handle, int mode, unsigned long offset, unsigned long length);
Description
The _dos_lock function locks a region of a file preventing other processes from accessing that region. The handle argument must be a handle to an open file. Values for mode are:

Value Meaning
0 Locks the region
1 Unlocks the region
The beginning of the region is specified by offset. Its length is specified by length.

The offset and length values of the unlocked region must be the exact same values of the region when it was locked. It is valid to lock a region that extends beyond the end of the file.

For DOS, Windows 3.x, and Phar Lap, a DOS system call 0x5c is used to lock and unlock the region. For these systems, the SHARE. EXE program must be installed to use file sharing.
Return Value
Returns 0 if successful, otherwise returns the operating system error code and sets errno.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_locking
Example
/* Example for _dos_lock
   Also demonstrates _dos_open, _dos_close

   LOCKER.C

   Locks 10 bytes of this file starting at offset 25,
   making them inaccessable to LOCKEE.EXE.
*/
#include <dos.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <share.h>
#include <io.h>

static void error(char *message)
{
 perror(message);
 exit(EXIT_FAILURE);
}
void main()
{
 int handle;
 if (_dos_open("locker.c",
     _O_RDONLY|_SH_DENYNO, &handle) != 0)
   error ("Open failed");
 if (_dos_lock(handle, 0, 25L, 10L) != 0)
     error ("Lock failed (is SHARE running?)");
 printf("LOCKER.C locked. Run LOCKEE.EXE in
        another Windows DOS box now.\n"
     "Press any key when ready to unlock: ");
 getch();
 if (_dos_lock(handle, 1, 25L, 10L) != 0)
   error("Unlock failed");
 printf("\nFile unlocked. Try LOCKEE.EXE
         again.\n");
 _dos_close(handle);
}


/* Second part of example for _dos_lock
   Also demonstrates _dos_open, _dos_seek,
   _dos_close

   LOCKEE.C

Prints the first 100 characters of LOCKER.C. If
a character can't be accessed, a question mark
is printed.
*/
#include <dos.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <share.h>

static void error(char *message)
{
 perror(message);
 exit(EXIT_FAILURE);
}
int main()
{
 int handle, i;
 char c;
 unsigned actual;

 if (_dos_open("LOCKER.C",
     _O_RDONLY|_SH_DENYNO, &handle) != 0)
     error("Open failed");
 for (i = 0; i < 100; i += 1)
 {
   if (_dos_seek(handle, (unsigned long)i, 0) == -1)
       error("Seek error");
   if (_dos_read(handle, &c, 1, &actual) != 0)
       printf("?");
   else
   {
       if (actual == 0)
           break;
       printf("%c", c);
   }
 }
 _dos_close(handle);
}
Output
---DOS box 1:
C:\SC\EXAMPLES> locker
LOCKER. C locked. Run LOCKEE. EXE in another
Windows DOS box now.
Press any key when ready to unlock:

---DOS box 2:

C:\SC\EXAMPLES> lockee
/*
   Example for _dos_l?????????? so demonstrates
_dos_open, _dos_close

LOCKER. C

Loc

---DOS box 1:

C:\SC\EXAMPLES> locker
LOCKER.C locked. Run LOCKEE.EXE in another
Windows DOS box now.
Press any key when ready to unlock:
File unlocked. Try LOCKEE.EXE again.

---DOS box 2:

C:\SC\EXAMPLES> lockee
/*
   Example for _dos_lock
   Also demonstrates _dos_open, _dos_close

   LOCKER.C

   Loc

_dos_open

Header
dos.h
errno.h
fcntl.h
share.h
Prototype
unsigned _dos_open( const char *pathname, unsigned mode, int *handle);
Description
The _dos_open function uses system call 0x3D to open the file specified by pathname, and to copy the handle into the location pointed to by handle. The mode argument selects the mode in which the file is opened. See the dos_open function.

Use the following access and inheritance mode values (defined in fcntl.h) and share mode values (defined in share.h). To specify more than one mode use the OR operator. You can specify only one access mode and one share mode at the same time.

Access Mode Meaning
_O_RDONLY Read-only
_O_WRONLY Write-only
_O_RDWR Both read and write
Share Mode Meaning
_SH_COMPAT Compatibility
_SH_DENYRW Deny reading and writing
_SH_DENYWR Deny writing
_SH_DENYRD Deny reading
_SH_DENYNO Deny neither
Inheritance Mode Meaning
_O_NOINHERIT File is not inherited
Synonym
Modes: O_RDONLY, O_WRONLY, O_RDWR, O_NOINHERIT, SH_COMPAT, SH_DENYRW, SH_DENYWR, SH_DENYRD, SH_DENYNO
Return Value
0 if successful. Otherwise, returns DOS error code; sets errno to:
EACESS Access denied
EINVAL Sharing mode specified if file sharing not installed
EMFILE Too many open files
ENOENT File not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_close dos_open
Example
/* Example for _dos_open, _dos_close */

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

void main()
{
 char *fname;
 unsigned int mode;
 int handle;
 int result;

 mode = O_RDONLY;
 fname = "temp.dat";
 result = _dos_open(fname, mode, &handle);

 if (result != 0)
    perror("Read_only open failed");
 else
 {
   printf("\nFile %s opened for reading\n",
           fname);
   _dos_close(handle);
 }

 mode = O_WRONLY;
 fname = "CON";

 result = _dos_open(fname, mode, &handle);

 if (result != 0)
   perror ("Error opening console");
 else
 {
   printf("\nFile %s opened for writing\n",
          fname);
   _dos_close( handle);
 }
}
Output
File temp.dat opened for reading
File CON opened for writing

dos_open

Header
io.h
Prototype
int dos_open( const char *pathname, int mode);
Description
The dos_open function uses system call 0x3D to open the file specified by pathname and returns the handle of the opened file. See the _dos_open function.

Use the following access and inheritance mode values (defined in fcntl.h) and share mode values (defined in share.h). To specify more than one mode use the OR operator. You can specify only one access mode and one share mode at the same time.

Access Mode Meaning
_O_RDONLY Read-only
_O_WRONLY Write-only
_O_RDWR Both read and write
Share Mode Meaning
_SH_COMPAT Compatibility
_SH_DENYRW Deny reading and writing
_SH_DENYWR Deny writing
_SH_DENYRD Deny reading
_SH_DENYNO Deny neither
Inheritance Mode Meaning
_O_NOINHERIT File is not inherited
Synonym
Modes: O_RDONLY, O_WRONLY, O_RDWR, O_NOINHERIT, SH_COMPAT, SH_DENYRW, SH_DENYWR, SH_DENYRD, SH_DENYNO
Return Value
The file handle if successful; otherwise, if unsuccessful returns -1 and the DOS error code, and sets errno to one of the following:

EACCESS Access denied
EINVAL Sharing mode specified when file sharing not installed
EMFILE Too many open files
ENOENT File not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_close _dos_open

_dos_read

Header
dos.h
Prototype
unsigned _dos_read( int handle, void __far *buffer, unsigned count, unsigned *numread);
Description
The _dos_read function uses system call 0x3F to read data from the file specified in the handle argument. The function attempts to read count bytes of data and copy them to the buffer pointed to by buffer. The value pointed to by numread shows the actual number of bytes that were read. If the value pointed to by numread is 0, _dos_read tried to read at the end of the file.
Return Value
If successful, the function returns 0. Otherwise, it returns the DOS error code and sets errno to EACCES (access denied) or EBADF (invalid file handle).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_write
Example
See dos_commit

_dos_seek

Header
dos.h
Prototype
unsigned long _dos_seek( int handle, unsigned long offset, int origin);
Description
The _dos_seek function moves the file pointer of a file to a specified position. The file pointer is the position where the next read or write occurs. Argument handle must be a handle to an open file. offset is the distance to move the file pointer. origin is the starting position of the move; values are:

Value Starting position
0 The beginning of the file
1 The current position
2 The end of the file
For DOS, Windows 3.x, and Phar Lap, a DOS system call 0x42 is used to seek.
Return Value
Returns the resulting offset from the beginning of the file. If unsuccessful, returns -1L and sets errno.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
fseek _lseek
Example
/* Example for _dos_seek
   Also demonstrates _dos_open, _dos_read

   _DOS_SEE.C
*/
#include <dos.h>
#include <fcntl.h>
#include <share.h>
#include <stdlib.h>
#include <stdio.h>

static void error(char *message)
{
 perror(message);
 exit(EXIT_FAILURE);
}
void main()
{
  int handle;
  char buffer[20];
  unsigned actual;

  if (_dos_open("_DOS_SEE.C",
      _O_RDONLY|_SH_DENYNO, &handle) != 0)
     error("Open failed");

  if (_dos_seek(handle, -20, 2) == -1)
     error("Couldn't seek from end");

  if (_dos_read(handle, buffer, 20, &actual) != 0)
     error("Couldn't read from end");
  printf("The 20 bytes at the end
         are\n\n%. 20s\n\n", buffer);

  if (_dos_seek(handle, 20, 0) == -1)
     error("Couldn't seek from beginning");
  if (_dos_read(handle, buffer, 20, &actual) != 0)
     error("Couldn't read from beginning");
  printf("20 bytes 20 from the beginning
         are\n\n%. 20s\n\n", buffer);

  if (_dos_seek(handle, 20, 1) == -1)
     error("Couldn't seek from the current position");
  if (_dos_read(handle, buffer, 20, &actual) != 0)
     error("Couldn't read from the current position");
  printf("20 bytes 20 from the current
          position are\n\n%. 20s\n\n", buffer);
}
Output
The 20 bytes at the end are

\n\n", buffer);
}

20 bytes 20 from the beginning are

   Also de

20 bytes 20 from the current position are

   _D

_dos_setblock

Header
dos.h
Prototype
unsigned _dos_setblock( unsigned newsize, unsigned seg, unsigned *maxsize);
Description
The _dos_setblock function uses system call 0x4A to change the size of a memory segment allocated by a previous call to dos_allocmem, dos_alloc, or dos_calloc. The newsize argument is the new number of paragraphs requested, seg is the segment address of the allocated memory whose size is to be changed. This function is the same as dos_setblock except in how values are returned.
Return Value
The _dos_setblock function uses system call 0x4A to change the size of a memory segment allocated by a previous call to dos_allocmem, dos_alloc, or dos_calloc. The newsize argument is the new number of paragraphs requested, seg is the segment address of the allocated memory whose size is to be changed. This function is the same as dos_setblock except in how values are returned.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_allocmem dos_alloc dos_calloc _dos_setblock
Example
/* Example for _dos_setblock
   Also demonstrates _dos_allocmem
   and _dos_freemem
*/
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>
void main()
{
 unsigned newseg;
 unsigned maxsize;
 int result;

 result = _dos_allocmem( 10,& newseg);
 if (result == 0)
 {
    printf("Memory allocated at %u\n",
              newseg);
    result = _dos_setblock(20, newseg,
              &maxsize);
    if (result == 0)
    {
      printf("Memory successfully expanded\n");
      result = _dos_freemem(newseg);
      if (result == 0)
         printf("Memory successfully freed\n");
      else
         perror("Error freeing memory");
    }
    else
    {
      printf("_dos_setblock failed: ");
      printf("only %u available at %u\n",
                maxsize, newseg);
      result = _dos_freemem (newseg);
      if (result == 0)
         printf("Memory successfully freed\n");
      else
         perror("Error freeing memory");
    }
 }
 else
    perror("_dos_allocmem failed");
}
Output
Memory allocated at 13988d
Memory successfully expanded
Memory successfully freed

dos_setblock

Header
dos.h
Prototype
unsigned dos_setblock( unsigned newsize, unsigned seg);
Description
The dos_setblock function is like the _dos_setblock function except in the way it returns values.
Return Value
If dos_setblock is successful, it returns the segment address of the allocated memory. Otherwise, the function sets _doserrno, does not change the block size, and returns the maximum possible block size.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_allocmem dos_alloc dos_calloc _dos_setblock

dos_set_ctrl_break

Header
dos.h
Prototype
void dos_set_ctrl_break( int on_off)
Description
Turns the control break checking on or off. A non-zero value for the on_off argument turns control break checking on and a zero value turns off control break checking. This function has the same effect as the BREAK command does for the DOS command processor.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
dos_get_ctrl_break

_dos_setdate

Header
dos.h
Prototype
unsigned _dos_setdate( struct _dosdate_t *date)
Description
The _dos_setdate function uses the DOS system call 0x2B to set the current date to the date specified in the date argument. The format of the _dosdate_t structure is as follows: 

struct _dosdate_t
{
 unsigned char day;       /* day of month( 1-31) */
 unsigned char month;     /* month (1-12) */
 unsigned int year;       /* year (1980-2099) */
 unsigned char dayofweek; /* day of week (0 = Sunday) */
}
Synonym
Function: dos_setdate
Type: dos_date_t
Return Value
0 if successful. Otherwise, returns a non-zero value and sets errno to EINVAL, if the date passed was invalid.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_getdate
Example
See _dos_getdate

_dos_setdrive

Header
dos.h
Prototype
void _dos_setdrive( unsigned drive, unsigned *no_of_drives);
Description
The _dos_setdrive function uses system call 0x0E to change the currently logged drive to that requested in the drive argument. This argument is supplied as an unsigned integer where 1 refers to drive A, 2 refers to drive B, 3 refers to drive C, and so on. Argument no_of_drives is the total number of logical drives in the system.

The term logical drives refers to all block transfer devices in the system. This includes diskette (floppy disk) drives, ram disks, CD-ROM disks, and hard disks – including those that are partitioned into separate drives. A system fitted with a single diskette drive returns a value of 2 in no_of_drives. This is because a single diskette drive can be accessed as either of two logical drives, A or B.
Synonym
Function: dos_setdrive
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_getdrive
Example
/* Example for _dos_setdrive */

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

void main()
{
 unsigned numdrives;
 _dos_setdrive(1, &numdrives);
 printf("Total number of drives is:%d\n",
        numdrives);
 printf("Current drive is now a:\n");
}
Output
Total number of drives is: 32
Current drive is now a:

_dos_setfileattr

Header
dos.h
Prototype
unsigned _dos_setfileattr( const char *filepath, unsigned att)
Description
The _dos_setfileattr function gets the current file attributes of the named file and places them in the unsigned integer pointed to by att. The char pointer filepath references a standard DOS path and filename as a null terminated string. Individual file attributes can be set by logically ORing them with the appropriate masks.

The following names, defined in dos.h, can specify attributes:

Name Meaning
_A_RDONLY Read only file
_A_HIDDEN Hidden file
_A_SYSTEM System file
_A_ARCH Archive file
_A_NORMAL Normal file; can be read or written to
Synonym
Function: dos_setfileattr Modes: FA_RDONLY, FA_HIDDEN, FA_SYSTEM, FA_ARCH, FA_NORMAL
Return Value
0 if successful, Otherwise, returns the DOS error code and sets errno to EACCESS or ENOENT.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_getfileattr
Example
See _dos_getfileattr

_dos_setftime

Header
dos.h
Prototype
unsigned _dos_setftime( int fd, unsigned date, unsigned time);
Description
The _dos_setftime function uses system call 0x57 to set the time and date of the file attatched to the file descriptor fd to those specified in the arguments date and time. The format of these arguments is shown below:

date:
bits 0 to 4 day of month (1-31)
bits 5 to 8 month (1-12)
bits 9 to 15 year (relative to 1980)
time:
bits 0 to 4 number of 2-second increments (0-29)
bits 5 to 10 minutes (0-59)
bits 11 to 15 hours (0-23)
Synonym
Function: dos_setftime
Return Value
0 if successful. Otherwise returns the DOS error code and sets errno to EBADF, indicating the file descriptor was invalid.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_getftime
Example
See _dos_getftime

_dos_settime

Header
dos.h
Prototype
unsigned _dos_settime( struct _dostime_t *time);
Description
The _dos_settime function uses system call 0x2D to set the current system time to the values passed in the structure pointed to by time.

The format of the time structure is: 

struct _dostime_t
{
 unsigned char hour;            /* hours (0-23) */
 unsigned char minute;          /* minutes (0-59) */
 unsigned char second;          /* seconds (0-59) */
 unsigned char hsecond;         /* seconds/ 100 (0-99)*/
}
Synonym
Function: dos_settime
Type: dos_time_t
Return Value
0 if successful. If an invalid time is passed, returns the DOS error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_gettime
Example
See _dos_gettime

_dos_setvect

Header
dos.h
Prototype
void _dos_setvect( unsigned intnum, void (__interrupt __far *handler)());
Description
The _dos_setvect function uses DOS system call 0x25 to set the current value of the target interrupt vector intnum to a handler routine pointed to by handler. When a subsequent interrupt (intnum) is generated, the handler routine is called. If handler is a C routine, it must first be declared with the __interrupt attribute. To replace an interrupt vector, see the _dos_getvect function.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_chain_intr _dos_getvect _dos_keep

dos_set_verify

Header
dos.h
Prototype
void dos_set_verify(int on_off);
Description
Sets automatic read-after-write verification on (1) or off (0). this functions has the same effect as the MS-DOS commands VERIFY ON and VERIFY OFF.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
dos_get_verify

_dos_write

Header
dos.h
Prototype
unsigned _dos_write( int handle, const void __far *buffer, unsigned count, unsigned *numwrt);
Description
The _dos_write function uses system call 0x40 to write data to a file. The handle argument specifies the file to write to, the buffer argument points to the data to write, the count argument indicates the number of bytes to write, and the numwrt indicates the number of bytes that were actually written.
Return Value
Returns 0 if successful. Otherwise, the function returns the DOS error code and sets errno to EACCESS (access denied) or EBADF (invalid file handle).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dos_read
Example
See dos_commit

_x386_coreleft

Header
dos.h
Prototype
unsigned _x386_coreleft(void);
Description
This function returns the largest memory block that are allocated using functions such as malloc or calloc. If Virtual Memory is in use, _x386_coreleft checks free disk space and adjusts free memory, allowing for changes in free disk space caused by adding or deleting files on the drive containing the swap file.

This function is implemented for the X memory model only.
Return Value
The size of the largest contiguous block of memory.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
calloc
malloc
_x386_free_protected_ptr

_x386_free_protected_ptr

Header
dos.h
Prototype
int _x386_free_protected_ptr(void __far *fptr);
Description
This function is implemented for the X memory model only. It frees a protected mode far pointer that has been previously allocated with _x386_mk_protected_ptr. A maximum of 8 protected mode pointers can exist at any time, unused.
Return Value
Returns 0. If unsuccessful, no action is taken and -1 is returned.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_x386_mk_protected_ptr

_x386_get_abs_address

Header
dos.h
Prototype
unsigned long _x386_get_abs_address(void __far *address);
Description
This function, implemented for the X memory model only, returns a 32-bit address relative to zero with a protected mode segment selector and a 32-bit offset for inputs. Use it to find the starting address of DGROUP as follows:

dgroup_address = _x386_get_abs_address ((void *) getDS());
Return Value
A 32-bit protected mode address relative to zero.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_x386_map_physical_address

_x386_map_physical_address

Header
dos.h
Prototype
void *_x386_map_physical_address(void *abs_addr, unsigned size);
Description
This function maps specific physical addresses. The abs_addr argument specifies the start address of the physical memory to map. The size argument indicates the size of the region, in bytes. The function is implemented for the X memory model only.

Typically, you use this function to access memory mapped I/ O devices. The region to be mapped must be completely above or completely below the 1MB boundary; it cannot lap over the boundary itself. The function will fail and return -1 if memory is insufficient or if the DPMI host refuses service. X-32 must allocate a minimum of 4 KB for each _x386_map_physical_address call.
Return Value
A near pointer that can be used to access the actual physical address requested. The device will not be accessible at the actual physical address; it will appear to be at the address returned by this function.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_x386_get_abs_address

_x386_memlock

Header
dos.h
Prototype
int _x386_memlock(void *__far pointer, unsigned int length);
Description
This function locks a region of memory in a virtual memory environment. Argument pointer points to the region of memory to lock; argument length is the size of the region, in bytes. This function is implemented for X memory model only.

On systems where virtual memory is enabled, use this function to lock all code, data, and stack accessed by hardware interrupt handlers, or INT 1BH, 23H, OR 24H handlers. This function can be called with or without a Virtual Memory manager; the function returns successfully if no Virtual Memory manager is present.
Return Value
If successful, 0 is returned. If unsuccessful, -1 is returned.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_x386_memunlock

_x386_memunlock

Header
dos.h
Prototype
int _x386_memunlock(void __far *pointer, unsigned int length);
Description
Unlocks a region of memory in a virtual memory environment. The pointer argument points to the region of memory to lock; the length argument is the size of the region, in bytes. This function can be called at any time, but it is only effective when a Virtual Memory manager is running.

This function is implemented for the X memory model only.
Return Value
If successful, 0 is returned. If unsuccessful, -1 is returned.
Compatibility
DOSX
See Also
_x386_memlock

_x386_mk_protected_ptr

Header
dos.h
Prototype
void __far *_x386_mk_protected_ptr(unsigned long abs_addr);
Description
This function is implemented for the X memory model only. With this function, the absolute address is given and the function returns a protected mode far pointer that can be used to access the memory at abs_addr. A maximum of 8 protected mode pointers can exist at any time. Unused, although previously allocated, pointers can be freed with _x386_free_protected_ptr.
Return Value
A protected mode far pointer.
Compatibility
DOSX
See Also
_x386_free_protected_ptr
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums