Версия:

Модуль fio

Модуль fio

Общие сведения

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

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

Индекс

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

Имя Использование
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.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) – одна или более строк для конкатенации.
возвращается:

путь к файлу

тип возвращаемого значения:
 

string (строка)

Пример:

tarantool> fio.pathjoin('/etc', 'default', 'myfile')
 ---
 - /etc/default/myfile
 ...
fio.basename(path-name[, suffix])

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

Параметры:
  • path-name (string) – путь к файлу
  • suffix (string) – суффикс
возвращается:

имя файла

тип возвращаемого значения:
 

string (строка)

Пример:

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

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

Параметры:
  • path-name (string) – путь к файлу
возвращается:

имя директории, то есть путь к файлу без имени файла.

тип возвращаемого значения:
 

string (строка)

Пример:

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

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

Параметры:
  • file-name (string) – имя файла
возвращается:

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

тип возвращаемого значения:
 

string (строка)

Пример:

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

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

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

path.exists(path-name)
Параметры:
  • path-name (string) – путь к директории или файлу.
возвращается:

true (правда), если путь к файлу ссылается на директорию или файл, которые присутствуют в системе, и не представляет собой нерабочую символьную ссылку; в противном случае, false (ложь)

тип возвращаемого значения:
 

boolean (логический)

path.is_dir(path-name)
Параметры:
  • path-name (string) – путь к директории или файлу.
возвращается:

true (правда), если путь к файлу ссылается на директорию; в противном случае, false (ложь)

тип возвращаемого значения:
 

boolean (логический)

path.is_file(path-name)
Параметры:
  • path-name (string) – путь к директории или файлу.
возвращается:

true (правда), если путь к файлу ссылается на файл; в противном случае, false (ложь)

тип возвращаемого значения:
 

boolean (логический)

Параметры:
  • path-name (string) – путь к директории или файлу.
возвращается:

true (правда), если путь к файлу ссылается на символьную ссылку; в противном случае, false (ложь)

тип возвращаемого значения:
 

boolean (логический)

path.lexists(path-name)
Параметры:
  • path-name (string) – путь к директории или файлу.
возвращается:

true (правда), если путь к файлу ссылается на директорию или файл, которые присутствуют в системе, и представляет собой нерабочую символьную ссылку; в противном случае, false (ложь)

тип возвращаемого значения:
 

boolean (логический)

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

fio.umask(mask-bits)

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

Параметры:
  • mask-bits (number) – биты маски.
возвращается:

предыдущие биты маски.

тип возвращаемого значения:
 

число

Пример:

tarantool> fio.umask(tonumber('755', 8))
 ---
 - 493
 ...
fio.lstat(path-name)
fio.stat(path-name)

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

Параметры:
  • path-name (string) – путь к файлу.
возвращается:

(Если ошибки нет) таблица с полями, которые описывают размер блока файла, время создания, размер и прочие атрибуты.
(В случае ошибки) возвращаются два значения: null, сообщение об ошибке.

тип возвращаемого значения:
 

таблица.

Кроме того, результат 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.

Пример:

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. Биты режима работы можно комбинировать путем обрамления их в фигурные скобки.
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: false, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

Параметры:
  • path-name (string) – путь к директории.
возвращается:

(Если выполнено) true. (Если не выполнено) false.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

Параметры:
  • path-name (string) – путь к директории.
возвращается:

(Если ошибки нет) список файлов.
(В случае ошибки) возвращаются два значения: null, сообщение об ошибке.

тип возвращаемого значения:
 

таблица

Пример:

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

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

Параметры:
  • path-name (string) – путь к файлу, который может содержать специальные символы.
возвращается:

список файлов, имена которых совпадают с введенной строкой.

тип возвращаемого значения:
 

таблица

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

Пример:

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

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

Пример:

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

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

Пример:

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) – путь.
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: false, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

Параметры:
  • path-name (string) – путь.
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: false, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

Параметры:
  • path-name (string) – путь.
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: null, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

Параметры:
  • src (string) – имя существующего файла.
  • dst (string) – связанное имя.
возвращается:

(Если ошибки нет) fio.link, fio.symlink и fio.unlink возвращают true (правда), fio.readlink возвращает ссылку.
(В случае ошибки) возвращаются два значения: false|null, сообщение об ошибке.

Пример:

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) – новое имя.
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: false, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

Параметры:
  • path-name (string) – путь к первоначальному файлу.
  • new-path-name (string) – путь к новому файлу.
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: false, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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) – новые права
возвращается:

null

Пример:

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) –
возвращается:

(Если ошибки нет) true.
(В случае ошибки) возвращаются два значения: false, сообщение об ошибке.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

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

возвращается:true – если выполнено, false – если не выполнено.
тип возвращаемого значения:
 boolean (логический)

Пример:

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. Биты режима работы можно комбинировать путем обрамления их в фигурные скобки.
возвращается:

(Если ошибки нет) дескриптор файла (далее сокращенно „fh“).
(В случае ошибки) возвращаются два значения: null, сообщение об ошибке.

тип возвращаемого значения:
 

пользовательские данные

Возможные ошибки: 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().
возвращается:

true – если выполнено, false – если не выполнено.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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

Пример:

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) – смещение в файле – где начинается запись
возвращается:

true – если выполнено, false – если не выполнено.

тип возвращаемого значения:
 

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))
возвращается:

true – если выполнено, false – если не выполнено.

тип возвращаемого значения:
 

boolean (логический)

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

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

Пример:

tarantool> fh:write("new data")
          ---
          - true
          ...
file-handle:truncate(new-size)

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

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

true – если выполнено, false – если не выполнено.

тип возвращаемого значения:
 

boolean (логический)

Пример:

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“ = начало файла.
возвращается:

новое положение, если выполнено

тип возвращаемого значения:
 

число

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

Пример:

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

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

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

подробная информация о файле.

тип возвращаемого значения:
 

таблица

Пример:

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().
возвращается:

true – если выполнено, false – если не выполнено.

Пример:

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

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

fio.c

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

Пример:

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