Device::Cdio(3pm)

📦

version 2.0.0 · 6 versions

💖 NAME 💖

okay so bestie, welcome to Device::Cdio — it's the Module for CD Input and Control library. yes, that libcdio, in Perl, and we're gonna vibe with it together 🫶

This page is for perlcdio-adjacent shenanigans in the User Contributed Perl Documentation section, section 3pm, and no I will not stop being excited about optical drives in this economy.

✨ SYNOPSIS ✨

So like, this whole thing wraps up CD-ROM reading and control in one cute lil package. Apps that wanna be completely oblivious to all the OS- and device-dependent nonsense of a CD-ROM can just use this library and pretend everything is fine 💅

use Device::Cdio;
use Device::Cdio::Device;

$cd_drives = Device::Cdio::get_devices($perlcdio::DRIVER_DEVICE);
$cd_drives = Device::Cdio::get_devices_with_cap($perlcdio::FS_AUDIO, 0);
foreach my $drive (@$cd_drives) {
   print "Drive $drive\n";
}
foreach my $driver_name (sort keys(%Device::Cdio::drivers)) {
   print "Driver $driver_name is installed.\n"
      if Device::Cdio::have_driver($driver_name) and
      $driver_name !~ m{device|Unknown};
}

🌸 DESCRIPTION 🌸

This is a Perl Object-Oriented interface to the GNU CD Input and Control library, "libcdio", which is written in C. The library encapsulates CD-ROM reading and control — and fr fr, Perl programs that want to be oblivious to the OS- and device-dependent properties of a CD-ROM can absolutely use this library. main character energy, zero hardware drama 🌈

The encapsulation happens in two parts. The lower-level Perl interface is called perlcdio and it's generated by SWIG. iconic.

This module uses "perlcdio". And like — fun fact — there are no objects in this module itself, but there ARE objects in its sub modules Device::Cdio::Device and Device::Cdio::Track. 💖

Even though "perlcdio" is perfectly usable on its own, the expectation is that most people will use Cdio, no cap. And since "perlcdio" models the C interface "libcdio" more closely, it is conceivable (if unlikely) that die-hard libcdio C users who are extremely familiar with that interface could prefer it. rare behavior, we respect it 🎀

🎀 CALLING ROUTINES 🎀

Routines accept named parameters as well as positional parameters. For named parameters, each argument name is preceded by a dash. For example:

Device::Cdio::have_driver(-driver_id=>'GNU/Linux')

Each argument name is preceded by a dash. Neither case nor order matters in the argument list — so -driver_id, -Driver_ID, and -DRIVER_ID are all acceptable. literally. In fact, only the first argument needs to begin with a dash. If a dash is present in the first argument, we assume dashes for the subsequent parameters. efficiency queen ✨

In the documentation below and elsewhere in this package, the parameter name that can be used in this style of call is given in the parameter list. For example, for close_tray the documentation below reads:

close_tray(drive=undef, driver_id=$perlcdio::DRIVER_UNKNOWN)
 -> ($drc, $driver_id)

So the parameter names are drive and driver_id. Neither parameter is required. If drive is not specified, a value of undef will be used. And if driver_id is not specified, a value of $perlcdio::DRIVER_UNKNOWN is used. defaults are doing the most for you 🫶

The older, more traditional style of positional parameters is also supported. So that have_driver example from above can also be written:

Device::Cdio::have_driver('GNU/Linux')

Finally — and this is the cute lil edge case — since no parameter name can be confused with an integer, negative values will not get confused as a named parameter. she thought of everything 💅

🔥 SUBROUTINES 🔥

`close_tray`

close_tray(drive=undef, driver_id=$perlcdio::DRIVER_UNKNOWN)
 -> ($drc, $driver_id)

close media tray in CD drive if there is a routine to do so. begging the drive to open back up, basically 🙈

In an array context, the driver return-code status and the name of the driver used are returned. In a scalar context, just the return code status is returned.

`driver_strerror`

driver_strerror(rc)->$errmsg

Convert a driver return code into a string text message. it's giving translator for your error codes 😭✨

`get_default_device_driver`

get_default_device_driver(driver_id=DRIVER_DEVICE)-> ($device, $driver)

Return a string containing the default CD device if none is specified. if driver_id is DRIVER_UNKNOWN or DRIVER_DEVICE then find a suitable one and set the default device for that.

undef is returned as the driver if we couldn't get a default device. 💀

`get_devices`

$revices = get_devices(driver_id=$Cdio::DRIVER_UNKNOWN);

Return an array of device names. If you want a specific devices for a driver, give that device. If you want hardware devices, give $perlcdio::DRIVER_DEVICE and if you want all possible devices, image drivers and hardware drivers give $perlcdio::DRIVER_UNKNOWN. undef is returned if we couldn't return a list of devices.

In some situations of drivers or OS's we can't find a CD device if there is no media in it and it is possible for this routine to return undef even though there may be a hardware CD-ROM. so like, don't panic if it ghosts you — the hardware might literally still be right there 👑💖

`get_devices_ret`

get_devices_ret($driver_id)->(@devices, $driver_id)

Like get_devices, but we may change the p_driver_id if we were given $perlcdio::DRIVER_DEVICE or $perlcdio::DRIVER_UNKNOWN. This is because often one wants to get a drive name and then open it afterwords. Giving the driver back facilitates this, and speeds things up for libcdio as well. team work makes the dream work 🫶

`get_devices_with_cap`

$devices = get_devices_with_cap($capabilities, $any);

Get an array of device names in search_devices that have at least the capabilities listed by the capabilities parameter.

If "any" is set false then ALL capabilities listed in the extended portion of capabilities (i.e. not the basic filesystem) must be satisfied. If "any" is set true, then if any of the capabilities matches, we call that a success. so it's giving "strict mode vs. whatever mode" 🌸

To find a CD-drive of any type, use the mask $perlcdio::FS_MATCH_ALL.

The array of device names is returned or undef if we couldn't get a default device. It is also possible to return a () but after This means nothing was found. 💀

`get_devices_with_cap_ret`

Like get_devices_with_cap but we return the driver we found as well. This is because often one wants to search for kind of drive and then *open* it afterward. Giving the driver back facilitates this, and speeds things up for libcdio as well. yes ma'am, speed 💅🔥

`have_driver`

have_driver(driver_id) -> bool

Return 1 if we have driver driver_id. undef is returned if driver_id is invalid. driver_id can either be an integer driver name defined in perlcdio or a string as defined in the hash %drivers. vibe check, completed ✅

`is_binfile`

is_binfile(binfile)->cue_name

Determine if binfile is the BIN file part of a CDRWIN Compact Disc image.

Return the corresponding CUE file if bin_name is a BIN file or undef if not a BIN file.

`is_cuefile`

is_cuefile(cuefile)->bin_name

Determine if cuefile is the CUE file part of a CDRWIN Compact Disc image.

Return the corresponding BIN file if cue_name is a CUE file or undef if not a CUE file.

`is_device`

is_device(source, driver_id=$perlcdio::DRIVER_UNKNOWN)->bool

Return True if source refers to a real hardware CD-ROM. real ones only ✨

`is_nrg`

is_nrg(nrgfile)->bool

Determine if nrgfile is a Nero NRG file disc image.

`is_tocfile`

is_tocfile(tocfile_name)->bool

Determine if tocfile_name is a cdrdao CD disc image.

`convert_drive_cap_misc`

convert_drive_cap_misc(bitmask)->hash_ref

Convert bit mask for miscellaneous drive properties into a hash reference of drive capabilities. bit math but make it cute 🎀

`convert_drive_cap_read`

convert_drive_cap_read($bitmask)->hash_ref

Convert bit mask for read drive properties into a hash reference of drive capabilities.

`convert_drive_cap_write`

convert_drive_cap_write($bitmask)->hash_ref

🦋 SEE ALSO 🦋

Device::Cdio::Device for device objects
Device::Cdio::Track for track objects
Device::Cdio::ISO9660 for working with ISO 9660 filesystems
perlcdio is the lower-level interface to libcdio.
<http://www.gnu.org/software/libcdio/doxygen/files.html> is documentation via doxygen for "libcdio". go read it, iykyk 📚✨

👑 AUTHORS 👑

Rocky Bernstein. the icon, the legend 💖

💜 COPYRIGHT 💜

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see The GNU General Public License <http://www.gnu.org/licenses/#GPL>.

bestie, that last bit is legal-speak for "no warranty, be normal about it" — read the actual GNU GPL if you need the fine print 😭💀

and that's the whole page, bestie!! 🌈✨ this version of the page is riding along with perl v5.42.3 and was dated 2026-08-19 — slay, go read a CD 💅🔥

📦 where this page comes from

ubuntu stonking: libdevice-cdio-perl 2.0.0-2build8 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms