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
andfio.symlink
andfio.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 ...
- fh (userdata) – file-handle as returned by
-
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 ...
- fh (userdata) – file-handle as returned by
-
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
andfh: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 withfiber.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 ...
- fh (userdata) – file-handle as returned by
-
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 ...
- fh (userdata) – file-handle as returned by
-
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 ...
- fh (userdata) – file-handle as returned by
-
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 ...
- fh (userdata) – file-handle as returned by
-
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 ...
- fh (userdata) – file-handle as returned by
-
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 <...> ...