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) CDRDAO(1) CDRDAO(1)

NAME cdrdao - writes audio CD-Rs in disc-at-once mode

SYNOPSIS cdrdao {show-toc|read-toc|read-cd|read-cddb|show-data|read-test|disk- info|msinfo|unlock|simulate|write|copy|blank} [--device device] [--source-device device] [--driver driver-id] [--source-driver driver- id] [--simulate] [--speed writing-speed] [--blank-mode mode] [--datafile file] [--read-raw] [--read-subchan [--no-mode2-mixed] mode] [--tao-source] [--tao-source-adjust link-blocks] [--fast-toc] [--buffers buffer-count] [--multi] [--overburn] [--eject] [--swap] [--session] [--force] [--reload] [--keepimage] [--on-the-fly] [--para- noia-mode mode] [--with-cddb] [--cddb-servers server-list] [--cddb- timeout timeout] [--cddb-directory directory] [--tmpdir directory] [--keep] [--save] [-n] [-v verbose-level] toc-file

DESCRIPTION cdrdao creates audio and data CD-Rs in disk-at-once (DAO) mode driven by a description file called toc-file. In DAO mode it is possible to create non standard track pre-gaps that have other lengths than 2 sec- onds and contain nonzero audio data. This is for example useful to divide live recordings into tracks where 2 second gaps would be kind of irritating.

Instead of a toc-file a cue file (used by a famous DOS/Windows master- ing tool) may be used. See the CUE FILES section for more details.

COMMANDS The first argument must be one of the following commands:

show-toc Print out a summary about what will be written to the CD-R.

read-toc Analyze each track of the inserted CD and create a toc-file that can be used to make a more or less exact copy of the CD. This command does not read out the audio or data tracks, use read-cd for this purpose.

You can specify a filename for the data file via the --datafile option.

read-cd Copies all tracks of the inserted CD to an image file and cre- ates a corresponding toc-file. The name of the image file defaults to "data.bin" if no --datafile option is given.

read-cddb Tries to retrieve title and artist data from a CDDB server for the CD represented by the given toc-file. The retrieved data is added as CD-TEXT data for language 0 to the toc-file. Existing CD-TEXT data for language 0 will be overwritten.

show-data Print out all samples that would be written to the CD-R. Each line contains the sample number (starting at 0) and the decimal sample value for the left and right channel. Useful to check if the byte order of audio files is correct.

read-test Check if all data can be read from the audio files that are defined in the toc-file. This will also check the communication with the slave process that is responsible for writing the audio data to the CD-recorder. Mainly used for testing.

disk-info Shows information about the inserted CD-R. If the CD-R has an open session it will also print the start of the last and cur- rent session which is used by mkisofs to create an image for a second or higher session.

msinfo Shows information required for creating multi session disks with mkisofs. The output is meant for processing by scripts.

unlock Tries to unlock the recorder device after a failed write or sim- ulation run. If you cannot eject the CD after a cdrdao run try this command.

blank Blanks a CD-RW. The CD-RW is minimally blanked by default. Use option --blank-mode to select another blanking mode. Sometimes the blanking speed must be manually reduced for a successful blanking operation. Use option --speed to select another blank- ing speed.

simulate Like write but laser stays cold. It is a shortcut for write--simulate.

write Write the CD-R according to the specifications in the toc-file.

copy Performs all steps to copy a CD. The device containing the source CD must be specified with option --source-device and the recorder device with option --device. If only a single device is available the option --source-device must be omitted and cdr- dao will prompt to insert the CD-R after an image of the source CD was created.

The image file with name "cddata<pid>.bin" will be created in the current working directory if no --datafile option is given. The created image will be removed after it has been written.

If option --on-the-fly is given no image file is created and the data will be directly piped from the reading device to the CD recorder.

OPTIONS --device [prot:]bus,id,lun Sets the SCSI address of the CD-recorder in form of a bus/id/lun triple, e.g. 0,2,0 for the logical unit 0 of SCSI device with ID 2 on bus 0. ATAPI devices can be specified by using the pre- fix ATAPI:, e.g. ATAPI:0,0,0. On some systems a device node may be specified directly, e.g. /dev/sg0 on Linux systems. Linux 2.6 users may also try the newer ATAPI interface with the ATA: prefix.

--source-device [prot:]bus,id,lun Like above but used for the copy command to specify the source device.

--driver driver-id:option-flags Force usage of specified driver instead of the automatically determined driver. Available driver IDs: cdd2600, plextor, plextor-scan, generic-mmc, generic-mmc-raw, ricoh-mp6200, yamaha-cdr10x, teac-cdr55, sony-cdu920, sony- cdu948, taiyo-yuden, toshiba. Specifying an illegal driver ID will give a list of available drivers. Option flags may be used to modify the behavior of some drivers. See README for details.

--source-driver driver-id:option-flags Like above but used for the device specified with option --source-device.

--speed value Set the writing speed to value. Default is the highest possible speed.

--blank-mode mode Sets the blanking mode. Available modes are full and minimal. Please consider that the data of minimally blanked disks may be easily recovered. Use the full blanking mode for completely erasing all data. The default blanking mode is minimal.

--datafile file Used for read-toc,read-cd and copy. Set the default data file placed in the toc-file by read-toc.Use-toindicateSTDIN. For commands read-cd and copy it specifies the name of the created image file.

--read-raw Only used for commands read-cd and read-toc. All data sectors will be written as 2352 byte blocks including the sector header and L-EC data to the image file. The track mode will be set to MODE1_RAW or MODE2_RAW in the created toc-file.

--read-subchan mode Used by commands read-cd, read-toc and copy. Specifies the type of sub-channel data that is extracted from the source CD and written to the track image or copied to the destination CD. Mode may be rw for reading packed R-W sub-channel data (de- interleaved and error corrected) and rw_raw for reading raw R-W sub-channel data (not de-interleaved, not error corrected, L-EC data included in the track image). If this option is not speci- fied no sub-channel data will be extracted.

--no-mode2-mixed Only used for commands read-cd and read-toc. If we have MODE2_FORM1 or MODE2_FORM2, don t extract it as MODE2_FORM_MIX. toc-file.

--tao-source This option indicates to the commands read-toc and read-cd that the source CD was written in TAO mode. It will be assumed that the pre-gap length between all tracks (except between two audio tracks) is the standard 150 blocks plus the number of link blocks (usually 2). The number of link blocks can be controlled with option --tao-source-adjust.

Use this option only if read-toc or read-cd give error messages in the transition areas between two tracks. If you use this option with pressed CDs or CDs written in DAO mode you will get wrong results.

--tao-source-adjust link-blocks Specifies the number of link blocks for tracks written in TAO mode. This option has only an effect if option --tao-source is given.

--fast-toc Only used for command read-toc. This option suppresses the pre- gap length and index mark extraction which speeds up the read- toc process. Standard 2 second pre-gaps (but no silence!) will be placed into the toc-file. The resulting CD will sound like the source CD. Only the CD player s display will behave slightly different in the transition area between two tracks.

This option might help, too, if read-toc fails with your drive otherwise.

--buffers buffer-count Specifies the number of buffers that are allocated to avoid buffer under runs. The minimal buffer count is fixed to 10, default is 32 except on FreeBSD systems, on which default is 20. Each buffer holds 1 second of audio data so that dividing buffer-count by the writing speed gives the maximum time for which reading of audio data may be stalled.

--multi If this option is given the session will not be closed after the audio data is successfully written. It is possible to append another session on such disks, e.g. to create a CD-EXTRA.

--overburn By default cdrdao will not allow to write more data on a medium than specified by the current medium. This option allows to ignore this condition.

--eject Eject the CD-R after writing or write simulation.

--swap Swap the byte order of all samples that are send to the CD- recorder.

--session session-nr Used for read-toc and read-cd to specify the session which should be processed on multi session CDs.

--reload Indicates that the tray may be opened before writing without prompting the user to reset the disk status after a simulation run.

--force Forces the execution of an operation that otherwise would not be performed.

--paranoia-mode mode Sets the correction mode for digital audio extraction. 0: No checking, data is copied directly from the drive. 1: Perform overlapped reading to avoid jitter. 2: Like 1 but with addi- tional checks of the read audio data. 3: Like 2 but with addi- tional scratch detection and repair.

The extraction speed reduces from 0 to 3.

Default is the full paranoia mode (3).

--keepimage If a CD is copied with command copy this option will cause that the created image is not removed after the copy process has fin- ished.

--on-the-fly Perform CD copy on the fly without creating an image file.

--with-cddb Enables the automatic fetching of CDDB data for use as CD-TEXT data for commands copy, read-toc and read-cd.

--cddb-servers server-list Sets space or , separated list of CDDB servers used for com- mand read-cddb or for commands where the --with-cddb option is active. A server entry may have the following forms:

<server> Connect to <server>, default cddbp port (888), use cddbp proto- col.

<server>:<port> Connect to <server>, port <port>, use cddbp protocol.

<server>:<cgi-bin-path> Connect to <server>, default http port (80), use http protocol, url: <cgi-bin-path>.

<server>:<port>:<cgi-bin-path> Connect to <server>, port <port>, use http protocol, url: <cgi- bin-path>.

<server>:<port>:<cgi-bin-path>:<proxy-server> Connect to <proxy-server>, default http port (80), use http pro- tocol, url: http://<server>:<port>/<cgi-bin-path>.

<server>:<port>:<cgi-bin-path>:<proxy-server>:<proxy-port> Connect to <proxy-server>, port <proxy-port>, use http protocol, url: http://<server>:<port>/<cgi-bin-path>.

The <cgi-bin-path> is usually "/~cddb/cddb.cgi".

All servers of the server list will be tried in the given order until a successful connection can be established. For http proxy servers the first successful connected http proxy server will be used independent of the ability to connect to the target http server.

Example: freedb.freedb.org:/~cddb/cddb.cgi

--cddb-timeout timeout Sets the timeout in seconds used for connections to CDDB servers.

--cddb-directory directory Specifies the local CDDB database directory where fetched CDDB records will be stored. If this option is not given a fetched CDDB record will not be stored locally.

--tmpdir directory Specifies the directory in which to store temporary data files created from decoding MP3 and Ogg Vorbis files. By default, "/tmp" is used.

--keep Upon exit from cdrdao, do not delete temporary WAV files created from MP3 and Ogg Vorbis files.

--save Saves some of the current options to the settings file "$HOME/.cdrdao" and exit. See section ´SETTINGS´ for more details.

-n Suppresses the 10 second pause before writing or simulating.

-v verbose-level Sets verbose level. Levels > 2 are debug levels which produce a lot of output.

TOC FILES The toc-file describes what data is written to the CD-R and allows con- trol over track/index positions, pre-gaps and sub-channel information. It is a simple text file, use your favorite text editor to create it.

A toc-file contains an optional header and a sequence of track specifications. Comments starting with // reaching until end of line can be placed anywhere.

Header CATALOG "ddddddddddddd" Specifies the optional catalog number of the CD. The string must contain exactly 13 digits.

The following flags specify the type of session that will be created. It is used to create the correct CD-TOC format and to check the consis- tency of the track modes for the desired session type. If multiple flags are given the last one will take effect.

CD_DA The disc contains only audio tracks.

CD_ROM The disc contains just mode 1 tracks or mode 1 and audio tracks (mixed mode CD).

CD_ROM_XA The disc contains mode 2 form 1 or mode 2 form 2 tracks. Audio tracks are allowed, too. This type must be used if multi session disks are created (option --multi).

CD_TEXT { ... } Defines global CD-TEXT data like the album title and the used languages. See the CD-TEXT section below for the syntax of the CD-TEXT block contents.

Track Specification TRACK <track-mode> [<sub-channel-mode>] Starts a new track, the track number is incremented by 1. The length of a track must be at least 4 seconds. The block length of the input data depends on the <track-mode>: AUDIO: 2352 bytes (588 samples), MODE1: 2048 bytes, MODE1_RAW: 2352 bytes, MODE2: 2336 bytes, MODE2_FORM1: 2048 bytes, MODE2_FORM2: 2324 bytes, MODE2_FORM_MIX: 2336 bytes including the sub-header, MODE2_RAW: 2352 bytes. The <sub-channel-mode> is optional. If given it specifies the type of sub-channel data for each sector. RW: packed R-W sub-channel data (96 bytes, L-EC data will be gener- ated if required), RW_RAW: raw R-W sub-channel data (interleaved and L-EC data already calculated, 96 bytes). The block length is increased by the sub-channel data length if a <sub-channel-mode> is specified. If the input data length is not a multiple of the block length it will be padded with zeros.

The following flags may follow the track start statement. They are used to set sub-channel information for the current track. Each flag is optional. If not given the following defaults are used: copy not per- mitted, no pre emphasis, two channel audio, no ISRC code.

[ NO ] COPY Sets or clears the copy permitted flag.

[ NO ] PRE_EMPHASIS Sets or clears the pre emphasis flag (only for audio tracks).

TWO_CHANNEL_AUDIO Indicates that track contains two channel audio data (only for audio tracks).

FOUR_CHANNEL_AUDIO Indicates that track contains four channel audio data (only for audio tracks).

ISRC "CCOOOYYSSSSS" Sets ISRC code of track (only for audio tracks). C: country code (upper case letters or digits) O: owner code (upper case letters or digits) Y: year (digits) S: serial number (digits)

An optional CD-TEXT block that defines the CD-TEXT data for this track may follow. See the CD-TEXT section below for the syntax of the CD-TEXT block contents.

CD_TEXT { ... }

At least one of the following statements must appear to specify the data for the current track. Lengths and start positions may be expressed in samples (1/44100 seconds) for audio tracks or in bytes for data tracks. It is also possible to give the length in blocks with the MSF format MM:SS:FF specifying minutes, seconds and frames (0 <= FF < 75) . A frame equals one block.

If more than one statement is used the track will be composed by con- catenating the data in the specified order.

SILENCE <length> Adds zero audio data of specified length to the current audio track. Useful to create silent pre-gaps.

ZERO <length> Adds zero data to data tracks. Must be used to define pre- or post-gaps between tracks of different mode.

[ FILE | AUDIOFILE ] "<filename>" <start> [ <length> ] Adds the audio data of specified file to the current audio track. It is possible to select a portion of an audio file with <start> and <length> which allows non destructive cutting. The first sample of an audio file is addressed with <start> = 0. If <length> is omitted or set to 0 all audio data from <start> until the end of file is used.

Audio files may have raw or WAVE format with 16 bits per sample, 44.1 kHz sampling rate, stereo. Raw files must have the layout MSBLeft LSBLeft MSBRight LSBRight ... (big endian byte order). WAVE files are expected to have little endian byte order. The option --swap reverses the expected byte order for all raw and WAVE files. Only filenames with a ".wav" ending are treated as WAVE files, all other names are assumed to be raw audio files. Use tools like sox(1) to convert other file formats to supported formats.

Specifying a "-" as filename causes data to be read from STDIN. Currently only raw files are supported from STDIN.

If you are unsure about the byte order of your audio files try the command show-data. If the byte order is correct you will see a sequence of increasing or decreasing numbers for both channels. Otherwise numbers are jumping between very high and low values - high volume static.

DATAFILE "<filename>" [ <length> ] Adds data from given file to the current data track. If <length> is omitted the actual file length will be used.

FIFO "<fifo path>" <length> Adds data from specified FIFO path to the current audio or data track. <length> must specify the amount of data that will be read from the FIFO. The value is always in terms of bytes (scalar value) or in terms of the block length (MSF value).

START [ MM:SS:FF ] Defines the length of the pre-gap (position where index switches from 0 to 1). If the MSF value is omitted the current track length is used. If the current track length is not a multiple of the block length the pre-gap length will be rounded up to next block boundary.

If no START statement is given the track will not have a pre- gap.

PREGAP MM:SS:FF This is an alternate way to specify a pre-gap with zero audio data. It may appear before the first SILENCE, ZERO or FILE statement. Either PREGAP or START can be used within a track specification. It is equivalent to the sequence SILENCE MM:SS:FF START for audio tracks or ZERO MM:SS:FF START for data tracks.

Nothing prevents mixing DATAFILE/ZERO and AUDIOFILE/ SILENCE statements within the same track. The results, however, are undefined.

The end of a track specification may contain zero or more index incre- ment statements:

INDEX MM:SS:FF Increments the index number at given position within the track. The first statement will increment from 1 to 2. The position is relative to the real track start, not counting an existing pre- gap.

CD-TEXT Blocks A CD-TEXT block may be placed in the global section to define data valid for the whole CD and in each track specification of a toc-file. The global section must define a language map that is used to map a language-number to country codes. Up to 8 different languages can be defined:

LANGUAGE_MAP { 0 : c1 1 : c2 ... 7 : c7 } The country code may be an integer value in the range 0..255 or one of the following countries (the corresponding integer value is placed in braces behind the token): EN(9, English) It is just necessary to define a mapping for the used languages.

If no mapping exists for a language-number the data for this language will be ignored.

For each language a language block must exist that defines the actual data for a certain language.

LANGUAGE language-number { cd-text-item cd-text-data cd-text-item cd- text-data ... } Defines the CD-TEXT items for given language-number which must be defined in the language map.

The cd-text-data may be either a string enclosed by " or binary data like { 0, 10, 255, ... } where each integer number must be in the range 0..255. The cd-text-item may be one of the following:

TITLE String data: Title of CD or track.

PERFORMER String data.

SONGWRITER String data.

COMPOSER String data.

ARRANGER String data.

MESSAGE String data. Message to the user.

DISC_ID String data: Should only appear in the global CD-TEXT block. The format is usually: XY12345

GENRE Mixture of binary data (genre code) and string data. Should only appear in the global CD-TEXT block. Useful entries will be cre- ated by gcdmaster.

TOC_INFO1 Binary data: Optional table of contents 1. Should only appear in the global CD-TEXT block.

TOC_INFO2 Binary data: Optional table of contents 2. Should only appear in the global CD-TEXT block.

UPC_EAN String data: This item should only appear in the global CD-TEXT block. Was always an empty string on the CD-TEXT CDs I had access to.

ISRC String data: ISRC code of track. The format is usually: CC-OOO- YY-SSSSS

SIZE_INFO Binary data: Contains summary about all CD-TEXT data and should only appear in the global CD-TEXT block. The data will be auto- matically (re)created when the CD-TEXT data is written.

If one of the CD-TEXT items TITLE, PERFORMER, SONGWRITER, COM- POSER, ARRANGER, ISRC is defined for at least on track or in the global section it must be defined for all tracks and in the global section. If a DISC_ID item is defined in the global sec- tion, an ISRC entry must be defined for each track.

Examples Simple track without pre-gap with all audio data from WAVE file "data.wav": CD_DA TRACK AUDIO FILE "data.wav" 0

Standard track with two second pre-gap, ISRC code and CD-TEXT: CD_DA CD_TEXT { LANGUAGE_MAP { 0 : EN }

LANGUAGE 0 { TITLE "CD Title" PERFORMER "Performer" DISC_ID "XY12345" UPC_EAN "" } }

TRACK AUDIO ISRC "DEXXX9800001" CD_TEXT { LANGUAGE 0 { TITLE "Track Title" PERFORMER "Performer" ISRC "DE-XXX-98-00001" } } PREGAP 0:2:0 FILE "data.wav" 0

Track with 10 second pre-gap containing audio data from raw file "data.cdr": CD_DA TRACK AUDIO FILE "data.cdr" 0 START 0:10:0

Composed track with data from different files. Pre-gap data and length is taken from "pregapdata.wav". The first minute of "track.cdr" is omitted and two seconds silence are inserted at 2:0:0. Index will be incremented after 2 and 4 minutes past track start: CD_DA TRACK AUDIO FILE "pregapdata.wav" 0 START FILE "track.cdr" 1:0:0 1:0:0 SILENCE 0:2:0 FILE "track.cdr" 2:0:0 INDEX 2:0:0 INDEX 4:0:0

Mixed mode CD with a data track as first track followed by two audio tracks. CD_ROM TRACK MODE1 DATAFILE "data_1" ZERO 00:02:00 // post-gap

TRACK AUDIO SILENCE 00:02:00 // pre-gap START FILE "data_2.wav" 0

TRACK AUDIO FILE "data_3.wav" 0

CUE FILES Cue files may be used wherever a toc-file is expected. The correspond- ing bin file is not taken from the FILE statement of a cue file but constructed from the cue file name by replacing ".cue" by ".bin". The cue file must have exactly one FILE statement.

Currently, following track modes are supported: MODE1/2048, MODE1/2352, MODE2/2336, MODE2/2352. The CATALOG, ISRC and POSTGAP statements are parsed but not evaluated, yet.

SETTINGS Some of the command line options can be stored as settings at following locations. The files will be read on startup of cdrdao in that order:

1. /etc/cdrdao.conf

2. /etc/defaults/cdrdao

3. $HOME/.cdrdao

Command line options will overwrite the loaded settings. The settings file contains name - value pairs separated by a colon. String values must be enclosed by ". The file is automatically written if the command line option --save is used but it is also possible to modify it manu- ally. Following values are defined:

write_device Device used for operations simulate, write, copy, blank, disk- info and unlock. Corresponding option: --device

write_driver Driver (including driver options) that is used for operations simulate, write, copy, blank, disk-info and unlock. Correspond- ing option: --driver

write_speed Specifies writing speed. Corresponding option: --speed

write_buffers Specifies fifo buffers used for recording. Corresponding option: --buffers

read_device Device used for operations read-toc, read-cd and copy. Corre- sponding option: --device or --source-device

read_driver Driver (including driver options) used for operations read-toc, read-cd and copy. Corresponding option: --driver or --source- driver

read_paranoia_mode Paranoia mode used for operations read-cd and copy. Correspond- ing option: --paranoia-mode

cddb_server_list CDDB server list for read-cddb. Corresponding option: --cddb- servers

cddb_timeout CDDB connection timeout in seconds used by read-cddb. Corre- sponding option: --cddb-timeout

cddb_directory Local directory where fetched CDDB records will be stored, used by read-cddb. Corresponding option: --cddb-directory

tmp_file_dir Directory where temporay WAV files will be created from decoding MP3 and Ogg Vorbis files. Corresponding option: --tmpdir

BUGS If the program is terminated during the write/simulation process used IPC resources may not be released. Use ipcs(8) and ipcrm(8) to delete them.

AUTHOR Andreas Mueller mueller@daneb.ping.de

SEE ALSO gcdmaster(1), cdrecord(1), cdda2wav(1), cdparanoia(1), sox(1), ipcs(8), ipcrm(8)

Oct 6, 2002 CDRDAO(1)