1<html> 2 3<head> 4<meta http-equiv="Content-Language" content="en-us"> 5<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<meta name="ProgId" content="FrontPage.Editor.Document"> 7<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 8<title>Filesystem Home</title> 9<link href="styles.css" rel="stylesheet"> 10</head> 11 12<body> 13 14<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" 15 bordercolor="#111111"> 16 <tr> 17 <td width="277"> 18<a href="../../../index.htm"> 19<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" 20 width="300" height="86" border="0"></a></td> 21 <td align="middle"> 22 <font size="7">Filesystem Library<br> 23 Version 3</font> 24 </td> 25 </tr> 26</table> 27 28<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" 29 bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> 30 <tr> 31 <td><a href="index.htm">Home</a> 32 <a href="tutorial.html">Tutorial</a> 33 <a href="reference.html">Reference</a> 34 <a href="faq.htm">FAQ</a> 35 <a href="release_history.html">Releases</a> 36 <a href="portability_guide.htm">Portability</a> 37 <a href="v3.html">V3 Intro</a> 38 <a href="v3_design.html">V3 Design</a> 39 <a href="deprecated.html">Deprecated</a> 40 <a href="issue_reporting.html">Bug Reports</a> 41 </td> 42</table> 43<p></p> 44<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" 45 bordercolor="#111111" align="right"> 46 <tr> 47 <td width="100%" bgcolor="#D7EEFF" align="center"> 48 <i><b>Contents</b></i></td> 49 </tr> 50 <tr> 51 <td width="100%" bgcolor="#E8F5FF"> 52 <a href="#Introduction">Introduction</a><br> 53 <a href="#Documentation">Documentation</a><br> 54 <a href="#Using">Using the library</a><br> 55 <a href="#Coding-guidelines">Coding guidelines</a><br> 56 <a href="#Cautions">Cautions</a><br> 57 <a href="#Headers">Headers</a><br> 58 <a href="#Examples">Example programs</a><br> 59 <a href="#Implementation">Implementation</a><br> 60 <a href="#Macros">Macros</a><br> 61 <a href="#Building">Building the object-library</a><br> 62 <a href="#Cgywin">Notes for Cygwin users</a><br> 63 <a href="#Change-history">Version history<br> 64 with acknowledgements</a></td> 65 </tr> 66 </table> 67<p></p> 68<h2><a name="Introduction">Introduction</a></h2> 69<p>The Boost.Filesystem library provides facilities to manipulate files and directories, 70and the paths that identify them.</p> 71 72<p>The features of the library include:</p> 73 74<ul> 75 <li><b>A modern C++ interface, highly compatible with the C++ standard 76 library.</b></li> 77</ul> 78<blockquote> 79 <blockquote> 80 81<p>Many users say the interface is their primary motivation for using 82Boost.Filesystem. They like its use of familiar idioms based on standard library 83containers, iterators, and algorithms. They like having errors reported by 84throwing exceptions.</p> 85 86 </blockquote> 87</blockquote> 88<ul> 89 <li><b>Portability between operating systems.</b><br> 90 <ul> 91 <li>At the C++ syntax level, it is convenient to learn and use one interface 92 regardless of the operating system.</li> 93 <li>At the semantic level, behavior of code is reasonably portable across 94 operating systems.</li> 95 <li>Dual generic or native path format support encourages program 96 portability, yet still allows communication with users in system specific 97 formats.<br> 98 </li> 99 </ul> 100 </li> 101 <li><b>Error handling and reporting via C++ exceptions (the default) or error 102 codes.</b><br> 103 <ul> 104 <li>C++ exceptions are the preferred error reporting mechanism for most 105 applications. The exception thrown includes the detailed error code 106 information important for diagnosing the exact cause of file system errors.</li> 107 <li>Error reporting via error code allows user code that provides detailed 108 error recovery to avoid becoming so littered with try-catch blocks as to be 109 unmaintainable. <br> 110 </li> 111 </ul> 112 </li> 113 <li><b>Suitable for a broad spectrum of applications, ranging from simple 114 script-like operations to extremely complex production code.</b><br> 115 <ul> 116 <li>At the simple script-like end of the spectrum, the intent is not to 117 compete with Python, Perl, or shell languages, but rather to provide 118 filesystem operations when C++ is already the language of choice.</li> 119 <li dir="ltr"> 120 <p dir="ltr">Finer grained control over operations and error handling is available to 121 support more complex applications or other cases where throwing exceptions 122 isn't desired.<br> 123 </li> 124 </ul> 125 </li> 126 <li> 127 <p dir="ltr"><b>Forms the basis for 128 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4100.pdf"> 129 ISO/IEC TS 18822</a>, the C++ standard library Filesystem Technical 130 Specification.</b></li> 131</ul> 132 133<h2><a name="Documentation">Documentation</a></h2> 134 135<p><b><a href="tutorial.html">Tutorial</a></b> - A gentle introduction to 136the library, with example programs provided for you to experiment with.</p> 137 138<p><b><a href="reference.html">Reference</a></b> - Formal documentation in the 139style of the C++ standard for 140every component of the library.</p> 141 142<p><b><a href="faq.htm">FAQ</a></b> - Frequently asked questions.</p> 143 144<p><b><a href="portability_guide.htm">Portability Guide</a></b> - Help for those 145concerned with writing code to run on multiple operating systems.</p> 146 147<p><b><a href="deprecated.html">Deprecated Features</a></b> - Identifies 148deprecated features and their replacements.</p> 149 150<p><b><a href="v3.html">Version 3 Introduction</a></b> - Aimed at users of prior 151Boost.Filesystem versions.</p> 152 153<p><b><a href="v3_design.html">Version 3 Design</a></b> - Historical document 154from the start of the Version 3 design process.</p> 155 156<p><b><a href="design.htm">Original Design</a></b> - Historical document from 157the start of the Version 1 design process.</p> 158 159<p><b><a href="do_list.html">Do List</a></b> - Boost.Filesystem development work 160in the pipeline.</p> 161 162<h2><a name="Using">Using</a> the library</h2> 163<p>Boost.Filesystem is implemented as a separately compiled library, so you must install 164binaries in a location that can be found by your linker. If you followed the 165<a href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost Getting Started</a> instructions, that's already been done for you.</p> 166<h2><a name="Coding-guidelines">Coding guidelines</a></h2> 167<p>For new code, defining <code>BOOST_FILESYSTEM_NO_DEPRECATED</code> before 168including filesystem headers is strongly recommended. This prevents inadvertent 169use of old features, particularly legacy function names, that have been replaced 170and are going to go away in the future.</p> 171<h2><a name="Cautions">Cautions</a></h2> 172<p>After reading the tutorial you can dive right into simple, 173script-like programs using the Filesystem Library! Before doing any serious 174work, however, there a few cautions to be aware of:</p> 175<h4><b>Effects and Postconditions not guaranteed in the presence of race-conditions</b></h4> 176<p>Filesystem function specifications follow the C++ Standard Library form, specifying behavior in terms of 177effects and postconditions. If 178a <a href="reference.html#Race-condition">race-condition</a> exists, a function's 179postconditions may no longer be true by the time the function returns to the 180caller.</p> 181<blockquote> 182<p><b><i>Explanation: </i></b>The state of files and directories is often 183globally shared, and thus may be changed unexpectedly by other threads, 184processes, or even other computers having network access to the filesystem. As an 185example of the difficulties this can cause, note that the following asserts 186may fail:</p> 187<blockquote> 188<p><code>assert( exists( "foo" ) == exists( "foo" ) ); // 189(1)<br> 190<br> 191remove_all( "foo" );<br> 192assert( !exists( "foo" ) ); // (2)<br> 193<br> 194assert( is_directory( "foo" ) == is_directory( "foo" ) ); // 195(3)</code></p> 196</blockquote> 197<p>(1) will fail if a non-existent "foo" comes into existence, or an 198existent "foo" is removed, between the first and second call to <i>exists()</i>. 199This could happen if, during the execution of the example code, another thread, 200process, or computer is also performing operations in the same directory.</p> 201<p>(2) will fail if between the call to <i>remove_all()</i> and the call to 202<i>exists()</i> a new file or directory named "foo" is created by another 203thread, process, or computer.</p> 204<p>(3) will fail if another thread, process, or computer removes an 205existing file "foo" and then creates a directory named "foo", between the 206example code's two calls to <i>is_directory()</i>.</p> 207</blockquote> 208<h4>E<b>xceptions</b></h4> 209<p>Unless otherwise specified, Boost.Filesystem functions throw <i> 210<a href="reference.html#basic_filesystem_error-constructors">basic_filesystem_error</a></i> 211exceptions to report failures such as I/O errors. Implementations may also use C++ Standard Library functions 212which can throw <i>std::bad_alloc </i>exceptions to report memory allocation 213errors. These exceptions may be thrown even 214though the error condition leading to the exception is not explicitly specified 215in the function's "Throws" paragraph.</p> 216<p>Nominally non-throwing versions are provided for 217<a href="reference.html#Operational-functions">operational functions</a> that 218access the external file system, since these are often used 219in contexts where error codes may be the preferred way to report an error. Even 220the nominally non-throwing versions of functions will throw <i>std::bad_alloc </i> 221exceptions to report memory allocation errors. However, functions marked <code> 222noexcept</code> never throw exceptions.</p> 223 224<h2><a name="Headers">Headers</a></h2> 225 226<p>The Boost.Filesystem library provides several headers:</p> 227 228<ul> 229 <li>Header <<a href="../../../boost/filesystem.hpp">boost/filesystem.hpp</a>> 230 provides access to all features of the library, except file streams.<br> 231 </li> 232 <li>Header <<a href="../../../boost/filesystem/fstream.hpp">boost/filesystem<i>/</i>fstream.hpp</a>> 233 inherits the same components as the C++ Standard 234 Library's <i>fstream</i> header, but files are identified by <code>const path&</code> 235 arguments rather that <code>const char*</code> arguments.</li> 236</ul> 237<h2><a name="Examples">Example programs</a></h2> 238<p>See the <a href="tutorial.html">tutorial</a> for example programs.</p> 239<h2><a name="Implementation">Implementation</a></h2> 240<p>The current implementation supports operating systems which provide 241the POSIX or Windows API's.</p> 242<p>The library is in regular use on Apple OS X, HP-UX, IBM AIX, Linux, 243Microsoft Windows, SGI IRIX, and Sun Solaris operating systems using a variety 244of compilers. It is also used by several smart phone operating systems.</p> 245<h2><a name="Macros">Macros</a></h2> 246<p>Users may defined the following macros if desired. Sensible defaults are 247provided, so users can ignore these macros unless they have special needs.</p> 248<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 249 <tr> 250 <td><b><i>Macro Name</i></b></td> 251 <td><b><i>Default</i></b></td> 252 <td><b><i>Effect if defined</i></b></td> 253 </tr> 254 <tr> 255 <td valign="top"><code>BOOST_FILESYSTEM_NO_DEPRECATED</code></td> 256 <td valign="top">Not defined.</td> 257 <td valign="top">Deprecated features are excluded from headers.</td> 258 </tr> 259 <tr> 260 <td valign="top"><code>BOOST_FILESYSTEM_DYN_LINK</code></td> 261 <td valign="top">Defined if <code>BOOST_ALL_DYN_LINK</code> is defined, 262 otherwise not defined.</td> 263 <td valign="top">The Boost.Filesystem library is dynamically linked. If not defined, 264 static linking is assumed.</td> 265 </tr> 266 <tr> 267 <td valign="top"><code>BOOST_FILESYSTEM_NO_LIB</code></td> 268 <td valign="top">Defined if <code>BOOST_ALL_NO_LIB</code> is defined, 269 otherwise not defined.</td> 270 <td valign="top">Boost.Filesystem library does not use the Boost auto-link 271 facility.</td> 272 </tr> 273 </table> 274<p>User-defined BOOST_POSIX_API and BOOST_WINDOWS_API macros are no longer 275supported.</p> 276<h2><a name="Building">Building</a> the object-library</h2> 277<p>The object-library will be built automatically if you are using the Boost 278build system. See 279<a href="../../../more/getting_started.html">Getting Started</a>. It can also be 280built manually using a <a href="../build/Jamfile.v2">Jamfile</a> 281supplied in directory libs/filesystem/build, or the user can construct an IDE 282project or make file which includes the object-library source files.</p> 283<p>The object-library source files are 284supplied in the <a href="../src">src directory</a>. These source files implement the 285library for POSIX or Windows compatible operating systems; no implementation is 286supplied for other operating systems. Note that many operating systems not 287normally thought of as POSIX systems, such as mainframe legacy 288operating systems or embedded operating systems, support POSIX compatible file 289systems and so will work with the Filesystem Library.</p> 290<p>The object-library can be built for static or dynamic (shared/dll) linking. 291This is controlled by the BOOST_ALL_DYN_LINK or BOOST_FILESYSTEM_DYN_LINK 292macros. See the <a href="http://www.boost.org/development/separate_compilation.html">Separate 293Compilation</a> page for a description of the techniques used.</p> 294<h3>Note for <a name="Cgywin">Cygwin</a> users</h3> 295<p> <a href="http://www.cygwin.com/">Cygwin</a> version 1.7 or later is 296required because only versions of GCC with wide character strings are supported.</p> 297 298<p> The library's implementation code treats Cygwin as a Windows platform, and 299thus uses the Windows API and uses Windows path syntax as the native path 300syntax.</p> 301 302<h2><a name="Change-history">Version history</a></h2> 303 304<h3>Version 4</h3> 305 306<p><b>Under development </b>- Add support for the 307<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4099.html">ISO 308C++ File System Technical Specification</a>. The Filesystem TS is based on 309Boost.Filesystem Version 3, with only a small number of changes. Most user code 310written for Version 3 should work unchanged with Version 4.</p> 311 312<h3>Version 3</h3> 313 314<p>Boost 1.44.0 - June, 2010 - Internationalization via single class <code>path</code>. 315More uniform error handling.</p> 316 317<p>Peter Dimov suggested use of a single path class rather than a <code>basic_path</code> 318class template. That idea was the basis for the Version 3 redesign.</p> 319 320<p>Thanks for comments from Robert Stewart, Zach Laine, Peter Dimov, Gregory 321Peele, Scott McMurray, John Bytheway, Jeff Flinn, Jeffery Bosboom.</p> 322 323<h3>Version 2</h3> 324 325<p>Boost 1.34.0 - May, 2007 - Internationalization via <code>basic_path</code> 326template.</p> 327 328<p>So many people have contributed comments and bug reports that it isn't any 329longer possible to acknowledge them individually. That said, Peter Dimov and Rob 330Stewart need to be specially thanked for their many constructive criticisms and 331suggestions. Terence 332Wilson and Chris Frey contributed timing programs which helped illuminate 333performance issues.</p> 334 335<h3>Version 1</h3> 336 337<p>Boost 1.30.0 - March, 2003 - Initial official Boost release.</p> 338 339<p>The Filesystem Library was designed and implemented by Beman Dawes. The 340original <i>directory_iterator</i> and <i>filesystem_error</i> classes were 341based on prior work from Dietmar Kuehl, as modified by Jan Langer. Thomas Witt 342was a particular help in later stages of initial development. Peter Dimov and 343Rob Stewart made many useful suggestions and comments over a long period of 344time. Howard Hinnant helped with internationalization issues.</p> 345 346<p>Key <a href="design.htm#Requirements">design requirements</a> and 347<a href="design.htm#Realities">design realities</a> were developed during 348extensive discussions on the Boost mailing list, followed by comments on the 349initial implementation. Numerous helpful comments were then received during the 350Formal Review.<p>Participants included 351Aaron Brashears, 352Alan Bellingham, 353Aleksey Gurtovoy, 354Alex Rosenberg, 355Alisdair Meredith, 356Andy Glew, 357Anthony Williams, 358Baptiste Lepilleur, 359Beman Dawes, 360Bill Kempf, 361Bill Seymour, 362Carl Daniel, 363Chris Little, 364Chuck Allison, 365Craig Henderson, 366Dan Nuffer, 367Dan'l Miller, 368Daniel Frey, 369Darin Adler, 370David Abrahams, 371David Held, 372Davlet Panech, 373Dietmar Kuehl, 374Douglas Gregor, 375Dylan Nicholson, 376Ed Brey, 377Eric Jensen, 378Eric Woodruff, 379Fedder Skovgaard, 380Gary Powell, 381Gennaro Prota, 382Geoff Leyland, 383George Heintzelman, 384Giovanni Bajo, 385Glen Knowles, 386Hillel Sims, 387Howard Hinnant, 388Jaap Suter, 389James Dennett, 390Jan Langer, 391Jani Kajala, 392Jason Stewart, 393Jeff Garland, 394Jens Maurer, 395Jesse Jones, 396Jim Hyslop, 397Joel de Guzman, 398Joel Young, 399John Levon, 400John Maddock, 401John Williston, 402Jonathan Caves, 403Jonathan Biggar, 404Jurko, 405Justus Schwartz, 406Keith Burton, 407Ken Hagen, 408Kostya Altukhov, 409Mark Rodgers, 410Martin Schuerch, 411Matt Austern, 412Matthias Troyer, 413Mattias Flodin, 414Michiel Salters, 415Mickael Pointier, 416Misha Bergal, 417Neal Becker, 418Noel Yap, 419Parksie, 420Patrick Hartling, Pavel Vozenilek, 421Pete Becker, 422Peter Dimov, 423Rainer Deyke, 424Rene Rivera, 425Rob Lievaart, 426Rob Stewart, 427Ron Garcia, 428Ross Smith, 429Sashan, 430Steve Robbins, 431Thomas Witt, 432Tom Harris, 433Toon Knapen, 434Victor Wagner, 435Vincent Finn, 436Vladimir Prus, and 437Yitzhak Sapir 438 439<p>A lengthy discussion on the C++ committee's library reflector illuminated the "illusion 440of portability" problem, particularly in postings by PJ Plauger and Pete Becker.</p> 441 442<p>Walter Landry provided much help illuminating symbolic link use cases for 443version 1.31.0. </p> 444 445<hr> 446<p>Revised 447<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->25 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38877" --></p> 448 449<p>© Copyright Beman Dawes, 2002-2005</p> 450<p> Use, modification, and distribution are subject to the Boost Software 451License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt"> 452www.boost.org/LICENSE_1_0.txt</a></p> 453 454</body> 455 456</html> 457
