YSTest: platform::FileDescriptor类 参考

YSTest PreAlpha_b900_20201012 The YSLib Test Project

类 | Public 成员函数 | 静态 Public 成员函数 | Public 属性 | Private 属性 | 所有成员列表
platform::FileDescriptor类 参考

文件描述符包装类。 更多...

`#include <FileIO.h>`

类 platform::FileDescriptor 继承关系图:
[图例]
platform::FileDescriptor 的协作图:
[图例]

## 类

struct | Deleter
| 删除器。 更多...

## Public 成员函数

yconstfn | DefDeCtor (FileDescriptor) yconstfn FileDescriptor(int fd) ynothrow
yconstfn | FileDescriptor (nullptr_t) ynothrow
| FileDescriptor (std::FILE *) ynothrow
| 构造：使用标准流。 更多...
YB_ATTR_nodiscard | PDefHOp (int, *,) const ynothrow ImplRet(desc) YB_ATTR_nodiscard PDefHOp(FileDescriptor *
YB_ATTR_nodiscard ynothrow | ImplRet (this) YB_ATTR_nodiscard PDefHOp(const FileDescriptor *
YB_ATTR_nodiscard ynothrow const ynothrow | ImplRet (this) explicit DefCvt(const ynothrow
YB_ATTR_nodiscard NodeCategory | GetCategory () const ynothrow
| 取节点类别。 更多...
YB_ATTR_nodiscard YB_NORETURN int | GetFlags () const
| 取旗标。 更多...
YB_ATTR_nodiscard mode_t | GetMode () const
| 取模式。 更多...
YB_ATTR_nodiscard FileTime | GetModificationTime () const
| 取修改时间。 更多...
YB_ATTR_nodiscard array< FileTime, 2 > | GetModificationAndAccessTime () const
| 取修改和访问时间。 更多...
YB_ATTR_nodiscard FileNodeID | GetNodeID () const ynothrow
| 取文件系统节点标识。 更多...
YB_ATTR_nodiscard size_t | GetNumberOfLinks () const ynothrow
| 取链接数。 更多...
YB_ATTR_nodiscard std::uint64_t | GetSize () const
| 取大小。 更多...
void | SetAccessTime (FileTime) const
| 设置访问时间。 更多...
YB_NORETURN bool | SetBlocking () const
| 设置阻塞模式。 更多...
YB_NORETURN void | SetFlags (int) const
| 设置旗标。 更多...
YB_NORETURN void | SetMode (mode_t) const
| 设置访问模式。 更多...
void | SetModificationTime (FileTime) const
| 设置修改时间。 更多...
void | SetModificationAndAccessTime (array< FileTime, 2 >) const
| 设置修改和访问时间。 更多...
YB_NORETURN bool | SetNonblocking () const
| 设置非阻塞模式。 更多...
YB_ATTR_nodiscard bool | SetSize (size_t) ynothrow
| 调整文件至指定长度。 更多...
YB_STATELESS int | SetTranslationMode (int) const ynothrow
| 设置翻译模式。 更多...
void | Flush ()
| 刷新。 更多...
| YB_NONNULL (2) size_t FullRead(void *
| 循环读写文件。 更多...
| YB_NONNULL (2) size_t FullWrite(const void *
| YB_NONNULL (2) size_t Read(void *
| 读写文件。 更多...
| YB_NONNULL (2) size_t Write(const void *
void | lock ()
void | lock_shared ()
bool | try_lock () ynothrowv
bool | try_lock_shared () ynothrowv
void | unlock () ynothrowv
void | unlock_shared () ynothrowv

## 静态 Public 成员函数

static | YB_NONNULL (3) void WriteContent(FileDescriptor
| 第二参数内容写入第一参数指定的文件。 更多...
static void | WriteContent (FileDescriptor, FileDescriptor, size_t=yimpl(size_t(BUFSIZ<< 4)))

## Public 属性

YB_ATTR_nodiscard ynothrow const ynothrow | bool
YB_ATTR_nodiscard ynothrow const ynothrow | desc
size_t | ynothrowv
static | FileDescriptor
static byte | size_t

## Private 属性

int | desc = -1

## 详细描述

文件描述符包装类。

注解
  除非另行指定，具有无异常抛出保证的操作失败时可能设置 errno 。
  不支持的平台操作失败设置 errno 为 ENOSYS 。
  除非另行指定，无异常抛出的操作使用值初始化的返回类型表示失败结果。
  以 `int` 为返回值的操作返回 `-1` 表示失败。
  满足 NullablePointer 要求。
  满足共享锁要求。

参见
  WG21 N4606 17.6.3.3[nullablepointer.requirements] 。
  WG21 N4606 30.4.1.4[thread.sharedmutex.requirements] 。

自从
  build 565

在文件 FileIO.h 第 148 行定义.

## 构造及析构函数说明

## ◆ FileDescriptor() [1/2]

yconstfn platform::FileDescriptor::FileDescriptor | ( | nullptr_t |  | ) |

inline

自从
  build 644

在文件 FileIO.h 第 176 行定义.

## ◆ FileDescriptor() [2/2]

platform::FileDescriptor::FileDescriptor | ( | std::FILE * |  | ) |

构造：使用标准流。

注解
  对空参数不设置 errno 。

当参数为空时得到表示无效文件的空描述符，否则调用 POSIX `fileno` 函数。

## 成员函数说明

## ◆ DefDeCtor()

yconstfn platform::FileDescriptor::DefDeCtor | ( | FileDescriptor |  | ) |

inline

在文件 FileIO.h 第 169 行定义.

## ◆ Flush()

void platform::FileDescriptor::Flush | ( |  | ) |

刷新。

异常

  std::system_error | 调用失败。

自从
  build 711

在文件 FileIO.cpp 第 633 行定义.

引用了 YCL_CallF_CAPI.

## ◆ GetCategory()

NodeCategory platform::FileDescriptor::GetCategory | ( |  | ) | const

取节点类别。

返回
  失败时为 NodeCategory::Invalid ，否则为对应类别。

自从
  build 638

在文件 FileIO.cpp 第 435 行定义.

引用了 platform::CategorizeNode(), platform_ex::Windows::CategorizeNode() , 以及 platform_ex::Windows::Invalid.

函数调用图:

## ◆ GetFlags()

int platform::FileDescriptor::GetFlags | ( |  | ) | const

取旗标。

自从
  build 719

注解
  非 POSIX 平台：不支持操作。

在文件 FileIO.cpp 第 447 行定义.

引用了 ystdex::throw_error(), YCL_CallF_CAPI , 以及 yfsig.

函数调用图:

## ◆ GetMode()

mode_t platform::FileDescriptor::GetMode | ( |  | ) | const

取模式。

在文件 FileIO.cpp 第 456 行定义.

引用了 platform::cstat() , 以及 yfsig.

函数调用图:

## ◆ GetModificationAndAccessTime()

array< FileTime, 2 > platform::FileDescriptor::GetModificationAndAccessTime | ( |  | ) | const

取修改和访问时间。

在文件 FileIO.cpp 第 469 行定义.

## ◆ GetModificationTime()

FileTime platform::FileDescriptor::GetModificationTime | ( |  | ) | const

取修改时间。

返回
  以 POSIX 时间相同历元的时间间隔。

注解
  当前 Windows 使用 `::GetFileTime` 实现，其它只保证最高精确到秒。

自从
  build 628

在文件 FileIO.cpp 第 464 行定义.

## ◆ GetNodeID()

FileNodeID platform::FileDescriptor::GetNodeID | ( |  | ) | const

取文件系统节点标识。

注解
  若存储分配失败，设置 errno 为 `ENOMEM` 。

自从
  build 638

在文件 FileIO.cpp 第 474 行定义.

引用了 platform_ex::Windows::QueryFileNodeID().

函数调用图:

## ◆ GetNumberOfLinks()

size_t platform::FileDescriptor::GetNumberOfLinks | ( |  | ) | const

取链接数。

在文件 FileIO.cpp 第 487 行定义.

引用了 platform_ex::Windows::QueryFileLinks() , 以及 CHRLib::size_t().

函数调用图:

## ◆ GetSize()

std::uint64_t platform::FileDescriptor::GetSize | ( |  | ) | const

取大小。

返回
  以字节计算的文件大小。

异常

  std::system_error | 描述符无效或文件大小查询失败。
  std::invalid_argument | 文件大小查询结果小于 0 。

注解
  非常规文件或文件系统实现可能出错。

自从
  build 628

在文件 FileIO.cpp 第 502 行定义.

引用了 platform_ex::Windows::QueryFileSize() , 以及 YCL_CallF_CAPI.

函数调用图:

## ◆ ImplRet() [1/2]

YB_ATTR_nodiscard ynothrow const ynothrow platform::FileDescriptor::ImplRet | ( | this |  | ) | const

## ◆ ImplRet() [2/2]

YB_ATTR_nodiscard ynothrow platform::FileDescriptor::ImplRet | ( | this |  | ) | const

自从
  build 625

## ◆ lock()

void platform::FileDescriptor::lock | ( |  | ) |

前置条件
  间接断言：文件有效。

注解
  DS 平台：无作用。
  POSIX 平台：不使用 POSIX 文件锁而使用 BSD 代替， 以避免无法控制的释放导致安全漏洞。

自从
  build 721

注解
  Win32 平台：对内存映射文件为协同锁，其它文件为强制锁。
  其它平台：协同锁。

警告
  网络或分布式文件系统可能不能正确支持独占锁（如 Andrew File System ）。

异常

  std::system_error | 文件锁定失败。

在文件 FileIO.cpp 第 705 行定义.

引用了 platform_ex::Windows::LockFile() , 以及 YCL_CallF_CAPI.

函数调用图:

## ◆ lock_shared()

void platform::FileDescriptor::lock_shared | ( |  | ) |

在文件 FileIO.cpp 第 716 行定义.

引用了 platform_ex::Windows::LockFile() , 以及 YCL_CallF_CAPI.

函数调用图:

## ◆ PDefHOp()

YB_ATTR_nodiscard platform::FileDescriptor::PDefHOp | ( | int | ,
|  | * |
| ) |  | const

注解
  和 operator-> 不一致，不返回引用，以避免生存期问题。

自从
  build 628
  build 625

## ◆ SetAccessTime()

void platform::FileDescriptor::SetAccessTime | ( | FileTime | ft | ) | const

设置访问时间。

异常

  std::system_error | 设置失败。

注解
  DS 平台：不支持操作。

自从
  build 651

在文件 FileIO.cpp 第 520 行定义.

引用了 platform_ex::Windows::ConvertTime(), platform_ex::Windows::SetFileTime() , 以及 yimpl.

函数调用图:

## ◆ SetBlocking()

bool platform::FileDescriptor::SetBlocking | ( |  | ) | const

设置阻塞模式。

异常

  std::system_error | 调用失败或不支持操作。

注解
  非 POSIX 平台：不支持操作。

自从
  build 719

返回
  是否需要并改变设置。

参见
  http://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html 。

在文件 FileIO.cpp 第 533 行定义.

引用了 platform::bool, ystdex::throw_error() , 以及 yfsig.

函数调用图:

## ◆ SetFlags()

void platform::FileDescriptor::SetFlags | ( | int | flags | ) | const

设置旗标。

在文件 FileIO.cpp 第 547 行定义.

引用了 ystdex::throw_error(), YCL_CallF_CAPI, yfsig , 以及 yunused.

函数调用图:

## ◆ SetMode()

void platform::FileDescriptor::SetMode | ( | mode_t | mode | ) | const

设置访问模式。

在文件 FileIO.cpp 第 558 行定义.

引用了 ystdex::throw_error(), YCL_CallF_CAPI, yfsig , 以及 yunused.

函数调用图:

## ◆ SetModificationAndAccessTime()

void platform::FileDescriptor::SetModificationAndAccessTime | ( | array< FileTime, 2 > | fts | ) | const

设置修改和访问时间。

在文件 FileIO.cpp 第 581 行定义.

引用了 platform_ex::Windows::ConvertTime() , 以及 platform_ex::Windows::SetFileTime().

函数调用图:

## ◆ SetModificationTime()

void platform::FileDescriptor::SetModificationTime | ( | FileTime | ft | ) | const

设置修改时间。

异常

  std::system_error | 设置失败。

注解
  DS 平台：不支持操作。
  Win32 平台：要求打开的文件具有写权限。

自从
  build 651

在文件 FileIO.cpp 第 568 行定义.

引用了 platform_ex::Windows::ConvertTime(), platform_ex::Windows::SetFileTime() , 以及 yimpl.

函数调用图:

## ◆ SetNonblocking()

bool platform::FileDescriptor::SetNonblocking | ( |  | ) | const

设置非阻塞模式。

返回
  是否需要并改变设置。

异常

  std::system_error | 调用失败或不支持操作。

注解
  非 POSIX 平台：不支持操作。
  对不支持非阻塞的文件描述符， POSIX 未指定是否忽略 `O_NONBLOCK` 。

参见
  http://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html 。

自从
  build 719

在文件 FileIO.cpp 第 594 行定义.

引用了 platform::bool, ystdex::throw_error() , 以及 yfsig.

函数调用图:

## ◆ SetSize()

bool platform::FileDescriptor::SetSize | ( | size_t | size | ) |

调整文件至指定长度。

自从
  build 625

前置条件
  指定文件需已经打开并可写。

返回
  是否成功。

注解
  不改变文件读写位置。

若文件不足指定长度，扩展并使用空字节填充；否则保留起始指定长度的字节。

在文件 FileIO.cpp 第 608 行定义.

引用了 size.

## ◆ SetTranslationMode()

int platform::FileDescriptor::SetTranslationMode | ( | int | mode | ) | const

设置翻译模式。

注解
  兼容 Win32 文本模式行为的平台：参数和返回值意义和语义同 `setmode` 函数。
  其它平台：无作用。

自从
  build 637

在文件 FileIO.cpp 第 620 行定义.

引用了 YCL_CallGlobal , 以及 yunused.

## ◆ try_lock()

bool platform::FileDescriptor::try_lock | ( |  | ) |

返回
  是否锁定成功。

在文件 FileIO.cpp 第 727 行定义.

引用了 platform_ex::Windows::TryLockFile() , 以及 YCL_TraceCallF_CAPI.

函数调用图:

## ◆ try_lock_shared()

bool platform::FileDescriptor::try_lock_shared | ( |  | ) |

在文件 FileIO.cpp 第 739 行定义.

引用了 platform_ex::Windows::TryLockFile() , 以及 YCL_TraceCallF_CAPI.

函数调用图:

## ◆ unlock()

void platform::FileDescriptor::unlock | ( |  | ) |

前置条件
  进程对文件访问具有所有权。

在文件 FileIO.cpp 第 751 行定义.

引用了 yfsig.

## ◆ unlock_shared()

void platform::FileDescriptor::unlock_shared | ( |  | ) |

在文件 FileIO.cpp 第 760 行定义.

引用了 yfsig.

## ◆ WriteContent()

void platform::FileDescriptor::WriteContent | ( | FileDescriptor | ofd,
|  | FileDescriptor | ifd,
|  | size_t | size = `yimpl(size_t(BUFSIZ << 4))`
| ) |  |

static

注解
  最后一个参数指定缓冲区大小的上限，若分配失败自动重新分配。

异常

  std::bad_alloc | 缓冲区分配失败。

在文件 FileIO.cpp 第 677 行定义.

引用了 YSLib::Text::buf, ystdex::retry_on_cond(), size, ystdex::to_string(), YAssert, YAssertNonnull, YCL_Raise_SysE , 以及 yfsig.

被这些函数引用 YSLib::IO::CopyFile().

函数调用图:
这是这个函数的调用关系图:

## ◆ YB_NONNULL() [1/5]

platform::FileDescriptor::YB_NONNULL | ( | 2 |  | ) |

循环读写文件。

前置条件
  间接断言：文件有效。
  间接断言：指针参数非空。

注解
  每次读写首先清除 errno ；读写时遇 EINTR 时继续。
  每次读 0 字节时设置 errno 为 0 。

参见
  Read

## ◆ YB_NONNULL() [2/5]

platform::FileDescriptor::YB_NONNULL | ( | 2 |  | ) | const

注解
  每次写 0 字节时设置 errno 为 ENOSPC 。

参见
  Write

## ◆ YB_NONNULL() [3/5]

platform::FileDescriptor::YB_NONNULL | ( | 2 |  | ) |

读写文件。

注解
  首先清除 errno 。
  Win64 平台：大小截断为 32 位。

返回
  若发生错误为 size_t(-1) ，否则为读取的字节数。

## ◆ YB_NONNULL() [4/5]

platform::FileDescriptor::YB_NONNULL | ( | 2 |  | ) | const

## ◆ YB_NONNULL() [5/5]

static platform::FileDescriptor::YB_NONNULL | ( | 3 |  | ) |

static

第二参数内容写入第一参数指定的文件。

前置条件
  断言：文件有效。
  最后参数指定的缓冲区大小不等于 0 。

异常

  std::system_error | 文件读写失败。

自从
  build 634

前置条件
  参数指定的缓冲区非空且大小不等于 0 。

## 类成员变量说明

## ◆ bool

YB_ATTR_nodiscard ynothrow const ynothrow platform::FileDescriptor::bool

在文件 FileIO.h 第 200 行定义.

## ◆ desc [1/2]

int platform::FileDescriptor::desc = -1

private

自从
  build 554

在文件 FileIO.h 第 166 行定义.

## ◆ desc [2/2]

YB_ATTR_nodiscard ynothrow const ynothrow platform::FileDescriptor::desc

初始值:
= -1)
YB_ATTR_nodiscard YB_PURE friend yconstfn PDefHOp(bool, ==,
const FileDescriptor& x, const FileDescriptor& y) ynothrow
ImplRet(x.desc == y.desc)
YB_ATTR_nodiscard YB_PURE friend yconstfn PDefHOp(bool, <,
const FileDescriptor& x, const FileDescriptor& y) ynothrow
ImplRet(x.desc < y.desc)
YB_ATTR_nodiscard FileTime
GetAccessTime() const

在文件 FileIO.h 第 200 行定义.

## ◆ FileDescriptor

platform::FileDescriptor::FileDescriptor

在文件 FileIO.h 第 430 行定义.

## ◆ size_t

byte platform::FileDescriptor::size_t

在文件 FileIO.h 第 430 行定义.

## ◆ ynothrowv

size_t platform::FileDescriptor::ynothrowv

在文件 FileIO.h 第 394 行定义.

该类的文档由以下文件生成:

- FileIO.h
- FileIO.cpp

YB_ATTR_nodiscard
#define YB_ATTR_nodiscard
标记返回值不被忽略的属性。
Definition: ydef.h:715
x
const EncapsulationBase & x
Definition: NPLA1Forms.cpp:1536
YB_PURE
#define YB_PURE
指示函数或函数模板实例为纯函数。
Definition: ydef.h:919
platform::FileDescriptor::FileDescriptor
static FileDescriptor
Definition: FileIO.h:430
platform::FileDescriptor::PDefHOp
YB_ATTR_nodiscard PDefHOp(int, *,) const ynothrow ImplRet(desc) YB_ATTR_nodiscard PDefHOp(FileDescriptor *
platform::ynothrow
const _tString &path ynothrow
Definition: YCLib/FileSystem.h:453
platform::FileDescriptor::desc
int desc
Definition: FileIO.h:166
platform::FileDescriptor::ImplRet
YB_ATTR_nodiscard ynothrow ImplRet(this) YB_ATTR_nodiscard PDefHOp(const FileDescriptor *
YSLib::UI::y
SPos SPos y
Definition: YWidget.cpp:44
const
const Decapsulate const Decapsulate &y ynothrow ContextNode &ctx const
Definition: NPLA1Forms.cpp:1629
yconstfn
#define yconstfn
指定编译时常量函数。
Definition: ydef.h:1073