.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ping_iterator_get_info 3"
.TH ping_iterator_get_info 3 "2006-05-29" "0.3.1" "liboping"
.SH "NAME"
ping_iterator_get_info \- Constructor for the liboping class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #include <oping.h>
.Ve
.PP
.Vb 4
\&  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 \fIping_iterator_get\fR\|(3) or
\&\fIping_iterator_next\fR\|(3).
.PP
The \fIinfo\fR argument specifies the type of information returned. Use the
following defines:
.IP "\fB\s-1PING_INFO_HOSTNAME\s0\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
\&\fIping_host_add\fR\|(3). The hostname is actually looked up every time you call
this method, no cache is involved within liboping.
.Sp
It is recommended to include \f(CW\*(C`netdb.h\*(C'\fR and allocate \fB\s-1NI_MAXHOST\s0\fR bytes of
buffer.
.IP "\fB\s-1PING_INFO_ADDRESS\s0\fR" 4
.IX Item "PING_INFO_ADDRESS"
Return the address used in \s-1ASCII\s0 (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 "\fB\s-1PING_INFO_FAMILY\s0\fR" 4
.IX Item "PING_INFO_FAMILY"
Returns the address family of the host. The buffer should be ig enough to hold
an integer. The value is either \fB\s-1AF_INET\s0\fR or \fB\s-1AF_INET6\s0\fR.
.IP "\fB\s-1PING_INFO_LATENCY\s0\fR" 4
.IX Item "PING_INFO_LATENCY"
Return the last measured latency or less than zero if the timeout occured
before a echo response was received. The buffer should be big enough to hold a
double value.
.IP "\fB\s-1PING_INFO_SEQUENCE\s0\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 "\fB\s-1PING_INFO_IDENT\s0\fR" 4
.IX Item "PING_INFO_IDENT"
Return the ident that is put into every \s-1ICMP\s0 packet sent to this host. Per
convention this usually is the \s-1PID\s0 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.
.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
\&\fB\s-1EINVAL\s0\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 \fB\s-1ENOMEM\s0\fR in this case.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIping_iterator_get\fR\|(3),
\&\fIliboping\fR\|(3)
.SH "AUTHOR"
.IX Header "AUTHOR"
liboping is written by Florian octo Forster <octo at verplant.org>.
It's homepage can be found at <http://verplant.org/liboping/>.
.PP
(c) 2005, 2006 by Florian octo Forster.