Libs-dev: Difference between revisions

From KolibriOS wiki
Jump to navigation Jump to search
mNo edit summary
(Separate libio subpage)
Line 6: Line 6:


==libio==
==libio==
Right now, libio provides API to only work with files, although other communication types (like pipes) are also planned.
''Main article: [[Libs-dev/libio]]''
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:
:<tt>proc file.find_first _dir, _mask, _attr</tt>
 
Arguments:
:<tt>_dir</tt>
::directory path to search in <asciiz>
:<tt>_mask</tt>
::file mask, with use of wildcards <asciiz>
:<tt>_attr</tt>
::file attributes mask (combination of FA_* constants) <dword>
 
Result:
:<tt>eax</tt>
::0 (error) / matched file data pointer (acts as find descriptor) <[[#FileInfoA|FileInfo]]*>
 
====file_find_next====
Find next file matching criteria.
 
Prototype:
:<tt>proc file.find_next _findd</tt>
 
Arguments:
:<tt>_findd</tt>
::find descriptor (see [[#file_find_first|file_find_first]]) <[[#FileInfoA|FileInfo]]*>
 
Result:
:<tt>eax</tt>
::0 (error) / matched file data pointer (acts as find descriptor) <[[#FileInfoA|FileInfo]]*>
 
====file_find_close====
Close find descriptor and free memory.
 
Prototype:
:<tt>proc file.find_close _findd</tt>
 
Arguments:
:<tt>_findd</tt>
::find descriptor (see [[#file_find_first|file_find_first]]) <[[#FileInfoA|FileInfo]]*>
 
Result:
:<tt>eax</tt>
::result of memory freeing routine
 
===functions (working with specific file)===
 
====file_size====
Get file size.
 
Prototype:
:<tt>proc file.size _name</tt>
 
Arguments:
:<tt>_name</tt>
::path to file (full or relative) <asciiz>
 
Result:
:<tt>eax</tt>
::-1 (error) / file size (in bytes, up to 2G) <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_open====
Open file.
 
Prototype:
:<tt>proc file.open _name, _mode</tt>
 
Arguments:
:<tt>_name</tt>
::path to file (full or relative) <asciiz>
:<tt>_mode</tt>
::mode to open file in (combination of [[#file_open_mode|O_* constants]]) <dword>
 
Result:
:<tt>eax</tt>
::0 (error) / file descriptor <InternalFileInfo*>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_read====
Read data from file.
 
Prototype:
:<tt>proc file.read _filed, _buf, _buflen</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
:<tt>_buf</tt>
::buffer to put read data to <byte*>
:<tt>_buflen</tt>
::buffer size (number of bytes to be read from file) <dword>
 
Result:
:<tt>eax</tt>
::-1 (error) / number of bytes read <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_write====
Write data to file.
 
Prototype:
:<tt>proc file.write _filed, _buf, _buflen</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
:<tt>_buf</tt>
::buffer to get write data from <byte*>
:<tt>_buflen</tt>
::buffer size (number of bytes to be written to file) <dword>
 
Result:
:<tt>eax</tt>
::-1 (error) / number of bytes written <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_seek====
Set file pointer position.
 
Prototype:
:<tt>proc file.seek _filed, _where, _origin</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
:<tt>_where</tt>
::position in file (in bytes) counted from specified origin <dword>
:<tt>_origin</tt>
::origin from where to set the position (one of [[#file_seek_origin|SEEK_* constants]]) <dword>
 
Result:
:<tt>eax</tt>
::-1 (error) / 0 <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_iseof====
Determine if file pointer is at the end of file.
 
Prototype:
:<tt>proc file.eof? _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::false / true <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_truncate (file_seteof)====
Truncate file size to current file pointer position:
 
Prototype:
:<tt>proc file.truncate _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::-1 (error) / 0 <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_tell====
Get current file pointer position.
 
Prototype:
:<tt>proc file.tell _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::-1 (error) / file pointer position <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_close====
Close file.
 
Prototype:
:<tt>proc file.close _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::-1 (error) / file pointer position <dword>
 
Notes:
:call [[#file_err|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:
:<tt>O_BINARY</tt>
::don't change read/written data in any way (default)
:<tt>O_READ</tt>
::open file for reading
:<tt>O_WRITE</tt>
::open file for writing
:<tt>O_CREATE</tt>
::create file if it doesn't exist, open otherwise
:<tt>O_SHARE</tt>
::allow simultaneous access by using different file descriptors (not implemented)
:<tt>O_TEXT</tt>
::replace newline chars with LF (overrides O_BINARY, not implemented)
 
====file seek origin====
SEEK_SET = 0
SEEK_CUR = 1
SEEK_END = 2
 
Detailed description:
:<tt>SEEK_SET</tt>
::from beginning of file
:<tt>SEEK_CUR</tt>
::from current pointer position
:<tt>SEEK_END</tt>
::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 [[SysFn70|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|FileDateTime]]
  DateAccess  [[#FileDateTime|FileDateTime]]
  DateModify  [[#FileDateTime|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|FileDateTime]]
  DateAccess  [[#FileDateTime|FileDateTime]]
  DateModify  [[#FileDateTime|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.
 
<source>
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(?)
</source>


==libini==
==libini==

Revision as of 05:41, 23 July 2010

Introduction

Libs-dev is a system libraries collection targeting different problematic programming areas.

Libraries description

Libs-dev now consists of four common-use libraries: libio (input-output programming), libini (INI-like files support), libimg (graphics files manipulation) and libgfx (drawing convenience API).

libio

Main article: Libs-dev/libio

libini

libimg

libgfx

Libraries tests

There's a .test directory containing different libraries tests. They are designed to be independent and should generate (or contain pre-generated) test data which leads to same results disregarding the order tests are executed in.

Coding style

All the public functions are contained in <library name>.asm file, supporting public declarations in <library name>.inc file. All other library-specific (private and auxilary) core functions and declarations are separated into <library name>_p.asm and <library name>_p.inc files. There could also be separate files with self-describing names providing additional functionality.

Functions located in public source files use naming concention as in <function namespace name>.<function name>. Functions located in private source files use naming convention as in <library name>._.<function name>. This allows to separate libraries code when linking statically.

Specific type of function description comments is being used allowing documentation to be generated automatically in the future.

Retrieved from "http://wiki.kolibrios.org/index.php?title=Libs-dev&oldid=2922"