Модуль 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])¶

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

Note that the basename of a path with a trailing slash is an empty string. It is different from how the Unix basename program interprets such a path.

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

Пример:

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

Example with a trailing slash:

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

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

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

Functions in this section are similar to some Python os.path functions.

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.tempdir() stores the created temporary directory into /tmp by default. Since version 2.4.1, this can be changed by setting the TMPDIR environment variable. Before starting Tarantool, or at runtime by os.setenv().

Пример:

tarantool> fio.tempdir()
---
- /tmp/lG31e7
...
tarantool> fio.mkdir('./mytmp')
---
- true
...

tarantool> os.setenv('TMPDIR', './mytmp')
---
...

tarantool> fio.tempdir()
---
- ./mytmp/506Z0b
...

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

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

Параметры:	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) – имя. 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.

Note that since version 2.4.1 fio.open() returns a descriptor which can be closed manually by calling the :close() method, or it will be closed automatically when it has no references, and the garbage collector deletes it.

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

Пример 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 и fh:write влияют на положение поиска по файлу, и это следует учитывать при работе нескольких файберов над одним файлом. Существует возможность ограничения или запрета на доступ к файлу с помощью fiber.ipc. Можно ограничить или запретить доступ к файлам из других файберов с помощью fiber.cond() или 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 и fh:write влияют на положение поиска по файлу, и это следует учитывать при работе нескольких файберов над одним файлом. Существует возможность ограничения или запрета на доступ к файлу с помощью fiber.ipc. Можно ограничить или запретить доступ к файлам из других файберов с помощью fiber.cond() или 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
    <...>
...