Module fio¶

Tarantool supports file input/output with an API that is similar to POSIX syscalls. All operations are performed asynchronously. Multiple fibers can access the same file simultaneously.

The fio module contains:

functions for common pathname manipulations,
functions for common file manipulations, and
constants which are the same as POSIX flag values (for example fio.c.flag.O_RDONLY = POSIX O_RDONLY).

Common pathname manipulations¶

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

Concatenate partial string, separated by „/“ to form a path name.

Параметры:	partial-string (string) – one or more strings to be concatenated.
Return:	path name
Rtype:	string

Example:

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

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

Given a full path name, remove all but the final part (the file name). Also remove the suffix, if it is passed.

Параметры:	path-name (string) – path name suffix (string) – suffix
Return:	file name
Rtype:	string

Example:

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

fio.dirname(path-name)¶

Given a full path name, remove the final part (the file name).

Параметры:	path-name (string) – path name
Return:	directory name, that is, path name except for file name.
Rtype:	string

Example:

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

Common file manipulations¶

fio.umask(mask-bits)¶

Set the mask bits used when creating files or directories. For a detailed description type «man 2 umask».

Параметры:	mask-bits (number) – mask bits.
Return:	previous mask bits.
Rtype:	number

Example:

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

fio.lstat(path-name)¶

fio.stat(path-name)¶

Returns information about a file object. For details type «man 2 lstat» or «man 2 stat».

Параметры:	path-name (string) – path name of file.
Return:	fields which describe the file’s block size, creation time, size, and other attributes.
Rtype:	table

Additionally, the result of fio.stat('file-name') will include methods equivalent to POSIX macros:

is_blk() = POSIX macro S_ISBLK,
is_chr() = POSIX macro S_ISCHR,
is_dir() = POSIX macro S_ISDIR,
is_fifo() = POSIX macro S_ISFIFO,
is_link() = POSIX macro S_ISLINK,
is_reg() = POSIX macro S_ISREG,
is_sock() = POSIX macro S_ISSOCK.

For example, fio.stat('/'):is_dir() will return 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)¶

Create or delete a directory. For details type «man 2 mkdir» or «man 2 rmdir».

Параметры:	path-name (string) – path of directory. mode (number) – Mode bits can be passed as a number or as string constants, for example „“S_IWUSR». Mode bits can be combined by enclosing them in braces.
Return:	true if success, false if failure.
Rtype:	boolean

Example:

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

fio.glob(path-name)¶

Return a list of files that match an input string. The list is constructed with a single flag that controls the behavior of the function: GLOB_NOESCAPE. For details type «man 3 glob».

Параметры:	path-name (string) – path-name, which may contain wildcard characters.
Return:	list of files whose names match the input string
Rtype:	table

Possible errors: nil.

Example:

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

fio.tempdir()¶

Return the name of a directory that can be used to store temporary files.

Example:

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

fio.cwd()¶

Return the name of the current working directory.

Example:

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

fio.link(src, dst)¶

fio.symlink(src, dst)¶

fio.readlink(src)¶

fio.unlink(src)¶

Functions to create and delete links. For details type «man readlink», «man 2 link», «man 2 symlink», «man 2 unlink»..

Параметры:	src (string) – existing file name. dst (string) – linked name.
Return:	`fio.link` and `fio.symlink` and `fio.unlink` return true if success, false if failure. `fio.readlink` returns the link value if success, nil if failure.

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

Rename a file or directory. For details type «man 2 rename».

Параметры:	path-name (string) – original name. new-path-name (string) – new name.
Return:	true if success, false if failure.
Rtype:	boolean

Example:

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

fio.chown(path-name, owner-user, owner-group)¶

fio.chmod(path-name, new-rights)¶

Manage the rights to file objects, or ownership of file objects. For details type «man 2 chown» or «man 2 chmod».

Параметры:	owner-user (string) – new user uid. owner-group (string) – new group uid. new-rights (number) – new permissions

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

Reduce file size to a specified value. For details type «man 2 truncate».

Параметры:	path-name (string) – new-size (number) –
Return:	true if success, false if failure.
Rtype:	boolean

Example:

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

fio.sync()¶

Ensure that changes are written to disk. For details type «man 2 sync».

Return:	true if success, false if failure.
Rtype:	boolean

Example:

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

fio.open(path-name[, flags[, mode]])¶

Open a file in preparation for reading or writing or seeking.

Параметры:	path-name (string) – flags (number) – Flags can be passed as a number or as string constants, for example „`O_RDONLY`“, „`O_WRONLY`“, „`O_RDWR`“. Flags can be combined by enclosing them in braces. mode (number) – Mode bits can be passed as a number or as string constants, for example „“S_IWUSR». Mode bits are significant if flags include O_CREAT or O_TMPFILE. Mode bits can be combined by enclosing them in braces.
Return:	file handle (later - fh)
Rtype:	userdata

Possible errors: nil.

Example:

tarantool> fh = fio.open('/home/username/tmp.txt', {'O_RDWR', 'O_APPEND'})
---
...
tarantool> fh -- display file handle returned by fio.open
---
- fh: 11
...

object file-handle¶

file-handle:close()¶

Close a file that was opened with fio.open. For details type «man 2 close».

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`.
Return:	true if success, false on failure.
Rtype:	boolean

Example:

tarantool> fh:close() -- where fh = file-handle
---
- true
...

file-handle:pread(count, offset)¶

file-handle:pwrite(new-string, offset)¶

Perform read/write random-access operation on a file, without affecting the current seek position of the file. For details type «man 2 pread» or «man 2 pwrite».

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`. count (number) – number of bytes to read new-string (string) – value to write offset (number) – offset within file where reading or writing begins
Return:	`fh:pwrite` returns true if success, false if failure. `fh:pread` returns the data that was read, or nil if failure.

Example:

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

file-handle:read(count)¶

file-handle:write(new-string)¶

Perform non-random-access read or write on a file. For details type «man 2 read» or «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.ipc.

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`. count (number) – number of bytes to read new-string (string) – value to write
Return:	`fh:write` returns true if success, false if failure. `fh:read` returns the data that was read, or nil if failure.

Example:

tarantool> fh:write('new data')
---
- true
...

file-handle:truncate(new-size)¶

Change the size of an open file. Differs from fio.truncate, which changes the size of a closed file.

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`.
Return:	true if success, false if failure.
Rtype:	boolean

Example:

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

file-handle:seek(position[, offset-from])¶

Shift position in the file to the specified position. For details type «man 2 seek».

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`. position (number) – position to seek to offset-from (string) – „`SEEK_END`“ = end of file, „`SEEK_CUR`“ = current position, „`SEEK_SET`“ = start of file.
Return:	the new position if success
Rtype:	number

Possible errors: nil.

Example:

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

file-handle:stat()¶

Return statistics about an open file. This differs from fio.stat which return statistics about a closed file. For details type «man 2 stat».

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`.
Return:	details about the file.
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()¶

Ensure that file changes are written to disk, for an open file. Compare fio.sync, which is for all files. For details type «man 2 fsync» or «man 2 fdatasync».

Параметры:	fh (userdata) – file-handle as returned by `fio.open()`.
Return:	true if success, false if failure.

Example:

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

FIO constants¶

fio.c¶

Table with constants which are the same as POSIX flag values on the target platform (see 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
    <...>
...

Версия:

Module fio¶

Common pathname manipulations¶

Common file manipulations¶

FIO constants¶