Watcom C Library Reference : dosexterr, _dos_find Functions, _dos_freemem
Watcom C Reference/D - E - F 2021. 6. 20. 19:41
Watcom C Library Reference : dosexterr, _dos_find Functions, _dos_freemem
dosexterr
Synopsis : #include <dos.h>
int dosexterr( struct DOSERROR *err_info );
struct _DOSERROR {
int exterror; /* contents of AX register */
char errclass; /* contents of BH register */
char action; /* contents of BL register */
char locus; /* contents of CH register */
};
Description : The dosexterr function extracts extended error information following a failed DOS function. This information is placed in the structure located by err_info. This function is only useful with DOS version 3.0 or later.
You should consult the technical documentation for the DOS system on your computer for an interpretation of the error information.
Returns : The function returns an unpredictable result when the preceding DOS call did not result in an error. Otherwise, the function returns the number of the extended error.
See Also : perror
Example :
#include <stdio.h>
#include <dos.h>
#include <fcntl.h>
struct _DOSERROR dos_err;
void main( )
{
int handle;
/* Try to open "stdio.h" and then close it */
if( _dos_open( "stdio.h", O_RDONLY, &handle ) != 0 ) {
dosexterr( &dos_err );
printf( "Unable to open file\n" );
printf( "exterror (AX) = %d\n", dos_err.exterror );
printf( "errclass (BH) = %d\n", dos_err.errclass );
printf( "action (BL) = %d\n", dos_err.action );
printf( "locus (CH) = %d\n", dos_err.locus );
} else {
printf( "Open succeeded\n" );
if ( _dos_close( handle ) != 0 ) {
printf( "Close failed\n");
} else {
printf( "Close succeeded\n" );
}
}
}
produces the following:
Unable to open file
exterror (AX) = 2
errclass (BH) = 8
action (BL) = 3
locus (CH) = 2
Classification : DOS
Systems : DOS, Win, DOS/PM
_dos_find Functions
Synopsis : #include <dos.h> u
unsigned _dos_findfirst( char *path, unsigned attributes, struct find_t *buffer );
unsigned _dos_findnext( struct find_t *buffer );
unsigned _dos_findclose( struct find_t *buffer );
struct find_t {
char reserved[21]; /* reserved for use by DOS */
char attrib; /* attribute byte for file */
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 */
#if defined (__OS2__) || defined (__NT__)
char name [256]; /* null-terminated filename */
#else
char name [13]; /* null-terminated filename */
#endif
};
Description : The _dos_findfirst function uses system call 0x4E to return information on the first file whose name and attributes match the path and attributes arguments. The information is returned in a find_t structure pointed to by buffer. The path argument may contain wildcard characters ('?' and '*'). The attributes argument may be any combination of the following constants:
| Attribute | Meaning |
| _A NORMAL | Indicates a normal file. File can be read or written without any restrictions. |
| _A RDONLY | Indicates a read-only file. File cannot be opened for "write". |
| _A HIDDEN | Indicates a hidden file. This file will not show up in a normal directory search. |
| _A SYSTEM | Indicates a system file. This file will not show up in a normal directory search. |
| _A_VOLID | Indicates a volume-ID. |
| _A_SUBDIR | Indicates a sub-directory |
| _A_ARCH | This is the archive flag. It is set whenever the file is modified cleared by the MS-DOS BACKUP command and other back programs. |
The attributes argument is interpreted by DOS as follows:
1. If _A_NORMAL is specified, then normal files are included in the search
2. If any of _A_HIDDEN, _A_SYSTEM, _A_SUBDIR are specified, then nor files and the specified type of files are included in the search.
3. If _A_VOLID is specified, then only volume-ID's are included in the search.
4. _A_RDONLY and _A_ARCH are ignored by this function.
The _dos_findnext function uses system call 0x4F to return information on the next file whose name and attributes match the pattern supplied to the _dos_findfirst function.
On some systems (e.g. OS/2), you must call _dos_findclose to indicate that you are done matching files. This function deallocates any resources that were allocated by the _dos_findfirst function.
Returns : The _dos_find functions return zero if successful. Otherwise, the _dos_findfirst and _dos_findnext functions return an MS-DOS error code and sets errno to ENOENT indicating that no more files matched the path and attributes arguments.
See Also : opendir, readdir, closedir
Example :
#include <stdio.h>
#include <dos.h>
void main( )
{
struct find_t fileinfo;
unsigned rc; /* return code */
/* Display name and size of "*.c" files */
rc = _dos_findfirst ( "*.c", _A_NORMAL, &fileinfo);
while( rc == 0 ) {
printf( "%14s %101d\n", fileinfo.name, fileinfo.size);
rc = _dos_findnext ( &fileinfo );
}
#if defined ( __OS2__ )
_dos_findclose( &fileinfo );
# endif
}
Classification : DOS
Systems : _dos_findclose - DOS, Win, OS/2 1.x(all), OS/2 2.x, NT, DOS/PM
_dos_findfirst - DOS, Win. OS/2 1.x(all), OS/2 2.x, NT, DOS/PM
_dos_findnext - DOS, Win, OS/2 1.x(all), OS/2 2.x, NT, DOS/PM
_dos_freemem
Synopsis : #include <dos.h>
unsigned _dos_freemem ( unsigned segment );
Description : The _dos_freemem function uses system call 0x49 to release memory that was previously allocated by _dos_allocmem. The value contained in segment is the one returned by a previous call to _dos_allocmem.
Returns : The _dos_freemem function returns zero if successful. Otherwise, it returns an MS-DOS error code and sets errno to ENOMEM indicating a bad segment value or DOS memory has been corrupted.
See Also : _dos_allocmem, _dos_setblock, free, hfree
Example :
#include <stdio.h>
#include <dos.h>
void main( )
{
unsigned short segment;
/* Try to allocate 100 paragraphs, then free them */
if( _dos_allocmem ( 100, &segment ) != 0 ) {
printf( "_dos_allocmem failed\n" );
printf( "Only %u paragraphs available\n", segment );
} else {
printf( "_dos_allocmem succeeded\n" );
if( _dos_freemem( segment ) != 0 ) {
printf( "_dos_freemem failed\n" );
} else {
printf( "_dos_freemem succeeded\n" );
}
}
}
Classification : DOS
Systems : DOS, OS/2 1.x(all), OS/2 2.x, NT, DOS/PM
This manual describes the WATCOM C library for DOS, Windows, and OS/2, It includes the Standard C Library (as defined in the ANSI C Standard).
WATCOM C Language Reference manual describes the ANSI C Programming language and extensions to it which are supported by WATCOM C/C++ (32bit)
