RPM(8) Red Hat Linux RPM(8)

NAME rpm - RPM Package Manager

SYNOPSIS QUERYING AND VERIFYING PACKAGES: rpm {-q|--query} [select-options] [query-options]

rpm {-V|--verify} [select-options] [verify-options]

rpm --import PUBKEY ...

rpm {-K|--checksig} [--nosignature] [--nodigest] PACKAGE_FILE ...

INSTALLING, UPGRADING, AND REMOVING PACKAGES: rpm {-i|--install} [install-options] PACKAGE_FILE ...

rpm {-U|--upgrade} [install-options] PACKAGE_FILE ...

rpm {-F|--freshen} [install-options] PACKAGE_FILE ...

rpm {-e|--erase} [--allmatches] [--nodeps] [--noscripts] [--notriggers] [--repackage] [--test] PACKAGE_NAME ...

MISCELLANEOUS: rpm {--initdb|--rebuilddb}

rpm {--addsign|--resign} PACKAGE_FILE ...

rpm {--querytags|--showrc}

rpm {--setperms|--setugids} PACKAGE_NAME ...

select-options [PACKAGE_NAME] [-a,--all] [-f,--file FILE] [-g,--group GROUP] {-p,--package PACKAGE_FILE] [--fileid MD5] [--hdrid SHA1] [--pkgid MD5] [--tid TID] [--querybynumber HDRNUM] [--triggeredby PACKAGE_NAME] [--whatprovides CAPABILITY] [--whatrequires CAPABILITY]

query-options [--changelog] [-c,--configfiles] [-d,--docfiles] [--dump] [--filesbypkg] [-i,--info] [--last] [-l,--list] [--provides] [--qf,--queryformat QUERYFMT] [-R,--requires] [--scripts] [-s,--state] [--triggers,--triggerscripts]

verify-options [--nodeps] [--nofiles] [--noscripts] [--nodigest] [--nosignature] [--nolinkto] [--nomd5] [--nosize] [--nouser] [--nogroup] [--nomtime] [--nomode] [--nordev]

install-options [--aid] [--allfiles] [--badreloc] [--excludepath OLDPATH] [--excludedocs] [--force] [-h,--hash] [--ignoresize] [--ignorearch] [--ignoreos] [--includedocs] [--justdb] [--nodeps] [--nodigest] [--nosignature] [--nosuggest] [--noorder] [--noscripts] [--notriggers] [--oldpackage] [--percent] [--prefix NEWPATH] [--relocate OLDPATH=NEWPATH] [--repackage] [--replacefiles] [--replacepkgs] [--test]

DESCRIPTION rpm is a powerful Package Manager, which can be used to build, install, query, verify, update, and erase individual software packages. A pack- age consists of an archive of files and meta-data used to install and erase the archive files. The meta-data includes helper scripts, file attributes, and descriptive information about the package. Packages come in two varieties: binary packages, used to encapsulate software to be installed, and source packages, containing the source code and recipe necessary to produce binary packages.

One of the following basic modes must be selected: Query, Verify, Sig- nature Check, Install/Upgrade/Freshen, Uninstall, Initialize Database, Rebuild Database, Resign, Add Signature, Set Owners/Groups, Show Query- tags, and Show Configuration.

GENERAL OPTIONS These options can be used in all the different modes.

-?, --help Print a longer usage message then normal.

--version Print a single line containing the version number of rpm being used.

--quiet Print as little as possible - normally only error messages will be displayed.

-v Print verbose information - normally routine progress messages will be displayed.

-vv Print lots of ugly debugging information.

--rcfile FILELIST Each of the files in the colon separated FILELIST is read sequentially by rpm for configuration information. Only the first file in the list must exist, and tildes will be expanded to the value of $HOME. The default FILELIST is /usr/lib/rpm/rpmrc:/usr/lib/rpm/red- hat/rpmrc:/etc/rpmrc:~/.rpmrc.

--pipe CMD Pipes the output of rpm to the command CMD.

--dbpath DIRECTORY Use the database in DIRECTORY rather than the default path /var/lib/rpm

--root DIRECTORY Use the file system tree rooted at DIRECTORY for all operations. Note that this means the database within DIRECTORY will be used for dependency checks and any scriptlet(s) (e.g. %post if installing, or %prep if building, a package) will be run after a chroot(2) to DIRECTORY.

-D, --defineMACRO EXPR Defines MACRO with value EXPR.

-E, --evalEXPR Prints macro expansion of EXPR.

INSTALL AND UPGRADE OPTIONS The general form of an rpm install command is

rpm {-i|--install} [install-options] PACKAGE_FILE ...

This installs a new package.

The general form of an rpm upgrade command is

rpm {-U|--upgrade} [install-options] PACKAGE_FILE ...

This upgrades or installs the package currently installed to a newer version. This is the same as install, except all other version(s) of the package are removed after the new package is installed.

rpm {-F|--freshen} [install-options] PACKAGE_FILE ...

This will upgrade packages, but only if an earlier version currently exists. The PACKAGE_FILE may be specified as an ftp or http URL, in which case the package will be downloaded before being installed. See FTP/HTTP OPTIONS for information on rpms internal ftp and http client support.

--aid Add suggested packages to the transaction set when needed.

--allfiles Installs or upgrades all the missingok files in the package, regardless if they exist.

--badreloc Used with --relocate, permit relocations on all file paths, not just those OLDPATHs included in the binary package relocation hint(s).

--excludepath OLDPATH Dont install files whose name begins with OLDPATH.

--excludedocs Don t install any files which are marked as documentation (which includes man pages and texinfo documents).

--force Same as using --replacepkgs, --replacefiles, and --oldpackage.

-h, --hash Print 50 hash marks as the package archive is unpacked. Use with -v|--verbose for a nicer display.

--ignoresize Dont check mount file systems for sufficient disk space before installing this package.

--ignorearch Allow installation or upgrading even if the architectures of the binary package and host dont match.

--ignoreos Allow installation or upgrading even if the operating systems of the binary package and host dont match.

--includedocs Install documentation files. This is the default behavior.

--justdb Update only the database, not the filesystem.

--nodigest Dont verify package or header digests when reading.

--nosignature Don t verify package or header signatures when reading.

--nodeps Dont do a dependency check before installing or upgrading a package.

--nosuggest Don t suggest package(s) that provide a missing dependency.

--noorder Dont reorder the packages for an install. The list of packages would normally be reordered to satisfy dependencies.

--noscripts

--nopre

--nopost

--nopreun

--nopostun Dont execute the scriptlet of the same name. The --noscripts option is equivalent to

--nopre --nopost --nopreun --nopostun

and turns off the execution of the corresponding %pre, %post, %preun, and %postun scriptlet(s).

--notriggers

--notriggerin

--notriggerun

--notriggerpostun Dont execute any trigger scriptlet of the named type. The --notriggers option is equivalent to

--notriggerin --notriggerun --notriggerpostun

and turns off execution of the corresponding %triggerin, %trig- gerun, and %triggerpostun scriptlet(s).

--oldpackage Allow an upgrade to replace a newer package with an older one.

--percent Print percentages as files are unpacked from the package archive. This is intended to make rpm easy to run from other tools.

--prefix NEWPATH For relocatable binary packages, translate all file paths that start with the installation prefix in the package relocation hint(s) to NEWPATH.

--relocate OLDPATH=NEWPATH For relocatable binary packages, translate all file paths that start with OLDPATH in the package relocation hint(s) to NEWPATH. This option can be used repeatedly if several OLDPATHs in the package are to be relocated.

--repackage Re-package the files before erasing. The previously installed package will be named according to the macro %_repack- age_name_fmt and will be created in the directory named by the macro %_repackage_dir (default value is /var/spool/repackage).

--replacefiles Install the packages even if they replace files from other, already installed, packages.

--replacepkgs Install the packages even if some of them are already installed on this system.

--test Do not install the package, simply check for and report poten- tial conflicts.

ERASE OPTIONS The general form of an rpm erase command is

rpm {-e|--erase} [--allmatches] [--nodeps] [--noscripts] [--notriggers] [--repackage] [--test] PACKAGE_NAME ...

The following options may also be used:

--allmatches Remove all versions of the package which match PACKAGE_NAME. Normally an error is issued if PACKAGE_NAME matches multiple packages.

--nodeps Dont check dependencies before uninstalling the packages.

--noscripts

--nopreun

--nopostun Don t execute the scriptlet of the same name. The --noscripts option during package erase is equivalent to

--nopreun --nopostun

and turns off the execution of the corresponding %preun, and %postun scriptlet(s).

--notriggers

--notriggerun

--notriggerpostun Don t execute any trigger scriptlet of the named type. The --notriggers option is equivalent to

--notriggerun --notriggerpostun

and turns off execution of the corresponding %triggerun, and %triggerpostun scriptlet(s).

--repackage Re-package the files before erasing. The previously installed package will be named according to the macro %_repack- age_name_fmt and will be created in the directory named by the macro %_repackage_dir (default value is /var/spool/repackage).

--test Dont really uninstall anything, just go through the motions. Useful in conjunction with the -vv option for debugging.

QUERY OPTIONS The general form of an rpm query command is

rpm {-q|--query} [select-options] [query-options]

You may specify the format that package information should be printed in. To do this, you use the

--qf|--queryformat QUERYFMT

option, followed by the QUERYFMT format string. Query formats are mod- ified versions of the standard printf(3) formatting. The format is made up of static strings (which may include standard C character escapes for newlines, tabs, and other special characters) and printf(3) type formatters. As rpm already knows the type to print, the type specifier must be omitted however, and replaced by the name of the header tag to be printed, enclosed by {} characters. Tag names are case insensitive, and the leading RPMTAG_ portion of the tag name may be omitted as well.

Alternate output formats may be requested by following the tag with :typetag. Currently, the following types are supported:

:armor Wrap a public key in ASCII armor.

:base64 Encode binary data using base64.

:date Use strftime(3) "%c" format.

:day Use strftime(3) "%a %b %d %Y" format.

:depflags Format dependency flags.

:fflags Format file flags.

:hex Format in hexadecimal.

:octal Format in octal.

:perms Format file permissions.

:shescape Escape single quotes for use in a script.

:triggertype Display trigger suffix.

For example, to print only the names of the packages queried, you could use %{NAME} as the format string. To print the packages name and dis- tribution information in two columns, you could use %-30{NAME}%{DISTRI- BUTION}. rpm will print a list of all of the tags it knows about when it is invoked with the --querytags argument.

There are two subsets of options for querying: package selection, and information selection.

PACKAGE SELECTION OPTIONS: PACKAGE_NAME Query installed package named PACKAGE_NAME.

-a, --all Query all installed packages.

-f, --file FILE Query package owning FILE.

--fileid MD5 Query package that contains a given file identifier, i.e. the MD5 digest of the file contents.

-g, --group GROUP Query packages with the group of GROUP.

--hdrid SHA1 Query package that contains a given header identifier, i.e. the SHA1 digest of the immutable header region.

-p, --package PACKAGE_FILE Query an (uninstalled) package PACKAGE_FILE. The PACKAGE_FILE may be specified as an ftp or http style URL, in which case the package header will be downloaded and queried. See FTP/HTTP OPTIONS for information on rpms internal ftp and http client support. The PACKAGE_FILE argument(s), if not a binary package, will be interpreted as an ASCII package manifest. Comments are permitted, starting with a #, and each line of a package mani- fest file may include white space separated glob expressions, including URLs with remote glob expressions, that will be expanded to paths that are substituted in place of the package manifest as additional PACKAGE_FILE arguments to the query.

--pkgid MD5 Query package that contains a given package identifier, i.e. the MD5 digest of the combined header and payload contents.

--querybynumber HDRNUM Query the HDRNUMth database entry directly; this is useful only for debugging.

--specfile SPECFILE Parse and query SPECFILE as if it were a package. Although not all the information (e.g. file lists) is available, this type of query permits rpm to be used to extract information from spec files without having to write a specfile parser.

--tid TID Query package(s) that have a given TID transaction identifier. A unix time stamp is currently used as a transaction identifier. All package(s) installed or erased within a single transaction have a common identifier.

--triggeredby PACKAGE_NAME Query packages that are triggered by package(s) PACKAGE_NAME.

--whatprovides CAPABILITY Query all packages that provide the CAPABILITY capability.

--whatrequires CAPABILITY Query all packages that requires CAPABILITY for proper function- ing.

PACKAGE QUERY OPTIONS: --changelog Display change information for the package.

-c, --configfiles List only configuration files (implies -l).

-d, --docfiles List only documentation files (implies -l).

--dump Dump file information as follows (implies -l):

path size mtime md5sum mode owner group isconfig isdoc rdev symlink

--filesbypkg List all the files in each selected package.

-i, --info Display package information, including name, version, and description. This uses the --queryformat if one was specified.

--last Orders the package listing by install time such that the latest packages are at the top.

-l, --list List files in package.

--provides List capabilities this package provides.

-R, --requires List packages on which this package depends.

--scripts List the package specific scriptlet(s) that are used as part of the installation and uninstallation processes.

-s, --state Display the states of files in the package (implies -l). The state of each file is one of normal, not installed, or replaced.

--triggers, --triggerscripts Display the trigger scripts, if any, which are contained in the package.

VERIFY OPTIONS The general form of an rpm verify command is

rpm {-V|--verify} [select-options] [verify-options]

Verifying a package compares information about the installed files in the package with information about the files taken from the package metadata stored in the rpm database. Among other things, verifying compares the size, MD5 sum, permissions, type, owner and group of each file. Any discrepancies are displayed. Files that were not installed from the package, for example, documentation files excluded on instal- lation using the "--excludedocs" option, will be silently ignored.

The package selection options are the same as for package querying (including package manifest files as arguments). Other options unique to verify mode are:

--nodeps Dont verify dependencies of packages.

--nodigest Dont verify package or header digests when reading.

--nofiles Dont verify any attributes of package files.

--noscripts Don t execute the %verifyscript scriptlet (if any).

--nosignature Dont verify package or header signatures when reading.

--nolinkto

--nomd5

--nosize

--nouser

--nogroup

--nomtime

--nomode

--nordev Dont verify the corresponding file attribute.

The format of the output is a string of 8 characters, a possible attribute marker:

c %config configuration file. d %doc documentation file. g %ghost file (i.e. the file contents are not included in the package payload). l %license license file. r %readme readme file.

from the package header, followed by the file name. Each of the 8 characters denotes the result of a comparison of attribute(s) of the file to the value of those attribute(s) recorded in the database. A single "." (period) means the test passed, while a single "?" (question mark) indicates the test could not be performed (e.g. file permissions prevent reading). Otherwise, the (mnemonically emBoldened) character denotes failure of the corresponding --verify test:

S file Size differs M Mode differs (includes permissions and file type) 5 MD5 sum differs D Device major/minor number mismatch L readLink(2) path mismatch U User ownership differs G Group ownership differs T mTime differs

DIGITAL SIGNATURE AND DIGEST VERIFICATION The general forms of rpm digital signature commands are

rpm --import PUBKEY ...

rpm {--checksig} [--nosignature] [--nodigest] PACKAGE_FILE ...

The --checksig option checks all the digests and signatures contained in PACKAGE_FILE to ensure the integrity and origin of the package. Note that signatures are now verified whenever a package is read, and --checksig is useful to verify all of the digests and signatures asso- ciated with a package.

Digital signatures cannot be verified without a public key. An ASCII armored public key can be added to the rpm database using --import. An imported public key is carried in a header, and key ring management is performed exactly like package management. For example, all currently imported public keys can be displayed by:

rpm -qa gpg-pubkey*

Details about a specific public key, when imported, can be displayed by querying. Heres information about the Red Hat GPG/DSA key:

rpm -qi gpg-pubkey-db42a60e

Finally, public keys can be erased after importing just like packages. Heres how to remove the Red Hat GPG/DSA key

rpm -e gpg-pubkey-db42a60e

SIGNING A PACKAGE rpm --addsign|--resign PACKAGE_FILE ...

Both of the --addsign and --resign options generate and insert new sig- natures for each package PACKAGE_FILE given, replacing any existing signatures. There are two options for historical reasons, there is no difference in behavior currently.

USING GPG TO SIGN PACKAGES In order to sign packages using GPG, rpm must be configured to run GPG and be able to find a key ring with the appropriate keys. By default, rpm uses the same conventions as GPG to find key rings, namely the $GNUPGHOME environment variable. If your key rings are not located where GPG expects them to be, you will need to configure the macro %_gpg_path to be the location of the GPG key rings to use.

For compatibility with older versions of GPG, PGP, and rpm, only V3 OpenPGP signature packets should be configured. Either DSA or RSA ver- ification algorithms can be used, but DSA is preferred.

If you want to be able to sign packages you create yourself, you also need to create your own public and secret key pair (see the GPG man- ual). You will also need to configure the rpm macros

%_signature The signature type. Right now only gpg and pgp are supported.

%_gpg_name The name of the "user" whose key you wish to use to sign your packages.

For example, to be able to use GPG to sign packages as the user "John Doe <jdoe@foo.com>" from the key rings located in /etc/rpm/.gpg using the executable /usr/bin/gpg you would include

%_signature gpg %_gpg_path /etc/rpm/.gpg %_gpg_name John Doe <jdoe@foo.com> %_gpgbin /usr/bin/gpg

in a macro configuration file. Use /etc/rpm/macros for per-system con- figuration and ~/.rpmmacros for per-user configuration.

REBUILD DATABASE OPTIONS The general form of an rpm rebuild database command is

rpm {--initdb|--rebuilddb} [-v] [--dbpath DIRECTORY] [--root DIRECTORY]

Use --initdb to create a new database if one doesnt already exist (existing database is not overwritten), use --rebuilddb to rebuild the database indices from the installed package headers.

SHOWRC The command

rpm --showrc

shows the values rpm will use for all of the options are currently set in rpmrc and macros configuration file(s).

FTP/HTTP OPTIONS rpm can act as an FTP and/or HTTP client so that packages can be queried or installed from the internet. Package files for install, upgrade, and query operations may be specified as an ftp or http style URL:

ftp://USER:PASSWORD@HOST:PORT/path/to/package.rpm

If the :PASSWORD portion is omitted, the password will be prompted for (once per user/hostname pair). If both the user and password are omit- ted, anonymous ftp is used. In all cases, passive (PASV) ftp transfers are performed.

rpm allows the following options to be used with ftp URLs:

--ftpproxy HOST The host HOST will be used as a proxy server for all ftp trans- fers, which allows users to ftp through firewall machines which use proxy systems. This option may also be specified by config- uring the macro %_ftpproxy.

--ftpport PORT The TCP PORT number to use for the ftp connection on the proxy ftp server instead of the default port. This option may also be specified by configuring the macro %_ftpport.

rpm allows the following options to be used with http URLs:

--httpproxy HOST The host HOST will be used as a proxy server for all http trans- fers. This option may also be specified by configuring the macro %_httpproxy.

--httpport PORT The TCP PORT number to use for the http connection on the proxy http server instead of the default port. This option may also be specified by configuring the macro %_httpport.

LEGACY ISSUES Executing rpmbuild The build modes of rpm are now resident in the /usr/bin/rpmbuild exe- cutable. Although legacy compatibility provided by the popt aliases below has been adequate, the compatibility is not perfect; hence build mode compatibility through popt aliases is being removed from rpm. Install the package containing rpmbuild (usually rpm-build) and see rpmbuild(8) for documentation of all the rpm build modes previously documented here in rpm(8).

Add the following lines to /etc/popt if you wish to continue invoking rpmbuild from the rpm command line:

rpm exec --bp rpmb -bp rpm exec --bc rpmb -bc rpm exec --bi rpmb -bi rpm exec --bl rpmb -bl rpm exec --ba rpmb -ba rpm exec --bb rpmb -bb rpm exec --bs rpmb -bs rpm exec --tp rpmb -tp rpm exec --tc rpmb -tc rpm exec --ti rpmb -ti rpm exec --tl rpmb -tl rpm exec --ta rpmb -ta rpm exec --tb rpmb -tb rpm exec --ts rpmb -ts rpm exec --rebuild rpmb --rebuild rpm exec --recompile rpmb --recompile rpm exec --clean rpmb --clean rpm exec --rmsource rpmb --rmsource rpm exec --rmspec rpmb --rmspec rpm exec --target rpmb --target rpm exec --short-circuit rpmb --short-circuit

FILES rpmrc Configuration /usr/lib/rpm/rpmrc /usr/lib/rpm/redhat/rpmrc /etc/rpmrc ~/.rpmrc

Macro Configuration /usr/lib/rpm/macros /usr/lib/rpm/redhat/macros /etc/rpm/macros ~/.rpmmacros

Database /var/lib/rpm/Basenames /var/lib/rpm/Conflictname /var/lib/rpm/Dirnames /var/lib/rpm/Filemd5s /var/lib/rpm/Group /var/lib/rpm/Installtid /var/lib/rpm/Name /var/lib/rpm/Packages /var/lib/rpm/Providename /var/lib/rpm/Provideversion /var/lib/rpm/Pubkeys /var/lib/rpm/Removed /var/lib/rpm/Requirename /var/lib/rpm/Requireversion /var/lib/rpm/Sha1header /var/lib/rpm/Sigmd5 /var/lib/rpm/Triggername

Temporary /var/tmp/rpm*

SEE ALSO popt(3), rpm2cpio(8), rpmbuild(8),

rpm --help - as rpm supports customizing the options via popt aliases its impossible to guarantee that whats described in the manual matches whats available.

http://www.rpm.org/ <URL:http://www.rpm.org/>

AUTHORS Marc Ewing <marc@redhat.com> Jeff Johnson <jbj@redhat.com> Erik Troan <ewt@redhat.com>

Red Hat, Inc. 09 June 2002 RPM(8) CDDA2WAV(1) CDDA2WAV(1)

NAME cdda2wav - a sampling utility that dumps CD audio data into wav sound files

SYNOPSIS cdda2wav [-c chans] [-s] [-m] [-b bits] [-r rate] [-a divider] [-t track[+endtrack]] [-i index] [-o offset] [-d duration] [-x] [-q] [-w] [-v optlist] [-V] [-Q] [-J] [-L cddbmode] [-R] [-P sectors] [-F] [-G] [-T] [-e] [-p percentage] [-n sectors] [-l buffers] [-N] [-J] [-H] [-g] [-B] [-D device] [-A auxdevice] [-I interface] [-O audiotype] [-C input-endianess] [-E output-endianess] [-M count] [-S speed] [-para- noia] [cddbp-server=servername] [cddbp-port=portnumber] [filename(s) or directories]

DESCRIPTION cdda2wav can retrieve audio tracks from CDROM drives (see README for a list of drives) that are capable of reading audio data digitally to the host (CDDA).

OPTIONS dev=device

-D device

-device device uses device as the source for CDDA reading. For example /dev/cdrom for the cooked_ioctl interface and Bus,ID,Lun for the generic_scsi interface. The device has to correspond with the interface setting (see below).

Using the cooked_ioctl is not recommended as this makes cdda2wav mainly depend on the audio extraction quality of the operating system which is usually extremely bad.

The setting of the environment variable CDDA_DEVICE is overrid- den by this option.

-A auxdevice

-auxdevice auxdevice uses auxdevice as CDROM drive for ioctl usage.

-I interface

-interface interface specifies the interface for CDROM access: generic_scsi or (on Linux, and FreeBSD systems) cooked_ioctl.

-c channels --channels uses 1 for mono, or 2 for stereo recording, or s for stereo recording with both channels swapped.

-s --stereo sets to stereo recording.

-m --mono sets to mono recording.

-x --max sets maximum (CD) quality.

-b bits --bits-per-sample sets bits per sample per channel: 8, 12 or 16.

-r rate --rate sets rate in samples per second. Possible values are listed with the -R option.

-a divider --divider sets rate to 44100Hz / divider. Possible values are listed with the -R option.

-R --dump-rates shows a list of all sample rates and their dividers.

-P sectors --set-overlap sets the initial number of overlap sectors for jitter correc- tion.

-n sectors --sectors-per-request reads sectors per request.

-l buffers --buffers-in-ring uses a ring buffer with buffers total.

-t track+endtrack --track selects the start track and optionally the end track.

-i index --index selects the start index.

-o offset --offset starts offset sectors behind start track (one sector equivalents 1/75 seconds).

-O audiotype --output-format can be wav (for wav files) or aiff (for apple/sgi aiff files) or aifc (for apple/sgi aifc files) or au or sun (for sun .au PCM files) or cdr or raw (for headerless files to be used for cd writers).

-C endianess --cdrom-endianess sets endianess of the input samples to little, big or guess to override defaults.

-E endianess --output-endianess sets endianess of the output samples to little or big to override defaults.

-d duration --duration sets recording time in seconds or frames. Frames (sectors) are indicated by a f suffix (like 75f for 75 sectors). 0 sets the time for whole track.

-B --bulk --alltracks copies each track into a seperate file.

-w --wait waits for signal, then start recording.

-F --find-extremes finds extrem amplitudes in samples.

-G --find-mono finds if input samples are in mono.

-T --deemphasize undo the effect of pre-emphasis in the input samples.

-e --echo copies audio data to sound device e.g. /dev/dsp.

-p percentage --set-pitch changes pitch of audio data copied to sound device.

-v itemlist --verbose-level prints verbose information about the CD. Level is a list of comma seperated suboptions. Each suboption controls the type of information to be reported.

+----------+----------------------------------------------------------------+ |Suboption | Description | +----------+----------------------------------------------------------------+ | disable | no information is given, warnings appear however | | all | all information is given | | toc | show table of contents | | summary | show a summary of the recording parameters | | indices | determine and display index offsets | | catalog | retrieve and display the media catalog number MCN | | trackid | retrieve and display all Intern. Standard Recording Codes ISRC | | sectors | show the table of contents in start sector notation | | titles | show the table of contents with track titles (when available) | +----------+----------------------------------------------------------------+ -N --no-write does not write to a file, it just reads (for debugging pur- poses).

-J --info-only does not write to a file, it just gives information about the disc.

-L cddb mode --cddb does a cddbp album- and track title lookup based on the cddb id. The parameter cddb mode defines how multiple entries shall be handled.

+----------+-----------------------------------------------------------+ |Parameter | Description | +----------+-----------------------------------------------------------+ | 0 | interactive mode. The user selects the entry to use. | | 1 | first fit mode. The first entry is taken unconditionally. | +----------+-----------------------------------------------------------+ cddbp-server=servername sets the server to be contacted for title lookups.

cddbp-port=portnumber sets the port number to be used for title lookups.

-H --no-infofile does not write an info file and a cddb file.

-g --gui formats the output to be better parsable by gui frontends.

-M count --md5 enables calculation of MD-5 checksum for count bytes from a beginning of a track.

-S speed --speed sets the cdrom device to one of the selectable speeds for read- ing.

-q --quiet quiet operation, no screen output.

-V --verbose-SCSI enable SCSI command logging to the console. This is mainly used for debugging.

-Q --silent-SCSI suppress SCSI command error reports to the console. This is mainly used for guis.

-scanbus Scan all SCSI devices on all SCSI busses and print the inquiry strings. This option may be used to find SCSI address of the CD/DVD-Recorder on a system. The numbers printed out as labels are computed by: bus * 100 + target

-paranoia use the paranoia library instead of cdda2wav s routines for reading.

-h --help display version of cdda2wav on standard output.

Defaults depend on the Makefile and environment variable settings (currently CDDA_DEVICE ).

ENVIRONMENT VARIABLES CDDA_DEVICE is used to set the device name. The device naming is com- patible with Joerg Schillings cdrecord package.

CDDBP_SERVER is used for cddbp title lookups when supplied.

CDDBP_PORT is used for cddbp title lookups when supplied.

RSH If the RSH environment variable is present, the remote connec- tion will not be created via rcmd(3) but by calling the program pointed to by RSH. Use e.g. RSH=/usr/bin/ssh to create a secure shell connection.

Note that this forces cdda2wav to create a pipe to the rsh(1) program and disallows cdda2wav to directly access the network socket to the remote server. This makes it impossible to set up performance parameters and slows down the connection compared to a root initiated rcmd(3) connection.

RSCSI If the RSCSI environment variable is present, the remote SCSI server will not be the program /opt/schily/sbin/rscsi but the program pointed to by RSCSI. Note that the remote SCSI server program name will be ignored if you log in using an account that has been created with a remote SCSI server program as login shell.

RETURN VALUES cdda2wav uses the following exit codes to indicate various degress of success:

+---------+--------------------------------------------------------------------+ |Exitcode | Description | +---------+--------------------------------------------------------------------+ | 0 | no errors encountered, successful operation. | | 1 | usage or syntax error. cdda2wav got inconsistent arguments. | | 2 | permission (un)set errors. permission changes failed. | | 3 | read errors on the cdrom/burner device encountered. | | 4 | write errors while writing one of the output files encountered. | | 5 | errors with soundcard handling (initialization/write). | | 6 | errors with stat() system call on the read device (cooked ioctl). | | 7 | pipe communication errors encountered (in forked mode). | | 8 | signal handler installation errors encountered. | | 9 | allocation of shared memory failed (in forked mode). | | 10 | dynamic heap memory allocation failed. | | 11 | errors on the audio cd medium encountered. | | 12 | device open error in ioctl handling detected. | | 13 | race condition in ioctl interface handling detected. | | 14 | error in ioctl() operation encountered. | | 15 | internal error encountered. Please report back!!! | | 16 | error in semaphore operation encountered (install / request). | | 17 | could not get the scsi transfer buffer. | | 18 | could not create pipes for process communication (in forked mode). | +---------+--------------------------------------------------------------------+ DISCUSSION cdda2wav is able to read parts of an audio CD or multimedia CDROM (con- taining audio parts) directly digitally. These parts can be written to a file, a pipe, or to a sound device.

cdda2wav stands for CDDA to WAV (where CDDA stands for compact disc digital audio and WAV is a sound sample format introduced by MS Win- dows). It allows copying CDDA audio data from the CDROM drive into a file in WAV or other formats.

The latest versions try to get higher real-time scheduling priorities to ensure smooth (uninterrupted) operation. These priorities are avail- able for super users and are higher than those of normal processes. Thus delays are minimized.

If your CDROM is on device DEV and it is loaded with an audio CD, you may simply invoke cdda2wav dev=DEV and it will create the sound file audio.wav recording the whole track beginning with track 1 in stereo at 16 bit at 44100 Hz sample rate, if your file system has enough space free. Otherwise recording time will be limited. For details see files README and README.INSTALL

HINTS ON OPTIONS Options Most of the options are used to control the format of the WAV file. In the following text all of them are described.

Select Device -D device selects the CDROM drive device to be used. The speci- fier given should correspond to the selected interface (see below). CHANGE! For the cooked_ioctl interface this is the cdrom device descriptor as before. The SCSI devices used with the generic SCSI interface however are now addressed with their SCSI-Bus, SCSI-Id, and SCSI-Lun instead of the generic SCSI device descriptor!!! One example for a SCSI CDROM drive on bus 0 with SCSI ID 3 and lun 0 is -D0,3,0.

Select Auxiliary device -A auxdevice is necessary for CD-Extra handling. For Non-SCSI- CDROM drives this is the same device as given by -D (see above). For SCSI-CDROM drives it is the CDROM drive (SCSI) device (i.e. /dev/sr0 ) corresponding to the SCSI device (i.e. 0,3,0 ). It has to match the device used for sampling.

Select Interface -I interface selects the CDROM drive interface. For SCSI drives use generic_scsi (cooked_ioctl may not yet be available for all devices): generic_scsi and cooked_ioctl. The first uses the generic SCSI interface, the latter uses the ioctl of the CDROM driver. The latter variant works only when the kernel driver supports CDDA reading. This entry has to match the selected CDROM device (see above).

Enable echo to soundcard -e copies audio data to the sound card while recording, so you hear it nearly simultaneously. The soundcard gets the same data that is recorded. This is time critical, so it works best with the -q option. To use cdda2wav as a pseudo CD player without recording in a file you could use cdda2wav -q -e -t2 -d0 -N to play the whole second track. This feature reduces the recording speed to at most onefold speed. You cannot make better record- ings than your sound card can play (since the same data is used).

Change pitch of echoed audio -p percentage changes the pitch of all audio echoed to a sound card. Only the copy to the soundcard is affected, the recorded audio samples in a file remain the same. Normal pitch, which is the default, is given by 100%. Lower percentages correspond to lower pitches, i.e. -p 50 transposes the audio output one octave lower. See also the script pitchplay as an example. This option was contributed by Raul Sobon.

Select mono or stereo recording -m or -c 1 selects mono recording (both stereo channels are mixed), -s or -c 2 or -c s selects stereo recording. Parameter s will swap both sound channels.

Select maximum quality -x will set stereo, 16 bits per sample at 44.1 KHz (full CD quality). Note that other format options given later can change this setting.

Select sample quality -b 8 specifies 8 bit (1 Byte) for each sample in each channel; -b 12 specifies 12 bit (2 Byte) for each sample in each channel; -b 16 specifies 16 bit (2 Byte) for each sample in each channel (Ensure that your sample player or sound card is capable of playing 12-bit or 16-bit samples). Selecting 12 or 16 bits dou- bles file size. 12-bit samples are aligned to 16-bit samples, so they waste some disk space.

Select sample rate -r samplerate selects a sample rate. samplerate can be in a range between 44100 and 900. Option -R lists all available rates.

Select sample rate divider -a divider selects a sample rate divider. divider can be mini- mally 1 and maximally 50.5 and everything between in steps of 0.5. Option -R lists all available rates.

To make the sound smoother at lower sampling rates, cdda2wav sums over n samples (where n is the specific dividend). So for 22050 Hertz output we have to sum over 2 samples, for 900 Hertz we have to sum over 49 samples. This cancels higher frequen- cies. Standard sector size of an audio CD (ignoring additional information) is 2352 Bytes. In order to finish summing for an output sample at sector boundaries the rates above have to be choosen. Arbitrary sampling rates in high quality would require some interpolation scheme, which needs much more sophisticated programming.

List a table of all sampling rates -R shows a list of all sample rates and their dividers. Dividers can range from 1 to 50.5 in steps of 0.5.

Select start track and optionally end track -t n+m selects n as the start track and optionally m as the last track of a range to be recorded. These tracks must be from the table of contents. This sets the track where recording begins. Recording can advance through the following tracks as well (lim- ited by the optional end track or otherwise depending on record- ing time). Whether one file or different files are then created depends on the -B option (see below).

Select start index -i n selects the index to start recording with. Indices other than 1 will invoke the index scanner, which will take some time to find the correct start position. An offset may be given addi- tionally (see below).

Set recording time -d n sets recording time to n seconds or set recording time for whole track if n is zero. In order to specify the duration in frames (sectors) also, the argument can have an appended f. Then the numerical argument is to be taken as frames (sectors) rather than seconds. Please note that if track ranges are being used they define the recording time as well thus overriding any -d option specified times.

Recording time is defined as the time the generated sample will play (at the defined sample rate). Since its related to the amount of generated samples, its not the time of the sampling process itself (which can be less or more). Its neither strictly coupled with the time information on the audio CD (shown by your hifi CD player). Differences can occur by the usage of the -o option (see below). Notice that recording time will be shortened, unless enough disk space exists. Recording can be aborted at anytime by pressing the break character (sig- nal SIGQUIT).

Record all tracks of a complete audio CD in seperate files -B copies each track into a seperate file. A base name can be given. File names have an appended track number and an extension corresponding to the audio format. To record all audio tracks of a CD, use a sufficient high duration (i.e. -d99999).

Set start sector offset -o sectors increments start sector of the track by sectors. By this option you are able to skip a certain amount at the beginning of a track so you can pick exactly the part you want. Each sector runs for 1/75 seconds, so you have very fine con- trol. If your offset is so high that it would not fit into the current track, a warning message is issued and the offset is ignored. Recording time is not reduced. (To skip introductory quiet passages automagically, use the -w option see below.)

Wait for signal option -w Turning on this option will suppress all silent output at startup, reducing possibly file size. cdda2wav will watch for any signal in the output signal and switches on writing to file.

Find extrem samples -F Turning on this option will display the most negative and the most positive sample value found during recording for both chan- nels. This can be useful for readjusting the volume. The values shown are not reset at track boundaries, they cover the complete sampling process. They are taken from the original samples and have the same format (i.e. they are independent of the selected output format).

Find if input samples are in mono -G If this option is given, input samples for both channels will be compared. At the end of the program the result is printed. Differences in the channels indicate stereo, otherwise when both channels are equal it will indicate mono.

Undo the pre-emphasis in the input samples -T Some older audio CDs are recorded with a modified frequency response called pre-emphasis. This is found mostly in classical recordings. The correction can be seen in the flags of the Table Of Contents often. But there are recordings, that show this set- ting only in the subchannels. If this option is given, the index scanner will be started, which reads the q-subchannel of each track. If pre-emphasis is indicated in the q-subchannel of a track, but not in the TOC, pre-emphasis will be assumed to be present, and subsequently a reverse filtering is done for this track before the samples are written into the audio file.

Set audio format -O audiotype can be wav (for wav files) or au or sun (for sun PCM files) or cdr or raw (for headerless files to be used for cd writers). All file samples are coded in linear pulse code modu- lation (as done in the audio compact disc format). This holds for all audio formats. Wav files are compatible to Wind*ws sound files, they have lsb,msb byte order as being used on the audio cd. The default filename extension is .wav . Sun type files are not like the older common logarithmically coded .au files, but instead as mentioned above linear PCM is used. The byte order is msb,lsb to be compatible. The default filename extension is .au . The AIFF and the newer variant AIFC from the Apple/SGI world store their samples in bigendian format (msb,lsb). In AIFC no compression is used. Finally the easiest format , the cdr aka raw format. It is done per default in msb,lsb byte order to satisfy the order wanted by most cd writ- ers. Since there is no header information in this format, the sample parameters can only be identified by playing the samples on a soundcard or similiar. The default filename extension is .cdr or .raw.

Select cdrom drive reading speed -S speed allows to switch the cdrom drive to a certain level of speed in order to reduce read errors. The argument is transfered verbatim to the drive. Details depend very much on the cdrom drives. An argument of 0 for example is often the default speed of the drive, a value of 1 often selects single speed.

Enable MD5 checksums -M count enables calculation of MD-5 checksum for count bytes from the beginning of a track. This was introduced for quick comparisons of tracks.

Use Montys libparanoia for reading of sectors -paranoia selects an alternate way of extracting audio sectors. Montys library is used with the following default options:

PARANOIA_MODE_FULL, but without PARANOIA_MODE_NEVERSKIP

for details see Montys libparanoia documentation. In this case the option -P has no effect.

Do linear or overlapping reading of sectors (This applies unless option -paranoia is used.) -P sectors sets the given number of sectors for initial overlap sampling for jitter correction. Two cases are to be distinguished. For nonzero values, some sectors are read twice to enable cdda2wavs jitter correction. If an argument of zero is given, no overlap sampling will be used. For nonzero overlap sectors cdda2wav dynamically adjusts the setting during sampling (like cdparanoia does). If no match can be found, cdda2wav retries the read with an increased overlap. If the amount of jitter is lower than the current overlapped samples, cdda2wav reduces the overlap set- ting, resulting in a higher reading speed. The argument given has to be lower than the total number of sectors per request (see option -n below). Cdda2wav will check this setting and issues a error message otherwise. The case of zero sectors is nice on low load situations or errorfree (perfect) cdrom drives and perfect (not scratched) audio cds.

Set the transfer size -n sectors will set the transfer size to the specified sectors per request.

Set number of ring buffer elements -l buffers will allocate the specified number of ring buffer elements.

Set endianess of input samples -C endianess will override the default settings of the input format. Endianess can be set explicitly to "little" or "big" or to the automatic endianess detection based on voting with "guess".

Set endianess of output samples -E endianess (endianess can be "little" or "big") will override the default settings of the output format.

Verbose option -v itemlist prints more information. A list allows selection of different information items.

disable keeps quiet

toc displays the table of contents

summary displays a summary of recording parameters

indices invokes the index scanner and displays start positions of indices

catalog retrieves and displays a media catalog number

trackid retrieves and displays international standard recording codes

sectors displays track start positions in absolute sector nota- tion

To combine several requests just list the suboptions seperated with commas.

The table of contents The display will show the table of contents with number of tracks and total time (displayed in mm:ss.hh format, mm=minutes, ss=seconds, hh=rounded 1/100 seconds). The following list dis- plays track number and track time for each entry. The summary gives a line per track describing the type of the track.

track preemphasis copypermitted tracktype chans

The track column holds the track number. preemphasis shows if that track has been given a non linear frequency response. NOTE: You can undo this effect with the -T option. copy-permit- ted indicates if this track is allowed to copy. tracktype can be data or audio. On multimedia CDs (except hidden track CDs) both of them should be present. channels is defined for audio tracks only. There can be two or four channels.

No file output -N this debugging option switches off writing to a file.

No infofile generation -H this option switches off creation of an info file and a cddb file.

Generation of simple output for gui frontends -g this option switches on simple line formatting, which is needed to support gui frontends (like xcd-roast).

Verbose SCSI logging -V this option switches on logging of SCSI commands. This will produce a lot of output (when SCSI devices are being used). This is needed for debugging purposes. The format is the same as being used with the cdrecord program from Joerg Schilling. I will not describe it here.

Quiet option -q suppresses all screen output except error messages. That reduces cpu time resources.

Just show information option -J does not write a file, it only prints information about the disc (depending on the -v option). This is just for information purposes.

CDDBP support Lookup album and track titles option -L cddbp mode Cdda2wav tries to retrieve performer, album-, and track titles from a cddbp server. The default server right now is freedb.freedb.org. It is planned to have more control over the server handling later. The parameter defines how multiple entries are handled:

0 interactive mode, the user chooses one of the entries.

1 take the first entry without asking.

Set server for title lookups cddbp-server servername When using -L or --cddb, the server being contacted can be set with this option.

Set portnumber for title lookups cddbp-port portnumber When using -L or --cddb, the server port being contacted can be set with this option.

HINTS ON USAGE Don t create samples you cannot read. First check your sample player software and sound card hardware. I experienced problems with very low sample rates (stereo <= 1575 Hz, mono <= 3675 Hz) when trying to play them with standard WAV players for sound blaster (maybe they are not legal in WAV format). Most CD-Writers insist on audio samples in a bigendian format. Now cdda2wav supports the -E endianess option to control the endianess of the written samples.

If your hardware is fast enough to run cdda2wav uninterrupted and your CD drive is one of the perfect ones, you will gain speed when switch- ing all overlap sampling off with the -P 0 option. Further fine tuning can be done with the -n sectors option. You can specify how much sec- tors should be requested in one go.

Cdda2wav supports pipes now. Use a filename of - to let cdda2wav output its samples to standard output.

Conversion to other sound formats can be done using the sox program package (although the use of sox -x to change the byte order of samples should be no more necessary; see option -E to change the output byte- order).

If you want to sample more than one track into different files in one run, this is currently possible with the -B option. When recording time exceeds the track limit a new file will be opened for the next track.

FILES Cdda2wav can generate a lot of files for various purposes.

Audio files:

There are audio files containing samples with default extensions These files are not generated when option (-N) is given. Multiple files may be written when the bulk copy option (-B) is used. Individual file names can be given as arguments. If the number of file names given is sufficient to cover all included audio tracks, the file names will be used verbatim. Otherwise, if there are less file names than files needed to write the included tracks, the part of the file name before the extension is extended with _dd where dd represents the current track number.

Cddb and Cdindex files:

If cdda2wav detects cd-extra or cd-text (album/track) title informa- tion, then .cddb and .cdindex files are generated unless suppressed by the option -H. They contain suitable formatted entries for submission to audio cd track title databases in the internet. The CDINDEX and CDDB(tm) systems are currently supported. For more information please visit www.musicbrainz.org and www.freedb.com.

Inf files:

The inf files are describing the sample files and the part from the audio cd, it was taken from. They are a means to transfer information to a cd burning program like cdrecord. For example, if the original audio cd had pre-emphasis enabled, and cdda2wav -T did remove the pre- emphasis, then the inf file has pre-emphasis not set (since the audio file does not have it anymore), while the .cddb and the .cdindex have pre-emphasis set as the original does.

WARNING IMPORTANT: it is prohibited to sell copies of copyrighted material by noncopyright holders. This program may not be used to circumvent copy- rights. The user acknowledges this constraint when using the software.

BUGS Generation of md5 checksums is currently broken.

Performance may not be optimal on slower systems.

The index scanner may give timeouts.

The resampling (rate conversion code) uses polynomial interpolation, which is not optimal.

Cdda2wav should use threads.

Cdda2wav currently cannot sample hidden audio tracks (track 1 index 0).

ACKNOWLEDGEMENTS Thanks goto Project MODE (http://www.mode.net/) and Fraunhofer Institut fuer integrierte Schaltungen (FhG-IIS) (http://www.iis.fhg.de/) for financial support. Plextor Europe and Ricoh Japan provided cdrom disk drives and cd burners which helped a lot to develop this software. Rammi has helped a lot with the debugging and showed a lot of stamina when hearing 100 times the first 16 seconds of the first track of the Krupps CD. Libparanoia contributed by Monty (Christopher Montgomery) xiphmont@mit.edu.

AUTHOR Heiko Eissfeldt heiko@colossus.escape.de

DATE 11 Sep 2002

CDDA2WAV(1)