liboping(3) [debian man page]
liboping(3) liboping liboping(3) NAME
liboping - Library to send ICMPv4/ICMPv6 echo packets to multiple hosts DESCRIPTION
This is an overview of liboping, a C library to send ICMP ECHO_REQUEST packets to remote hosts and measure the time it takes for replies to be received. This method, often simply called "ping", is a common way to measure network latency and/or host reachability. The goals of this library are to provide the above functionality in a platform and protocol independent manner. The interface is simple, object oriented and (hopefully) ANSI-C compliant. GENERAL USAGE
There are two main types that are used by applications. Both are "opaque types", meaning they are structures that are not completely defined in the header file, so you cannot access the structures' members. You don't need to, don't do it. These structures are subject to change without notice. "pingobj_t" A ping-object. You can set specific options for this object, add and remove hosts to/from it and send ICMP packets to all associated hosts. This is often called a "handle". "pingobj_iter_t" An iterator over the hosts associated with a "pingobj_t" object. This iterator can be used to query more information about a host, for example the hostname, the measured latency or the current ICMP sequence. Upon startup you usually create one or more "pingobj_t" objects and add hosts to it using the "ping_host_add" method (see below). You periodically send "echo requests" using the "ping_send" method, iterate over all hosts using "ping_iterator_get" and "ping_iterator_next". For each host you call "ping_iterator_get_info" to read the current latency and do something with it. If an error occurs you can use "ping_get_error" so get information on what failed. LINKING WITH LIBOPING
Depending on you platform you don't need any extra libraries (e.g. GNU/Linux) or "libsocket" (using "-lsocket") if the "socket" function is not in the C-library. The latter is the case for the Solaris operating system. SYMBOL NAMES
All "official" function or method names are prefixed with "ping_". Don't use any other functions or methods. Although no such functions should exist. THREAD SAFETY
liboping has been designed to be as thread safe a possible. However, this has not been tested and may need some additional work. Use at your own risk and please report back any problems or success messages. Thank you :) SEE ALSO
ping_construct(3), ping_setopt(3), ping_host_add(3), ping_send(3), ping_get_error(3), ping_iterator_get(3), ping_iterator_get_info(3), ping_iterator_get_context(3) LICENSE
liboping is licensed under the GPLv2. No other version of the license is applicable. 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 2012-01-31 liboping(3)
Check Out this Related Man Page
OPING(8) liboping OPING(8) NAME
oping - send ICMP ECHO_REQUEST to network hosts SYNOPSIS
oping [-4 | -6] [-c count] [-i interval] host [host [host ...]] oping [-4 | -6] [-c count] [-i interval] -f filename noping [-4 | -6] [-c count] [-i interval] host [host [host ...]] noping [-4 | -6] [-c count] [-i interval] -f filename DESCRIPTION
oping uses ICMPv4 or ICMPv6 ECHO_REQUEST packets to measure a hosts reachability and the network latency. In contrast to the original ping(8) utility oping can send ICMP packets to multiple hosts in parallel and wait for all ECHO_RESPONSE packets to arrive. In contrast to the fping utility (URL is listed in "SEE ALSO") oping can use both, IPv4 and IPv6 transparently and side by side. noping is an ncurses-based front-end to liboping which displays ping statistics online and highlights aberrant round-trip times if the terminal supports colors. OPTIONS
-4 Force the use of IPv4. -6 Force the use of IPv6. -c count Send (and receive) count ICMP packets, then stop and exit. -i interval Send one ICMP packet (per host) each interval seconds. This can be a floating-point number to specify sub-second precision. -t ttl Set the IP Time to Live to ttl. This must be a number between (and including) 1 and 255. If omitted, the value 64 is used. -I address Set the source address to use. You may either specify an IP number or a hostname. You cannot pass the interface name, as you can with GNU's ping(8) - use the -D option for that purpose. -D interface name Set the outgoing network device to use. -f filename Instead of specifying hostnames on the command line, read them from filename. If filename is -, read from "STDIN". If oping is installed with the SetUID-bit, it will set the effective UID to the real UID before opening the file. In the special (but common) case that oping is owned by the super-user (UID 0), this means that privileges are temporarily dropped before opening the file, in order to prevent users from reading arbitrary files on the system. If your system doesn't provide saved set-user IDs (this was an optional feature before POSIX 2001), the behavior is different because it is not possible to temporarily drop privileges. The alternative behavior is: If the real user ID (as returned by getuid(2)) and the effective user ID (as returned by geteuid(2)) differ, the only argument allowed for this option is "-" (i.e. standard input). -Q qos Specify the Quality of Service (QoS) for outgoing packets. This is a somewhat tricky option, since the meaning of the bits in the IPv4 header has been revised several times. The currently recommended method is Differentiated Services which is used in IPv6 headers as well. There are shortcuts for various predefined per-hop behaviors (PHBs): be Selects the Best Effort behavior. This is the default behavior. ef Selects the Expedited Forwarding (EF) per-hop behavior, as defined in RFC 3246. This PHB is characterised by low delay, low loss and low jitter, i.e. high priority traffic. va Selects the Voice Admitted (VA) per-hop behavior, as defined in RFC 5865. This traffic class is meant for Voice over IP (VoIP) traffic which uses Call Admission Control (CAC) for reserving network capacity. afcp Selects one of 12 differentiated services code points (DSCPs), which are organized in four classes with three priorities each. Therefore, c must be a number between 1 through 4 and p must be a number between 1 through 3, for example "af13", "af22" and "af41". In each class, the lower priority number takes precedence over the higher priority number. csn Selects one of the eight Class Selector PHBs. n is a number between 0 through 7. The class selectors have been defined to be compatible to the Precedence field in the IPv4 header as defined in RFC 791. Please note that "cs0" is synonymous to "be". The old definition of the same bits in the IPv4 header was as Type of Service (ToS) field, specified in RFC 1349. It defined four possible values which have appropriate aliases. Please note that this use of the bits is deprecated and the meaning is limited to IPv4! lowdelay Minimize delay throughput Maximize throughput reliability Maximize reliability mincost Minimize monetary cost Alternatively, you can also specify the byte manually. You can use either a decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number (00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal respectively. The printed lines will contain information about the QoS field of received packets if either a non-standard QoS setting was used on outgoing packets or if the QoS byte of incoming packets is not zero. In other words, the QoS information is omitted if both, the outgoing and the incoming QoS bytes are zero. The received byte is always interpreted as Differentiated Services Code Point (DSCP) and Explicit Congestion Notification (ECN), even if the deprecated Type of Service (ToS) aliases were used to specify the bits of outgoing packets. -Z percent If any hosts have a drop rate higher than percent, where percent is a number between zero and 100 inclusively, exit with a non-zero exit status. Since it is not possible to have a higher drop rate than 100%, passing this limit will effectively disable the feature (the default). Setting the option to zero means that the exit status will only be zero if all replies for all hosts have been received. The exit status will indicate the number of hosts with more than percent packets lost, up to a number of 255 failing hosts. COLORS
If supported by the terminal, noping will highlight the round-trip times (RTT) using the colors green, yellow and red. Green signals RTTs that are in the "expected" range, yellow marks moderately unusual times and times that differ a lot from the expected value are printed in red. The information used to categorize round-trip times is the average round-trip time and the standard deviation. RTTs that differ from the average by less than the standard deviation are considered to be "normal" and are printed in green. Times that differ from the average more than the standard deviation but less than twice the standard deviation are considered "moderately unusual" and are printed in yellow. Times differing more than twice the standard deviation from the average are considered to be "unusual" and are printed in red. SEE ALSO
ping(8), <http://www.fping.com/>, liboping(3) AUTHOR
liboping is written by Florian "octo" Forster <ff at octo.it>. Its homepage can be found at <http://verplant.org/liboping/>. Copyright (c) 2005-2011 by Florian "octo" Forster. 1.6.2 2012-02-03 OPING(8)