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.

SEE ALSO

       ping_iterator_get(3), liboping(3)

AUTHOR

       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.

1.10.0                                             2024-03-31                          ping_iterator_get_info(3)