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