SANE Scanner Access Now Easy                 sane-backend_conf(5)

NAME
     sane-backend_conf - SANE <backend>.conf file description and
     format

DESCRIPTION
  Introduction
     Each backend has a default  <backend>.conf  file.   Probably
     built automatically from the source file <backend>.conf.in.

     This  man page discusses in general terms how a sane backend
     <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 <backend>.conf file when they are passed to the  backend
     attach function.  Unfortunately many do not or do it poorly.

     There  are  two  reasonable places for a backend to document
     lines in its' <backend>.conf file.  First in the backend man
     page.   Second  as  comments  directly in the <backend>.conf
     file via the <backend>.conf.in source file.

     The primary purpose of the  <backend>.conf  file  is  for  a
     sane-frontend  to  identify and attach all available (one or
     more) scanners to the appropriate sane system backend.

     But a secondary purpose is provided to parse and set  opera-
     tional  parameters  using "opt_name-value pair" option lines
     in the <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.

     Truly a nice feature, but unused by most backends.

     Usually a backend will explicitly reject the option  setting
     feature.   As  a consequence each and every non-comment line
     in the <backend>.conf file will be passed  to  the  backends
     attach function.  What the backend attach function does with
     these data is entirely up to  the  backend.   (see  EXAMPLES
     section).

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

SunOS 5.10           Last change: 12 jun 2019                   1

SANE Scanner Access Now Easy                 sane-backend_conf(5)

     If  the  sane-backend  implements the option setting feature
     function 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.

     If  the  backend rejects the option setting feature (version
     1.0.27git and prior) function sanei_configure_attach  simply
     passes the parsed word list from each non-blank, non-comment
     line in the <backend>.conf file to the backends attach func-
     tion.   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  backend.conf
     file at will.

     In addition, there is no user notification or other diagnos-
     tic mechanism  in  the  sanei_configure_attach  function  to
     alert  the  user  that the backend.conf file is (or at least
     appears to be) inconsistent with with the backends  declared
     operational strategy.

     At  best,  setting  the debug envvar SANE_DEBUG_SANEI_CONFIG
     will only show the word list being  passed  to  the  backend
     attach  function,  without any mention that the backend does
     not support the "opt_name-value pair" option lines is recog-
     nized as an option line.

     To observe how the backend is handling the data being passed
     to  its'  attach  function  set  the  backend  debug  envvar
     SANE_DEBUG_<backend>.   Do  this  especially  if scanning is
     failing (see EXAMPLES section an example of diagnostics).

FILE FORMAT
     In general a <backend>.conf file contains lines that may  be
     comment  lines,  blank  lines or data lines (e.g. lines con-
     taining 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'
     attach function.

     Data lines are formed by whitespace delimited words:

          [ <whitespace> ] word_chars [ <whitespace> word_chars ... ]

     where
          leading <whitespace> is optional.

SunOS 5.10           Last change: 12 jun 2019                   2

SANE Scanner Access Now Easy                 sane-backend_conf(5)

          word_chars are printable ascii chars (possibly utf-8).

          additional <whitespace> delimited words are optional.

     An "opt_name-value pair" option line format is:

          [ option ] <whitespace> opt_name <whitespace> [ value ]

     where
          the word option is actually optional,  but  if  present
          must be lower case and may be preceded by whitespace.

          opt_name  is  defined  by  the  backend  if  the <back-
          end>.conf option line feature is implemented.

          value may be optional depending on the opt_name type as
          defined by the backend.

     NB:  value  is NOT checked for validity before assignment to
     opt_name, as a result it is possible to cause seg faults and
     other  fatal  errors  with  a  mis-configured <backend>.conf
     file.

     If a backend does NOT implement  the  "opt_name-value  pair"
     option  line  feature the sanei/sanei_config.c sanei_config-
     ure_attach function simply parses each  <backend>.conf  data
     line  into  a  list  of space delimited words and passes the
     word list to the backends attach function.  It is  incumbent
     on  a  backends attach function to handle the data appropri-
     ately.

EXAMPLES
  Man Page Well Done
     The sane test backend (sane-test(5)) implements  the  <back-
     end>.conf  option line feature for a large list of opt_names
     and associated values and documents it very well.  Refer  to
     file   backend/test.conf   and  man  page  sane-test(5)  for
     specifics.

  Use Case: WTH?
     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

     a) rtfm for sane-<backend>.5. YES!  option  lines  are  sup-
        ported.

     b) so  per the rtfm, you insert the following two lines into
        ./<backend>.conf just after the line that identifies your
        Canon LiDE 200 scanner (e.g usb 0x04a9 0x1905)
            option x 216
            option y 280

SunOS 5.10           Last change: 12 jun 2019                   3

SANE Scanner Access Now Easy                 sane-backend_conf(5)

     And run another scan.  No joy, WTH?  The scan still defaults
     to A4 paper dimensions.  So you set  SANE_DEBUG_SANEI_CONFIG
     =  4  and  SANE_DEBUG_<backend> = 3 on the same command line
     and run the scan again:

        $ ( 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.

     Notice lines 11-21 and 22-32.
     The sequence happens twice because the scanner device to use
     (e.g.  -d  <DEVICE>  is  not listed on the command line (see
     scanimage(1)).  Why this second pass is needed  is  unclear,
     but  it  does not occur when -d <DEVICE> is included on com-
     mand line.

SunOS 5.10           Last change: 12 jun 2019                   4

SANE Scanner Access Now Easy                 sane-backend_conf(5)

     Referring to lines 15, 16, and lines 18, 19.
     sanei_configure_attach  parses  the  "opt_name-value   pair"
     option  data and passes the word list to the backends 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  pro-
     cessed similarly.

     Conclusively,  this  backend does NOT 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!

  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):

        1) hack   the   backend  and  implement  the  at  runtime
           "opt_name-value pair" option setting features you want
           and need and re-build.

        2) hack  the  backend  *_low.c file that sets the scanner
           model device defaults and re-build.

        3) use a more advanced frontend that supports pre-defined
           options.

        4) write a scanimage wrapper script that presets the var-
           ious objectionable defaults.

        5) get a scanner that uses a more user friendly backend.

  Suggested Man Page Change/Improvement
     If you come across a backend with the <backend>.conf  option
     line   feature   inadequately   documented   either  on  the
     sane-<backend>.5 man page or with a lack  of  commentary  in
     the  <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 sane-devel@alioth-lists.debian.net.

  Recommended Change: doc/sane-genesys.man
     As shown above the genesys backend man page (for  sane-back-
     end version 1.0.27git and prior) (file doc/sane-genesys.man)
     is in need of improvement/change.

     In section "CONFIGURATION" the man page explicitly states:

          The file can also contain option lines.

SunOS 5.10           Last change: 12 jun 2019                   5

SANE Scanner Access Now Easy                 sane-backend_conf(5)

     That sentence is, at best,  misleading,  and  arguably  just
     wrong, as demonstrated in the above diagnostic output.

     Recommend the sentence be changed to be something like:

          The  file  may include option lines, but they will have
          no effect and will be silently ignored.

     It would also be good to add a comment line to  the  ./back-
     end/genesys.conf.in  source  file indicating that "opt_name-
     value pair" option lines are unsupported.  Just a thought.

ENVIRONMENT
     SANE_CONFIG_DIR
          This environment variable specifies the search path for
          the backend configuration file.  Under UNIX, the direc-
          tories are separated by a colon (`:'), under OS/2 (e.g.
          dossy  heritage systems), they are separated by a semi-
          colon (`;').

          If envvar  SANE_CONFIG_DIR  is  not  set,  the  default
          search path is:
               1) the current working directory (".")
               2) the compiled in CONFIGDIR ("/opt/csw/etc/sane.d")

          If envvar SANE_CONFIG_DIR ends with the directory sepa-
          rator character, (e.g. ':' or  ';')  then  the  default
          directories  will also be searched after the explicitly
          specified directory list.

          For example, setting SANE_CONFIG_DIR to  "/tmp/config:"
          would  result  in  directories  "/tmp/config", ".", and
          "/opt/csw/etc/sane.d" being searched (in that order).

FILES
     <backend>.conf     wherever it is found.

     <backend>.conf.in  source file for your scanner.

     backend/test.conf  for reference.

SEE ALSO
     scanimage(1), sane(7), sane-<backend>(5) for your scanner.

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

SunOS 5.10           Last change: 12 jun 2019                   6