diff options
Diffstat (limited to 'docs/canonical_filenames.html')
| -rw-r--r-- | docs/canonical_filenames.html | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/docs/canonical_filenames.html b/docs/canonical_filenames.html new file mode 100644 index 0000000..c1c03b1 --- /dev/null +++ b/docs/canonical_filenames.html @@ -0,0 +1,156 @@ +<HTML> +<HEAD><TITLE>APR Canonical Filenames</TITLE></HEAD> +<BODY> +<h1>APR Canonical Filename</h1> + +<h2>Requirements</h2> + +<p>APR porters need to address the underlying discrepancies between +file systems. To achieve a reasonable degree of security, the +program depending upon APR needs to know that two paths may be +compared, and that a mismatch is guaranteed to reflect that the +two paths do not return the same resource</p>. + +<p>The first discrepancy is in volume roots. Unix and pure derivatives +have only one root path, "/". Win32 and OS2 share root paths of +the form "D:/", D: is the volume designation. However, this can +be specified as "//./D:/" as well, indicating D: volume of the +'this' machine. Win32 and OS2 also may employ a UNC root path, +of the form "//server/share/" where share is a share-point of the +specified network server. Finally, NetWare root paths are of the +form "server/volume:/", or the simpler "volume:/" syntax for 'this' +machine. All these non-Unix file systems accept volume:path, +without a slash following the colon, as a path relative to the +current working directory, which APR will treat as ambiguous, that +is, neither an absolute nor a relative path per se.</p> + +<p>The second discrepancy is in the meaning of the 'this' directory. +In general, 'this' must be eliminated from the path where it occurs. +The syntax "path/./" and "path/" are both aliases to path. However, +this isn't file system independent, since the double slash "//" has +a special meaning on OS2 and Win32 at the start of the path name, +and is invalid on those platforms before the "//server/share/" UNC +root path is completed. Finally, as noted above, "//./volume/" is +legal root syntax on WinNT, and perhaps others.</p> + +<p>The third discrepancy is in the context of the 'parent' directory. +When "parent/path/.." occurs, the path must be unwound to "parent". +It's also critical to simply truncate leading "/../" paths to "/", +since the parent of the root is root. This gets tricky on the +Win32 and OS2 platforms, since the ".." element is invalid before +the "//server/share/" is complete, and the "//server/share/../" +sequence is the complete UNC root "//server/share/". In relative +paths, leading ".." elements are significant, until they are merged +with an absolute path. The relative form must only retain the ".." +segments as leading segments, to be resolved once merged to another +relative or an absolute path.</p> + +<p>The fourth discrepancy occurs with acceptance of alternate character +codes for the same element. Path separators are not retained within +the APR canonical forms. The OS filesystem and APR (slashed) forms +can both be returned as strings, to be used in the proper context. +Unix, Win32 and Netware all accept slashes and backslashes as the +same path separator symbol, although unix strictly accepts slashes. +While the APR form of the name strictly uses slashes, always consider +that there could be a platform that actually accepts slashes as a +character within a segment name.</p> + +<p>The fifth and worst discrepancy plagues Win32, OS2, Netware, and some +filesystems mounted in Unix. Case insensitivity can permit the same +file to slip through in both it's proper case and alternate cases. +Simply changing the case is insufficient for any character set beyond +ASCII, since various dialectic forms of characters suffer from one to +many or many to one translations. An example would be u-umlaut, which +might be accepted as a single character u-umlaut, a two character +sequence u and the zero-width umlaut, the upper case form of the same, +or perhaps even a capital U alone. This can be handled in different +ways depending on the purposes of the APR based program, but the one +requirement is that the path must be absolute in order to resolve these +ambiguities. Methods employed include comparison of device and inode +file uniqifiers, which is a fairly fast operation, or querying the OS +for the true form of the name, which can be much slower. Only the +acknowledgement of the file names by the OS can validate the equality +of two different cases of the same filename.</p> + +<p>The sixth discrepancy, illegal or insignificant characters, is especially +significant in non-unix file systems. Trailing periods are accepted +but never stored, therefore trailing periods must be ignored for any +form of comparison. And all OS's have certain expectations of what +characters are illegal (or undesirable due to confusion.)</p> + +<p>A final warning, canonical functions don't transform or resolve case +or character ambiguity issues until they are resolved into an absolute +path. The relative canonical path, while useful, while useful for URL +or similar identifiers, cannot be used for testing or comparison of file +system objects.</p> + +<hr> + +<h2>Canonical API</h2> + +Functions to manipulate the apr_canon_file_t (an opaque type) include: + +<ul> +<li>Create canon_file_t (from char* path and canon_file_t parent path) +<li>Merged canon_file_t (from path and parent, both canon_file_t) +<li>Get char* path of all or some segments +<li>Get path flags of IsRelative, IsVirtualRoot, and IsAbsolute +<li>Compare two canon_file_t structures for file equality +</ul> + +<p>The path is corrected to the file system case only if is in absolute +form. The apr_canon_file_t should be preserved as long as possible and +used as the parent to create child entries to reduce the number of expensive +stat and case canonicalization calls to the OS.</p> + +<p>The comparison operation provides that the APR can postpone correction +of case by simply relying upon the device and inode for equivalence. The +stat implementation provides that two files are the same, while their +strings are not equivalent, and eliminates the need for the operating +system to return the proper form of the name.</p> + +<p>In any case, returning the char* path, with a flag to request the proper +case, forces the OS calls to resolve the true names of each segment. Where +there is a penalty for this operation and the stat device and inode test +is faster, case correction is postponed until the char* result is requested. +On platforms that identify the inode, device, or proper name interchangably +with no penalties, this may occur when the name is initially processed.</p> + +<hr> + +<h2>Unix Example</h2> + +<p>First the simplest case:</p> + +<pre> +Parse Canonical Name +accepts parent path as canonical_t + this path as string + +Split this path Segments on '/' + +For each of this path Segments + If first Segment + If this Segment is Empty ([nothing]/) + Append this Root Segment (don't merge) + Continue to next Segment + Else is relative + Append parent Segments (to merge) + Continue with this Segment + If Segment is '.' or empty (2 slashes) + Discard this Segment + Continue with next Segment + If Segment is '..' + If no previous Segment or previous Segment is '..' + Append this Segment + Continue with next Segment + If previous Segment and previous is not Root Segment + Discard previous Segment + Discard this Segment + Continue with next Segment + Append this Relative Segment + Continue with next Segment +</pre> + +</BODY> +</HTML> |