src/mans/ping_iterator_get_info.pod

   1 =head1 NAME
   2
   3 ping_iterator_get_info - Constructor for the liboping class
   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 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 ig 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 occured
  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 liboping
  77 can handle several hosts in parallel it uses a (pseudo-)random number here. The
  78 buffer should be big enough to hold an integer value.
  79
  80 =back
  81
  82 The I<buffer> argument is a pointer to an appropriately sized area of memory
  83 where the result of the call will be stored. The I<buffer_len> value is used as
  84 input and output: When calling B<ping_iterator_get_info> it reports the size of
  85 the memory region pointed to by I<buffer>. The method will write the number of
  86 bytes actually written to the memory into I<buffer_len> before returning.
  87
  88 =head1 RETURN VALUE
  89
  90 B<ping_iterator_get_info> returns zero if it succeeds.
  91
  92 B<EINVAL> is returned if the value passed as I<info> is unknown. Both,
  93 I<buffer> and I<buffer_len>, will be left untouched in this case.
  94
  95 If the requested information didn't fit into I<buffer> then the size that would
  96 have been needed is written into I<buffer_len>; I<buffer> itself is left
  97 untouched. The return value is B<ENOMEM> in this case.
  98
  99 =head1 SEE ALSO
 100
 101 L<ping_iterator_get(3)>,
 102 L<liboping(3)>
 103
 104 =head1 AUTHOR
 105
 106 liboping is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
 107 It's homepage can be found at L<http://verplant.org/liboping/>.
 108
 109 (c) 2005-2008 by Florian octo Forster.