Added `liboping.pod' - a first manpage draft.

diff --git a/src/liboping.pod b/src/liboping.pod
new file mode 100644 (file)
index 0000000..8e7ea22
--- /dev/null
+++ b/src/liboping.pod
@@ -0,0 +1,87 @@
+=head1 NAME
+
+liboping - Library to send ICMPv4/ICMPv6 echo packets to multiple hosts
+
+=head1 DESCRIPTION
+
+This is an overview of liboping, a C library to send ICMP ECHO_REQUEST packets
+to remote hosts and measure the time it takes for replies to be received. This
+method, often simply called "ping", is a common way to measure network latency
+and/or host reachability.
+
+The goals of this library are to provide the above functionality in a platform
+and protocol independent manner. The interface is simple, object oriented and
+(hopefully) ANSI-C compliant.
+
+=head1 GENERAL USAGE
+
+There are two main types that are used by applications. Both are "opaque
+types", meaning they are structures that are B<not> completely defined in the
+header file, so you cannot access the structures' members. You don't need to,
+don't do it. These structures are object to change without notice.
+
+=over 4
+
+=item C<pingobj_t>
+
+A ping-object. You can set specific options for this object, add and remove
+hosts to/from it and send ICMP packets to all associated hosts. This is often
+called a "handle".
+
+=item C<pingobj_iter_t>
+
+An iterator over the hosts associated with a C<pingobj_t> object. This iterator
+can be used to query more information about a host, for example the hostname,
+the measured latency or the current ICMP sequence.
+
+=back
+
+Upon startup you usually create one or more C<pingobj_t> objects and add hosts
+to it using the C<ping_host_add> method (see below). You periodically send
+"echo requests" using the C<ping_send> method, iterate over all hosts using
+C<ping_iterator_get> and C<ping_iterator_next>. For each host you call
+C<ping_iterator_get_info> to read the current latency and do something with it.
+
+If an error occurs you can use C<ping_get_error> so get information on what
+failed.
+
+=head1 LINKING WITH LIBOPING
+
+Depending on you platform you don't need any extra libraries (e.g. GNU/Linux)
+or C<libsocket> (using C<-lsocket>) if the C<socket> function is not in the
+C-library. The latter is the case for the Solaris operating system.
+
+=head1 SYMBOL NAMES
+
+All "official" function or method names are prefixed with "ping_". Don't use
+any other functions or methods. Although no such functions should exist.
+
+=head1 THREAD SAFETY
+
+liboping has been designed to be as thread safe a possible. However, this has
+not been tested and may need some additional work. Use at your own risk and
+please report back any problems or success messages. Thank you :)
+
+=head1 SEE ALSO
+
+ping_construct(3),
+ping_setopt(3),
+ping_host_add(3),
+ping_send(3),
+ping_get_error(3),
+ping_iterator_get(3),
+ping_iterator_get_info(3),
+ping_iterator_get_context(3)
+
+=head1 LICENSE
+
+liboping is licensed under the GPLv2. No other version of the license is
+applicable. If you want to link a non-GPL-compliant program with liboping
+contact the author for double-licensing options.
+
+=head1 CONTACT
+
+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.