.TH sane\-backend_conf 5 "12 jun 2019" "" "SANE Scanner Access Now Easy"
.IX sane\-backend_conf
.\"
.\" run doc/sane-backend_conf.man thru doc Makefile to get final man page
.\"
.\"   (cd doc; rm -f sane-backend_conf.5 ; gmake sane-backend_conf.5 )
.\"
.\"   nroff -man doc/sane-backend_conf.5 >doc/sane-backend_conf.txt
.\"
.\"   troff -man -Tpost doc/sane-backend_conf.5 \\
.\"   | /usr/lib/lp/postscript/dpost >doc/sane-backend_conf.5.ps
.\"
.\"
.SH NAME
sane\-backend_conf \- SANE <backend>.conf file description and format
.PP

.SH DESCRIPTION
.SS Introduction
Each backend has a default
.I <backend>.conf
file.
Probably built automatically from the source file
.IR <backend>.conf.in .
.PP
This man page discusses in general
terms how a sane backend
.I <backend>.conf
file is processed by sane sanei.
It is up to each sane backend to document
how it uses the data from its' own
.I <backend>.conf
file when they are passed to the backend
.B attach
function.
Unfortunately many do not or do it poorly.
.PP
There are two reasonable places for a backend
to document lines in its'
.I <backend>.conf
file.
First in the backend man page.
Second as comments directly in the
.I <backend>.conf
file via the
.I <backend>.conf.in
source file.
.PP
The primary purpose of the
.I <backend>.conf
file is for a sane-frontend
to identify and attach all
available (one or more)
scanners to the appropriate sane system backend.
.PP
But a secondary purpose is provided to
parse and set operational parameters using
"opt_name-value pair" option lines in the
.I <backend>.conf
file associated with scanner.
This feature, if exploited by a backend,
allows a user to alter the pre-configured
and compiled in, default settings for the
scanner without having to enter them on
the sane-frontend command line.
In addition the backend designer/coder is not
required to provide any additional backend code
beyond enabling the feature.
.PP
Truly a nice feature, but unused by most backends.
.PP
Usually a backend will explicitly reject the
option setting feature.
As a consequence each and every non-comment
line in the
.I <backend>.conf
file will be passed to the backends
.B attach
function.
What the backend
.B attach
function does with these data
is entirely up to the backend.
(see EXAMPLES section).
.PP

.SS backend.conf Processing Details
.I sanei/sanei_config.c
provides the function
.B sanei_configure_attach
that searches for, opens, reads and
parses the first
.I <backend>.conf
file found via the default search path ".:/opt/csw/etc/sane.d"
or via an alternate search path defined in envvar
\fBSANE_CONFIG_DIR\fP (see ENVIRONMENT section).
The primary purpose is to
get 1 or more scanner device ids
and pass each id to the backends
.B attach
function.
.PP

If the sane-backend implements the
option setting feature function
.B sanei_configure_attach
parses each "opt_name-value pair"
line extracting "opt_name" and "value".
It then assigns "value" to "opt_name" just as
if the "opt_name" and "value" had been
entered on the sane-frontend command line.
.PP

If the backend rejects the option setting feature
(version 1.0.27git and prior) function
.B sanei_configure_attach
simply passes the parsed word list from each
non-blank, non-comment line in the
.I <backend>.conf
file to the backends
.B attach
function.
This happens even with recognized "opt_name-value pair"
lines (see FILE FORMAT section).
This is probably not what the backend designer
had in mind, but it is out of their control
since a user is free to edit a
.I backend.conf
file at will.
.PP
In addition, there is no user notification
or other diagnostic mechanism in the
.B sanei_configure_attach
function to alert the user that the
.I backend.conf
file is (or at least appears to be) inconsistent with
with the backends declared operational strategy.
.PP
At best, setting the debug envvar
.B SANE_DEBUG_SANEI_CONFIG
will only show the word list being passed
to the backend
.B attach
function, without any mention that the backend
does not support the "opt_name-value pair" option lines
is recognized as an option line.
.PP
To observe how the backend is handling
the data being passed to its'
.B attach
function set the backend debug envvar
\fBSANE_DEBUG_<backend>\fP.
Do this especially if scanning is failing
(see EXAMPLES section an example of diagnostics).
.PP
.sp 4
.SH "FILE FORMAT"
In general a
.I <backend>.conf
file contains lines that may be comment lines,
blank lines or data lines (e.g. lines
containing one or more whitespace delimited words).
Blank or whitespace only lines and lines
optionally starting with whitespace
followed by the '#' character will
be ignored and discarded when read.
Comments are NOT supported data lines.
If present they will be parsed as
words and included in the space delimited
word list and passed on to the backends'
.B attach
function.    
.PP
Data lines are formed by whitespace delimited words:
.PP
.nf
.RS 5
[ <whitespace> ] \fBword_chars\fP [ <whitespace> word_chars ... ]
.PP
.RE
.fi
where
.RS 5
leading <whitespace> is optional.
.PP
\fBword_chars\fP are printable ascii chars (possibly utf-8).
.PP
additional <whitespace> delimited words are optional.
.RE
.PP
An "opt_name-value pair" option line format is:
.PP
.RS 5
.nf
[ \fBoption\fP ] <whitespace> \fBopt_name\fP <whitespace> [ \fBvalue\fP ]
.PP
.RE
.fi
where
.RS 5
the word \fBoption\fP is actually optional,
but if present must be lower case and may be
preceded by whitespace.
.PP
\fBopt_name\fP is defined by the backend if the
\fI<backend>.conf\fP option line feature is implemented.
.PP
\fBvalue\fP may be optional depending on the
\fBopt_name\fP type as defined by the backend.
.RE
.PP
NB: \fBvalue\fP is NOT checked for validity before
assignment to \fBopt_name\fP,
as a result it is possible
to cause seg faults and other fatal errors
with a mis-configured
.I <backend>.conf
file.
.PP
If a backend does NOT implement the
"opt_name-value pair" option line feature the
.I sanei/sanei_config.c
.B sanei_configure_attach
function simply parses each
.I <backend>.conf
data line into a list of space delimited
words and passes the word list to the backends
.B attach
function.
It is incumbent on a backends
.B attach
function to handle the data appropriately.
.PP

.SH EXAMPLES
.SS Man Page Well Done
The sane
.B "test"
backend (\fBsane-test(5)\fP)
implements the
.I <backend>.conf
option line feature for a large list of
.BR "opt_name" s
and associated
.BR value s
and documents it very well.
Refer to file
.I backend/test.conf
and man page
.B sane\-test(5)
for specifics.
.PP

.SS "Use Case: WTH?"
.PP
Your brand new scanner has arrived but the sane-backend
for it defaults to A4 paper and being in northamerica
most paper is USLetter.
So you
.IP a) 3
rtfm for sane-<backend>.5. YES! option lines are supported.
.IP b)
so per the rtfm, you insert the following two lines into
.I ./<backend>.conf
just after the line that identifies your Canon LiDE 200 scanner
(e.g usb 0x04a9 0x1905)
    option x 216
    option y 280
.PP
And run another scan.
No joy, WTH?
The scan still defaults to A4 paper dimensions.
So you set
.B SANE_DEBUG_SANEI_CONFIG
= 4 and
.B SANE_DEBUG_<backend>
= 3 on the same command line and
run the scan again:
.\" .sp 4 \" push following to new page
.PP
.ft CB \" courier 7 point
.ps 7
.nf
.na
   $ ( SANE_DEBUG_SANEI_CONFIG=4  SANE_DEBUG_GENESYS=3 \\
   ./frontend/scanimage --format png > usletter_dims.png )
 1 [sanei_debug] Setting debug level of sanei_config to 4.
 2 [sanei_config] sanei_config_open: attempting to open `./dll.conf'
 3 [sanei_config] sanei_config_open: attempting to open `/opt/csw/etc/sane.d/dll.conf'
 4 [sanei_config] sanei_config_open: using file `/opt/csw/etc/sane.d/dll.conf'
 5 [sanei_config] sanei_config_open: attempting to open `./dll.aliases'
 6 [sanei_config] sanei_config_open: attempting to open `/opt/csw/etc/sane.d/dll.aliases'
 7 [sanei_config] sanei_config_open: could not find config file `dll.aliases'
 8 [sanei_debug] Setting debug level of genesys to 3.
 9 [genesys] SANE Genesys backend version 1.0 build 2511 from sane-backends 1.0.27git
10 [genesys] SANE Genesys backend built with libusb
11 [sanei_config] sanei_configure_attach: start
12 [sanei_config] sanei_config_open: attempting to open `./genesys.conf'
13 [sanei_config] sanei_config_open: using file `./genesys.conf'
14 [sanei_config] sanei_configure_attach: trying to attach with 'usb 0x04a9 0x1905'
15 [sanei_config] sanei_configure_attach: trying to attach with 'option x 216'
16 [genesys] attach: couldn't open device `option x 216': Invalid argument
17 [genesys] attach_one_device: Invalid argument
18 [sanei_config] sanei_configure_attach: trying to attach with 'option y 280'
19 [genesys] attach: couldn't open device `option y 280': Invalid argument
20 [genesys] attach_one_device: Invalid argument
21 [sanei_config] sanei_configure_attach: exit
22 [sanei_config] sanei_configure_attach: start
23 [sanei_config] sanei_config_open: attempting to open `./genesys.conf'
24 [sanei_config] sanei_config_open: using file `./genesys.conf'
25 [sanei_config] sanei_configure_attach: trying to attach with 'usb 0x04a9 0x1905'
26 [sanei_config] sanei_configure_attach: trying to attach with 'option x 216'
27 [genesys] attach: couldn't open device `option x 216': Invalid argument
28 [genesys] attach_one_device: Invalid argument
29 [sanei_config] sanei_configure_attach: trying to attach with 'option y 280'
30 [genesys] attach: couldn't open device `option y 280': Invalid argument
31 [genesys] attach_one_device: Invalid argument
32 [sanei_config] sanei_configure_attach: exit
33 [sanei_config] sanei_config_open: attempting to open `./net.conf'
34 [sanei_config] sanei_config_open: attempting to open `/opt/csw/etc/sane.d/net.conf'
35 [sanei_config] sanei_config_open: using file `/opt/csw/etc/sane.d/net.conf'
NOTE: Line numbers added for reference.
.PP
.ad
.fi
Notice lines 11-21 and 22-32.
.br
The sequence happens twice because the scanner
device to use (e.g. -d <DEVICE> is
not listed on the command line (see \fBscanimage(1)\fP).
Why this second pass is needed is unclear,
but it does not occur when -d <DEVICE> is
included on command line.
.PP
Referring to lines 15, 16, and lines 18, 19.
.br
.B sanei_configure_attach
parses the "opt_name-value pair" option data
and passes the word list to the backends
.B attach
function, which, in this case, attempts to
use the data as a device id and tries
to open it.
This fails but nothing fatal to the program
occurs and the next .conf line is processed similarly.
.PP
Conclusively, this backend does \fBNOT\fP support
the "opt_name-value pair" setting feature
regardless of what the sane-<backend>.5
(i.e. sane-genesys.5) indicates.
But at least it is not crashing!
.PP
.SS How To Fix This Issue
What can you do to avoid having to enter
USLetter dimensions the command line
each and every time you run a scan?
(ordered by decreasing effort but increasing
out of pocket expense):
.RS 3
.IP 1) 3
hack the backend and implement the at
runtime "opt_name-value pair" option
setting features you want and need
and re-build.
.IP 2) 3
hack the backend \fI*_low.c\fP file that sets
the scanner model device defaults and re-build.
.IP 3) 3
use a more advanced frontend that supports
pre-defined options.
.IP 4) 3
write a scanimage wrapper script that presets
the various objectionable defaults.
.IP 5) 3
get a scanner that uses a more user friendly
backend.
.RE 3
.PP
.SS "Suggested Man Page Change/Improvement"
If you come across a backend with the
.I <backend>.conf
option line feature inadequately documented
either on the sane-<backend>.5 man page
or with a lack of commentary in the
.I <backend>.conf
file you are encouraged to help
improve the documentation
by, at the very least, notifying
the sane-devel people or better yet,
by submitting suggested changes to
\fBsane-devel@alioth-lists.debian.net\fP.
.PP
.SS Recommended Change: \fIdoc/sane-genesys.man\fP
As shown above the genesys backend man page
(for sane-backend version 1.0.27git and prior)
(file \fIdoc/sane-genesys.man\fP) is in need of
improvement/change.
.PP
In section "CONFIGURATION" the man page explicitly states:
.PP
.RS
\fBThe file can also contain option lines.\fP
.RE
.PP
That sentence is, at best, misleading,
and arguably just wrong, as demonstrated in
the above diagnostic output.
.PP
Recommend the sentence be changed to be something like:
.RS
.ll 55
.PP
\fBThe file may include option lines, but they
will have no effect and will be silently ignored.\fP
.RE
.PP
It would also be good to add a comment line to the
.I ./backend/genesys.conf.in
source file indicating that "opt_name-value pair" option lines
are unsupported.
Just a thought.
.PP
.SH ENVIRONMENT
.TP
.B SANE_CONFIG_DIR
.RS
This environment variable specifies the
search path for the backend configuration file.
Under UNIX, the directories are
separated by a colon (`:'),
under OS/2 (e.g. dossy heritage systems),
they are separated by a semi-colon (`;').
.PP
If envvar
.B SANE_CONFIG_DIR
is not set,
the default search path is:
.RS
1) the current working directory (".")
.br
.nf
2) the compiled in CONFIGDIR ("/opt/csw/etc/sane.d")
.fi
.RE
.PP
If envvar
.B SANE_CONFIG_DIR
ends with the directory separator character,
(e.g. ':' or ';') then the default directories
will also be searched after the explicitly
specified directory list.
.PP
For example, setting
.B SANE_CONFIG_DIR
to "/tmp/config:" would result in directories
"/tmp/config", ".", and "/opt/csw/etc/sane.d"
being searched (in that order).
.RE
.PP
.SH FILES
.TP \w'<backend>.conf.in'u+2n
.I <backend>.conf
wherever it is found.
.TP
.I <backend>.conf.in
source file for your scanner.
.br
.TP
.I backend/test.conf
for reference.
.PP
.SH "SEE ALSO"
.B scanimage(1),
.B sane(7),
\fBsane-<backend>(5)\fP for your scanner.
.PP

.SH AUTHOR
strawman hack by r a schmied <ras ampersand acm dot org>
.br
send changes/comments to \fBsane-devel@alioth-lists.debian.net\fP

.PP
.\" $Id: sane-backend_conf.man,v 1.8 2019/06/18 22:42:03 ras Exp ras $
