From: Rich Bowen Date: Fri, 17 Apr 2026 15:55:03 +0000 (+0000) Subject: Style guide: use rather than for httpd programs. X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=67878bd95797d2da0e6e11f74c5febd1c504c8dd;p=thirdparty%2Fapache%2Fhttpd.git Style guide: use rather than for httpd programs. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1933136 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/programs/ab.xml b/docs/manual/programs/ab.xml index 4c32c397a0..e6f5f8fa3a 100644 --- a/docs/manual/programs/ab.xml +++ b/docs/manual/programs/ab.xml @@ -26,7 +26,7 @@ ab - Apache HTTP server benchmarking tool -

ab is a tool for benchmarking your Apache Hypertext +

ab is a tool for benchmarking your Apache Hypertext Transfer Protocol (HTTP) server. It is designed to give you an impression of how your current Apache installation performs. This especially shows you how many requests per second your Apache installation is capable of @@ -164,7 +164,7 @@ needed).

-q
-
When processing more than 150 requests, ab outputs a +
When processing more than 150 requests, ab outputs a progress count on stderr every 10% or 100 requests or so. The -q flag will suppress these messages.
@@ -237,7 +237,7 @@
Output -

The following list describes the values returned by ab: +

The following list describes the values returned by ab:

@@ -330,7 +330,7 @@

It does not implement HTTP/1.x fully; only accepts some 'expected' forms of responses. The rather heavy use of strstr(3) shows up top in profile, which might indicate a performance problem; i.e., you - would measure the ab performance rather than the server's.

+ would measure the ab performance rather than the server's.

diff --git a/docs/manual/programs/apachectl.xml b/docs/manual/programs/apachectl.xml index bae6512a7c..da09e01de8 100644 --- a/docs/manual/programs/apachectl.xml +++ b/docs/manual/programs/apachectl.xml @@ -26,27 +26,27 @@ apachectl - Apache HTTP Server Control Interface -

apachectl is a front end to the Apache HyperText +

apachectl is a front end to the Apache HyperText Transfer Protocol (HTTP) server. It is designed to help the administrator control the functioning of the Apache httpd daemon.

-

The apachectl script can operate in two modes. +

The apachectl script can operate in two modes. First, it can act as a simple front-end to the httpd command that simply sets any necessary environment variables and then invokes httpd, passing through any command line - arguments. Second, apachectl can act as a SysV init + arguments. Second, apachectl can act as a SysV init script, taking simple one-word arguments like start, restart, and stop, and translating them into appropriate signals to httpd.

If your Apache installation uses non-standard paths, you will - need to edit the apachectl script to set the + need to edit the apachectl script to set the appropriate paths to the httpd binary. You can also specify any necessary httpd command line arguments. See the comments in the script for details.

-

The apachectl script returns a 0 exit value on +

The apachectl script returns a 0 exit value on success, and >0 if an error occurs. For more details, view the comments in the script.

 @@ -58,13 +58,13 @@
Synopsis -

When acting in pass-through mode, apachectl can take +

When acting in pass-through mode, apachectl can take all the arguments available for the httpd binary.

apachectl [ httpd-argument ]

-

When acting in SysV init mode, apachectl takes simple, +

When acting in SysV init mode, apachectl takes simple, one-word commands, defined below.

apachectl command

diff --git a/docs/manual/programs/apxs.xml b/docs/manual/programs/apxs.xml index af8e442a06..da5c60ed67 100644 --- a/docs/manual/programs/apxs.xml +++ b/docs/manual/programs/apxs.xml @@ -26,7 +26,7 @@ apxs - APache eXtenSion tool -

apxs is a tool for building and installing extension +

apxs is a tool for building and installing extension modules for the Apache HyperText Transfer Protocol (HTTP) server. This is achieved by building a dynamic shared object (DSO) from one or more source or object files which then can be loaded into the Apache server @@ -35,7 +35,7 @@

So to use this extension mechanism your platform has to support the DSO feature and your Apache httpd binary has to be built with the - mod_so module. The apxs tool automatically + mod_so module. The apxs tool automatically complains if this is not the case. You can check this yourself by manually running the command

@@ -48,7 +48,7 @@ $ httpd -l

The module mod_so should be part of the displayed list. If these requirements are fulfilled you can easily extend your Apache server's functionality by installing your own modules with the DSO mechanism - by the help of this apxs tool:

+ by the help of this apxs tool:

@@ -67,14 +67,14 @@ $ _

The arguments files can be any C source file (.c), a object - file (.o) or even a library archive (.a). The apxs tool + file (.o) or even a library archive (.a). The apxs tool automatically recognizes these extensions and automatically used the C source files for compilation while just using the object and archive files for the linking phase. But when using such pre-compiled objects make sure they are compiled for position independent code (PIC) to be able to use them for a dynamically loaded shared object. For instance with GCC you always just have to use -fpic. For other C compilers consult its - manual page or at watch for the flags apxs uses to compile the + manual page or at watch for the flags apxs uses to compile the object files.

For more details about DSO support in Apache read the documentation of @@ -127,7 +127,7 @@ $ _

This explicitly sets the module name for the -i (install) and -g (template generation) option. Use this to explicitly specify the module name. For option -g this is required, for - option -i the apxs tool tries to determine the + option -i the apxs tool tries to determine the name from the source or (as a fallback) at least by guessing it from the filename.
@@ -270,7 +270,7 @@ $ _

Then you have to update the Apache configuration by making sure a LoadModule directive is present to - load this shared object. To simplify this step apxs provides + load this shared object. To simplify this step apxs provides an automatic way to install the shared object in its "modules" directory and updating the httpd.conf file accordingly. This can be achieved by running:

diff --git a/docs/manual/programs/dbmmanage.xml b/docs/manual/programs/dbmmanage.xml index 86985512a0..48946ab6be 100644 --- a/docs/manual/programs/dbmmanage.xml +++ b/docs/manual/programs/dbmmanage.xml @@ -26,11 +26,11 @@ dbmmanage - Manage user authentication files in DBM format -

dbmmanage is used to create and update the DBM format files +

dbmmanage is used to create and update the DBM format files used to store usernames and password for basic authentication of HTTP users via mod_authn_dbm. Resources available from the Apache HTTP server can be restricted to just - the users listed in the files created by dbmmanage. This + the users listed in the files created by dbmmanage. This program can only be used when the usernames are stored in a DBM file. To use a flat-file database see htpasswd.

@@ -166,19 +166,19 @@ may exist on your system. The three primary examples are SDBM, NDBM, the GNU project's GDBM, and Berkeley DB 2. Unfortunately, all these libraries use different file formats, and you must make sure that the file format used - by filename is the same format that dbmmanage - expects to see. dbmmanage currently has no way of determining + by filename is the same format that dbmmanage + expects to see. dbmmanage currently has no way of determining what type of DBM file it is looking at. If used against the wrong format, will simply return nothing, or may create a different DBM file with a different name, or at worst, it may corrupt the DBM file if you were attempting to write to it.

-

dbmmanage has a list of DBM format preferences, defined by +

dbmmanage has a list of DBM format preferences, defined by the @AnyDBM::ISA array near the beginning of the program. Since we prefer the Berkeley DB 2 file format, the order in which - dbmmanage will look for system libraries is Berkeley DB 2, + dbmmanage will look for system libraries is Berkeley DB 2, then NDBM, then GDBM and then SDBM. The first library found will be the - library dbmmanage will attempt to use for all DBM file + library dbmmanage will attempt to use for all DBM file transactions. This ordering is slightly different than the standard @AnyDBM::ISA ordering in Perl, as well as the ordering used by the simple dbmopen() call in Perl, so if you use any other diff --git a/docs/manual/programs/htcacheclean.xml b/docs/manual/programs/htcacheclean.xml index e1e51bcb00..2653fc65d8 100644 --- a/docs/manual/programs/htcacheclean.xml +++ b/docs/manual/programs/htcacheclean.xml @@ -26,7 +26,7 @@ htcacheclean - Clean up the disk cache

-

htcacheclean is used to keep the size of +

htcacheclean is used to keep the size of mod_cache_disk's storage within a given size limit, or limit on inodes in use. This tool can run either manually or in daemon mode. When running in daemon mode, it sleeps in the background and checks the cache @@ -104,7 +104,7 @@

-n
Be nice. This causes slower processing in favour of other - processes. htcacheclean will sleep from time to time + processes. htcacheclean will sleep from time to time so that (a) the disk IO will be delayed and (b) the kernel can schedule other processes in the meantime.
@@ -160,7 +160,7 @@
Deleting a specific URL -

If htcacheclean is passed one or more URLs, each URL will +

If htcacheclean is passed one or more URLs, each URL will be deleted from the cache. If multiple variants of an URL exists, all variants would be deleted.

@@ -177,7 +177,7 @@
Listing URLs in the Cache

By passing the -a or -A options to - htcacheclean, the URLs within the cache will be listed + htcacheclean, the URLs within the cache will be listed as they are found, one URL per line. The -A option dumps the full cache entry after the URL, with fields in the following order:

@@ -202,7 +202,7 @@
Exit Status -

htcacheclean returns a zero status ("true") if all +

htcacheclean returns a zero status ("true") if all operations were successful, 1 otherwise. If an URL is specified, and the URL was cached and successfully removed, 0 is returned, 2 otherwise. If an error diff --git a/docs/manual/programs/htdbm.xml b/docs/manual/programs/htdbm.xml index dcd6ccb7d7..4a679fcbd6 100644 --- a/docs/manual/programs/htdbm.xml +++ b/docs/manual/programs/htdbm.xml @@ -26,7 +26,7 @@ htdbm - Manipulate DBM password databases

-

htdbm is used to manipulate the DBM format files used to +

htdbm is used to manipulate the DBM format files used to store usernames and password for basic authentication of HTTP users via mod_authn_dbm. See the dbmmanage documentation for more information about these DBM files.

@@ -172,7 +172,7 @@ This algorithm is insecure by today's standards.
-p
-
Use plaintext passwords. Though htdbm will support +
Use plaintext passwords. Though htdbm will support creation on all platforms, the httpd daemon will only accept plain text passwords on Windows and Netware.
@@ -222,7 +222,7 @@ SDBM, NDBM, GNU GDBM, and Berkeley/Sleepycat DB 2/3/4. Unfortunately, all these libraries use different file formats, and you must make sure that the file format used by filename is the same format that - htdbm expects to see. htdbm currently has + htdbm expects to see. htdbm currently has no way of determining what type of DBM file it is looking at. If used against the wrong format, will simply return nothing, or may create a different DBM file with a different name, or at worst, it may corrupt @@ -233,9 +233,9 @@
Exit Status -

htdbm returns a zero status ("true") if the username and +

htdbm returns a zero status ("true") if the username and password have been successfully added or updated in the DBM File. - htdbm returns 1 if it encounters some problem + htdbm returns 1 if it encounters some problem accessing files, 2 if there was a syntax problem with the command line, 3 if the password was entered interactively and the verification entry didn't match, 4 if its operation was @@ -255,7 +255,7 @@ is prompted for the password. If executed on a Windows system, the password will be hashed using the modified Apache MD5 algorithm; otherwise, the system's crypt() routine will be used. If the file does not - exist, htdbm will do nothing except return an error.

+ exist, htdbm will do nothing except return an error.

htdbm -c /home/doe/public_html/.htdbm jane @@ -263,7 +263,7 @@

Creates a new file and stores a record in it for user jane. The user is prompted for the password. If the file exists and cannot be - read, or cannot be written, it is not altered and htdbm + read, or cannot be written, it is not altered and htdbm will display a message and return an error status.

@@ -275,7 +275,7 @@

To convert an existing text file htpasswd-generated password file to a dbm file, use awk to - feed each line of that file into htdbm:

+ feed each line of that file into htdbm:

htdbm -cbp passwords.dbm bogus bogus @@ -289,7 +289,7 @@
Security Considerations -

Web password files such as those managed by htdbm should +

Web password files such as those managed by htdbm should not be within the Web server's URI space -- that is, they should not be fetchable with a browser.

@@ -311,11 +311,11 @@
Restrictions

On the Windows platform, passwords hashed with - htdbm are limited to no more than 255 + htdbm are limited to no more than 255 characters in length. Longer passwords will be truncated to 255 characters.

-

The MD5 algorithm used by htdbm is specific to the Apache +

The MD5 algorithm used by htdbm is specific to the Apache software; passwords hashed using it will not be usable with other Web servers.

diff --git a/docs/manual/programs/htdigest.xml b/docs/manual/programs/htdigest.xml index ace28ed9b2..1c29815040 100644 --- a/docs/manual/programs/htdigest.xml +++ b/docs/manual/programs/htdigest.xml @@ -26,10 +26,10 @@ htdigest - manage user files for digest authentication -

htdigest is used to create and update the flat-files used +

htdigest is used to create and update the flat-files used to store usernames, realm and password for digest authentication of HTTP users. Resources available from the Apache HTTP server can be restricted - to just the users listed in the files created by htdigest.

+ to just the users listed in the files created by htdigest.

This manual page only lists the command line arguments. For details of the directives necessary to configure digest authentication in diff --git a/docs/manual/programs/htpasswd.xml b/docs/manual/programs/htpasswd.xml index b52239898c..09a39da17f 100644 --- a/docs/manual/programs/htpasswd.xml +++ b/docs/manual/programs/htpasswd.xml @@ -26,24 +26,24 @@ htpasswd - Manage user files for basic authentication

-

htpasswd is used to create and update the flat-files used to +

htpasswd is used to create and update the flat-files used to store usernames and password for basic authentication of HTTP users. If - htpasswd cannot access a file, such as not being able to write + htpasswd cannot access a file, such as not being able to write to the output file or not being able to read the file in order to update it, it returns an error status and makes no changes.

Resources available from the Apache HTTP server can be restricted to - just the users listed in the files created by htpasswd. This + just the users listed in the files created by htpasswd. This program can only manage usernames and passwords stored in a flat-file. It can hash and display password information for use in other types of data stores, though. To use a DBM database see dbmmanage or htdbm.

-

htpasswd hashes passwords using either bcrypt, a +

htpasswd hashes passwords using either bcrypt, a version of MD5 modified for Apache, SHA-1, or the system's crypt() routine. SHA-2-based hashes (SHA-256 and SHA-512) are supported for crypt(). Files managed by - htpasswd may contain a mixture of different encoding + htpasswd may contain a mixture of different encoding types of passwords; some user records may have bcrypt or MD5-hashed passwords while others in the same file may have passwords hashed with crypt().

@@ -180,7 +180,7 @@ distribution. today's standards.
-p
-
Use plaintext passwords. Though htpasswd will support +
Use plaintext passwords. Though htpasswd will support creation on all platforms, the httpd daemon will only accept plain text passwords on Windows and Netware.
@@ -210,9 +210,9 @@ distribution.
Exit Status -

htpasswd returns a zero status ("true") if the username and +

htpasswd returns a zero status ("true") if the username and password have been successfully added or updated in the - passwdfile. htpasswd returns 1 if it + passwdfile. htpasswd returns 1 if it encounters some problem accessing files, 2 if there was a syntax problem with the command line, 3 if the password was entered interactively and the verification entry didn't match, @@ -231,7 +231,7 @@ distribution.

Adds or modifies the password for user jsmith. The user is prompted for the password. The password will be hashed using the modified Apache MD5 algorithm. If the file does not exist, - htpasswd will do nothing except return an error.

+ htpasswd will do nothing except return an error.

htpasswd -c /home/doe/public_html/.htpasswd jane @@ -239,7 +239,7 @@ distribution.

Creates a new file and stores a record in it for user jane. The user is prompted for the password. If the file exists and cannot be - read, or cannot be written, it is not altered and htpasswd + read, or cannot be written, it is not altered and htpasswd will display a message and return an error status.

@@ -252,7 +252,7 @@ distribution.
Security Considerations -

Web password files such as those managed by htpasswd should +

Web password files such as those managed by htpasswd should not be within the Web server's URI space -- that is, they should not be fetchable with a browser.

@@ -284,11 +284,11 @@ distribution.
Restrictions

On the Windows platform, passwords hashed with - htpasswd are limited to no more than 255 + htpasswd are limited to no more than 255 characters in length. Longer passwords will be truncated to 255 characters.

-

The MD5 algorithm used by htpasswd is specific to the Apache +

The MD5 algorithm used by htpasswd is specific to the Apache software; passwords hashed using it will not be usable with other Web servers.

diff --git a/docs/manual/programs/httpd.xml b/docs/manual/programs/httpd.xml index 8ad4a278f6..77d93c0134 100644 --- a/docs/manual/programs/httpd.xml +++ b/docs/manual/programs/httpd.xml @@ -26,12 +26,12 @@ httpd - Apache Hypertext Transfer Protocol Server -

httpd is the Apache HyperText Transfer Protocol +

httpd is the Apache HyperText Transfer Protocol (HTTP) server program. It is designed to be run as a standalone daemon process. When used like this it will create a pool of child processes or threads to handle requests.

-

In general, httpd should not be invoked directly, +

In general, httpd should not be invoked directly, but rather should be invoked via apachectl on Unix-based systems or as a service on Windows NT, @@ -88,7 +88,7 @@ module="core">ServerRoot. The default is

-k start|restart|graceful|stop|graceful-stop
-
Signals httpd to start, restart, or stop. See Signals httpd to start, restart, or stop. See Stopping Apache httpd for more information.
-C directive
@@ -161,11 +161,11 @@ DUMP_... arguments to print information about the configuration,
-v
-
Print the version of httpd, and then exit.
+
Print the version of httpd, and then exit.
-V
-
Print the version and build parameters of httpd, and +
Print the version and build parameters of httpd, and then exit.
-X
diff --git a/docs/manual/programs/httxt2dbm.xml b/docs/manual/programs/httxt2dbm.xml index 3e90bed3f6..33b232206e 100644 --- a/docs/manual/programs/httxt2dbm.xml +++ b/docs/manual/programs/httxt2dbm.xml @@ -26,7 +26,7 @@ httxt2dbm - Generate dbm files for use with RewriteMap -

httxt2dbm is used to generate dbm files from text input, for +

httxt2dbm is used to generate dbm files from text input, for use in RewriteMap with the dbm map type.

diff --git a/docs/manual/programs/logresolve.xml b/docs/manual/programs/logresolve.xml index 867f91ce64..c4f2d48afa 100644 --- a/docs/manual/programs/logresolve.xml +++ b/docs/manual/programs/logresolve.xml @@ -27,7 +27,7 @@ log files -

logresolve is a post-processing program to +

logresolve is a post-processing program to resolve IP-addresses in Apache's access logfiles. To minimize impact on your nameserver, logresolve has its very own internal hash-table cache. This means that each IP number will only be @@ -56,7 +56,7 @@

-c
-
This causes logresolve to apply some DNS checks: +
This causes logresolve to apply some DNS checks: after finding the hostname from the IP address, it looks up the IP addresses for the hostname and checks that one of these matches the original address.
diff --git a/docs/manual/programs/rotatelogs.xml b/docs/manual/programs/rotatelogs.xml index ed3d9aa908..2d55095a04 100644 --- a/docs/manual/programs/rotatelogs.xml +++ b/docs/manual/programs/rotatelogs.xml @@ -26,7 +26,7 @@ rotatelogs - Piped logging program to rotate Apache logs -

rotatelogs is a simple program for use in +

rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature. It supports rotation based on a time interval or maximum size of the log.

 @@ -64,20 +64,20 @@ to the specified link name. This can be used to watch the log continuously across rotations using a command like tail -F linkname.

If the linkname is not an absolute -path, it is relative to rotatelogs' working directory, +path, it is relative to rotatelogs' working directory, which is the ServerRoot when -rotatelogs is run by the server. +rotatelogs is run by the server.

-p program
-

If given, rotatelogs will execute the specified +

If given, rotatelogs will execute the specified program every time a new log file is opened. The filename of the newly opened file is passed as the first argument to the program. If executing after a rotation, the old log file is passed as the second argument.

-

rotatelogs does not wait for the specified +

rotatelogs does not wait for the specified program to terminate before continuing to operate, and will not log any error code returned on termination.

The spawned program uses the @@ -91,7 +91,7 @@ across the rotation.

-f
Causes the logfile to be opened immediately, as soon as -rotatelogs starts, instead of waiting for the +rotatelogs starts, instead of waiting for the first logfile entry to be read (for non-busy sites, there may be a substantial delay between when the server is started and when the first request is handled, meaning that the @@ -165,9 +165,9 @@ megabytes, but 5 megabytes was reached twice in the same day, the same log file name would be produced and log rotation would keep writing to the same file.

If the logfile is not an absolute -path, it is relative to rotatelogs' working directory, +path, it is relative to rotatelogs' working directory, which is the ServerRoot when -rotatelogs is run by the server. +rotatelogs is run by the server.

diff --git a/docs/manual/programs/suexec.xml b/docs/manual/programs/suexec.xml index 7ddf54e545..7f8bd07a0c 100644 --- a/docs/manual/programs/suexec.xml +++ b/docs/manual/programs/suexec.xml @@ -26,10 +26,10 @@ suexec - Switch user before executing external programs -

suexec is used by the Apache HTTP Server to switch +

suexec is used by the Apache HTTP Server to switch to another user before executing CGI programs. In order to achieve this, it must run as root. Since the HTTP daemon normally doesn't - run as root, the suexec executable needs the + run as root, the suexec executable needs the setuid bit set and must be owned by root. It should never be writable for any other person than root.

@@ -49,7 +49,7 @@
-V
If you are root, this option displays the compile options of -suexec. For security reasons all configuration options are +suexec. For security reasons all configuration options are changeable only at compile time.