# Portability Guide

## Introduction

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. The file and directory names in paths present a particularly troublesome portability problem.

It is not possible to know in advance if a file or directory name will be valid (and thus portable) for an operating system whose requirements are unknown. There is always the possibility that an operating system could use names which are unusual (number between 17 and 4095, for example) or very limited (maximum of two character names, for example).

It is possible, however, to know if a name is valid for a particular operating system. It is also possible to construct names which are very likely to be portable to a large number of modern and legacy operating systems.

By providing name validity checking facilities, the Filesystem Library allows programmers to ensure that a given name meets the requirements for specific operating systems, or meets the recommendations for general portability.

To do: An implementation should be required to provide check functions for the host O/S, and for the portability recommendations. But it isn't possible to require implementors to supply an open ended number of checking functions. It would be helpful if there was a registry to ensure that checking functions for a particular O/S had the same specification regardless of implementor.

## Limits imposed by specific operating systems

(To be supplied)

Operating system | Check function | Requirements

## File and directory name recommendations

(Very preliminary draft)

Recommendation | Check function | Rationale
Limit file and directory names to the characters A-Z, a-z, 0-9, period, hyphen, and underscore. For even greater portability, don't use hyphens at all. |  | 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. ISO-9660, and possibly some legacy systems, do not permit hyphens at all.
Do not use periods in directory names. |  | Requirement for Requirement for ISO-9660, OpenVMS native filesystem, and other legacy systems.
Do not use more that one period in a file name. |  | Requirement for ISO-9660, OpenVMS native filesystem, and other legacy systems.
Do not use period, hyphen, or underscore as the first character of a file or directory name. |  | Some operating systems treat have special rules for the first character of names. POSIX, for example.
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". |  | 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).
Do not assume names are case insensitive. For example, do not expect a file created with the name of "Foo" to be open successfully with the name of "foo". |  | Some filesystems are case sensitive. For example, POSIX.
Limit the length of names and the depth of the directory tree so that the total length of the string returned by generic_path() to 255 characters. Note that ISO 9660 level 1 has an explicit directory tree depth limit of 8. |  | Some operating systems place limits on the total path length. For example, Windows 2000 limits paths to 260 characters total length.
Limit the length of any one name in a path. Pick the specific limit according to the operating systems you wish portability to: Greater than 31 characters: POSIX, Windows, MAC OS X. 31 characters: Classic Mac OS 8 characters + period + 3 characters: ISO 9660 (CD-ROM) ... |  | Limiting name length can markedly reduce the expressiveness of file names, yet placing only very high limits on lengths inhibits wide portability.

© Copyright Beman Dawes, 2002

Revised 13 September, 2002