1 SPRAY(3RPC)                  RPC Library Functions                 SPRAY(3RPC)
   2 
   3 
   4 
   5 NAME
   6        spray - scatter data in order to test the network
   7 
   8 SYNOPSIS
   9        cc [ flag ... ] file ... -lsocket -lnsl -lrpcsvc [ library ... ]
  10        #include <rpcsvc/spray.h>
  11 
  12        bool_t xdr_sprayarr(XDR *xdrs, sprayarr *objp);
  13 
  14 
  15        bool_t xdr_spraycumul(XDR *xdrs, spraycumul *objp);
  16 
  17 
  18 DESCRIPTION
  19        The spray program sends packets to a given machine to test
  20        communications with that machine.
  21 
  22 
  23        The spray program is not a C function interface, per se, but it can be
  24        accessed using the generic remote procedure calling interface
  25        clnt_call(). See rpc_clnt_calls(3NSL). The program sends a packet to
  26        the called host. The host acknowledges receipt of the packet. The
  27        program counts the number of acknowledgments and can return that count.
  28 
  29 
  30        The spray program currently supports the following procedures, which
  31        should be called in the order given:
  32 
  33        SPRAYPROC_CLEAR
  34                           This procedure clears the counter.
  35 
  36 
  37        SPRAYPROC_SPRAY
  38                           This procedure sends the packet.
  39 
  40 
  41        SPRAYPROC_GET
  42                           This procedure returns the count and the amount of
  43                           time since the last SPRAYPROC_CLEAR.
  44 
  45 
  46 EXAMPLES
  47        Example 1 Using spray()
  48 
  49 
  50        The following code fragment demonstrates how the spray program is used:
  51 
  52 
  53          #include <rpc/rpc.h>
  54          #include <rpcsvc/spray.h>
  55           .  .  .
  56               spraycumul     spray_result;
  57               sprayarr  spray_data;
  58               char      buf[100];      /* arbitrary data */
  59               int       loop = 1000;
  60               CLIENT    *clnt;
  61               struct timeval timeout0 = {0, 0};
  62               struct timeval timeout25 = {25, 0};
  63               spray_data.sprayarr_len = (uint_t)100;
  64               spray_data.sprayarr_val = buf;
  65               clnt = clnt_create("somehost", SPRAYPROG, SPRAYVERS, "netpath");
  66               if (clnt == (CLIENT *)NULL) {
  67                    /* handle this error */
  68               }
  69               if (clnt_call(clnt, SPRAYPROC_CLEAR,
  70                    xdr_void, NULL, xdr_void, NULL, timeout25)) {
  71                         /* handle this error */
  72               }
  73               while (loop- > 0)      {
  74                    if (clnt_call(clnt, SPRAYPROC_SPRAY,
  75                         xdr_sprayarr, &spray_data, xdr_void, NULL, timeout0)) {
  76                              /* handle this error */
  77                    }
  78               }
  79               if (clnt_call(clnt, SPRAYPROC_GET,
  80                    xdr_void, NULL, xdr_spraycumul, &spray_result, timeout25)) {
  81                         /* handle this error */
  82               }
  83               printf("Acknowledged %ld of 1000 packets in %d secs %d usecs\n",
  84                    spray_result.counter,
  85                    spray_result.clock.sec,
  86                    spray_result.clock.usec);
  87 
  88 
  89 ATTRIBUTES
  90        See attributes(5) for descriptions of the following attributes:
  91 
  92 
  93 
  94 
  95        +---------------+-----------------+
  96        |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
  97        +---------------+-----------------+
  98        |MT-Level       | Unsafe          |
  99        +---------------+-----------------+
 100 
 101 SEE ALSO
 102        rpc_clnt_calls(3NSL), attributes(5)
 103 
 104 NOTES
 105        This interface is unsafe in multithreaded applications.  Unsafe
 106        interfaces should be called only from the main thread.
 107 
 108 
 109        A spray program is not useful as a networking benchmark as it uses
 110        unreliable connectionless transports, for example, udp. It can report a
 111        large number of packets dropped, when the drops were caused by the
 112        program sending packets faster than they can be buffered locally, that
 113        is, before the packets get to the network medium.
 114 
 115 
 116 
 117                                 April 13, 2017                     SPRAY(3RPC)