This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.
ToUserDevice -- Click element;
Pass packets to user-level programs via a character device.
Ports: 1 input, no outputs
Package: linuxmodule (core)
ToUserDevice provides a way to get packets from click running in linuxmodule
into userspace through a character device. This is a way of giving packets to a
user process without going through linux's routing or networking code.
Internally, ToUserDevice has a queue of packets.
ToUserDevice can optionally apply encapsulation to the packets, either pcap
encapsulation or length-delimited encapsulation.
The character device can act like a datagram socket, where one packet is
returned per read()/recv() call (but the packet may end up truncated), or it can
act like a streaming socket where all packet data is reliably returned in a
stream. In order to reliably be able to detect packet boundaries, it makes the
most sense to use one of the encapsulation types if using the streaming
In addition, ToUserDevice can run in a mode where reads will block until there
is data available (the default mode) or it can run in a mode where read() will
return 0 (end-of-file) if the device is empty. This can be particularly useful
with the pcap format where the character device will appear to be a valid pcap
Keyword arguments are:
- Unsigned integer. Sets the capacity of the internal ring buffer that stores
the packets. Defaults to 64.
- Boolean. If true, then reads will block until there is data to return. If
false, reads when the ring buffer is empty will return 0. Defaults to true.
- Boolean. Sets the drop policy of this device if the ring buffer is currently
full. Defaults to true.
- String. Must be one of: none, pcap, len32, or len_net16. Defaults to 'none.'
Choosing pcap will cause each new open of the character device to first receive
a valid pcap file header, and add individual pcap packet headers to each packet.
len32 prepends a uint32 in host byte order before each packet with the packet's
length. len_net16 prepends a uint16 in network byte order before each packet
with the packet's length.
- Unsigned integer. When using 'ENCAP pcap', this changes the reported network
type of the pcap file. Defaults to 1 (Ethernet).
- Unsigned integer. This limits the amount of packet data returned by the 'pcap'
encapsulation type. Only affects the pcap type. Defaults to 65535.
- String. Must be one of 'packet' or 'stream'. It defaults to 'packet' if ENCAP
is 'none', and to 'stream' otherwise.
- Unsigned integer. Sets the maximum number of packets returned per read. Default
is 1. Zero means unlimited. It is likely not wise to set this to anything
except 1 if this is a 'TYPE packet' device.
- Boolean. Causes the element to print many debugging messages. Defaults to
The device must be first created in the /dev directory
via 'mknod /dev/fromclickX c 241 X' where X is the minor device number (i.e. 0, 1, 2)
A user level application can then read directly from the device once it opens a file
Generated by 'click-elem2man' from '../elements/linuxmodule/touserdevice.hh:13' on 16/Jul/2011.