Модуль fio¶

Overview¶

Tarantool поддерживает файловый ввод-вывод с помощью API, который аналогичен системным вызовам POSIX. Все операции проводятся асинхронно. Несколько файберов могут получать доступ к одному файлу одновременно.

Модуль fio включает в себя:

• функции для стандартных действий с путем к файлу,
• функции для проверки наличия и типа директории или файла,
• функции для стандартных действий с файлами, а также
• постоянные., которые совпадают с флаговыми значениями POSIX (например, fio.c.flag.O_RDONLY = POSIX O_RDONLY).

Index¶

Ниже приведен перечень всех функций и элементов модуля fio.

Стандартные действия с путем к файлу¶

fio.pathjoin(partial-string[, partial-string ...])¶

Конкатенация частей строки, разделенных „/“ для формирования пути к файлу.

Параметры:	partial-string (string) – одна или более строк для конкатенации.
Return:	путь к файлу
Rtype:	string

Example:

tarantool> fio.pathjoin('/etc', 'default', 'myfile')
 ---
 - /etc/default/myfile
 ...

fio.basename(path-name[, suffix])¶

Удаление из полного пути к файлу всего, за исключением последней части (имени файла). Также удаление суффикса, если он передается.

Параметры:	path-name (string) – путь к файлу suffix (string) – суффикс
Return:	имя файла
Rtype:	string

Example:

tarantool> fio.basename('/path/to/my.lua', '.lua')
 ---
 - my
 ...

fio.dirname(path-name)¶

Удаление последней части (имени файла) из полного пути к файлу.

Параметры:	path-name (string) – путь к файлу
Return:	имя директории, то есть путь к файлу без имени файла.
Rtype:	string

Example:

tarantool> fio.dirname('path/to/my.lua')
 ---
 - 'path/to/'

fio.abspath(file-name)¶

Возврат полного пути к файлу на основании последней части (имени файла).

Параметры:	file-name (string) – имя файла
Return:	имя директории, то есть путь к файлу с именем файла.
Rtype:	string

Example:

tarantool> fio.abspath('my.lua')
 ---
 - 'path/to/my.lua'
 ...

Проверка наличия и типа директории или файла¶

Функции в данном разделе подобны некоторым функциям Python os.path.

path.exists(path-name)¶

Параметры:	path-name (string) – путь к директории или файлу.
Return:	true (правда), если путь к файлу ссылается на директорию или файл, которые присутствуют в системе, и не представляет собой нерабочую символьную ссылку; в противном случае, false (ложь)
Rtype:	boolean

path.is_dir(path-name)¶

Параметры:	path-name (string) – путь к директории или файлу.
Return:	true (правда), если путь к файлу ссылается на директорию; в противном случае, false (ложь)
Rtype:	boolean

path.is_file(path-name)¶

Параметры:	path-name (string) – путь к директории или файлу.
Return:	true (правда), если путь к файлу ссылается на файл; в противном случае, false (ложь)
Rtype:	boolean

path.is_link(path-name)¶

Параметры:	path-name (string) – путь к директории или файлу.
Return:	true (правда), если путь к файлу ссылается на символьную ссылку; в противном случае, false (ложь)
Rtype:	boolean

path.lexists(path-name)¶

Параметры:	path-name (string) – путь к директории или файлу.
Return:	true (правда), если путь к файлу ссылается на директорию или файл, которые присутствуют в системе, и представляет собой нерабочую символьную ссылку; в противном случае, false (ложь)
Rtype:	boolean

Стандартные действия с файлом¶

fio.umask(mask-bits)¶

Определение битов маски при создании файлов или директорий. Для получения более подробного описания введите man 2 umask.

Параметры:	mask-bits (number) – биты маски.
Return:	предыдущие биты маски.
Rtype:	number

Example:

tarantool> fio.umask(tonumber('755', 8))
 ---
 - 493
 ...

fio.lstat(path-name)¶

fio.stat(path-name)¶

Возврат информации об объекте файла. Для получения более подробной информации введите man 2 lstat или man 2 stat.

Параметры:	path-name (string) – путь к файлу.
Return:	(Если ошибки нет) таблица с полями, которые описывают размер блока файла, время создания, размер и прочие атрибуты. (В случае ошибки) возвращаются два значения: null, сообщение об ошибке.
Rtype:	таблица.

Кроме того, результат fio.stat('имя-файла') будет включать в себя методы, которые аналогичны макросам в POSIX:

• is_blk() = макрос S_ISBLK в POSIX,
• is_chr() = макрос S_ISCHR в POSIX
• is_dir() = макрос S_ISDIR в POSIX,
• is_fifo() = макрос S_ISFIFO в POSIX,
• is_link() = макрос S_ISLINK в POSIX,
• is_reg() = макрос S_ISREG в POSIX,
• is_sock() = макрос S_ISSOCK в POSIX.

Например, fio.stat('/'):is_dir() вернет true.

Example:

tarantool> fio.lstat('/etc')
 ---
 - inode: 1048577
   rdev: 0
   size: 12288
   atime: 1421340698
   mode: 16877
   mtime: 1424615337
   nlink: 160
   uid: 0
   blksize: 4096
   gid: 0
   ctime: 1424615337
   dev: 2049
   blocks: 24
 ...

fio.mkdir(path-name[, mode])¶

fio.rmdir(path-name)¶

Создание или удаление директории. Для получения подробной информации введите man 2 mkdir или man 2 rmdir.

Параметры:	path-name (string) – путь к директории. mode (number) – Биты режима работы можно передать в виде числа или строковых постоянных, например S_IWUSR. Биты режима работы можно комбинировать путем обрамления их в фигурные скобки.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.mkdir('/etc')
 ---
 - false
 ...

fio.chdir(path-name)¶

Изменение рабочей директории. Для получения более подробной информации введите man 2 chdir.

Параметры:	path-name (string) – путь к директории.
Return:	(Если выполнено) true. (Если не выполнено) false.
Rtype:	boolean

Example:

tarantool> fio.chdir('/etc')
          ---
          - true
          ...

fio.listdir(path-name)¶

Вывод списка файлов в директории. Результат похож на результат команды ls.

Параметры:	path-name (string) – путь к директории.
Return:	(Если ошибки нет) список файлов. (В случае ошибки) возвращаются два значения: null, сообщение об ошибке.
Rtype:	table

Example:

tarantool> fio.listdir('/usr/lib/tarantool')
 ---
 - - mysql
 ...

fio.glob(path-name)¶

Возврат списка файлов, имена которых совпадают с введенной строкой. Список составляется с одним флагом, который контролирует поведение функции: GLOB_NOESCAPE. Для получения подробной информации введите man 3 glob.

Параметры:	path-name (string) – путь к файлу, который может содержать специальные символы.
Return:	список файлов, имена которых совпадают с введенной строкой.
Rtype:	table

Возможные ошибки: nil.

Example:

tarantool> fio.glob('/etc/x*')
 ---
 - - /etc/xdg
   - /etc/xml
   - /etc/xul-ext
 ...

fio.tempdir()¶

Возврат имени директории, которую можно использовать для хранения временных файлов.

Example:

tarantool> fio.tempdir()
 ---
 - /tmp/lG31e7
 ...

fio.cwd()¶

Возврат имени текущей рабочей директории.

Example:

tarantool> fio.cwd()
 ---
 - /home/username/tarantool_sandbox
 ...

fio.copytree(from-path, to-path)¶

Копирование всего из директории from-path, включая поддиректории, в to-path. Результат аналогичен результату введения команды cp -r. Директория to-path должна быть пустой.

Параметры:	from-path (string) – путь. to-path (string) – путь.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.copytree('/home/original','/home/archives')
 ---
 - true
 ...

fio.mktree(path-name)¶

Создание пути, включая поддиректории, но без содержимого файла. Результат аналогичен результату введения команды mkdir.

Параметры:	path-name (string) – путь.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.mktree('/home/archives')
 ---
 - true
 ...

fio.rmtree(path-name)¶

Удаление указанной директории, включая поддиректории. Результат аналогичен результату введения команды rmdir. Директория должна быть пустой.

Параметры:	path-name (string) – путь.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: null, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.rmtree('/home/archives')
 ---
 - true
 ...

fio.link(src, dst)¶

fio.symlink(src, dst)¶

fio.readlink(src)¶

fio.unlink(src)¶

Функции для создания и удаления ссылок. Для получения подробной информации введите man readlink, man 2 link, man 2 symlink, man 2 unlink.

Параметры:	src (string) – имя существующего файла. dst (string) – связанное имя.
Return:	(Если ошибки нет) fio.link, fio.symlink и fio.unlink возвращают true (правда), fio.readlink возвращает ссылку. (В случае ошибки) возвращаются два значения: false|null, сообщение об ошибке.

Example:

tarantool> fio.link('/home/username/tmp.txt', '/home/username/tmp.txt2')
 ---
 - true
 ...
 tarantool> fio.unlink('/home/username/tmp.txt2')
 ---
 - true
 ...

fio.rename(path-name, new-path-name)¶

Переименование файла или директории. Для получения подробной информации введите man 2 rename.

Параметры:	path-name (string) – первоначальное имя. new-path-name (string) – новое имя.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.rename('/home/username/tmp.txt', '/home/username/tmp.txt2')
 ---
 - true
 ...

fio.utime(file-name[, accesstime[, updatetime]])¶

Change the access time and possibly also change the update time of a file. For details type man 2 utime. Times should be expressed as number of seconds since the epoch.

Параметры:	file-name (string) – name. accesstime (number) – time of last access. default current time. updatetime (number) – time of last update. default = access time.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.utime('/home/username/tmp.txt')
---
- true
...

fio.copyfile(path-name, new-path-name)¶

Копирование файла. Результат аналогичен результату введения команды cp.

Параметры:	path-name (string) – путь к первоначальному файлу. new-path-name (string) – путь к новому файлу.
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.copyfile('/home/user/tmp.txt', '/home/usern/tmp.txt2')
 ---
 - true
 ...

fio.chown(path-name, owner-user, owner-group)¶

fio.chmod(path-name, new-rights)¶

Управление правами на использование и правами владения объектами файла. Для получения подробной информации введите man 2 chown или man 2 chmod.

Параметры:	owner-user (string) – новый UID пользователя. owner-group (string) – новый UID группы. new-rights (number) – новые права
Return:	null

Example:

tarantool> fio.chmod('/home/username/tmp.txt', tonumber('0755', 8))
 ---
 - true
 ...
 tarantool> fio.chown('/home/username/tmp.txt', 'username', 'username')
 ---
 - true
 ...

fio.truncate(path-name, new-size)¶

Уменьшение размера файла до указанного значения. Для получения подробной информации введите man 2 truncate.

Параметры:	path-name (string) – new-size (number) –
Return:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
Rtype:	boolean

Example:

tarantool> fio.truncate('/home/username/tmp.txt', 99999)
 ---
 - true
 ...

fio.sync()¶

Проверка записи изменений на диск. Для получения подробной информации введите man 2 sync.

Return:	true – если выполнено, false – если не выполнено.
Rtype:	boolean

Example:

tarantool> fio.sync()
 ---
 - true
 ...

fio.open(path-name[, flags[, mode]])¶

Открытие файла в процессе подготовки к чтению, записи или поиску.

Параметры:	path-name (string) – Полный путь к открываемому файлу. flags (number) – Флаги могут передаваться в виде числа или в виде строковых постоянных, например „O_RDONLY“, „O_WRONLY“, „O_RDWR“. Флаги можно комбинировать путем обрамления их в фигурные скобки. Все флаги в Linux, как описано на странице руководства по Linux, представлены ниже: * O_APPEND (открывать файл в режиме добавления), * O_ASYNC (включать ввод-вывод, управляемый сигналом), * O_CLOEXEC (устанавливать флаг, связанный с закрытием), * O_CREAT (создать файл, если он не существует), * O_DIRECT (минимизировать или отключать кэширование), * O_DIRECTORY (завершать вызов с ошибкой, если путь не является директорией), * O_EXCL (завершать вызов с ошибкой, если файл не может быть создан), * O_LARGEFILE (открывать 64-битные файлы), * O_NOATIME (не обновлять время последнего доступа к файлу), * O_NOCTTY (не делать терминальное устройство управляющим терминалом tty), * O_NOFOLLOW (не открывать символьные ссылки), * O_NONBLOCK (открывать в неблокирующем режиме), * O_PATH (получить путь для низкоуровневого использования), * O_SYNC (включить принудительную запись, если возможно), * O_TMPFILE (создать безымянный временный файл), * O_TRUNC (урезать) … и всегда используется один из флагов: * O_RDONLY (только для чтения), * O_WRONLY (только для записи) или * O_RDWR (для чтения и записи). mode (number) – Биты режима работы можно передать в виде числа или строковых постоянных, например S_IWUSR. Биты режима работы имеют значение, если указаны флаги O_CREAT или O_TMPFILE. Биты режима работы можно комбинировать путем обрамления их в фигурные скобки.
Return:	(Если ошибки нет) дескриптор файла (далее сокращенно „fh“). (В случае ошибки) возвращаются два значения: null, сообщение об ошибке.
Rtype:	userdata

Возможные ошибки: nil.

Пример 1:

tarantool> fh = fio.open('/home/username/tmp.txt', {'O_RDWR', 'O_APPEND'})
 ---
 ...
 tarantool> fh -- отображение дескриптора файла, который возвращает fio.open
 ---
 - fh: 11
 ...

Пример 2:

Использование fio.open() с tonumber('N', 8) для определения прав в виде восьмеричного числа:

tarantool> fio.open('x.txt', {'O_WRONLY', 'O_CREAT'}, tonumber('644',8))
 ---
 - fh: 12
 ...

object file-handle¶

file-handle:close()¶

Закрытие файла, который был открыт с помощью fio.open. Для получения подробной информации введите man 2 close.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open().
Return:	true – если выполнено, false – если не выполнено.
Rtype:	boolean

Example:

tarantool> fh:close() -- где fh = дескриптор файла
 ---
 - true
 ...

file-handle:pread(count, offset)¶

file-handle:pread(buffer, count, offset)

Чтение файла с произвольным доступом независимо от текущего положения в поиске. Для получения подробной информации введите man 2 pread.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open(). buffer – откуда читать (если формат – pread(buffer, count, offset)) count (number) – количество байтов для чтения offset (number) – смещение в файле – где начинается чтение

Если формат – pread(count, offset), возвращается строка с данными, прочитанными из файла, либо нулевое значение nil, если не выполнено.

Если формат – pread(buffer, count, offset), возвращаются данные в буфер. (Буферы можно ввести с помощью buffer.ibuf.)

Example:

tarantool> fh:pread(25, 25)
 ---
 - |
   elete from t8//
   insert in
 ...

file-handle:pwrite(new-string, offset)¶

file-handle:pwrite(buffer, count, offset)

Запись в файл с произвольным доступом независимо от текущего положения в поиске. Для получения подробной информации введите man 2 pwrite.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open(). new-string or buffer (string) – записываемое значение count (number) – количество записываемых байтов (если формат – pwrite(buffer, count, offset)) offset (number) – смещение в файле – где начинается запись
Return:	true – если выполнено, false – если не выполнено.
Rtype:	boolean

Если формат –pwrite(new-string, offset), строка записывается в файл до конца строки.

Если формат – pwrite(buffer, count, offset), содержимое буфера записывается в файл в объеме, указанном в count. (Буферы можно ввести с помощью buffer.ibuf.)

ibuf = require('buffer').ibuf()
 ---
 ...

 tarantool> fh:pwrite(ibuf, 1, 0)
 ---
 - true
 ...

file-handle:read([count])¶

file-handle:read(buffer, count)

Чтение файла не с произвольным доступом. Для получения подробной информации введите man 2 read или man 2 write.

Примечание

fh:read и fh:write влияют на положение поиска по файлу, и это следует учитывать при работе нескольких файберов над одним файлом. Существует возможность ограничения или запрета на доступ к файлу с помощью fiber.ipc.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open(). buffer – откуда читать (если формат – read(buffer, count)) count (number) – количество байтов для чтения

Если формат – read() – без count – считываются все байты в файле.

Если формат – read() или read([count]), возвращается строка с данными, прочитанными из файла, либо нулевое значение nil, если не выполнено.

Если формат – read(buffer, count), возвращаются данные в буфер. (Буферы можно ввести с помощью buffer.ibuf.)

ibuf = require('buffer').ibuf()
 ---
 ...

 tarantool> fh:read(ibuf:reserve(5), 5)
 ---
 - 5
 ...

 tarantool> require('ffi').string(ibuf:alloc(5),5)
 ---
 - abcde

file-handle:write(new-string)¶

file-handle:write(buffer, count)

Запись в файл не с произвольным доступом. Для получения подробной информации введите man 2 write.

Примечание

fh:read и fh:write влияют на положение поиска по файлу, и это следует учитывать при работе нескольких файберов над одним файлом. Существует возможность ограничения или запрета на доступ к файлу с помощью fiber.ipc.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open(). new-string or buffer (string) – записываемое значение count (number) – количество записываемых байтов (если формат – write(buffer, count))
Return:	true – если выполнено, false – если не выполнено.
Rtype:	boolean

Если формат – write(new-string), строка записывается в файл до конца строки.

Если формат – write(buffer, count), содержимое буфера записывается в файл в объеме, указанном в count. (Буферы можно ввести с помощью buffer.ibuf.)

Example:

tarantool> fh:write("new data")
          ---
          - true
          ...

file-handle:truncate(new-size)¶

Изменение размера открытого файла. Отличается от функции fio.truncate, которая изменяет размер закрытого файла.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open().
Return:	true – если выполнено, false – если не выполнено.
Rtype:	boolean

Example:

tarantool> fh:truncate(0)
 ---
 - true
 ...

file-handle:seek(position[, offset-from])¶

Изменение положения в файле на указанное. Для получения подробной информации введите man 2 seek.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open(). position (number) – искомое положение offset-from (string) – „SEEK_END“ = конец файла, „SEEK_CUR“ = текущее положение, „SEEK_SET“ = начало файла.
Return:	новое положение, если выполнено
Rtype:	number

Возможные ошибки: nil.

Example:

tarantool> fh:seek(20, 'SEEK_SET')
 ---
 - 20
 ...

file-handle:stat()¶

Возврат статистики об открытом файле. Отличается от функции fio.stat, которая возвращает статистику о закрытом файле. Для получения подробной информации введите man 2 stat.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open().
Return:	подробная информация о файле.
Rtype:	table

Example:

tarantool> fh:stat()
 ---
 - inode: 729866
   rdev: 0
   size: 100
   atime: 140942855
   mode: 33261
   mtime: 1409430660
   nlink: 1
   uid: 1000
   blksize: 4096
   gid: 1000
   ctime: 1409430660
   dev: 2049
   blocks: 8
 ...

file-handle:fsync()¶

file-handle:fdatasync()¶

Проверка записи изменений в открытом файле на диск. Ср. с fio.sync для всех файлов. Для получения подробной информации введите man 2 fsync or man 2 fdatasync.

Параметры:	fh (userdata) – дескриптор файла, который возвращает fio.open().
Return:	true – если выполнено, false – если не выполнено.

Example:

tarantool> fh:fsync()
 ---
 - true
 ...

Постоянные для файлового ввода-вывода¶

fio.c¶

Таблица с постоянными, которые совпадают с флаговыми значениями в POSIX на целевой платформе (см. man 2 stat).

Example:

tarantool> fio.c
 ---
 - seek:
     SEEK_SET: 0
     SEEK_END: 2
     SEEK_CUR: 1
   mode:
     S_IWGRP: 16
     S_IXGRP: 8
     S_IROTH: 4
     S_IXOTH: 1
     S_IRUSR: 256
     S_IXUSR: 64
     S_IRWXU: 448
     S_IRWXG: 56
     S_IWOTH: 2
     S_IRWXO: 7
     S_IWUSR: 128
     S_IRGRP: 32
   flag:
     O_EXCL: 2048
     O_NONBLOCK: 4
     O_RDONLY: 0
     <...>
 ...