Libs-dev/libio

Right now, libio provides API to only work with files (although other communication types like pipes were also planned initially)

By default, library is compiled to use OEM file names. Support for Unicode file names is also present but requires include file to be changed and library to be recompiled.

In most cases, libio follows POSIX function prototypes. POSIX equivalents are specified for each function, where applicable.

Functions (enumerating files)

file_find_first

Find first file with matching attributes and mask in specified directory.

Prototype:

proc file.find_first _dir, _mask, _attr

Arguments:

_dir → asciiz

directory path to search in

_mask → asciiz

file mask, with use of wildcards (a.k.a. shell patterns)

_attr → dword

file attributes mask (combination of FA_* constants)

Result:

eax → FileInfo*

0 (error) / matched file data pointer (acts as find descriptor)

file_find_next

Find next file matching criteria.

Prototype:

proc file.find_next _findd

Arguments:

_findd → FileInfo*

find descriptor (see file_find_first)

Result:

eax → FileInfo*

0 (error) / matched file data pointer (acts as find descriptor)

file_find_close

Close find descriptor and free memory.

Prototype:

proc file.find_close _findd

Arguments:

_findd → FileInfo*

find descriptor (see file_find_first)

Result:

eax → dword

result of memory freeing routine

Functions (working with specific file)

file_size

Get file size.

Prototype:

proc file.size _name

Arguments:

_name → asciiz

path to file (full or relative)

Result:

ebx (attention: ebx, not eax) → dword

-1 (error) / file size (in bytes, up to 2G)

Notes:

call file_err to obtain extended error information

file_open

Open file.

Prototype:

proc file.open _name, _mode

Arguments:

_name → asciiz

path to file (full or relative)

_mode → dword

mode to open file in (combination of O_* constants)

Result:

eax → InternalFileInfo*

0 (error) / file descriptor

Notes:

call file_err to obtain extended error information

POSIX equivalent:

FILE *result = fopen(_name, _mode);

file_read

Read data from file.

Prototype:

proc file.read _filed, _buf, _buflen

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

_buf → byte*

buffer to put read data to

_buflen → dword

buffer size (number of bytes to be read from file)

Result:

eax → dword

-1 (error) / number of bytes read

Notes:

call file_err to obtain extended error information

POSIX equivalent:

size_t result = fread(_buf, _buflen, 1, _filed);

file_write

Write data to file.

Prototype:

proc file.write _filed, _buf, _buflen

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

_buf → byte*

buffer to get write data from

_buflen → dword

buffer size (number of bytes to be written to file)

Result:

eax → dword

-1 (error) / number of bytes written

Notes:

call file_err to obtain extended error information

POSIX equivalent:

size_t result = fwrite(_buf, _buflen, 1, _filed);

file_seek

Set file pointer position.

Prototype:

proc file.seek _filed, _where, _origin

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

_where → dword

position in file (in bytes) counted from specified origin

_origin → dword

origin from where to set the position (one of SEEK_* constants)

Result:

eax → dword

-1 (error) / 0

Notes:

call file_err to obtain extended error information

POSIX equivalent:

int result = fseek(_filed, _where, _origin);

file_iseof

Determine if file pointer is at the end of file.

Prototype:

proc file.eof? _filed

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

Result:

eax → dword

false / true

Notes:

call file_err to obtain extended error information

POSIX equivalent:

int result = feof(_filed);

file_truncate (file_seteof)

Truncate file size to current file pointer position:

Prototype:

proc file.truncate _filed

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

Result:

eax → dword

-1 (error) / 0

Notes:

call file_err to obtain extended error information

POSIX equivalent:

int result = ftruncate(fileno(_filed), ftell(_filed));

file_tell

Get current file pointer position.

Prototype:

proc file.tell _filed

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

Result:

eax → dword

-1 (error) / file pointer position

Notes:

call file_err to obtain extended error information

POSIX equivalent:

long result = ftell(_filed);

file_close

Close file.

Prototype:

proc file.close _filed

Arguments:

_filed → InternalFileInfo*

file descriptor (see file_open)

Result:

eax → dword

-1 (error) / 0

Notes:

call file_err to obtain extended error information

POSIX equivalent:

int result = fclose(_filed);

file_err

Not yet implemented. It was planned to give an extended information about errors that occur.

Constants

File open mode

O_BINARY = 00000000b
O_READ   = 00000001b
O_WRITE  = 00000010b
O_CREATE = 00000100b
O_SHARE  = 00001000b
O_TEXT   = 00010000b

Detailed description:

O_BINARY

don't change read/written data in any way (default)

O_READ

open file for reading

O_WRITE

open file for writing

O_CREATE

create file if it doesn't exist, open otherwise

O_SHARE

allow simultaneous access by using different file descriptors (not implemented)

O_TEXT

replace newline chars with LF (overrides O_BINARY, not implemented)

File seek origin

SEEK_SET = 0
SEEK_CUR = 1
SEEK_END = 2

Detailed description:

SEEK_SET

from beginning of file

SEEK_CUR

from current pointer position

SEEK_END

from end of file

File attributes

FA_READONLY = 00000001b
FA_HIDDEN   = 00000010b
FA_SYSTEM   = 00000100b
FA_LABEL    = 00001000b
FA_FOLDER   = 00010000b
FA_ARCHIVED = 00100000b
FA_ANY      = 00111111b

Detailed description:

FA_READONLY

file is read-only (write forbidden)

FA_HIDDEN

file or directory is hidden (should generally not be visible by user)

FA_SYSTEM

file or directory contains valuable operating system data

FA_LABEL

not a file, name holds disk label

FA_FOLDER

not a file, but directory

FA_ARCHIVED

file is archived (deprecated, system-specific use)

FA_ANY

any of above attributes (used when specifying mask)

Structures

FileDateTime

Date and time as returned by underlying system calls.

struct FileDateTime
  union
    time    dd ?
    struct
      sec   db ?
      min   db ?
      hour  db ?
    ends
  ends
  union
    date    dd ?
    struct
      day   db ?
      month db ?
      year  dw ?
    ends
  ends
ends

FileInfoBlock

File information block used by underlying system calls to identify function to be called and its basic arguments. Should generally not be used by programs.

struct FileInfoBlock
  Function   dd ?
  Position   dd ?
  Flags      dd ?
  Count      dd ?
  Buffer     dd ?
             db ?
  FileName   dd ?
ends

FileInfoHeader

File information header as returned by underlying call to 70.1 system function. Should generally not be used by programs.

struct FileInfoHeader
  Version    dd ?
  FilesRead  dd ?
  FilesCount dd ?
             rd 5
ends

FileInfoA

OEM version of FileInfo structure.

struct FileInfoA
  Attributes   dd ?
  Flags        dd ?
  DateCreate   FileDateTime
  DateAccess   FileDateTime
  DateModify   FileDateTime
  union
    FileSize   dq ?
    struct
      FileSizeLow  dd ?
      FileSizeHigh dd ?
    ends
  ends
  FileName     rb 264
ends

FileInfoW

Unicode version of FileInfo structure.

struct FileInfoW
  Attributes   dd ?
  Flags        dd ?
  DateCreate   FileDateTime
  DateAccess   FileDateTime
  DateModify   FileDateTime
  union
    FileSize   dq ?
    struct
      FileSizeLow  dd ?
      FileSizeHigh dd ?
    ends
  ends
  FileName     rw 260
ends

Usage examples

Small piece of code illustrating file opening, reading 256 bytes, seeking to the beginning, writing same data back and closing file descriptor. Note that we could succeessfully read less than 256 bytes, so we remember the exact number. Note also that we use "invoke" here since the call is indirect.

include 'libio/libio.inc'

; ...

        invoke  file_open, filename, O_READ + O_WRITE
        or      eax, eax
        jz      .error

        mov     [fdesc], eax
 
        invoke  file_read, eax, buffer, 256
        mov     [bytes_read], eax
        inc     eax
        jz      .close

        invoke  file_seek, [fdesc], 0, SEEK_SET
        inc     eax
        jz      .close

        invoke  file_write, [fdesc], buffer, [bytes_read]

  .close:
        invoke  file_close, [fdesc]
 
  .error:

; ...

filename   db '/hd0/1/a.dat', 0
fdesc      dd ?
bytes_read dd ?
buffer     db 256 dup(?)

Same code written in C could look like (just for the reference):

    FILE *f = file_open("/hd0/1/a.dat", O_READ | O_WRITE);
    if (f)
    {
        do
        {
            char buffer[256];
            size_t bytes_read = file_read(f, buffer, sizeof(buffer));
            if (bytes_read == -1)
            {
                break;
            }
            if (file_seek(f, 0, SEEK_SET) == -1)
            {
                break;
            }
            file_write(f, buffer, bytes_read);
        }
        while (0);
        file_close(f);
    }