From: octo <octo>
Date: Mon, 1 May 2006 18:44:07 +0000 (+0000)
Subject: Added manpage `ping_send(3)'
X-Git-Tag: liboping-0.1.0~10
X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=d1ca96131f1f217dcb9f7e9cbff764bec4db1615;p=collectd.git

Added manpage `ping_send(3)'
Added manpage `ping_host_add(3)'
Added both manpages to the build system.
---

diff --git a/src/mans/Makefile.am b/src/mans/Makefile.am
index 93db2bd4..79cbcd0f 100644
--- a/src/mans/Makefile.am
+++ b/src/mans/Makefile.am
@@ -1,8 +1,10 @@
-man_MANS = liboping.3 ping_construct.3 ping_setopt.3
+man_MANS = liboping.3 ping_construct.3 ping_setopt.3 ping_host_add.3 ping_send.3
 
 liboping_3_SOURCES = liboping.pod
 ping_construct_3_SOURCES = ping_construct.pod
 ping_setopt_3_SOURCES = ping_setopt.pod
+ping_host_add_3_SOURCES = ping_host_add.pod
+ping_send_3_SOURCES = ping_send.pod
 
 .pod.1:
 	pod2man --release=$(VERSION) --center=$(PACKAGE) $< >$@
diff --git a/src/mans/ping_host_add.pod b/src/mans/ping_host_add.pod
new file mode 100644
index 00000000..fe52cf85
--- /dev/null
+++ b/src/mans/ping_host_add.pod
@@ -0,0 +1,48 @@
+=head1 NAME
+
+ping_host_add - Add a host to a liboping object
+
+=head1 SYNOPSIS
+
+  #include <oping.h>
+
+  int ping_host_add    (pingobj_t *obj, const char *host);
+  int ping_host_remove (pingobj_t *obj, const char *host);
+
+=head1 DESCRIPTION
+
+The B<ping_host_add> method tries to resolve the I<host> argument, open a
+socket and associate everything with the liboping object I<obj>.
+
+The I<obj> argument is a pointer to an liboping object, as returned by
+ping_construct(3).
+
+The I<host> parameter is a '\0' terminated string which is interpreted as a
+hostname or an IP address. Depending on the address family setting, set with
+ping_setopt(3), the hostname is resolved to an IPv4 or IPv6 address.
+
+The B<ping_host_remove> method looks for I<host> within I<obj> and remove it if
+found. It will close the socket and deallocate the memory, too.
+
+=head1 RETURN VALUE
+
+If B<ping_host_add> succeeds it returns zero. If an error occurs a value less
+than zero is returned and the last error is saved internally. You can receive
+the error message using ping_get_error(3).
+
+B<ping_host_remove> returns zero upon success and less than zero if it failed.
+Currently the only reason for failure is that the host isn't found, but this is
+subject to change. Use ping_get_error(3) to receive the error message.
+
+=head1 SEE ALSO
+
+ping_construct(3),
+ping_setopt(3),
+ping_get_error(3)
+
+=head1 AUTHOR
+
+liboping is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
+It's homepage can be found at L<http://verplant.org/liboping/>.
+
+(c) 2005, 2006 by Florian octo Forster.
diff --git a/src/mans/ping_send.pod b/src/mans/ping_send.pod
new file mode 100644
index 00000000..cb7cbc01
--- /dev/null
+++ b/src/mans/ping_send.pod
@@ -0,0 +1,41 @@
+=head1 NAME
+
+ping_send - Send ICMP echo requests to all associated hosts and wait for ICMP echo responses to arrive
+
+=head1 SYNOPSIS
+
+  #include <oping.h>
+
+  int ping_send (pingobj_t *obj);
+
+=head1 DESCRIPTION
+
+The B<ping_send> method is the actual workhorse of this library. It crafts ICMP
+packets for the hosts associated with I<obj> and sends them via the
+corresponding sockets. It then waits for echo responses and receives them,
+writing latency information for each host. The method returns after all echo
+replies have been read or the timeout (set with ping_setopt(3)) is reached.
+
+After this function returns you will most likely iterate over all hosts using
+ping_iterator_get(3) and ping_iterator_next (described in the same manpage) and
+call ping_iterator_get_info(3) on each host.
+
+=head1 RETURN VALUE
+
+B<ping_send> returns the value of echo replies received or a value less than
+zero if an error occured. Use ping_get_error(3) to receive an error message.
+
+=head1 SEE ALSO
+
+ping_construct(3),
+ping_setopt(3),
+ping_iterator_get(3),
+ping_iterator_get_info(3),
+ping_get_error(3)
+
+=head1 AUTHOR
+
+liboping is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
+It's homepage can be found at L<http://verplant.org/liboping/>.
+
+(c) 2005, 2006 by Florian octo Forster.
diff --git a/src/mans/ping_setopt.pod b/src/mans/ping_setopt.pod
index c4f5eeb2..0346f8ba 100644
--- a/src/mans/ping_setopt.pod
+++ b/src/mans/ping_setopt.pod
@@ -36,8 +36,9 @@ values are 1 through 255. Default is B<PING_DEF_TTL>.
 =item B<PING_OPT_AF>
 
 The address family to use. The memory pointed to by I<val> is interpreted as an
-integer and must be either B<AF_UNSPEC>, B<AF_INET>, or B<AF_INET6>. Default is
-B<PING_DEF_AF>.
+integer and must be either B<AF_UNSPEC>, B<AF_INET>, or B<AF_INET6>. This
+option only effects hosts that are being added B<after> this option has been
+set. Default is B<PING_DEF_AF>.
 
 =back