.\" -*- mode: nroff -*-
.ds V 1.3
.ds E " \-\- 
.if t .ds E \(em
.de Sp
.if n .sp
.if t .sp 0.4
..
.de Es
.Sp
.RS 5
.nf
..
.de Ee
.fi
.RE
.PP
..
.de Rs
.RS
.Sp
..
.de Re
.Sp
.RE
..
.de M
.BR "\\$1" "(\\$2)\\$3"
..
.de RM
.RB "\\$1" "\\$2" "(\\$3)\\$4"
..
.TH CLICK 1 "26/Mar/2003" "Version \*V"
.SH NAME
click \- Click user-level driver
'
.SH SYNOPSIS
.B click
.RI \%[ options ]
.RI \%[ router\-file ]
'
.SH DESCRIPTION
The
.B click
driver executes a Click modular router specification in a user-level
program. It reads a router configuration file, sets up the router according
to that file, and generally continues until interrupted. The router
configuration is written in the Click language (see
.M click 5 ),
and can contain dynamically loadable code, which
.B click
will link against before installing the configuration.
.PP
The
.B click
program can read and write packets from the network using Berkeley Packet
Filters\*Esee
.M FromDevice.u n
and
.M ToDevice.u n .
It can also read and write BPF dump files, such as those created by
.M tcpdump 1 "\*Esee"
.M FromDump n
and
.M ToDump n .
The
.M InfiniteSource n
element, and others like it, may be useful for testing configurations
without affecting the network.
'
.SH "OPTIONS"
'
If any filename argument is a single dash "-",
.B click
will use the standard input or output instead, as appropriate.
'
.TP 5
.BI \-f " file"
.PD 0
.TP
.BI \-\-file " file"
Read the router configuration from
.IR file .
The default is the standard input.
'
.Sp
.TP
.BI \-e " expr"
.TP
.BI \-\-expression " expr"
Use
.IR expr ,
a string in the Click language, as the router configuration.
'
.Sp
.TP
.BI \-p " port"
.TP
.BI \-\-port " port"
Open a
.M ControlSocket n
connection listening on TCP port
.IR port .
ControlSockets allow users to connect to the router and call its read and
write handlers remotely.
'
.Sp
.TP
.BI \-u " file"
.TP
.BI \-\-unix\-socket " file"
Open a
.M ControlSocket n
connection listening on a Unix socket, on file
.IR file .
'
.Sp
.TP
.BR \-R ", " \-\-allow\-reconfigure
Provide a "hotconfig" handler, which allows remote
.M ControlSocket n
users, and elements within the router, to reconfigure the router
dynamically. See
.M click.o 8 's
"/click/hotconfig" section for more information on hot-swapping.
'
.Sp
.TP
.BI \-h " \fR[\fPelement\fR.]\fPhandler"
.TP
.BI \-\-handler " \fR[\fPelement\fR.]\fPhandler"
After running the driver, call
.IR element 's
read handler named
.IR handler ,
or the global read handler named
.IR handler ,
and print the result to standard output.  Each element has several generic
handlers\*Efor example,
.BR config
returns the element's configuration string and
.BR class
returns the element's class name.  Some elements have additional handlers;
.M Counter n ,
for example, has
.BR count " and " rate
handlers that return the number of packets arrived and the recent arrival
rate in packets per second.  See
.M click.o 8
for more information on generic handlers, and the element documentation for
more information on element-specific handlers.
.Sp
.I element
may be a pattern that uses the shell's globbing syntax (*, ?, and
[...]).  In this case,
.B click
will run each
.I handler
whose element's name matches the pattern.
.I element
may also be an element class or interface name, such as "Queue" or "Storage";
.B click
will run each
.I handler
whose element has that class or interface.
'
.Sp
.TP
.BI \-x " \fR[\fPelement\fR.]\fPhandler"
.TP
.BI \-\-exit-handler " \fR[\fPelement\fR.]\fPhandler"
After running the driver, call
.IR element 's
read handler named
.IR handler ,
or the global read handler named
.IR handler ,
and use the result as the
.B click
process exit value.  The handler should return an integer, which is used directly, or a boolean (true means 0, false means 1).
'
.Sp
.TP
.BI \-o " file"
.TP
.BI \-\-output " file"
Write a flattened version of the router configuration to
.IR file .
The flattening process removes all compound elements and additional archive
members.
'
.Sp
.TP 5
.BR \-q ", " \-\-quit
Do not run the driver. This option can be used to check a configuration for
errors, or to check handler results (with the
.B \-\-handler
option) without running the configuration.
'
.Sp
.TP 5
.BR \-t ", " \-\-time
Print the time it took to run the driver.
'
.Sp
.TP 5
.BR \-w ", " \-\-no\-warnings
Do not print any warning messages.
'
.Sp
.TP
.BI \-C " path"
.TP
.BI \-\-clickpath " path"
Use
.I path
for CLICKPATH.
'
.Sp
.TP 5
.BI \-\-help
Print usage information and exit.
'
.Sp
.TP
.BI \-\-version
Print the version number and some quickie warranty information and exit.
'
.PD
'
.SH "BUGS"
If you get an unaligned access error, try running your configuration
through
.M click-align 1
first.
'
.SH "SEE ALSO"
.M click-align 1 ,
.M click 5 ,
.M click.o 8 ,
.M ControlSocket n ,
.M FromDevice.u n ,
.M ToDevice.u n ,
.M FromDump n ,
.M ToDump n ,
.M tcpdump 1 ,
.M InfiniteSource n
'
.SH AUTHOR
.na
Eddie Kohler, kohler@cs.ucla.edu
.br
http://www.pdos.lcs.mit.edu/click/
'