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¶
- •
- 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.