.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Device::Cdio 3pm" .TH Device::Cdio 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Device::Cdio \- Module for CD Input and Control library. .SH "SYNOPSIS" .IX Header "SYNOPSIS" This encapsulates CD-ROM reading and control. Applications wishing to be oblivious of the \s-1OS\-\s0 and device-dependent properties of a CD-ROM can use this library. .PP .Vb 2 \& 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\en"; \& } \& foreach my $driver_name (sort keys(%Device::Cdio::drivers)) { \& print "Driver $driver_name is installed.\en" \& if Device::Cdio::have_driver($driver_name) and \& $driver_name !~ m{device|Unknown}; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is an Perl Object-Oriented interface to the \s-1GNU CD\s0 Input and Control library, \f(CW\*(C`libcdio\*(C'\fR, written in C. The library encapsulates CD-ROM reading and control. Perl programs wishing to be oblivious of the \s-1OS\-\s0 and device-dependent properties of a CD-ROM can use this library. .PP The encapsulation is done in two parts. The lower-level Perl interface is called perlcdio and is generated by \s-1SWIG.\s0 .PP This module uses \f(CW\*(C`perlcdio\*(C'\fR. Actually, there are no objects in module, but there are in its sub modules Device::Cdio::Device and Device::Cdio::Track. .PP Although \f(CW\*(C`perlcdio\*(C'\fR is perfectly usable on its own, it is expected that Cdio is what most people will use. As \f(CW\*(C`perlcdio\*(C'\fR more closely models the C interface \f(CW\*(C`libcdio\*(C'\fR, it is conceivable (if unlikely) that die-hard libcdio C users who are very familiar with that interface could prefer that. .SS "\s-1CALLING ROUTINES\s0" .IX Subsection "CALLING ROUTINES" Routines accept named parameters as well as positional parameters. For named parameters, each argument name is preceded by a dash. For example: .PP .Vb 1 \& Device::Cdio::have_driver(\-driver_id=>\*(AqGNU/Linux\*(Aq) .Ve .PP Each argument name is preceded by a dash. Neither case nor order matters in the argument list. \f(CW\*(C`\-driver_id\*(C'\fR, \f(CW\*(C`\-Driver_ID\*(C'\fR, and \&\f(CW\*(C`\-DRIVER_ID\*(C'\fR 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. .PP 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 \f(CW\*(C`close_tray\*(C'\fR the documentation below reads: .PP .Vb 2 \& close_tray(drive=undef, driver_id=$perlcdio::DRIVER_UNKNOWN) \& \-> ($drc, $driver_id) .Ve .PP So the parameter names are \*(L"drive\*(R", and \*(L"driver_id\*(R". Neither parameter is required. If \*(L"drive\*(R" is not specified, a value of \*(L"undef\*(R" will be used. And if \*(L"driver_id\*(R" is not specified, a value of \&\f(CW$perlcdio::DRIVER_UNKNOWN\fR is used. .PP The older, more traditional style of positional parameters is also supported. So the \f(CW\*(C`have_driver\*(C'\fR example from above can also be written: .PP .Vb 1 \& Device::Cdio::have_driver(\*(AqGNU/Linux\*(Aq) .Ve .PP Finally, since no parameter name can be confused with a an integer, negative values will not get confused as a named parameter. .SH "SUBROUTINES" .IX Header "SUBROUTINES" .SS "close_tray" .IX Subsection "close_tray" close_tray(drive=undef, driver_id=$perlcdio::DRIVER_UNKNOWN) \-> ($drc, \f(CW$driver_id\fR) .PP close media tray in \s-1CD\s0 drive if there is a routine to do so. .PP 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. .SS "driver_strerror" .IX Subsection "driver_strerror" driver_strerror(rc)\->$errmsg .PP Convert a driver return code into a string text message. .SS "get_default_device_driver" .IX Subsection "get_default_device_driver" get_default_device_driver(driver_id=DRIVER_DEVICE)\-> ($device, \f(CW$driver\fR) .PP Return a string containing the default \s-1CD\s0 device if none is specified. if driver_id is \s-1DRIVER_UNKNOWN\s0 or \s-1DRIVER_DEVICE\s0 then find a suitable one set the default device for that. .PP undef is returned as the driver if we couldn't get a default device. .SS "get_devices" .IX Subsection "get_devices" \&\f(CW$revices\fR = get_devices(driver_id=$Cdio::DRIVER_UNKNOWN); .PP Return an array of device names. If you want a specific devices for a driver, give that device. If you want hardware devices, give \&\f(CW$perlcdio::DRIVER_DEVICE\fR and if you want all possible devices, image drivers and hardware drivers give \f(CW$perlcdio::DRIVER_UNKNOWN\fR. undef is returned if we couldn't return a list of devices. .PP In some situations of drivers or \s-1OS\s0's we can't find a \s-1CD\s0 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. .SS "get_devices_ret" .IX Subsection "get_devices_ret" get_devices_ret($driver_id)\->(@devices, \f(CW$driver_id\fR) .PP Like get_devices, but we may change the p_driver_id if we were given \&\f(CW$perlcdio::DRIVER_DEVICE\fR or \f(CW$perlcdio::DRIVER_UNKNOWN\fR. This is because often one wants to get a drive name and then \fIopen\fR it afterwords. Giving the driver back facilitates this, and speeds things up for libcdio as well. .SS "get_devices_with_cap" .IX Subsection "get_devices_with_cap" \&\f(CW$devices\fR = get_devices_with_cap($capabilities, \f(CW$any\fR); .PP Get an array of device names in search_devices that have at least the capabilities listed by the capabilities parameter. .PP If \*(L"any\*(R" is set false then \s-1ALL\s0 capabilities listed in the extended portion of capabilities (i.e. not the basic filesystem) must be satisfied. If \*(L"any\*(R" is set true, then if any of the capabilities matches, we call that a success. .PP To find a CD-drive of any type, use the mask \f(CW$perlcdio::FS_MATCH_ALL\fR. .PP 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. .SS "get_devices_with_cap_ret" .IX Subsection "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. .SS "have_driver" .IX Subsection "have_driver" have_driver(driver_id) \-> bool .PP 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 \f(CW%drivers\fR. .SS "is_binfile" .IX Subsection "is_binfile" is_binfile(binfile)\->cue_name .PP Determine if binfile is the \s-1BIN\s0 file part of a \s-1CDRWIN\s0 Compact Disc image. .PP Return the corresponding \s-1CUE\s0 file if bin_name is a \s-1BIN\s0 file or undef if not a \s-1BIN\s0 file. .SS "is_cuefile" .IX Subsection "is_cuefile" is_cuefile(cuefile)\->bin_name .PP Determine if cuefile is the \s-1CUE\s0 file part of a \s-1CDRWIN\s0 Compact Disc image. .PP Return the corresponding \s-1BIN\s0 file if cue_name is a \s-1CUE\s0 file or undef if not a \s-1CUE\s0 file. .SS "is_device" .IX Subsection "is_device" is_device(source, driver_id=$perlcdio::DRIVER_UNKNOWN)\->bool .PP Return True if source refers to a real hardware CD-ROM. .SS "is_nrg" .IX Subsection "is_nrg" is_nrg(nrgfile)\->bool .PP Determine if nrgfile is a Nero \s-1NRG\s0 file disc image. .SS "is_tocfile" .IX Subsection "is_tocfile" is_tocfile(tocfile_name)\->bool .PP Determine if tocfile_name is a cdrdao \s-1CD\s0 disc image. .SS "convert_drive_cap_misc" .IX Subsection "convert_drive_cap_misc" convert_drive_cap_misc(bitmask)\->hash_ref .PP Convert bit mask for miscellaneous drive properties into a hash reference of drive capabilities .SS "convert_drive_cap_read" .IX Subsection "convert_drive_cap_read" convert_drive_cap_read($bitmask)\->hash_ref .PP Convert bit mask for read drive properties into a hash reference of drive capabilities .SS "convert_drive_cap_write" .IX Subsection "convert_drive_cap_write" convert_drive_cap_write($bitmask)\->hash_ref .SH "SEE ALSO" .IX Header "SEE ALSO" Device::Cdio::Device for device objects and Device::Cdio::Track for track objects and Device::Cdio::ISO9660 for working with \s-1ISO 9660\s0 filesystems. .PP perlcdio is the lower-level interface to libcdio. .PP is documentation via doxygen for \f(CW\*(C`libcdio\*(C'\fR. .SH "AUTHORS" .IX Header "AUTHORS" Rocky Bernstein .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2006, 2011 Rocky Bernstein .PP This program is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program. If not, see The \s-1GNU\s0 General Public License .