.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "perliso9660 3pm"
.TH perliso9660 3pm 2024-01-10 "perl v5.38.2" "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
perliso9660 \- lower\-level wrapper to libiso9660, the ISO 9660 library of the CD Input and Control package
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This is fairly straight-forward wrapper around the C library libiso9660
Although this is perfectly usable on its own, it is expected that the
Object-Oriented interface Device::Cdio::ISO9660 is what most people will
want to use.
.PP
There are various constants that are defined here.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Encapsulation is done in two parts. The lower-level Perl
interface is called perliso9660 (this file) and is generated via SWIG.
.SH CONSTANTS
.IX Header "CONSTANTS"
.IP ISO_BLOCKSIZE 4
.IX Item "ISO_BLOCKSIZE"
Number of bytes in an ISO 9660 block (2048)
.IP PVD_SECTOR 4
.IX Item "PVD_SECTOR"
"Primary Volume Descriptor" sector (16)
.IP EVD_SECTOR 4
.IX Item "EVD_SECTOR"
"End Volume Descriptor" sector (17)
.IP LEN_ISONAME 4
.IX Item "LEN_ISONAME"
Size in bytes of the filename  portion + null byte (31)
.IP MAX_SYSTEM_ID 4
.IX Item "MAX_SYSTEM_ID"
Maximum number of characters in a system id (32)
.IP MAX_ISONAME 4
.IX Item "MAX_ISONAME"
Size in bytes of the filename portion + null byte. (37)
.IP MAX_PREPARER_ID 4
.IX Item "MAX_PREPARER_ID"
Maximum number of characters in a preparer id. (128)
.IP MAX_ISOPATHNAME 4
.IX Item "MAX_ISOPATHNAME"
Maximum number of characters in the entire ISO 9660 filename. (255)
.IP MAX_PUBLISHER_ID 4
.IX Item "MAX_PUBLISHER_ID"
Maximum number of characters in a publisher id.
.IP MAX_APPLICATION_ID 4
.IX Item "MAX_APPLICATION_ID"
Maximum number of characters in an application id.
.IP MAX_VOLUME_ID 4
.IX Item "MAX_VOLUME_ID"
Maximum number of characters in a volume id.
.IP MAX_VOLUMESET_ID 4
.IX Item "MAX_VOLUMESET_ID"
Maximum number of characters in a volume-set id.
.IP STANDARD_ID 4
.IX Item "STANDARD_ID"
String inside frame which identifies an ISO 9660 filesystem. This
string is the "id" field of an iso9660_pvd_t or an iso9660_svd_t.
.IP EXTENSION_JOLIET_LEVEL1 4
.IX Item "EXTENSION_JOLIET_LEVEL1"
Use Joliet Level 1.
.IP EXTENSION_JOLIET_LEVEL2 4
.IX Item "EXTENSION_JOLIET_LEVEL2"
Use Joliet Level 2.
.IP EXTENSION_JOLIET_LEVEL3 4
.IX Item "EXTENSION_JOLIET_LEVEL3"
Use Joliet Level 3
.IP EXTENSION_ROCK_RIDGE 4
.IX Item "EXTENSION_ROCK_RIDGE"
Use Rock-Ridge Extensions.
.IP EXTENSION_HIGH_SIERRA 4
.IX Item "EXTENSION_HIGH_SIERRA"
Use High-Sierra Extensions.
.IP EXTENSION_ALL 4
.IX Item "EXTENSION_ALL"
Use any of the above extensions.
.IP EXTENSION_NONE 4
.IX Item "EXTENSION_NONE"
Use none of the above extensions.
.IP EXTENSION_JOLIET 4
.IX Item "EXTENSION_JOLIET"
Use any Joliet Extension available.
.SS "Directory Flags"
.IX Subsection "Directory Flags"
.IP FILE 4
.IX Item "FILE"
Not really a flag but the lack of one.
.IP EXISTENCE 4
.IX Item "EXISTENCE"
Do not make existence known (hidden).
.IP DIRECTORY 4
.IX Item "DIRECTORY"
This file is a directory.
.IP ASSOCIATED 4
.IX Item "ASSOCIATED"
This file is an associated file
.IP RECORD 4
.IX Item "RECORD"
Record format is in extended attribute if not set.
.IP PROTECTION 4
.IX Item "PROTECTION"
No read/execute permission in extended attribute.
.IP DRESERVED1 4
.IX Item "DRESERVED1"
Reserved bit 5.
.IP DRESERVED2 4
.IX Item "DRESERVED2"
Reserved bit 6
.IP MULTIEXTENT 4
.IX Item "MULTIEXTENT"
Not the final entry of a multi-extent file.
.SS "Volume Descriptor Types"
.IX Subsection "Volume Descriptor Types"
.IP VD_BOOT_RECORD 4
.IX Item "VD_BOOT_RECORD"
CD is bootable
.IP VD_PRIMARY 4
.IX Item "VD_PRIMARY"
Primary Volume descriptor which must be in any ISO\-9660
.IP VD_SUPPLEMENTARY 4
.IX Item "VD_SUPPLEMENTARY"
(optional) Supplimentary Volume Descriptor. But used by Joliet, for
example.
.IP VD_PARITION 4
.IX Item "VD_PARITION"
Indicates a partition of a CD.
.IP VD_END 4
.IX Item "VD_END"
.SS "Flags for strncpy"
.IX Subsection "Flags for strncpy"
.PD 0
.IP NOCHECK 4
.IX Item "NOCHECK"
.PD
Enumeration meaning don not check in strncpy_pad.
.IP SEVEN_BIT 4
.IX Item "SEVEN_BIT"
Enumeration in strncpy_pad for checking entry has only 7\-bit characters.
.IP ACHARS 4
.IX Item "ACHARS"
Enumeration in strncpy_pad for checking entry has only ACHARs.
.IP DCHARS 4
.IX Item "DCHARS"
Enumeration in strncpy_pad for checking entry has only DCHARs.
.SH SUBROUTINES
.IX Header "SUBROUTINES"
.SS "Input Output"
.IX Subsection "Input Output"
\fIopen_iso\fR
.IX Subsection "open_iso"
.PP
Open an ISO 9660 image for reading. Maybe in the future we will have
mode. undef is returned on error.
.PP
\fIopen_ext\fR
.IX Subsection "open_ext"
.PP
Open an ISO 9660 image for reading allowing various ISO 9660
extensions.  Maybe in the future we will have a mode. undef is
eturned on error.
.PP
\fIopen_fuzzy\fR
.IX Subsection "open_fuzzy"
.PP
Open an ISO 9660 image for reading with some tolerence for positioning
of the ISO9660 image. We scan for \f(CW$perliso9660::ISO_STANDARD_ID\fR and
use that to set he eventual offset to adjust by (as long as that is <=
i_fuzz).
.PP
Maybe in the future we will have a mode. undef is returned on error.
.PP
See also open_iso
.PP
\fIopen_fuzzy_ext\fR
.IX Subsection "open_fuzzy_ext"
.PP
Open an ISO 9660 image for reading with some tolerence for positioning
of the ISO9660 image. We scan for ISO_STANDARD_ID and use that to set
the eventual offset to adjust by (as long as that is <= i_fuzz).
.PP
Maybe in the future we will have a mode. undef is returned on error.
.PP
\fIifs_fuzzy_read_superblock\fR
.IX Subsection "ifs_fuzzy_read_superblock"
.PP
Read the Super block of an ISO 9660 image but determine framesize
and datastart and a possible additional offset. Generally here we are
not reading an ISO 9660 image but a CD-Image which contains an ISO 9660
filesystem.
.PP
\fIclose\fR
.IX Subsection "close"
.PP
Close previously opened ISO 9660 image.
1 is unconditionally returned. If there was an error 0 would
be returned.
.PP
\fIseek_read\fR
.IX Subsection "seek_read"
.PP
Seek to a position and then read n bytes. (buffer, size) are is returned.
.PP
\fIfs_read_pvd\fR
.IX Subsection "fs_read_pvd"
.PP
Read the Primary Volume Descriptor for a CD.
1 is returned if read, and 0 if there was an error.
.PP
\fIifs_read_pvd\fR
.IX Subsection "ifs_read_pvd"
.PP
Read the Primary Volume Descriptor for an ISO 9660 image.
1 is returned if read, and 0 if there was an error.
.PP
\fI_fs_read_superblock\fR
.IX Subsection "_fs_read_superblock"
.PP
Read the Super block of an ISO 9660 image. This is the
Primary Volume Descriptor (PVD) and perhaps a Supplemental Volume
Descriptor if (Joliet) extensions are acceptable.
.PP
\fIifs_read_superblock\fR
.IX Subsection "ifs_read_superblock"
.PP
Read the Super block of an ISO 9660 image. This is the
Primary Volume Descriptor (PVD) and perhaps a Supplemental Volume
Descriptor if (Joliet) extensions are acceptable.
.SS "Time Conversion"
.IX Subsection "Time Conversion"
\fIset_dtime\fR
.IX Subsection "set_dtime"
.PP
Set time in format used in ISO 9660 directory index record
from a Unix time structure.
.PP
\fIset_ltime\fR
.IX Subsection "set_ltime"
.PP
Set "long" time in format used in ISO 9660 primary volume descriptor
from a Unix time structure.
.PP
\fIget_dtime\fR
.IX Subsection "get_dtime"
.PP
Get Unix time structure from format use in an ISO 9660 directory index
record. Even though tm_wday and tm_yday fields are not explicitly in
dtime, they are calculated from the other fields.
.PP
If tm is to reflect the localtime, set "use_localtime" 1, otherwise
tm will reported in GMT.
.PP
\fIget_ltime\fR
.IX Subsection "get_ltime"
.PP
Get "long" time in format used in ISO 9660 primary volume descriptor
from a Unix time structure.
.SS "Character Classification and String Manipulation"
.IX Subsection "Character Classification and String Manipulation"
\fIis_dchar\fR
.IX Subsection "is_dchar"
.PP
Return 1 if c (an int) is a DCHAR \- a character that can appear in an an
ISO\-9600 level 1 directory name. These are the ASCII capital
letters A\-Z, the digits 0\-9 and an underscore.
.PP
\fIis_achar\fR
.IX Subsection "is_achar"
.PP
\fIname_translate\fR
.IX Subsection "name_translate"
.PP
Convert an ISO\-9660 file name that stored in a directory entry into
what is usually listed as the file name in a listing.
wercase name, and remove trailing ;1's or .;1's and
turn the others into version numbers.
.PP
\fIname_translate_ext\fR
.IX Subsection "name_translate_ext"
.PP
Convert an ISO\-9660 file name that stored in a directory entry into
what is usually listed as the file name in a listing.  Lowercase
name if no Joliet Extension interpretation. Remove trailing ;1's or
\&.;1's and turn the others into version numbers.
.PP
\fIstrncpy_pad\fR
.IX Subsection "strncpy_pad"
.PP
Pad string src with spaces to size len and copy this to dst. If len is
less than the length of src, dst will be truncated to the first len
characters of src.
.PP
src can also be scanned to see if it contains only ACHARs, DCHARs,
7\-bit ASCII chars depending on the enumeration _check.
.PP
In addition to getting changed, dst is the return value.  Note: this
string might not be undef terminated.
.SS "File and Directory Names"
.IX Subsection "File and Directory Names"
\fIdirname_valid_p\fR
.IX Subsection "dirname_valid_p"
.PP
Check that psz_path is a valid ISO\-9660 directory name.
.PP
A valid directory name should not start out with a slash (/),
dot (.) or null byte, should be less than 37 characters long,
have no more than 8 characters in a directory component
which is separated by a /, and consist of only DCHARs.
.PP
1 is returned if psz_path is valid.
.PP
\fIpathname_isofy\fR
.IX Subsection "pathname_isofy"
.PP
Take psz_path and a version number and turn that into a ISO\-9660
pathname.  (That is just the pathname followed by ";" and the version
number. For example, mydir/file.ext \-> MYDIR/FILE.EXT;1 for version
1. The resulting ISO\-9660 pathname is returned.
.PP
\fIpathname_valid_p\fR
.IX Subsection "pathname_valid_p"
.PP
Check that psz_path is a valid ISO\-9660 pathname.
.PP
A valid pathname contains a valid directory name, if one appears and
the filename portion should be no more than 8 characters for the
file prefix and 3 characters in the extension (or portion after a
dot). There should be exactly one dot somewhere in the filename
portion and the filename should be composed of only DCHARs.
.PP
1 is returned if psz_path is valid.
.PP
\fIfs_find_lsn\fR
.IX Subsection "fs_find_lsn"
.PP
Given a directory pointer, find the filesystem entry that contains
lsn and return information about it.
.PP
Returns stat_t of entry if we found lsn, or undef otherwise.
.PP
\fIifs_find_lsn\fR
.IX Subsection "ifs_find_lsn"
.PP
Given a directory pointer, find the filesystem entry that contains
lsn and return information about it.
.PP
Returns stat_t of entry if we found lsn, or undef otherwise.
.PP
\fIfs_stat\fR
.IX Subsection "fs_stat"
.PP
Return file status for psz_path. undef is returned on error.
.PP
\fIfs_stat_translate\fR
.IX Subsection "fs_stat_translate"
.PP
Return file status for path name psz_path. undef is returned on error.
pathname version numbers in the ISO 9660 name are dropped, i.e. ;1
is removed and if level 1 ISO\-9660 names are lowercased.
.PP
\fIifs_stat\fR
.IX Subsection "ifs_stat"
.PP
Return file status for pathname. undef is returned on error.
.PP
\fIifs_stat_translate\fR
.IX Subsection "ifs_stat_translate"
.PP
Return file status for path name psz_path. undef is returned on
error.  pathname version numbers in the ISO 9660 name are dropped,
i.e. ;1 is removed and if level 1 ISO\-9660 names are lowercased.
.PP
\fIfs_readdir\fR
.IX Subsection "fs_readdir"
.PP
Read psz_path (a directory) and return a list of iso9660_stat_t
pointers for the files inside that directory. The caller must free the
returned result.
.PP
\fIifs_readdir\fR
.IX Subsection "ifs_readdir"
.PP
Read psz_path (a directory) and return a list of iso9660_stat_t
pointers for the files inside that directory. The caller must free
the returned result.
.PP
\fIget_dir_len\fR
.IX Subsection "get_dir_len"
.PP
Return the directory name stored in the iso9660_dir_t
.PP
A string is allocated: the caller must deallocate.
.PP
\fIdir_to_name\fR
.IX Subsection "dir_to_name"
.PP
\fIget_posix_filemode\fR
.IX Subsection "get_posix_filemode"
.PP
Returns a POSIX mode for a given p_iso_dirent.
.SS "Primary Volume Descriptor Routines"
.IX Subsection "Primary Volume Descriptor Routines"
\fIget_application_id\fR
.IX Subsection "get_application_id"
.PP
Return the PVD's application ID.
.PP
undef is returned if there is some problem in getting this.
.PP
\fIifs_get_application_id\fR
.IX Subsection "ifs_get_application_id"
.PP
Get the application ID.  psz_app_id is set to undef if there
is some problem in getting this and 0 is returned.
.PP
\fIget_preparer_id\fR
.IX Subsection "get_preparer_id"
.PP
Return a string containing the preparer id with trailing
blanks removed.
.PP
\fIifs_get_preparer_id\fR
.IX Subsection "ifs_get_preparer_id"
.PP
Get the preparer ID.  psz_preparer_id is set to undef if there
is some problem in getting this and 0 is returned.
.PP
\fIget_publisher_id\fR
.IX Subsection "get_publisher_id"
.PP
Return a string containing the PVD's publisher id with trailing
blanks removed.
.PP
\fIifs_get_publisher_id\fR
.IX Subsection "ifs_get_publisher_id"
.PP
Get the publisher ID.  psz_publisher_id is set to undef if there
is some problem in getting this and 0 is returned.
.PP
\fIget_pvd_type\fR
.IX Subsection "get_pvd_type"
.PP
\fIget_pvd_id\fR
.IX Subsection "get_pvd_id"
.PP
\fIget_pvd_space_size\fR
.IX Subsection "get_pvd_space_size"
.PP
\fIget_pvd_block_size\fR
.IX Subsection "get_pvd_block_size"
.PP
\fIget_pvd_version\fR
.IX Subsection "get_pvd_version"
.PP
Return the primary volume id version number (of pvd).
If there is an error 0 is returned.
.PP
\fIget_system_id\fR
.IX Subsection "get_system_id"
.PP
Return a string containing the PVD's system id with trailing
blanks removed.
.PP
\fIifs_get_system_id\fR
.IX Subsection "ifs_get_system_id"
.PP
Get the system ID.  psz_system_id is set to undef if there
is some problem in getting this and 0 is returned.
.PP
\fIget_root_lsn\fR
.IX Subsection "get_root_lsn"
.PP
Return the LSN of the root directory for pvd.
If there is an error CDIO_INVALID_LSN is returned.
.PP
\fIget_volume_id\fR
.IX Subsection "get_volume_id"
.PP
Return the PVD's volume ID.
.PP
\fIifs_get_volume_id\fR
.IX Subsection "ifs_get_volume_id"
.PP
Get the system ID.  psz_system_id is set to undef if there
s some problem in getting this and 0 is returned.
.PP
\fIget_volumeset_id\fR
.IX Subsection "get_volumeset_id"
.PP
Return the PVD's volumeset ID.
undef is returned if there is some problem in getting this.
.PP
\fIifs_get_volumeset_id\fR
.IX Subsection "ifs_get_volumeset_id"
.PP
Get the systemset ID.  psz_systemset_id is set to undef if there
is some problem in getting this and 0 is returned.
.SS "Path Table Routines"
.IX Subsection "Path Table Routines"
\fIiso9660_pathtable_init\fR
.IX Subsection "iso9660_pathtable_init"
.PP
Zero out pathable. Do this first.
.PP
\fIpathtable_get_size\fR
.IX Subsection "pathtable_get_size"
.PP
\fIpathtable_l_add_entry\fR
.IX Subsection "pathtable_l_add_entry"
.PP
\fIpathtable_m_add_entry\fR
.IX Subsection "pathtable_m_add_entry"
.PP
\fIset_evd\fR
.IX Subsection "set_evd"
.SS Miscellaneous
.IX Subsection "Miscellaneous"
\fIget_joliet_level\fR
.IX Subsection "get_joliet_level"
.PP
Return the Joliet level recognized for p_iso.
.PP
\fIifs_is_xa\fR
.IX Subsection "ifs_is_xa"
.PP
Return 1 if ISO 9660 image has extended attrributes (XA).
.SH METHODS
.IX Header "METHODS"
.SS this
.IX Subsection "this"
This seems to be an artifact of SWIG.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://www.gnu.org/software/libcdio> has documentation on
libcdio including the a manual and the API via doxygen.
.SH AUTHORS
.IX Header "AUTHORS"
Rocky Bernstein \f(CW\*(C`<rocky at cpan.org>\*(C'\fR.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006, 2008, 2011, 2017 Rocky Bernstein <rocky@cpan.org>
.PP
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.
.PP
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.
.PP
You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.