mirror of
https://github.com/boostorg/filesystem.git
synced 2026-02-27 17:02:19 +00:00
229 lines
12 KiB
HTML
229 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=windows-1252">
|
||
<title>Portability Guide</title>
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF">
|
||
|
||
<h1>
|
||
<img border="0" src="../../../c++boost.gif" align="center" width="277" height="86">Path
|
||
Name Portability
|
||
Guide</h1>
|
||
|
||
<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 the Filesystem Library 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 or
|
||
file systems.</p>
|
||
<p>It is possible 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>Some operating systems support multiple file systems, and 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 some of those file systems differ a great deal. Each file system may have
|
||
differing rules for overall path validity, such as a maximum length or number of
|
||
sub-directories.</p>
|
||
|
||
<p>As a result, the Boost Filesystem Library's <i>name_check</i> mechanism
|
||
cannot guarantee directory and file name portability. Rather, it is 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><a href="path.htm#name_check_typedef">name_check</a></i> function
|
||
returns true if its argument is a valid name for a particular operating or file
|
||
system. A number of these functions are supplied, and user-supplied <i>
|
||
name_check</i> functions are also allowed.</p>
|
||
|
||
<p>The <a href="#portable_name">portable_name</a> function is of particular
|
||
interest because it is the initial <a href="path.htm#name_check_mechanism">
|
||
default name_check function</a> and is carefully chosen to provide wide
|
||
portability yet without severe restrictions on expressiveness.</p>
|
||
|
||
<p>The <a href="#native">native</a> function is of particular interest because
|
||
it is often used when the source of the path is operator input or other sources
|
||
which are formatted according to operating system rules.</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>Name</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></code></td>
|
||
<td>Returns <i>true</i> for names containing 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>
|
||
Only characters allowed are 0-9, a-z, A-Z, '.', '_', and '-'.<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></code></td>
|
||
<td>Returns <i>true</i> for names containing only the characters
|
||
specified by the Windows platform SDK as valid regardless of the file
|
||
system. Allows any character except 0x0-0x1F, '<', '>', ':', '"', '/', '\',
|
||
and '|'. Furthermore, names must not end with a trailing space or period.<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></code></td>
|
||
<td><code>windows_name(name) && portable_posix_name(name)</code>,
|
||
and first character not period or hyphen.<p>
|
||
<b>Note:</b> This is the initial default name_check.</p>
|
||
<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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left" valign="top"><code><a name="portable_directory_name">
|
||
portable_directory_name</a></code></td>
|
||
<td><code>portable_name(name)</code>, and no periods.<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></code></td>
|
||
<td><code>portable_name(name)</code>,except allows one
|
||
period only, and only if followed by one to three additional 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="no_check">no_check</a></code></td>
|
||
<td>Returns <i>true</i>.<p><b>Use: </b>When the generic grammar
|
||
is desired, but name checking is not desired. For example, a program which
|
||
traffics in names created elsewhere may have no choice but to accept those
|
||
names. Another example is a application which prefers to use the Filesystem
|
||
Library and its generic grammar, but is uninterested in portability. An
|
||
alternative to <code>no_check</code> might be <code>native</code>, but <code>native</code>
|
||
has the side effect of altering the grammar accepted.</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left" valign="top"><code><a name="native">native</a></code></td>
|
||
<td>Implementation defined name_check. Guaranteed to return <i>
|
||
true</i> for all names considered valid by the operating system.<p><b>Side
|
||
effect:</b> Syntax for path constructor <i>src</i> string is implementation
|
||
defined according to the path syntax rules for the operating system.</p>
|
||
<p><b>Use:</b> In path constructors, when the source is operator input or
|
||
other sources which are formatted according to operating system rules. Note
|
||
that <code>default_name_check( native )</code> causes all path src
|
||
strings to be treated according to the path syntax rules for the operating
|
||
system, which may or may not be desirable.</p>
|
||
<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 filesystems.</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 Requirement for ISO-9660, OpenVMS native
|
||
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, OpenVMS native 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 filesystems 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 filesystems are case sensitive. For example, POSIX.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">Don't use hyphens in names.</td>
|
||
<td valign="top">ISO-9660, and possibly some legacy systems, do not permit
|
||
hyphens.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">Limit the length of names and the depth of the directory
|
||
tree so that the total length of the string returned by path::string() to
|
||
255 characters.
|
||
Note that ISO 9660 level 1 has an explicit directory tree depth limit of 8.</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 you wish portability to:<br>
|
||
Greater than 31 characters: POSIX, Windows, MAC OS X.<br>
|
||
31 characters: Classic Mac OS<br>
|
||
8 characters + period + 3 characters: ISO 9660 level 1 (CD-ROM)</td>
|
||
<td valign="top">Limiting name length can markedly reduce the expressiveness of file names, yet placing
|
||
only very high limits on lengths inhibits wide portability.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<p>© Copyright Beman Dawes, 2002, 2003</p>
|
||
<p>See accompanying <a href="../../../LICENSE">license</a> for terms and
|
||
conditions of use.</p>
|
||
<p>Revised
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->14 September, 2003<!--webbot bot="Timestamp" endspan i-checksum="39340" --></p>
|
||
|
||
</body>
|
||
|
||
</html> |