Версия:

Модуль fio

Модуль fio

Overview

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

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

Index

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

Name Use
fio.pathjoin() Формирование пути к файлу из одной или более частей строки
fio.basename() Получение имени файла
fio.dirname() Получение имени директории
fio.abspath() Получение имен директории и файла
fio.path.exists() Проверка наличия файла или директории
fio.path.is_dir() Проверка, является ли файл или директория директорией
fio.path.is_file() Проверка, является ли файл или директория файлом
fio.path.is_link() Проверка, является ли файл или директория ссылкой
fio.path.lexists() Проверка наличия файла или директории
fio.umask() Определение битов маски
fio.lstat()
fio.stat()
Получение информации об объекте файла
fio.mkdir()
fio.rmdir()
Создание или удаление директории
fio.chdir() Изменение рабочей директории
fio.listdir() Вывод списка файлов в директории
fio.glob() Получение файлов, имена которых совпадают с заданной строкой
fio.tempdir() Получение имени директории для хранения временных файлов
fio.cwd() Получение имени текущей рабочей директории
fio.copytree()
fio.mktree()
fio.rmtree()
Создание и удаление директорий
fio.link()
fio.symlink()
fio.readlink()
fio.unlink()
Создание и удаление ссылок
fio.rename() Переименование файла или директории
fio.utime() Change file update time
fio.copyfile() Копирование файла
fio.chown()
fio.chmod()
Управление правами на использование и правами владения объектами файла
fio.truncate() Уменьшение размера файла
fio.sync() Проверка записи изменений на диск
fio.open() Открытие файла
file-handle:close() Закрытие файла
file-handle:pread()
file-handle:pwrite()
Чтение или запись в файл с произвольным доступом
file-handle:read()
file-handle:write()
Чтение или запись в файл не с произвольным доступом
file-handle:truncate() Изменение размера открытого файла
file-handle:seek() Изменение позиции в файле
file-handle:stat() Получение статистики об открытом файле
file-handle:fsync()
file-handle:fdatasync()
Проверка записи изменений в открытом файле на диск
fio.c Таблица переменных, аналогичных флаговым значениям POSIX

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

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

Функции для создания и удаления ссылок. Для получения подробной информации введите 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
     <...>
 ...