src/mans/ping_iterator_get_info.pod

   1 =head1 NAME
   2
   3 ping_iterator_get_info - Receive information about a host
   4
   5 =head1 SYNOPSIS
   6
   7   #include <oping.h>
   8
   9   int ping_iterator_get_info (pingobj_iter_t *iter,
  10                   int info,
  11                   void *buffer,
  12                   size_t *buffer_len);
  13
  14 =head1 DESCRIPTION
  15
  16 The B<ping_iterator_get_info> method can be used on an host iterator to return
  17 various information about the current host.
  18
  19 The I<iter> argument is an iterator as returned by L<ping_iterator_get(3)> or
  20 L<ping_iterator_next(3)>.
  21
  22 The I<info> argument specifies the type of information returned. Use the
  23 following defines:
  24
  25 =over 4
  26
  27 =item B<PING_INFO_USERNAME>
  28
  29 Return the hostname of the host the iterator points to as supplied by the user.
  30 This is the name you passed to L<ping_host_add(3)> and which you need to pass
  31 to C<ping_host_remove>, too.
  32
  33 =item B<PING_INFO_HOSTNAME>
  34
  35 Return the hostname of the host the iterator points to. Since the name is
  36 looked up using the socket address this may differ from the hostname passed to
  37 L<ping_host_add(3)>. The hostname is actually looked up every time you call
  38 this method, no cache is involved within I<liboping>.
  39
  40 It is recommended to include C<netdb.h> and allocate B<NI_MAXHOST> bytes of
  41 buffer.
  42
  43 =item B<PING_INFO_ADDRESS>
  44
  45 Return the address used in ASCII (i.e. human readable) format. The address is
  46 looked up every time you call this method. 40 bytes should be sufficient for
  47 the buffer (16 octets in hex format, seven colons and one null byte), but more
  48 won't hurt.
  49
  50 =item B<PING_INFO_FAMILY>
  51
  52 Returns the address family of the host. The buffer should be big enough to hold
  53 an integer. The value is either B<AF_INET> or B<AF_INET6>.
  54
  55 =item B<PING_INFO_LATENCY>
  56
  57 Return the last measured latency or less than zero if the timeout occurred
  58 before a echo response was received. The buffer should be big enough to hold a
  59 double value.
  60
  61 =item B<PING_INFO_DROPPED>
  62
  63 Return the number of times that no response was received within the timeout.
  64 This value is only increased but may wrap around at the 32E<nbsp>bit boundary.
  65 The buffer should be big enough to hold a 32E<nbsp>bit integer, e.E<nbsp>g. an
  66 C<uint32_t>.
  67
  68 =item B<PING_INFO_SEQUENCE>
  69
  70 Return the last sequence number sent. This number is increased regardless of
  71 echo responses being received or not. The buffer should hold an integer.
  72
  73 =item B<PING_INFO_IDENT>
  74
  75 Return the ident that is put into every ICMP packet sent to this host. Per
  76 convention this usually is the PID of the sending process, but since
  77 I<liboping> can handle several hosts in parallel it uses a (pseudo-)random
  78 number here. The buffer should be big enough to hold an integer value.
  79
  80 =item B<PING_INFO_RECV_TTL>
  81
  82 Returns the I<time to live> (TTL) of the received network packets. This number
  83 depends on the value that was used by the remote host when it sent the echo
  84 reply and has nothing to do with the B<PING_OPT_TTL> of L<ping_setopt(3)>. The
  85 buffer should be big enough to hold an integer value.
  86
  87 =item B<PING_INFO_RECV_QOS>
  88
  89 Returns the value of the I<Quality of Service> (QoS) byte of the incoming IPv4
  90 or IPv6 packet. This byte is not interpreted by I<liboping> at all and may be
  91 DSCPE<nbsp>/ ECN or precedenceE<nbsp>/ ToS depending on your network setup.
  92 Please see the appropriate RFCs for further information on values you can
  93 expect to receive. The buffer is expected to an C<uint8_t>.
  94
  95 =back
  96
  97 The I<buffer> argument is a pointer to an appropriately sized area of memory
  98 where the result of the call will be stored. The I<buffer_len> value is used as
  99 input and output: When calling B<ping_iterator_get_info> it reports the size of
 100 the memory region pointed to by I<buffer>. The method will write the number of
 101 bytes actually written to the memory into I<buffer_len> before returning.
 102
 103 =head1 RETURN VALUE
 104
 105 B<ping_iterator_get_info> returns zero if it succeeds.
 106
 107 B<EINVAL> is returned if the value passed as I<info> is unknown. Both,
 108 I<buffer> and I<buffer_len>, will be left untouched in this case.
 109
 110 If the requested information didn't fit into I<buffer> then the size that would
 111 have been needed is written into I<buffer_len>; I<buffer> itself is left
 112 untouched. The return value is B<ENOMEM> in this case.
 113
 114 =head1 KNOWN BUGS
 115
 116 =over 4
 117
 118 =item
 119
 120 B<PING_INFO_RECV_TTL> is not available under Debian Etch due to a missing
 121 define in the header files.
 122
 123 =back
 124
 125 =head1 SEE ALSO
 126
 127 L<ping_iterator_get(3)>,
 128 L<liboping(3)>
 129
 130 =head1 AUTHOR
 131
 132 liboping is written by Florian "octo" Forster E<lt>ff at octo.itE<gt>.
 133 Its homepage can be found at L<http://noping.cc/>.
 134
 135 Copyright (c) 2005-2011 by Florian "octo" Forster.