Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Sane(3)		      User Contributed Perl Documentation	       Sane(3)

       Sane - Perl extension for the SANE (Scanner Access Now Easy) Project

	 use Sane;
	 my @devices = Sane->get_devices;
	 my $device = Sane::Device->open($devices[0]->{name});
	 my $param = $device->get_parameters;
	 my ($data, $len) = $device->read ($param->{bytes_per_line});
	 print $fh $data;

       Perl bindings for the SANE (Scanner Access Now Easy) Project.  This
       module allows you to access SANE-compatible scanners in a Perlish and
       object-oriented way, freeing you	from the casting and memory management
       in C, yet remaining very	close in spirit	to original API.

       The Sane	module allows a	Perl developer to use SANE-compatible
       scanners.  Find out more	about SANE at <>.

       Most methods set	$Sane::STATUS, which is	overloaded to give either an
       integer as dictated by the SANE standard, or the	the corresponding
       message,	as required.

       Returns an array	with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions:


       Returns an scalar with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions
       combined	as per the Perl	version	numbering, i.e.	sane 1.0.19 gives
       1.000019. This allows simple version comparisons.

       This function can be used to query the list of devices that are
       available.  If the function executes successfully, it returns a array
       of hash references with the devices found.  The returned	list is
       guaranteed to remain valid until	(a) another call to this function is
       performed or (b)	a call to sane_exit() is performed.  This function can
       be called repeatedly to detect when new devices become available.

       If argument local_only is true, only local devices are returned
       (devices	directly attached to the machine that SANE is running on).  If
       it is false, the	device list includes all remote	devices	that are
       accessible to the SANE library.

	 my @devices = Sane->get_devices;
	 if ($Sane::STATUS == SANE_STATUS_GOOD)	{
	  print	"Name: $devices[0]->{name}\n";
	  print	"Vendor: $devices[0]->{vendor}\n";
	  print	"Model:	$devices[0]->{model}\n";
	  print	"Type: $devices[0]->{type}\n";

       This function is	used to	establish a connection to a particular device.
       The name	of the device to be opened is passed in	argument name.	If the
       call completes successfully, a Sane::Device object is returned.	As a
       special case, specifying	a zero-length string as	the device requests
       opening the first available device (if there is such a device).

	 my $device = Sane::Device->open($device_name);

       This function is	used to	access option descriptors.  The	function
       returns a hash reference	with the option	descriptor for option number n
       of the Sane::Device object.  Option number 0 is guaranteed to be	a
       valid option.  Its value	is an integer that specifies the number	of
       options that are	available for the Sane::Device object (the count
       includes	option 0). If n	is not a valid option index, the function

	 my $option = $device->get_option_descriptor($n);
	 if ($Sane::STATUS == SANE_STATUS_GOOD)	{
	  print	"Name: $option->{name}\n";
	  print	"Name: $option->{title}\n";
	  print	"Name: $option->{desc}\n";
	  print	"Name: $option->{type}\n";
	  print	"Name: $option->{unit}\n";
	  print	"Name: $option->{cap}\n";
	  print	"Name: $option->{max_values}\n";
	  print	"Name: $option->{constraint_type}\n";

       The contents of the name, title,	desc, type, unit, cap and
       constraint_type are as the C API	description
       (<>). There is a	further	constraint key
       that either contains an array with the possible option values, or a
       hash with max, min, and quant keys.

       The max_values key replaced the size key	in the C API, and contains the
       maximum number of values	that the option	may contain.

       Returns the current value of the	selected option.

	 my $value = $device->get_option($n);
	 if ($Sane::STATUS == SANE_STATUS_GOOD)	{
	  print	"value:	$value\n";

       For $option->{max_values} > 1, $value is	a reference to an array.

       Commands	the selected device to automatically select an appropriate
       value.  This mode remains effective until overridden by an explicit
       set_option request.


       Sets the	selected option, returning flags in $info, which are described
       in the C	API (<>).

	 $orig = $device->get_option($n);
	 $info = $device->set_option($n, $value);
	 if ($info & SANE_INFO_INEXACT)	{
	  $value = $device->get_option($n);
	  print	"rounded value of $opt->{name} from $orig to $value\n";

       For $option->{max_values} > 1, $value can be a reference	to an array.

       This function is	used to	obtain the current scan	parameters.  The
       returned	parameters are guaranteed to be	accurate between the time a
       scan has	been started (Sane::Device->start() has	been called) and the
       completion of that request. Outside of that window, the returned	values
       are best-effort estimates of what the parameters	will be	when
       Sane::Device->start() gets invoked. Calling this	function before	a scan
       has actually started allows, for	example, to get	an estimate of how big
       the scanned image will be.

	 $param	= $device->get_parameters;
	 if ($Sane::STATUS == SANE_STATUS_GOOD)	{
	  print	"format	$param->{format}\n";
	  print	"last_frame $param->{last_frame}\n";
	  print	"bytes_per_line	$param->{bytes_per_line}\n";
	  print	"pixels_per_line $param->{pixels_per_line}\n";
	  print	"lines $param->{lines}\n";
	  print	"depth $param->{depth}\n";

       Please see the C	documentation (<>) for
       details of the above values.

       This function initiates aquisition of an	image from the device


       This function is	used to	read image data	from the device	specified.
       The number of bytes returned in $buf is stored in $len.	A backend must
       set this	to zero	when a status other than SANE_STATUS_GOOD is returned.
       When the	call succeeds, the number of bytes returned can	be anywhere in
       the range from 0	to maxlen bytes.

	 $param	= $device->get_parameters;
	 $maxlen = $param->{bytes_per_line};
	 ($buf,	$len) =	$test->read ($maxlen);

       If this function	is called when no data is available, one of two	things
       may happen, depending on	the I/O	mode that is in	effect for the device.

       1. If the device	is in blocking I/O mode	(the default mode), the	call
       blocks until at least one data byte is available	(or until some error
       2. If the device	is in non-blocking I/O mode, the call returns
       immediately with	status SANE_STATUS_GOOD	and with $len set to zero.

       The I/O mode of the device can be set via a call	to

       This function is	used to	immediately or as quickly as possible cancel
       the currently pending operation of the device.


       This function can be called at any time (as long	as $device is valid)
       but usually affects long-running	operations only	(such as image is
       acquisition). It	is safe	to call	this function asynchronously (e.g.,
       from within a signal handler). It is important to note that completion
       of this operaton	does not imply that the	currently pending operation
       has been	cancelled. It only guarantees that cancellation	has been
       initiated. Cancellation completes only when the cancelled call returns
       (typically with a status	value of SANE_STATUS_CANCELLED).  Since	the
       SANE API	does not require any other operations to be re-entrant,	this
       implies that a frontend must not	call any other operation until the
       cancelled operation has returned.

       This function is	used to	set the	I/O mode of the	device.	The I/O	mode
       can be either blocking or non-blocking. If argument $bool is SANE_TRUE,
       the mode	is set to non-blocking mode, otherwise it's set	to blocking
       mode. This function can be called only after a call to
       Sane::Device->start() has been performed.

	 $device->set_io_mode ($bool);

       By default, newly opened	handles	operate	in blocking mode. A backend
       may elect not to	support	non-blocking I/O mode. In such a case the
       status value SANE_STATUS_UNSUPPORTED is returned. Blocking I/O must be
       supported by all	backends, so calling this function with	SANE_FALSE is
       guaranteed to complete successfully.

       This function is	used to	obtain a (platform-specific) file-descriptor
       for the device that is readable if and only if image data is available
       (i.e., when a call to Sane::Device->read() will return at least one
       byte of data).

	 $fd = $device->get_select_fd;

       This function can be called only	after a	call to	Sane::Device->start()
       has been	performed and the returned file-descriptor is guaranteed to
       remain valid for	the duration of	the current image acquisition (i.e.,
       until Sane::Device->cancel() or Sane::Device->start() get called	again
       or until	Sane::Device->read() returns with status SANE_STATUS_EOF).
       Indeed, a backend must guarantee	to close the returned select file
       descriptor at the point when the	next Sane::Device->read() call would
       return SANE_STATUS_EOF. This is necessary to ensure the application can
       detect when this	condition occurs without actually having to call

       A backend may elect not to support this operation. In such a case, the
       function	returns	with status code SANE_STATUS_UNSUPPORTED.

       Note that the only operation supported by the returned file-descriptor
       is a host operating-system dependent test whether the file-descriptor
       is readable (e.g., this test can	be implemented using select() or
       poll() under UNIX). If any other	operation is performed on the file
       descriptor, the behavior	of the backend becomes unpredictable.  Once
       the file-descriptor signals ``readable''	status,	it will	remain in that
       state until a call to sane_read() is performed. Since many input
       devices are very	slow, support for this operation is strongly
       encouraged as it	permits	an application to do other work	while image
       acquisition is in progress.

       This function is	a pure-Perl helper function to write a PNM header. It
       will fetch the current image settings using
       Sane::Device->get_parameters, if	they are not already provided, e.g.:



	$parm =	$device->get_parameters;
	$device->write_pnm_header ($fh,	$parm->{format},
					$parm->{lines},	$parm->{depth});

       The SANE	Standard Reference <> is a
       handy companion.	The Perl bindings follow the C API very	closely, and
       the C reference documentation should be considered the canonical

       Jeffrey Ratcliffe, <>

       Copyright (C) 2008--2012	by Jeffrey Ratcliffe

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.5 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.0			  2012-04-02			       Sane(3)


Want to link to this manual page? Use this URL:

home | help