.TH usbmodules 8 "12 June 2001" "usbutils-0.70" "Linux USB Utilities"
.IX usbmodules
.SH NAME
usbmodules \- List kernel driver modules available for a plugged
in USB device
.SH SYNOPSIS
.B usbmodules
.RB [ "--device " /proc/bus/usb/NNN/NNN 
.RB | " --product " xx/xx/xx " --type " dd/dd/dd " --interface " dd/dd/dd ]
.RB [ "--check " modulename ]
.RB [ --help ]
.RB [ "--mapfile " pathname ]
.RB [ "--version " pathname ]
.SH DESCRIPTION
.B usbmodules
lists driver modules that may be
able to manage interfaces on
currently plugged in USB devices.
.B usbmodules
may be used by /sbin/hotplug or one of its agents (normally
.IR /etc/hotplug/usb.agent )
when USB devices are "hot plugged" into the system.  This can be done by
the following Bourne shell syntax:
.IP
	for module in $(usbmodules --device $DEVICE) ; do
.IP
		modprobe -s -k "$module"
.IP
	done
.PP
or
.IP
	for module in $(usbmodules --product $PRODUCT --type $TYPE --interface $INTERFACE) ; do
.IP
		modprobe -s -k "$module"
.IP
	done
.PP
The DEVICE environment variable is passed from the kernel to /sbin/hotplug
during USB hotplugging if the kernel was configured using
.I usbdevfs.
The environment variables PRODUCT, TYPE and INTERFACE are set when
/sbin/hotplug is called during hotplugging.
.B usbmodules
can operate with both configurations.
.PP
When a USB device is removed from the system, the Linux kernel will
decrement a usage count on USB driver module.  If this count drops
to zero (i.e., there are no clients for the USB device driver), then the
.B modprobe -r
process that is normally configured to run from cron every few minutes
will eventually remove the unneeded module.
.PP
.SH OPTIONS
.TP
.BI "--check " modulename
Instead of listing the relevant modules, just exit with code 0 (success)
if the given module's exported USB ID patterns matches.  Otherwise,
return failure.  
.B usbmodules
emits no output either way.
.TP
.BI "--device " /proc/bus/usb/MMM/NNN
Selects which device
.B usbmodules
will examine.  The argument is mandatory unless
.B --procuct
,
.B --type
and
.B --interface
are used together.
.TP
.BI "--product " xx/xx/xx " --type " dd/dd/dd " --interface " dd/dd/dd
Alternative way to select the device
.B usbmodules
will examine. These arguments are mandatory unless
.B --device
is given.
.TP
.B --help, -h
Print a help message
.TP
.BI "--mapfile " /etc/hotplug/usb.handmap
Use the specified file instead of the
/lib/modules/.../modules.usbmap file
corresponding to the running kernel.
.TP
.B --version
Identifies the version of
.I usbutils
this tool was built with.
.SH FILES
.TP
.B /lib/modules/<kernel-version>/modules.usbmap
This file is automatically generated by
.B depmod,
versions 2.4.2 and later, and is used by
.B usbmodules
to determine which modules correspond to which USB ID's.
.TP
.B /proc/bus/usb
An optional interface to USB devices provided by Linux kernels with
versions of the 2.4 USB support. Contains per-bus subdirectories
with per-device files (offering a usermode driver API as well
as access to device and configuration descriptors), a
.I devices
file containing a list of all USB devices, and a 
.I drivers
file listing USB device drivers known to the USB subsystem.

.SH SEE ALSO
.BR lsusb (8),
.I http://linux-hotplug.sourceforge.net

.SH AUTHOR
.B usbmodules
was written by Adam J. Richter <adam@yggdrasil.com>, and is
based partly on
.B
lsusb,
which was written by Thomas Sailer <sailer@ife.ee.ethz.ch>.

.\" Code and documentation updated by David Brownell.


.SH COPYRIGHT
.B usbmodules
is copyright 2000, Yggdrasil Computing, Incorporated, and
copyright 1999, Thomas Sailer.
.B usbmodules
may
may be copied under the terms and conditions of version 2 of the GNU
General Public License as published by the Free Software Foundation
(Cambrige, Massachusetts, United States of America).