文件系统库 版本 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 项目或 make 文件。

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

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

针对 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 建议使用单个路径类而不是 basic_path 类模板。这个想法是 Version 3 重构的基础。

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

Version 2

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

有太多人提供了评论和错误报告，以至于无法再单独对他们表示感谢。也就是说，需要特别感谢 Peter Dimov 和 Rob Stewart 对他们许多建设性的批评和建议。Terence Wilson 和 Chris Frey 贡献了计时程序，这有助于阐明性能问题。

Version 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