注意

本文档适用于 Ceph 的开发版本。

LibCephFS (Python)

cephfs Python 模块提供对 CephFS 服务的访问。

API 调用

此模块是 libcephfs 的一个轻量级包装器。

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

libcephfs Python 包装器

abort_conn()

中止 mds 连接。

chdir(path)

更改当前工作目录。

参数:

path -- 要更改到的工作目录的路径。

chmod(path, mode)

更改目录模式。

参数:

  • path -- 要创建的目录的路径。这必须是绝对路径或相对于当前工作目录的相对路径。

  • mode -- 创建后目录应具有的权限。

返回类型:

None

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

更改目录所有权

参数:

  • path -- 要更改的目录的路径。

  • uid -- 要设置的 uid

  • gid -- 要设置的 gid

  • follow_symlink -- 如果 @path 是符号链接（默认），则对目标文件执行操作

close(fd)

关闭打开的文件。

参数:

fd -- 引用打开文件的文件描述符。

closedir(handle)

关闭打开的目录。

参数:

handle -- 打开的目录流句柄

conf_get(option)

将配置值作为字符串获取。

参数:

option -- 要获取的配置选项

conf_parse_argv(argv)

解析命令行参数并加载配置参数。

参数:

argv -- 参数列表

conf_read_file(conffile=None)

从指定的配置文件加载 ceph 配置。

参数:

opt (conffile str) -- ceph.conf 的路径以覆盖默认设置

conf_set(option, val)

从字符串设置配置值。

参数:

  • option -- 要设置的配置选项

  • value -- 要设置的配置选项的值

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

创建一个用于与 Ceph 交互的挂载句柄。所有 libcephfs 函数都对挂载信息句柄进行操作。

参数:

  • opt (conf dict) -- 覆盖默认设置和配置文件的设置

  • optional (conffile Union[int,str],) -- ceph.conf 的路径以覆盖默认设置

Auth_id str opt:

用于验证客户端实体的 ID

debug_get_fd_caps(fd)

获取给定 fd 当前向客户端颁发的功能。

参数:

fd -- 要获取颁发的文件描述符

debug_get_file_caps(path)

获取给定路径当前向客户端颁发的功能。

参数:

path -- 要获取功能的S文件/目录路径。

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

为文件预分配或释放字节范围的磁盘空间。

参数:

  • fd -- 要进行 fallocate 操作的文件描述符。

  • mode -- 标志确定要对给定范围执行的操作。默认操作 (0) 是返回 -EOPNOTSUPP，因为 cephfs 不分配磁盘块来提供写入保证。如果在模式中指定 FALLOC_FL_KEEP_SIZE 标志，则文件大小不会更改。如果在模式中指定 FALLOC_FL_PUNCH_HOLE 标志，则操作是释放空间并清零字节范围。

  • offset -- 字节范围开始。

  • length -- 范围的长度。

fchmod(fd, mode)

根据 fd 更改文件模式。

参数:

  • fd -- 要更改文件模式的文件描述符

  • mode -- 要设置的权限。

fchown(fd, uid, gid)

更改文件所有权

参数:

  • fd -- 要更改所有权的文件描述符

  • uid -- 要设置的 uid

  • gid -- 要设置的 gid

fcopyfile(spath, dpath, mode=0)

将一个文件复制到另一个文件。

参数:

  • spath -- 源文件路径。

  • dpath -- 目标文件路径。

  • mode -- 创建后文件应具有的权限。

fgetxattr(fd, name, size=255)

获取给定文件 fd 的扩展属性。

参数:

  • fd -- 引用文件的打开文件描述符

  • name -- 要获取的扩展属性的名称

  • size -- 预分配缓冲区的大小

flistxattr(fd, size=65536)

列出文件上设置的扩展属性键。

参数:

  • fd -- 引用文件的打开文件描述符。

  • size -- 用于填充扩展属性键的列表缓冲区的大小。

flock(fd, operation, owner)

应用或移除咨询锁。

参数:

  • fd -- 要更改咨询锁的打开文件描述符。

  • operation -- 要对文件执行的咨询锁操作

  • owner -- 用户提供的所有者标识符（任意整数）

fremovexattr(fd, name)

移除文件的扩展属性。

参数:

  • fd -- 引用文件的打开文件描述符。

  • name -- 要移除的扩展属性的名称。

fsetattrx(fd, dict_stx, mask)

设置文件的属性。

参数:

  • path -- 要设置属性的文件/目录的路径。

  • mask -- statx 结构中已设置的所有 CEPH_SETATTR_* 值的掩码。

  • stx -- 必须包含要设置到文件上的属性值的 statx 结构字典。

fsetxattr(fd, name, value, flags)

设置文件的扩展属性。

参数:

  • fd -- 引用文件的打开文件描述符。

  • name -- 要设置的扩展属性的名称。

  • value -- 扩展属性值的字节

fstat(fd)

获取打开文件的扩展统计信息和属性。

参数:

fd -- 要获取统计信息的文件描述符。

fsync(fd, syncdataonly)

将打开的文件同步到持久介质。

参数:

  • fd -- 要同步的文件描述符。

  • syncdataonly -- 一个布尔值，表示是同步元数据和数据 (0) 还是仅同步数据 (1)。

ftruncate(fd, size)

将文件截断为给定大小。如果此操作导致文件扩展，则空字节将填充零。

参数:

  • path -- 要截断的文件的路径。

  • size -- 文件的新大小。

futime(fd, times=None)

设置由描述符指向的文件的访问和修改时间

参数:

  • fd -- 打开文件的文件描述符

  • times -- 如果 times 不为 None，则它必须是一个元组 (atime, mtime)

futimens(fd, times=None)

设置由描述符指向的文件的访问和修改时间

参数:

  • fd -- 打开文件的文件描述符

  • times -- 如果 times 不为 None，则它必须是一个元组 (atime, mtime)

futimes(fd, times=None)

设置由描述符指向的文件的访问和修改时间

参数:

  • fd -- 打开文件的文件描述符

  • times -- 如果 times 不为 None，则它必须是一个元组 (atime, mtime)

get_addrs()

获取与此 RADOS 会话关联的客户端地址。

get_cap_return_timeout()

获取客户端必须返回 caps 的时间量

如果客户端未返回其 caps，MDS 可能会在此超时后将其列入黑名单。应用程序应检查此值并确保将委托超时设置为低于此值的值。

get_default_pool()

获取 cephfs 的默认池名称和 ID。返回 dict{pool_name, pool_id}。

get_file_replication(fd)

从打开的文件描述符获取文件复制信息。

参数:

fd -- 引用要获取复制信息的文件描述符。

get_fscid()

返回此 fs 客户端的文件系统 ID。

get_instance_id()

获取当前实例的全局 ID

get_layout(fd)

从打开的文件描述符获取文件布局。

参数:

fd -- 引用要获取布局的文件描述符。

get_path_replication(path)

获取给定路径的文件复制信息。

参数:

path -- 要获取复制信息的文件/目录路径。

get_pool_id(pool_name)

获取命名池的 ID。

参数:

pool_name -- 池的名称。

get_pool_replication(pool_id)

获取池复制因子。

参数:

pool_id -- 要查找的池 ID

getcwd()

获取当前工作目录。

返回类型:

bytes

返回:

当前工作目录的路径

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

获取扩展属性。

参数:

  • path -- 文件路径

  • name -- 要获取的扩展属性的名称

  • size -- 预分配缓冲区的大小

init()

初始化文件系统客户端（但尚未挂载文件系统）

lazyio(fd, enable)

启用/禁用文件的 lazyio。

参数:

  • fd -- 要启用 lazio 的文件描述符。

  • enable -- 启用 lazyio 或禁用 lazyio 的布尔值。

lazyio_propagate(fd, offset, count)

刷新文件的写入缓冲区，从而将缓冲的写入传播到文件。

参数:

  • fd -- 要同步的文件描述符。

  • offset -- 字节范围开始。

  • count -- 从偏移量开始的字节数。

lazyio_synchronize(fd, offset, count)

刷新文件的写入缓冲区并使读取缓存失效。这允许后续的读取操作直接从文件读取和缓存数据，因此每个人的传播写入都将可见。

参数:

  • fd -- 要同步的文件描述符。

  • offset -- 字节范围开始。

  • count -- 从偏移量开始的字节数。

lchmod(path, mode)

更改文件模式。如果路径是符号链接，它不会被解引用。

参数:

  • path -- 文件路径。这必须是绝对路径或相对于当前工作目录的相对路径。

  • mode -- 要设置的权限。

返回类型:

None

lchown(path, uid, gid)

更改符号链接的所有权

参数:

  • path -- 要更改的符号链接的路径。

  • uid -- 要设置的 uid

  • gid -- 要设置的 gid

lgetxattr(path, name, size=255)

获取扩展属性而不跟随符号链接。此函数与 ceph_getxattr 相同，但如果路径引用符号链接，我们将获取符号链接的扩展属性，而不是它指向的文件的属性。

参数:

  • path -- 文件路径

  • name -- 要获取的扩展属性的名称

  • size -- 预分配缓冲区的大小

创建链接。

参数:

  • existing -- 现有文件/目录的路径，以链接到该文件/目录。

  • newname -- 新文件/目录的路径，以链接自该文件/目录。

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

列出文件上设置的扩展属性键。

参数:

  • path -- 文件路径。

  • size -- 用于填充扩展属性键的列表缓冲区的大小。

llistxattr(path, size=65536)

列出文件上设置的扩展属性键，但不跟随符号链接。

参数:

  • path -- 文件路径。

  • size -- 用于填充扩展属性键的列表缓冲区的大小。

lremovexattr(path, name)

移除文件的扩展属性，但不跟随符号链接。

参数:

  • path -- 文件路径。

  • name -- 要移除的扩展属性的名称。

lseek(fd, offset, whence)

设置文件的当前位置。

参数:

  • fd -- 要从中读取的打开文件描述符。

  • offset -- 要从中读取的文件中的偏移量。如果此值为负，则函数从文件描述符的当前偏移量开始读取。

  • whence -- 指示要执行的查找类型（SEEK_SET、SEEK_CUR、SEEK_END）的标志

lsetxattr(path, name, value, flags)

设置文件的扩展属性，但不跟随符号链接。

参数:

  • path -- 文件路径。

  • name -- 要设置的扩展属性的名称。

  • value -- 扩展属性值的字节

lstat(path)

获取文件的扩展统计信息和属性。如果文件是符号链接，则返回链接本身的信息，而不是它指向的文件的信息。

参数:

path -- 要获取统计信息的文件或目录。

lutimes(path, times=None)

设置文件的访问和修改时间。如果文件是符号链接，则不跟随到目标。

参数:

  • path -- 必须更改时间戳的文件路径

  • times -- 如果 times 不为 None，则它必须是一个元组 (atime, mtime)

mds_command(mds_spec, args, input_data)
返回:

输出状态整数、输出状态字符串、输出数据的 3 元组

mds_command2(result, mds_spec, args, input_data=None, one_shot=False)
参数:

result: 具有 complete 方法的完成对象，接受整数 rc、字节输出和字节错误输出

参数:

mds_spec: 要向其发送命令的一个或多个 MDS 的身份（例如 “*” 或 “fsname:0”）

参数:

args: JSON 编码的 MDS 命令

参数:

input_data: 命令的可选输入数据

参数:

one_shot: 可选布尔值，指示命令是否应只尝试/发送一次

返回:

如果命令已发送/将要发送或引发异常，则为 0

mkdir(path, mode)

创建目录。

参数:

  • path -- 要创建的目录的路径。这必须是绝对路径或相对于当前工作目录的相对路径。

  • mode -- 创建后目录应具有的权限。

mkdirs(path, mode)

一次创建多个目录。

参数:

  • path -- 应创建的目录和子目录的完整路径。

  • mode -- 创建后目录应具有的权限

mknod(path, mode, rdev=0)

创建块或字符特殊文件。

参数:

  • path -- 特殊文件路径。

  • mode -- 要使用的权限和特殊文件的类型。类型可以是 stat.S_IFREG、stat.S_IFCHR、stat.S_IFBLK、stat.S_IFIFO 之一。两者应使用按位 OR 组合。

  • rdev -- 如果文件类型为 stat.S_IFCHR 或 stat.S_IFBLK，则此参数指定新创建的设备特殊文件的主次号。否则，它将被忽略。

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

创建快照。

参数:

  • path -- 要快照的目录路径。

  • name -- 快照名称

  • mode -- 快照权限

  • metadata -- 要与快照一起存储的元数据键/值

引发:
class:

TypeError

引发:
class:

Error

返回类型:

int

返回:

成功时为 0

mount(mount_root=None, filesystem_name=None)

使用路径作为挂载根执行挂载。

open(path, flags, mode=0)

创建和/或打开文件。

参数:

  • path -- 要打开的文件路径。如果 flags 参数包含 O_CREAT，则文件将在打开之前先创建。

  • flags -- 控制文件如何创建/打开的选项掩码集。

  • mode -- 如果文件不存在且 flags 中指定了 O_CREAT，则放置在文件上的权限。

opendir(path)

打开给定目录。

参数:

path -- 要打开的目录的路径名。必须是绝对路径或相对于当前工作目录的路径。

返回类型:

DirResult

返回:

打开的目录流句柄

opensnapdiff(root_path, rel_path, snap1name, snap2name)

打开给定目录。

参数:

path -- 要打开的目录的路径名。必须是绝对路径或相对于当前工作目录的路径。

返回类型:

SnapDiffHandle

返回:

打开的目录流句柄

preadv(fd, buffers, offset)

将数据写入文件。

参数:

  • fd -- 要从中读取的打开文件描述符

  • buffers -- 要从文件中读取的字节对象列表

  • offset -- 文件读取的偏移量。如果此值为负，则函数从文件描述符的当前偏移量开始读取。

pwritev(fd, buffers, offset)

将数据写入文件。

参数:

  • fd -- 要写入的打开文件描述符

  • buffers -- 要写入文件的字节对象列表

  • offset -- 文件写入的偏移量。如果此值为负，则函数从文件描述符的当前偏移量开始写入。

read(fd, offset, l)

从文件读取数据。

参数:

  • fd -- 要从中读取的打开文件描述符。

  • offset -- 要从中读取的文件中的偏移量。如果此值为负，则函数从文件描述符的当前偏移量开始读取。

  • l -- 指示要执行的查找类型的标志

readdir(handle)

获取打开目录中的下一个条目。

参数:

handle -- 打开的目录流句柄

返回类型:

Optional[DirEntry]

返回:

下一个目录条目，如果在目录末尾（或目录为空）则为 None。此指针不应由调用者释放，并且仅在返回和下一次调用 readdir 或 closedir 之间可以安全访问。

读取符号链接。

参数:

  • path -- 要读取的符号链接路径

  • size -- 缓冲区长度

返回类型:

bytes

返回:

用于保存符号链接指向的文件路径的缓冲区。

removexattr(path, name, follow_symlink=True)

移除文件的扩展属性。

参数:

  • path -- 文件路径。

  • name -- 要移除的扩展属性的名称。

rename(src, dst)

重命名文件或目录。

参数:

  • src -- 现有文件或目录的路径。

  • dst -- 文件或目录的新名称。

rewinddir(handle)

将目录流倒回到目录的开头。

参数:

handle -- 打开的目录流句柄

rmdir(path)

移除目录。

参数:

path -- 要移除的目录路径。

rmsnap(path, name)

移除快照。

参数:

  • path -- 要移除快照的目录路径

  • name -- 快照名称

引发:
class:

Error

返回类型:

int

返回:

成功时为 0

rmtree(trash_path, should_cancel, suppress_errors=False)

当 trash_path 是目录时，删除 trash_path 下存在的整个文件层次结构。使用深度优先（防止内存消耗过多）和非递归（防止达到 Python 的最大递归限制错误）方法执行此删除。

如果 trash_path 是 regfile、symlink 或其他东西的路径，则删除它们并返回。

seekdir(handle, offset)

将目录流移动到给定偏移量指定的位置。

参数:

  • handle -- 打开的目录流句柄

  • offset -- 要将目录流移动到的位置。此偏移量应为 telldir 返回的值。请注意，此值不引用目录中的第 n 个条目，不能通过加减操作进行操作。

set_mount_timeout(timeout)

设置挂载超时

参数:

timeout -- 挂载超时

set_session_timeout(timeout)

设置 ceph 客户端会话超时。必须在挂载之前调用。

参数:

timeout -- 要设置的超时

set_uuid(uuid)

设置 ceph 客户端 uuid。必须在挂载之前调用。

参数:

uuid -- 要设置的 uuid

setattrx(path, dict_stx, mask, flags)

设置文件的属性。

参数:

  • path -- 要设置属性的文件/目录的路径。

  • mask -- statx 结构中已设置的所有 CEPH_SETATTR_* 值的掩码。

  • stx -- 必须包含要设置到文件上的属性值的 statx 结构字典。

  • flags -- AT_* 标志的掩码（目前仅支持 AT_ATTR_NOFOLLOW）

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

设置文件的扩展属性。

参数:

  • path -- 文件路径。

  • name -- 要设置的扩展属性的名称。

  • value -- 扩展属性值的字节

shutdown()

卸载并销毁 ceph 挂载句柄。

snap_info(path)

获取快照信息

参数:

path -- 快照路径

引发:
class:

Error

返回类型:

Dict[str, Any]

返回:

快照元数据

stat(path, follow_symlink=True)

获取文件的扩展统计信息和属性。

参数:

path -- 要获取统计信息的文件或目录。

statfs(path)

对 ceph 文件系统执行 statfs。此调用将文件系统范围的统计信息填充到传入的缓冲区中。

参数:

path -- 挂载文件系统内的任何路径

statx(path, mask, flag)

获取文件的扩展统计信息和属性。

参数:

  • path -- 要获取统计信息的文件或目录。

  • mask -- CEPH_STATX_* 标志的位掩码，显示设计的属性。

  • flag -- 可用于设置 AT_* 修饰符标志的位掩码 (AT_STATX_SYNC_AS_STAT, AT_STATX_FORCE_SYNC, AT_STATX_DONT_SYNC 和 AT_SYMLINK_NOFOLLOW)

创建符号链接。

参数:

  • existing -- 现有文件/目录的路径，以链接到该文件/目录。

  • newname -- 新文件/目录的路径，以链接自该文件/目录。

sync_fs()

将所有文件系统数据同步到持久介质

telldir(handle)

获取目录流的当前位置。

参数:

handle -- 打开的目录流句柄

返回值:

目录流的位置。请注意，ceph_telldir 返回的偏移量没有特定的顺序（不能用不等式进行比较）。

truncate(path, size)

将文件截断为给定大小。如果此操作导致文件扩展，则空字节将填充零。

参数:

  • path -- 要截断的文件的路径。

  • size -- 文件的新大小。

移除文件、链接或符号链接。如果文件/链接有多个链接指向它，则在移除所有引用之前，文件不会从命名空间中消失。

参数:

path -- 要取消链接的文件或链接的路径。

unmount()

卸载挂载句柄。

utime(path, times=None)

设置路径的访问和修改时间

参数:

  • path -- 必须更改时间戳的文件路径

  • times -- 如果 times 不为 None，则它必须是一个元组 (atime, mtime)

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

设置路径的访问和修改时间

参数:

  • path -- 必须更改时间戳的文件路径

  • times -- 如果 times 不为 None，则它必须是一个元组 (atime, mtime)

  • follow_symlink -- 如果 @path 是符号链接（默认），则对目标文件执行操作

version()

获取 libcephfs C 库的版本号。

返回:

libcephfs 版本的 (major, minor, extra) 组件元组

write(fd, buf, offset)

将数据写入文件。

参数:

  • fd -- 要写入的打开文件描述符

  • buf -- 要写入文件的字节

  • offset -- 文件写入的偏移量。如果此值为负，则函数从文件描述符的当前偏移量开始写入。

由 Ceph 基金会为您呈现

Ceph 文档是由非营利性 Ceph 基金会 资助和托管的社区资源。如果您希望支持这项工作和我们的其他努力，请考虑 立即加入。