cesky: 
,
English: 
FILE
Files
Litos8 supports FAT12 and FAT16 file systems. Devices and directories can be accessed in the same way as files, i.e. sequence read and write. Therefore, when using file function, heightened caution is needed to avoid unwanted writes to directory, disk or memory.
Device names:
Device names need to be terminated by a colon ":". The size of the letters in the device name does not matter. Directories can be used only on system disks (A: .. P:). E.g. "C:\" opens root directory of the C: disk.
The path to the file can be specified either absolute (e.g. "C:\TEST\List.txt") or relative to the current directory. In relative syntax, "." character specifies current directory, ".." specifies parent directory. The size of letters in names of files and directories does not matter. As path separator can be used both "/" and "\" characters, however, the system preferably uses "\" character (according to DOS conventions).
In file and directory names can be used wilcards "*" (=asterisk, any set of characters) and "?" (=any one character). File name can have 1 to 8 character. Separation point may be followed by the 0 to 3 character extension. Wildcards can be used in the path or while opening the file - in this case, the first matching entry will be used.
Unlike DOS system, one global current directory is used for all disks. Therefore, entering a disk in path presets the root directory of the disk ("C:test.txt" specification has the same meaning as "C:\test.txt").
Beware of differences: "HD1:" opens physical disk 80h (including its master boot sector), "C:" opens system disk on its first partition (starting at boot sector of the partition), "C:\" will open root directory of C: disk, "C:\TEST" opens directory TEST on C: disk, "C:\TEST\List.txt" opens file in directory C:\TEST. Whether it is a device, directory or file, you can test it by attributes DIR_Device and DIR_DIR in descriptor of open file.
In system there is no treatment to multiple access to the file (e.g. locking file access) or later write to the disk. After writting to the file, you must close the file (or empty it by using FlushFile) to write changes in the directory entry to the disk. Number of opened files is not limited. Opening a file only fills up information about file in user's FILE descriptor, no further records about files does not exist in the system.
GetCurPath - get current path
OUTPUT:
BX = pointer to CTEXT with current path
SetCurPath - set current path
INPUT:
BX = pointer to TEXT with new current path
OUTPUT:
CY = error
AbsPath - absolutize path
INPUT:
BX = pointer to TEXT with relative path
OUTPUT:
AX = new TEXT with absolute path (without ending "\",
uppercase)
CY = error (AX = 0 on error)
OpenFile - open file
INPUT:
BX = TEXT file name (with path)
DI = pointer to destination FILE structure
OUTPUT:
CY = error, file not found
CreateFileDir - create and open file or directory
INPUT:
BX = TEXT filename (with path)
DL = attributes (incl. DIR_DIR)
DI = pointer to destination FILE structure
OUTPUT:
CY = error
CreateFile - create and open file
INPUT:
BX = TEXT filename (with path)
DI = pointer to destination FILE structures
OUTPUT:
CY = error
CreateDir - create directory
INPUT:
BX = TEXT dir name (with path)
OUTPUT:
CY = error
DeleteFileDir - delete file or directory
INPUT:
BX = TEXT filename (with path)
DL = required attributes
DH = mask of attributes
OUTPUT:
CY = error
DeleteFile - delete file
INPUT:
BX = TEXT file name (with path)
OUTPUT:
CY = error or file is R/O.
DeleteDir - delete directory
INPUT:
BX = TEXT directory name (with path)
OUTPUT:
CY = error, directory is R/O or it is not empty.
RenameFileDir - rename file or directory (in place)
INPUT:
BX = TEXT file name (with path)
AX = TEXT file new name (without path, can contain ? and *)
OUTPUT:
CY = error (new name cannot be with path)
MoveFile - move file
INPUT:
BX = TEXT file name (with path)
AX = TEXT file new name (with path, cannot contain ? or *)
OUTPUT:
CY = error (cannot move to another disk)
ReadFile - read from file
INPUT:
DI = pointer to FILE structure (must be open)
SI = destination buffer
CX = number of bytes
OUTPUT:
CY = error
CX = successfully readed bytes
WriteFile - write to file
INPUT:
DI = pointer to FILE structure (must be open)
SI = source buffer
CX = number of bytes
OUTPUT:
CY = error
CX = successfully written bytes
FlushFile - flush file (write directory entry if needed)
INPUT:
DI = pointer to FILE structure (must be open)
OUTPUT:
CY = error
CloseFile - close file
INPUT:
DI = pointer to FILE structure (must be open)
OUTPUT:
CY = error
OpenDir - open directory
INPUT:
BX = TEXT file name (with path)
DI = pointer to destination FILE structure
OUTPUT:
CY = error, file not found
FindFiles - search files or directories
INPUT:
BX = TEXT filename (with path)
DL = required attributes (incl. DIR_THISDIR and DIR_UPDIR)
DH = mask of attributes (incl. DIR_THISDIR and DIR_UPDIR)
DI = array of FILE structures (NULL = only get number of files)
BP = max. number of files (0 = no limit)
OUTPUT:
CY = error, file not found or some error
BP = number of files
NOTES: Deleted entry is found only if mask starts with FATDELCHAR.
FileExist - check if file or directory exists
INPUT:
BX = TEXT directory name (with path)
OUTPUT:
CY = error, file not found
AX = number of files
FileAttr - get file attributes from FILE structure
INPUT:
DI = pointer to FILE structure
OUTPUT:
AL = file attributes (including DIR_THISDIR and DIR_UPDIR)
GetFileAttr - get file attributes
INPUT:
BX = TEXT file or directory name (with path)
OUTPUT:
CY = error, file not found (AL = 0)
AL = file attributes (incl.DIR_THISDIR and DIR_UPDIR,0 on err.)
SetFileAttr - set file attributes
INPUT:
BX = TEXT file or directory name (with path)
AL = new file attributes (cannot change DIR attribute)
OUTPUT:
CY = error
FileSize - get file size from FILE structure
INPUT:
DI = pointer to FILE structure
OUTPUT:
DX:AX = file size
NOTES: Does not modify flags.
GetFileSize - get file size
INPUT:
BX = TEXT file or directory name (with path)
OUTPUT:
CY = error, file not found (DX:AX = 0)
DX:AX = file size (0 on error)
SetFileSize - set file size
INPUT:
DI = pointer to FILE structure
DX:AX = new file size
OUTPUT:
CY = error
NOTES: Does not initialize content of new clusters. Directory size only growths, not decreases.
FileDateTime - get file date and time from FILE structure
INPUT:
DI = pointer to FILE structure
OUTPUT:
AL = second (0..58, can be 0..62, only even second)
CL = minute (0..59, can be 0..63)
CH = hour (0..23, can be 0..31)
DL = day (1..31, can be 0..31)
DH = month (1..12, can be 0..15)
SI = year (1980..2117)
GetFileDateTime - get file date and time
INPUT:
BX = TEXT file or directory name (with path)
OUTPUT:
CY = error, file not found (all entries = 0)
AL = second (0..58, can be 0..62, only even second)
CL = minute (0..59, can be 0..63)
CH = hour (0..23, can be 0..31)
DL = day (1..31, can be 0..31)
DH = month (1..12, can be 0..15)
SI = year (1980..2117)
SetFileDateTime - set file date and time
INPUT:
BX = TEXT file or directory name (with path)
AL = second (0..58, can be 0..62, only even second)
CL = minute (0..59, can be 0..63)
CH = hour (0..23, can be 0..31)
DL = day (1..31, can be 0..31)
DH = month (1..12, can be 0..15)
SI = year (1980..2117)
OUTPUT:
CY = error
FilePos - get file seek position
INPUT:
DI = pointer to FILE structure
OUTPUT:
DX:AX = offset in file (0 on error)
CY = error (DX:AX = 0)
FileSeek - set file seek position
INPUT:
DX:AX = offset in file or in device (0 on error)
DI = pointer to FILE structure
CL = seek mode (SEEK_BEG, SEEK_CUR, SEEK_END)
OUTPUT:
CY = error
NOTES: Can seek behind end of file.
FileSetPos - set file seek position from begin
INPUT:
DX:AX = offset in file or in device from begin (0 on error)
DI = pointer to FILE structure
OUTPUT:
CY = error
NOTES: Can seek behind end of file.
FileReset - reset file position to begin
INPUT:
DI = pointer to FILE structure
OUTPUT:
CY = error
AddFileName - add filename from FILE structure
INPUT:
SI = pointer to FILE structure
BX = destination TEXT (filename will be
added after old text)
OUTPUT:
BX = old or new pointer to TEXT structure
CY = memory error
OpenRoot - open root directory
INPUT:
AL = system disk (0..)
DI = pointer to destination FILE structure
OUTPUT: CY = error
ClearFileDesc - clear FILE descriptor
INPUT:
DI = pointer to FILE structure
GetClustSect - get first absolute sector of cluster
INPUT:
AX = cluster (0=root)
BX = pointer to SDD descriptor
OUTPUT:
DX:AX = absolute sector
PrepFileMask - prepare filename mask
INPUT:
CX = filename length
SI = filename
DI = file mask buffer (length 11 bytes: 8 name + 3 extension)
OUTPUT:
CY = mask contains "?" characters
FileSDD - get SDD descriptor from FILE structure
INPUT:
DI = pointer to FILE structure
OUTPUT:
BX = pointer to SDD descriptor (or
NULL on CY error)
CY = error, invalid disk number (returns BX = NULL)
GetNextClust - get next FAT entry
INPUT:
AX = current cluster
BX = pointer to SDD descriptor
OUTPUT:
AX = new cluster (-1 = end of file)
CY = error (AX undefined)
SetNextClust - set next FAT entry
INPUT:
AX = next cluster (use FAT16 constants)
DX = current cluster
BX = pointer to SDD descriptor
OUTPUT:
CY = error
NOTES: FlushFAT need to be called after FAT operations.
FindFreeClust - find free cluster
INPUT:
BX = pointer to SDD descriptor
OUTPUT:
AX = free cluster
CY = error (AX undefined)
NOTES: Searching from LastFreeClust position.
SetLastFree - set last free cluster
INPUT:
AX = last free cluster (2..)
BX = pointer to SDD descriptor
NOTES: Used by FindFreeClust function.
ReadFAT - read FAT sector into cache
INPUT:
AX = relative FAT sector
BX = pointer to SDD descriptor
OUTPUT:
SI = sector buffer SectBuf
CY = read error
NOTES: FAT buffer will be flushed if other FAT sector is needed.
WriteFAT - write FAT sector from cache
INPUT:
BX = pointer to SDD descriptor
OUTPUT:
CY = write error (all FAT copies are invalid)
NOTES: FlushFAT should be called after all writes.
FlushFAT - write FAT sector, if it was modified
INPUT:
BX = pointer to SDD descriptor
OUTPUT:
CY = write error (all FAT copies are invalid)
DiskFree - get free space on disk
INPUT:
AL = disk number (0..)
OUTPUT:
DX:AX = free space on disk (in bytes, 0 on error)
BX:CX = used space on disk (in bytes, 0 on error)
CY = error (DX:AX, BX:CX = 0 on error)
PATHCHAR: (="\") path separator
PATHCHAR2: (="/") alternative path separator
PATHMAX: (=260) max. length of current path
FATDELCHAR: (=0e5h) delete character
SEEK_BEG: (=0) seek from start of file
SEEK_CUR: (=1) seek from current position
SEEK_END: (=2) seek from end
DIR_Name: (8 bytes) filename
DIR_Ext: (3 bytes) extension
DIR_Attr: (byte) attributes (see below)
DIR_Res: (10 bytes) ...reserved
DIR_Time: (word) last write time
DIR_Date: (word) last write date
DIR_Cluster: (word) start cluster
DIR_Size: (dword) file size
directory special mark (first byte of filename):
DIR_FREE: (=0) free entry
DIR_ERASE: (=0e5h) erased entry
DIR_RO: (=B0) Read-Only
DIR_HID: (=B1) Hidden
DIR_SYS: (=B2) System
DIR_VOL: (=B3) Volume Label
DIR_DIR: (=B4) Directory
DIR_ARC: (=B5) Archive
DIR_Mask: (=B0+B1+B2+B3+B4+B5) mask of valid attributes
DIR_Device: (=B6) system internal - device
DIR_Dirty: (=B7) system internal - file is dirty
DIR_THISDIR: (=B6) search files - this directory "."
DIR_UPDIR: (=B7) search files - upper directory ".."
FILE descriptor (compatible with DIR entry):
FILE_Name: (8 bytes) filename
("\"=root, " "=closed) or device name
(without ":")
FILE_Ext: (3 bytes) extension
FILE_Attr: (byte) attributes and flags (incl. DIR_Device,
DIR_Dirty)
FILE_DirDW:
FILE_DirL: (word) sector with directory entry LOW
FILE_DirH: (byte) sector with directory entry HIGH
FILE_DirInx: (byte) dir entry in sector and disk;
- file: bit 0..3: index of entry in dir, bit 4..7: system disk
0..15;
- device: bit 0..3: device type (0=SYS) (bit 3: 1=char device),
bit 4..7: device index 0..15
FILE_ClustDisk: (word) current abs. cluster on disk, 0 = device
or root, -1 = unknown
FILE_Off: (dword, union with FILE_ClustOff and FILE_ClustFile)
block device or root: current offset
FILE_ClustOff: (word) current offset in cluster
FILE_ClustFile: (word) current rel. cluster in file
FILE_Time: (word) last write time
FILE_Date: (word) last write date
FILE_Cluster: (word) start cluster (0=root)
FILE_Size: (dword) file size
