Модуль fio

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

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

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

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

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

Параметры:

• partial-string (string) — одна или несколько строк для конкатенации.

Возвращает

путь к файлу

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

string

Пример:

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

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

Обратите внимание, что базовое имя пути с завершающим слешем — пустая строка. Это отличается от того, как программа basename в Unix интерпретирует такой путь.

Параметры:

• path-name (string) — имя пути
• suffix (string) — суффикс

Возвращает

имя файла

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

string

Пример:

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

Пример с завершающим слешем:

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

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

Параметры:

• path-name (string) — путь к файлу

Возвращает

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

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

string

Пример:

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

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

Параметры:

• file-name (string) — имя файла

Возвращает

имя каталога, то есть путь, включающий имя файла.

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

string

Пример:

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

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

Параметры:

• path-name (string) — путь к каталогу или файлу.

Возвращает

true, если path-name указывает на существующий каталог или файл, не являющийся битой символической ссылкой; в противном случае — false.

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

boolean

Параметры:

• path-name (string) — путь к каталогу или файлу.

Возвращает

true, если path-name указывает на каталог; в противном случае — false.

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

boolean

Параметры:

• path-name (string) — путь к каталогу или файлу.

Возвращает

true, если path-name указывает на файл; в противном случае — false.

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

boolean

Параметры:

• path-name (string) — путь к каталогу или файлу.

Возвращает

true, если path-name указывает на символическую ссылку; в противном случае — false.

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

boolean

Параметры:

• path-name (string) — путь к каталогу или файлу.

Возвращает

true, если path-name указывает на существующий каталог или файл либо на битую символическую ссылку; в противном случае — false.

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

boolean

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

Параметры:

• mask-bits (number) — биты маски.

Возвращает

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

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

number

Пример:

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

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

Параметры:

• path-name (string) — путь к файлу.

Возвращает

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

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

table

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

• is_blk() = POSIX-макрос S_ISBLK,
• is_chr() = POSIX-макрос S_ISCHR,
• is_dir() = POSIX-макрос S_ISDIR,
• is_fifo() = POSIX-макрос S_ISFIFO,
• is_link() = POSIX-макрос S_ISLINK,
• is_reg() = POSIX-макрос S_ISREG,
• is_sock() = POSIX-макрос S_ISSOCK. Например, 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

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

Параметры:

• path-name (string) — путь к директории.
• mode (number) — биты режима. Биты режима можно передать числом или строковыми константами, например S_IWUSR. Биты режима можно комбинировать, заключив их в фигурные скобки.

Возвращает

(при отсутствии ошибки) true. (при ошибке) два возвращаемых значения: false, сообщение об ошибке.

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

boolean

Пример:

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

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

Параметры:

• path-name (string) — путь к директории.

Возвращает

(при успехе) true. (при неудаче) false.

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

boolean

Пример:

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

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

Параметры:

• path-name (string) — путь к директории.

Возвращает

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

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

table

Пример:

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

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

Параметры:

• path-name (string) — путь, который может содержать подстановочные символы.

Возвращает

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

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

table

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

Пример:

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

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

По умолчанию fio.tempdir() сохраняет созданную временную директорию в /tmp. Начиная с версии 2.4.1, это поведение можно изменить, задав переменную окружения TMPDIR — перед запуском Tarantool или во время выполнения с помощью os.setenv().

Пример:

 
tarantool> fio.tempdir()---- /tmp/lG31e7tarantool> fio.mkdir('./mytmp')---- truetarantool> os.setenv('TMPDIR', './mytmp')---tarantool> fio.tempdir()---- ./mytmp/506Z0b

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

Пример:

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

Копирование всего из директории 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

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

Параметры:

• path-name (string) — путь к директории.

Возвращает

(если нет ошибок) true. (при ошибке) два возвращаемых значения: false, сообщение об ошибке.

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

boolean

Пример:

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

Удаление указанной директории, включая поддиректории. Результат аналогичен результату выполнения команды rm -rf в терминале.

Параметры:

• 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')---- truetarantool> fio.unlink('/home/username/tmp.txt2')---- true

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

Изменение времени доступа и, возможно, времени изменения файла. Подробнее см. man 2 utime. Время указывается в секундах, прошедших с начала эпохи.

Параметры:

• file-name (string) — имя.
• accesstime (number) — время последнего доступа. По умолчанию — текущее время.
• updatetime (number) — время последнего изменения. По умолчанию = время доступа.

Возвращает

(при отсутствии ошибки) true. (при ошибке) два возвращаемых значения: false, сообщение об ошибке.

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

boolean

Пример:

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

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

Параметры:

• path-name (string) — путь к исходному файлу.
• new-path-name (string) — путь к новому файлу.

Возвращает

(при отсутствии ошибок) true. (при ошибке) два возвращаемых значения: false, сообщение об ошибке.

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

boolean

Пример:

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

Управление правами на использование и правами владения объектами файла. Для получения подробной информации введите 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))---- truetarantool> fio.chown('/home/username/tmp.txt', 'username', 'username')---- true

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

Параметры:

• path-name (string) — путь к файлу.
• new-size (number) — новый размер файла.

Возвращает

(если нет ошибок) true. (если есть ошибка) два возвращаемых значения: false, сообщение об ошибке.

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

boolean

Пример:

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

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

Возвращает

true в случае успеха, false в случае ошибки.

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

boolean

Пример:

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

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

Параметры:

• 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, сообщение об ошибке.

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

userdata

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

Обратите внимание, что начиная с версии 2.4.1 fio.open() возвращает дескриптор, который можно закрыть вручную, вызвав метод :close(), либо он будет закрыт автоматически, когда на него не останется ссылок и сборщик мусора удалит его.

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

Пример 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

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

Параметры:

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

Возвращает

true в случае успеха, false в случае ошибки.

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

boolean

Пример:

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

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

Параметры:

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

Возвращает

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

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

Пример:

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

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

Параметры:

• fh (userdata) — файловый дескриптор, возвращаемый fio.open().
• new-string (string) — записываемое значение (если формат — pwrite(new-string, offset)).
• buffer (cdata) — записываемое значение (если формат — pwrite(buffer, count, offset)).
• count (number) — количество записываемых байтов.
• offset (number) — смещение в файле, с которого начинается запись.

Возвращает

true в случае успеха, false в случае ошибки.

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

boolean

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

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

Пример:

 
tarantool> ibuf = require('buffer').ibuf()---tarantool> fh:pwrite(ibuf, 1, 0)---- true

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

Параметры:

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

Возвращает

• Если формат read() — без указания count — выполняется чтение всех байт файла.
• Если формат read() или read([count]), возвращается строка, содержащая данные, прочитанные из файла, или пустая строка в случае ошибки.
• Если формат read(buffer, count), данные возвращаются в буфер. Буферы можно получить с помощью buffer.ibuf.
• В случае ошибки метод возвращает nil, err и устанавливает ошибку в errno.

Пример:

 
tarantool> ibuf = require('buffer').ibuf()---tarantool> fh:read(ibuf:reserve(5), 5)---- 5tarantool> require('ffi').string(ibuf:alloc(5),5)---- abcde

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

Параметры:

• fh (userdata) — файловый дескриптор, возвращаемый fio.open().
• new-string (string) — записываемое значение (если формат — write(new-string)).
• buffer (cdata) — записываемое значение (если формат — write(buffer, count)).
• count (number) — количество записываемых байтов.

Возвращает

true в случае успеха, false в случае ошибки.

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

boolean

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

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

Пример:

 
tarantool> fh:write("new data")---- truetarantool> ibuf = require('buffer').ibuf()---tarantool> fh:write(ibuf, 1)---- true

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

Параметры:

• fh (userdata) — файловый дескриптор, возвращаемый функцией fio.open().

Возвращает

true в случае успеха, false в случае ошибки.

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

boolean

Пример:

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

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

Параметры:

• fh (userdata) — файловый дескриптор, возвращаемый fio.open().
• position (number) — позиция для перемещения.
• offset-from (string) — 'SEEK_END' = конец файла, 'SEEK_CUR' = текущая позиция, 'SEEK_SET' = начало файла.

Возвращает

новая позиция при успешном выполнении.

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

number

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

Пример:

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

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

Параметры:

• fh (userdata) — файловый дескриптор, возвращаемый функцией fio.open().

Возвращает

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

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

table

Пример:

 
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

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

Параметры:

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

Возвращает

true в случае успеха, false в случае ошибки.

Пример:

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

Таблица с постоянными, которые совпадают с флаговыми значениями в 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, ...}