[ceph.git] / ceph / src / boost / libs / filesystem / doc / index.htm

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Filesystem Home</title>
<link href="styles.css" rel="stylesheet">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
 bordercolor="#111111">
  <tr>
    <td width="277">
<a href="../../../index.htm">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle"
 width="300" height="86" border="0"></a></td>
    <td align="middle">
    <font size="7">Filesystem Library<br>
    Version 3</font>
    </td>
  </tr>
</table>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
 bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  <tr>
    <td><a href="index.htm">Home</a> &nbsp;&nbsp;
    <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
    <a href="reference.html">Reference</a> &nbsp;&nbsp;
    <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
    <a href="release_history.html">Releases</a> &nbsp;&nbsp;
    <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
    <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
    <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
    <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
    <a href="issue_reporting.html">Bug Reports</a>&nbsp;&nbsp;
    </td>
</table>
<p></p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
 bordercolor="#111111" align="right">
  <tr>
    <td width="100%" bgcolor="#D7EEFF" align="center">
      <i><b>Contents</b></i></td>
  </tr>
  <tr>
    <td width="100%" bgcolor="#E8F5FF">
    <a href="#Introduction">Introduction</a><br>
    <a href="#Documentation">Documentation</a><br>
    <a href="#Using">Using the library</a><br>
    <a href="#Coding-guidelines">Coding guidelines</a><br>
    <a href="#Cautions">Cautions</a><br>
    <a href="#Headers">Headers</a><br>
    <a href="#Examples">Example programs</a><br>
    <a href="#Implementation">Implementation</a><br>
    <a href="#Macros">Macros</a><br>
    <a href="#Building">Building the object-library</a><br>
    <a href="#Cgywin">Notes for Cygwin users</a><br>
    <a href="#Change-history">Version history<br>
&nbsp; with acknowledgements</a></td>
  </tr>
  </table>
<p></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>The Boost.Filesystem library provides facilities to manipulate files and directories, 
and the paths that identify them.</p>

<p>The features of the library include:</p>

<ul>
  <li><b>A modern C++ interface, highly compatible with the C++ standard 
  library.</b></li>
</ul>
<blockquote>
  <blockquote>

<p>Many users say the interface is their primary motivation for using 
Boost.Filesystem. They like its use of familiar idioms based on standard library 
containers, iterators, and algorithms. They like having errors reported by 
throwing exceptions.</p>

  </blockquote>
</blockquote>
<ul>
  <li><b>Portability between operating systems.</b><br>
&nbsp;<ul>
    <li>At the C++ syntax level, it is convenient to learn and use one interface 
    regardless of the operating system.</li>
    <li>At the semantic level, behavior of code is reasonably portable across 
    operating systems.</li>
    <li>Dual generic or native path format support encourages program 
    portability, yet still allows communication with users in system specific 
    formats.<br>
&nbsp;</li>
  </ul>
  </li>
  <li><b>Error handling and reporting via C++ exceptions (the default) or error 
  codes.</b><br>
&nbsp;<ul>
    <li>C++ exceptions are the preferred error reporting mechanism for most 
    applications. The exception thrown includes the detailed error code 
    information important for diagnosing the exact cause of file system errors.</li>
    <li>Error reporting via error code allows user code that provides detailed 
    error recovery to avoid becoming so littered with try-catch blocks as to be 
    unmaintainable. <br>
&nbsp;</li>
  </ul>
  </li>
  <li><b>Suitable for a broad spectrum of applications, ranging from simple 
  script-like operations to extremely complex production code.</b><br>
&nbsp;<ul>
    <li>At the simple script-like end of the spectrum, the intent is not to 
    compete with Python, Perl, or shell languages, but rather to provide 
    filesystem operations when C++ is already the language of choice.</li>
    <li dir="ltr">
    <p dir="ltr">Finer grained control over operations and error handling is available to 
    support more complex applications or other cases where throwing exceptions 
    isn't desired.<br>
&nbsp;</li>
  </ul>
  </li>
  <li>
  <p dir="ltr"><b>Forms the basis for
  <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4100.pdf">
  ISO/IEC TS 18822</a>, the C++ standard library Filesystem Technical 
  Specification.</b></li>
</ul>

<h2><a name="Documentation">Documentation</a></h2>

<p><b><a href="tutorial.html">Tutorial</a></b> - A gentle introduction to 
the library, with example programs provided for you to experiment with.</p>

<p><b><a href="reference.html">Reference</a></b> - Formal documentation in the 
style of the C++ standard for 
every component of the library.</p>

<p><b><a href="faq.htm">FAQ</a></b> - Frequently asked questions.</p>

<p><b><a href="portability_guide.htm">Portability Guide</a></b> - Help for those 
concerned with writing code to run on multiple operating systems.</p>

<p><b><a href="deprecated.html">Deprecated Features</a></b> - Identifies 
deprecated features and their replacements.</p>

<p><b><a href="v3.html">Version 3 Introduction</a></b> - Aimed at users of prior 
Boost.Filesystem versions.</p>

<p><b><a href="v3_design.html">Version 3 Design</a></b> - Historical document 
from the start of the Version 3 design process.</p>

<p><b><a href="design.htm">Original Design</a></b> - Historical document from 
the start of the Version 1 design process.</p>

<p><b><a href="do_list.html">Do List</a></b> - Boost.Filesystem development work 
in the pipeline.</p>

<h2><a name="Using">Using</a> the library</h2>
<p>Boost.Filesystem is implemented as a separately compiled library, so  you must install 
binaries in a location that can be found by your linker. If you followed the 
<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>
<h2><a name="Coding-guidelines">Coding guidelines</a></h2>
<p>For new code, defining <code>BOOST_FILESYSTEM_NO_DEPRECATED</code> before 
including filesystem headers is strongly recommended. This prevents inadvertent 
use of old features, particularly legacy function names, that have been replaced 
and are going to go away in the future.</p>
<h2><a name="Cautions">Cautions</a></h2>
<p>After reading the tutorial you can dive right into  simple, 
script-like programs using the Filesystem Library! Before doing any serious 
work, however, there a few cautions to be aware of:</p>
<h4><b>Effects and Postconditions not guaranteed in the presence of race-conditions</b></h4>
<p>Filesystem function specifications follow the C++ Standard Library form, specifying behavior in terms of 
effects and postconditions. If 
a <a href="reference.html#Race-condition">race-condition</a> exists, a function's 
postconditions may no longer be true by the time the function returns to the 
caller.</p>
<blockquote>
<p><b><i>Explanation: </i></b>The state of files and directories is often
globally shared, and thus may be changed unexpectedly by other threads, 
processes, or even other computers having network access to the filesystem. As an 
example of the difficulties this can cause, note that the following asserts 
may fail:</p>
<blockquote>
<p><code>assert( exists( &quot;foo&quot; ) == exists( &quot;foo&quot; ) );&nbsp; // 
(1)<br>
<br>
remove_all( &quot;foo&quot; );<br>
assert( !exists( &quot;foo&quot; ) );&nbsp; // (2)<br>
<br>
assert( is_directory( &quot;foo&quot; ) == is_directory( &quot;foo&quot; ) ); // 
(3)</code></p>
</blockquote>
<p>(1) will fail if a non-existent &quot;foo&quot; comes into existence, or an 
existent &quot;foo&quot; is removed, between the first and second call to <i>exists()</i>. 
This could happen if, during the execution of the example code, another thread, 
process, or computer is also performing operations in the same directory.</p>
<p>(2) will fail if between the call to <i>remove_all()</i> and the call to
<i>exists()</i> a new file or directory named &quot;foo&quot; is created by another 
thread, process, or computer.</p>
<p>(3) will fail if another thread, process, or computer removes an 
existing file &quot;foo&quot; and then creates a directory named &quot;foo&quot;, between the 
example code's two calls to <i>is_directory()</i>.</p>
</blockquote>
<h4>E<b>xceptions</b></h4>
<p>Unless otherwise specified, Boost.Filesystem functions throw <i>
<a href="reference.html#basic_filesystem_error-constructors">basic_filesystem_error</a></i> 
exceptions to report failures such as I/O errors. Implementations may also use C++ Standard Library functions 
which can throw <i>std::bad_alloc </i>exceptions to report memory allocation 
errors. These exceptions may be thrown even 
though the error condition leading to the exception is not explicitly specified 
in the function's &quot;Throws&quot; paragraph.</p>
<p>Nominally non-throwing versions are provided for
<a href="reference.html#Operational-functions">operational functions</a> that 
access the external file system, since these are often used 
in contexts where error codes may be the preferred way to report an error. Even 
the nominally non-throwing versions of functions will throw <i>std::bad_alloc </i>
exceptions to report memory allocation errors. However, functions marked <code>
noexcept</code> never throw exceptions.</p>

<h2><a name="Headers">Headers</a></h2>

<p>The Boost.Filesystem library provides several&nbsp;headers:</p>

<ul>
  <li>Header &lt;<a href="../../../boost/filesystem.hpp">boost/filesystem.hpp</a>&gt; 
  provides access to all features of the library, except file streams.<br>
&nbsp;</li>
  <li>Header &lt;<a href="../../../boost/filesystem/fstream.hpp">boost/filesystem<i>/</i>fstream.hpp</a>&gt; 
  inherits the same components as the C++ Standard 
  Library's <i>fstream</i> header, but files are identified by <code>const path&amp;</code> 
  arguments rather that <code>const char*</code> arguments.</li>
</ul>
<h2><a name="Examples">Example programs</a></h2>
<p>See the <a href="tutorial.html">tutorial</a> for example programs.</p>
<h2><a name="Implementation">Implementation</a></h2>
<p>The current implementation supports operating systems which provide 
the POSIX or Windows API's.</p>
<p>The library is in regular use on Apple  OS X, HP-UX, IBM AIX, Linux, 
Microsoft Windows, SGI IRIX, and Sun Solaris operating systems using a variety 
of compilers. It is also used by several smart phone operating systems.</p>
<h2><a name="Macros">Macros</a></h2>
<p>Users may defined the following macros if desired. Sensible defaults are 
provided, so users can ignore these macros unless they have special needs.</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
  <tr>
    <td><b><i>Macro Name</i></b></td>
    <td><b><i>Default</i></b></td>
    <td><b><i>Effect if defined</i></b></td>
  </tr>
  <tr>
    <td valign="top"><code>BOOST_FILESYSTEM_NO_DEPRECATED</code></td>
    <td valign="top">Not defined.</td>
    <td valign="top">Deprecated features are excluded from headers.</td>
  </tr>
  <tr>
    <td valign="top"><code>BOOST_FILESYSTEM_DYN_LINK</code></td>
    <td valign="top">Defined if <code>BOOST_ALL_DYN_LINK</code> is defined, 
    otherwise not defined.</td>
    <td valign="top">The Boost.Filesystem library is dynamically linked. If not defined, 
    static linking is assumed.</td>
  </tr>
  <tr>
    <td valign="top"><code>BOOST_FILESYSTEM_NO_LIB</code></td>
    <td valign="top">Defined if <code>BOOST_ALL_NO_LIB</code> is defined, 
    otherwise not defined.</td>
    <td valign="top">Boost.Filesystem library does not use the Boost auto-link 
    facility.</td>
  </tr>
  </table>
<p>User-defined BOOST_POSIX_API and BOOST_WINDOWS_API macros are no longer 
supported.</p>
<h2><a name="Building">Building</a> the object-library</h2>
<p>The object-library will  be built automatically if you are using the Boost 
build system. See
<a href="../../../more/getting_started.html">Getting Started</a>. It can also be 
built manually using a <a href="../build/Jamfile.v2">Jamfile</a> 
supplied in directory libs/filesystem/build, or the user can construct an IDE 
project or make file which includes the object-library source files.</p>
<p>The object-library source files are 
supplied in the <a href="../src">src directory</a>. These source files implement the 
library for POSIX or Windows compatible operating systems; no implementation is 
supplied for other operating systems. Note that many operating systems not 
normally thought of as POSIX  systems, such as mainframe legacy 
operating systems or embedded operating systems, support POSIX compatible file 
systems and so will work with the Filesystem Library.</p>
<p>The object-library can be built for static or dynamic (shared/dll) linking. 
This is controlled by the BOOST_ALL_DYN_LINK or BOOST_FILESYSTEM_DYN_LINK 
macros. See the <a href="http://www.boost.org/development/separate_compilation.html">Separate 
Compilation</a> page for a description of the techniques used.</p>
<h3>Note for <a name="Cgywin">Cygwin</a> users</h3>
<p> <a href="http://www.cygwin.com/">Cygwin</a> version 1.7 or later is 
required because only versions of GCC with wide character strings are supported.</p>

<p> The library's implementation code treats Cygwin as a Windows platform, and 
thus uses the Windows API and uses Windows path syntax as the native path 
syntax.</p>

<h2><a name="Change-history">Version history</a></h2>

<h3>Version 4</h3>

<p><b>Under development </b>- Add support for the
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4099.html">ISO 
C++ File System Technical Specification</a>. The Filesystem TS is based on 
Boost.Filesystem Version 3, with only a small number of changes. Most user code 
written for Version 3 should work unchanged with Version 4.</p>

<h3>Version 3</h3>

<p>Boost 1.44.0 - June, 2010 - Internationalization via single class <code>path</code>. 
More uniform error handling.</p>

<p>Peter Dimov suggested use of a single path class rather than a <code>basic_path</code> 
class template. That idea was the basis for the Version 3 redesign.</p>

<p>Thanks for comments from Robert Stewart, Zach Laine, Peter Dimov, Gregory 
Peele, Scott McMurray, John Bytheway, Jeff Flinn, Jeffery Bosboom.</p>

<h3>Version 2</h3>

<p>Boost 1.34.0 - May, 2007 - Internationalization via <code>basic_path</code> 
template.</p>

<p>So many people have contributed comments and bug reports that it isn't any 
longer possible to acknowledge them individually. That said, Peter Dimov and Rob 
Stewart need to be specially thanked for their many constructive criticisms and 
suggestions. Terence 
Wilson and Chris Frey contributed timing programs which helped illuminate 
performance issues.</p>

<h3>Version 1</h3>

<p>Boost 1.30.0 - March, 2003 - Initial official Boost release.</p>

<p>The Filesystem Library was designed and implemented by Beman Dawes. The 
original <i>directory_iterator</i> and <i>filesystem_error</i> classes were 
based on prior work from Dietmar Kuehl, as modified by Jan Langer. Thomas Witt 
was a particular help in later stages of initial development. Peter Dimov and 
Rob Stewart made many useful suggestions and comments over a long period of 
time. Howard Hinnant helped with internationalization issues.</p>

<p>Key <a href="design.htm#Requirements">design requirements</a> and
<a href="design.htm#Realities">design realities</a> were developed during 
extensive discussions on the Boost mailing list, followed by comments on the 
initial implementation. Numerous helpful comments were then received during the 
Formal Review.<p>Participants included 
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 Kuehl,
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, and
Yitzhak Sapir
 
<p>A lengthy discussion on the C++ committee's library reflector illuminated the &quot;illusion 
of portability&quot; problem, particularly in postings by PJ Plauger and Pete Becker.</p>

<p>Walter Landry provided much help illuminating symbolic link use cases for 
version 1.31.0.&nbsp;</p>

<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->25 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38877" --></p>

<p>&copy; Copyright Beman Dawes, 2002-2005</p>
<p> Use, modification, and distribution are subject to the Boost Software 
License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a></p>

</body>

</html>
Commit	Line	Data
7c673cae FG	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,
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	<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
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( "foo" ) == exists( "foo" ) );  //
189	(1)<br>
190	<br>
191	remove_all( "foo" );<br>
192	assert( !exists( "foo" ) );  // (2)<br>
193	<br>
194	assert( 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
198	existent "foo" 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 "foo" 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 "foo" and then creates a directory named "foo", 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 "Throws" 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 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
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 "illusion
440	of 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
443	version 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
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>