ceph/src/boost/libs/filesystem/doc/index.htm

   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> &nbsp;&nbsp;
  32     <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
  33     <a href="reference.html">Reference</a> &nbsp;&nbsp;
  34     <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
  35     <a href="release_history.html">Releases</a> &nbsp;&nbsp;
  36     <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
  37     <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
  38     <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
  39     <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
  40     <a href="issue_reporting.html">Bug Reports</a>&nbsp;&nbsp;
  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 &nbsp; 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,
  70 and 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
  82 Boost.Filesystem. They like its use of familiar idioms based on standard library
  83 containers, iterators, and algorithms. They like having errors reported by
  84 throwing exceptions.</p>
  85
  86   </blockquote>
  87 </blockquote>
  88 <ul>
  89   <li><b>Portability between operating systems.</b><br>
  90 &nbsp;<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 &nbsp;</li>
  99   </ul>
 100   </li>
 101   <li><b>Error handling and reporting via C++ exceptions (the default) or error
 102   codes.</b><br>
 103 &nbsp;<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 &nbsp;</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 &nbsp;<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 &nbsp;</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
 136 the 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
 139 style of the C++ standard for
 140 every 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
 145 concerned with writing code to run on multiple operating systems.</p>
 146
 147 <p><b><a href="deprecated.html">Deprecated Features</a></b> - Identifies
 148 deprecated features and their replacements.</p>
 149
 150 <p><b><a href="v3.html">Version 3 Introduction</a></b> - Aimed at users of prior
 151 Boost.Filesystem versions.</p>
 152
 153 <p><b><a href="v3_design.html">Version 3 Design</a></b> - Historical document
 154 from the start of the Version 3 design process.</p>
 155
 156 <p><b><a href="design.htm">Original Design</a></b> - Historical document from
 157 the 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
 160 in 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
 164 binaries 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
 168 including filesystem headers is strongly recommended. This prevents inadvertent
 169 use of old features, particularly legacy function names, that have been replaced
 170 and 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,
 173 script-like programs using the Filesystem Library! Before doing any serious
 174 work, 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
 177 effects and postconditions. If
 178 a <a href="reference.html#Race-condition">race-condition</a> exists, a function's
 179 postconditions may no longer be true by the time the function returns to the
 180 caller.</p>
 181 <blockquote>
 182 <p><b><i>Explanation: </i></b>The state of files and directories is often
 183 globally shared, and thus may be changed unexpectedly by other threads,
 184 processes, or even other computers having network access to the filesystem. As an
 185 example of the difficulties this can cause, note that the following asserts
 186 may fail:</p>
 187 <blockquote>
 188 <p><code>assert( exists( &quot;foo&quot; ) == exists( &quot;foo&quot; ) );&nbsp; //
 189 (1)<br>
 190 <br>
 191 remove_all( &quot;foo&quot; );<br>
 192 assert( !exists( &quot;foo&quot; ) );&nbsp; // (2)<br>
 193 <br>
 194 assert( is_directory( &quot;foo&quot; ) == is_directory( &quot;foo&quot; ) ); //
 195 (3)</code></p>
 196 </blockquote>
 197 <p>(1) will fail if a non-existent &quot;foo&quot; comes into existence, or an
 198 existent &quot;foo&quot; is removed, between the first and second call to <i>exists()</i>.
 199 This could happen if, during the execution of the example code, another thread,
 200 process, 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 &quot;foo&quot; is created by another
 203 thread, process, or computer.</p>
 204 <p>(3) will fail if another thread, process, or computer removes an
 205 existing file &quot;foo&quot; and then creates a directory named &quot;foo&quot;, between the
 206 example 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>
 211 exceptions to report failures such as I/O errors. Implementations may also use C++ Standard Library functions
 212 which can throw <i>std::bad_alloc </i>exceptions to report memory allocation
 213 errors. These exceptions may be thrown even
 214 though the error condition leading to the exception is not explicitly specified
 215 in the function's &quot;Throws&quot; paragraph.</p>
 216 <p>Nominally non-throwing versions are provided for
 217 <a href="reference.html#Operational-functions">operational functions</a> that
 218 access the external file system, since these are often used
 219 in contexts where error codes may be the preferred way to report an error. Even
 220 the nominally non-throwing versions of functions will throw <i>std::bad_alloc </i>
 221 exceptions to report memory allocation errors. However, functions marked <code>
 222 noexcept</code> never throw exceptions.</p>
 223
 224 <h2><a name="Headers">Headers</a></h2>
 225
 226 <p>The Boost.Filesystem library provides several&nbsp;headers:</p>
 227
 228 <ul>
 229   <li>Header &lt;<a href="../../../boost/filesystem.hpp">boost/filesystem.hpp</a>&gt;
 230   provides access to all features of the library, except file streams.<br>
 231 &nbsp;</li>
 232   <li>Header &lt;<a href="../../../boost/filesystem/fstream.hpp">boost/filesystem<i>/</i>fstream.hpp</a>&gt;
 233   inherits the same components as the C++ Standard
 234   Library's <i>fstream</i> header, but files are identified by <code>const path&amp;</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
 241 the POSIX or Windows API's.</p>
 242 <p>The library is in regular use on Apple  OS X, HP-UX, IBM AIX, Linux,
 243 Microsoft Windows, SGI IRIX, and Sun Solaris operating systems using a variety
 244 of 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
 247 provided, 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
 275 supported.</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
 278 build system. See
 279 <a href="../../../more/getting_started.html">Getting Started</a>. It can also be
 280 built manually using a <a href="../build/Jamfile.v2">Jamfile</a>
 281 supplied in directory libs/filesystem/build, or the user can construct an IDE
 282 project or make file which includes the object-library source files.</p>
 283 <p>The object-library source files are
 284 supplied in the <a href="../src">src directory</a>. These source files implement the
 285 library for POSIX or Windows compatible operating systems; no implementation is
 286 supplied for other operating systems. Note that many operating systems not
 287 normally thought of as POSIX  systems, such as mainframe legacy
 288 operating systems or embedded operating systems, support POSIX compatible file
 289 systems and so will work with the Filesystem Library.</p>
 290 <p>The object-library can be built for static or dynamic (shared/dll) linking.
 291 This is controlled by the BOOST_ALL_DYN_LINK or BOOST_FILESYSTEM_DYN_LINK
 292 macros. See the <a href="http://www.boost.org/development/separate_compilation.html">Separate
 293 Compilation</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
 296 required 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
 299 thus uses the Windows API and uses Windows path syntax as the native path
 300 syntax.</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
 308 C++ File System Technical Specification</a>. The Filesystem TS is based on
 309 Boost.Filesystem Version 3, with only a small number of changes. Most user code
 310 written 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>.
 315 More uniform error handling.</p>
 316
 317 <p>Peter Dimov suggested use of a single path class rather than a <code>basic_path</code>
 318 class 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
 321 Peele, 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>
 326 template.</p>
 327
 328 <p>So many people have contributed comments and bug reports that it isn't any
 329 longer possible to acknowledge them individually. That said, Peter Dimov and Rob
 330 Stewart need to be specially thanked for their many constructive criticisms and
 331 suggestions. Terence
 332 Wilson and Chris Frey contributed timing programs which helped illuminate
 333 performance 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
 340 original <i>directory_iterator</i> and <i>filesystem_error</i> classes were
 341 based on prior work from Dietmar Kuehl, as modified by Jan Langer. Thomas Witt
 342 was a particular help in later stages of initial development. Peter Dimov and
 343 Rob Stewart made many useful suggestions and comments over a long period of
 344 time. 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
 348 extensive discussions on the Boost mailing list, followed by comments on the
 349 initial implementation. Numerous helpful comments were then received during the
 350 Formal Review.<p>Participants included
 351 Aaron Brashears,
 352 Alan Bellingham,
 353 Aleksey Gurtovoy,
 354 Alex Rosenberg,
 355 Alisdair Meredith,
 356 Andy Glew,
 357 Anthony Williams,
 358 Baptiste Lepilleur,
 359 Beman Dawes,
 360 Bill Kempf,
 361 Bill Seymour,
 362 Carl Daniel,
 363 Chris Little,
 364 Chuck Allison,
 365 Craig Henderson,
 366 Dan Nuffer,
 367 Dan'l Miller,
 368 Daniel Frey,
 369 Darin Adler,
 370 David Abrahams,
 371 David Held,
 372 Davlet Panech,
 373 Dietmar Kuehl,
 374 Douglas Gregor,
 375 Dylan Nicholson,
 376 Ed Brey,
 377 Eric Jensen,
 378 Eric Woodruff,
 379 Fedder Skovgaard,
 380 Gary Powell,
 381 Gennaro Prota,
 382 Geoff Leyland,
 383 George Heintzelman,
 384 Giovanni Bajo,
 385 Glen Knowles,
 386 Hillel Sims,
 387 Howard Hinnant,
 388 Jaap Suter,
 389 James Dennett,
 390 Jan Langer,
 391 Jani Kajala,
 392 Jason Stewart,
 393 Jeff Garland,
 394 Jens Maurer,
 395 Jesse Jones,
 396 Jim Hyslop,
 397 Joel de Guzman,
 398 Joel Young,
 399 John Levon,
 400 John Maddock,
 401 John Williston,
 402 Jonathan Caves,
 403 Jonathan Biggar,
 404 Jurko,
 405 Justus Schwartz,
 406 Keith Burton,
 407 Ken Hagen,
 408 Kostya Altukhov,
 409 Mark Rodgers,
 410 Martin Schuerch,
 411 Matt Austern,
 412 Matthias Troyer,
 413 Mattias Flodin,
 414 Michiel Salters,
 415 Mickael Pointier,
 416 Misha Bergal,
 417 Neal Becker,
 418 Noel Yap,
 419 Parksie,
 420 Patrick Hartling, Pavel Vozenilek,
 421 Pete Becker,
 422 Peter Dimov,
 423 Rainer Deyke,
 424 Rene Rivera,
 425 Rob Lievaart,
 426 Rob Stewart,
 427 Ron Garcia,
 428 Ross Smith,
 429 Sashan,
 430 Steve Robbins,
 431 Thomas Witt,
 432 Tom Harris,
 433 Toon Knapen,
 434 Victor Wagner,
 435 Vincent Finn,
 436 Vladimir Prus, and
 437 Yitzhak Sapir
 438
 439 <p>A lengthy discussion on the C++ committee's library reflector illuminated the &quot;illusion
 440 of portability&quot; 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
 443 version 1.31.0.&nbsp;</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>&copy; Copyright Beman Dawes, 2002-2005</p>
 450 <p> Use, modification, and distribution are subject to the Boost Software
 451 License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">
 452 www.boost.org/LICENSE_1_0.txt</a></p>
 453
 454 </body>
 455
 456 </html>