1 files changed, 154 insertions, 0 deletions
diff --git a/man/man3/pmdiscoverservices.3 b/man/man3/pmdiscoverservices.3
new file mode 100644
index 0000000..cfe7a77
--- /dev/null
+++ b/man/man3/pmdiscoverservices.3
@@ -0,0 +1,154 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2014 Red Hat.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 2 of the License, or (at your
+.\" option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+.\" for more details.
+.\" 
+.\"
+.TH PMDISCOVERSERVICES 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmDiscoverServices\f1 \- discover PCP services on the network
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.sp
+.nf
+int pmDiscoverServices(const char *\fIservice\fP, const char *\fImechanism\fP, const char *\fIglobalOptions\fP, char ***\fIurls\fP);
+.fi
+.sp
+cc ... \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+Given a PCP service name, as identified by
+.IR service ,
+and using the type of discovery optionally specified in
+.IR mechanism ,
+.B pmDiscoverServices
+returns, via
+.IR urls ,
+a list of URLs representing the services discovered on the network.
+.PP 
+.I service
+specifies the PCP service to be discovered. Currently supported services are
+.B PM_SERVER_SERVICE_SPEC,
+.B PM_PROXY_SERVICE_SPEC
+and
+.B PM_WEBD_SERVICE_SPEC,
+which search for
+.BR pmcd (1),
+.BR pmproxy (1),
+and
+.BR pmwebd (1),
+servers respectively.
+.PP 
+.IR mechanism
+specifies the style of discovery to be used.
+.PP
+The currently supported mechanisms are:
+.TP
+.B avahi
+This searches for services which are broadcasting using mDNS via
+.BR avahi-daemon (8).
+An optional suffix \fB",timeout=NNNN"\fP may be added
+to specify the discovery timeout, in floating-point multiples of one
+second.  The default timeout is 0.5 seconds, which may be overridden
+by the \fBAVAHI_DISCOVERY_TIMEOUT\fP environment variable, also
+specified in floating-point multiples of one second.
+.TP
+.B probe=<net-address>/<mask-bits>
+Actively probes the given subnet for the requested PCP service(s).
+<net-address> is an inet or ipv6
+network address and <mask-bits> is the number of bits used to define the
+subnet. For example, 192.168.1.0/24 defines an 8 bit subnet consisting of the
+addresses 192.168.1.0 through 192.168.1.255.
+An optional suffix \fB",maxThreads=N"\fP may be added to limit the number of
+threads used while probing. The default is no fixed limit, which is to say that
+the process' rlimits for the number of threads and open file descriptors
+will be respected.
+.PP
+.IR mechanism
+may also be NULL, which means to use all available discovery mechanisms.
+.PP 
+.I globalOptions
+is a string containing options to be applied to the entire
+discovery process. Currently, the only supported option is \fB"resolve"\fP.
+Normally the
+results are reported as a list of urls containing the network addresses
+of the discovered servers. The \fB"resolve"\fP option requests
+that an attempt be made to resolve these addresses. If successful, the host
+name will be reported instead. If unsuccessful, then the address will be
+reported.
+.PP 
+.B pmDiscoverServices
+will return the number of services discovered, else a value
+less than zero for an error.
+The value zero indicates that no services were discovered.
+.PP
+The resulting list of pointers,
+.IR urls ,
+.B and
+the values
+(the URLs) that the pointers reference will have been
+allocated by
+.B pmDiscoverServices
+with a single call to
+.BR malloc (3C),
+and it is the
+responsibility of the
+.B pmDiscoverServices
+caller to
+.BR free (\c
+.IR urls )
+to release the space
+when it is no longer required.
+.PP
+When an error occurs, or no services are discovered,
+.I urls
+is undefined (no space will have been
+allocated, and so calling
+.BR free (3C)
+is a singularly bad idea).
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+Values for these variables may be obtained programmatically
+using the
+.BR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR PMAPI (3),
+.BR pmcd (1),
+.BR pmproxy (1),
+.BR pmwebd (1),
+.BR pmfind (1),
+.BR pmGetConfig (3),
+.BR pcp.conf (5),
+.BR pcp.env (5)
+and
+.BR avahi-daemon (8).
+.SH DIAGNOSTICS
+.IP \f3EOPNOTSUPP\f1
+The specified \fImechanism\fP is not supported.