Libs-dev/libio

From KolibriOS wiki
Revision as of 05:45, 23 July 2010 by Mike.dld (talk | contribs) (Fixed anchors)
Jump to navigation Jump to 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.

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
directory path to search in <asciiz>
_mask
file mask, with use of wildcards <asciiz>
_attr
file attributes mask (combination of FA_* constants) <dword>

Result:

eax
0 (error) / matched file data pointer (acts as find descriptor) <FileInfo*>

file_find_next

Find next file matching criteria.

Prototype:

proc file.find_next _findd

Arguments:

_findd
find descriptor (see file_find_first) <FileInfo*>

Result:

eax
0 (error) / matched file data pointer (acts as find descriptor) <FileInfo*>

file_find_close

Close find descriptor and free memory.

Prototype:

proc file.find_close _findd

Arguments:

_findd
find descriptor (see file_find_first) <FileInfo*>

Result:

eax
result of memory freeing routine

Functions (working with specific file)

file_size

Get file size.

Prototype:

proc file.size _name

Arguments:

_name
path to file (full or relative) <asciiz>

Result:

eax
-1 (error) / file size (in bytes, up to 2G) <dword>

Notes:

call file_err to obtain extended error information

file_open

Open file.

Prototype:

proc file.open _name, _mode

Arguments:

_name
path to file (full or relative) <asciiz>
_mode
mode to open file in (combination of O_* constants) <dword>

Result:

eax
0 (error) / file descriptor <InternalFileInfo*>

Notes:

call file_err to obtain extended error information

file_read

Read data from file.

Prototype:

proc file.read _filed, _buf, _buflen

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>
_buf
buffer to put read data to <byte*>
_buflen
buffer size (number of bytes to be read from file) <dword>

Result:

eax
-1 (error) / number of bytes read <dword>

Notes:

call file_err to obtain extended error information

file_write

Write data to file.

Prototype:

proc file.write _filed, _buf, _buflen

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>
_buf
buffer to get write data from <byte*>
_buflen
buffer size (number of bytes to be written to file) <dword>

Result:

eax
-1 (error) / number of bytes written <dword>

Notes:

call file_err to obtain extended error information

file_seek

Set file pointer position.

Prototype:

proc file.seek _filed, _where, _origin

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>
_where
position in file (in bytes) counted from specified origin <dword>
_origin
origin from where to set the position (one of SEEK_* constants) <dword>

Result:

eax
-1 (error) / 0 <dword>

Notes:

call file_err to obtain extended error information

file_iseof

Determine if file pointer is at the end of file.

Prototype:

proc file.eof? _filed

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>

Result:

eax
false / true <dword>

Notes:

call file_err to obtain extended error information

file_truncate (file_seteof)

Truncate file size to current file pointer position:

Prototype:

proc file.truncate _filed

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>

Result:

eax
-1 (error) / 0 <dword>

Notes:

call file_err to obtain extended error information

file_tell

Get current file pointer position.

Prototype:

proc file.tell _filed

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>

Result:

eax
-1 (error) / file pointer position <dword>

Notes:

call file_err to obtain extended error information

file_close

Close file.

Prototype:

proc file.close _filed

Arguments:

_filed
file descriptor (see file_open) <InternalFileInfo*>

Result:

eax
-1 (error) / file pointer position <dword>

Notes:

call file_err to obtain extended error information

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

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 252
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. 

include 'libio/libio.inc'

; ...

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

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

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

        stdcall file_write, [fdesc], buffer, [bytes_read]

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

; ...

filename   db '/hd0/1/a.dat', 0
fdesc      dd ?
bytes_read dd ?
buffer     db 256 dup(?)
Retrieved from "http://wiki.kolibrios.org/index.php?title=Libs-dev/libio&oldid=2924"