Ubuntu Manpage: Device::Cdio - Module for CD Input and Control library.

Provided by: libdevice-cdio-perl_0.4.0-3_amd64

NAME

       Device::Cdio - Module for CD Input and Control library.

SYNOPSIS

       This encapsulates CD-ROM reading and control. Applications wishing to be oblivious of the
       OS- and device-dependent properties of a CD-ROM can use this library.

           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 an Perl Object-Oriented interface to the GNU CD Input and Control library,
"libcdio", written in C. The library encapsulates CD-ROM reading and control. Perl
programs wishing to be oblivious of the OS- and device-dependent properties of a CD-ROM
can use this library.

The encapsulation is done in two parts. The lower-level Perl interface is called perlcdio
and is generated by SWIG.

This module uses "perlcdio". Actually, there are no objects in module, but there are in
its sub modules Device::Cdio::Device and Device::Cdio::Track.

Although "perlcdio" is perfectly usable on its own, it is expected that Cdio is what most
people will use. As "perlcdio" more closely models the C interface "libcdio", it is
conceivable (if unlikely) that die-hard libcdio C users who are very familiar with that
interface could prefer that.

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. "-driver_id", "-Driver_ID", and "-DRIVER_ID" are all acceptable. 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.

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.

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

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

Finally, since no parameter name can be confused with a an integer, negative values will
not get confused as a named parameter.

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.

       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.

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

   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.

   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.

       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.

   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.

   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.

   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

   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

AUTHORS

       Rocky Bernstein

COPYRIGHT