The File device provides access to the file system. It provides a way to: read, write, copy, move, symlink, or delete files or directories execute external commands

;file
.macro file._path_s           $30
.macro file.type              $32
.macro file.size_w            $33
.macro file.result_w          $35
.macro file.length_w          $37
.macro file._buffer           $39
.macro file.operation         $3B
.macro file.offset            $3C

=== [2][RW] _path_s The address of the string corresponding to the name or path to the file or directory to access. If the operation to perform is copy, move, or symlink, the path must be comprised by the source and destination paths, separated by |. === [1][RW] type The type of the file being accessed. It can be set to one of the following values: $00 - not accessible $01 - file $02 - directory === [2][RO] size_w The size of the file being processed (zero for directories). Files larger than 64KB will still show up as 64KB in size. === [2][RO] result_w Depending on the operation, this indicates: the number of bytes read/written (read, write, append, copy) non-zero if the operation succeeded (delete, move, symlink, splice) the return value of the executed command (execute) Note that this is not used by the seek or splice operations, as their outcome is reflected by the offset register and by whether an error was raised or not. === [2][RW] length_w For most operations, this is length of the buffer used by that particular operation in bytes. Depending on the case, it can be a read or write buffer. For the splice operation, this is instead the number of bytes to remove from the file starting at offset. === [2][RW] _buffer The address of the area of memory where data will be read or written, depending on the operation (up to file.length bytes). If the file being accessed is a directory, its content will be listed on separate lines, in the following format: <type> <size> <name> e.g. 01 003B test1.txt 01 0234 test2.txt 02 0000 example Where: Type indicates either a file (01) or a directory (02). Size is the size (up to 64KiB) of the file in bytes, in hexadecimal format. Name is the name of the file. If the operation is set to execute, if this register and length are set, stdout and stderr will be captured in this buffer instead of being printed to the screen. When creating a directory, this register must be set to $00. For the splice operation, the buffer holds the null-terminated replacement text (it cannot contain embedded null bytes), or $0000 to delete the selected bytes without inserting anything. === [1][RW] operation The operation to perform on the specified file. If an error occurs, it will be written to the system.error address, starting with 3 as high nibble. $01 - read $02 - write $03 - append $04 - delete $05 - copy $06 - move $07 - symlink $08 - execute $09 - splice $0A - seek Note that : operations on directories require file.type set to $02 copy and delete only work on empty directories splice only works on regular files, and only supports files of up to 0xFFFE bytes (one less than the maximum reported by size), both before and after the operation. === [2][RW] offset The current position of the file device's streaming cursor, used by read, write, and append. Writing to this register (or setting operation to seek) moves the cursor there, provided that file.path is already set (path must be written first, since writing it resets offset back to $0000) and the value doesn't exceed the file current size (a missing file counts as size $0000; directories are rejected). Out-of-range offsets raise an error and leave the register unchanged from the last valid position. The register is kept in sync automatically: it advances after every read, write, or append (append always ends up at the end of the file, regardless of the offset previously set), and it is reset to $0000 whenever a path is written or a splice completes successfully. Seeking then writing on a path that was last opened for append will overwrite at the requested offset instead of appending. For splice, offset is the start byte of the range being replaced, not a streaming position; it is not required to be pre-seeked and is not advanced by the operation.