convert to mdoc;

1 files changed, 319 insertions, 366 deletions

diff --git a/usr.sbin/httpd/src/support/apxs.8 b/usr.sbin/httpd/src/support/apxs.8
index 3791aaece2b..86450c15cf8 100644
--- a/usr.sbin/httpd/src/support/apxs.8
+++ b/usr.sbin/httpd/src/support/apxs.8
@@ -1,4 +1,5 @@
-.TH apxs 8 "April 1998"
+.\"	$OpenBSD: apxs.8,v 1.12 2004/12/07 15:48:57 jmc Exp $
+.\"
 .\" ====================================================================
 .\" The Apache Software License, Version 1.1
 .\"
@@ -56,414 +57,366 @@
 .\" originally written at the National Center for Supercomputing Applications,
 .\" University of Illinois, Urbana-Champaign.
 .\"
-.SH NAME
-apxs \- APache eXtenSion tool
-.SH SYNOPSIS
-.B apxs
-.B \-g
-[
-.BI \-S " variable=value
-]
-.BI \-n " name"
-
-.B apxs
-.B \-q
-[
-.BI \-S " variable=value
-]
-.IR query " ..."
-
-.B apxs
-.B \-c
-[
-.BI \-S " variable=value
-]
-[
-.BI \-o " dsofile"
-]
-[
-.BI \-I " incdir"
-]
-[
-.BI \-D " variable[=value]"
-]
-[
-.BI \-L " libdir"
-]
-[
-.BI \-l " libname"
-]
-[
-.BI \-Wc, "compiler-flags"
-]
-[
-.BI \-Wl, "linker-flags"
-]
-.IR files " ..."
-
-.B apxs
-.B \-i
-[
-.BI \-S " variable=value
-]
-[
-.BI \-n " name"
-]
-[
-.B \-a
-]
-[
-.B \-A
-]
-.IR dsofile " ..."
-
-.B apxs
-.B \-e
-[
-.BI \-S " variable=value
-]
-[
-.BI \-n " name"
-]
-[
-.B \-a
-]
-[
-.B \-A
-]
-.IR dsofile " ..."
-.PP
-.SH DESCRIPTION
-.B 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
-.I files
+.Dd December 7, 2004
+.Dt APXS 8
+.Os
+.Sh NAME
+.Nm apxs
+.Nd APache eXtenSion tool
+.Sh SYNOPSIS
+.Nm
+.Bk -words
+.Fl c
+.Xo
+.Oo Fl D
+.Ar variable Ns Oo = Ns Ar value Oc Oc
+.Xc
+.Op Fl I Ar incdir
+.Op Fl L Ar libdir
+.Op Fl l Ar libname
+.No \ \&\ \& Op Fl o Ar dsofile
+.Xo
+.Oo Fl S
+.Ar variable Ns = Ns Ar value Oc
+.Xc
+.Op Fl Wc , Ns Ar compiler-flags
+.No \ \&\ \& Op Fl Wl , Ns Ar linker-flags
+.Ar file ...
+.Ek
+.Nm
+.Fl e
+.Op Fl Aa
+.Op Fl n Ar name
+.Xo
+.Oo Fl S
+.Ar variable Ns = Ns Ar value Oc
+.Xc
+.Ar dsofile ...
+.Nm
+.Fl g
+.Xo
+.Oo Fl S
+.Ar variable Ns = Ns Ar value Oc
+.Xc
+.Fl n Ar name
+.Nm
+.Fl i
+.Op Fl Aa
+.Op Fl n Ar name
+.Xo
+.Oo Fl S
+.Ar variable Ns = Ns Ar value Oc
+.Xc
+.Ar dsofile ...
+.Nm
+.Fl q
+.Xo
+.Oo Fl S
+.Ar variable Ns = Ns Ar value Oc
+.Xc
+.Ar query ...
+.Sh DESCRIPTION
+.Nm
+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 can then be loaded into
-the Apache server at runtime via the
-.B LoadModule
+.Xr httpd 8
+at runtime via the
+.Ic LoadModule
 directive from
-.BR mod_so.
-
-So to use this extension mechanism, your platform has
-to support the DSO feature and your
-Apache
-.B httpd
+.Ic mod_so .
+So to use this extension mechanism,
+your platform has to support the DSO feature and your
+.Xr httpd 8
 binary has to be built with the
-.B mod_so
+.Ic mod_so
 module.
 The
-.B apxs
+.Nm
 tool automatically complains if this is not the case.
 You can check this yourself by manually running the command
-
-.nf
-  $ httpd -l
-.fi
-
+.Pp
+.Dl $ httpd -l
+.Pp
 The module
-.B mod_so
+.Ic 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, with the help of this
-.B apxs
+If these requirements are fulfilled,
+you can easily extend your Apache server's functionality by
+installing your own modules with the DSO mechanism,
+with the help of the
+.Nm
 tool:
-
-.nf
-  $ apxs -i -a -c mod_foo.c
-  gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
-  ld -Bshareable -o mod_foo.so mod_foo.o
-  cp mod_foo.so /path/to/apache/libexec/mod_foo.so
-  chmod 755 /path/to/apache/libexec/mod_foo.so
-  [activating module `foo' in /path/to/apache/etc/httpd.conf]
-  $ apachectl restart
-  /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
-  [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
-  /path/to/apache/sbin/apachectl restart: httpd started
-  $ _
-.fi
-
+.Bd -literal -offset indent
+$ apxs -i -a -c mod_foo.c
+gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
+ld -Bshareable -o mod_foo.so mod_foo.o
+cp mod_foo.so /path/to/apache/libexec/mod_foo.so
+chmod 755 /path/to/apache/libexec/mod_foo.so
+[activating module `foo' in /path/to/apache/etc/httpd.conf]
+$ apachectl restart
+/path/to/apache/sbin/apachectl restart: httpd not running, trying to start
+[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
+/path/to/apache/sbin/apachectl restart: httpd started
+$ _
+.Ed
+.Pp
 The argument
-.I files
-can be any C source file (.c), an object file (.o) or
-even a library archive (.a). The
-.B apxs
+.Ar file
+can be any C source file (.c),
+an object file (.o),
+or even a library archive (.a).
+The
+.Nm
 tool automatically recognizes these extensions and automatically uses the C
-source files for compilation, whereas it just uses 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 DSO. For instance, with GCC you just have to always use
-.BR -fpic .
+source files for compilation,
+whereas it just uses 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 DSO.
+For instance, with GCC you just have to always use
+.Fl fpic .
 For other
 C compilers, please consult their manual
 pages or watch for the flags
-.B apxs
+.Nm
 uses to compile the object files.
-
-For more details about DSO support in Apache, first read the background
-information about DSO in htdocs/manual/dso.html, then read the documentation
-of
-.BR mod_so .
-
-.PP
-.SH OPTIONS
-Common options:
-.TP 12
-.BI \-n " name"
-This explicitly sets the module name for the
-.B \-i
-(install)
-and
-.B \-g
-(template generation) option. Use this to explicitly specify the module name.
-For option
-.B \-g
-this is required, for option
-.B \-i
-the
-.B apxs
-tool tries to determine the name from the source or (as a fallback) at least
-by guessing it from the filename.
-.PP
-Query options:
-.TP 12
-.B \-q 
-Performs a query for 
-.BR apxs 's
-knowledge about certain settings. The
-.I query
-parameters can be one or more of the following variable names:
-.nf
-  CC              TARGET
-  CFLAGS          SBINDIR    
-  CFLAGS_SHLIB    INCLUDEDIR 
-  LD_SHLIB        LIBEXECDIR 
-  LDFLAGS_SHLIB   SYSCONFDIR 
-  LIBS_SHLIB      PREFIX
-.fi
-Use this for manually determining settings. For instance use
-.nf
-  INC=-I`apxs -q INCLUDEDIR`
-.fi
-inside your own Makefiles if you need manual access
-to Apache's C header files.
-.PP
-Configuration options:
-.TP 12
-.BI \-S " variable=value"
-This option changes the 
-.B apxs 
-settings described above.
-.PP
-Template Generation options:
-.TP 12
-.B \-g
-This generates a subdirectory
-.I name
-(see option
-.BR \-n ")"
-and two files: A sample module source file named
-.BI mod_ name.c
-which can be used as a template for creating your own modules or
-as a quick start for playing with the 
-.B apxs
-mechanism.
-And a corresponding
-.B Makefile
-for even easier building and installing of this module.
-.PP
-DSO compilation options:
-.TP 12
-.B \-c
-This indicates the compilation operation. It first compiles the C source
-files (.c) of
-.I files
+.Pp
+For more details about DSO support in Apache,
+first read the background information about DSO in
+.Pa htdocs/manual/dso.html ,
+then read the documentation of
+.Ic mod_so .
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl A
+Same as the
+.Fl a
+option but the created
+.Ic LoadModule
+directive is prefixed with a hash sign (#),
+i.e. the module is just prepared for later activation but initially disabled.
+.It Fl a
+This activates the module by automatically adding a corresponding
+.Ic LoadModule
+line to Apache's httpd.conf configuration file,
+or by enabling it if it already exists.
+.It Fl c
+This indicates the compilation operation.
+It first compiles the C source files (.c) of
+.Ar file ...\&
 into corresponding object files (.o) and then builds a DSO in
-.I dsofile
-by linking these object files plus the remaining
-object files (.o and .a) of
-.I files
+.Ar dsofile
+by linking these object files plus the remaining object files (.o and .a) of
+.Ar file ...
 If no
-.B \-o
-option is specified
+.Fl o
+option is specified,
 the output file is guessed from the first filename in
-.I files
+.Ar file ...\&
 and thus usually defaults to
-.BI mod_ name.so
-.TP 12
-.BI \-o " dsofile"
-Explicitly specifies the filename of the created DSO file. If
-not specified and the name cannot be guessed from the
-.I files
-list, the fallback name
-.B mod_unknown.so
-is used.
-.TP 12
-.BI \-D " variable[=value]"
+.Ar mod_name.so
+.It Xo
+.Fl D
+.Ar variable Ns Op = Ns Ar value
+.Xc
 This option is directly passed through to the compilation command(s).
 Use this to add your own defines to the build process.
-.TP 12
-.BI \-I " incdir"
+.It Fl e
+This indicates the editing operation, which can be used with the
+.Fl a
+and
+.Fl A
+options similarly to the
+.Fl i
+operation to edit Apache's httpd.conf configuration file,
+without attempting to install the module.
+.It Fl g
+This generates a subdirectory
+.Ar name
+(see the
+.Fl n
+option)
+and two files:
+a sample module source file named
+.Pa mod_name.c
+which can be used as a template for creating your own modules or
+as a quick start for playing with the
+.Nm
+mechanism,
+and a corresponding
+.Pa Makefile
+for even easier building and installing of this module.
+.It Fl I Ar incdir
 This option is directly passed through to the compilation command(s).
 Use this to add your own include directories to search to the build process.
-.TP 12
-.BI \-L " libdir"
+.It Fl i
+This indicates the installation operation and installs one or more
+DSOs into the server's
+.Ar libexec
+directory.
+.It Fl L Ar libdir
 This option is directly passed through to the linker command.
 Use this to add your own library directories to search to the build process.
-.TP 12
-.BI \-l " libname"
+.It Fl l Ar libname
 This option is directly passed through to the linker command.
 Use this to add your own libraries to search to the build process.
-.TP 12
-.BI \-Wc, "compiler-flags"
-This option passes 
-.I compiler-flags
+.It Fl n Ar name
+This explicitly sets the module name for the
+.Fl i
+(install)
+and
+.Fl g
+(template generation) option.
+Use this to explicitly specify the module name.
+For option
+.Fl g
+this is required;
+for option
+.Fl i ,
+.Nm
+tries to determine the name from the source or (as a fallback) at least
+by guessing it from the filename.
+.It Fl o Ar dsofile
+Explicitly specifies the filename of the created DSO file.
+If not specified and the name cannot be guessed from the
+.Ar file ...\&
+list,
+the fallback name
+.Ar mod_unknown.so
+is used.
+.It Fl q
+Performs a query for
+.Nm apxs Ns 's
+knowledge about certain settings.
+The
+.Ar query
+parameters can be one or more of the following variable names:
+.Bd -literal -offset indent
+CC              TARGET
+CFLAGS          SBINDIR
+CFLAGS_SHLIB    INCLUDEDIR
+LD_SHLIB        LIBEXECDIR
+LDFLAGS_SHLIB   SYSCONFDIR
+LIBS_SHLIB      PREFIX
+.Ed
+.Pp
+Use this for manually determining settings.
+For instance,
+use the following inside your own Makefiles if you need manual access
+to Apache's C header files:
+.Pp
+.Dl INC=-I`apxs -q INCLUDEDIR`
+.It Fl S Ar variable Ns = Ns Ar value
+This option changes the
+.Nm
+settings described above.
+.It Fl Wc , Ns Ar compiler-flags
+This option passes
+.Ar compiler-flags
 as additional flags to the compiler command.
 Use this to add local compiler-specific options.
-.TP 12
-.BI \-Wl, "linker-flags"
-This option passes 
-.I linker-flags
+.It Fl Wl , Ns Ar linker-flags
+This option passes
+.Ar linker-flags
 as additional flags to the linker command.
 Use this to add local linker-specific options.
-.PP
-DSO installation and configuration options:
-.TP 12
-.B \-i
-This indicates the installation operation and installs one or more
-DSOs into the
-server's
-.I libexec
-directory.
-.TP 12
-.B \-a
-This activates the module by automatically adding a corresponding
-.B LoadModule
-line to Apache's
-.B httpd.conf
-configuration file, or by enabling it if it already exists.
-.TP 12
-.B \-A
-Same as option
-.B \-a
-but the created 
-.B LoadModule
-directive is prefixed with a hash sign (#), i.e. the module is
-just prepared for later activation but initially disabled. 
-.TP 12
-.B \-e
-This indicates the editing operation, which can be used with the
-.B \-a
-and
-.B \-A
-options similarly to the
-.B \-i
-operation to edit Apache's
-.B httpd.conf
-configuration file, without attempting to install the module.
-.PD
-.SH EXAMPLES
-Assume you have an Apache module named mod_foo.c available which should extend
-Apache's server functionality. To accomplish this you first have to compile
+.El
+.Sh EXAMPLES
+Assume you have an Apache module named
+.Dq mod_foo.c
+available which should extend Apache's server functionality.
+To accomplish this you first have to compile
 the C source into a DSO suitable for loading into the Apache server
 under runtime via the following command:
-
-.nf
-  $ apxs -c mod_foo.c
-  gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
-  ld -Bshareable -o mod_foo.so mod_foo.o
-  $ _
-.fi
-
+.Bd -literal -offset indent
+$ apxs -c mod_foo.c
+gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
+ld -Bshareable -o mod_foo.so mod_foo.o
+$ _
+.Ed
+.Pp
 Then you have to update the Apache configuration by making sure a
-.B LoadModule
-directive is present to load this DSO. To simplify this
-step
-.B apxs
+.Ic LoadModule
+directive is present to load this DSO.
+To simplify this step,
+.Nm
 provides an automatic way to install the DSO in the
-"libexec" directory and updating the
-.B httpd.conf
-file accordingly. This can be achieved by running:
-
-.nf
-  $ apxs -i -a mod_foo.c
-  cp mod_foo.so /path/to/apache/libexec/mod_foo.so
-  chmod 755 /path/to/apache/libexec/mod_foo.so
-  [activating module `foo' in /path/to/apache/etc/httpd.conf]
-  $ _
-.fi
-
+.Dq libexec
+directory and updating the httpd.conf file accordingly.
+This can be achieved by running:
+.Bd -literal -offset indent
+$ apxs -i -a mod_foo.c
+cp mod_foo.so /path/to/apache/libexec/mod_foo.so
+chmod 755 /path/to/apache/libexec/mod_foo.so
+[activating module `foo' in /path/to/apache/etc/httpd.conf]
+$ _
+.Ed
+.Pp
 This way a line named
-
-.nf
-  LoadModule foo_module libexec/mod_foo.so
-.fi
-
+.Pp
+.Dl LoadModule foo_module libexec/mod_foo.so
+.Pp
 is added to the configuration file, if still not present.
 If you want this operation to be disabled, use the
-.B \-A
+.Fl A
 option, i.e.
-
-.nf
-  $ apxs -i -A mod_foo.c
-.fi
-
-For a quick test of the 
-.B apxs
+.Pp
+.Dl $ apxs -i -A mod_foo.c
+.Pp
+For a quick test of the
+.Nm
 mechanism you can create a sample Apache module
-template plus a corresponding 
-.B Makefile 
+template plus a corresponding
+.Ar Makefile
 via:
-
-.nf
-  $ apxs -g -n foo
-  Creating [DIR]  foo
-  Creating [FILE] foo/Makefile
-  Creating [FILE] foo/mod_foo.c
-  $ _
-.fi
-
+.Bd -literal -offset indent
+$ apxs -g -n foo
+Creating [DIR]  foo
+Creating [FILE] foo/Makefile
+Creating [FILE] foo/mod_foo.c
+$ _
+.Ed
+.Pp
 Then you can immediately compile this sample module into a DSO and
 load it into the Apache server:
-
-.nf
-  $ cd foo
-  $ make all reload
-  apxs -c mod_foo.c
-  gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
-  ld -Bshareable -o mod_foo.so mod_foo.o
-  apxs -i -a -n "foo" mod_foo.so
-  cp mod_foo.so /path/to/apache/libexec/mod_foo.so
-  chmod 755 /path/to/apache/libexec/mod_foo.so
-  [activating module `foo' in /path/to/apache/etc/httpd.conf]
-  apachectl restart
-  /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
-  [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
-  /path/to/apache/sbin/apachectl restart: httpd started
-  $ _
-.fi
-
+.Bd -literal -offset indent
+$ cd foo
+$ make all reload
+apxs -c mod_foo.c
+gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
+ld -Bshareable -o mod_foo.so mod_foo.o
+apxs -i -a -n "foo" mod_foo.so
+cp mod_foo.so /path/to/apache/libexec/mod_foo.so
+chmod 755 /path/to/apache/libexec/mod_foo.so
+[activating module `foo' in /path/to/apache/etc/httpd.conf]
+apachectl restart
+/path/to/apache/sbin/apachectl restart: httpd not running, trying to start
+[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
+/path/to/apache/sbin/apachectl restart: httpd started
+$ _
+.Ed
+.Pp
 You can even use
-.B apxs
+.Nm
 to compile complex modules outside the Apache source tree, like PHP3, because
-.B apxs 
-automatically recognizes C source files and object files.  
-
-.nf
-  $ cd php3
-  $ ./configure --with-shared-apache=../apache-1.3
-  $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
-  gcc -fpic -DSHARED_MODULE -I/tmp/apache/include  -c mod_php3.c
-  ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
-  $ _
-.fi
-
-Only C source files are compiled, while remaining object files are used for the
-linking phase.
-
-.PD
-.SH SEE ALSO
-.BR apachectl(1),
-.BR httpd(8).
-.
+.Nm
+automatically recognizes C source files and object files.
+.Bd -literal -offset indent
+$ cd php3
+$ ./configure --with-shared-apache=../apache-1.3
+$ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
+gcc -fpic -DSHARED_MODULE -I/tmp/apache/include  -c mod_php3.c
+ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
+$ _
+.Ed
+.Pp
+Only C source files are compiled,
+while remaining object files are used for the linking phase.
+.Sh SEE ALSO
+.Xr apachectl 1 ,
+.Xr httpd 8