devn00b
/
EQ2EMu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242
							<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=utf-8">
<title>Portability Guide</title>
<link href="styles.css" rel="stylesheet">
</head>

<body bgcolor="#FFFFFF">

<h1>
<img border="0" src="../../../boost.png" align="center" width="300" height="86">Path
Name Portability
Guide</h1>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
 bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  <tr>
    <td><a href="index.htm">Home</a> &nbsp;&nbsp;
    <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
    <a href="reference.html">Reference</a> &nbsp;&nbsp;
    <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
    <a href="release_history.html">Releases</a> &nbsp;&nbsp;
    <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
    <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
    <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
    <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
    <a href="issue_reporting.html">Bug Reports </a>&nbsp;&nbsp;
    </td>
</table>

<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 Boost.Filesystem 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
systems or
file systems.</p>
<p>It is possible, however, to know in advance if a directory or file name is likely to be valid for a particular
operating system.&nbsp;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 Joliet 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 those file systems differ. Each file system may also have
differing rules for overall path validity, such as a maximum length or number of
sub-directories. Some legacy systems have different rules for directory names
versus regular file names.</p>

<p>As a result, Boost.Filesystem's <i>name_check</i> functions
cannot guarantee directory and file name portability. Rather, they are intended to
give the programmer a &quot;fighting chance&quot; 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>name_check</i> function
returns true if its argument is valid as a directory and regular file name for a
particular operating or file system. A number of these functions are provided.</p>

<p>The <a href="#portable_name">portable_name</a> function is of particular
interest because it has been carefully designed to provide wide
portability yet not overly restrict expressiveness.</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>Function</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>(const
    std::string&amp;<i> name</i>)</code></td>
    <td><b>Returns:</b> <i>true</i> if <code>!name.empty() &amp;&amp; name</code> contains 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>
    The allowed characters are <code>0-9</code>, <code>a-z</code>, <code>A-Z</code>,
    <code>'.'</code>, <code>'_'</code>, and <code>'-'</code>.<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>(const
    std::string&amp;<i> name</i>)</code></td>
    <td><b>Returns:</b>&nbsp; <i>true</i> if <code>!name.empty() &amp;&amp; name</code> contains
    only the characters specified by the Windows platform SDK as valid
    regardless of the file system <code>&amp;&amp; (name</code> is <code>&quot;.&quot;</code> or
    <code>&quot;..&quot;</code>&nbsp; or does not end with a trailing space or period<code>)</code>.&nbsp;
    The allowed characters are anything except <code>0x0-0x1F</code>, <code>'&lt;'</code>,
    <code>'&gt;'</code>, <code>':'</code>, <code>'&quot;'</code>, <code>'/'</code>,
    <code>'\'</code>, and <code>'|'</code>.<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>(const
    std::string&amp;<i> name</i>)</code></td>
    <td><b>Returns:</b> <code>&nbsp;windows_name(name) &amp;&amp; portable_posix_name(name)
    &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
    modern operating systems, large and small, and to some legacy O/S's. The
    first character not a period or hyphen restriction is a requirement of
    several older operating systems.</td>
  </tr>
  <tr>
    <td align="left" valign="top"><code><a name="portable_directory_name">
    portable_directory_name</a>(const std::string&amp;<i> name</i>)</code></td>
    <td><b>Returns:</b> <code>portable_name(name) &amp;&amp; (name</code> is <code>&quot;.&quot;</code>
    or <code>&quot;..&quot;</code>&nbsp; or contains no periods<code>)</code>.<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>(const std::string&amp;<i> name</i>)</code></td>
    <td><b>Returns:</b> <code>portable_name(name) &amp;&amp; </code>any period is followed by one to three additional
    non-period 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 &quot;file extension&quot;
    but limit its length.</td>
  </tr>
  <tr>
    <td align="left" valign="top"><code><a name="native">native</a>(const
    std::string&amp;<i> name</i>)</code></td>
    <td><b>Returns:</b> Implementation defined. Returns <i>
    true</i> for names considered valid by the operating system's native file
    systems.<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 &quot;portable_&quot; <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 file systems.</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 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 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 &quot;Foo&quot; and &quot;foo&quot;. </td>
    <td valign="top">Some file systems are case insensitive.&nbsp; 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.&nbsp; For example, do not expect a file
    created with the name of &quot;Foo&quot; to be opened successfully with the name of &quot;foo&quot;.</td>
    <td valign="top">Some file systems are case sensitive.&nbsp; 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.&nbsp;
    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.&nbsp; 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.&nbsp; Pick the specific limit according to
    the operating systems and or file systems you wish portability to:<br>
    &nbsp;&nbsp; Not a concern::&nbsp; POSIX, Windows, MAC OS X.<br>
    &nbsp;&nbsp; 31 characters: Classic Mac OS<br>
&nbsp;&nbsp; 8 characters + period + 3 characters: ISO 9660 level 1<br>
&nbsp;&nbsp; 32 characters: ISO 9660 level 2 and 3<br>
&nbsp;&nbsp; 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 -->29 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38652" --></p>

<p>&copy; 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>