Skip to content

Commit

Permalink
Spelling corrections in docs;
Browse files Browse the repository at this point in the history
Pull request #6
docs/APRDesign.html
docs/canonical_filenames.html
docs/incomplete_types
Submitted by: "Bruno P. Kinoshita" <brunodepaulak yahoo.com.br>

Pull request #10
misc/unix/errorcodes.c 
Submitted by: Jimmy Casey <casey.jimmy gmail.com>

Backports: r1839622


git-svn-id: https://svn.apache.org/repos/asf/apr/apr/branches/1.7.x@1839623 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information
wrowe committed Aug 30, 2018
1 parent 49a5e69 commit 9dfa236
Show file tree
Hide file tree
Showing 4 changed files with 22 additions and 22 deletions.
10 changes: 5 additions & 5 deletions docs/APRDesign.html
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ <h2>Creating an APR Type</h2>
<p>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:</p>

<ul>
Expand Down Expand Up @@ -227,7 +227,7 @@ <h2>Documentation</h2>

<p>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.</p>

<h2>APR Error reporting</h2>
Expand All @@ -246,7 +246,7 @@ <h2>APR Error reporting</h2>

<p>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.</p>
There are five types of error values in APR, each with its own offset.</p>

<!-- This should be turned into a table, but I am lazy today -->
<pre>
Expand Down Expand Up @@ -277,7 +277,7 @@ <h2>APR Error reporting</h2>

<strong>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.</strong>
the error code indicates an error condition or a status condition.</strong>

<p>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
Expand Down Expand Up @@ -345,7 +345,7 @@ <h2>APR Error reporting</h2>
an error string. If we convert all errors to a common subset, we have four
steps to output an error string:</p>

<p>The seocnd problem with option 1, is that it is a lossy conversion. For
<p>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
Expand Down
26 changes: 13 additions & 13 deletions docs/canonical_filenames.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ <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 guarenteed to reflect that the
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 deriviates
<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
Expand All @@ -21,7 +21,7 @@ <h2>Requirements</h2>
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.</p>

<p>The second discrepancy is in the meaning of the 'this' directory.
Expand All @@ -39,35 +39,35 @@ <h2>Requirements</h2>
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.</p>

<p>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.</p>

<p>The fifth and worst discrepancy plauges Win32, OS2, Netware, and some
<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 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.</p>
Expand All @@ -76,7 +76,7 @@ <h2>Requirements</h2>
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.)</p>
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
Expand Down Expand Up @@ -111,10 +111,10 @@ <h2>Canonical API</h2>

<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 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.</p>
with no penalties, this may occur when the name is initially processed.</p>

<hr>

Expand Down
6 changes: 3 additions & 3 deletions docs/incomplete_types
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion misc/unix/errorcodes.c
Original file line number Diff line number Diff line change
Expand Up @@ -369,7 +369,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)
Expand Down

0 comments on commit 9dfa236

Please sign in to comment.