文件系统 库 版本 4

介绍

Boost.Filesystem 库提供用于操作文件和目录以及标识它们的路径的设施。

该库的特性包括

• 现代 C++ 接口，与 C++ 标准库高度兼容。

许多用户表示，该接口是他们使用 Boost.Filesystem 的主要动机。他们喜欢它使用基于标准库容器、迭代器和算法的熟悉习惯用法。他们喜欢通过抛出异常来报告错误。

• 跨操作系统可移植性。
   
  • 在 C++ 语法层面，无论操作系统如何，学习和使用一个接口都很方便。
  • 在语义层面，代码的行为在不同操作系统之间具有合理的便携性。
  • 双重通用或原生路径格式支持促进了程序的便携性，但仍允许与用户以系统特定格式进行通信。
     
• 通过 C++ 异常（默认）或错误代码进行错误处理和报告。
   
  • C++ 异常是大多数应用程序首选的错误报告机制。抛出的异常包含详细的错误代码信息，对于诊断文件系统错误的具体原因很重要。
  • 通过错误代码进行错误报告允许用户代码提供详细的错误恢复，而不会因为过多地使用 try-catch 块而变得难以维护。
     
• 适用于广泛的应用，从简单的脚本式操作到极其复杂的生产代码。
   
  • 在简单的脚本式操作端，目的不是与 Python、Perl 或 shell 语言竞争，而是当 C++ 已经是首选语言时提供文件系统操作。

  • 为支持更复杂的应用程序或不希望抛出异常的其他情况，提供了对操作和错误处理更细粒度的控制。
     

• 构成了 ISO/IEC TS 18822 的基础，即 C++ 标准库文件系统技术规范。

文档

教程 - 该库的入门指南，提供示例程序供您试验。

参考 - 以 C++ 标准风格提供的库的每个组件的正式文档。

常见问题 - 常见问题解答。

可移植性指南 - 为关注编写可在多个操作系统上运行的代码的用户提供帮助。

已弃用功能 - 标识已弃用的功能及其替换项。

版本 4 描述 - 与版本 3 的更改摘要。

版本 3 介绍 - 面向先前 Boost.Filesystem 版本的用户。

版本 3 设计 - 来自版本 3 设计过程开始时的历史文档。

原始设计 - 来自版本 1 设计过程开始时的历史文档。

待办事项列表 - Boost.Filesystem 开发工作中正在进行的任务。

使用该库

Boost.Filesystem 实现为单独编译的库，因此您必须将二进制文件安装在链接器可以找到的位置。如果您遵循了 Boost 入门 说明，那么这已经为您完成了。

编码指南

对于新代码，强烈建议在包含文件系统头文件之前定义 BOOST_FILESYSTEM_NO_DEPRECATED。这可以防止不小心使用已被替换且将在未来移除的旧功能，特别是旧函数名称。

注意事项

阅读教程后，您就可以开始使用文件系统库编写简单的脚本式程序了！但在进行任何严肃的工作之前，有几点注意事项需要您了解：

在存在竞争条件的情况下，效果和后置条件不保证

文件系统函数规范遵循 C++ 标准库的格式，以效果和后置条件来指定行为。如果存在 竞争条件，函数返回给调用者时，其后置条件可能不再成立。

解释： 文件和目录的状态通常是全局共享的，因此可能被其他线程、进程，甚至拥有文件系统网络访问权的其他计算机意外更改。作为示例说明这种困难，请注意以下断言可能会失败：

assert( exists( "foo" ) == exists( "foo" ) );  // (1)

remove_all( "foo" );
assert( !exists( "foo" ) );  // (2)

assert( is_directory( "foo" ) == is_directory( "foo" ) ); // (3)

(1) 如果在第一次和第二次调用 exists() 之间，“foo”不存在，或者存在的“foo”被删除，则断言会失败。如果示例代码执行期间，另一个线程、进程或计算机也在同一目录中执行操作，则可能发生这种情况。

(2) 如果在调用 remove_all() 和调用 exists() 之间，另一个线程、进程或计算机创建了一个名为“foo”的新文件或目录，则断言会失败。

(3) 如果在示例代码两次调用 is_directory() 之间，另一个线程、进程或计算机删除了一个现有的文件“foo”，然后创建了一个名为“foo”的目录，则断言会失败。

异常

除非另有规定，Boost.Filesystem 函数会抛出 basic_filesystem_error 异常来报告 I/O 错误等失败。实现也可能使用 C++ 标准库函数，这些函数会抛出 std::bad_alloc 异常来报告内存分配错误。即使导致异常的错误条件未在函数的“Throws”段落中明确指定，也可能会抛出这些异常。

为访问外部文件系统的 操作函数 提供了名义上不抛出异常的版本，因为这些函数通常在错误代码是首选错误报告方式的上下文中被使用。即使是函数名义上不抛出异常的版本，也会抛出 std::bad_alloc 异常来报告内存分配错误。然而，标记为 noexcept 的函数永远不会抛出异常。

头文件

Boost.Filesystem 库提供了几个 头文件

• 头文件 <boost/filesystem.hpp> 提供了对库所有功能的访问，不包括文件流。
   
• 头文件 <boost/filesystem/fstream.hpp> 继承了与 C++ 标准库的 fstream 头文件相同的组件，但文件由 const path& 参数标识，而不是 const char* 参数。

示例程序

有关示例程序，请参阅 教程。

实现

当前实现支持提供 POSIX 或 Windows API 的操作系统。

该库在 Apple OS X、HP-UX、IBM AIX、Linux、Microsoft Windows、SGI IRIX 和 Sun Solaris 操作系统上使用各种编译器，并被定期使用。它也被一些智能手机操作系统使用。

宏

用户可以根据需要定义以下宏。提供了合理的默认值，因此用户可以忽略这些宏，除非他们有特殊需求。

用户定义的 BOOST_POSIX_API 和 BOOST_WINDOWS_API 宏不再受支持。

构建对象库

如果您正在使用 Boost 构建系统，对象库将自动构建。请参阅 入门。也可以使用目录 libs/filesystem/build 中提供的 Jamfile 手动构建，或者用户可以构建一个包含对象库源文件的 IDE 项目或 Makefile。

对象库源文件在 src 目录中提供。这些源文件实现了适用于 POSIX 或 Windows 兼容操作系统的库；不为其他操作系统提供实现。请注意，许多通常不被认为是 POSIX 系统的操作系统，例如大型机遗留操作系统或嵌入式操作系统，都支持 POSIX 兼容的文件系统，因此可以与文件系统库一起工作。

对象库可以为静态或动态（共享/dll）链接构建。这由 BOOST_ALL_DYN_LINK 或 BOOST_FILESYSTEM_DYN_LINK 宏控制。有关所用技术的描述，请参阅 Separate Compilation 页面。

Cygwin 用户 注意事项

需要 Cygwin 版本 1.7 或更高版本，因为仅支持具有宽字符字符串的 GCC 版本。

库的实现代码将 Cygwin 视为 Windows 平台，因此使用 Windows API 并将 Windows 路径语法作为原生路径语法。

版本历史

版本 4

开发中 - 提高与 C++17 中引入的 std::filesystem 的兼容性（原始提案：ISO C++ 文件系统技术规范）。文件系统 TS 基于 Boost.Filesystem 版本 3，只有少量更改。为版本 3 编写的大多数用户代码应在版本 4 中保持不变。差异可以在 单独的章节中看到。

版本 3

Boost 1.44.0 - 2010 年 6 月 - 通过单个类 path 实现国际化。更统一的错误处理。

Peter Dimov 建议使用单个 path 类而不是 basic_path 类模板。这个想法是版本 3 重新设计的依据。

感谢 Robert Stewart、Zach Laine、Peter Dimov、Gregory Peele、Scott McMurray、John Bytheway、Jeff Flinn、Jeffery Bosboom 的评论。

版本 2

Boost 1.34.0 - 2007 年 5 月 - 通过 basic_path 模板实现国际化。

许多人贡献了评论和错误报告，以至于无法再逐一感谢。尽管如此，Peter Dimov 和 Rob Stewart 因其许多建设性的批评和建议而应特别感谢。Terence Wilson 和 Chris Frey 提供了计时程序，有助于阐明性能问题。

版本 1

Boost 1.30.0 - 2003 年 3 月 - 首次正式发布 Boost。

文件系统库由 Beman Dawes 设计和实现。原始的 directory_iterator 和 filesystem_error 类基于 Dietmar Kühl 的先前工作，并由 Jan Langer 修改。Thomas Witt 在早期开发后期提供了特别的帮助。Peter Dimov 和 Rob Stewart 在很长一段时间内提出了许多有用的建议和评论。Howard Hinnant 协助处理了国际化问题。

关键 设计要求和 设计现实是在 Boost 邮件列表中进行了广泛的讨论，然后在初次实施后收到评论而制定的。在正式评审期间收到了许多有益的评论。参与者包括 Aaron Brashears、Alan Bellingham、Aleksey Gurtovoy、Alex Rosenberg、Alisdair Meredith、Andy Glew、Anthony Williams、Baptiste Lepilleur、Beman Dawes、Bill Kempf、Bill Seymour、Carl Daniel、Chris Little、Chuck Allison、Craig Henderson、Dan Nuffer、Dan'l Miller、Daniel Frey、Darin Adler、David Abrahams、David Held、Davlet Panech、Dietmar Kühl、Douglas Gregor、Dylan Nicholson、Ed Brey、Eric Jensen、Eric Woodruff、Fedder Skovgaard、Gary Powell、Gennaro Prota、Geoff Leyland、George Heintzelman、Giovanni Bajo、Glen Knowles、Hillel Sims、Howard Hinnant、Jaap Suter、James Dennett、Jan Langer、Jani Kajala、Jason Stewart、Jeff Garland、Jens Maurer、Jesse Jones、Jim Hyslop、Joel de Guzman、Joel Young、John Levon、John Maddock、John Williston、Jonathan Caves、Jonathan Biggar、Jurko、Justus Schwartz、Keith Burton、Ken Hagen、Kostya Altukhov、Mark Rodgers、Martin Schuerch、Matt Austern、Matthias Troyer、Mattias Flodin、Michiel Salters、Mickael Pointier、Misha Bergal、Neal Becker、Noel Yap、Parksie、Patrick Hartling、Pavel Vozenilek、Pete Becker、Peter Dimov、Rainer Deyke、Rene Rivera、Rob Lievaart、Rob Stewart、Ron Garcia、Ross Smith、Sashan、Steve Robbins、Thomas Witt、Tom Harris、Toon Knapen、Victor Wagner、Vincent Finn、Vladimir Prus 和 Yitzhak Sapir。

C++ 委员会的库反射器上的一次长篇讨论，特别是 PJ Plauger 和 Pete Becker 的帖子，阐明了“可移植性的幻觉”问题。

Walter Landry 在 1.31.0 版本中提供了许多帮助，阐明了符号链接用例。

© Beman Dawes，2002-2005 版权所有

© Andrey Semashev，2021 版权所有

使用、修改和分发受 Boost 软件许可证 1.0 版约束。请参阅 www.boost.org/LICENSE_1_0.txt