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
|
<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>Portability Guide</title>
</head>
<body bgcolor="#FFFFFF">
<h1>
<img border="0" src="../../../boost.png" align="center" width="277" height="86">Path
Name Portability
Guide</h1>
<p>
<a href="#Introduction">Introduction</a><br>
<a href="#name_check_functions">name_check functions</a><br>
<a href="#recommendations">File and directory name recommendations</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>Like any other C++ program which performs I/O operations, there is no
guarantee that a program using the Filesystem Library will be portable between
operating systems. Critical aspects of I/O, such as how the operating system
interprets paths, are unspecified by the C and C++ Standards.</p>
<p>It is not possible to know if a file or directory name will be
valid (and thus portable) for an unknown operating system. There is always the possibility that an operating system could use
names which are unusual (numbers less than 4096, for example) or very
limited in size (maximum of six character names, for example). In other words,
portability is never absolute; it is always relative to specific operating or
file systems.</p>
<p>It is possible to know in advance if a directory or file name is likely to be valid for a particular
operating system. It is also possible to construct names which are
likely to be portable to a large number of modern and legacy operating systems.</p>
<p>Almost all modern operating systems support multiple file systems. At the
minimum, they support a native file system plus a CD-ROM file system (Generally
ISO-9669, often with Juliet extensions).</p>
<p>Each file system
may have its own naming rules. For example, modern versions of Windows support NTFS, FAT, FAT32, and ISO-9660 file systems, among others, and the naming rules
for some of those file systems differ a great deal. Each file system may have
differing rules for overall path validity, such as a maximum length or number of
sub-directories.</p>
<p>As a result, the Boost Filesystem Library's <i>name_check</i> mechanism
cannot guarantee directory and file name portability. Rather, it is intended to
give the programmer a "fighting chance" to achieve portability by early
detection of common naming problems.</p>
<h2><a name="name_check_functions">name_check functions</a></h2>
<p>A <i><a href="path.htm#name_check_typedef">name_check</a></i> function
returns true if its argument is a valid name for a particular operating or file
system. A number of these functions are supplied, and user-supplied <i>
name_check</i> functions are also allowed.</p>
<p>The <a href="#portable_name">portable_name</a> function is of particular
interest because it is the initial <a href="path.htm#name_check_mechanism">
default name_check function</a> and is carefully chosen to provide wide
portability yet without severe restrictions on expressiveness.</p>
<p>The <a href="#native">native</a> function is of particular interest because
it is often used when the source of the path is operator input or other sources
which are formatted according to operating system rules.</p>
<table border="1" cellpadding="5" cellspacing="0">
<tr>
<td align="center" colspan="2"><b>Library Supplied name_check Functions</b></td>
</tr>
<tr>
<td align="center"><b>Name</b></td>
<td align="center"><b>Description</b></td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="portable_posix_name">portable_posix_name</a></code></td>
<td>Returns <i>true</i> for names containing only the characters
specified in<i> Portable Filename Character Set</i> rules as defined in by
POSIX (<a href="http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap03.html">www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap03.html</a>).<br>
Only characters allowed are 0-9, a-z, A-Z, '.', '_', and '-'.<p><b>Use:</b>
applications which must be portable to any POSIX system.</td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="windows_name">windows_name</a></code></td>
<td>Returns <i>true</i> for names containing only the characters
specified by the Windows platform SDK as valid regardless of the file
system. Allows any character except 0x0-0x1F, '<', '>', ':', '"', '/', '\',
and '|'. Furthermore, names must not end with a trailing space or period.<p>
<b>Use:</b> applications which must be portable to Windows.</p>
<p><b>Note:</b> Reserved device names are not valid as file names, but are
not being detected because they are still valid as a path. Specifically,
CON, PRN, AUX, CLOCK$, NUL, COM[1-9], LPT[1-9], and these names followed by
an extension (for example, NUL.tx7).</td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="portable_name">portable_name</a></code></td>
<td><code>windows_name(name) && portable_posix_name(name)</code>,
and first character not period or hyphen.<p>
<b>Note:</b> This is the initial default name_check.</p>
<p><b>Use:</b> applications which must be portable to a wide variety of
modern operating systems, large and small, and to some legacy O/S's.</td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="portable_directory_name">
portable_directory_name</a></code></td>
<td><code>portable_name(name)</code>, and no periods.<p><b>Use:</b> applications
which must be portable to a wide variety of platforms, including OpenVMS.</td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="portable_file_name">
portable_file_name</a></code></td>
<td><code>portable_name(name)</code>,except allows one
period only, and only if followed by one to three additional characters.<p><b>Use:</b>
applications which must be portable to a wide variety of platforms,
including OpenVMS and other systems which have a concept of "file extension"
but limit its length.</td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="no_check">no_check</a></code></td>
<td>Returns <i>true</i>.<p><b>Use: </b>When the generic grammar
is desired, but name checking is not desired. For example, a program which
traffics in names created elsewhere may have no choice but to accept those
names. Another example is a application which prefers to use the Filesystem
Library and its generic grammar, but is uninterested in portability. An
alternative to <code>no_check</code> might be <code>native</code>, but <code>native</code>
has the side effect of altering the grammar accepted.</td>
</tr>
<tr>
<td align="left" valign="top"><code><a name="native">native</a></code></td>
<td>Implementation defined name_check. Guaranteed to return <i>
true</i> for all names considered valid by the operating system.<p><b>Side
effect:</b> Syntax for path constructor <i>src</i> string is implementation
defined according to the path syntax rules for the operating system.</p>
<p><b>Use:</b> In path constructors, when the source is operator input or
other sources which are formatted according to operating system rules. Note
that <code>default_name_check( native )</code> causes all path src
strings to be treated according to the path syntax rules for the operating
system, which may or may not be desirable.</p>
<p><b>Note:</b> May return <i>true</i> for some names not considered valid
by the operating system under all conditions (particularly on operating systems which support
multiple file systems.)</td>
</tr>
</table>
<h2>File and directory name <a name="recommendations">recommendations</a></h2>
<table border="1" cellpadding="5" cellspacing="0">
<tr>
<td align="center" valign="top"><strong>Recommendation</strong></td>
<td align="center" valign="top"><strong>Rationale</strong></td>
</tr>
<tr>
<td valign="top">Limit file and directory names to the characters A-Z, a-z, 0-9, period, hyphen, and
underscore.<p>Use any of the "portable_" <a href="#name_check_functions">
name check functions</a> to enforce this recommendation.</td>
<td valign="top">These are the characters specified by the POSIX standard for portable directory and
file names, and are also valid for Windows, Mac, and many other modern filesystems.</td>
</tr>
<tr>
<td valign="top">Do not use a period or hyphen as the first
character of a name. Do not use period as the last character of a name.<p>
Use <a href="#portable_name">portable_name</a>,
<a href="#portable_directory_name">portable_directory_name</a>, or
<a href="#portable_file_name">portable_file_name</a> to enforce this
recommendation.</td>
<td valign="top">Some operating systems treat have special rules for the
first character of names. POSIX, for example. Windows does not permit period
as the last character.</td>
</tr>
<tr>
<td valign="top">Do not use periods in directory names.<p>Use
<a href="#portable_directory_name">portable_directory_name</a> to enforce
this recommendation.</td>
<td valign="top">Requirement for ISO-9660 without Juliet extensions, OpenVMS native filesystem, and other legacy systems.</td>
</tr>
<tr>
<td valign="top">Do not use more that one period in a file name, and limit
the portion after the period to three characters.<p>Use
<a href="#portable_file_name">portable_file_name</a> to enforce this
recommendation.</td>
<td valign="top">Requirement for ISO-9660 level 1, OpenVMS native filesystem, and
other legacy systems. </td>
</tr>
<tr>
<td valign="top">Do not assume names are case sensitive. For example, do not expected a directory to be
able to hold separate elements named "Foo" and "foo". </td>
<td valign="top">Some filesystems are case insensitive. For example, Windows
NTFS is case preserving in the way it stores names, but case insensitive in
searching for names (unless running under the POSIX sub-system, it which
case it does case sensitive searches). </td>
</tr>
<tr>
<td valign="top">Do not assume names are case insensitive. For example, do not expect a file
created with the name of "Foo" to be opened successfully with the name of "foo".</td>
<td valign="top">Some filesystems are case sensitive. For example, POSIX.</td>
</tr>
<tr>
<td valign="top">Don't use hyphens in names.</td>
<td valign="top">ISO-9660 level 1, and possibly some legacy systems, do not permit
hyphens.</td>
</tr>
<tr>
<td valign="top">Limit the length of the string returned by path::string() to
255 characters.
Note that ISO 9660 has an explicit directory tree depth limit of 8, although
this depth limit is removed by the Juliet extensions.</td>
<td valign="top">Some operating systems place limits on the total path length. For example,
Windows 2000 limits paths to 260 characters total length.</td>
</tr>
<tr>
<td valign="top">Limit the length of any one name in a path. Pick the specific limit according to
the operating systems and or file systems you wish portability to:<br>
Not a concern:: POSIX, Windows, MAC OS X.<br>
31 characters: Classic Mac OS<br>
8 characters + period + 3 characters: ISO 9660 level 1<br>
32 characters: ISO 9660 level 2 and 3<br>
128 characters (64 if unicode): ISO 9660 with Juliet extensions</td>
<td valign="top">Limiting name length can markedly reduce the expressiveness of file names, yet placing
only very high limits on lengths inhibits widest portability.</td>
</tr>
</table>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->01 December, 2003<!--webbot bot="Timestamp" endspan i-checksum="38505" --></p>
<p> Copyright Beman Dawes, 2002, 2003</p>
<p> Use, modification, and distribution are subject to the Boost Software
License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>
|
