Sane(3)

💖 Sane(3) — the manual page, but make it make sense 💖

User Contributed Perl Documentation · this is the Sane(3) page, bestie. yes it's Perl. no, don't run. 🫶

okay so. scanners. actual hardware. and Perl is gonna talk to it. stay with me.

---

🌸 NAME 🌸

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

---

✨ SYNOPSIS ✨

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

---

🦋 ABSTRACT 🦋

Perl bindings for the SANE (Scanner Access Now Easy) Project. This module lets you talk to SANE-compatible scanners in a Perlish, object-oriented way, which means you get to skip all the casting and memory management that C makes you do, while still staying very close in spirit to the original API. literally the best of both worlds. 💅

---

💜 DESCRIPTION 💜

The Sane module lets a Perl developer use SANE-compatible scanners. Wanna know more about SANE? Go look at <http://www.sane-project.org>. 🔥

Most methods set $Sane::STATUS, which is overloaded — so it gives you either an integer, exactly as dictated by the SANE standard, or the corresponding message, whichever one you need. iconic behavior tbh.

---

🎀 Sane->get_version 🎀

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

join('.',Sane->get_version)

---

🎀 Sane->get_version_scalar 🎀

Returns an scalar with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions squished together the way Perl version numbering works, i.e. sane 1.0.19 gives 1.000019. This lets you do simple version comparisons. no cap, super handy. ✨

---

🎀 Sane->get_devices 🎀

Use this one to query the list of devices that are available. If it runs successfully, you get back an array of hash references with the devices it found. That returned list is guaranteed to stay valid until either (a) you call this function again, or (b) you call sane_exit(). You can call this function over and over to detect when new devices show up. 👑

If argument local_only is true, you only get local devices back — meaning devices directly attached to the machine that SANE is running on. If it's false, the device list includes all the 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";
}

---

🎀 Sane::Device->open 🎀

This function establishes a connection to one particular device. The name of the device you wanna open goes in argument name. If the call completes successfully, you get a Sane::Device object back. And here's the special case: if you pass a zero-length string as the device, you're requesting the first available device (assuming there is such a device). 🙈

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

---

🎀 Sane::Device->get_option_descriptor 🎀

Use this to access option descriptors. It returns a hash reference holding 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 tells you how many options are available for the Sane::Device object (and yes, that count includes option 0). If n is not a valid option index, the function croaks. 💀

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 name, title, desc, type, unit, cap and constraint_type are exactly as the C API describes them (<http://www.sane-project.org/html>). There's also a further constraint key, which either holds an array with the possible option values, or a hash with max, min, and quant keys.

The max_values key replaced the size key from the C API, and it holds the maximum number of values that the option may contain. noted. 🍓

---

🎀 Sane::Device->get_option 🎀

Returns the current value of the option you selected.

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

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

---

🎀 Sane::Device->set_auto 🎀

Tells the selected device to automatically pick an appropriate value. This mode stays in effect until an explicit set_option request overrides it. set it and forget it bestie.

$device->set_auto($n);

---

🎀 Sane::Device->set_option 🎀

Sets the selected option, and returns flags in $info, which are described in the C API (<http://www.sane-project.org/html>).

$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";
}

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

---

🎀 Sane::Device->get_parameters 🎀

This one gets you the current scan parameters. The parameters you get back are guaranteed to be accurate between the moment 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 before a scan has actually started is lowkey useful — it lets you, for example, get an estimate of how big the scanned image is gonna 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 (<http://www.sane-project.org/html>) for the details of all those values above. iykyk. 📖

---

🎀 Sane::Device->start 🎀

This function kicks off the acquisition of an image from the device you specified. let's gooo.

$device->start;

---

🎀 Sane::Device->read 🎀

This function reads image data from the device you 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 you call this function when no data is available, one of two things can happen, depending on the I/O mode that's currently 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 occurs).
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.

You can set the I/O mode of the device by calling Sane::Device->set_io_mode().

---

🎀 Sane::Device->cancel 🎀

This function immediately, or as quickly as possible, cancels the currently pending operation of the device.

$device->cancel;

You can call this function at any time (as long as $device is valid), but usually it only affects long-running operations (like image acquisition). It's safe to call this function asynchronously — e.g., from inside a signal handler. And it's important to note: completion of this operation 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). And 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. so like, wait your turn. 💀

---

🎀 Sane::Device->set_io_mode 🎀

This function sets 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. You can only call this function 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 that case the status value SANE_STATUS_UNSUPPORTED is returned. Blocking I/O must be supported by all backends though, so calling this function with SANE_FALSE is guaranteed to complete successfully. periodt. 💅

---

🎀 Sane::Device->get_select_fd 🎀

This function gets you 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;

You can only call this function 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). In fact, a backend must guarantee that it closes the returned select file descriptor at the point when the next Sane::Device->read() call would return SANE_STATUS_EOF. This is necessary so the application can detect when that condition occurs without actually having to call Sane::Device->read(). 🧠

A backend may elect not to support this operation. In that 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 of whether the file-descriptor is readable (e.g., this test can be implemented using select() or poll() under UNIX). If you perform any other operation 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 — it lets an application do other work while image acquisition is in progress. multitasking queen. 👑

---

🎀 Sane::Device->write_pnm_header 🎀

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're not already provided, e.g.:

$device->write_pnm_header($fh);

or

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

🌈 SEE ALSO 💖

okay so before you go, bestie, there's one (1) more thing you should absolutely have in your tabs:

The SANE Standard Reference <http://www.sane-project.org/html> is literally the handy companion for this whole situation. Like, it's the bestie to this manpage's bestie. ✨

And real talk — the Perl bindings follow the C API very closely, so if you want the actual tea, the C reference documentation should be considered the canonical source. No cap. The Perl stuff is a glow-up of the C stuff, so when in doubt, go to the source of the source. 🫶

---

🌸 AUTHOR 🎀

This whole thing was brought to you by:

Jeffrey Ratcliffe, <Jeffrey.Ratcliffe@gmail.com>

give it up for him, he ate 💅

---

👑 COPYRIGHT AND LICENSE 💖

okay so legal bit, but make it cute:

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 ✨

so yeah, it's giving open source, it's giving freedom, it's giving do what you want but respect the terms. periodt. 🦋

---

and that's a wrap on this manpage, bestie 💖 you made it to the end, which is honestly main character energy. go read the SANE Standard Reference, go scan something iconic, and remember: the C docs are canonical. iykyk 🌈

this page came to you from perl v5.42.0 and is dated 2025-07-25 — so yes, it's recent, it's fresh, it's that girl. stay slaying ✨🎀