Subversion Repositories Kolibri OS

Compare Revisions

Regard whitespace Rev 6797 → Rev 6798

/kernel/trunk/docs/sysfuncr.txt
1695,7 → 1695,6
======================================================================
================ Функция 30 - работа с текущей папкой. ===============
======================================================================
 
-------- Подфункция 1 - установить текущую папку для потока. ---------
Параметры:
* eax = 30 - номер функции
1704,7 → 1703,7
правила формирования строки указаны в описании функции 70.
Возвращаемое значение:
* функция не возвращает значения
 
----------------------------------------------------------------------
--------- Подфункция 2 - получить текущую папку для потока. ----------
Параметры:
* eax = 30 - номер функции
1712,27 → 1711,21
* ecx = указатель на буфер
* edx = размер буфера
Возвращаемое значение:
* eax = длина имени текущей папки (включая завершающий 0)
* eax = длина строки (включая завершающий 0)
Замечания:
* Если размера буфера недостаточно для копирования всего имени,
копируются только первые (edx-1) байт и в конце ставится
завершающий 0.
* Если размера буфера недостаточно для копирования всего пути,
копируются только часть строки и в конце ставится завершающий 0.
* По умолчанию, текущая папка для потока - "/rd/1".
* При создании процесса/потока текущая папка наследуется от
родителя.
 
----------------------------------------------------------------------
---- Подфункция 3 - установить доп. системную директорию для ядра ----
Параметры:
* eax = 30 - номер функции
* ebx = 3 - номер подфункции
* ecx = указатель на блок данных:
для кодировки cp866:
key rb 64
path rb 64
для кодировки UTF-16LE:
key rb 64
dw 2
path rw 31
Пример:
align 64
key db 'kolibrios',0 ; ключ должен быть в нижнем регистре
1743,20 → 1736,29
* функция не возвращает значения
Замечания:
* Функция может быть вызвана только 1 раз за 1 сессию работы ОС.
* Кодировка не влияет на символьный ключ.
 
----- Подфункция 4 - получить текущую папку в кодировке UTF-16LE -----
* При вводе пути символьный ключ не зависит от кодировки.
----------------------------------------------------------------------
--- Подфункция 4 - установить текущую папку с указанием кодировки. ---
Параметры:
* eax = 30 - номер функции
* ebx = 4 - номер подфункции
* ecx = указатель на строку с путём к новой текущей папке
* edx = кодировка строки, подробности указаны в описании функции 80.
Возвращаемое значение:
* функция не возвращает значения
----------------------------------------------------------------------
---- Подфункция 5 - получить текущую папку с указанием кодировки. ----
Параметры:
* eax = 30 - номер функции
* ebx = 5 - номер подфункции
* ecx = указатель на буфер
* edx = размер буфера
* esi = кодировка строки
Возвращаемое значение:
* eax = количество символов в строке (включая завершающий 0)
* eax = длина строки в байтах (включая завершающий 0)
Замечания:
* Если размера буфера недостаточно для копирования всего имени,
копируются только первые (edx-2) байт и в конце ставится
завершающий 0.
* Если размера буфера недостаточно для копирования всего пути,
копируются только часть строки и в конце ставится завершающий 0.
* По умолчанию, текущая папка для потока - "/rd/1".
* При создании процесса/потока текущая папка наследуется от
родителя.
3380,13 → 3382,13
eax - SF_SYS_MISC (68)
ebx - SSF_CONTROL_DRIVER (17)
======================================================================
============= Функция 68, подфункция 19 - загрузить DLL. =============
== Функция 68, подфункция 18 - загрузить DLL с указанием кодировки. ==
======================================================================
Параметры:
* eax = 68 - номер функции
* ebx = 19 - номер подфункции
* ecx = указатель на строку с путём к DLL,
правила формирования строки указаны в описании функции 70.
* ebx = 18 - номер подфункции
* ecx = указатель на строку с путём к DLL
* edx = кодировка строки, подробности указаны в описании функции 80.
Возвращаемое значение:
* eax = 0 - неудача
* иначе eax = указатель на таблицу экспорта DLL
3395,6 → 3397,18
заканчивающийся нулём. Первый dword в структуре является
указателем на имя функции, второй содержит адрес функции.
 
======================================================================
============= Функция 68, подфункция 19 - загрузить DLL. =============
======================================================================
Параметры:
* eax = 68 - номер функции
* ebx = 19 - номер подфункции
* ecx = указатель на строку с путём к DLL,
правила формирования строки указаны в описании функции 70.
Возвращаемое значение:
* eax = 0 - неудача
* иначе eax = указатель на таблицу экспорта DLL
 
---------------------- Константы для регистров: ----------------------
eax - SF_SYS_MISC (68)
ebx - SSF_LOAD_DLL (19)
3557,7 → 3571,7
eax - SF_SYS_MISC (68)
ebx - SSF_SET_EXCEPTION_STATE (25)
======================================================================
= Функция 68, подфункция 26 - освободить страницы памяти ============
======= Функция 68, подфункция 26 - освободить страницы памяти =======
======================================================================
Параметры:
* eax = 68 - номер функции
3573,7 → 3587,7
eax - SF_SYS_MISC (68)
ebx - SSF_MEM_FREE_EXT (26)
======================================================================
= Функция 68, подфункция 27 - загрузить файл ===================
============= Функция 68, подфункция 27 - загрузить файл =============
======================================================================
Параметры:
* eax = 68 - номер функции
3590,6 → 3604,20
eax - SF_SYS_MISC (68)
ebx - SSF_LOAD_FILE (27)
======================================================================
== Функция 68, подфункция 28 - загрузить файл с указанием кодировки ==
======================================================================
Параметры:
* eax = 68 - номер функции
* ebx = 28 - номер подфункции
* ecx = указатель на строку с путём к файлу
* edx = кодировка строки, подробности указаны в описании функции 80.
Возвращаемое значение:
* eax = указатель на загруженный файл или 0
* edx = размер загруженного файла или 0
Примечания:
* функция загружает и, при необходимости, распаковывает файл (kunpack)
 
======================================================================
======================== Функция 69 - отладка. =======================
======================================================================
Процесс может загрузить другой процесс как отлаживаемый установкой
3891,9 → 3919,9
в других регистрах
Общий формат информационной структуры:
* +0: dword: номер подфункции
* +4: dword: смещение в файле
* +8: dword: старший dword смещения (должен быть 0) или поле флагов
* +12 = +0xC: dword: размер
* +4: dword: смещение в файле или папке
* +8: dword: старшая часть смещения или поле флагов
* +12 = +0xC: dword: размер данных
* +16 = +0x10: dword: указатель на данные
* +20 = +0x14: ?: текстовая строка - путь к файлу, заканчивается нулём
или
3902,7 → 3930,7
Чувствительность к регистру букв зависит от файловой системы.
Если путь начинается не с '/', то он считается относительным.
Получить или установить текущую папку можно с помощью сисфункции 30.
'../' в начале пути означает подъём на одну папку относительно текущей.
'../' в пути означает подъём на одну папку относительно текущей.
Можно указать кодировку строки, поместив в её начале байт со значениями:
* 1 = cp866
* 2 = UTF-16LE
3909,6 → 3937,7
* 3 = UTF-8
иначе будет использоваться кодировка cp866. В абсолютном пути можно
поместить этот байт после '/' или добавить дополнительный '/' перед ним.
Также, можно использовать сисфункцию 80.
Формат абсолютного пути:
/base/number/dir1/dir2/.../dirn/file,
где base/number идентифицирует устройство, на котором ищется файл:
3992,11 → 4021,12
* +0: dword: 1 = номер подфункции
* +4: dword: индекс начального блока (считая с 0)
* +8: dword: в какой кодировке возвращать имена:
0 = cp866 -> байт на символ
1 = UTF-16LE -> 2 байта на символ
0 = по умолчанию
1 = cp866
2 = UTF-16LE
3 = UTF-8
* +12 = +0xC: dword: сколько блоков читать
* +16 = +0x10: dword: указатель на буфер, куда будут записаны
данные, размер буфера должен быть не меньше 32+n(40+256*enc+8) байт
* +16 = +0x10: dword: указатель на буфер, куда будут записаны данные.
* +20 = +0x14: путь, правила формирования имён указаны в общем описании
Возвращаемое значение:
* eax = 0 - успешно, иначе код ошибки файловой системы
4029,9 → 4059,7
это может быть полезно для автоматического создания
backup-архивов, ибо при записи бит обычно устанавливается
(не в Kolibri, правда)
* +4: dword: кодировка имени:
* 0 = cp866 -> байт на символ
* 1 = UTF-16LE -> 2 байта на символ
* +4: dword: кодировка имени, соответствует полю +8 информационной структуры
* +8: 4*byte: время создания файла
* +12 = +0xC: 4*byte: дата создания файла
* +16 = +0x10: 4*byte: время последнего доступа (чтение или запись)
4039,7 → 4067,7
* +24 = +0x18: 4*byte: время последней модификации
* +28 = +0x1C: 4*byte: дата последней модификации
* +32 = +0x20: qword: размер файла в байтах (до 16777216 Тб)
* +40 = +0x28: (256*enc+8)*byte: имя
* +40 = +0x28: имя, размер в cp866 составляет 264 байта, иначе - 520 байт.
Формат времени:
* +0: byte: секунды
* +1: byte: минуты
4052,9 → 4080,8
* +2: word: год
* например, 25.11.1979 записывается как (в hex) 19 0B BB 07
Замечания:
* Если в БДВК присутствует имя в cp866, то длина БДВК составляет
304 байта, если в UTF-16LE - 560 байт. Значение длины выравнено
на целое кратное 16 байт для ускорения обработки в кэш-памяти CPU.
* Если БДВК содержит имя в cp866, то длина БДВК составляет
304 байта, иначе - 560 байт.
* Строка имени заканчивается нулём, дальнейшие данные содержат мусор.
* Если файлы в папке кончились раньше, чем было прочитано
запрошенное количество, то функция прочитает, сколько сможет,
4835,6 → 4862,31
---------------------- Константы для регистров: ----------------------
eax - SF_TERMINATE_PROCESS (-1)
======================================================================
=== Функция 80 - работа с файловой системой с указанием кодировки. ===
======================================================================
Параметры:
* eax = 80
* ebx = указатель на информационную структуру
Возвращаемое значение:
* eax = 0 - успешно; иначе код ошибки файловой системы
* в зависимости от подфункции может возвращаться значение и
в других регистрах
Общий формат информационной структуры:
* +0: dword: номер подфункции
* +4: dword: смещение в файле или папке
* +8: dword: старшая часть смещения или поле флагов
* +12 = +0xC: dword: размер данных
* +16 = +0x10: dword: указатель на данные
* +20 = +0x14: dword: кодировка строки:
1 = cp866
2 = UTF-16LE
3 = UTF-8
0 = по умолчанию (поддерживает байт кодировки в начале строки)
* +24 = +0x18: dword: указатель на строку пути (заканчивается нулём)
 
В остальном полностью соответствует функции 70.
 
======================================================================
=========================== Список событий ===========================
======================================================================
Очередное событие можно получить вызовом одной из функций 10
/kernel/trunk/docs/sysfuncs.txt
1677,7 → 1677,6
======================================================================
============= Function 30 - work with the current folder. ============
======================================================================
 
--------- Subfunction 1 - set current folder for the thread. ---------
Parameters:
* eax = 30 - function number
1686,7 → 1685,7
rules of path forming can be found in function 70 description.
Returned value:
* function does not return value
 
----------------------------------------------------------------------
--------- Subfunction 2 - get current folder for the thread. ---------
Parameters:
* eax = 30 - function number
1694,26 → 1693,21
* ecx = pointer to buffer
* edx = size of buffer
Returned value:
* eax = size of the current folder's name (including terminating 0)
* eax = size of the string (including terminating 0)
Remarks:
* If the buffer is too small to hold all data, only first (edx-1)
bytes are copied and than terminating 0 is inserted.
* If the buffer is too small to hold all path, only part of the string
will be copied and terminated with 0.
* By default, current folder for the thread is "/rd/1".
* At process/thread creation the current folder will be inherited
from the parent.
 
----------------------------------------------------------------------
--- Subfunction 3 - install the add.system directory for the kernel --
Parameters:
* eax = 30 - function number
* ebx = 3 - subfunction number
* ecx = pointer to a block of data:
for cp866 encoding:
key rb 64
path rb 64
for UTF-16LE encoding:
key rb 64
dw 2
path rw 31
Example:
align 64
key db 'kolibrios',0 ; key must be in lower case
1724,19 → 1718,29
* function does not return value
Remarks:
* The function can be called only 1 time for 1 session of the OS.
* The key is not affected by encoding.
 
------ Subfunction 4 - get current folder in UTF-16LE encoding. ------
* On input the symbolic key is not changing by encoding.
----------------------------------------------------------------------
---- Subfunction 4 - set current folder, specifying the encoding. ----
Parameters:
* eax = 30 - function number
* ebx = 4 - subfunction number
* ecx = pointer to string with the path to new current folder
* edx = string encoding, details can be found in function 80 description.
Returned value:
* function does not return value
----------------------------------------------------------------------
---- Subfunction 5 - get current folder, specifying the encoding. ----
Parameters:
* eax = 30 - function number
* ebx = 5 - subfunction number
* ecx = pointer to buffer
* edx = size of buffer
* esi = string encoding
Returned value:
* eax = number of chars in the buffer (including terminating 0)
* eax = size of the string in bytes (including terminating 0)
Remarks:
* If the buffer is too small to hold all data, only first (edx-2)
bytes are copied and than terminating 0 is inserted.
* If the buffer is too small to hold all path, only part of the string
will be copied and terminated with 0.
* By default, current folder for the thread is "/rd/1".
* At process/thread creation the current folder will be inherited
from the parent.
3343,13 → 3347,13
eax - SF_SYS_MISC (68)
ebx - SSF_CONTROL_DRIVER (17)
======================================================================
=============== Function 68, subfunction 19 - load DLL. ==============
== Function 68, subfunction 18 - load DLL, specifying the encoding. ==
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 19 - subfunction number
* ecx = pointer to the string with path to DLL,
rules of path forming can be found in function 70 description.
* ebx = 18 - subfunction number
* ecx = pointer to the string with path to DLL
* edx = string encoding, details can be found in function 80 description.
Returned value:
* eax = 0 - failed
* otherwise eax = pointer to DLL export table
3358,6 → 3362,18
by zero. The first dword in structure points to function name,
the second dword contains address of function.
 
======================================================================
=============== Function 68, subfunction 19 - load DLL. ==============
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 19 - subfunction number
* ecx = pointer to the string with path to DLL,
rules of path forming can be found in function 70 description.
Returned value:
* eax = 0 - failed
* otherwise eax = pointer to DLL export table
 
---------------------- Constants for registers: ----------------------
eax - SF_SYS_MISC (68)
ebx - SSF_LOAD_DLL (19)
3552,6 → 3568,20
eax - SF_SYS_MISC (68)
ebx - SSF_LOAD_FILE (27)
======================================================================
== Function 68, subfunction 28 - load file, specifying the encoding ==
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 28 - subfunction number
* ecx = pointer to the string with path to file
* edx = string encoding, details can be found in function 80 description.
Returned value:
* eax = pointer to the loaded file, or zero
* edx = size of the loaded file, or zero
Remarks:
* function loads file and unpacks, if necessary
 
======================================================================
====================== Function 69 - debugging. ======================
======================================================================
A process can load other process as debugged by set of corresponding
3847,9 → 3877,9
* some subfunctions return value in other registers too
General format of the information structure:
* +0: dword: subfunction number
* +4: dword: file offset
* +8: dword: high dword of offset (must be 0) or flags field
* +12 = +0xC: dword: size
* +4: dword: offset in file or folder
* +8: dword: higher part of offset or flags
* +12 = +0xC: dword: size of data
* +16 = +0x10: dword: pointer to data
* +20 = +0x14: ?: path - zero terminated string
or
3857,8 → 3887,8
* +21 = +0x15: dword: pointer to string
Case sensitivity depends on filesystem.
If a path not begins with '/', it is considered a relative.
To get or set the current folder, use the function 30.
'../' in the beginning means a lift by one folder relatively current folder.
To get or set the current folder, use the sysfunction 30.
'../' in the path means a lift by one folder relatively current folder.
To set the encoding, put at the start of the string a byte with next values:
* 1 = cp866
* 2 = UTF-16LE
3865,6 → 3895,7
* 3 = UTF-8
otherwise will be used cp866. In an absolute path
you may put this byte after the '/' or put an additional '/' before it.
Also, you may use the sysfunction 80.
Format of an absolute path:
/base/number/dir1/dir2/.../dirn/file,
where base/number identifies device, on which file is located:
3945,12 → 3976,13
Format of the information structure:
* +0: dword: 1 = subfunction number
* +4: dword: index of starting block (beginning from 0)
* +8: dword: encoding:
* 0 = cp866 -> byte per char
* 1 = UTF-16LE -> word per char
* +8: dword: names encoding:
0 = default
1 = cp866
2 = UTF-16LE
3 = UTF-8
* +12 = +0xC: dword: number of blocks to read
* +16 = +0x10: dword: pointer to buffer for data, buffer size
must be not less than 32+n(40+256*enc+8) bytes
* +16 = +0x10: dword: pointer to buffer for data
* +20 = +0x14: path, general rules of names forming
Returned value:
* eax = 0 - success, otherwise file system error code
3982,9 → 4014,7
and after archiving this bit is cleared - it can be useful
for automatically creating of backup-archives as at writing
this bit is usually set
* +4: dword: encoding:
* 0 = cp866 -> byte per char
* 1 = UTF-16LE -> word per char
* +4: dword: encoding, equals to field +8 in the information structure
* +8: 4*byte: time of file creation
* +12 = +0xC: 4*byte: date of file creation
* +16 = +0x10: 4*byte: time of last access (read or write)
3992,7 → 4022,7
* +24 = +0x18: 4*byte: time of last modification
* +28 = +0x1C: 4*byte: date of last modification
* +32 = +0x20: qword: file size in bytes (up to 16777216 Tb)
* +40 = +0x28: (256*enc+8)*byte: name
* +40 = +0x28: name, 264 bytes in cp866, otherwise - 520 bytes.
Time format:
* +0: byte: seconds
* +1: byte: minutes
4006,8 → 4036,7
* for example, 25.11.1979 is written as (in hex) 19 0B BB 07
Remarks:
* If BDFE contains cp866 name, the length of BDFE is 304 bytes,
if UTF-16LE name - 560 bytes. Value of length is aligned
on 16-byte bound to accelerate processing in CPU cache.
otherwise - 560 bytes.
* Name string is zero terminated, further data contain garbage.
* If files in folder were ended before requested number was read,
the function will read as many as it can, and after that return
5047,6 → 5076,30
eax - SF_FUTEX (77)
ebx - SSF_WAKE (3)
======================================================================
=== Function 80 - file system interface with parameter of encoding ===
======================================================================
Parameters:
* eax = 80
* ebx = pointer to the information structure
Returned value:
* eax = 0 - success; otherwise file system error code
* some subfunctions return value in other registers too
General format of the information structure:
* +0: dword: subfunction number
* +4: dword: offset in file or folder
* +8: dword: higher part of offset or flags
* +12 = +0xC: dword: size of data
* +16 = +0x10: dword: pointer to data
* +20 = +0x14: dword: string encoding:
1 = cp866
2 = UTF-16LE
3 = UTF-8
0 = default (supports encoding byte at the start of the string)
* +24 = +0x18: dword: pointer to zero terminated string with path
 
The rest is similar to sysfunction 70.
 
======================================================================
=============== Function -1 - terminate thread/process ===============
======================================================================
Parameters: