GS(1)

✨ GS(1) ✨

okay so bestie, meet gs — Ghostscript — the absolute icon of the Unix world. This is the GS(1) manual page and I'm gonna walk you through it like we're texting at 2am. 🦋

---

🌸 NAME 🌸

gs — Ghostscript (PostScript and PDF language interpreter and previewer) 💖

---

🎀 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 command (and its lil siblings gswin32c, gswin32, gsos2) invokes Ghostscript, which is an interpreter for Adobe Systems' PostScript(tm) and Portable Document Format (PDF) languages. 💅

So here's the vibe: gs reads files in order and executes them as Ghostscript programs. Once it's done with those, it keeps reading more input from standard input (usually your keyboard), interpreting <em>each line separately</em>, and sends output to an output device — which might be a file, or might be an X11 window preview, see below. The interpreter bails gracefully when it hits the quit command (whether that's in a file or typed at the keyboard), at end-of-file, or at an interrupt signal (like Control-C at the keyboard). 🫶

The interpreter knows a ton of option switches — some of them are described below, but for the full tea, check the usage documentation. Switches can appear anywhere on the command line and they apply to all files that come after them. If you run Ghostscript with the -h or -? switch, you get a message showing several useful switches, all the devices known to that executable, and the search path for fonts; on Unix it also shows where the detailed documentation lives. 👑

Ghostscript may be built to use many different output devices. To see which devices <em>your</em> executable includes, run gs -h. 🔍

Unless you specify a particular device, Ghostscript normally opens the first one in that list and directs output to it. If it was built with X11 support, the default device is often an X11 window (a previewer); otherwise ghostscript will typically use the bbox device and print the dimensions of the PostScript file on stdout. 📐

So if the first one in the list is the one you want, just issue:

gs myfile.ps

You can also check the set of available devices from inside Ghostscript — invoke it and type:

devicenames ==

⚠️ but heads up bestie: the first device on the resulting list may not be the default device you determine with gs -h. not the same thing, no cap.

To specify AbcXyz as the initial output device, include the switch:

-sDEVICE=AbcXyz

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

gs -sDEVICE=epson myfile.ps

📌 The -sDEVICE= switch must precede the first mention of a file to print, and only the switch's first use has any effect. So don't be out here trying to switch devices mid-command, it's giving delulu.

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:

• setpagedevice
• (command line)
• GS_DEVICE
• (first device in build list)

---

Some devices can support different resolutions (densities). To specify the resolution on such a device, 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 lets you choose where it sends the output — on Unix systems, usually to a temporary file. To send the output to a file foo.xyz, use:

-sOutputFile=foo.xyz

Maybe you wanna print each page separately? so valid. To do that, send output to a series of files foo1.xyz, foo2.xyz, ... using the -sOutputFile= switch with %d in a filename template:

-sOutputFile=foo%d.xyz

Each resulting file receives one page of output, and the files are numbered 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 systems, directs it to a printer), use:

-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. fr fr, don't skip this one.

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 so many things other than print or view PostScript and PDF files. For example, if you wanna know the bounding box of a PostScript (or EPS) file, Ghostscript provides a special "device" that just prints out this information. obsessed.

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 operator) 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 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 supplied directory is . in -I. See also the INITIALIZATION FILES section below, and the bundled Use.htm for a detailed discussion on search paths and how Ghostscript finds files. 🔎
• -q — Quiet startup: suppress normal startup messages, and also do the equivalent of -dQUIET. shhh bestie. 🤫
• -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 -dDEVICEYRESOLUTION=number2. This is for the benefit of devices such as printers that support multiple X and Y resolutions. If only one number 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 it indicates to Ghostscript that standard input is coming from a file or a pipe and not interactively from the command line. Ghostscript reads from standard input until it reaches end-of-file, executing it like any other file, and then continues 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 systemdict 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 definitions in userdict or other dictionaries).

---

🌈 SPECIAL NAMES 🌈

• -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 X11). This may be needed if the platform fonts look undesirably different from the scalable fonts. font drama, iykyk.
• -dSAFER — Restricts file operations the job can perform. Now the default mode of operation. 👑
• -dWRITESYSTEMDICT — Leaves systemdict writable. This is necessary when running special utility programs, but is strongly discouraged as it bypasses normal PostScript security measures. 💀
• -sDEVICE=device — Selects an alternate initial output device, as described above.
• -sOutputFile=filename — Selects an alternate output file (or pipe) for the initial output device, as described above.

---

🛡️ SAFER MODE 🛡️

The -dSAFER option restricts file system accesses to those files and directories allowed by the relevant environment variables (such as GS_LIB) or by the command line parameters (see https://ghostscript.com/doc/current/Use.htm for details). 🔒

SAFER mode is now the default mode of operation. So when you're running programs that need to open files or set restricted parameters, you should pass the -dNOSAFER command line option or its synonym -dDELAYSAFER.

⚠️ Running with NOSAFER/DELAYSAFER (as the name suggests) loosens the security and is thus recommended ONLY for debugging or in VERY controlled workflows, and strongly NOT recommended in any other circumstances. like bestie. please. 🙈

🌸 FILES 🌸

okay so here's the tea on where Ghostscript keeps its stuff: a bunch of the run-time file locations are literally baked right into the executable when it gets built. So like, they're compiled in, not vibing somewhere you can just move around. On Unix these are typically based in /usr/local, but bestie, it might be different on your system, don't @ me. Under DOS they're typically based in C:\GS, but they can be elsewhere too — especially if you installed Ghostscript with GSview.

Wanna know where your docs live? Run gs -h and it'll tell you the location of the Ghostscript documentation on your system, and from there you can get more deets. 💅

• /usr/local/share/ghostscript/#.##/* — startup files, utilities, and the basic font definitions. the whole starter pack fr.
• /usr/local/share/ghostscript/fonts/* — more font definitions. the font closet just keeps going 🎀
• /usr/local/share/ghostscript/#.##/examples/* — Ghostscript demonstration files. show-off files, iconic behavior.
• /usr/local/share/ghostscript/#.##/doc/* — diverse document files. the lore. 📚

---

✨ INITIALIZATION FILES ✨

So when Ghostscript goes looking for the initialization files gs_*.ps, or the files related to fonts, or the file for the run operator, it does this little hunt:

First it tries to open the file with the name as given, using the current working directory if you didn't specify a directory. Makes sense, right?

But if that fails — and the file name doesn't specify an explicit directory or drive (like, it doesn't contain / on Unix systems, or \ on MS Windows systems) — then Ghostscript starts trying directories in this exact order, no cap:

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.

And here's the cute part — each of these (GS_LIB_DEFAULT, GS_LIB, and the -I parameter) can be either a single directory or a list of directories separated by :. So you can chain them together like friendship bracelets. 🫶

---

🌈 ENVIRONMENT 🌈

• GS_OPTIONS — a string of options to be processed before the command line options. it's giving pregame. 🍓
• GS_DEVICE — used to specify an output device.
• GS_FONTPATH — path names used to search for fonts. where the fonts hang out.
• 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". periodt.

• 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 display window (default = true).

Peep the usage document for a more complete list of resources, iykyk. 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 server's resource database:

% xrdb -merge ~/.Xresources

slay. 💖

---

💜 SEE ALSO 💜

The various Ghostscript document files (above), especially Use.htm. go read it bestie, it's the main character of the docs.

---

💀 BUGS 💀

See http://bugs.ghostscript.com/ and the Usenet news group comp.lang.postscript. not me sending you straight to the bug tracker 😭

---

⭐ VERSION ⭐

This document was last revised for Ghostscript version 10.04.0.

---

🦋 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.

---

and that's the whole page, bestie!! 🎀 this one was Ghostscript 10.04.0, dated 18 Sept 2024, and it's page GS(1) if you were wondering. go forth and render, you absolute icon 👑💅