ceph/src/boost/libs/filesystem/doc/portability_guide.htm

   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
  16 Name Portability
  17 Guide</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> &nbsp;&nbsp;
  23     <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
  24     <a href="reference.html">Reference</a> &nbsp;&nbsp;
  25     <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
  26     <a href="release_history.html">Releases</a> &nbsp;&nbsp;
  27     <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
  28     <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
  29     <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
  30     <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
  31     <a href="issue_reporting.html">Bug Reports </a>&nbsp;&nbsp;
  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
  41 guarantee that a program using Boost.Filesystem will be portable between
  42 operating systems. Critical aspects of I/O such as how the operating system
  43 interprets 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
  45 valid (and thus portable) for an unknown operating system. There is always the possibility that an operating system could use
  46 names which are unusual (numbers less than 4096, for example) or very
  47 limited in size (maximum of six character names, for example). In other words,
  48 portability is never absolute; it is always relative to specific operating
  49 systems or
  50 file 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
  52 operating system.&nbsp;It is also possible to construct names which are
  53 likely 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
  56 minimum, they support a native file system plus a CD-ROM file system (Generally
  57 ISO-9669, often with Juliet extensions).</p>
  58
  59 <p>Each file system
  60 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
  61 for those file systems differ. Each file system may also have
  62 differing rules for overall path validity, such as a maximum length or number of
  63 sub-directories. Some legacy systems have different rules for directory names
  64 versus regular file names.</p>
  65
  66 <p>As a result, Boost.Filesystem's <i>name_check</i> functions
  67 cannot guarantee directory and file name portability. Rather, they are intended to
  68 give the programmer a &quot;fighting chance&quot; to achieve portability by early
  69 detection 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
  74 returns true if its argument is valid as a directory and regular file name for a
  75 particular 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
  78 interest because it has been carefully designed to provide wide
  79 portability 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&amp;<i> name</i>)</code></td>
  92     <td><b>Returns:</b> <i>true</i> if <code>!name.empty() &amp;&amp; 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&amp;<i> name</i>)</code></td>
 102     <td><b>Returns:</b>&nbsp; <i>true</i> if <code>!name.empty() &amp;&amp; name</code> contains
 103     only the characters specified by the Windows platform SDK as valid
 104     regardless of the file system <code>&amp;&amp; (name</code> is <code>&quot;.&quot;</code> or
 105     <code>&quot;..&quot;</code>&nbsp; or does not end with a trailing space or period<code>)</code>.&nbsp;
 106     The allowed characters are anything except <code>0x0-0x1F</code>, <code>'&lt;'</code>,
 107     <code>'&gt;'</code>, <code>':'</code>, <code>'&quot;'</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&amp;<i> name</i>)</code></td>
 118     <td><b>Returns:</b> <code>&nbsp;windows_name(name) &amp;&amp; portable_posix_name(name)
 119     &amp;&amp; (name</code> is <code>&quot;.&quot;</code> or <code>&quot;..&quot;</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&amp;<i> name</i>)</code></td>
 127     <td><b>Returns:</b> <code>portable_name(name) &amp;&amp; (name</code> is <code>&quot;.&quot;</code>
 128     or <code>&quot;..&quot;</code>&nbsp; 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&amp;<i> name</i>)</code></td>
 134     <td><b>Returns:</b> <code>portable_name(name) &amp;&amp; </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 &quot;file extension&quot;
 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&amp;<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 &quot;portable_&quot; <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 &quot;Foo&quot; and &quot;foo&quot;. </td>
 194     <td valign="top">Some file systems are case insensitive.&nbsp; 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.&nbsp; For example, do not expect a file
 201     created with the name of &quot;Foo&quot; to be opened successfully with the name of &quot;foo&quot;.</td>
 202     <td valign="top">Some file systems are case sensitive.&nbsp; 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.&nbsp;
 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.&nbsp; 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.&nbsp; Pick the specific limit according to
 219     the operating systems and or file systems you wish portability to:<br>
 220     &nbsp;&nbsp; Not a concern::&nbsp; POSIX, Windows, MAC OS X.<br>
 221     &nbsp;&nbsp; 31 characters: Classic Mac OS<br>
 222 &nbsp;&nbsp; 8 characters + period + 3 characters: ISO 9660 level 1<br>
 223 &nbsp;&nbsp; 32 characters: ISO 9660 level 2 and 3<br>
 224 &nbsp;&nbsp; 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>&copy; Copyright Beman Dawes, 2002, 2003</p>
 235 <p> Use, modification, and distribution are subject to the Boost Software
 236 License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">
 237 LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 238 www.boost.org/LICENSE_1_0.txt</a>)</p>
 239
 240 </body>
 241
 242 </html>