A SAMPLE LLRPC USER
===================

    There are two ways to communicate with a Click kernel module from user
level. The first, handlers, uses a simple file-based model: you read and
write files in /click or /click/ELEMENTNAME. Generally, these files are
ASCII. For example, to read the current count from a counter named 'c', you
might read '/click/c/count', then parse the result (a simple string like
"2003") into an integer. To change the RED min_thresh parameter, you might
write a string like "10" to the file '/click/red/min_thresh'.

    Handlers are a heavyweight mechanism -- all that file opening and
closing and data parsing and unparsing -- although relatively easy to use.
The other communication method, LLRPCs (low-level remote procedure calls),
is much faster, although less safe; it's suitable for heavy-duty
kernel/user communication.

    A Click LLRPC is implemented by ioctl. A user-level program opens any
of the element's handler files -- for example, its '/click/ELEMENT/name'
handler -- then calls ioctl(), passing in the file descriptor, one of the
LLRPC IDs from <click/llrpc.h>, and the relevant data. For example, the
CLICK_LLRPC_GET_COUNT LLRPC takes a pointer to an integer. On input, this
integer identifies the counter of interest.  On output, its value is set to
the relevant count. This is much less expensive than using an ASCII 'count'
handler.

    Several of our elements provide LLRPC interfaces; for example, check
out the Counter element in elements/standard/counter.cc. These interfaces
are generally documented in the element manual pages -- for example, 'man
Counter'.

    Sometimes, you may want to keep a file descriptor open for a long time
for making LLRPC calls. Remember that this file descriptor will become
invalid if someone installs another Click configuration! All LLRPC calls on
the old file descriptor will return EINVAL. One reasonable behavior for
EINVAL errors is to close and reopen the file descriptor on error, try
again, and only complain if the ioctl fails the second time as well.
