API.HTM

DOCUMENTATION

================================

API

LibreDOS's syscalls are on interrupt 80h. The function numbers here are in Decimal.

FUNCTION 0 & 1: - Exit application
EAX = 0 or 1
DESCRIPTION: Exits the application and returns control to the CLI.

FUNCTION 2: - Print String
EAX = 2
ESI = Pointer to a null terminated string.
DESCRIPTION: Prints the string in ESI.

FUNCTION 3: - Read from file.
EAX = 3
EBX = File handle
ECX = Pointer to buffer for reading file data.
EDX = Number of bytes to read from the file.
DESCRIPTION: Reads the specified number of bytes into the data buffer. Stdin has not been implimented here yet.
RETURNS: EAX contains the number of bytes read, or else -1 on error.

FUNCTION 4: - Write to file.
EAX = 4
EBX = File handle
ECX = Pointer to buffer holding the file data to be written.
EDX = Number of bytes to write to the file.
DESCRIPTION: Writes the specified number of bytes from the data buffer to file. If you wish to write to the stdout or stderr, just use a filehandle of 2 or less.
RETURNS: Nothing returned.

FUNCTION 5: - Open existing file.
EAX = 5
EBX = Pointer to null terminated filename/
DESCRIPTION: Opens a file that already exists in the filesystem.
RETURNS: Returns 0 if the file isn't found.

FUNCTION 6: - Close file.
EAX = 6
EBX = File Handle
DESCRIPTION: Closes a file.
RETURNS: Nothing.

FUNCTION 8: - Create new file.
EAX = 8
EBX = Pointer to null terminated filename.
DESCRIPTION: Creates a new file and returns a file handle.
RETURNS: EAX contains the new file handle.

FUNCTION 10: - Erases a file.
EAX = 10
EBX = Pointer to null terminated filename.
DESCRIPTION: Erases a file from the file system.
RETURNS: Nothing.

FUNCTION 11: - Executes a new program.
EAX = 11
ESI = Pointer to null terminated filename.
EDI = Pointer to null terminated command line parameters.
DESCRIPTION: Launches a new program, and blocks till the new program has finished running.
RETURNS: Nothing.

FUNCTION 12: - Allocate memory.
EAX = 12
DESCRIPTION: Allocates a 1mb section of RAM and returns an address for immediate usage. An application can start immediatly using the memory with ESI and EDI.
RETURNS: EAX contains the address of the block.

FUNCTION 13: - Free memory.
EAX = 13
EBX = Address of memory block previously allocated with function 12. DESCRIPTION: Frees up a 1mb block for reallocation. Be sure to use this before exiting an application, or the memory will be permanently allocated.
RETURNS: Nothing.

FUNCTION 19: - File seek.
EAX = 19
EBX = File handle
ECX = File position
EDX = Mode - 0 is absolute position, 1 is offset from start of file, 2 is offset from end.
DESCRIPTION: Repositions the file pointer in the specified file.
RETURNS: EAX contains the new position of the file pointer.

FUNCTION 20: - Read byte from file.
EAX = 20
EBX = File handle
DESCRIPTION: Reads exactly one byte from file.
RETURNS: EAX contains the byte, or -1 on error or eof.

FUNCTION 21: - Write byte to file.
EAX = 21
EBX = File handle
ECX = Byte to write to the file.
DESCRIPTION: Writes exactly one byte to a file.
RETURNS: Nothing.

FUNCTION 22: - Find first file or directory in current directory.
EAX = 22
EDI = A 28 byte buffer to hold the file structure.
DESCRIPTION: Finds the first file in the current directory and fills a 28 byte data structure. File attributes are 0 for regular file, 16 for directory, and (-1) if there are no files to be found.
The structure is as follows:
11 byte filename
9 bytes of padding for future use
4 bytes for file attributes
4 bytes for the file size
RETURNS: Nothing.

FUNCTION 23: - Find next file or directory in current directory.
EAX = 23
EDI = A 28 byte buffer to hold the file structure.
DESCRIPTION: Finds the first file in the current directory and fills a 28 byte data structure. File attributes are 0 for regular file, 16 for directory, and (-1) if there are no files to be found.
The structure is as follows:
11 byte filename
9 bytes of padding for future use
4 bytes for file attributes
4 bytes for the file size

FUNCTION 32: - Get command parameters.
EAX = 32
EDI = A buffer to hold the command parameters.
DESCRIPTION: This will copy the command line used to open an application to the buffer.
RETURNS: Nothing.
WARNING: Be careful to allocated a large enough buffer for the options you think a user may pass to your program.

FUNCTION 33: - Install interrupt handler.
EAX = 33
EBX = Interrupt number.
ECX = A pointer to your new handler.
DESCRIPTION: This installs an interrupt handler for a user program, ie. drivers.
RETURNS: Nothing.
EXAMPLE: Driver Example

FUNCTION 34: - Install irq handler.
EAX = 34
EBX = IRQ number.
ECX = A pointer to your new handler.
DESCRIPTION: This installs an irq handler for a user program, ie. drivers.
RETURNS: Nothing.
EXAMPLE: See Function 33, the procedure is the same.

FUNCTION 35: - Unmask an irq.
EAX = 35
EBX = The irq to be unmasked.
DESCRIPTION: Unmask an irq.
RETURNS: Nothing.

FUNCTION 36: - Mask an irq.
EAX = 36
EBX = The irq to be masked.
DESCRIPTION: Mask an irq.
RETURNS: Nothing.

FUNCTION 84: - Print a single character.
EAX = 84
EBX = The ascii code of the character.
DESCRIPTION: Prints a single character to the screen.
RETURNS: Nothing.

FUNCTION 86: - Get a key.
EAX = 86
DESCRIPTION: Gets a key from the keyboard buffer. See function 87.
RETURNS: EAX contains the ASCII of the key, EBX contains the scancode.

FUNCTION 87: - Check for key.
EAX = 87
DESCRIPTION: Checks to see if there is a key waiting in the keyboard buffer.
RETURNS: EAX is 1 if there is a key, 0 otherwise.

FUNCTION 89: - Returns a files base memory.
EAX = 89
EBX = File handle
DESCRIPTION: This returns the memory location of a loaded file to be used with EDI and ESI.
RETURNS: EAX contains the memory block of the file.

FUNCTION 96: - Clear screen.
EAX = 96
DESCRIPTION: Completely clears the console screen.
RETURNS: Nothing.

FUNCTION 97: - Set vga video mode.
EAX = 97
EBX = desired mode
DESCRIPTION: changes the vga video mode using vm86.
RETURNS: Nothing.

FUNCTION 98: - Returns data selector.
EAX = 98
DESCRIPTION: Returns your program's data selector.
RETURNS: EAX contains the selector.

FUNCTION 99: - Set operating drive.
EAX = 99
EBX = drive 0 for A, 1 for boot partition, 0x80 for C.
DESCRIPTION: Changes the operating drive specified in EBX.
RETURNS: Nothing.

FUNCTION 100: - Get operating drive.
EAX = 100
DESCRIPTION: Returns the current drive.
RETURNS: EAX = current drive.

FUNCTION 101: - Load absolute sector.
EAX = 101
EBX = Sector
EDI = Buffer to hold the sector data.
DESCRIPTION: Loads an LBA sector to the buffer.
RETURNS: Nothing.

FUNCTION 102: - Save absolute sector.
EAX = 102
EBX = Sector
ESI = Buffer that holds the sector data.
DESCRIPTION: Saves an LBA sector to disk.
RETURNS: Nothing.

FUNCTION 103: - Get relative application base.
EAX = 103
DESCRIPTION: This returns the relative base where your application has been loaded. You can then use this data to determine the location of an absolute address in memory, ie. the video memory. This is often used for vert2phys and phys2vert routines.
RETURNS: EAX contains the address.

FUNCTION 104: - Create directory.
EAX = 104
ESI = pointer to null terminated directory name.
DESCRIPTION: Creates a new directory.
RETURNS: Nothing.

FUNCTION 105: - Change directory.
EAX = 105
ESI = pointer to null terminated directory name.
DESCRIPTION: Changes to a new directory.
RETURNS: Nothing.

FUNCTION 106: - Get current directory.
EAX = 106
EDI = pointer to buffer to hold the directory name including full path.
DESCRIPTION: Get the working directory with full path.
RETURNS: Nothing.

FUNCTION 112: - Get mouse data.
EAX = 112
EBX = 1 for mouse button, 2 for mouse x, 3 for mouse y
DESCRIPTION: Returns the data requested from EBX.
RETURNS: EAX contains the button or position.

FUNCTION 113: - Exit with Keep.
EAX = 113
DESCRIPTION: Exits your application but does not release it from memory. This is usefull for drivers and is similar to the DOS keep function.
RETURNS: Nothing.

FUNCTION 114: - Get file attributes.
EAX = 114
ESI = Null terminated filename
DESCRIPTION: Returns the attributes for a file specified in esi.
RETURNS: EAX contains the attributes. 0 is a regular file, 16 is a directory, -1 is returned if the file doesn't exist.

FUNCTION 115: - Rename file
EAX = 115
EBX = Null terminated filename
ECX = Null terminated NEW filename
DESCRIPTION: Renames a file.
RETURNS: Nothing

FUNCTION 116: - Erase Directory
EAX = 116
ESI = Null terminated filename
DESCRIPTION: Deletes a directory. The directory must be empty.
RETURNS: EAX = 0 if successful, or -1 if error

FUNCTION 117: - Opendir
EAX = 117
ESI = Pointer to empty File Descriptor Block
DESCRIPTION: Opens a directory entry and stores the struct to where ESI points.
RETURNS: EAX = 0 if successful, -1 if error

FUNCTION 118: - Readdir
EAX = 118
ESI = Pointer to File Descriptor Block which was initializad with Function 117
DESCRIPTION: Reads the next directory entry into the File Descriptor Block.
RETURNS: EAX = 0 if successful, -1 if error

FUNCTION 119: - Stat
EAX = 119
ESI = Pointer to File Descriptor Block
DESCRIPTION: Stat init function for File Descriptor Block
RETURNS: EAX = 0 if successful, -1 if error

FUNCTION 120: - fstat
EAX = 120
ESI = Pointer to initialized File Descriptor Block (Function 119)
DESCRIPTION: Stats file info the initialized File Desciptor Block
RETURNS: EAX = 0 if successful, -1 if error

FUNCTION 121: - Parse command
EAX = 121
ESI = Pointer to command
DESCRIPTION: Parses command line in ESI
RETURNS: EAX = 0 if successful, -1 if error

FUNCTION 122: - Init Vesa
EAX = 122
DESCRIPTION: Inits to 640x480x256 VESA mode. This was originally intended as a GUI function, but remains for possible future development. *May also be removed in the future.
RETURNS: Nothing.

FUNCTION 123: - Set video ram address
EAX = 123
EBX = Video ram address (not absolute, see function 103)
DESCRIPTION: Sets video ram address. Useful for buffering text ram.
RETURNS: Nothing

FUNCTION 124: - Get BIOS time
EAX = 124
DESCRIPTION: Returns BIOS time
RETURNS: EAX = BIOS time

FUNCTION 125: - Get BIOS ticks
EAX = 125
DESCRIPTION: Returns BIOS ticks since midnight
RETURNS: EAX = ticks

=========================================

More functions will be added in the future. If you've noticed any errors please let us know in the forums.

(c)2022 - Kumpute Nation. All rights reserved.