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