forked from boostorg/filesystem
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreference.html
3588 lines (3492 loc) · 197 KB
/
reference.html
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
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<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 Library Proposal
</title>
</head>
<body bgcolor="#FFFFFF">
<p>Doc. no. WG21/N1975=06-0045<br>
Date:
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2006-04-04<!--webbot bot="Timestamp" endspan i-checksum="12266" --><br>
Project: Programming Language C++<br>
Reply to: Beman Dawes <<a href="mailto:[email protected]">[email protected]</a>></p>
<h1>Filesystem Library Proposal for TR2 (Revision 3)</h1>
<h2><a name="TOC">Table of Contents</a></h2>
<table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
<tr>
<td width="26%" valign="top"><a href="#Introduction">Introduction</a><br>
<a href="#Motivation">Motivation and Scope</a><br>
<a href="#Impact">Impact on the Standard</a><br>
<a href="#Design">Important Design Decisions</a><br>
<a href="#Text">Proposed Text for TR2</a><br>
<a href="#Text">Introductory chapter</a><br>
<a href="#Diagnostics-library">Diagnostics library chapter</a><br>
<a href="#Diagnostics-library">Filesystem library chapter</a><br>
<a href="#Definitions">Definitions</a><br>
<a href="#Requirements">Requirements</a><br>
<a href="#Requirements-on-programs">Requirements on programs</a><br>
<a href="#Requirements-on-implementations">Requirements</a><br>
<a href="#Requirements-on-implementations">on implementations</a><br>
<a href="#Header-filesystem-synopsis">
Header <filesystem> synopsis</a><br>
<a href="#Path-traits">Path traits</a><br>
<a href="#Class-template-basic_path">
Class template basic_path</a><br>
<a href="#Pathname-formats">Pathname formats</a><br>
<a href="#Pathname-grammar">Pathname grammar</a><br>
<a href="#Filename-conversion">Filename conversion</a><br>
<a href="#basic_path-requirements">Requirements</a> </td>
<td width="35%" valign="top"> Class template basic_path (continued)<br>
<a href="#basic_path-requirements">basic_path constructors</a><br>
<a href="#basic_path-assignments">basic_path assignments</a><br>
<a href="#basic_path-modifiers">basic_path modifiers</a><br>
<a href="#basic_path-inserter-extractor">basic_path operators</a><br>
<a href="#basic_path-observers">basic_path observers</a><br>
<a href="#basic_path-iterators">basic_path iterators</a><br>
<a href="#basic_path-non-member-functions">basic_path non-member functions</a><br>
<a href="#basic_path-inserter-extractor">basic_path inserter and extractor</a><span style="background-color: #FFFFFF"><br>
</span>
<a href="#Class-template-basic_filesystem_error">Class template
basic_filesystem_error</a><br>
<a href="#basic_filesystem_error-constructors">basic_filesystem_error
constructors</a><br>
<a href="#basic_filesystem_error-observers">basic_filesystem_error observers</a><br>
<a href="#Class-template-basic_directory_entry">Class template
basic_directory_entry</a><br>
<a href="#basic_directory_entry-constructors">basic_directory_entry constructors</a><br>
<a href="#basic_directory_entry-modifiers">basic_directory_entry modifiers</a><br>
<a href="#basic_directory_entry-observers">basic_directory_entry observers</a><br>
<a href="#basic_directory_entry-comparisons">basic_directory_entry comparisons</a></td>
<td width="89%" valign="top">Filesystem library chapter (continued)<br>
<a href="#Class-template-basic_directory_iterator">Class template
basic_directory_iterator</a><br>
<a href="#basic_directory_iterator-constructors">basic_directory_iterator
constructors</a><br>
<a href="#Class-template-basic_recursive_directory_iterator">Class template
basic_recursive_directory_iterator</a><br>
<a href="#file_status">Class
file_status</a><br>
<a href="#Non-member-functions">
Non-member operational functions</a><br>
<a href="#Status-functions">Status functions</a><br>
<a href="#Predicate-functions">Predicate functions</a><br>
<a href="#Attribute-functions">Attribute functions</a><br>
<a href="#Operations-functions">Other operations functions</a><br>
<a href="#Convenience-functions">Convenience functions</a><br>
<a href="#header-cerrno">Additions to
header <cerrno></a><br>
<a href="#header-fstream">Additions
to header <fstream></a><br>
<a href="#Suggestions-for-fstream">Suggestions for <code><fstream></code></a><code><br>
</code>
<a href="#Suggestions-for-fstream"> implementations</a><br>
<a href="#Path-decomposition-table">Path decomposition table</a><br>
<a href="#Issues">Issues</a><br>
<a href="#Acknowledgements">Acknowledgements</a><br>
<a href="#References">References</a><br>
<a href="#Revision-History"><span style="background-color: #FFFFFF">Revision
History</span></a></td>
</tr>
</table>
<h2><a name="Introduction">Introduction</a></h2>
<p>This paper proposes addition of a filesystem library component
to the C++ Standard Library Technical Report 2. The proposal is based on the Boost Filesystem Library (see <a href="http://www.boost.org/libs/filesystem">www.boost.org/libs/filesystem</a>).</p>
<p>The library provides portable facilities to query and
manipulate paths, files, and directories. The Boost version of the library is widely used. It would
be a pure addition to the C++ standard, leaving in place existing
standard library functionality in the relatively few areas where there is overlap.</p>
<p>Users say they prefer the Boost Filesystem Library interface to native
operating system or
<i>POSIX</i> API's, even in code without portability requirements, because the design
follows modern C++ practice.</p>
<p>The proposed text includes an <a href="#Example-program">example</a> of a
program using the library.</p>
<h2><a name="Motivation">Motivation</a> and Scope</h2>
<p><b><i>Why is this important? </i></b></p>
<p>The motivation for the library is the desire to perform <i><b>safe, portable, script-like filesystem operations</b></i> from within C++ programs. Because the
C++ Standard Library currently contains no facilities for such filesystem tasks
as directory iteration or directory creation, programmers currently must rely on
operating system specific interfaces, making it difficult to write
portable programs.</p>
<p>The intent is not to compete
with Python, Perl, or shell scripting languages, but rather to provide
file system operations where C++ is already the language of choice. The design
encourages, but does not require, safe and portable usage.</p>
<p><b><i>What kinds of problems does it address, and what kinds of programmers is
it intended to support?</i></b></p>
<p>The library addresses everyday needs, for both application programs and
libraries. It is useful across every application domain that uses files. It is
intended to be useful to all levels of programmers, from rank beginners to
seasoned experts.</p>
<p><b><i>Is it based on existing practice?</i></b></p>
<p>Yes, very much so. The proposal is based on the Boost Filesystem Library,
which has been in use since 2002 and by now is in very wide use.</p>
<p>Note, however, that until recently all the Boost experience was with a
narrow-character only version of the library. The internationalized version as
described in this proposal is just starting to be used, and will not be fully
released until Boost release 1.34.</p>
<p>The underlying mechanisms have been in use for decades on the world's most
wide-spread operating systems, such as <i>POSIX</i>, <i>Windows</i>, and various
mainframe operating systems. What this proposal brings to the table is an
approach that is C++
Standard Library friendly and fully internationalized.</p>
<p><b><i>Is there a reference implementation?</i></b></p>
<p>Yes. The Boost Filesystem Library is freely and publicly available. The Boost library will track the TR2 proposed
library as the proposal evolves.</p>
<h2><a name="Impact">Impact</a> on the Standard</h2>
<p><b><i>What does it depend on, and what depends on it?</i></b></p>
<p>It depends on
some standard library components, such as basic_string. No other proposals
depend on it.</p>
<p>If a revision to the Code Conversion Proposal (See
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1683.html">
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1683.html</a>) is
accepted, it may be advantageous for the Filesystem Library
to use that library rather than the current code conversion facilities proposed
below.</p>
<p><b><i>Is it a pure extension, or does it require changes to standard
components?</i></b></p>
<p>Most of the proposed library is a pure extension.</p>
<p>There are <a href="#header-cerrno">additions to header <cerrno></a>. Since
the critical portions that might require change to C headers (always a sore
point) are already mandated for <i>POSIX</i> compliance, and represent
existing practice for many non-<i>POSIX</i> operating systems such as for <i>Windows</i>, it is not expected that they will cause any problems.</p>
<p>There are <a href="#header-fstream">additions to header <fstream></a>.
These have been carefully specified to avoid breaking existing code in common operating environments such as <i>POSIX</i>, <i>
Windows</i>, and <i>OpenVMS</i>. See <a href="#Suggestions-for-fstream">
Suggestions for <code><fstream></code> implementations</a> for techniques to
avoid breaking existing code in other environments, particularly on operating
systems allowing slashes in filenames.</p>
<p><b><i>Can it be implemented using today's compilers, or does it require
language features that will only be available as part of C++0x?</i></b></p>
<p>It can
be (and has been) implemented with today's compilers.</p>
<p>There is one minor function that can best be implemented by an addition to
current C++ runtime libraries, although an acceptable workaround is documented.</p>
<p>On operating systems with built-in support for wide-character file names,
such as <i>Windows</i>, high-quality implementation of the header <fstream>
additions require an addition to the C++ Standard Library implementation. The
addition is relatively small and localized, and is already supplied by the most
recent Dinkumware implementation of the Standard Library. There is a workaround that avoids
modifying the standard library, but it is very much a hack and depends on a <i>
Windows</i> feature (8.3 filename support) which some users disable, thereby
disabling the workaround. The issue doesn't affect implementations on operating
systems which only support narrow character file names.</p>
<h2>Important <a name="Design">Design</a> Decisions</h2>
<h4><i>Why did you choose the specific design that you did?</i></h4>
<p>Many of the specific design decisions were driven by the desire to provide a modern C++ interface
that works
well with the C++ Standard Library. The intent is that Standard Library users
can become comfortable with the Filesystem Library in very short order.</p>
<p>The proposed library encourages both syntactic and semantic portability, yet
does not force implementors into heroic efforts on hopeless systems. This
balances the benefits to users of both code and knowledge portability with the
realities faced by implementors on some operating systems.</p>
<p><span style="background-color: #FFFFFF">In some
cases users always need portable semantics. In some cases users always need
platform specific semantics. In some cases users need to be able to choose
between portable and platform specific semantics. The design evolved over a
period of years to identify and meet each of those needs. </span></p>
<p>Because of the desire to support simple "script-like" usage, use cases often
drove design choices. For example, users can write <code>if (exists("foo"))</code> rather than
the lengthier <code>if (exists(path("foo")))</code>.</p>
<p>Because filesystem operations often encounter unexpected runtime errors, the library
by default reports runtime errors via C++ exceptions,
and ensures enough information is provided for meaningful error messages,
including internationalized error messages.</p>
<p><b><i>What alternatives did you consider, and what are the tradeoffs?</i></b></p>
<p><i>Additional observers and modifiers for file system attributes.</i>
Attribute functions which cannot supply portable semantics are not provided,
avoiding the illusion of portability in cases where it cannot in fact exist.</p>
<p><i>A larger number of operational convenience functions.</i>
Convenience functions (functions which can be portably created by composition
from basic functions) were not provided unless there was widespread agreement on
usefulness and need.</p>
<p><i>Compile-time or run-time options for operational functions.</i>
Numerous trial implementations were abandoned because the added complexity
out-weighed the benefits, and because consensus could not be reached on the
feature set.</p>
<p><i>Automatic path name checking.</i> This feature, supplied by the Boost
library for several years, allowed users to specify both default and per
constructor path name checking, and thus allowed the desired degree of portability to be
automatically enforced. This implicit name checking was abandoned because of user
confusion and complaints of excessive nannyism..</p>
<p><i>Separate path types for regular file and directory pathnames.</i> Pathname
formats that use different syntax for regular pathnames versus directory
pathnames are passing into extinction. Why prolong the agony at the cost of
torturing those using modern systems? It is perhaps significant that one of the few web
sites dedicated to preserving a dual pathname format operating system is named
<i>Deathrow</i> (<a href="http://deathrow.vistech.net/">http://deathrow.vistech.net/</a>).</p>
<p><i>Single path type which can at runtime accept narrow or wide character
pathnames.</i> Although certainly interesting, and possibly superior, such a
design would not interoperate well with the current Standard Library's compile-time
typed <code>basic_string</code>. A new runtime polymorphic string class would be
the best place to experiment with this concept, not a path class.</p>
<p><b><i>What are the consequences of your choices, for users and implementors?</i></b></p>
<p>The design has evolved over a period of four years of actual experience by
Boost users, and the most frequent causes of user complaints (such as enforced
name-checking and several over-strict preconditions) were eliminated. The TR
process will allow further refinement. The intent is to ensure user needs are
met.</p>
<p>Because the Boost implementation is tested and
used in a wide range of <i>POSIX</i> and <i>Windows</i> environments, many implementation
concerns have already been addressed.</p>
<p><b><i>What decisions are left up to implementors?</i></b></p>
<p>Because implementations of the library are dependent on facilities of the
underlying operating system, implementors are given unusual freedom to redefine
semantics of the library. That being said, implementors are given strong
normative encouragement to provide the TR described semantics whenever feasible.</p>
<p><b><i>If there are any similar libraries in use, how do their design
decisions compare to yours?</i></b></p>
<p>There are a number of libraries which address the problem domain. Most of the
C/C++ libraries have C, rather than C++ interfaces. For example, see the Apache Portable Runtime
Project (<a href="http://apr.apache.org">http://apr.apache.org</a>). The ACE
toolkit (<a href="http://www.cs.wustl.edu/~schmidt/ACE.html">http://www.cs.wustl.edu/~schmidt/ACE.html</a>)
uses a C++ approach, but doesn't mesh well with the C++ Standard Library. For
example, the ACE directory iterator differs greatly from Standard Library
iterator requirements.</p>
<h2>Proposed <a name="Text">Text</a> for Technical Report 2</h2>
<p><span style="font-style: italic; background-color: #E0E0E0">Gray-shaded
italic text is commentary on the proposal. It is not to be added to the TR.</span></p>
<p><span style="background-color: #FFFFFF"><i>Italic text is editorial guidance.
It is not to be added to the TR.</i></span></p>
<p><span style="font-style: italic; background-color: #FFFFFF">
<a name="frontmatter">Add</a> to the
introductory section of the TR:</span></p>
<p>The following standard contains provisions which, through reference in this
text, constitute provisions of this Technical Report. At the time of
publication, the editions indicated were valid. All standards are subject to
revision, and parties to agreements based on this Technical Report are
encouraged to investigate the possibility of applying the most recent editions
of the standard indicated below. Members of IEC and ISO maintain registers of
currently valid International Standards.</p>
<ul>
<li>ISO/IEC 9945:2003, <i>Portable Operating System Interface (POSIX<a href="#Footnote-1"><sup>1</sup></a>),
part 1 (Base Definitions) and part 2 (System Interfaces)</i>, both as corrected by their
respective 2004 Correction 1 documents.<p>[<i>Note:</i> ISO/IEC 9945:2003 is
also IEEE Std 1003.1-2001, and The Open Group Base Specifications, Issue 6,
and is also known as The Single Unix<font face="Times New Roman"><sup><a href="#Footnote-2">2</a></sup><i><b>
</b></i>Specification, Version 3. It is available from each of those organizations,
and may be read online or downloaded from
<a href="http://www.unix.org/single_unix_specification/">
www.unix.org/single_unix_specification/</a> <i>-- end note</i>]</font></p>
</li>
</ul>
<p>ISO/IEC 9945:2003, with the indicated corrections, is hereinafter called <i>
POSIX</i>.</p>
<p>Some library behavior in this Technical Report is defined by reference to <i>
POSIX</i>. How such behavior is actually implemented is unspecified.</p>
<blockquote>
<p>[<i>Note:</i> This constitutes an "as if" rule for implementation of
operating system dependent behavior. Presumably implementations will usually call native
operating system API's. <i>--end note</i>]</p>
</blockquote>
<p>Implementations are encouraged, but not required, to support such behavior
as it is defined by <i>POSIX</i>. Implementations shall document any
behavior that differs from the <i>POSIX</i> defined behavior. Implementations that do not support exact <i>POSIX</i> behavior are
encouraged to provide behavior as close to <i>POSIX</i> behavior as is reasonable given the
limitations of actual operating systems. If an implementation cannot provide any
reasonable behavior, the implementation shall report an error in an
implementation-defined manner.</p>
<blockquote>
<p>[<i>Note:</i> Such errors might be reported by an #error directive, a <code>
static_assert</code>, a <code>basic_filesystem_error</code> exception, a special
return value, or some other manner. <i>--end note</i>]</p>
</blockquote>
<p><a name="Footnote-1">Footnote 1</a>: <i>POSIX</i>® is a registered trademark of The
IEEE.</p>
<p><a name="Footnote-2">Footnote 2</a>: <i>UNIX</i>® is a registered trademark of The
Open Group.</p>
<p><span style="background-color: #FFFFFF"><i>Add a new clause to the TR:</i></span></p>
<hr>
<h2>Chapter <span style="font-weight: 400"><i>(tbs)</i></span> -
<a name="Diagnostics-library">Diagnostics library</a></h2>
<hr>
<p>This clause describes components that C++ programs may use to detect and
report error conditions.</p>
<h3>Header <code><system_error></code></h3>
<pre>namespace std
{
namespace tr2
{
namespace sys
{
typedef <i>implementation-defined</i> system_error_type;
typedef int errno_type; // determined by C standard
system_error_type system_code(errno_type err);
errno_type iso_code(system_error_type err);
std::string& system_message(error_code err, std::string& target);
std::wstring& system_message(error_code err, std::wstring& target);
enum iso_t { iso };
class error_code;
class system_error;
} // namespace sys
} // namespace tr2
} // namespace std</pre>
<p>Type <code>system_error_type</code> is the implementation-defined type used
by the operating system to report error codes.</p>
<blockquote>
<p>[<i>Note:</i> On POSIX, <code>system_error_type</code> is normally <code>int</code>.
On Windows it is normally <code>unsigned int</code>. This type might differ if
the implementation is built on an emulation<i> </i>layer such as Cygwin. <i>--
end note</i>]</p>
</blockquote>
<pre>system_error_type system_code(errno_type err);</pre>
<blockquote>
<p><i>Returns:</i> An <code>system_error_type</code> value corresponding to
<code>err</code>.</p>
<p>[<i>Note:</i> There is no guarantee that for a value <code>err</code> of type
<code>errno_type</code>, <code>err == iso_code( system_code(err) )</code>. <i>--
end note</i>]</p>
</blockquote>
<pre>errno_type iso_code(system_error_type err);</pre>
<blockquote>
<p><i>Returns:</i> An <code>errno_type</code> value corresponding to <code>err</code>.</p>
<p>[<i>Note:</i> There is no guarantee that for a value <code>err</code> of type
<code>system_error_type</code>, <code>err == system_code( iso_code(err) )</code>.
<i>-- end note</i>]</p>
</blockquote>
<pre>std::string& system_message(error_code err, std::string& target);
std::wstring& system_message(error_code err, std::wstring& target);</pre>
<blockquote>
<p><i>Effects: </i>Appends to <code>target</code> an operating system specific
and locale specific message corresponding to <code>err.system()</code>.</p>
<p><i>Returns:</i> <code>target</code>.</p>
<p><i>Remarks:</i> Implementors and users are permitted to supply additional
overloads in namespace <code>std::tr2::sys</code>.</p>
</blockquote>
<h3>Class <code>error_code</code></h3>
<pre>namespace std
{
namespace tr2
{
namespace sys
{
class error_code
{
public:
error_code();
error_code(system_error_type err);
error_code(errno_type err, iso_t);
system_error_type system() const;
void system(system_error_type err);
errno_type iso() const;
void iso(errno_type err);
bool error() const;
bool operator==(error_code rhs) const;
};
} // namespace sys
} // namespace tr2
} // namespace std</pre>
<p>The class <code>error_code</code> defines the type of objects used to
identify specific errors originating from the operating system.</p>
<pre>error_code();</pre>
<blockquote>
<p><i>Postcondition:</i> <code>!error()&& iso()==0</code>, and <code>system()</code>
returns the value used by the operating system to represent not an error. </p>
</blockquote>
<pre>error_code(system_error_type err);</pre>
<blockquote>
<p><i>Postcondition:</i> <code>system()==err</code>.</p>
</blockquote>
<pre>error_code(errno_type err, iso_t);</pre>
<blockquote>
<p><i>Postcondition:</i> <code>iso()==err</code>.</p>
</blockquote>
<pre>system_error_type system() const;</pre>
<blockquote>
<p><i>Returns:</i> If the most recent non-const function called, or the
constructor if no non-const function has been called, had an <code>err</code>
argument of type <code>system_error_type</code>, then return that argument.
Otherwise, return <code>system_code(iso())</code>.</p>
</blockquote>
<pre>void system(system_error_type err);</pre>
<blockquote>
<p><i>Postcondition:</i> <code>system()==err</code>.</p>
</blockquote>
<pre>errno_type iso() const;</pre>
<blockquote>
<p><i>Returns:</i> If the most recent non-const function called, or the
constructor if no non-const function has been called, had an <code>err</code>
argument of type <code>errno_type</code>, then return that argument.
Otherwise, return <code>iso_code(system())</code>.</p>
</blockquote>
<pre>void iso(errno_type err);</pre>
<blockquote>
<p><i>Postcondition:</i> <code>iso()==err</code>.</p>
</blockquote>
<pre>bool error() const;</pre>
<blockquote>
<p><i>Returns:</i> <code>system()==error_code(x),</code> where <code>x</code>
is the value used by the operating system to represent not an error.</p>
</blockquote>
<pre>bool operator==(error_code rhs) const;</pre>
<blockquote>
<p><i>Returns:</i> <code>system()==rhs.system()</code>.</p>
</blockquote>
<h3>Class <code>system_error</code></h3>
<pre>namespace std
{
namespace tr2
{
namespace sys
{
class system_error : public std::runtime_error
{
public:
system_error(const std::string & what_arg, error_code ec);
error_code code() const;</pre>
<pre> const char * what() const;
};
} // namespace sys
} // namespace tr2
} // namespace std</pre>
<p>The class <code>system_error</code> defines the type of objects thrown as
exceptions to report errors originating from the operating system.</p>
<pre>system_error(const std::string & what_arg, error_code ec);</pre>
<blockquote>
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
<p><i>Postcondition:</i> <code>strcmp(runtime_error::what(), what_arg .c_str()) == 0 &&
code() == ec</code>.</p>
</blockquote>
<pre>error_code code() const;</pre>
<blockquote>
<p><i>Returns:</i> the <code>ec</code> constructor argument.</p>
</blockquote>
<pre>const char * what() const;</pre>
<blockquote>
<p><i>Returns: </i>A string containing <code>runtime_error::what()</code> and
the result of calling <code>system_message()</code> with a first argument of
<code>code()</code>. The exact format is unspecified.</p>
</blockquote>
<p><span style="background-color: #FFFFFF"><i>Add a new clause to the TR:</i></span></p>
<hr>
<h2>Chapter <span style="font-weight: 400"><i>(tbs)</i></span> - <a name="Filesystem-library">Filesystem library</a></h2>
<hr>
<p>This clause describes components that C++ programs may use to interrogate and
manipulate files (including directories), and certain of their
attributes.</p>
<p>This clause applies only to hosted implementations (C++ Std, 1.4,
Implementation compliance [intro.compliance]).</p>
<blockquote>
<p>[<i>Note:</i> This clause applies to any hosted implementation.
Specific operating systems such as <i>OpenMVS</i><sup><a href="#Footnote-3">3</a></sup>,
<i>UNIX</i>, and <i>Windows</i><sup><a href="#Footnote-4">4</a></sup> are mentioned only for purposes of illustration or to
give guidance to implementors. No slight to other operating systems is implied
or intended. <i>--end note</i>.]</p>
</blockquote>
<p>Unless otherwise specified, all components described in this clause are
declared in namespace <code>std::tr2::sys</code>.</p>
<blockquote>
<p>[<i>Note:</i> The <code>sys</code> sub-namespace prevents collisions with
names already in the standard library and emphasizes reliance on the
operating system dependent behavior inherent in file system operations. <i>-- end
note</i>]</p>
</blockquote>
<p>The <i>Effects</i> and <i>Postconditions</i> of functions described in this clause
may not be achieved in
the presence of <a href="#Race-condition">race conditions</a>. No diagnostic is required.</p>
<p>If the possibility of race conditions makes it unreliable for a program to
test for a precondition before calling a function described in this clause, <i>
Requires</i> is not specified for the condition. Instead, the condition is
specified as a <i>Throws</i> condition.</p>
<blockquote>
<p>[<i>Note:</i> As a design practice, preconditions are not specified when it
is unreasonable for a program to detect them prior to calling the function. <i>
-- end note</i>]</p>
</blockquote>
<p><a name="Footnote-3">Footnote 3</a>: <i>OpenMVS</i>® is a registered
trademark of Hewlett-Packard Development Company.</p>
<p><a name="Footnote-4">Footnote 4</a>: <i>Windows</i>® is a registered
trademark of Microsoft Corporation.</p>
<h3><a name="Definitions">Definitions</a></h3>
<p>The following definitions shall apply to this clause:</p>
<p><i><a name="File">File</a>: </i>An object that can be written to, or read from, or both. A file
has certain attributes, including type. File types include regular file,
symbolic link, and directory. Other types of files may be supported by the
implementation.</p>
<p><i><a name="File-system">File system</a>:</i> A collection of files and certain of their attributes.</p>
<p><i><a name="Filename">Filename</a>:</i> The name of a file. The format is as
specified by the <i>POSIX
<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_169">
Filename</a></i> base definition.</p>
<p><i><a name="Path">Path</a>:</i> A sequence of elements which identify
a location within a filesystem. The elements are the <i>root-name</i>, <i>
root-directory</i>, and each successive <i>filename</i>. See
<a href="#Pathname-grammar">Pathname grammar</a>.</p>
<p><i><a name="Pathname">Pathname</a>: </i>A character string that represents a
path.</p>
<p><i><a name="Link">Link</a>: </i>A directory entry object that associates a
filename with a file. On some file systems, several directory entries can
associate names with the same file.</p>
<p><i><a name="Hard-link">Hard link</a>:</i> A link to an existing file. Some
file systems support multiple hard links to a file. If the last hard link to a
file is removed, the file itself is removed.</p>
<blockquote>
<p>[<i>Note:</i> A hard link can be thought of as a shared-ownership smart
pointer to a file.<i> -- end note</i>]<i> </i></p>
</blockquote>
<p><i><a name="Symbolic-link">Symbolic link</a>: </i>A type of file with the
property that when the file is encountered during pathname resolution, a string
stored by the file is used to modify the pathname resolution.</p>
<blockquote>
<p>[<i>Note:</i> A symbolic link can be thought of as a raw pointer to a file.
If the file pointed to does not exist, the symbolic link is said to be a
"dangling" symbolic link.<i> -- end note</i>]<i> </i></p>
</blockquote>
<p><i><a name="Slash">Slash</a>:</i> The character <tt>'/'</tt>, also known as
solidus.</p>
<p><i><a name="Dot">Dot</a>:</i> The character '.', also known as period.</p>
<p><i><a name="Race-condition">Race condition</a>:</i> The condition that occurs
when multiple threads, processes, or computers interleave access and
modification of
the same object within a file system.</p>
<h3><a name="Requirements">Requirements</a></h3>
<h4><a name="Requirements-on-programs">Requirements on programs</a></h4>
<p>The arguments for template parameters named <code>Path</code>, <code>Path1</code>,
or <code>Path2</code> described in this clause shall be of type <code>basic_path</code>,
or a class derived from <code>basic_path</code>, unless otherwise
specified.</p>
<h4><a name="Requirements-on-implementations">Requirements on implementations</a></h4>
<p>Some function templates described in this clause have a template parameter
named <code>Path</code>, <code>Path1</code>, or <code>Path2</code>. When called
with a function argument <code>s</code> of type <code>char*</code> or <code>
std::string</code>, the implementation shall treat the argument as if it were
coded <code>path(s)</code>. When called with a function argument <code>s</code>
of type <code>wchar_t*</code> or <code>std::wstring</code>, the implementation
shall treat the argument as if it were coded <code>wpath(s)</code>. For
functions with two arguments, implementations shall not supply this treatment
when <code>Path1</code> and <code>Path2</code> are different types.</p>
<blockquote>
<p>[<i>Note:</i> This "do-the-right-thing" rule allows users to write <code>exists("foo")</code>,
taking advantage of class <code>basic_path</code>'s string conversion
constructor, rather
than the lengthier and more error prone <code>exists(path("foo"))</code>. This
is particularly important for the simple, script-like, programs which are an
important use case for the library. Calling two argument functions with
different types is a very rare usage, and may well be a coding error, so
automatic conversion is not supported for such cases.</p>
<p>The implementation technique is unspecified. One possible implementation
technique, using
<code>exists()</code> as an example, is:</p>
<blockquote>
<pre>template <class Path>
typename boost::enable_if<is_basic_path<Path>,bool>::type exists(const Path& p);
inline bool exists(const path& p) { return exists<path>(p); }
inline bool exists(const wpath& p) { return exists<wpath>(p); }</pre>
</blockquote>
<p> The <code>enable_if</code> will fail for a C string or <code>
std::basic_string</code> argument, which will then be automatically converted
to a <code>basic_path</code> object via the appropriate <code>basic_path</code> conversion
constructor. <i>-- end note</i>]</p>
<p><span style="background-color: #E0E0E0"><i>The two overloads are not given
in the normative text because:</i></span></p>
<ul>
<li><span style="background-color: #E0E0E0"><i>Better techniques for
achieving the desired affect may be developed, perhaps enabled by core
language changes like Concepts.</i></span></li>
<li><span style="background-color: #E0E0E0"><i>Implementations may prefer
techniques that work with legacy compilers that do not support enable_if.</i></span></li>
<li><span style="background-color: #E0E0E0"><i>Spelling out the overloads
makes the text longer and harder to read without adding much benefit.</i></span></li>
<li><span style="background-color: #E0E0E0"><i>More overloads will probably
be needed for char16_t and char32_t (or whatever they end up being called),
making it even less attractive to actually spell out each one. </i></span>
</li>
</ul>
</blockquote>
<p>Implementations of functions described in this clause are permitted to call the applications
program interface (API) provided by the operating system. If such an operating
system API call results in an error, implementations
shall report the error by throwing exception <code>basic_filesystem_error</code>,
unless otherwise specified.</p>
<blockquote>
<p>[<i>Note: </i>Such exceptions and the conditions that cause them to be thrown
are not explicitly described in each <i>Throws</i> element within this clause.
Because hardware failures, network failures, race conditions, and a plethora of
other errors occur frequently in file system operations, users should be aware
that <span style="background-color: #FFFFFF">unless otherwise specified</span> any file system operation, not matter how apparently innocuous, may throw
an exception. <i>-- end note</i>]</p>
</blockquote>
<p><span style="background-color: #FFFFFF">Functions commonly used in contexts
where errors are not exceptional have overloads taking an additional argument of
type </span><code><span style="background-color: #FFFFFF">error_code& ec</span></code><span style="background-color: #FFFFFF">. Such overloaded functions shall not throw exceptions. If an error occurs,
<code>ec</code> shall be set to the
error code reported by the operating system, otherwise <code>ec</code> shall be set to 0. If
an overload without an argument of type </span><code>
<span style="background-color: #FFFFFF">error_code& ec</span></code><span style="background-color: #FFFFFF"> returns void, the other overload (with an argument of type </span><code>
<span style="background-color: #FFFFFF">error_code& ec</span></code><span style="background-color: #FFFFFF">) returns an <code>
error_code</code> with the value of ec.</span></p>
<h3><a name="Header-filesystem-synopsis">Header <code><filesystem></code> synopsis</a></h3>
<pre>namespace std
{
namespace tr2
{
namespace sys
{
template <class String, class Traits> class <a href="#Class-template-basic_path">basic_path</a>;
template<class String, class Traits>
void swap(basic_path<String, Traits> & lhs, basic_path<String, Traits> & rhs);
template<class String, class Traits> bool operator<(<i>a</i> a, <i>b</i> b);
template<class String, class Traits> bool operator==(<i>a</i> a, <i>b</i> b);
template<class String, class Traits> bool operator!=(<i>a</i> a, <i>b</i> b);
template<class String, class Traits> bool operator>(<i>a</i> a, <i>b</i> b);
template<class String, class Traits> bool operator<=(<i>a</i> a, <i>b</i> b);
template<class String, class Traits> bool operator>=(<i>a</i> a, <i>b</i> b);
template<class String, class Traits> bool operator/(<i>a</i> a, <i>b</i> b);
template<class Path>
basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type> &
operator<<(basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type>& os, const Path & ph);
template<class Path>
basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type> &
operator>>(basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type>& is, Path & ph);
struct path_traits;
struct wpath_traits;
typedef basic_path<std::string, path_traits> path;
typedef basic_path<std::wstring, wpath_traits> wpath;
template<class Path> struct is_basic_path;
template<class Path> struct slash { static const char value = '/'; };
template<class Path> struct dot { static const char value = '.'; };
<span style="background-color: #FFFFFF"> template<class Path> struct colon { static const char value = ':'; };</span><span style="background-color: #FFFF00">
</span>
<span style="background-color: #FFFFFF">class filesystem_error;</span><span style="background-color: #FFFF00">
</span>
template <class Path> class <a href="#Class-template-basic_filesystem_error">basic_filesystem_error</a>;
typedef basic_filesystem_error<path> filesystem_error;
typedef basic_filesystem_error<wpath> wfilesystem_error;
<span style="background-color: #FFFFFF">template <class Path> class <a href="#Class-template-basic_directory_entry">basic_directory_entry</a>;
typedef basic_directory_entry<path> directory_entry;
typedef basic_directory_entry<wpath> wdirectory_entry;
</span>
template <class Path> class <a href="#Class-template-basic_directory_iterator">basic_directory_iterator</a>;
typedef basic_directory_iterator<path> directory_iterator;
typedef basic_directory_iterator<wpath> wdirectory_iterator;
template <class Path> class <a href="#Class-template-basic_recursive_directory_iterator">basic_recursive_directory_iterator</a>;
typedef basic_recursive_directory_iterator<path> recursive_directory_iterator;
typedef basic_recursive_directory_iterator<wpath> wrecursive_directory_iterator;
enum file_type { status_unknown, file_not_found, regular_file, directory_file,
symlink_file, block_file, character_file, fifo_file, socket_file,
type_unknown
};
class <a href="#file_status">file_status</a>;
<span style="background-color: #FFFFFF">struct space_info // returned by </span><a href="#space" style="text-decoration: none"><span style="background-color: #FFFFFF">space</span></a><span style="background-color: #FFFFFF"> function
{
uintmax_t capacity;
uintmax_t free;
uintmax_t available;
};
</span>
// <a href="#Status-functions">status functions</a>
template <class Path> file_status status(const Path& p);
template <class Path> file_status status(const Path& p, error_code& ec);
template <class Path> file_status symlink_status(const Path& p);
template <class Path> file_status symlink_status(const Path& p, error_code& ec);
// <a href="#Predicate-functions">predicate functions</a>
bool status_known( file_status s );
bool exists( file_status s );
bool is_regular( file_status s );
bool is_directory( file_status s );
bool is_symlink( file_status s );
bool is_other( file_status s );
template <class Path> bool exists(const Path& p);
template <class Path> bool is_directory(const Path& p);
template <class Path> bool is_regular(const Path& p);
template <class Path> bool is_other(const Path& p);
template <class Path> bool is_symlink(const Path& p);
template <class Path> bool is_empty(const Path& p);
template <class Path1, class Path2>
bool equivalent(const Path1& p1, const Path2& p2);
// <a href="#Attribute-functions">attribute functions</a>
template <class Path> Path current_path();
template <class Path> const Path& initial_path();
template <class Path> <span style="background-color: #FFFFFF; ">uintmax_t</span> file_size(const Path& p);
<span style="background-color: #FFFFFF"> template <class Path> space_info space(const Path& p);</span><span style="background-color: #FFFF00">
</span> template <class Path> std::time_t last_write_time(const Path& p);
template <class Path>
void last_write_time(const Path& p, const std::time_t new_time);
// <a href="#Operations-functions">operations functions</a>
template <class Path> bool create_directory(const Path& dp);
template <class Path1, class Path2>
void create_hard_link(const Path1& old_fp, const Path2& new_fp);
<span style="background-color: #FFFFFF"> template <class Path1, class Path2>
error_code create_hard_link(const Path1& old_fp, const Path2& new_fp, error_code& ec);
template <class Path1, class Path2>
void create_symlink(const Path1& old_fp, const Path2& new_fp);
template <class Path1, class Path2>
error_code create_symlink(const Path1& old_fp, const Path2& new_fp, error_code& ec);
</span> template <class Path> bool remove(const Path& p);
template <class Path1, class Path2>
void rename(const Path1& from_p, const Path2& to_p);
template <class Path1, class Path2>
void copy_file(const Path1& from_fp, const Path2& to_fp);
template <class Path> Path system_complete(const Path& p);
template <class Path> Path complete(const Path& p, const Path& base=initial_path<Path>());
// <a href="#Convenience-functions">convenience functions</a>
template <class Path> bool create_directories(const Path& p);
template <class Path> typename Path::string_type extension(const Path& p);
template <class Path> typename Path::string_type basename(const Path& p);
template <class Path>
Path replace_extension(const Path& p, const typename Path::string_type& new_extension);
} // namespace sys
} // namespace tr2
} // namespace std</pre>
<h3><a name="Path-traits">Path traits</a></h3>
<p>This subclause defines requirements on classes representing path behavior
traits, and defines two classes that satisfy those requirements for paths based
on <code>string</code> and <code>wstring</code>.. It also defines several path
additional path traits structure templates, and defines several specializations
of them.</p>
<p>Class template <code>basic_path</code> defined in this clause requires additional
types, values, and behavior to complete the definition of its semantics.</p>
<p>For purposes of exposition, Traits behaves as if it is a class with private
members bool m_locked, initialized false, and std::locale m_locale, initialized </p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
<tr>
<td width="50%" align="center" colspan="2"><b><i>
<a name="Path-Behavior-Traits-Requirements">Path Behavior Traits
Requirements</a></i></b></td>
</tr>
<tr>
<td width="38%" align="center"><b><i>Expression</i></b></td>
<td width="62%" align="center"><b><i>Requirements</i></b></td>
</tr>
<tr>
<td width="38%" valign="top"><code>Traits::external_string_type</code></td>
<td width="62%">A typedef which is a specialization of <code>basic_string</code>.
The <code>value_type</code> is a character type used by the operating system
to represent pathnames.</td>
</tr>
<tr>
<td width="38%" valign="top"><code>Traits::internal_string_type</code></td>
<td width="62%">A typedef which is a specialization of <code>basic_string</code>.
The <code>value_type</code> is a character type to be used by the program to
represent pathnames. Required be the same type as the <code>basic_path
String</code> template parameter. </td>
</tr>
<tr>
<td width="38%" valign="top"><code>Traits::to_external( p, is )</code></td>
<td width="62%"><code>is</code>, converted by the <code>m_locale</code>
<code>codecvt</code> facet to <code>external_string_type</code>.</td>
</tr>
<tr>
<td width="38%" valign="top"><code>Traits::to_internal( p, xs )</code></td>
<td width="62%"><code>xs</code>, converted by the <code>m_locale</code>
<code>codecvt</code> facet to to <code>internal_string_type</code>.</td>
</tr>
<tr>
<td width="38%" valign="top"><code>Traits::imbue(loc)</code></td>
<td width="62%"><i>Effects:</i> if <code>m_locked</code>, throw. Otherwise,
<code>m_locked = true; m_locale = loc;<br>
</code><i>Returns:</i> <code>void</code><b><br>
</b><i>Throws:</i> <code>basic_filesystem_error</code></td>
</tr>
<tr>
<td width="38%" valign="top"><code>Traits::imbue(loc, std::nothrow)</code></td>
<td width="62%"><i>Effects:</i> <code>if (!m_locked) m_locale = loc; bool
temp(m_locked); m_locked = true;<br>
</code><i>Returns:</i> <code>temp</code></td>
</tr>
</table>
<p>Type <code>is_basic_path</code> shall be a <i>UnaryTypeTrait</i> (TR1, 4.1).
The primary template shall be derived directly or indirectly from <code>
std::tr1::false_type</code>. Type <code>is_basic_path</code> shall be
specialized for <code>path</code>, <code>wpath</code>, and any
user-specialized <code>basic_path</code> types, and such specializations shall
be derived directly or indirectly from <code>std::tr1::true_type</code>.</p>
<p>Structure templates <code>slash</code>, <code>dot</code>, and <code>
<span style="background-color: #FFFFFF">colon</span></code><span style="background-color: #FFFFFF">
</span>are supplied with
values of type <code>char</code>. If a user-specialized <code>basic_path</code>
has a <code>
value_type</code> type which is not convertible from <code>char</code>, the
templates <code>slash</code> and <code>dot</code> shall be specialized to
provide <code>value</code> with type which is convertible to <code>
basic_path::value_type</code>.</p>
<h3><a name="Class-template-basic_path">Class template <code>basic_path</code></a></h3>
<p>Class template <code>basic_path</code> provides a portable mechanism for
representing <a href="#Path">paths</a> in C++ programs, using a portable generic
pathname <a href="#Pathname-grammar">grammar</a>. When portability is not a
requirement, native file system specific formats can be used. Class template
<code>basic_path</code> is concerned only with the lexical and syntactic aspects
of a path. The path does not have to exist in the operating system's file
system, and may contain names which are not even valid for the current operating
system. </p>
<blockquote>
<p>[<i>Note: </i>If the library's functions trafficked only in C++<i> </i>or
C-style strings, they would provide only the illusion of portability since
while the syntax of function calls would be portable, the semantics of the
strings they operate on would not be portable. <i>-- end note</i>]</p>
</blockquote>
<pre>namespace std
{
namespace tr2
{
namespace sys
{
template <class String, class Traits> class basic_path
{
public:
typedef basic_path<String, Traits> path_type;
typedef String string_type;
typedef typename String::value_type value_type;
typedef Traits traits_type;
typedef typename Traits::external_string_type external_string_type;
// <a href="#basic_path-constructors">constructors/destructor</a>
basic_path();
basic_path(const basic_path& p);
basic_path(const string_type& s);
basic_path(const value_type* s);
template <class InputIterator>
basic_path(InputIterator first, InputIterator last);
~basic_path();
// <a href="#basic_path-assignments">assignments</a>
basic_path& operator=(const basic_path& p);
basic_path& operator=(const string_type& s);
basic_path& operator=(const value_type* s);
template <class InputIterator>
basic_path& assign(InputIterator first, InputIterator last);
// <a href="#basic_path-modifiers">modifiers</a>
basic_path& operator/=(const basic_path& rhs);
basic_path& operator/=(const string_type& s);
basic_path& operator/=(const value_type* s);
template <class InputIterator>
basic_path& append(InputIterator first, InputIterator last);
<span style="background-color: #FFFFFF">void clear();
void swap( basic_path & rhs );</span>
basic_path& remove_leaf();
// <a href="#basic_path-observers">observers</a>
const string_type string() const;
const string_type file_string() const;
const string_type directory_string() const;
const external_string_type external_file_string() const;
const external_string_type external_directory_string() const;
string_type root_name() const;
string_type root_directory() const;
basic_path root_path() const;
basic_path relative_path() const;
string_type leaf() const;
basic_path branch_path() const;
bool empty() const;
bool is_complete() const;
bool has_root_name() const;
bool has_root_directory() const;
bool has_root_path() const;
bool has_relative_path() const;
bool has_leaf() const;
bool has_branch_path() const;
// <a href="#basic_path-iterators">iterators</a>
class iterator;
typedef iterator const_iterator;
iterator begin() const;
iterator end() const;
};
} // namespace sys
} // namespace tr2
} // namespace std</pre>
<p>A <code>basic_path</code> object stores a possibly empty <a href="#Path">path</a>.
The internal form of the stored path is unspecified.</p>
<p><a name="pathname-resolution">Functions</a> described in this clause which access files or their attributes do so by
resolving a <code>basic_path</code> object into a particular file in a file
hierarchy. The pathname, suitably converted to the string type, format, and
encoding
required by the operating system, is resolved as if by the <i>POSIX</i>
<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
Pathname Resolution</a> mechanism. The encoding of the resulting pathname is determined by the <code>Traits::to_external</code> conversion function.</p>
<blockquote>
<p>[<i>Note:</i> There is no guarantee that the path stored in a <code>basic_path</code>
object is valid for a particular operating system or file system. <i>-- end note</i>]</p>
</blockquote>
<p>Some functions in this clause return <code>basic_path</code> objects for
paths composed partly or wholly of pathnames obtained from the operating system.
Such pathnames are suitably converted from the actual format and string
type supplied by the operating system. The encoding of the resulting path is determined by the <code>Traits::to_internal</code> conversion function.</p>
<p>For member functions described as returning "<code>const string_type</code>" or
"<code>const external_string_type</code>", implementations are permitted to return
"<code>const string_type&</code>" or "<code>const external_string_type&</code>"
respectively.</p>
<blockquote>