Libs-dev/libio/ru

В настоящий момент, libio предоставляет API только для работы с файлами, однако другие типы взаимодействия (например, шины) также есть в планах.

По умолчанию, библиотека комплируется с поддержкой имён файлов в OEM кодировке. Поддержка имён файлов в Unicode присутствует, однако требует изменения включаемого файла и пересборки библиотеки.

В большинстве случаев, libio следует прототипам функций POSIX. Для каждой функции, где это возможно, указан её POSIX эквивалент.

Функции (перебор файлов)

file_find_first

Найти первый файл с соответствующими атрибутами и маской в указанной директории.

Прототип:

proc file.find_first _dir, _mask, _attr

Агрументы:

_dir → asciiz

директория, в которой нужно производить поиск

_mask → asciiz

маска файла, с использованием шаблонных символов

_attr → dword

маска атрибутов файла (комбинация констант FA_*)

Результат:

eax → FileInfo*

0 (ошибка) / указатель на структуру с информацией о найденном файле (используется как дескриптор поиска)

file_find_next

Найти следующий файл, соответствующий критериям.

Прототип:

proc file.find_next _findd

Аргументы:

_findd → FileInfo*

дескриптор поиска (см. file_find_first)

Результат:

eax → FileInfo*

0 (ошибка) / указатель на структуру с информацией о найденном файле (используется как дескриптор поиска)

file_find_close

Закрыть дескриптор поиска и освободить память.

Прототип:

proc file.find_close _findd

Аргументы:

_findd → FileInfo*

дескриптор поиска (см. file_find_first)

Результат:

eax → dword

код возврата функции освобождения памяти

Функции (работа с отдельным файлом)

file_size

Получить размер файла.

Прототип:

proc file.size _name

Аргументы:

_name → asciiz

путь к файлу (абсолютный или относительный)

Результат:

eax → dword

-1 (ошибка) / размер файла (в байтах, до 2 гигабайт)

Замечания:

используйте file_err для получения расширенной информации об ошибке

file_open

Открыть файл.

Прототип:

proc file.open _name, _mode

Аргументы:

_name → asciiz

путь к файлу (абсолютный или относительный)

_mode → dword

режим работы с файлом (сомбинация констант O_*)

Результат:

eax → InternalFileInfo*

0 (ошибка) / дескриптор файла

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

FILE *result = fopen(_name, _mode);

file_read

Прочитать данные из файла.

Прототип:

proc file.read _filed, _buf, _buflen

Аргументы:

_filed → InternalFileInfo*

дескриптор файла (см. file_open)

_buf → byte*

буфер для размещения прочитанных данных

_buflen → dword

размер буфера (количество байт, которое необходимо прочитать)

Результат:

eax → dword

-1 (ошибка) / количество прочитанных байт

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

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

file_write

Записать данные в файл.

Прототип:

proc file.write _filed, _buf, _buflen

Аргументы:

_filed → InternalFileInfo*

дескриптор файла (см. file_open)

_buf → byte*

буфер с данными для записи

_buflen → dword

размер буфера (количество байт, которое необходимо записать)

Результат:

eax → dword

-1 (ошибка) / количество записанных байт

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

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

file_seek

Установить позицию файлового указателя.

Прототип:

proc file.seek _filed, _where, _origin

Аргументы:

_filed → InternalFileInfo*

дескриптор файла (см. file_open)

_where → dword

смещение в файле (в байтах) начиная от указанного исходного места

_origin → dword

исходное место, от которого рассчитывается позиция (одна из констант SEEK_*)

Результат:

eax → dword

-1 (ошибка) / 0

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

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

file_iseof

Определить, находится ли файловый указатель в конце файла.

Прототип:

proc file.eof? _filed

Аргументы:

_filed → InternalFileInfo*

дескриптор файла (см. file_open)

Результат:

eax → dword

ложь / истина

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

int result = feof(_filed);

file_truncate (file_seteof)

Установить размер файла в текущее значение позиции файлового указателя.

Прототип:

proc file.truncate _filed

Аргументы:

_filed → InternalFileInfo*

дескриптор файла (см. file_open)

Результат:

eax → dword

-1 (ошибка) / 0

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

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

file_tell

Получить текущее значение позиции файлового указателя.

Прототип:

proc file.tell _filed

Аргументы:

_filed → InternalFileInfo*

дескриптор файоа (см. file_open)

Результат:

eax → dword

-1 (ошибка) / позиция файлового указателя

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

long result = ftell(_filed);

file_close

Закрыть файл.

Прототип:

proc file.close _filed

Аргументы:

_filed → InternalFileInfo*

дескриптор файла (см. file_open)

Результат:

eax → dword

-1 (ошибка) / 0

Замечания:

используйте file_err для получения расширенной информации об ошибке

POSIX эквивалент:

int result = fclose(_filed);

Константы

Режим открытия файла

<source> O_BINARY = 00000000b O_READ = 00000001b O_WRITE = 00000010b O_CREATE = 00000100b O_SHARE = 00001000b O_TEXT = 00010000b </source>

Детальное описание:

O_BINARY

ни коим образом не изменять читаемые/записываемые данные (по умолчанию)

O_READ

открыть файл для чтения

O_WRITE

открыть файл для записи

O_CREATE

создать файл, если его не существует; иначе, открыть уже существующий

O_SHARE

разрещить параллельный доступ в файлу, используя разные дескрипторы (не реализовано)

O_TEXT

заменять символы конфа строки на LF (замещает O_BINARY, не реализовано)

Исходное место перемещения по файлу

<source> SEEK_SET = 0 SEEK_CUR = 1 SEEK_END = 2 </source>

Детальное описание:

SEEK_SET

от начала файла

SEEK_CUR

от текущего положения файлового указателя

SEEK_END

от конца файла

Атрибуты файла

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

Детальное описание:

FA_READONLY

файл только для чтения (запись запрещена)

FA_HIDDEN

файл или директория скрыты (обычно, не видим для пользователя)

FA_SYSTEM

файл или директория содержат важные данные операционной системы

FA_LABEL

не файл, имя содержит метку диска

FA_FOLDER

не файл, но директория

FA_ARCHIVED

архивный файл (устаревший флаг, используется системой)

FA_ANY

любой из перечисленных атрибутов (используется для увазания маски)

Структуры

FileDateTime

Дата и время в формате, возвращаемом системными вызовами.

<source> 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 </source>

FileInfoBlock

Дескриптор, используемый системными вызовами для идентификации вызываемой функции и её базовых аргументов. Обычно не должна использоваться в программах напрямую.

<source> struct FileInfoBlock

 Function   dd ?
 Position   dd ?
 Flags      dd ?
 Count      dd ?
 Buffer     dd ?
            db ?
 FileName   dd ?

ends </source>

FileInfoHeader

Дескриптор списка файлов, возвращаемый как результат вызова системной функции 70.1. Обычно не должна использоваться в программах напрямую.

<source> struct FileInfoHeader

 Version    dd ?
 FilesRead  dd ?
 FilesCount dd ?
            rd 5

ends </source>

FileInfoA

OEM версия структуры FileInfo (блока данных входа каталога).

<source> 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 </source>

FileInfoW

Unicode версия структуры FileInfo (блока данных входа каталога).

<source> 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 </source>

Примеры использования

Небольшой кусок кода, иллюстрирующий открытие файла, чтение 256 байт, перемещения указателя в начало файла, запись прочитанных данных и закрытие дескриптора файла. Заметьте, что может быть успешно прочитано менее 256 байт, поэтому мы запоминаем точное число. Заметьте также, что мы используем "invoke", так как вызов функции — косвенный.

<source line> 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(?) </source>

Тот же самый код на языке C может выглядеть так (для сравнения):

<source lang="c" line>

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

</source>