Added these manpages: ping_get_error(3), ping_iterator_get(3), and ping_iterator_get_...

diff --git a/src/mans/Makefile.am b/src/mans/Makefile.am
index 79cbcd0f91dd85937bc3cf5746171006b958321b..d683366b3a07dd13c251b11e4085de659c7be864 100644 (file)
--- a/src/mans/Makefile.am
+++ b/src/mans/Makefile.am
@@ -1,10 +1,13 @@
-man_MANS = liboping.3 ping_construct.3 ping_setopt.3 ping_host_add.3 ping_send.3
+man_MANS = liboping.3 ping_construct.3 ping_setopt.3 ping_host_add.3 \
+          ping_send.3 ping_get_error.3 ping_iterator_get.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
+ping_get_error_3_SOURCES = ping_get_error.pod
+ping_iterator_get_3_SOURCES = ping_iterator_get.pod
 
 .pod.1:
        pod2man --release=$(VERSION) --center=$(PACKAGE) $< >$@

diff --git a/src/mans/ping_get_error.pod b/src/mans/ping_get_error.pod
new file mode 100644 (file)
index 0000000..f246eed
--- /dev/null
+++ b/src/mans/ping_get_error.pod
@@ -0,0 +1,30 @@
+=head1 NAME
+
+ping_get_error - Return the last error message
+
+=head1 SYNOPSIS
+
+  #include <oping.h>
+
+  const char *ping_get_error (pingobj_t *obj);
+
+=head1 DESCRIPTION
+
+The B<ping_get_error> method returns an error message indicating the last error
+encountered. B<This method is not thread safe whatsoever.>
+
+=head1 RETURN VALUE
+
+A C<const> string representing the last error or an empty string if no error
+was encountered yet.
+
+=head1 SEE ALSO
+
+liboping(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_iterator_get.pod b/src/mans/ping_iterator_get.pod
new file mode 100644 (file)
index 0000000..40b67fb
--- /dev/null
+++ b/src/mans/ping_iterator_get.pod
@@ -0,0 +1,45 @@
+=head1 NAME
+
+ping_iterator_get, ping_iterator_next - Iterate over all hosts of a liboping object
+
+=head1 SYNOPSIS
+
+  #include <oping.h>
+
+  pingobj_iter_t *ping_iterator_get (pingobj_t *obj);
+  pingobj_iter_t *ping_iterator_next (pingobj_iter_t *iter)
+
+=head1 DESCRIPTION
+
+These two functions can be used to iterate over all hosts associated with a
+liboping object. You can use these methods as follows:
+
+  pingobj_iter_t *iter;
+
+  for (iter = ping_iterator_get (obj);
+       iter != NULL;
+       iter = ping_iterator_next (iter))
+  {
+    ...;
+  }
+
+To get usable information from an iterator object (which is also an opaque data
+type, just like the liboping object itself) use ping_iterator_get_info(3) and
+ping_iterator_get_context(3).
+
+=head1 RETURN VALUE
+
+The B<ping_iterator_get> returns an iterator for I<obj> or NULL if no host is
+associated with I<obj>.
+
+The B<ping_iterator_next> returns an iterator for the host following I<iter> or
+NULL if the last host has been reached.
+
+=head1 SEE ALSO
+
+ping_host_add(3),
+ping_iterator_get_info(3),
+ping_iterator_get_context(3),
+liboping(3)
+
+=head1 AUTHOR

diff --git a/src/mans/ping_iterator_get_context.pod b/src/mans/ping_iterator_get_context.pod
new file mode 100644 (file)
index 0000000..5833fc9
--- /dev/null
+++ b/src/mans/ping_iterator_get_context.pod
@@ -0,0 +1,96 @@
+=head1 NAME
+
+ping_iterator_get_info - Constructor for the liboping class
+
+=head1 SYNOPSIS
+
+  #include <oping.h>
+
+  int ping_iterator_get_info (pingobj_iter_t *iter,
+                 int info,
+                 void *buffer,
+                 size_t *buffer_len);
+
+=head1 DESCRIPTION
+
+The B<ping_iterator_get_info> method can be used on an host iterator to return
+various information about the current host.
+
+The I<iter> argument is an iterator as returned by ping_iterator_get(3) or
+ping_iterator_next(3).
+
+The I<info> argument specifies the type of information returned. Use the
+following defines:
+
+=over 4
+
+=item B<PING_INFO_HOSTNAME>
+
+Return the hostname of the host the iterator points to. Since the name is
+looked up using the socket address this may differ from the hostname passed to
+ping_host_add(3). The hostname is actually looked up every time you call this
+method, no cache is involved within liboping.
+
+It is recommended to include C<netdb.h> and allocate B<NI_MAXHOST> bytes of
+buffer.
+
+=item B<PING_INFO_ADDRESS>
+
+Return the address used in ASCII (i.e. human readable) format. The address is
+looked up every time you call this method. 40 bytes should be sufficient for
+the buffer (16 octets in hex format, seven colons and one null byte), but more
+won't hurt.
+
+=item B<PING_INFO_FAMILY>
+
+Returns the address family of the host. The buffer should be ig enough to hold
+an integer. The value is either B<AF_INET> or B<AF_INET6>.
+
+=item B<PING_INFO_LATENCY>
+
+Return the last measured latency or less than zero if the timeout occured
+before a echo response was received. The buffer should be big enough to hold a
+double value.
+
+=item B<PING_INFO_SEQUENCE>
+
+Return the last sequence number sent. This number is increased regardless of
+echo responses being received or not. The buffer should hold an integer.
+
+=item B<PING_INFO_IDENT>
+
+Return the ident that is put into every ICMP packet sent to this host. Per
+convention this usually is the PID of the sending process, but since liboping
+can handle several hosts in parallel it uses a (pseudo-)random number here. The
+buffer should be big enough to hold an integer value.
+
+=back
+
+The I<buffer> argument is a pointer to an appropriately sized area of memory
+where the result of the call will be stored. The I<buffer_len> value is used as
+input and output: When calling B<ping_iterator_get_info> it reports the size of
+the memory region pointed to by I<buffer>. The method will write the number of
+bytes actually written to the memory into I<buffer_len> before returning.
+
+=head1 RETURN VALUE
+
+B<ping_iterator_get_info> returns zero if it succeeds.
+
+B<EINVAL> is returned if the value passed as I<info> is unknown. Both,
+I<buffer> and I<buffer_len>, will be left untouched in this case.
+
+If the requested information didn't fit into I<buffer> then the size that would
+have been needed is written into I<buffer_len>; I<buffer> itself is left
+untouched. The return value is B<ENOMEM> in this case.
+
+=head1 SEE ALSO
+
+ping_iterator_get(3),
+liboping(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.