Libs-dev/libio

From KolibriOS wiki
Jump to: navigation, search

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

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:

eaxFileInfo*
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:

_finddFileInfo*
find descriptor (see file_find_first)

Result:

eaxFileInfo*
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:

_finddFileInfo*
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:

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);

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.

  1. include 'libio/libio.inc'
  2.  
  3. ; ...
  4.  
  5.         invoke  file_open, filename, O_READ + O_WRITE
  6.         or      eax, eax
  7.         jz      .error
  8.  
  9.         mov     [fdesc], eax
  10.  
  11.         invoke  file_read, eax, buffer, 256
  12.         mov     [bytes_read], eax
  13.         inc     eax
  14.         jz      .close
  15.  
  16.         invoke  file_seek, [fdesc], 0, SEEK_SET
  17.         inc     eax
  18.         jz      .close
  19.  
  20.         invoke  file_write, [fdesc], buffer, [bytes_read]
  21.  
  22.   .close:
  23.         invoke  file_close, [fdesc]
  24.  
  25.   .error:
  26.  
  27. ; ...
  28.  
  29. filename   db '/hd0/1/a.dat', 0
  30. fdesc      dd ?
  31. bytes_read dd ?
  32. buffer     db 256 dup(?)

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

  1.     FILE *f = file_open("/hd0/1/a.dat", O_READ | O_WRITE);
  2.     if (f)
  3.     {
  4.         do
  5.         {
  6.             char buffer[256];
  7.             size_t bytes_read = file_read(f, buffer, sizeof(buffer));
  8.             if (bytes_read == -1)
  9.             {
  10.                 break;
  11.             }
  12.             if (file_seek(f, 0, SEEK_SET) == -1)
  13.             {
  14.                 break;
  15.             }
  16.             file_write(f, buffer, bytes_read);
  17.         }
  18.         while (0);
  19.         file_close(f);
  20.     }