Модуль fio¶

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

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

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

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

Указатель¶

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

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

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

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

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

Пример:

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

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

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

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

Пример:

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

fio.dirname(path-name)¶

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

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

Пример:

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

fio.abspath(file-name)¶

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

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

Пример:

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

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

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

fio.path.exists(path-name)¶

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

fio.path.is_dir(path-name)¶

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

fio.path.is_file(path-name)¶

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

fio.path.is_link(path-name)¶

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

fio.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 -p в терминале.

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

Пример:

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

fio.rmtree(path-name)¶

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

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

Пример:

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) – связанное имя.
возвращает:	(Если ошибки нет) 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.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.
возвращает:	(Если ошибки нет) true. (В случае ошибки) возвращаются два значения: false, сообщение об ошибке.
тип возвращаемого значения:
	boolean (логический)

Пример:

tarantool> fio.utime('/home/username/tmp.txt')
---
- 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:

Using fio.open() with tonumber('N', 8) to set permissions as an octal number:

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

Если формат – 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 (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
...

file-handle:read([count])¶

file-handle:read(buffer, count)

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

Примечание

fh:read and fh:write affect the seek position within the file, and this must be taken into account when working on the same file from multiple fibers. It is possible to limit or prevent file access from other fibers with fiber.cond() or fiber.channel().

Параметры:	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)
---
- 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 and fh:write affect the seek position within the file, and this must be taken into account when working on the same file from multiple fibers. It is possible to limit or prevent file access from other fibers with fiber.cond() or fiber.channel().

Параметры:	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")
---
- true
...
tarantool> ibuf = require('buffer').ibuf()
---
...
tarantool> fh:write(ibuf, 1)
---
- 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
    <...>
...