Add man page for lsdistcc.

git-svn-id: http://distcc.googlecode.com/svn/trunk@769 01de4be4-8c4a-0410-9132-4925637da917

2 files changed, 159 insertions, 2 deletions

diff --git a/Makefile.in b/Makefile.in
index df70d08..38a753d 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -375,9 +375,9 @@ default_dir = packaging/RedHat/default
 default_files = $(default_dir)/distcc
 
 man1_MEN = man/distcc.1 man/distccd.1 man/distccmon-text.1 \
-           man/pump.1 man/include_server.1
+           man/lsdistcc.1 man/pump.1 man/include_server.1
 man_HTML = man/distcc_1.html man/distccd_1.html man/distccmon_text_1.html \
-	   man/pump_1.html man/include_server_1.html
+           man/lsdistcc_1.html man/pump_1.html man/include_server_1.html
 MEN = $(man1_MEN)
 
 gnome_data = gnome/distccmon-gnome-icon.png	\
@@ -665,6 +665,9 @@ man/distccd_1.html: man/distccd.1
 man/distccmon_text_1.html: man/distccmon-text.1
 	troff2html -man "$(srcdir)"/man/distccmon-text.1 > $@
 
+man/lsdistcc_1.html: man/lsdistcc.1
+	troff2html -man "$(srcdir)"/man/lsdistcc.1 > $@
+
 man/pump_1.html: man/pump.1
 	troff2html -man "$(srcdir)"/man/pump.1 > $@
 
diff --git a/man/lsdistcc.1 b/man/lsdistcc.1
new file mode 100644
index 0000000..992cdef
--- /dev/null
+++ b/man/lsdistcc.1
@@ -0,0 +1,154 @@
+.TH lsdistcc 1 "1 May 2012"
+
+.SH "NAME"
+lsdistcc \- simple distcc server discovery
+
+.SH "SYNOPSIS"
+.B lsdistcc
+[\fIOPTIONS\fR] [\fIFORMAT\fR]
+.PP
+.B lsdistcc
+[\fIOPTIONS\fR]
+.I host1 ...
+
+.SH "DESCRIPTION"
+.B lsdistcc
+autodetects listening distcc servers either by looking in DNS for
+hosts named according to a given
+.IR FORMAT ,
+or by checking the host names given on the command line.
+
+Hosts are considered good servers based solely on whether their name
+fits the format and whether they are listening on the right port (and
+optionally whether they respond when you send them a compile job).
+
+Scans for hosts named according to
+.I FORMAT
+(default is "distcc%d"; see
+.BR printf (3))
+and starting from 1, so hosts such as distcc1, distcc2, and so on.
+Stops after 7 seconds or the first host name that does not resolve.
+Prints the names of all such servers listening on distcc's port.
+
+If a list of host names is given in the command line,
+.B lsdistcc
+will only check those hosts.
+
+.SH "OPTIONS"
+.TP
+.B --help
+Displays summary instructions
+
+.TP
+.B -l
+Output latency in milliseconds after each hostname
+(not including DNS latency)
+
+.TP
+.B -n
+Print IP address rather than name
+
+.TP
+.B -x
+Append ,down to down hosts in host list
+
+.TP
+.BI -t "TIMEOUT"
+Set number of seconds to stop searching after [7]
+
+.TP
+.BI -h "HTIMEOUT"
+Set number of milliseconds before retrying gethostbyname [500]
+
+.TP
+.BI -c "CTIMEOUT"
+Set number of milliseconds before giving up on connect [900]
+(0 to inhibit connect)
+
+.TP
+.BI -k "KTIMEOUT"
+Set number of milliseconds before giving up on compile [1500]
+(0 to inhibit compile)
+
+.TP
+.BI -m "BITS"
+Set number of bits of address that must match first host found [0]
+
+.TP
+.BI -o "OVERLAP"
+Set number of extra DNS requests to send [1]
+
+.TP
+.BI -g "DNSGAP"
+Set number of missing DNS entries to tolerate [0]
+
+.TP
+.BI -r "PORT"
+Port to connect to [3632]
+
+.TP
+.BI -P "PROTOCOL"
+Protocol version to use (1-3) [1]
+
+.TP
+.BI -p "COMPILER"
+Name of compiler to use [none]
+
+.TP
+.B -d
+Append DNS domain name to format
+
+.TP
+.B -v
+Verbose
+
+.SH "EXAMPLES"
+Scan for servers named distcc1, distcc2, ...
+that provide a compiler named gcc-4.6
+and include their latencies in the output:
+
+.RS
+$ lsdistcc \-l \-pgcc-4.6
+.RE
+
+Scan for a compiler named gcc-4.6 on the servers hosta, somehost, hostx, and hosty:
+
+.RS
+$ lsdistcc \-pgcc-4.6 hosta somehost hostx hosty
+.RE
+
+To use the program in a build script, add the lines:
+
+.RS
+DISTCC_HOSTS=`lsdistcc`
+.br
+export DISTCC_HOSTS
+.RE
+
+before the line that invokes make.
+Or, in a Makefile, add the line:
+
+.RS
+export DISTCC_HOSTS = $(shell lsdistcc)
+.RE
+
+.SH "EXIT STATUS"
+The exit status is 0 if any servers were found, and 1 otherwise.
+
+Uses 'for i=1... sprintf(format, i)' to construct names of servers,
+stops after 7 seconds or at second server that doesn't resolve,
+prints the names of all such servers listening on distcc's port.
+Default format is distcc%d.
+
+.SH "SEE ALSO"
+.BR distcc (1),
+.BR distccd (1),
+.BR printf (3)
+
+.I http://code.google.com/p/distcc/
+
+.SH "AUTHOR"
+.B lsdistcc
+was written by Dan Kegel, Dongmin Zhang, and Manos Renieris.
+
+This manual page was written by Daniel Hartwig for the Debian project.