LibCephFS (Python)

The cephfs python module provides access to CephFS service.

API calls

This module is a thin wrapper around libcephfs.

class cephfs.DirEntry(d_ino, d_off, d_reclen, d_type, d_name)
class cephfs.LibCephFS

libcephfs python wrapper

abort_conn()

Abort mds connections.

chdir(path)

Change the current working directory.

Parameters

path – the path to the working directory to change into.

chmod(path, mode)

Change directory mode.

Parameters

  • path – the path of the directory to create. This must be either an absolute path or a relative path off of the current working directory.

  • mode – the permissions the directory should have once created.

Return type

None

chown(path, uid, gid, follow_symlink=True)

Change directory ownership

Parameters

  • path – the path of the directory to change.

  • uid – the uid to set

  • gid – the gid to set

  • follow_symlink – perform the operation on the target file if @path is a symbolic link (default)

close(fd)

Close the open file.

Parameters

fd – the file descriptor referring to the open file.

closedir(handle)

Close the open directory.

Parameters

handle – the open directory stream handle

conf_get(option)

Gets the configuration value as a string.

Parameters

option – the config option to get

conf_parse_argv(argv)

Parse the command line arguments and load the configuration parameters.

Parameters

argv – the argument list

conf_read_file(conffile=None)

Load the ceph configuration from the specified config file.

Parameters

opt (conffile str) – the path to ceph.conf to override the default settings

conf_set(option, val)

Sets a configuration value from a string.

Parameters

  • option – the configuration option to set

  • value – the value of the configuration option to set

create(conf=None, conffile=- 1, auth_id=None)

Create a mount handle for interacting with Ceph. All libcephfs functions operate on a mount info handle.

Parameters

  • opt (conf dict) – settings overriding the default ones and conffile

  • optional (conffile Union[int,str],) – the path to ceph.conf to override the default settings

Auth_id str opt

the id used to authenticate the client entity

debug_get_fd_caps(fd)

Get the capabilities currently issued to the client given the fd.

Parameters

fd – the file descriptor to get issued

debug_get_file_caps(path)

Get the capabilities currently issued to the client given the path.

Parameters

path – the path of the file/directory to get the capabilities of.

fallocate(fd, offset, length, mode=0)

Preallocate or release disk space for the file for the byte range.

Parameters

  • fd – the file descriptor of the file to fallocate.

  • mode – the flags determines the operation to be performed on the given range. default operation (0) allocate and initialize to zero the file in the byte range, and the file size will be changed if offset + length is greater than the file size. if the FALLOC_FL_KEEP_SIZE flag is specified in the mode, the file size will not be changed. if the FALLOC_FL_PUNCH_HOLE flag is specified in the mode, the operation is deallocate space and zero the byte range.

  • offset – the byte range starting.

  • length – the length of the range.

fchmod(fd, mode)

Change file mode based on fd.

Parameters

  • fd – the file descriptor of the file to change file mode

  • mode – the permissions to be set.

fchown(fd, uid, gid)

Change file ownership

Parameters

  • fd – the file descriptor of the file to change ownership

  • uid – the uid to set

  • gid – the gid to set

fgetxattr(fd, name, size=255)

Get an extended attribute given the fd of a file.

Parameters

  • fd – the open file descriptor referring to the file

  • name – the name of the extended attribute to get

  • size – the size of the pre-allocated buffer

flistxattr(fd, size=65536)

List the extended attribute keys set on a file.

Parameters

  • fd – the open file descriptor referring to the file.

  • size – the size of list buffer to be filled with extended attribute keys.

flock(fd, operation, owner)

Apply or remove an advisory lock.

Parameters

  • fd – the open file descriptor to change advisory lock.

  • operation – the advisory lock operation to be performed on the file

  • owner – the user-supplied owner identifier (an arbitrary integer)

fremovexattr(fd, name)

Remove an extended attribute of a file.

Parameters

  • fd – the open file descriptor referring to the file.

  • name – name of the extended attribute to remove.

fsetattrx(fd, dict_stx, mask)

Set a file’s attributes.

Parameters

  • path – the path to the file/directory to set the attributes of.

  • mask – a mask of all the CEPH_SETATTR_* values that have been set in the statx struct.

  • stx – a dict of statx structure that must include attribute values to set on the file.

fsetxattr(fd, name, value, flags)

Set an extended attribute on a file.

Parameters

  • fd – the open file descriptor referring to the file.

  • name – the name of the extended attribute to set.

  • value – the bytes of the extended attribute value

fstat(fd)

Get an open file’s extended statistics and attributes.

Parameters

fd – the file descriptor of the file to get statistics of.

fsync(fd, syncdataonly)

Synchronize an open file to persistent media.

Parameters

  • fd – the file descriptor of the file to sync.

  • syncdataonly – a boolean whether to synchronize metadata and data (0) or just data (1).

ftruncate(fd, size)

Truncate the file to the given size. If this operation causes the file to expand, the empty bytes will be filled in with zeros.

Parameters

  • path – the path to the file to truncate.

  • size – the new size of the file.

futime(fd, times=None)

Set access and modification time for a file pointed by descriptor

Parameters

  • fd – file descriptor of the open file

  • times – if times is not None, it must be a tuple (atime, mtime)

futimens(fd, times=None)

Set access and modification time for a file pointer by descriptor

Parameters

  • fd – file descriptor of the open file

  • times – if times is not None, it must be a tuple (atime, mtime)

futimes(fd, times=None)

Set access and modification time for a file pointer by descriptor

Parameters

  • fd – file descriptor of the open file

  • times – if times is not None, it must be a tuple (atime, mtime)

get_addrs()

Get associated client addresses with this RADOS session.

get_cap_return_timeout()

Get the amount of time that the client has to return caps

In the event that a client does not return its caps, the MDS may blocklist it after this timeout. Applications should check this value and ensure that they set the delegation timeout to a value lower than this.

get_default_pool()

Get the default pool name and id of cephfs. This returns dict{pool_name, pool_id}.

get_file_replication(fd)

Get the file replication information from an open file descriptor.

Parameters

fd – the open file descriptor referring to the file to get the replication information of.

get_fscid()

Return the file system id for this fs client.

get_instance_id()

Get a global id for current instance

get_layout(fd)

Get the file layout from an open file descriptor.

Parameters

fd – the open file descriptor referring to the file to get the layout of.

get_path_replication(path)

Get the file replication information given the path.

Parameters

path – the path of the file/directory to get the replication information of.

get_pool_id(pool_name)

Get the id of the named pool.

Parameters

pool_name – the name of the pool.

get_pool_replication(pool_id)

Get the pool replication factor.

Parameters

pool_id – the pool id to look up

getcwd()

Get the current working directory.

Return type

bytes

Returns

the path to the current working directory

getxattr(path, name, size=255, follow_symlink=True)

Get an extended attribute.

Parameters

  • path – the path to the file

  • name – the name of the extended attribute to get

  • size – the size of the pre-allocated buffer

init()

Initialize the filesystem client (but do not mount the filesystem yet)

lazyio(fd, enable)

Enable/disable lazyio for the file.

Parameters

  • fd – the file descriptor of the file for which to enable lazio.

  • enable – a boolean to enable lazyio or disable lazyio.

lazyio_propagate(fd, offset, count)

Flushes the write buffer for the file thereby propogating the buffered write to the file.

Parameters

  • fd – the file descriptor of the file to sync.

  • offset – the byte range starting.

  • count – the number of bytes starting from offset.

lazyio_synchronize(fd, offset, count)

Flushes the write buffer for the file and invalidate the read cache. This allows a subsequent read operation to read and cache data directly from the file and hence everyone’s propagated writes would be visible.

Parameters

  • fd – the file descriptor of the file to sync.

  • offset – the byte range starting.

  • count – the number of bytes starting from offset.

lchmod(path, mode)

Change file mode. If the path is a symbolic link, it won’t be dereferenced.

Parameters

  • path – the path of the file. This must be either an absolute path or a relative path off of the current working directory.

  • mode – the permissions to be set .

Return type

None

lchown(path, uid, gid)

Change ownership of a symbolic link

Parameters

  • path – the path of the symbolic link to change.

  • uid – the uid to set

  • gid – the gid to set

lgetxattr(path, name, size=255)

Get an extended attribute without following symbolic links. This function is identical to ceph_getxattr, but if the path refers to a symbolic link, we get the extended attributes of the symlink rather than the attributes of the file it points to.

Parameters

  • path – the path to the file

  • name – the name of the extended attribute to get

  • size – the size of the pre-allocated buffer

Create a link.

Parameters

  • existing – the path to the existing file/directory to link to.

  • newname – the path to the new file/directory to link from.

listxattr(path, size=65536, follow_symlink=True)

List the extended attribute keys set on a file.

Parameters

  • path – path of the file.

  • size – the size of list buffer to be filled with extended attribute keys.

llistxattr(path, size=65536)

List the extended attribute keys set on a file but do not follow symbolic link.

Parameters

  • path – path of the file.

  • size – the size of list buffer to be filled with extended attribute keys.

lremovexattr(path, name)

Remove an extended attribute of a file but do not follow symbolic link.

Parameters

  • path – path of the file.

  • name – name of the extended attribute to remove.

lseek(fd, offset, whence)

Set the file’s current position.

Parameters

  • fd – the file descriptor of the open file to read from.

  • offset – the offset in the file to read from. If this value is negative, the function reads from the current offset of the file descriptor.

  • whence – the flag to indicate what type of seeking to performs:SEEK_SET, SEEK_CUR, SEEK_END

lsetxattr(path, name, value, flags)

Set an extended attribute on a file but do not follow symbolic link.

Parameters

  • path – the path to the file.

  • name – the name of the extended attribute to set.

  • value – the bytes of the extended attribute value

lstat(path)

Get a file’s extended statistics and attributes. If the file is a symbolic link, return the information of the link itself rather than the information of the file it points to.

Parameters

path – the file or directory to get the statistics of.

lutimes(path, times=None)

Set access and modification time for a file. If the file is a symbolic link do not follow to the target.

Parameters

  • path – file path for which timestamps have to be changed

  • times – if times is not None, it must be a tuple (atime, mtime)

mds_command(mds_spec, args, input_data)
Returns

3-tuple of output status int, output status string, output data

mkdir(path, mode)

Create a directory.

Parameters

  • path – the path of the directory to create. This must be either an absolute path or a relative path off of the current working directory.

  • mode – the permissions the directory should have once created.

mkdirs(path, mode)

Create multiple directories at once.

Parameters

  • path – the full path of directories and sub-directories that should be created.

  • mode – the permissions the directory should have once created

mknod(path, mode, rdev=0)

Make a block or character special file.

Parameters

  • path – the path to the special file.

  • mode – the permissions to use and the type of special file. The type can be one of stat.S_IFREG, stat.S_IFCHR, stat.S_IFBLK, stat.S_IFIFO. Both should be combined using bitwise OR.

  • rdev – If the file type is stat.S_IFCHR or stat.S_IFBLK then this parameter specifies the major and minor numbers of the newly created device special file. Otherwise, it is ignored.

mksnap(path, name, mode, metadata={})

Create a snapshot.

Parameters

  • path – path of the directory to snapshot.

  • name – snapshot name

  • mode – permission of the snapshot

  • metadata – metadata key/value to store with the snapshot

Raises
class

TypeError

Raises
class

Error

Return type

int

Returns

0 on success

mount(mount_root=None, filesystem_name=None)

Perform a mount using the path for the root of the mount.

open(path, flags, mode=0)

Create and/or open a file.

Parameters

  • path – the path of the file to open. If the flags parameter includes O_CREAT, the file will first be created before opening.

  • flags – set of option masks that control how the file is created/opened.

  • mode – the permissions to place on the file if the file does not exist and O_CREAT is specified in the flags.

opendir(path)

Open the given directory.

Parameters

path – the path name of the directory to open. Must be either an absolute path or a path relative to the current working directory.

Return type

DirResult

Returns

the open directory stream handle

preadv(fd, buffers, offset)

Write data to a file.

Parameters

  • fd – the file descriptor of the open file to read from

  • buffers – the list of byte object to read from the file

  • offset – the offset of the file read from. If this value is negative, the function reads from the current offset of the file descriptor.

pwritev(fd, buffers, offset)

Write data to a file.

Parameters

  • fd – the file descriptor of the open file to write to

  • buffers – the list of byte object to write to the file

  • offset – the offset of the file write into. If this value is negative, the function writes to the current offset of the file descriptor.

read(fd, offset, l)

Read data from the file.

Parameters

  • fd – the file descriptor of the open file to read from.

  • offset – the offset in the file to read from. If this value is negative, the function reads from the current offset of the file descriptor.

  • l – the flag to indicate what type of seeking to perform

readdir(handle)

Get the next entry in an open directory.

Parameters

handle – the open directory stream handle

Return type

Optional[DirEntry]

Returns

the next directory entry or None if at the end of the directory (or the directory is empty. This pointer should not be freed by the caller, and is only safe to access between return and the next call to readdir or closedir.

Read a symbolic link.

Parameters

  • path – the path to the symlink to read

  • size – the length of the buffer

Return type

bytes

Returns

buffer to hold the path of the file that the symlink points to.

removexattr(path, name, follow_symlink=True)

Remove an extended attribute of a file.

Parameters

  • path – path of the file.

  • name – name of the extended attribute to remove.

rename(src, dst)

Rename a file or directory.

Parameters

  • src – the path to the existing file or directory.

  • dst – the new name of the file or directory.

rewinddir(handle)

Rewind the directory stream to the beginning of the directory.

Parameters

handle – the open directory stream handle

rmdir(path)

Remove a directory.

Parameters

path – the path of the directory to remove.

rmsnap(path, name)

Remove a snapshot.

Parameters

  • path – path of the directory for removing snapshot

  • name – snapshot name

Raises
class

Error

Return type

int

Returns

0 on success

seekdir(handle, offset)

Move the directory stream to a position specified by the given offset.

Parameters

  • handle – the open directory stream handle

  • offset – the position to move the directory stream to. This offset should be a value returned by telldir. Note that this value does not refer to the nth entry in a directory, and can not be manipulated with plus or minus.

set_mount_timeout(timeout)

Set mount timeout

Parameters

timeout – mount timeout

set_session_timeout(timeout)

Set ceph client session timeout. Must be called before mount.

Parameters

timeout – the timeout to set

set_uuid(uuid)

Set ceph client uuid. Must be called before mount.

Parameters

uuid – the uuid to set

setattrx(path, dict_stx, mask, flags)

Set a file’s attributes.

Parameters

  • path – the path to the file/directory to set the attributes of.

  • mask – a mask of all the CEPH_SETATTR_* values that have been set in the statx struct.

  • stx – a dict of statx structure that must include attribute values to set on the file.

  • flags – mask of AT_* flags (only AT_ATTR_NOFOLLOW is respected for now)

setxattr(path, name, value, flags, follow_symlink=True)

Set an extended attribute on a file.

Parameters

  • path – the path to the file.

  • name – the name of the extended attribute to set.

  • value – the bytes of the extended attribute value

shutdown()

Unmount and destroy the ceph mount handle.

snap_info(path)

Fetch sapshot info

Parameters

path – snapshot path

Raises
class

Error

Return type

Dict[str, Any]

Returns

snapshot metadata

stat(path, follow_symlink=True)

Get a file’s extended statistics and attributes.

Parameters

path – the file or directory to get the statistics of.

statfs(path)

Perform a statfs on the ceph file system. This call fills in file system wide statistics into the passed in buffer.

Parameters

path – any path within the mounted filesystem

statx(path, mask, flag)

Get a file’s extended statistics and attributes.

Parameters

  • path – the file or directory to get the statistics of.

  • mask – want bitfield of CEPH_STATX_* flags showing designed attributes.

  • flag – bitfield that can be used to set AT_* modifier flags (AT_STATX_SYNC_AS_STAT, AT_STATX_FORCE_SYNC, AT_STATX_DONT_SYNC and AT_SYMLINK_NOFOLLOW)

Creates a symbolic link.

Parameters

  • existing – the path to the existing file/directory to link to.

  • newname – the path to the new file/directory to link from.

sync_fs()

Synchronize all filesystem data to persistent media

telldir(handle)

Get the current position of a directory stream.

Parameters

handle – the open directory stream handle

Return value

The position of the directory stream. Note that the offsets returned by ceph_telldir do not have a particular order (cannot be compared with inequality).

truncate(path, size)

Truncate the file to the given size. If this operation causes the file to expand, the empty bytes will be filled in with zeros.

Parameters

  • path – the path to the file to truncate.

  • size – the new size of the file.

Removes a file, link, or symbolic link. If the file/link has multiple links to it, the file will not disappear from the namespace until all references to it are removed.

Parameters

path – the path of the file or link to unlink.

unmount()

Unmount a mount handle.

utime(path, times=None)

Set access and modification time for path

Parameters

  • path – file path for which timestamps have to be changed

  • times – if times is not None, it must be a tuple (atime, mtime)

utimes(path, times=None, follow_symlink=True)

Set access and modification time for path

Parameters

  • path – file path for which timestamps have to be changed

  • times – if times is not None, it must be a tuple (atime, mtime)

  • follow_symlink – perform the operation on the target file if @path is a symbolic link (default)

version()

Get the version number of the libcephfs C library.

Returns

a tuple of (major, minor, extra) components of the libcephfs version

write(fd, buf, offset)

Write data to a file.

Parameters

  • fd – the file descriptor of the open file to write to

  • buf – the bytes to write to the file

  • offset – the offset of the file write into. If this value is negative, the function writes to the current offset of the file descriptor.