Mentioned control messages, usbfs, and more methods for permission adjustment.

Henning Meier-Geinitz <henning@meier-geinitz.de>

doc/sane-usb.man

@@ -1,4 +1,4 @@
-.TH sane-scsi 5 "03 Jul 2002"
+.TH sane-scsi 5 "06 Jul 2002"
 .IX sane-usb
 .SH NAME
 sane-usb - USB configuration tips for SANE
@@ -21,15 +21,15 @@ Direct access to the USB device files to access kernel scanner drivers. Used
 by the epson backend.
 .PP
 This manual page describes the access of USB scanners over the sanei_usb
-interface. For point two and three of this list have a look at the backends'
+interface. For the backends using direct kernel or libusb access have a look
-manual pages for details.
+at their manual pages for details.
 .PP
-Two methods for accessing USB devices are used: direct access using the kernel
+Two methods for accessing USB devices are used by sanei_usb: direct access
-scanner driver and access over libusb. sanei_usb tries both methods, if they
+using the kernel scanner driver and access over libusb. sanei_usb tries both
-are available. Currently USB access is only tested for Linux (kernel, libusb),
+methods, if they are available. Currently USB access is only tested for Linux
-FreeBSD (kernel) and OpenBSD (kernel). Libusb access should also work on
+(kernel, libusb), FreeBSD (kernel) and OpenBSD (kernel). Libusb access should
-NetBSD and Mac OS X (Darwin) but hasn't been tested yet. For installation
+also work on NetBSD and Mac OS X (Darwin) but hasn't been tested yet. For
-issues, also check the @DOCDIR@/README.platform files.
+installation issues, also check the @DOCDIR@/README.platform files.
 .PP
 Most backends will detect USB scanners automatically using "usb" configuration
 file lines. This method allows to identify scanners by the USB vendor and
@@ -87,12 +87,15 @@ scanners).
 
 .SH WHEN TO USE WHICH ACCESS METHOD
 Generally speaking, if your scanner works with one method, there is no need
-toi switch to the other one. Libusb is the more general approach and will be
+to switch to the other one.
-able to access any scanner. Also, it supports more platforms. However, the
+.PP
-library must be available and installed on the system and setting permissions
+Libusb is the more general approach and will be able to access any
-isn't easy at least on Linux. Libusb acces isn't tested very
+scanner. Also, it supports more platforms. However, the library must be
-well. Autodetecting scanners with the kernel access method only works with
+available and installed on the system and setting permissions isn't easy at
-newer Linux kernels.
+least on Linux. Libusb access isn't tested very well.
+.PP
+Autodetecting scanners and using USB control messages with the kernel access
+method only works with recent (>=v2.4.12) Linux kernels.
 
 .SH KERNEL SCANNER DRIVER TIPS
 Ensure that the access permissions for the USB device are set appropriately.
@@ -122,19 +125,39 @@ details look at @DOCDIR@/README.openbsd.
 .SH LIBUSB ACCESS TIPS
 Libusb can only access your scanner if it's not claimed by the kernel scanner
 driver. If you want to use libusb, unload the kernel driver (e.g. rmmod
-scanner under Linux).
+scanner under Linux). For Linux, your kernel needs support for the USB
+filesystem (usbfs) and that filesystem must be mounted. That's done
+automatically, if /etc/fstab contains a line like this:
+.PP
+.RS
+none /proc/bus/usb usbfs defaults  0  0
+.RE
 .PP
 The permissions for the device files used by libusb must be ajusted for user
 access. Otherwise only root can use SANE devices. For
 .IR Linux ,
-the devices are
+the devices are located in /proc/bus/usb/. There are directories named
-located in /proc/bus/usb/. There are directories named e.g. "001" (the bus
+e.g. "001" (the bus name) containing files "001", "002" etc. (the device
-name) containing files "001", "002" etc. (the device files). The right device
+files). The right device files can be found out by running scanimage -L as
-files can be found out by running scanimage -L as root. Setting permissions
+root. Setting permissions with "chmod" is not permanent, however. They will be
-with "chmod" is not permanent, however. They will be resetted after reboot or
+resetted after reboot or replugging the scanner. It's also possible to mount
-replugging the scanner. For the 
+the usbfs with the option "devmode=0666", e.g. by using the following line in
+/etc/fstab:
+.PP
+.RS
+none /proc/bus/usb usbfs defaults,devmode=0666  0  0
+.RE
+.PP
+However, this way everyone has access to all USB devices. Another way to set
+permissions is to use the hotplug utilities
+(http://linux-hotplug.sourceforge.net/), which support dynamic setting of
+access permissions. Last, the frontends can be run as root. However, that's
+not recommended for security reasons.
+.PP
+For the
 .IR BSDs,
-the device files are named /dev/ugen*.
+the device files are named /dev/ugen*. Use chmod to apply appropriate
+permissions.
 
 .SH ENVIRONMENT
 .TP