((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/eping" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg") (toc)) (section 2 "eping" (p "eping is a Scheme implementation of the ICMP ping utility. Although it can be used like an average OS ping utility, eping is intended to be used programmatically (e.g. for gathering statistics, monitoring). It uses raw sockets thus a privileged account must be used.") (highlight sh "[procedure] (eping HOST #!key (mode 'probe)\n                              (count #f)\n                              (timeout 1000)\n                              (interval 1000)\n                              (ttl 64)\n                              (tos 0)\n                              (dont-fragment #f)\n                              (src-addr #f)\n                              (id #f)\n                              (seq-start 0)\n                              (size 56)\n                              (pattern \"\")\n                              (recv-min #f)\n                              (lost-max #f)\n                              (cons-recv-min #f)\n                              (cons-lost-max #f)\n                              (msg1 \"%i is alive\\n\")\n                              (msg2 \"\")\n                              (dotcols 0)\n                              (quiet #t))") (p "HOST can be either an IPv4 address or a hostname: \"192.168.1.1\", \"example.com\", and even 'example.com are all valid hosts.") (p "eping supports four modes of operation: " (i "probe") " (default), " (i "stats") ", " (i "dot") " and " (i "mtu") ".") (section 3 "Probe mode" (p "In this mode eping returns either true or false if it considers an host alive or unreachable respectively. The default behavior is to consider an host alive as soon as an echo reply is received. If no reply is received in " (i "count") " attempts (5 by default), the host is considered unreachable. Probe mode is the default one so it can be omitted as parameter.") (highlight scheme "(eping \"call-cc.org\")\n\n===> #t") (p "The aliveness criteria can be changed through the five parameters " (i "count") ", " (i "recv-min") ", " (i "lost-max") ", " (i "cons-recv-min") ", " (i "cons-lost-max") " (see \"Parameters\" section). As soon as one of these conditions is met eping returns the associated boolean value. If no condition is met in " (i "count") " attempts " (i "#f") " is returned.") (p "In non-quiet 'submode' a message is displayed.") (highlight scheme "(eping \"call-cc.org\" quiet: #f)\n209.172.49.65 is alive") (p "The output messages can be customized through the " (i "msg1") " and " (i "msg2") " parameters.")) (section 3 "Stats mode" (p "In stats mode eping returns a vector of statistics #(sent lost rtt-min rtt-avg rtt-max rtt-std). The rtt values are expressed in " (i "ms") ".") (highlight scheme "(eping \"call-cc.org\" mode: 'stats)\n\n===> #(5 0 133 134.2 136 0.92)") (p "In non-quiet 'submode' the output resembles a standard ping utility:") (highlight scheme "(eping \"call-cc.org\" mode: 'stats quiet: #f)\n64 bytes from 209.172.49.65: icmp_seq=0 ttl=52 time=139ms\n64 bytes from 209.172.49.65: icmp_seq=1 ttl=52 time=227ms\n64 bytes from 209.172.49.65: icmp_seq=2 ttl=52 time=135ms\n64 bytes from 209.172.49.65: icmp_seq=3 ttl=52 time=170ms\n64 bytes from 209.172.49.65: icmp_seq=4 ttl=52 time=256ms\n\n--- call-cc.org ping statistics ---\n5 packets transmitted, 5 packets received, 0% packet loss\nround-trip min/avg/max/stddev = 135.0/185.4/256.0/48.26 ms") (p "Ctrl-\\ (SIGQUIT) can be used to print partial statistics without halting the ping (POSIX platforms only). Ctrl-C can be used to stop and collect the statistics at any moment.") (p "By default 5 packets are sent. The " (i "count") " option can be used to change this value (0 meaning non-stop operation).")) (section 3 "Dot mode" (p "In this mode eping returns a single character for each echo request:") (pre "[.] Echo reply received\n[!] No response\n[N] Network unreachable\n[H] Host unreachable\n[P] Protocol unreachable\n[F] Packet too big and DF bit set\n[A] Administratively filtered\n[T] Time to live exceeded\n[O] Network/Host unreachable for TOS\n[U] Unreachable (generic error)") (highlight scheme "(eping \"call-cc.org\" mode: 'dot quiet: #f timeout: 134 count: 20)\n..!...!....!.!!!....") (p "The " (i "dotcols") " parameter can be used to set the number of chars to be printed before a newline. The default behavior (0) inserts a newline only after the last echo request.") (highlight scheme "(eping \"call-cc.org mode\": 'dot quiet: #f timeout: 134 count: 20 dotcols: 5)\n!...!\n....!\n...!.\n!....") (p "In quiet 'submode' a string built from the generated characters is returned.") (highlight scheme "(eping \"call-cc.org\" mode: 'dot count: 3)\n\n===> \"...\"")) (section 3 "MTU mode" (p "In mtu mode eping attempts to discover the MTU along the path. To speed up the process it is advisable to lower the default 1000" (i "ms") " echo requests interval time (" (i "interval") " option).") (highlight scheme "(eping \"call-cc.org\" mode: 'mtu interval: 250)\n\n===> 1492") (p "Lossy links may slow down or even prevent the convergence. The " (i "count") " option can be used to increase the number of attempts (default is 64). If the mtu can't be computed #f is returned.")) (section 3 "Parameters" (section 4 "General" (ul (li (b "count") " The number of echo requests to be sent. The default is 5 for modes other than " (i "mtu") " and 64 for " (i "mtu") " mode. If set to 0 echo requests are sent until a probe condition is met (" (i "probe") " mode), mtu is computed (" (i "mtu") " mode) or SIGINT (Ctrl-C) is received (all modes).") (li (b "timeout") " The amount of time in " (i "ms") " to let pass before considering an host unreachable (default is 1000ms).") (li (b "interval") " The interval in " (i "ms") " between echo requests (default is 1000ms). This value can't be set lower than " (i "timeout") " (this rule is enforced lowering " (i "timeout") " in case)."))) (section 4 "IP" (ul (li (b "ttl") " / " (b "tos") " Respectively the Time To Live and TOS in the IP header.") (li (b "dont-fragment") " Sets the Don't Fragment (DF) flag in the IP header.") (li (b "src-addr") " Binds the ICMP socket to a specific IP address."))) (section 4 "ICMP" (ul (li (b "size") " The ICMP payload size.") (li (b "pattern") " A string used to fill the payload (repeated if necessary).") (li (b "id") " The Identifier field (0-65535). By default it is generated randomly for every invocation of the eping function.") (li (b "seq-start") " The initial sequence of the echo requests (0 by default)."))) (section 4 "Probing" (ul (li (b "recv-min") " Minimum number of received replies before considering an host alive.") (li (b "lost-max") " Maximum number of missed replies before considering an host unreachable.") (li (b "cons-recv-min") " Minimum number of consecutive received replies before considering an host alive.") (li (b "cons-lost-max") "  Maximum number of consecutive missed replies before considering an host unreachable."))) (section 4 "Output" (ul (li (b "msg1") " The message displayed when an host is considered alive. The default message is \"%i is alive\\n\" where %i is expanded to the IP address of the host. Similarly %h is interpreted as the hostname.") (li (b "msg2") "  The message displayed when an host is considered unreachable. By default it is an empty string.") (li (b "dotcols") " In " (i "dot") " mode the number of displayed chars before a newline is inserted. By default (0) a newline is inserted only after the last displayed char.") (li (b "quiet") " By default eping doesn't display anything unless this option is set to " (i "#f") ".")))) (section 3 "Requirements" (p (int-link "socket") " (>= 0.2.4)")) (section 3 "Installation" (highlight bash "$ chicken-install eping") (p "A command-line application is also available:") (highlight sh "$ chicken-install -r eping\n$ cd eping/app\n$ make\n$ ./eping\neping HOST [-mode probe|stats|dot|mtu]\n           [-count COUNT]\n           [-interval INTERVAL]\n           [-timeout TIMEOUT]\n           [-ttl TTL]\n           [-tos TOS]\n           [-src-addr IP]\n           [-dont-fragment]\n           [-id ID]\n           [-seq-start SEQ]\n           [-size SIZE]\n           [-pattern PATTERN]\n           [-recv-min RMIN]\n           [-lost-max LMAX]\n           [-cons-recv-min CRMIN]\n           [-cons-lost-max CLMAX]\n           [-msg1 MSG1]\n           [-msg2 MSG2]\n           [-dotcols COLS]\n           [-quiet]\n           [-version]")) (section 3 "Usage" (highlight scheme "(use eping)")) (section 3 "Todo/Wishlist" (ul (li "hop count mode") (li "pattern matching") (li "traceroute mode?") (li "tcp/udp support?") (li "ipv6?"))) (section 3 "About this egg" (p "The source code is hosted at " (link "https://bitbucket.org/miklam/eping/" "Bitbucket") ". Feel free to send pull requests or open an issue there. Alternatively, send an e-mail to the " (link "mailto://chicken-users@nongnu.org" "chicken-users") " mailing list for information or requests.") (section 4 "Version History" (dl (dt "1.0") (dd "Initial release"))) (section 4 "Author" (p "Michele La Monaca")) (section 4 "License" (pre "Copyright (c) 2013\nMichele La Monaca (eping@lamonaca.net)\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are\nmet:\n\n1) Redistributions of source code must retain the above copyright\nnotice, this list of conditions and the following disclaimer.\n\n2) Redistributions in binary form must reproduce the above copyright\nnotice, this list of conditions and the following disclaimer in the\ndocumentation and/or other materials provided with the distribution.\n\n3) Neither the name of the author nor the names of its contributors\nmay be used to endorse or promote products derived from this software\nwithout specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS\nFOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE\nCOPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,\nINDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\nHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\nSTRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\nARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED\nOF THE POSSIBILITY OF SUCH DAMAGE.")))))