Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ping_iterator_get_info(3)	   liboping	     ping_iterator_get_info(3)

NAME
       ping_iterator_get_info -	Receive	information about a host

SYNOPSIS
	 #include <oping.h>

	 int ping_iterator_get_info (pingobj_iter_t *iter,
			 int info,
			 void *buffer,
			 size_t	*buffer_len);

DESCRIPTION
       The ping_iterator_get_info method can be	used on	an host	iterator to
       return various information about	the current host.

       The iter	argument is an iterator	as returned by ping_iterator_get(3) or
       ping_iterator_next(3).

       The info	argument specifies the type of information returned. Use the
       following defines:

       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	ping_host_add(3) and
	   which you need to pass to "ping_host_remove", too.

       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 ping_host_add(3).	The hostname is	actually
	   looked up every time	you call this method, no cache is involved
	   within liboping.

	   It is recommended to	include	"netdb.h" and allocate NI_MAXHOST
	   bytes of buffer.

       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.

       PING_INFO_FAMILY
	   Returns the address family of the host. The buffer should be	big
	   enough to hold an integer. The value	is either AF_INET or AF_INET6.

       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.

       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 "uint32_t".

       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.

       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 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.

       PING_INFO_RECV_TTL
	   Returns the time to live (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
	   PING_OPT_TTL	of ping_setopt(3). The buffer should be	big enough to
	   hold	an integer value.

       PING_INFO_RECV_QOS
	   Returns the value of	the Quality of Service (QoS) byte of the
	   incoming IPv4 or IPv6 packet. This byte is not interpreted by
	   liboping 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 "uint8_t".

       The buffer argument is a	pointer	to an appropriately sized area of
       memory where the	result of the call will	be stored. The buffer_len
       value is	used as	input and output: When calling ping_iterator_get_info
       it reports the size of the memory region	pointed	to by buffer. The
       method will write the number of bytes actually written to the memory
       into buffer_len before returning.

RETURN VALUE
       ping_iterator_get_info returns zero if it succeeds.

       EINVAL is returned if the value passed as info is unknown. Both,	buffer
       and buffer_len, will be left untouched in this case.

       If the requested	information didn't fit into buffer then	the size that
       would have been needed is written into buffer_len; buffer itself	is
       left untouched. The return value	is ENOMEM in this case.

KNOWN BUGS
       o   PING_INFO_RECV_TTL is not available under Debian Etch due to	a
	   missing define in the header	files.

SEE ALSO
       ping_iterator_get(3), liboping(3)

AUTHOR
       liboping	is written by Florian "octo" Forster <octo at verplant.org>.
       Its homepage can	be found at <http://verplant.org/liboping/>.

       Copyright (c) 2005-2011 by Florian "octo" Forster.

1.6.2				  2011-09-06	     ping_iterator_get_info(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | KNOWN BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ping_iterator_get_info&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help