.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "ping_iterator_get_info 3" .TH ping_iterator_get_info 3 2024-03-07 1.10.0 liboping .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME ping_iterator_get_info \- Receive information about a host .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& int ping_iterator_get_info (pingobj_iter_t *iter, \& int info, \& void *buffer, \& size_t *buffer_len); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" The \fBping_iterator_get_info\fR method can be used on an host iterator to return various information about the current host. .PP The \fIiter\fR argument is an iterator as returned by \fBping_iterator_get\fR\|(3) or \&\fBping_iterator_next\fR\|(3). .PP The \fIinfo\fR argument specifies the type of information returned. Use the following defines: .IP \fBPING_INFO_USERNAME\fR 4 .IX Item "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 \fBping_host_add\fR\|(3) and which you need to pass to \f(CW\*(C`ping_host_remove\*(C'\fR, too. .IP \fBPING_INFO_HOSTNAME\fR 4 .IX Item "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 \&\fBping_host_add\fR\|(3). The hostname is actually looked up every time you call this method, no cache is involved within \fIliboping\fR. .Sp It is recommended to include \f(CW\*(C`netdb.h\*(C'\fR and allocate \fBNI_MAXHOST\fR bytes of buffer. .IP \fBPING_INFO_ADDRESS\fR 4 .IX Item "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. .IP \fBPING_INFO_FAMILY\fR 4 .IX Item "PING_INFO_FAMILY" Returns the address family of the host. The buffer should be big enough to hold an integer. The value is either \fBAF_INET\fR or \fBAF_INET6\fR. .IP \fBPING_INFO_LATENCY\fR 4 .IX Item "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. .IP \fBPING_INFO_DROPPED\fR 4 .IX Item "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 \&\f(CW\*(C`uint32_t\*(C'\fR. .IP \fBPING_INFO_SEQUENCE\fR 4 .IX Item "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. .IP \fBPING_INFO_IDENT\fR 4 .IX Item "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 \&\fIliboping\fR can handle several hosts in parallel it uses a (pseudo\-)random number here. The buffer should be big enough to hold an integer value. .IP \fBPING_INFO_RECV_TTL\fR 4 .IX Item "PING_INFO_RECV_TTL" Returns the \fItime to live\fR (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 \fBPING_OPT_TTL\fR of \fBping_setopt\fR\|(3). The buffer should be big enough to hold an integer value. .IP \fBPING_INFO_RECV_QOS\fR 4 .IX Item "PING_INFO_RECV_QOS" Returns the value of the \fIQuality of Service\fR (QoS) byte of the incoming IPv4 or IPv6 packet. This byte is not interpreted by \fIliboping\fR 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 \f(CW\*(C`uint8_t\*(C'\fR. .PP The \fIbuffer\fR argument is a pointer to an appropriately sized area of memory where the result of the call will be stored. The \fIbuffer_len\fR value is used as input and output: When calling \fBping_iterator_get_info\fR it reports the size of the memory region pointed to by \fIbuffer\fR. The method will write the number of bytes actually written to the memory into \fIbuffer_len\fR before returning. .SH "RETURN VALUE" .IX Header "RETURN VALUE" \&\fBping_iterator_get_info\fR returns zero if it succeeds. .PP \&\fBEINVAL\fR is returned if the value passed as \fIinfo\fR is unknown. Both, \&\fIbuffer\fR and \fIbuffer_len\fR, will be left untouched in this case. .PP If the requested information didn't fit into \fIbuffer\fR then the size that would have been needed is written into \fIbuffer_len\fR; \fIbuffer\fR itself is left untouched. The return value is \fBENOMEM\fR in this case. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBping_iterator_get\fR\|(3), \&\fBliboping\fR\|(3) .SH AUTHOR .IX Header "AUTHOR" liboping is written by Florian "octo" Forster . Its homepage can be found at . .PP Copyright (c) 2006\-2017 by Florian "octo" Forster.