NAME

GlusterFS::GFAPI::FFI::Volume - GFAPI Volume API

SYNOPSIS

DESCRIPTION

ATTRIBUTES

mounted

Read-only attribute that returns True if the volume is mounted.

The value of the attribute is internally changed on invoking mount() and umount() functions.

fs

host

Host with glusterd management daemon running OR path to socket file which glusterd is listening on.

volname

Name of GlusterFS volume to be mounted and used.

protocol

Transport protocol to be used to connect to management daemon. Permitted values are "tcp" and "rdma".

port

Port number where gluster management daemon is listening.

log_file

Path to log file. When this is set to None, a new logfile will be created in default log directory

i.e /var/log/glusterfs

log_level

Integer specifying the degree of verbosity. Higher the value, more verbose the logging.

CONSTRUCTOR

new

options

host

Host with glusterd management daemon running OR path to socket file which glusterd is listening on.

volname

Name of GlusterFS volume to be mounted and used.

proto

Transport protocol to be used to connect to management daemon. Permitted values are "tcp" and "rdma".

port

Port number where gluster management daemon is listening.

log_file

Path to log file. When this is set to None, a new logfile will be created in default log directory

i.e /var/log/glusterfs

log_level

Integer specifying the degree of verbosity. Higher the value, more verbose the logging.

METHODS

mount

Mount a GlusterFS volume for use.

umount

Unmount a mounted GlusterFS volume.

Provides users a way to free resources instead of just waiting for perl to call DEMOLISH() at refcnt to be zero.

set_logging

Set logging parameters. Can be invoked either before or after invoking mount().

When invoked before mount(), the preferred log file and log level choices are recorded and then later enforced internally as part of mount().

When invoked at any point after mount(), the change in log file and log level is instantaneous.

parameters

log_file

Path of log file.

If set to "/dev/null", nothing will be logged. If set to None, a new logfile will be created in default log directory (/var/log/glusterfs)

log_level

Integer specifying the degree of verbosity. Higher the value, more verbose the logging.

get_volume_id

Returns the volume ID (of type UUID) for the currently mounted volume.

access

Use the real uid/gid to test for access to path.

parameters

path

Path to be checked.

mode

mode should be F_OK to test the existence of path, or it can be the inclusive OR of one or more of R_OK, W_OK, and X_OK to test permissions

returns

True if access is allowed, False if not

chdir

Change the current working directory to the given path.

parameters

path

Path to change current working directory to

chmod

Change mode of path

parameters

path

the item to be modified

mode

new mode

chown

Change owner and group id of path

parameters

path

the path to be modified

uid

new user id for path

gid

new group id for path

exists

Returns True if path refers to an existing path.

Returns False for broken symbolic links.

This function may return False if permission is not granted to execute stat() on the requested file, even if the path physically exists.

getatime

Returns the last access time as reported by stat()

getctime

Returns the time when changes were made to the path as reported by stat(). This time is updated when changes are made to the file or dir's inode or the contents of the file.

getcwd

Returns current working directory.

getmtime

Returns the time when changes were made to the content of the path as reported by stat().

getsize

Return the size of a file in bytes, reported by stat()

getxattr

Retrieve the value of the extended attribute identified by key for path specified.

parameters

path

Path to file or directory

key

Key of extended attribute

size

If size is specified as zero, we first determine the size of xattr and then allocate a buffer accordingly.

If size is non-zero, it is assumed the caller knows the size of xattr.

returns

Value of extended attribute corresponding to key specified.

isdir

Returns True if path is an existing directory.

Returns False on all failure cases including when path does not exist.

isfile

Return True if path is an existing regular file.

Returns False on all failure cases including when path does not exist.

islink

Return True if path refers to a directory entry that is a symbolic link.

Returns False on all failure cases including when path does not exist.

listdir

Return a list containing the names of the entries in the directory given by path.

The list is in arbitrary order.

It does not include the special entries '.' and '..' even if they are present in the directory.

parameters

path

Path to directory

returns

List of names of directory entries

listdir_with_stat

Return a list containing the name and stat of the entries in the directory given by path.

The list is in arbitrary order.

It does not include the special entries '.' and '..' even if they are present in the directory.

paramters

path

Path to directory

returns

A list of hashref. The hashref is of the form (name, stat) where name is a string indicating name of the directory entry and stat contains stat info of the entry.

scandir

Return an iterator of GlusterFS::GFAPI::FFI::DirEntry objects corresponding to the entries in the directory given by path.

The entries are yielded in arbitrary order, and the special entries '.' and '..' are not included.

Using scandir() instead of listdir() can significantly increase the performance of code that also needs file type or file attribute information, because GlusterFS::GFAPI::FFI::DirEntry objects expose this information.

scandir() provides same functionality as listdir_with_stat() except that scandir() does not return a list and is an iterator.

Hence scandir is less memory intensive on large directories.

parameters

path

Path to directory

listxattr

Retrieve list of extended attribute keys for the specified path.

parameters

path

Path to file or directory.

size

If size is specified as zero, we first determine the size of list and then allocate a buffer accordingly.

If size is non-zero, it is assumed the caller knows the size of the list.

returns

List of extended attribute keys.

lstat

Return stat information of path. If path is a symbolic link, then it returns information about the link itself, not the file that it refers to.

makedirs

Recursive directory creation function. Like mkdir(), but makes all intermediate-level directories needed to contain the leaf directory.

The default mode is 0777 (octal).

mkdir

Create a directory named path with numeric mode mode.

The default mode is 0777 (octal).

fopen

Similar to Perl's built-in File object returned by Perl's open().

Unlike Perl's open(), fopen() provided here is only for convenience and it does NOT invoke glibc's fopen and does NOT do any kind of I/O bufferring as of today.

The most commonly-used values of mode are 'r' for reading, 'w' for writing (truncating the file if it already exists), and 'a' for appending. If mode is omitted, it defaults to 'r'.

Modes 'r+', 'w+' and 'a+' open the file for updating (reading and writing); note that 'w+' truncates the file.

Append 'b' to the mode to open the file in binary mode but this has no effect as of today.

parameters

path

Path of file to be opened

mode

Mode to open the file with. This is a string.

returns

an instance of File class

open

Similar to Perl's open()

As of today, the only way to consume the raw glfd returned is by passing it to File class.

parameters

path

Path of file to be opened

flags

Integer which flags must include one of the following access modes: O_RDONLY, O_WRONLY, or O_RDWR.

mode

specifies the permissions to use in case a new file is created.

The default mode is 0777 (octal)

returns

the raw glfd (pointer to memory in C, number in perl)

opendir

Open a directory.

parameters

Path to the directory

readdirplus

Enable readdirplus which will also fetch stat information for each entry of directory.

returns

Returns a instance of Dir class

readlink

Return a string representing the path to which the symbolic link points.

The result may be either an absolute or relative pathname.

remove

Remove (delete) the file path. If path is a directory. This is identical to the unlink() function.

removexattr

Remove a extended attribute of the path.

parameters

path

Path to the file or directory.

key

The key of extended attribute.

path

Path of symbolic link

returns

Contents of symlink

rename

Rename the file or directory from src to dst. If dst is a directory, will be raised.

If dst exists and is a file, it will be replaced silently if the user has permission.

parameters

src

dst

rmdir

Remove (delete) the directory path. Only works when the directory is empty, otherwise, is raised. In order to remove whole directory trees, rmtree() can be used.

parameters

path

rmtree

Delete a whole directory tree structure. Raises error if path is a symbolic link.

parameters

path

If True, errors are ignored

ignore_errors

onerror

If set, it is called to handle the error with arguments (func, path, exc) where func is the function that raised the error, path is the argument that caused it to fail; and exc is the exception that was raised.

If ignore_errors is False and onerror is None, an exception is raised

setfsuid

setfsuid() changes the value of the caller's filesystem user ID-the user ID that the Linux kernel uses to check for all accesses to the filesystem.

parameters

uid

user id to be changed

setfsgid

setfsgid() changes the value of the caller's filesystem group ID-the group ID that the Linux kernel uses to check for all accesses to the filesystem.

parameters

gid

group id to be changed

setxattr

Set extended attribute of the path.

parameters

path

Path to file or directory.

key

The key of extended attribute.

value

The valiue of extended attribute.

flags

Possible values are 0 (default), 1 and 2.

If 0 - xattr will be created if it does not exist, or the value will be replaced if the xattr exists. If 1 - it performs a pure create, which fails if the named attribute already exists. If 2 - it performs a pure replace operation, which fails if the named attribute does not already exist.

stat

Returns stat information of path.

parameters

path

Path to file or directory.

statvfs

Returns information about a mounted glusterfs volume. path is the pathname of any file within the mounted filesystem.

parameters

path

Path to file or directory.

returns

An object whose attributes describe the filesystem on the given path, and correspond to the members of the statvfs structure, namely:

f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_fsid, f_flag, and f_namemax.

link

Create a hard link pointing to source named link.

parameters

source

link

symlink

Create a symbolic link link which points to source

parameters

source

link

unlink

Delete the file path

parameters

path

Path to file or directory.

utime

Set the access and modified times of the file specified by path. If times is undef, then the file's access and modified times are set to the current time. (The effect is similar to running the Unix program touch on the path.) Otherwise, times must be a instance of GlusterFS::GFAPI::FFI::Timespecs, which is used to set the access and modified times, respectively.

walk

Generate the file names in a directory tree by walking the tree either top-down or bottom-up.

parameters

top

Directory path to walk

topdown

If topdown is True or not specified, the triple for a directory is generated before the triples for any of its subdirectories. If topdown is False, the triple for a directory is generated after the triples for all of its subdirectories.

onerror

If optional argument onerror is specified, it should be a function; it will be called with one argument, an exception data. It can report the error to continue with the walk, or raise exception to abort the walk.

followlinks

Set followlinks to True to visit directories pointed to by symlinks.

samefile

Return True if both pathname arguments refer to the same file or directory (as indicated by device number and inode number). Raise an exception if a stat() call on either pathname fails.

parameters

path1

Path to one file

path2

Path to another file

copyfileobj

Copy the contents of the file-like object fsrc to the file-like object fdst. The integer length, if given, is the buffer size. Note that if the current file position of the fsrc object is not 0, only the contents from the current file position to the end of the file will be copied.

parameters

fsrc

Source file object

fdst

Destination file object

length

Size of buffer in bytes to be used in copying

copyfile

Copy the contents (no metadata) of the file named src to a file named dst. dst must be the complete target file name.

If src and dst are the same, exception is raised.

The destination location must be writable.

If dst already exists, it will be replaced.

Special files such as character or block devices and pipes cannot be copied with this function.

src and dst are path names given as strings.

parameters

src

Path of source file

dst

Path of destination file

copymode

Copy the permission bits from src to dst. The file contents, owner, and group are unaffected. src and dst are path names given as strings.

parameters

src

Path of source file

dst

Path of destination file

copystat

Copy the permission bits, last access time, last modification time, and flags from src to dst. The file contents, owner, and group are unaffected. src and dst are path names given as strings.

parameters

src Path of source file

dst Path of destination file

parameters

src

dst

copy

Copy data and mode bits ("cp src dst").

Copy the file src to the file or directory dst. If dst is a directory, a file with the same basename as src is created (or overwritten) in the directory specified. Permission bits are copied. src and dst are path names given as strings.

parameters

src

Path of source file

dst

Path of destination file or directory

copy2

Similar to copy(), but metadata is copied as well - in fact, this is just copy() followed by copystat().

This is similar to the Unix command cp -p. The destination may be a directory.

src

Path of source file

dst

Path of destination file or directory

copytree

Recursively copy a directory tree using copy2().

The destination directory must not already exist.

If exception(s) occur, an exception is raised with a list of reasons.

If the optional symlinks flag is true, symbolic links in the source tree result in symbolic links in the destination tree; if it is false, the contents of the files pointed to by symbolic links are copied.

The optional ignore argument is a callable. If given, it is called with the src parameter, which is the directory being visited by copytree(), and names which is the list of src contents:

C<callable(src, names) -> ignored_names>

Since copytree() is called recursively, the callable will be called once for each directory that is copied.

It returns a list of names relative to the src directory that should not be copied.

BUGS

SEE ALSO

AUTHOR

Ji-Hyeon Gim <potatogim@gluesys.com>

COPYRIGHT AND LICENSE

This software is copyright 2017-2018 by Ji-Hyeon Gim.

This is free software; you can redistribute it and/or modify it under the same terms as the GPLv2/LGPLv3.

cpanm GlusterFS::GFAPI::FFI::Stat

perl -MCPAN -e shell
install GlusterFS::GFAPI::FFI::Stat