242 lines
12 KiB
HTML
242 lines
12 KiB
HTML
|
<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>
|
||
|
|
<a href="tutorial.html">Tutorial</a>
|
||
|
|
<a href="reference.html">Reference</a>
|
||
|
|
<a href="faq.htm">FAQ</a>
|
||
|
|
<a href="release_history.html">Releases</a>
|
||
|
|
<a href="portability_guide.htm">Portability</a>
|
||
|
|
<a href="v4.html">V4</a>
|
||
|
|
<a href="v3.html">V3 Intro</a>
|
||
|
|
<a href="v3_design.html">V3 Design</a>
|
||
|
|
<a href="deprecated.html">Deprecated</a>
|
||
|
|
<a href="issue_reporting.html">Bug Reports </a>
|
||
|
|
</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. 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 "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>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&<i> name</i>)</code></td>
|
||
|
|
<td><b>Returns:</b> <i>true</i> if <code>!name.empty() && 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&<i> name</i>)</code></td>
|
||
|
|
<td><b>Returns:</b> <i>true</i> if <code>!name.empty() && name</code> contains
|
||
|
|
only the characters specified by the Windows platform SDK as valid
|
||
|
|
regardless of the file system <code>&& (name</code> is <code>"."</code> or
|
||
|
|
<code>".."</code> or does not end with a trailing space or period<code>)</code>.
|
||
|
|
The allowed characters are anything except <code>0x0-0x1F</code>, <code>'<'</code>,
|
||
|
|
<code>'>'</code>, <code>':'</code>, <code>'"'</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&<i> name</i>)</code></td>
|
||
|
|
<td><b>Returns:</b> <code> windows_name(name) && portable_posix_name(name)
|
||
|
|
&& (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
|
||
|
|
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&<i> name</i>)</code></td>
|
||
|
|
<td><b>Returns:</b> <code>portable_name(name) && (name</code> is <code>"."</code>
|
||
|
|
or <code>".."</code> 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&<i> name</i>)</code></td>
|
||
|
|
<td><b>Returns:</b> <code>portable_name(name) && </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 "file extension"
|
||
|
|
but limit its length.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><code><a name="native">native</a>(const
|
||
|
|
std::string&<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 "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 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 "Foo" and "foo". </td>
|
||
|
|
<td valign="top">Some file systems 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 file systems 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>© 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>
|