ping_iterator_get_info(3)					     liboping						 ping_iterator_get_info(3)

NAME

       ping_iterator_get_info - Receive information about a host

SYNOPSIS

	 #include <oping.h>

	 int ping_iterator_get_info (pingobj_iter_t *iter,
			 int info,
			 void *buffer,
			 size_t *buffer_len);

DESCRIPTION

       The ping_iterator_get_info method can be used on an host iterator to return various information about the current host.

       The iter argument is an iterator as returned by ping_iterator_get(3) or ping_iterator_next(3).

       The info argument specifies the type of information returned. Use the following defines:

       PING_INFO_USERNAME
	   Return the hostname of the host the iterator points to as supplied by the user.  This is the name you passed to ping_host_add(3) and
	   which you need to pass to "ping_host_remove", too.

       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 "netdb.h" and allocate NI_MAXHOST bytes of buffer.

       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.

       PING_INFO_FAMILY
	   Returns the address family of the host. The buffer should be big enough to hold an integer. The value is either AF_INET or AF_INET6.

       PING_INFO_LATENCY
	   Return the last measured latency or less than zero if the timeout occurred before a echo response was received. The buffer should be
	   big enough to hold a double value.

       PING_INFO_DROPPED
	   Return the number of times that no response was received within the timeout.  This value is only increased but may wrap around at the
	   32 bit boundary.  The buffer should be big enough to hold a 32 bit integer, e. g. an "uint32_t".

       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.

       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.

       PING_INFO_RECV_TTL
	   Returns the time to live (TTL) of the received network packets. This number depends on the value that was used by the remote host when
	   it sent the echo reply and has nothing to do with the PING_OPT_TTL of ping_setopt(3). The buffer should be big enough to hold an
	   integer value.

       PING_INFO_RECV_QOS
	   Returns the value of the Quality of Service (QoS) byte of the incoming IPv4 or IPv6 packet. This byte is not interpreted by liboping at
	   all and may be DSCP / ECN or precedence / ToS depending on your network setup.  Please see the appropriate RFCs for further information
	   on values you can expect to receive. The buffer is expected to an "uint8_t".

       The buffer argument is a pointer to an appropriately sized area of memory where the result of the call will be stored. The buffer_len value
       is used as input and output: When calling ping_iterator_get_info it reports the size of the memory region pointed to by buffer. The method
       will write the number of bytes actually written to the memory into buffer_len before returning.

RETURN VALUE

       ping_iterator_get_info returns zero if it succeeds.

       EINVAL is returned if the value passed as info is unknown. Both, buffer and buffer_len, will be left untouched in this case.

       If the requested information didn't fit into buffer then the size that would have been needed is written into buffer_len; buffer itself is
       left untouched. The return value is ENOMEM in this case.

KNOWN BUGS

       o   PING_INFO_RECV_TTL is not available under Debian Etch due to a missing define in the header files.

SEE ALSO

       ping_iterator_get(3), liboping(3)

AUTHOR

       liboping is written by Florian "octo" Forster <octo at verplant.org>.  Its homepage can be found at <http://verplant.org/liboping/>.

       Copyright (c) 2005-2011 by Florian "octo" Forster.

1.6.2								    2012-01-31						 ping_iterator_get_info(3)