From 2b8a2308af343471e8184ff265526a6a36153ed0 Mon Sep 17 00:00:00 2001 From: octo Date: Mon, 1 May 2006 19:21:31 +0000 Subject: [PATCH] Added these manpages: ping_get_error(3), ping_iterator_get(3), and ping_iterator_get_info(3) --- src/mans/Makefile.am | 5 +- src/mans/ping_get_error.pod | 30 ++++++++ src/mans/ping_iterator_get.pod | 45 ++++++++++++ src/mans/ping_iterator_get_context.pod | 96 ++++++++++++++++++++++++++ 4 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 src/mans/ping_get_error.pod create mode 100644 src/mans/ping_iterator_get.pod create mode 100644 src/mans/ping_iterator_get_context.pod diff --git a/src/mans/Makefile.am b/src/mans/Makefile.am index 79cbcd0f..d683366b 100644 --- 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 index 00000000..f246eed7 --- /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 + + const char *ping_get_error (pingobj_t *obj); + +=head1 DESCRIPTION + +The B method returns an error message indicating the last error +encountered. B + +=head1 RETURN VALUE + +A C 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 Eocto at verplant.orgE. +It's homepage can be found at L. + +(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 index 00000000..40b67fb2 --- /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 + + 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 returns an iterator for I or NULL if no host is +associated with I. + +The B returns an iterator for the host following I 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 index 00000000..5833fc9a --- /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 + + int ping_iterator_get_info (pingobj_iter_t *iter, + int info, + void *buffer, + size_t *buffer_len); + +=head1 DESCRIPTION + +The B method can be used on an host iterator to return +various information about the current host. + +The I argument is an iterator as returned by ping_iterator_get(3) or +ping_iterator_next(3). + +The I argument specifies the type of information returned. Use the +following defines: + +=over 4 + +=item B + +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 and allocate B bytes of +buffer. + +=item B + +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 + +Returns the address family of the host. The buffer should be ig enough to hold +an integer. The value is either B or B. + +=item B + +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 + +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 + +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 argument is a pointer to an appropriately sized area of memory +where the result of the call will be stored. The I value is used as +input and output: When calling B it reports the size of +the memory region pointed to by I. The method will write the number of +bytes actually written to the memory into I before returning. + +=head1 RETURN VALUE + +B returns zero if it succeeds. + +B is returned if the value passed as I is unknown. Both, +I and I, will be left untouched in this case. + +If the requested information didn't fit into I then the size that would +have been needed is written into I; I itself is left +untouched. The return value is B in this case. + +=head1 SEE ALSO + +ping_iterator_get(3), +liboping(3) + +=head1 AUTHOR + +liboping is written by Florian octo Forster Eocto at verplant.orgE. +It's homepage can be found at L. + +(c) 2005, 2006 by Florian octo Forster. -- 2.30.2