saft logo Scanner Access For Tcl



Download / Install





saft - scanner acces for Tcl.


package require Tcl 8.5

package require saft ?0.1?

::saft::searchScanners ?commandPrefix?

::saft::listScannerInfo subcommand ?UID ?option? ?

::saft::startScan ?options? filename


saft is a scanning utility for Tcl that tries to provide a common interface to different scanning subsystems. Currently only Sane is supported.


::saft::searchScanners ?-command commandPrefix?

Search for connected scanners and collect information about the options each of them supports. These informations are saved interally and can be queried with ::saft::listScannerInfo.

Note that saft does not autodetect connection/disconnection of devices: ::saft::searchScanners needs to be called to make a new device available or to remove information about a disconnected device.

If the -command option is passed, the command runs in "nonblocking" mode. This means that the command will return immediately and arrange for commandPrefix to be invoked when the operation is completed. The result of the device search will be appended as one additional argument to commandPrefix. Whtout the -command option, the command returns only once the operation is complete ("blocking" mode). See also BLOCKING VS. NONBLOCKING INVOCATION below.

The command returns the result of the device search in blocking mode, empty string in nonblocking. The result is a list of device dictionaries, one for each device found (see DEVICE INFORMATION DICTIONARY below).

::saft::listScannerInfo subcommand ?UID ?option? ?

Retrieve various information about scanning devices, i.e. available devices, accepted values for options, defaults, etc.

This command returns internally saved information, which might not reflect the actual state of the system. If the system changed (e.g. new device plugged/unplugged), saft::searchScanners must be called before those changes can be seen with this command.

::saft::listScannerInfo will raise an error if it is called while searchScanners is running in the background. This is because information gotten while ::saft::searchScanners is running in the background might become invalid as soon as the search completes.

See the sections DEVICE INFORMATION and OPTIONS DICTIONARY for detailed information about the format of the dictionaries returned by this command.

Following subcommands are acceppted:

::saft::listScannerInfo default ?UID ?option? ?

With no additional arguments, returns a device dictionary describing the default scanning device. If no devices are present, or if ::saft::searchScanners has not been invoked yet, the dictionary will have empty strings as values for each key.

If an UID is provided, returns the defaults for scanner-specific options as an options dictionary.

If an option argument is passed (must be one of the scanner-specific options) the command returns the default for that option.

An empty string means that the option is not supported by the device.

::saft::listScannerInfo available ?UID ?option? ?

With no additional arguments, returns a list of device dictionaries. Each of these dictionaries describes one of the available scanning devices. If no devices are present, or if ::saft::searchScanners has not been invoked yet, returns an empty list.

If an UID is provided, provides all acceppted values for scanner-specific options in an options dictionary. For each option, this dictionary will contain a list of supported values.

If an option argument is passed (must be one of the scanner-specific options) the command returns a list containig the available values for that option.

An empty list means that the option is not supported by that specific device.

::saft::startScan ?options? filename

Start to scan an image and write it to filename. The path to the file must exist - no directories will be created.

This command can be invoked in "nonblocking" mode (providing a -command option) or in "blocking" mode (the default). In "nonblocking" mode, the command returns an empty string. In "blocking" mode it returns a list of dictionaries - one for each page scanned. Each dictionary contains the parameters used for the scan. More details about this dictionary can be found in the section SCAN INFO DICTIONARY. For details about "blocking" vs. "nonblocking" operation see BLOCKING VS. NONBLOCKING INVOCATION.

filename specifies where the scanned image will be written. Every occurrence of the sequence %N in filename will be substituted with an numeric index. See IMAGE FILE NUMBERS below.

::saft::startScan accepts a number of options to control the scanning operation. They can be split in two categories: device-dependent and device-independent ones. The device-independent options can always be used, no matter what device is used. They are:

If this option is specified, the command returns immediately and arranges commandPrefix to be invoked when the scanning of a page is complete. One argument will be appended to commandPrefix, a dictionary containig detailed information about the scan (see SCAN INFO DICTIONARY below). When scanning from an automatic document feeder, the command will be invoked once for every page scanned.

-device UID

Use scanner with identifier UID. If not specified, the default device will be used.

-maxpages number

When scanning from the automatic document feeder, scan at most number pages. Empty string or negative values mean no maximum set, i.e. scan util feeder is out of documents. Defaults to -1 (scan everything). Option is ignored when no automatic document feeder is used.

-overwrite boolean

If true, overwrite existing files when scanning. Default: false.

-startindex int

First index to use when output file(s) are numbered (see IMAGE FILE NUMBERS below).

Device-dependent options might or mith not be supported by a given device. The available and default values for these options vary with devices and platform. A list of valid values and defaults can be obtained with the ::saft::listScannerInfo command. For reliable behaviour, you MUST check the available values for these options before using them. Passing invalid values and using options that the device does not support, results in an error.

Color depth (mode) to use. descr is subsystem/scanner-specific, and must be one of the options listed by saft::getInformation

-format formatName

Image format to use. formatName is the standard extension of the desired image format (without the dot).

-resolution int

Resolution to use. If specified resolution is not supported, the nearest one is used.

-source source

Select the scan source (e.g. ADF, Flatbed).


The commands ::saft::searchScanners and ::saft::startScan can take quite a while to complete. If you need to keep your application responsive they can be used in "nonblocking" mode. Both commands accept a -command option. If this option is given, the command returns immediately. The return value is an empty string in this case. When the requested task is complete, the commandPrefix passed with -command will be invoked - with the result of the operation appended to it.

If no -command option is provided, the commands runs in "blocking" mode, i.e. they return only once the operation is complete. In this case the return value is the result of the operation.


An index can be added to the name of the scanned files, useful when scanning multiple pages with an automatic document feeder. This index will be increased for each successive page in one scan operation. The index is not remembered from one call to ::saft::startScan to the next.

An index will be added when at least one of the following occurs:


A scan request produces more than one page (ADF)


The option -startindex is provided


filename contains the sequence %N at least once

Every occurrence of the sequence %N in filename will be replaced with the index. %% will be substituted with a single ’%’, all other %* sequences - where * is any characther - will be ignored. The %N can be used in directory names too, but beware: the path must already exist!

If an index is needed but no ’%N’ can be found in the filename, the index will be placed at the end of the name of the file, before the extension (path/to/filename%N.ext).

If an index is required, but -startindex was not provided, index count starts with 1.


Information about scanners is passed as a dictionary with this these key/values:

A human readable (and understandable...) text description of the device. Typically vendor and model.

device devString

The OS-specific name for the device - e.g. ‘brother3:bus2;dev5’ under Sane/Linux. Nothe that, from one session to the other, this name can be different for the same actual device. Ergo, if you want to remember a specific device between sessions - for example to save a default scanner - don’t use devString! Use UID for this purpose.

UID identifier

A unique identifier for the device. The actual format of this identifier is not defined, but on a given subsystem/platform a device will always have the same UID.


Information about scanner-specific options is passed in a dictionary. This dictionary will have a key for every scanner-specific option, the corresponding value is either a list (supported values) or a single value (current setting, defaults).


A scan operation will produce a dictionary containig detailed information about options and parameters used for the scan. The values in this dictionary are the ones actually used, which are not necessarly equal to the ones passed to the command. The dictionary has these elements:

This key signals if everything went smoothly: it is strongly recommended to check code before doing anything with the other values. If there was a problem, they might be meaningless. These error codes (strings, actually) are meant to be interpreted at program level - they tell what went wrong. A human readable message is stored in errmsg. Possible values are:


Everything’s fine


Cannot write output file


No document available - nothing was scanned.


Device specified with -device option or default device not found or no scanners at all.


Problem with the platform-specific subsystem: missing dependency/unsupported version, other problem accessing device.

errmsg message

Error message in prosa. Empty string if command was sucessful.

colordepth depthString

Color depth used.

command commandPrefix

Command prefix passed.

device UID

UID of device that performed the scan

file fileName

The absolute and normalized path to the image file scanned.

format formatName

Image format used for output

lastpage boolean

If false, the scan operation will produce at least one more page. True signals the end of the scanning process.


Value of -maxpages passed.

pagecount int

The number of pages scanned so far.

resolution int

Resolution used for the scan

startindex int

If an index was substituted in the filename(s), the index of the first page. Empty string otherwise.

source scanSource

Scanner source used.


This is an early development release, so there are certainly many bugs and problems. Please report!

Please post bug reports, whishes, suggestions to the mailing list or the bugtracker on the saft project page at sourceforge:


scanimage(1) sane(7)


scan image scanner sane

Contact | Hosting: | Valid XHTML 1.0! | Last updated: May 2013