1GS(1)                             Ghostscript                            GS(1)
2
3
4

NAME

6       gs  -  Ghostscript  (PostScript  and  PDF language interpreter and pre‐
7       viewer)
8

SYNOPSIS

10       gs [ options ] [ files ] ... (Unix, VMS)
11       gswin32c [ options ] [ files ] ... (MS Windows)
12       gswin32 [ options ] [ files ] ... (MS Windows 3.1)
13       gsos2 [ options ] [ files ] ... (OS/2)
14

DESCRIPTION

16       The gs (gswin32c,  gswin32,  gsos2)  command  invokes  Ghostscript,  an
17       interpreter of Adobe Systems' PostScript(tm) and Portable Document For‐
18       mat (PDF) languages.  gs reads "files" in sequence and executes them as
19       Ghostscript programs. After doing this, it reads further input from the
20       standard input stream (normally the keyboard), interpreting  each  line
21       separately and output to an output device (may be a file or an X11 win‐
22       dow preview, see below).  The  interpreter  exits  gracefully  when  it
23       encounters  the "quit" command (either in a file or from the keyboard),
24       at end-of-file, or at an interrupt signal (such  as  Control-C  at  the
25       keyboard).
26
27       The  interpreter  recognizes  many  option  switches, some of which are
28       described below. Please see the usage documentation for complete infor‐
29       mation.  Switches  may appear anywhere in the command line and apply to
30       all files thereafter.  Invoking Ghostscript with the -h  or  -?  switch
31       produces a message which shows several useful switches, all the devices
32       known to that executable, and the search path for  fonts;  on  Unix  it
33       also shows the location of detailed documentation.
34
35       Ghostscript  may be built to use many different output devices.  To see
36       which devices your executable includes, run "gs -h".
37
38       Unless you specify a particular device, Ghostscript normally opens  the
39       first one of those and directs output to it.
40
41       If  built  with  X11 support, often the default device is an X11 window
42       (previewer), else ghostscript will typically use the  bbox  device  and
43       print on stdout the dimension of the postscript file.
44
45       So  if the first one in the list is the one you want to use, just issue
46       the command
47
48            gs myfile.ps
49
50       You can also check the set of  available  devices  from  within  Ghost‐
51       script: invoke Ghostscript and type
52
53            devicenames ==
54
55       but  the  first  device  on  the  resulting list may not be the default
56       device you determine with "gs -h".  To specify "AbcXyz" as the  initial
57       output device, include the switch
58
59            -sDEVICE=AbcXyz
60
61       For example, for output to an Epson printer you might use the command
62
63            gs -sDEVICE=epson myfile.ps
64
65       The  "-sDEVICE="  switch  must  precede  the first mention of a file to
66       print, and only the switch's first use has any effect.
67
68       Finally, you can specify a default device in the  environment  variable
69       GS_DEVICE.  The order of precedence for these alternatives from highest
70       to lowest (Ghostscript uses the device defined highest in the list) is:
71
72       Some devices can support different resolutions (densities).  To specify
73       the resolution on such a printer, use the "-r" switch:
74
75            gs -sDEVICE=<device> -r<xres>x<yres>
76
77       For  example,  on a 9-pin Epson-compatible printer, you get the lowest-
78       density (fastest) mode with
79
80            gs -sDEVICE=epson -r60x72
81
82       and the highest-density (best output quality) mode with
83
84            gs -sDEVICE=epson -r240x72.
85
86       If you select a printer as the output device, Ghostscript  also  allows
87       you  to  choose  where Ghostscript sends the output -- on Unix systems,
88       usually to a temporary file.  To send the output to a  file  "foo.xyz",
89       use the switch
90
91            -sOutputFile=foo.xyz
92
93       You  might  want  to  print each page separately.  To do this, send the
94       output to a series of files "foo1.xyz, foo2.xyz, ..." using the "-sOut‐
95       putFile=" switch with "%d" in a filename template:
96
97            -sOutputFile=foo%d.xyz
98
99       Each resulting file receives one page of output, and the files are num‐
100       bered in sequence.  "%d" is a printf format specification; you can also
101       use a variant like "%02d".
102
103       On Unix and MS Windows systems you can also send output to a pipe.  For
104       example, to pipe output to the "lpr" command (which, on many Unix  sys‐
105       tems, directs it to a printer), use the option
106
107            -sOutputFile=%pipe%lpr
108
109       Note  that the '%' characters need to be doubled on MS Windows to avoid
110       mangling by the command interpreter.
111
112       You can also send output to standard output:
113
114            -sOutputFile=-
115       or
116            -sOutputFile=%stdout%
117
118       In this case you must also use the -q switch,  to  prevent  Ghostscript
119       from writing messages to standard output.
120
121       To select a specific paper size, use the command line switch
122
123            -sPAPERSIZE=<paper_size>
124
125       for instance
126
127            -sPAPERSIZE=a4
128       or
129            -sPAPERSIZE=legal
130
131       Most ISO and US paper sizes are recognized. See the usage documentation
132       for a  full  list,  or  the  definitions  in  the  initialization  file
133       "gs_statd.ps".
134
135       Ghostscript  can do many things other than print or view PostScript and
136       PDF files.  For example, if you want to know  the  bounding  box  of  a
137       PostScript  (or EPS) file, Ghostscript provides a special "device" that
138       just prints out this information.
139
140       For example, using one of the example  files  distributed  with  Ghost‐
141       script,
142
143            gs -sDEVICE=bbox golfer.ps
144
145       prints out
146
147            %%BoundingBox: 0 25 583 732
148            %%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445
149

OPTIONS

151       -- filename arg1 ...
152              Takes  the  next argument as a file name as usual, but takes all
153              remaining arguments (even if they have  the  syntactic  form  of
154              switches)  and  defines  the name "ARGUMENTS" in "userdict" (not
155              "systemdict") as an array of those strings, before  running  the
156              file.   When  Ghostscript  finishes executing the file, it exits
157              back to the shell.
158
159       -Dname=token
160       -dname=token
161              Define a name in "systemdict" with the  given  definition.   The
162              token must be exactly one token (as defined by the "token" oper‐
163              ator) and may contain no whitespace.
164
165       -Dname
166       -dname Define a name in "systemdict" with value=null.
167
168       -Sname=string
169       -sname=string
170              Define a name in "systemdict" with  a  given  string  as  value.
171              This is different from -d.  For example, -dname=35 is equivalent
172              to the program fragment
173                   /name 35 def
174              whereas -sname=35 is equivalent to
175                   /name (35) def
176
177       -P     Makes Ghostscript to look first in  the  current  directory  for
178              library  files.   By default, Ghostscript no longer looks in the
179              current directory, unless, of course, the first explicitly  sup‐
180              plied directory is "." in -I.  See also the INITIALIZATION FILES
181              section below, and bundled Use.htm for  detailed  discussion  on
182              search paths and how Ghostcript finds files.
183
184       -q     Quiet startup: suppress normal startup messages, and also do the
185              equivalent of -dQUIET.
186
187       -gnumber1xnumber2
188              Equivalent to -dDEVICEWIDTH=number1 and  -dDEVICEHEIGHT=number2.
189              This  is  for  the benefit of devices (such as X11 windows) that
190              require (or allow) width and height to be specified.
191
192       -rnumber
193       -rnumber1xnumber2
194              Equivalent to -dDEVICEXRESOLUTION=number1  and  -dDEVICEYRESOLU‐
195              TION=number2.  This is for the benefit of devices such as print‐
196              ers that support multiple X and Y resolutions.  If only one num‐
197              ber is given, it is used for both X and Y resolutions.
198
199       -Idirectories
200              Adds  the  designated  list  of  directories  at the head of the
201              search path for library files.
202
203       -      This is not really a switch, but indicates to  Ghostscript  that
204              standard  input is coming from a file or a pipe and not interac‐
205              tively from the command line.  Ghostscript reads  from  standard
206              input  until it reaches end-of-file, executing it like any other
207              file, and then continues with processing the command line.  When
208              the  command line has been entirely processed, Ghostscript exits
209              rather than going into its interactive mode.
210
211       Note that the normal initialization file  "gs_init.ps"  makes  "system‐
212       dict"  read-only, so the values of names defined with -D, -d, -S, or -s
213       cannot be changed (although, of course, they can be superseded by defi‐
214       nitions in "userdict" or other dictionaries.)
215

SPECIAL NAMES

217       -dDISKFONTS
218              Causes  individual character outlines to be loaded from the disk
219              the first time  they  are  encountered.   (Normally  Ghostscript
220              loads  all  the  character outlines when it loads a font.)  This
221              may allow loading more fonts into RAM, at the expense of  slower
222              rendering.
223
224       -dNOCACHE
225              Disables character caching.  Useful only for debugging.
226
227       -dNOBIND
228              Disables the "bind" operator.  Useful only for debugging.
229
230       -dNODISPLAY
231              Suppresses the normal initialization of the output device.  This
232              may be useful when debugging.
233
234       -dNOPAUSE
235              Disables the prompt and pause at the end of each page.  This may
236              be  desirable  for applications where another program is driving
237              Ghostscript.
238
239       -dNOPLATFONTS
240              Disables the use of fonts supplied by  the  underlying  platform
241              (for  instance  X  Windows).  This may be needed if the platform
242              fonts look undesirably different from the scalable fonts.
243
244       -dSAFER
245              Restricts file operations the job can perform.  Strongly  recom‐
246              mended for spoolers, conversion scripts or other sensitive envi‐
247              ronments where a badly written or malicious  PostScript  program
248              code must be prevented from changing important files.
249
250       -dWRITESYSTEMDICT
251              Leaves  "systemdict"  writable.   This is necessary when running
252              special utility programs such as font2c and pcharstr, which must
253              bypass normal PostScript access protection.
254
255       -sDEVICE=device
256              Selects an alternate initial output device, as described above.
257
258       -sOutputFile=filename
259              Selects  an alternate output file (or pipe) for the initial out‐
260              put device, as described above.
261

SAFER MODE

263       The -dSAFER option disables the "deletefile" and "renamefile" operators
264       and  prohibits opening piped commands ("%pipe%cmd"). Only "%stdout" and
265       "%stderr" can be opened for writing.  It  also  disables  reading  from
266       files, except for "%stdin", files given as a command line argument, and
267       files contained in paths given by LIBPATH and FONTPATH or specified  by
268       the system params /FontResourceDir and /GenericResourceDir.
269
270       This mode also sets the .LockSafetyParams parameter of the initial out‐
271       put device to protect against programs that attempt to write  to  files
272       using  the  OutputFile  device  parameter.  Since the device parameters
273       specified on the command line, including OutputFile, are set  prior  to
274       SAFER  mode,  use  of  "-sOutputFile=..."  on the command line is unre‐
275       stricted.
276
277       SAFER mode prevents changing the /GenericResourceDir, /FontResourceDir,
278       /SystemParamsPassword, and /StartJobPassword.
279
280       While SAFER mode is not the default, it is the default for many wrapper
281       scripts such as ps2pdf and may be the default in a  subsequent  release
282       of  Ghostscript.  Thus when running programs that need to open files or
283       set restricted parameters you should pass the  -dNOSAFER  command  line
284       option or its synonym -dDELAYSAFER.
285
286       When running with -dNOSAFER it is possible to perform a "save" followed
287       by ".setsafe", execute a file or procedure in SAFER mode, and then  use
288       "restore"  to  return  to  NOSAFER  mode.  In order to prevent the save
289       object from being restored  by  the  foreign  file  or  procedure,  the
290       ".runandhide"  operator should be used to hide the save object from the
291       restricted procedure.
292

FILES

294       The locations of many Ghostscript run-time files are compiled into  the
295       executable  when  it  is  built.   On Unix these are typically based in
296       /usr/local, but this may be different on your system.  Under  DOS  they
297       are  typically  based in C:\GS, but may be elsewhere, especially if you
298       install Ghostscript with GSview.  Run "gs -h" to find the  location  of
299       Ghostscript  documentation  on your system, from which you can get more
300       details.
301
302       /usr/local/share/ghostscript/#.##/*
303              Startup files, utilities, and basic font definitions
304
305       /usr/local/share/ghostscript/fonts/*
306              More font definitions
307
308       /usr/local/share/ghostscript/#.##/examples/*
309              Ghostscript demonstration files
310
311       /usr/local/share/ghostscript/#.##/doc/*
312              Diverse document files
313

INITIALIZATION FILES

315       When looking for the initialization files "gs_*.ps", the files  related
316       to  fonts,  or the file for the "run" operator, Ghostscript first tries
317       to open the file with the name as  given,  using  the  current  working
318       directory  if  no  directory is specified.  If this fails, and the file
319       name doesn't specify an explicit  directory  or  drive  (for  instance,
320       doesn't  contain  "/"  on  Unix  systems or "\" on MS Windows systems),
321       Ghostscript tries directories in this order:
322
323       1.  the directories specified by the -I switches in  the  command  line
324           (see below), if any;
325
326       2.  the  directories  specified  by the GS_LIB environment variable, if
327           any;
328
329       3.  the directories specified by the GS_LIB_DEFAULT macro in the Ghost‐
330           script makefile when the executable was built.  When gs is built on
331           Unix,   GS_LIB_DEFAULT    is    usually    "/usr/local/share/ghost‐
332           script/#.##:/usr/local/share/ghostscript/fonts" where "#.##" repre‐
333           sents the Ghostscript version number.
334
335       Each of these (GS_LIB_DEFAULT, GS_LIB, and -I parameter) may be  either
336       a single directory or a list of directories separated by ":".
337

ENVIRONMENT

339       GS_OPTIONS
340              String  of  options  to  be  processed  before  the command line
341              options
342
343       GS_DEVICE
344              Used to specify an output device
345
346       GS_FONTPATH
347              Path names used to search for fonts
348
349       GS_LIB Path names for initialization files and fonts
350
351       TEMP   Where temporary files are made
352

X RESOURCES

354       Ghostscript, or more properly the X11 display  device,  looks  for  the
355       following resources under the program name "Ghostscript":
356
357       borderWidth
358              The border width in pixels (default = 1).
359
360       borderColor
361              The name of the border color (default = black).
362
363       geometry
364              The window size and placement, WxH+X+Y (default is NULL).
365
366       xResolution
367              The  number  of  x  pixels  per  inch  (default is computed from
368              WidthOfScreen and WidthMMOfScreen).
369
370       yResolution
371              The number of y  pixels  per  inch  (default  is  computed  from
372              HeightOfScreen and HeightMMOfScreen).
373
374       useBackingPixmap
375              Determines  whether  backing store is to be used for saving dis‐
376              play window (default = true).
377
378       See the usage document for a more complete list of resources.   To  set
379       these  resources on Unix, put them in a file such as "~/.Xresources" in
380       the following form:
381
382            Ghostscript*geometry:     612x792-0+0
383            Ghostscript*xResolution: 72
384            Ghostscript*yResolution: 72
385
386       Then merge these resources into the X server's resource database:
387
388            % xrdb -merge ~/.Xresources
389

SEE ALSO

391       The various Ghostscript document files (above), especially Use.htm.
392

BUGS

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

VERSION

398       This document was last revised for Ghostscript version 9.07.
399

AUTHOR

401       Artifex  Software,  Inc.  are  the  primary maintainers of Ghostscript.
402       Russell J. Lang, gsview at ghostgum.com.au, is the author  of  most  of
403       the MS Windows code in Ghostscript.
404
405
406
4079.07                           12 February 2013                          GS(1)
Impressum