ping_iterator_get_info - Receive information about a host
#include <oping.h>
int ping_iterator_get_info (pingobj_iter_t *iter,
int info,
void *buffer,
size_t *buffer_len);
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.
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.
liboping is written by Florian "octo" Forster <ff at
octo.it>. Its homepage can be found at <http://noping.cc/>.
Copyright (c) 2006-2017 by Florian "octo" Forster.