| 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=windows-1252"> |
|---|
| 8 | <title>Portability Guide</title> |
|---|
| 9 | </head> |
|---|
| 10 | |
|---|
| 11 | <body bgcolor="#FFFFFF"> |
|---|
| 12 | |
|---|
| 13 | <h1> |
|---|
| 14 | <img border="0" src="../../../boost.png" align="center" width="277" height="86">Path |
|---|
| 15 | Name Portability |
|---|
| 16 | Guide</h1> |
|---|
| 17 | |
|---|
| 18 | <p> |
|---|
| 19 | <a href="#Introduction">Introduction</a><br> |
|---|
| 20 | <a href="#name_check_functions">name_check functions</a><br> |
|---|
| 21 | <a href="#recommendations">File and directory name recommendations</a></p> |
|---|
| 22 | <h2><a name="Introduction">Introduction</a></h2> |
|---|
| 23 | <p>Like any other C++ program which performs I/O operations, there is no |
|---|
| 24 | guarantee that a program using the Filesystem Library will be portable between |
|---|
| 25 | operating systems. Critical aspects of I/O, such as how the operating system |
|---|
| 26 | interprets paths, are unspecified by the C and C++ Standards.</p> |
|---|
| 27 | <p>It is not possible to know if a file or directory name will be |
|---|
| 28 | valid (and thus portable) for an unknown operating system. There is always the possibility that an operating system could use |
|---|
| 29 | names which are unusual (numbers less than 4096, for example) or very |
|---|
| 30 | limited in size (maximum of six character names, for example). In other words, |
|---|
| 31 | portability is never absolute; it is always relative to specific operating or |
|---|
| 32 | file systems.</p> |
|---|
| 33 | <p>It is possible to know in advance if a directory or file name is likely to be valid for a particular |
|---|
| 34 | operating system. It is also possible to construct names which are |
|---|
| 35 | likely to be portable to a large number of modern and legacy operating systems.</p> |
|---|
| 36 | |
|---|
| 37 | <p>Almost all modern operating systems support multiple file systems. At the |
|---|
| 38 | minimum, they support a native file system plus a CD-ROM file system (Generally |
|---|
| 39 | ISO-9669, often with Juliet extensions).</p> |
|---|
| 40 | |
|---|
| 41 | <p>Each file system |
|---|
| 42 | 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 |
|---|
| 43 | for some of those file systems differ a great deal. Each file system may have |
|---|
| 44 | differing rules for overall path validity, such as a maximum length or number of |
|---|
| 45 | sub-directories.</p> |
|---|
| 46 | |
|---|
| 47 | <p>As a result, the Boost Filesystem Library's <i>name_check</i> mechanism |
|---|
| 48 | cannot guarantee directory and file name portability. Rather, it is intended to |
|---|
| 49 | give the programmer a "fighting chance" to achieve portability by early |
|---|
| 50 | detection of common naming problems.</p> |
|---|
| 51 | |
|---|
| 52 | <h2><a name="name_check_functions">name_check functions</a></h2> |
|---|
| 53 | |
|---|
| 54 | <p>A <i><a href="path.htm#name_check_typedef">name_check</a></i> function |
|---|
| 55 | returns true if its argument is a valid name for a particular operating or file |
|---|
| 56 | system. A number of these functions are supplied, and user-supplied <i> |
|---|
| 57 | name_check</i> functions are also allowed.</p> |
|---|
| 58 | |
|---|
| 59 | <p>The <a href="#portable_name">portable_name</a> function is of particular |
|---|
| 60 | interest because it is the initial <a href="path.htm#name_check_mechanism"> |
|---|
| 61 | default name_check function</a> and is carefully chosen to provide wide |
|---|
| 62 | portability yet without severe restrictions on expressiveness.</p> |
|---|
| 63 | |
|---|
| 64 | <p>The <a href="#native">native</a> function is of particular interest because |
|---|
| 65 | it is often used when the source of the path is operator input or other sources |
|---|
| 66 | which are formatted according to operating system rules.</p> |
|---|
| 67 | <table border="1" cellpadding="5" cellspacing="0"> |
|---|
| 68 | <tr> |
|---|
| 69 | <td align="center" colspan="2"><b>Library Supplied name_check Functions</b></td> |
|---|
| 70 | </tr> |
|---|
| 71 | <tr> |
|---|
| 72 | <td align="center"><b>Name</b></td> |
|---|
| 73 | <td align="center"><b>Description</b></td> |
|---|
| 74 | </tr> |
|---|
| 75 | <tr> |
|---|
| 76 | <td align="left" valign="top"><code><a name="portable_posix_name">portable_posix_name</a></code></td> |
|---|
| 77 | <td>Returns <i>true</i> for names containing only the characters |
|---|
| 78 | specified in<i> Portable Filename Character Set</i> rules as defined in by |
|---|
| 79 | POSIX (<a href="http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap03.html">www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap03.html</a>).<br> |
|---|
| 80 | Only characters allowed are 0-9, a-z, A-Z, '.', '_', and '-'.<p><b>Use:</b> |
|---|
| 81 | applications which must be portable to any POSIX system.</td> |
|---|
| 82 | </tr> |
|---|
| 83 | <tr> |
|---|
| 84 | <td align="left" valign="top"><code><a name="windows_name">windows_name</a></code></td> |
|---|
| 85 | <td>Returns <i>true</i> for names containing only the characters |
|---|
| 86 | specified by the Windows platform SDK as valid regardless of the file |
|---|
| 87 | system. Allows any character except 0x0-0x1F, '<', '>', ':', '"', '/', '\', |
|---|
| 88 | and '|'. Furthermore, names must not end with a trailing space or period.<p> |
|---|
| 89 | <b>Use:</b> applications which must be portable to Windows.</p> |
|---|
| 90 | <p><b>Note:</b> Reserved device names are not valid as file names, but are |
|---|
| 91 | not being detected because they are still valid as a path. Specifically, |
|---|
| 92 | CON, PRN, AUX, CLOCK$, NUL, COM[1-9], LPT[1-9], and these names followed by |
|---|
| 93 | an extension (for example, NUL.tx7).</td> |
|---|
| 94 | </tr> |
|---|
| 95 | <tr> |
|---|
| 96 | <td align="left" valign="top"><code><a name="portable_name">portable_name</a></code></td> |
|---|
| 97 | <td><code>windows_name(name) && portable_posix_name(name)</code>, |
|---|
| 98 | and first character not period or hyphen.<p> |
|---|
| 99 | <b>Note:</b> This is the initial default name_check.</p> |
|---|
| 100 | <p><b>Use:</b> applications which must be portable to a wide variety of |
|---|
| 101 | modern operating systems, large and small, and to some legacy O/S's.</td> |
|---|
| 102 | </tr> |
|---|
| 103 | <tr> |
|---|
| 104 | <td align="left" valign="top"><code><a name="portable_directory_name"> |
|---|
| 105 | portable_directory_name</a></code></td> |
|---|
| 106 | <td><code>portable_name(name)</code>, and no periods.<p><b>Use:</b> applications |
|---|
| 107 | which must be portable to a wide variety of platforms, including OpenVMS.</td> |
|---|
| 108 | </tr> |
|---|
| 109 | <tr> |
|---|
| 110 | <td align="left" valign="top"><code><a name="portable_file_name"> |
|---|
| 111 | portable_file_name</a></code></td> |
|---|
| 112 | <td><code>portable_name(name)</code>,except allows one |
|---|
| 113 | period only, and only if followed by one to three additional characters.<p><b>Use:</b> |
|---|
| 114 | applications which must be portable to a wide variety of platforms, |
|---|
| 115 | including OpenVMS and other systems which have a concept of "file extension" |
|---|
| 116 | but limit its length.</td> |
|---|
| 117 | </tr> |
|---|
| 118 | <tr> |
|---|
| 119 | <td align="left" valign="top"><code><a name="no_check">no_check</a></code></td> |
|---|
| 120 | <td>Returns <i>true</i>.<p><b>Use: </b>When the generic grammar |
|---|
| 121 | is desired, but name checking is not desired. For example, a program which |
|---|
| 122 | traffics in names created elsewhere may have no choice but to accept those |
|---|
| 123 | names. Another example is a application which prefers to use the Filesystem |
|---|
| 124 | Library and its generic grammar, but is uninterested in portability. An |
|---|
| 125 | alternative to <code>no_check</code> might be <code>native</code>, but <code>native</code> |
|---|
| 126 | has the side effect of altering the grammar accepted.</td> |
|---|
| 127 | </tr> |
|---|
| 128 | <tr> |
|---|
| 129 | <td align="left" valign="top"><code><a name="native">native</a></code></td> |
|---|
| 130 | <td>Implementation defined name_check. Guaranteed to return <i> |
|---|
| 131 | true</i> for all names considered valid by the operating system.<p><b>Side |
|---|
| 132 | effect:</b> Syntax for path constructor <i>src</i> string is implementation |
|---|
| 133 | defined according to the path syntax rules for the operating system.</p> |
|---|
| 134 | <p><b>Use:</b> In path constructors, when the source is operator input or |
|---|
| 135 | other sources which are formatted according to operating system rules. Note |
|---|
| 136 | that <code>default_name_check( native )</code> causes all path src |
|---|
| 137 | strings to be treated according to the path syntax rules for the operating |
|---|
| 138 | system, which may or may not be desirable.</p> |
|---|
| 139 | <p><b>Note:</b> May return <i>true</i> for some names not considered valid |
|---|
| 140 | by the operating system under all conditions (particularly on operating systems which support |
|---|
| 141 | multiple file systems.)</td> |
|---|
| 142 | </tr> |
|---|
| 143 | </table> |
|---|
| 144 | |
|---|
| 145 | <h2>File and directory name <a name="recommendations">recommendations</a></h2> |
|---|
| 146 | |
|---|
| 147 | <table border="1" cellpadding="5" cellspacing="0"> |
|---|
| 148 | |
|---|
| 149 | <tr> |
|---|
| 150 | <td align="center" valign="top"><strong>Recommendation</strong></td> |
|---|
| 151 | <td align="center" valign="top"><strong>Rationale</strong></td> |
|---|
| 152 | </tr> |
|---|
| 153 | <tr> |
|---|
| 154 | <td valign="top">Limit file and directory names to the characters A-Z, a-z, 0-9, period, hyphen, and |
|---|
| 155 | underscore.<p>Use any of the "portable_" <a href="#name_check_functions"> |
|---|
| 156 | name check functions</a> to enforce this recommendation.</td> |
|---|
| 157 | <td valign="top">These are the characters specified by the POSIX standard for portable directory and |
|---|
| 158 | file names, and are also valid for Windows, Mac, and many other modern filesystems.</td> |
|---|
| 159 | </tr> |
|---|
| 160 | <tr> |
|---|
| 161 | <td valign="top">Do not use a period or hyphen as the first |
|---|
| 162 | character of a name. Do not use period as the last character of a name.<p> |
|---|
| 163 | Use <a href="#portable_name">portable_name</a>, |
|---|
| 164 | <a href="#portable_directory_name">portable_directory_name</a>, or |
|---|
| 165 | <a href="#portable_file_name">portable_file_name</a> to enforce this |
|---|
| 166 | recommendation.</td> |
|---|
| 167 | <td valign="top">Some operating systems treat have special rules for the |
|---|
| 168 | first character of names. POSIX, for example. Windows does not permit period |
|---|
| 169 | as the last character.</td> |
|---|
| 170 | </tr> |
|---|
| 171 | <tr> |
|---|
| 172 | <td valign="top">Do not use periods in directory names.<p>Use |
|---|
| 173 | <a href="#portable_directory_name">portable_directory_name</a> to enforce |
|---|
| 174 | this recommendation.</td> |
|---|
| 175 | <td valign="top">Requirement for ISO-9660 without Juliet extensions, OpenVMS native filesystem, and other legacy systems.</td> |
|---|
| 176 | </tr> |
|---|
| 177 | <tr> |
|---|
| 178 | <td valign="top">Do not use more that one period in a file name, and limit |
|---|
| 179 | the portion after the period to three characters.<p>Use |
|---|
| 180 | <a href="#portable_file_name">portable_file_name</a> to enforce this |
|---|
| 181 | recommendation.</td> |
|---|
| 182 | <td valign="top">Requirement for ISO-9660 level 1, OpenVMS native filesystem, and |
|---|
| 183 | other legacy systems. </td> |
|---|
| 184 | </tr> |
|---|
| 185 | <tr> |
|---|
| 186 | <td valign="top">Do not assume names are case sensitive. For example, do not expected a directory to be |
|---|
| 187 | able to hold separate elements named "Foo" and "foo". </td> |
|---|
| 188 | <td valign="top">Some filesystems are case insensitive. For example, Windows |
|---|
| 189 | NTFS is case preserving in the way it stores names, but case insensitive in |
|---|
| 190 | searching for names (unless running under the POSIX sub-system, it which |
|---|
| 191 | case it does case sensitive searches). </td> |
|---|
| 192 | </tr> |
|---|
| 193 | <tr> |
|---|
| 194 | <td valign="top">Do not assume names are case insensitive. For example, do not expect a file |
|---|
| 195 | created with the name of "Foo" to be opened successfully with the name of "foo".</td> |
|---|
| 196 | <td valign="top">Some filesystems are case sensitive. For example, POSIX.</td> |
|---|
| 197 | </tr> |
|---|
| 198 | <tr> |
|---|
| 199 | <td valign="top">Don't use hyphens in names.</td> |
|---|
| 200 | <td valign="top">ISO-9660 level 1, and possibly some legacy systems, do not permit |
|---|
| 201 | hyphens.</td> |
|---|
| 202 | </tr> |
|---|
| 203 | <tr> |
|---|
| 204 | <td valign="top">Limit the length of the string returned by path::string() to |
|---|
| 205 | 255 characters. |
|---|
| 206 | Note that ISO 9660 has an explicit directory tree depth limit of 8, although |
|---|
| 207 | this depth limit is removed by the Juliet extensions.</td> |
|---|
| 208 | <td valign="top">Some operating systems place limits on the total path length. For example, |
|---|
| 209 | Windows 2000 limits paths to 260 characters total length.</td> |
|---|
| 210 | </tr> |
|---|
| 211 | <tr> |
|---|
| 212 | <td valign="top">Limit the length of any one name in a path. Pick the specific limit according to |
|---|
| 213 | the operating systems and or file systems you wish portability to:<br> |
|---|
| 214 | Not a concern:: POSIX, Windows, MAC OS X.<br> |
|---|
| 215 | 31 characters: Classic Mac OS<br> |
|---|
| 216 | 8 characters + period + 3 characters: ISO 9660 level 1<br> |
|---|
| 217 | 32 characters: ISO 9660 level 2 and 3<br> |
|---|
| 218 | 128 characters (64 if unicode): ISO 9660 with Juliet extensions</td> |
|---|
| 219 | <td valign="top">Limiting name length can markedly reduce the expressiveness of file names, yet placing |
|---|
| 220 | only very high limits on lengths inhibits widest portability.</td> |
|---|
| 221 | </tr> |
|---|
| 222 | </table> |
|---|
| 223 | |
|---|
| 224 | <hr> |
|---|
| 225 | <p>Revised |
|---|
| 226 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->01 December, 2003<!--webbot bot="Timestamp" endspan i-checksum="38505" --></p> |
|---|
| 227 | |
|---|
| 228 | <p>© Copyright Beman Dawes, 2002, 2003</p> |
|---|
| 229 | <p> Use, modification, and distribution are subject to the Boost Software |
|---|
| 230 | License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt"> |
|---|
| 231 | LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> |
|---|
| 232 | www.boost.org/LICENSE_1_0.txt</a>)</p> |
|---|
| 233 | |
|---|
| 234 | </body> |
|---|
| 235 | |
|---|
| 236 | </html> |
|---|
