1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
|
<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=windows-1252">
<title>Filesystem Home</title>
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
</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">Filesystem Home</a>
<a href="release_history.html">Releases</a>
<a href="reference.html">Reference</a>
<a href="tutorial.html">Tutorial</a>
<a href="faq.htm">FAQ</a>
<a href="portability_guide.htm">Portability</a>
<a href="v3.html">V3 Intro</a>
<a href="v3_design.html">V3 Design</a>
<a href="deprecated.html">Deprecated</a>
</td>
</tr>
</table>
<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>
with acknowledgements</a></td>
</tr>
</table>
<div align="center">
<center>
<table border="1" cellpadding="10" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td>
<p align="left">This is Version 3 of the Filesystem library. Version 2 is
not longer supported. 1.49.0 was the last release of Boost to supply
Version 2</p>
</td>
</tr>
</table>
</center>
</div>
<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>
<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>
</li>
</ul>
</li>
<li><b>Error handling and reporting via C++ exceptions (the default) or error
codes.</b><br>
<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>
</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>
<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>Finer grained control over operations and error handling is available to
support more complex applications or other cases where throwing exceptions
isn't desired.</li>
</ul>
</li>
</ul>
<p>A proposal,
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1975.html">
N1975</a>, to include Boost.Filesystem in Technical Report 2 has been accepted
by the C++ Standards Committee. That proposal was based on version 2 of
Boost.Filesystem; presumably the final TR2 form will be based on version 3.</p>
<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( "foo" ) == exists( "foo" ) ); //
(1)<br>
<br>
remove_all( "foo" );<br>
assert( !exists( "foo" ) ); // (2)<br>
<br>
assert( is_directory( "foo" ) == is_directory( "foo" ) ); //
(3)</code></p>
</blockquote>
<p>(1) will fail if a non-existent "foo" comes into existence, or an
existent "foo" 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 "foo" is created by another
thread, process, or computer.</p>
<p>(3) will fail if another thread, process, or computer removes an
existing file "foo" and then creates a directory named "foo", between the
example code's two calls to <i>is_directory()</i>.</p>
</blockquote>
<h4><b>May throw exceptions</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 if they cannot successfully complete their operational
specifications. Also, implementations may use C++ Standard Library functions,
which may throw <i>std::bad_alloc</i>. These exceptions may be thrown even
though the error condition leading to the exception is not explicitly specified
in the function's "Throws" paragraph.</p>
<p>All exceptions thrown by the Filesystem
Library are implemented by calling <a href="../../utility/throw_exception.html">
boost::throw_exception()</a>. Thus exact behavior may differ depending on
BOOST_NO_EXCEPTIONS at the time the filesystem source files are compiled.</p>
<p>Non-throwing versions are provided of several functions that are often used
in contexts where error codes may be the preferred way to report an error.</p>
<h2><a name="Headers">Headers</a></h2>
<p>The Boost.Filesystem library provides several headers:</p>
<ul>
<li>Header <<a href="../../../boost/filesystem.hpp">boost/filesystem.hpp</a>>
provides access to all features of the library, except file streams.<br>
</li>
<li>Header <<a href="../../../boost/filesystem/fstream.hpp">boost/filesystem<i>/</i>fstream.hpp</a>>
inherits the same components as the C++ Standard
Library's <i>fstream</i> header, but files are identified by <code>const path&</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>
<h3>Other examples</h3>
<p>The programs used to generate the Boost regression test status tables use the
Filesystem Library extensively. See:</p>
<ul>
<li><a href="../../../tools/regression/src/process_jam_log.cpp">process_jam_log.cpp</a></li>
<li><a href="../../../tools/regression/src/compiler_status.cpp">compiler_status.cpp</a></li>
</ul>
<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.</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 directory <a href="src">libs/filesystem/src</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 3</h3>
<p>Boost <span style="background-color: #FFFF00">1.??.0 - ???, 2010</span> - 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 "illusion
of portability" 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. </p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->20 March, 2012<!--webbot bot="Timestamp" endspan i-checksum="28814" --></p>
<p>© 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>
|
