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) GS(1) Ghostscript GS(1)

NAME gs - Ghostscript (PostScript and PDF language interpreter and pre- viewer)

SYNOPSIS gs [ options ] [ files ] ... (Unix, VMS) gswin32c [ options ] [ files ] ... (MS Windows) gswin32 [ options ] [ files ] ... (MS Windows 3.1) gsos2 [ options ] [ files ] ... (OS/2)

DESCRIPTION The gs (gswin32c, gswin32, gsos2) command invokes Ghostscript, an interpreter of Adobe Systems PostScript(tm) and Portable Document For- mat (PDF) languages. gs reads "files" in sequence and executes them as Ghostscript programs. After doing this, it reads further input from the standard input stream (normally the keyboard), interpreting each line separately. The interpreter exits gracefully when it encounters the "quit" command (either in a file or from the keyboard), at end-of-file, or at an interrupt signal (such as Control-C at the keyboard).

The interpreter recognizes many option switches, some of which are described below. Please see the usage documentation for complete infor- mation. Switches may appear anywhere in the command line and apply to all files thereafter. Invoking Ghostscript with the -h or -? switch produces a message which shows several useful switches, all the devices known to that executable, and the search path for fonts; on Unix it also shows the location of detailed documentation.

Ghostscript may be built to use many different output devices. To see which devices your executable includes, run "gs -h". Unless you spec- ify a particular device, Ghostscript normally opens the first one of those and directs output to it, so if the first one in the list is the one you want to use, just issue the command

gs myfile.ps

You can also check the set of available devices from within Ghostscript: invoke Ghostscript and type

devicenames ==

but the first device on the resulting list may not be the default device you determine with "gs -h". To specify "AbcXyz" as the initial output device, include the switch

-sDEVICE=AbcXyz

For example, for output to an Epson printer you might use the command

gs -sDEVICE=epson myfile.ps

The "-sDEVICE=" switch must precede the first mention of a file to print, and only the switchs first use has any effect.

Finally, you can specify a default device in the environment variable GS_DEVICE. The order of precedence for these alternatives from highest to lowest (Ghostscript uses the device defined highest in the list) is:

Some devices can support different resolutions (densities). To specify the resolution on such a printer, use the "-r" switch:

gs -sDEVICE=<device> -r<xres>x<yres>

For example, on a 9-pin Epson-compatible printer, you get the lowest- density (fastest) mode with

gs -sDEVICE=epson -r60x72

and the highest-density (best output quality) mode with

gs -sDEVICE=epson -r240x72.

If you select a printer as the output device, Ghostscript also allows you to choose where Ghostscript sends the output -- on Unix systems, usually to a temporary file. To send the output to a file "foo.xyz", use the switch

-sOutputFile=foo.xyz

You might want to print each page separately. To do this, send the output to a series of files "foo1.xyz, foo2.xyz, ..." using the "-sOut- putFile=" switch with "%d" in a filename template:

-sOutputFile=foo%d.xyz

Each resulting file receives one page of output, and the files are num- bered in sequence. "%d" is a printf format specification; you can also use a variant like "%02d".

On Unix and MS Windows systems you can also send output to a pipe. For example, to pipe output to the "lpr" command (which, on many Unix sys- tems, directs it to a printer), use the option

-sOutputFile=%pipe%lpr

Note that the % characters need to be doubled on MS Windows to avoid mangling by the command interpreter.

You can also send output to standard output:

-sOutputFile=- or -sOutputFile=%stdout%

In this case you must also use the -q switch, to prevent Ghostscript from writing messages to standard output.

To select a specific paper size, use the command line switch

-sPAPERSIZE=<paper_size>

for instance

-sPAPERSIZE=a4 or -sPAPERSIZE=legal

Most ISO and US paper sizes are recognized. See the usage documentation for a full list, or the definitions in the initialization file "gs_statd.ps".

Ghostscript can do many things other than print or view PostScript and PDF files. For example, if you want to know the bounding box of a PostScript (or EPS) file, Ghostscript provides a special "device" that just prints out this information.

For example, using one of the example files distributed with Ghostscript,

gs -sDEVICE=bbox golfer.ps

prints out

%%BoundingBox: 0 25 583 732 %%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445

OPTIONS -- filename arg1 ... Takes the next argument as a file name as usual, but takes all remaining arguments (even if they have the syntactic form of switches) and defines the name "ARGUMENTS" in "userdict" (not "systemdict") as an array of those strings, before running the file. When Ghostscript finishes executing the file, it exits back to the shell.

-Dname=token -dname=token Define a name in "systemdict" with the given definition. The token must be exactly one token (as defined by the "token" oper- ator) and may contain no whitespace.

-Dname -dname Define a name in "systemdict" with value=null.

-Sname=string -sname=string Define a name in "systemdict" with a given string as value. This is different from -d. For example, -dname=35 is equivalent to the program fragment /name 35 def whereas -sname=35 is equivalent to /name (35) def

-P Makes Ghostscript to look first in the current directory for library files. By default, Ghostscript no longer looks in the current directory, unless, of course, the first explicitly sup- plied directory is "." in -I. See also the INITIALIZATION FILES section below, and bundled Use.htm for detailed discussion on search paths and how Ghostcript finds files. -q Quiet startup: suppress normal startup messages, and also do the equivalent of -dQUIET.

-gnumber1xnumber2 Equivalent to -dDEVICEWIDTH=number1 and -dDEVICEHEIGHT=number2. This is for the benefit of devices (such as X11 windows) that require (or allow) width and height to be specified.

-rnumber -rnumber1xnumber2 Equivalent to -dDEVICEXRESOLUTION=number1 and -dDEVICEYRESOLU- TION=number2. This is for the benefit of devices such as print- ers that support multiple X and Y resolutions. If only one num- ber is given, it is used for both X and Y resolutions.

-Idirectories Adds the designated list of directories at the head of the search path for library files.

- This is not really a switch, but indicates to Ghostscript that standard input is coming from a file or a pipe and not interac- tively from the command line. Ghostscript reads from standard input until it reaches end-of-file, executing it like any other file, and then continues with processing the command line. When the command line has been entirely processed, Ghostscript exits rather than going into its interactive mode.

Note that the normal initialization file "gs_init.ps" makes "system- dict" read-only, so the values of names defined with -D, -d, -S, or -s cannot be changed (although, of course, they can be superseded by defi- nitions in "userdict" or other dictionaries.)

SPECIAL NAMES -dDISKFONTS Causes individual character outlines to be loaded from the disk the first time they are encountered. (Normally Ghostscript loads all the character outlines when it loads a font.) This may allow loading more fonts into RAM, at the expense of slower rendering.

-dNOCACHE Disables character caching. Useful only for debugging.

-dNOBIND Disables the "bind" operator. Useful only for debugging.

-dNODISPLAY Suppresses the normal initialization of the output device. This may be useful when debugging.

-dNOPAUSE Disables the prompt and pause at the end of each page. This may be desirable for applications where another program is driving Ghostscript.

-dNOPLATFONTS Disables the use of fonts supplied by the underlying platform (for instance X Windows). This may be needed if the platform fonts look undesirably different from the scalable fonts.

-dSAFER Disables the "deletefile" and "renamefile" operators and the ability to open files in any mode other than read-only. This strongly recommended for spoolers, conversion scripts or other sensitive environments where a badly written or malicious PostScript program code must be prevented from changing impor- tant files.

-dWRITESYSTEMDICT Leaves "systemdict" writable. This is necessary when running special utility programs such as font2c and pcharstr, which must bypass normal PostScript access protection.

-sDEVICE=device Selects an alternate initial output device, as described above.

-sOutputFile=filename Selects an alternate output file (or pipe) for the initial out- put device, as described above.

FILES The locations of many Ghostscript run-time files are compiled into the executable when it is built. On Unix these are typically based in /usr/local, but this may be different on your system. Under DOS they are typically based in CGS, but may be elsewhere, especially if you install Ghostscript with GSview. Run "gs -h" to find the location of Ghostscript documentation on your system, from which you can get more details.

/usr/local/share/ghostscript/#.##/* Startup files, utilities, and basic font definitions

/usr/local/share/ghostscript/fonts/* More font definitions

/usr/local/share/ghostscript/#.##/examples/* Ghostscript demonstration files

/usr/local/share/ghostscript/#.##/doc/* Diverse document files

INITIALIZATION FILES When looking for the initialization files "gs_*.ps", the files related to fonts, or the file for the "run" operator, Ghostscript first tries to open the file with the name as given, using the current working directory if no directory is specified. If this fails, and the file name doesn t specify an explicit directory or drive (for instance, doesnt contain "/" on Unix systems or " Ghostscript tries directories in this order:

1. the directories specified by the -I switches in the command line (see below), if any;

2. the directories specified by the GS_LIB environment variable, if any;

3. the directories specified by the GS_LIB_DEFAULT macro in the Ghostscript makefile when the executable was built. When gs is built on Unix, GS_LIB_DEFAULT is usually "/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts" where "#.##" represents the Ghostscript version number.

Each of these (GS_LIB_DEFAULT, GS_LIB, and -I parameter) may be either a single directory or a list of directories separated by ":".

ENVIRONMENT GS_OPTIONS String of options to be processed before the command line options

GS_DEVICE Used to specify an output device

GS_FONTPATH Path names used to search for fonts

GS_LIB Path names for initialization files and fonts

TEMP Where temporary files are made

X RESOURCES Ghostscript, or more properly the X11 display device, looks for the following resources under the program name "Ghostscript":

borderWidth The border width in pixels (default = 1).

borderColor The name of the border color (default = black).

geometry The window size and placement, WxH+X+Y (default is NULL).

xResolution The number of x pixels per inch (default is computed from WidthOfScreen and WidthMMOfScreen).

yResolution The number of y pixels per inch (default is computed from HeightOfScreen and HeightMMOfScreen).

useBackingPixmap Determines whether backing store is to be used for saving dis- play window (default = true).

See the usage document for a more complete list of resources. To set these resources on Unix, put them in a file such as "~/.Xresources" in the following form:

Ghostscript*geometry: 612x792-0+0 Ghostscript*xResolution: 72 Ghostscript*yResolution: 72

Then merge these resources into the X servers resource database:

% xrdb -merge ~/.Xresources

SEE ALSO The various Ghostscript document files (above), especially Use.htm.

BUGS See http://bugs.ghostscript.com/ and the Usenet news group comp.lang.postscript.

VERSION This document was last revised for Ghostscript version 8.70.

AUTHOR Artifex Software, Inc. are the primary maintainers of Ghostscript. Russell J. Lang, gsview at ghostgum.com.au, is the author of most of the MS Windows code in Ghostscript.

8.70 31 July 2009 GS(1)