From 9c9e45b67f0900ce1062b626aa016f0ccff57376 Mon Sep 17 00:00:00 2001
From: "William A. Rowe Jr" The current design of APR requires that most APR types be incomplete.
It is not possible to write flexible portable code if programs can access
the internals of APR types. This is because different platforms are
-likely to define different native types. There are only two execptions to
+likely to define different native types. There are only two exceptions to
this rule: For an actual example, look at any file in the include directory. The
reason the docs are in the header files is to ensure that the docs always
-reflect the current code. If you change paramters or return values for a
+reflect the current code. If you change parameters or return values for a
function, please be sure to update the documentation. All platforms return errno values unchanged. Each platform can also have
one system error type, which can be returned after an offset is added.
-There are five types of error values in APR, each with it's own offset.Creating an APR Type
@@ -227,7 +227,7 @@
Documentation
APR Error reporting
@@ -246,7 +246,7 @@ APR Error reporting
@@ -277,7 +277,7 @@APR Error reporting
The difference in naming between APR_OS_START_ERROR and APR_OS_START_STATUS mentioned above allows programmers to easily determine if -the error code indicates an error condition or a status codition. +the error code indicates an error condition or a status condition.If your function has multiple return codes that all indicate success, but with different results, or if your function can only return PASS/FAIL, you @@ -345,7 +345,7 @@
APR Error reporting
an error string. If we convert all errors to a common subset, we have four steps to output an error string: -The seocnd problem with option 1, is that it is a lossy conversion. For +
The second problem with option 1, is that it is a lossy conversion. For example, Windows and OS/2 have a couple hundred error codes, but POSIX errno only defines about 50 errno values. This means that if we convert to a canonical error value immediately, there is no way for the programmer to diff --git a/docs/canonical_filenames.html b/docs/canonical_filenames.html index 2bd9bdba822..c1c03b1d543 100644 --- a/docs/canonical_filenames.html +++ b/docs/canonical_filenames.html @@ -8,10 +8,10 @@
Requirements
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 guarenteed to reflect that the +compared, and that a mismatch is guaranteed to reflect that the two paths do not return the same resource
. -The first discrepancy is in volume roots. Unix and pure deriviates +
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 @@ -21,7 +21,7 @@
Requirements
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 ambigious, that +current working directory, which APR will treat as ambiguous, that is, neither an absolute nor a relative path per se.The second discrepancy is in the meaning of the 'this' directory. @@ -39,35 +39,35 @@
Requirements
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/../" -seqence is the complete UNC root "//server/share/". In relative +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.The fourth discrepancy occurs with acceptance of alternate character -codes for the same element. Path seperators are not retained within +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 seperator symbol, although unix strictly accepts slashes. +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.
-The fifth and worst discrepancy plauges Win32, OS2, Netware, and some +
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 dilectic forms of characters suffer from one to +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 captial U alone. This can be handled in different +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 quering the OS +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.
@@ -76,7 +76,7 @@Requirements
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 undesireable due to confusion.) +characters are illegal (or undesirable due to confusion.)A final warning, canonical functions don't transform or resolve case or character ambiguity issues until they are resolved into an absolute @@ -111,10 +111,10 @@
Canonical API
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 penality for this operation and the stat device and inode test +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 penalities, this may occur when the name is initially processed.
+with no penalties, this may occur when the name is initially processed.
diff --git a/docs/incomplete_types b/docs/incomplete_types index cbed7774232..08b0c0a522e 100644 --- a/docs/incomplete_types +++ b/docs/incomplete_types @@ -38,7 +38,7 @@ typedef struct ap_file_t { #endif } ap_file_t; -This captures the essense of what is currently being defined for ap_file_t +This captures the essence of what is currently being defined for ap_file_t using incomplete types. However, using this structure leads developers to believe that they are safe accessing any of the fields in this structure. This is not true. On some platforms, such as Windows, about half of the @@ -53,7 +53,7 @@ macros, for example: #define filetype int #endif -And then in the defintion for ap_file_t, we could say: +And then in the definition for ap_file_t, we could say: filetype filedes; This gets rid of some of the complexity, by moving it off to the side, but @@ -73,7 +73,7 @@ Having said all of that, sometimes incomplete types just don't make sense. For example, the first implementation of time functions used incomplete types, which added a layer of complexity that turned out to be unnecessary. If a platform cannot provide a simple number that represents the number of seconds -elapsed since a specifed date and time, then APR doesn't really want to +elapsed since a specified date and time, then APR doesn't really want to provide support for that platform. APR is trying hard to provide a balance of incomplete and complete types, diff --git a/misc/unix/errorcodes.c b/misc/unix/errorcodes.c index 4f9b1d92474..a45d43f528b 100644 --- a/misc/unix/errorcodes.c +++ b/misc/unix/errorcodes.c @@ -380,7 +380,7 @@ static char *native_strerror(apr_status_t statcode, char *buf, /* glibc style */ /* BeOS has the function available, but it doesn't provide - * the prototype publically (doh!), so to avoid a build warning + * the prototype publicly (doh!), so to avoid a build warning * we add a suitable prototype here. */ #if defined(BEOS)