Please consider a donation to the Higher Intellect project. See https://preterhuman.net/donate.php or the Donate to Higher Intellect page for more info.

PostScript Operators from A-Z

From Higher Intellect Vintage Wiki
Jump to navigation Jump to search
--------------------------------------------------------------------------
		      PostScript Operators from A-Z
--------------------------------------------------------------------------


abs
add
aload
anchorsearch
and
arc
arcn
arct
arcto
array
ashow
astore
atan
awidthshow
begin
bind
bitshift
bytesavailable
cachestatus
ceiling
charpath
clear
cleardictstack
cleartomark
clip
clippath
closefile
closepath
colorimage
concat
concatmatrix
condition
configurationerror
copy
copypage
cos
count
countdictstack
countexecstack
counttomark
cshow
currentblackgeneration
currentcacheparams
currentcmykcolor
currentcolor
currentcolorrendering
currentcolorscreen
currentcolorspace
currentcolortransfer
currentcontext
currentdash
currentdevparams
currentdict
currentfile
currentflat
currentfont
currentglobal
currentgray
currentgstate
currenthalftone
currenthalftonephase
currenthsbcolor
currentlinecap
currentlinejoin
currentlinewidth
currentmatrix
currentmiterlimit
currentobjectformat
currentoverprint
currentpacking
currentpagedevice
currentpoint
currentrgbcolor
currentscreen
currentshared
currentstrokeadjust
currentsystemparams
currenttransfer
currentundercolorremoval
currentuserparams
curveto
cvi
cvlit
cvn
cvr
cvrs
cvs
cvx
def
defaultmatrix
definefont
defineresource
defineusername
defineuserobject
deletefile
detach
deviceinfo
dict
dictfull
dictstack
dictstackoverflow
dictstackunderflow
div
dtransform
dup
echo
eexec
end
eoclip
eofill
eoviewclip
eq
erasepage
errordict
exch
exec
execform
execstack
execstackoverflow
execuserobject
executeonly
executive
exit
exitserver
exp
false
file
filenameforall
fileposition
fill
filter
findencoding
findfont
findresource
flattenpath
floor
flush
flushfile
FontDirectory
for
forall
fork
gcheck
ge
get
getinterval
globaldict
GlobalFontDirectory
glyphshow
grestore
grestoreall
gsave
gstate
gt
handleerror
identmatrix
idtransform
if
ifelse
image
imagemask
index
ineofill
infill
initclip
initgraphics
initmatrix
initviewclip
instroke
internaldict
interrupt
inueofill
inufill
inustroke
invalidaccess
invalidcontext
invalidexit
invalidfileaccess
invalidfont
invalidid
invalidrestore
invertmatrix
ioerror
ISOLatin1Encoding
itransform
join
known
kshow
languagelevel
le
length
limitcheck
lineto
ln
load
lock
log
loop
lt
makefont
makepattern
mark
matrix
maxlength
mod
monitor
moveto
mul
ne
neg
newpath
noaccess
nocurrentpoint
not
notify
null
nulldevice
or
packedarray
pathbbox
pathforall
pop
print
printobject
product
prompt
pstack
put
putinterval
quit
rand
rangecheck
rcurveto
read
readhexstring
readline
readonly
readstring
realtime
rectclip
rectfill
rectstroke
rectviewclip
renamefile
repeat
resetfile
resourceforall
resourcestatus
restore
reversepath
revision
rlineto
rmoveto
roll
rootfont
rotate
round
rrand
run
save
scale
scalefont
scheck
search
selectfont
serialnumber
setbbox
setblackgeneration
setcachedevice
setcachedevice2
setcachelimit
setcacheparams
setcharwidth
setcmykcolor
setcolor
setcolorrendering
setcolorscreen
setcolorspace
setcolortransfer
setdash
setdevparams
setfileposition
setflat
setfont
setglobal
setgray
setgstate
sethalftone
sethalftonephase
sethsbcolor
setlinecap
setlinejoin
setlinewidth
setmatrix
setmiterlimit
setobjectformat
setoverprint
setpacking
setpagedevice
setpattern
setrgbcolor
setscreen
setshared
setstrokeadjust
setsystemparams
settransfer
setucacheparams
setundercolorremoval
setuserparams
setvmthreshold
shareddict
show
showpage
sin
sqrt
srand
stack
stackoverflow
stackunderflow
StandardEncoding
start
startjob
status
statusdict
stop
stopped
store
string
stringwidth
stroke
strokepath
sub
syntaxerror
systemdict
timeout
token
transform
translate
true
truncate
type
typecheck
uappend
ucache
ucachestatus
ueofill
ufill
undef
undefined
undefinedfilename
undefinedresource
undefinedresult
undefinefont
undefineresource
undefineuserobject
unmatchedmark
unregistered
upath
userdict
UserObjects
usertime
ustroke
ustrokepath
version
viewclip
viewclippath
VMerror
vmreclaim
vmstatus
wait
wcheck
where
widthshow
write
writehexstring
writeobject
writestring
wtranslation
xcheck
xor
xshow
xyshow
yield
yshow


==========================================================================
==========================================================================



*abs* num1 abs num2

returns the absolute value of num1.
The type of the result is the same as the type of num1 unless num1 is the
most negative integer, in which case the result is a real.

EXAMPLE:
4.5 abs 4.5
-3 abs 3
0 abs 0

ERRORS: stackunderflow, typecheck

SEE ALSO: neg
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*add* num1 num2 add sum

returns the sum of num1 and num2.
If both operands are integers and the result is within integer range, the
result is an integer; otherwise, the result is a real.

EXAMPLE:

3 4 add 7

9.9 1.1 add 11.0

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: div, mul , sub , idiv , mod
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*aload* array aload array0 ... arrayn-1 array
packedarray aload packedarray0 ... packedarrayn-1 packedarray

successively pushes all n elements of array or packedarray on the operand
stack (where n is the length of the operand), and finally pushes the
operand itself.

EXAMPLE:
[23 (ab) -6] aload 23 (ab) -6 [23 (ab) -6]

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck

SEE ALSO: astore , get , getinterval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*anchorsearch* string seek anchorsearch
post match true (if found)
string false (if not found)

determines if the string seek matches the initial substring of string
(that is, string is at least as long as seek and the corresponding
characters are equal).
If it matches, anchorsearch splits string into two segments: match, the
portion of string that matches seek, and post, the remainder of string; it
then pushes the string objects post and match and the boolean true. If not,
anchorsearch pushes the original string and the boolean false. anchorsearch
is a special case of the search operator.

EXAMPLE:
(abbc) (ab) anchorsearch (bc) (ab) true
(abbc) (bb) anchorsearch (abbc) false
(abbc) (bc) anchorsearch (abbc) false
(abbc) (B) anchorsearch (abbc) false

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck

SEE ALSO: search, token
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*and* bool1 bool2 and bool3
int1 int1 and int1

If the operands are booleans, and returns their logical conjunction. If the
operands are integers, and returns the bitwise and of their binary
representations.

EXAMPLE:
true true and true % a complete truth table
true false and false
false true and false
false false and false

99 1 and 1
52 7 and 4

ERRORS: stackunderflow, typecheck

SEE ALSO: or , xor , not , true , false
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*arc* x y r ang1 ang2 arc -

appends a counterclockwise arc of a circle to the current path, possibly
preceded by a straight line segment. The arc has (x, y) as center, r as
radius, ang1 the angle of a vector from (x, y) of length r to the first
endpoint of the arc, and ang2 the angle of a vector from (x, y) of length r
to the second endpoint of the arc.

If there is a current point, the arc operator includes a straight line
segment from the current point to the first endpoint of this arc and then
adds the arc into the current path. If the current path is empty, the arc
operator does not produce the initial straight line segment. In any event,
the second endpoint of the arc becomes the new current point.

Angles are measured in degrees counterclockwise from the positive x-axis of
the current user coordinate system. The curve produced is circular in user
space. If user space is scaled non-uniformly (i.e., differently in x and y)
arc will produce elliptical curves in device space.

The operators that produce arcs (arc, arcn, arct, and arcto represent them
internally as one or more Bezier cubic curves. This is done with sufficient
accuracy that a faithful rendition of an arc is produced. However, a
program that reads the constructed path using pathforall will encounter
curveto segments where arcs were specified originally.

EXAMPLE:
newpath 0 0 moveto 0 0 1 0 45 arc closepath

This constructs a 1-unit radius, 45-degree "pie slice."

ERRORS: limitcheck , stackunderflow, typecheck

SEE ALSO: arcn , arct , arcto , curveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*arcn* x y r ang1 ang2 arcn -

(arc negative) behaves like arc, but arcn builds its arc segment in a
clockwise direction in user space.

EXAMPLE:
newpath 0 0 2 0 90 arc 0 0 1 90 0 arcn closepath

This constructs a 2-unit radius, 1-unit wide, 90-degree "windshield wiper
swath."

ERRORS: limitcheck , stackunderflow, typecheck

SEE ALSO: arc, arct , arcto , curveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*arct* x1 y1 x2 y2 r arct - 2

appends an arc of a circle to the current path, possibly preceded by a
straight line segment. The arc is defined by a radius r and two tangent
lines.The tangent lines are those drawn from the current point, here called
(x0, y0), to (x1, y1), and from (x1, y1) to (x2, y2). If the current point
is undefined, arct executes the error nocurrentpoint.

The center of the arc is located within the inner angle between the tangent
lines. It is the only point located at distance r in a direction
perpendicular to both lines. The arc begins at the first tangent point
(xt1, yt1) on the first tangent line, passes between its center and the
point (x1, y1), and ends at the second tangent point (xt2, yt2) on the
second tangent line.

Before constructing the arc, arct adds a straight line segment from the
current point (x0, y0) to (xt1, yt1), unless those points are the same. In
any event, (xt2, yt2) becomes the new current point.

The curve produced is circular in user space. If user space is scaled
non-uniformly (i.e., differently in x and y) arct will produce elliptical
curves in device space.

If the two tangent lines are collinear, arct merely appends a straight line
segment from (x0, y0) to (x1, y1), considering the arc to be part of a
degenerate circle with radius 0 at that point.

EXAMPLE:
newpath 0 0 moveto
0 4 4 4 1 arct
4 4 lineto

This constructs a 4-unit wide, 4-unit high right angle with a 1-unit radius
"rounded corner."

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck,
undefinedresult

SEE ALSO: arc, arcn , arcto , curveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*arcto* x1 y1 x2 y2 r arcto xt1 yt1 xt2 yt2

produces the same effect as arct. It also returns the two tangent point
coordinates (xt1, yt1) and (xt2, yt2) in user space.
arcto is not allowed as an element of a user path, whereas arct is allowed.

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck,
undefinedresult

SEE ALSO: arc, arcn , arcto , curveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*array* int array array

creates an array of length int, each of whose elements is initialized with
a null object, and pushes this array on the operand stack. The int operand
must be a non-negative integer not greater than the maximum allowable array
length . The array is allocated in local or global VM according to the
current VM allocation mode.

EXAMPLE:
3 array [null null null]

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck, VMerror

SEE ALSO: [, ], aload, astore, packedarray
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ashow* ax ay string ashow -

paints the characters of string in a manner similar to show. But while
doing so, ashow adjusts the width of each character shown by adding ax to
the character's x width and ay to its y width, thus modifying the spacing
between characters. The numbers ax and ay are x and y displacements in the
user coordinate system, not in the character coordinate system.

This operator enables a string of text to be fitted to a specific width by
adjusting all the spaces between characters by a uniform amount.

EXAMPLE:
/Helvetica findfont 12 scalefont setfont
14 61 moveto (Normal spacing) show
14 47 moveto 4 0 (Wide spacing) ashow

ERRORS: invalidaccess, invalidfont, nocurrentpoint, stackunderflow,
typecheck

SEE ALSO: show, awidthshow, cshow, kshow, widthshow, xshow, xyshow, yshow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*astore* any0 ... anyn-1 array astore array

stores the objects any0 through anyn-1 from the operand stack into array,
where n is the length of array. The astore operator first removes the array
operand from the stack and determines its length. It then removes that
number of objects from the stack, storing the topmost one into element n -
1 of array and the bottommost one into element 0 of array. Finally, it
pushes array back on the stack. Note that astore cannot be performed on
packed arrays.

If the value of array is in global VM and any of any0 ... anyn-1 are
composite objects whose values are in local VM, an invalidaccess error
occurs.

EXAMPLE:
(a) (bcd) (ef) 3 array astore [(a) (bcd) (ef)]

This creates a three element array, stores the strings (a), (bcd), and (ef)
into it as elements 0, 1, and 2, and leaves the array object on the operand
stack.

ERRORS: invalidaccess, stackunderflow, typecheck,

SEE ALSO: aload, put, putinterval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*atan* num den atan angle

returns the angle (in degrees between 0 and 360) whose tangent is num/den.
Either num or den may be zero, but not both. The signs of num and den
determine the quadrant in which the result will lie: a positive num yields
a result in the positive y plane, a positive den yields a result in the
positive x plane. The result is a real.

EXAMPLE:
0 1 atan 0.0
1 0 atan 90.0
-100 0 atan 270.0
4 4 atan 45.0

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: cos, sin
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*awidthshow* cx cy char ax ay string awidthshow -

paints the characters of string in a manner similar to show, but combines
the special effects of ashow and widthshow. awidthshow adjusts the width of
each character shown by adding ax to its x width and ay to its y width,
thus modifying the spacing between characters. Furthermore, awidthshow
modifies the width of each occurrence of the character char by an
additional amount (cx, cy). The interpretation of char is as described for
the widthshow operator.

This operator enables fitting a string of text to a specific width by
adjusting all of the spaces between characters by a uniform amount, while
independently controlling the width of some specific character, such as the
space character.

EXAMPLE:
/Helvetica findfont 12 scalefont setfont
30 60 moveto (Normal spacing) show
30 46 moveto 6 0 8#040 .5 0 (Wide spacing) awidthshow

ERRORS: invalidaccess, invalidfont, nocurrentpoint, rangecheck,
stackunderflow, typecheck

SEE ALSO: ashow, cshow, kshow, show, widthshow, xshow, xyshow, yshow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*begin* dict begin

- pushes dict on the dictionary stack, making it the current dictionary and
installing it as the first of the dictionaries consulted during implicit
name lookup and by def, load, store, and where.

ERRORS: dictstackoverflow, invalidaccess, stackunderflow, typecheck

SEE ALSO: end, countdictstack, dictstack
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*bind* proc bind proc
replaces executable operator names in proc by their values. For each
element of proc that is an executable name, bind looks up the name in the
context of the current dictionary stack as if by load. If the name is found
and its value is an operator object, bind replaces the name by the operator
in proc. If the name is not found or its value is not an operator, bind
does not make a change.

For each procedure object in proc, bind applies itself recursively to that
procedure, makes the procedure read-only, and stores it back into proc. The
bind operator applies to both arrays and packed arrays, but it treats their
access attributes differently. It will ignore a read-only array; that is,
it will neither bind elements of the array nor examine nested procedures.
On the other hand, bind will operate on a packed array (which is always
read-only), disregarding its access attribute.
No error occurs in either case.

The effect of bind is that all operator names in proc and in procedures
nested in proc to any depth become "tightly bound" to the operators
themselves. During subsequent execution of proc, the interpreter encounters
the operators themselves rather than the names of operators.

ERRORS: typecheck

SEE ALSO: load
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*bitshift* int1 shift bitshift int2

shifts the binary representation of int1 left by shift bits and returns the
result. Bits shifted out are lost; bits shifted in are zero. If shift is
negative, then a right shift by -shift bits is performed. This produces an
arithmetically correct result only for positive values of int1. Both int1
and shift must be integers.

EXAMPLE:
7 3 bitshift -> 56
142 -3 bitshift -> 17

ERRORS: stackunderflow, typecheck

SEE ALSO: and, or, xor, not
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*bytesavailable* file bytesavailable int

returns the number of bytes that are immediately available for reading from
file without waiting.
The result is -1 if end-of-file has been encountered or if the number of
bytes available cannot be determined for other reasons.

ERRORS: ioerror, stackunderflow, typecheck

SEE ALSO: read, readhexstring, readline, readstring
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cachestatus* - cachestatus bsize bmax msize mmax csize cmax blimit

returns measurements of several aspects of the font cache .
cachestatus reports the current consumption and limit for each of three
font cache resources: bytes of bitmap storage (bsize and bmax), font/matrix
combinations (msize and mmax), and total number of cached characters (csize
and cmax). It also reports the limit on the number of bytes occupied by a
single cached character (blimit). Characters whose bitmaps are larger than
this are not cached.

ERRORS: stackoverflow

SEE ALSO: setcachelimit, setsystemparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ceiling* num1 ceiling num2

returns the least integer value greater than or equal to num1.
The type of the result is the same as the type of the operand.

EXAMPLE:
3.2 ceiling -> 4.0
-4.8 ceiling -> -4.0
99 ceiling -> 99

ERRORS: stackunderflow, typecheck

SEE ALSO: floor, round, truncate, cvi
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*charpath* string bool charpath -

obtains the character path outlines that would result if string were shown
at the current point using show. Instead of painting the path, however,
charpath appends the path to the current path. This yields a result
suitable for general filling, stroking, or clipping

The bool operand determines what happens if the character path is designed
to be stroked rather than filled or outlined. If bool is false, charpath
simply appends the character path to the current path; the result is
suitable only for stroking. If bool is true, charpath applies the
strokepath operator to the character path; the result is suitable for
filling or clipping, but not for stroking. charpath does not produce
results for portions of a character defined as images or masks rather than
as paths.

The outlines of some fonts are protected. (In Level 1 implementations, this
applies to all fonts; in Level 2, only to certain special fonts and not to
ordinary Type 1 or Type 3 fonts.) If the current font is protected, using
charpath to obtain its outlines causes the pathforall and upath operators
to be disabled for as long as those outlines remain in the current path.

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck

SEE ALSO: show, flattenpath, pathbbox, clip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*clear* any1 ... anyn clear

pops all objects from the operand stack and discards them.

ERRORS: (none)

SEE ALSO: count, cleartomark, pop
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cleardictstack* - cleardictstack -

pops all dictionaries off the dictionary stack except for the permanent
entries. In Level 1 implementations the permanent entries are systemdict
and userdict; in Level 2 they are systemdict, globaldict, and userdict.
(In Level 1 implementations, cleardictstack is a procedure defined in
userdict instead of an operator defined in systemdict.)

ERRORS: dictstackunderflow

ERRORS: (none)

SEE ALSO: begin, end
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cleartomark* mark obj1 ... objn cleartomark -

pops the operand stack repeatedly until it encounters a mark, which it also
pops from the stack
(obj1 through objn are any objects other than marks).

ERRORS: unmatchedmark

SEE ALSO: clear, mark, counttomark, pop
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*clip* - clip -

intersects the inside of the current clipping path with the inside of the
current path to produce a new, smaller current clipping path.
The inside of the current path is determined by the normal PostScript
non-zero winding number rule , while the inside of the current clipping
path is determined by whatever rule was used at the time that path was
created.

In general, clip produces a new path whose inside (according to the
non-zero winding number rule) consists of all areas that are inside both of
the original paths. The way this new path is constructed (the order of its
segments, whether it self-intersects, etc.) is not specified.
clip treats an open subpath of the current path as though it were closed;
it does not actually alter the path itself. It is permissible for the
current path to be empty. The result of executing clip is always a
non-empty clipping path, though it may enclose zero area.

There is no way to enlarge the current clipping path (other than by
initclip or initgraphics) or to set a new clipping path without reference
to the current one. The recommended way of using clip is to bracket the
clip and the sequence of graphics to be clipped with gsave and grestore.
The grestore will restore the clipping path that was in effect before the
gsave. The setgstate operator can also be used to reset the clipping path
to an earlier state.

Unlike fill and stroke, clip does not implicitly perform a newpath after it
has finished using the current path. Any subsequent path construction
operators will append to the current path unless newpath is executed
explicitly. This can cause unexpected behavior.

ERRORS: limitcheck

SEE ALSO: eoclip, clippath, initclip, rectclip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*clippath* - clippath -

sets the current path to one that describes the current clipping path.
This operator is useful for determining the exact extent of the imaging
area on the current output device.

If the current clipping path is the result of application of the clip or
eoclip operator, the path set by clippath is generally suitable only for
filling or clipping. It is not suitable for stroking because it may contain
interior segments or disconnected subpaths produced by the clipping
process.

EXAMPLE:
clippath 1 setgray fill

This erases (fills with white) the interior of the current clipping path.

ERRORS: (none)

SEE ALSO: clip, eoclip, initclip, rectclip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*closefile* file closefile -

closes file-in other words, breaks the association between the file object
and the underlying file. For an output file, closefile first performs a
flushfile. It may also take device-dependent actions, such as truncating a
disk file to the current position or transmitting an end-of-file
indication.

ERRORS: ioerror, stackunderflow, typecheck

SEE ALSO: file, filter, status
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*closepath* - closepath -

closes the current subpath by appending a straight line segment connecting
the current point to the subpath's starting point-generally, the point most
recently specified by moveto. If the current subpath is already closed or
the current path is empty, closepath does not do anything

closepath terminates the current subpath. Appending another segment to the
current path will begin a new subpath, even if it is drawn from the
endpoint reached by the closepath.

ERRORS: limitcheck

SEE ALSO: newpath, moveto, lineto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*colorimage* width height bits/comp matrix
datasrc0 ... datasrcn-1 multi ncomp colorimage - LEVEL 2

paints a sampled image onto the current page.
The description here only summarizes the colorimage operator.

The sampled image is a rectangular array of width x height sample values.
colorimage interprets the width, height, and matrix operands in the same
way as does image.

Each image sample consists of 1, 3, or 4 color components, as specified by
the ncomp operand. Each component consists of bits/comp bits (1, 2, 4, 8,
or 12). All components are the same size.

If ncomp is 1, the samples have only one (gray) component; the operation of
colorimage is equivalent to that of image using the first five operands. If
ncomp is 3, the samples consist of red, green, and blue components. If
ncomp is 4, the samples consist of cyan, magenta, yellow, and black
components. The 1, 3, and 4 component values are interpreted according to
the DeviceGray, DeviceRGB, and DeviceCMYK color spaces, respectively ,
regardless of the current color space.

The multi operand is a boolean that determines how colorimage is to obtain
sample data from its data sources. If multi is false, there is a single
data source, datasrc0; colorimage obtains all components from that source,
interleaved on a per-sample basis. If multi is true, there are ncomp data
sources, datasrc0 ... datasrcn-1, one for each component. The data sources
can be procedures, strings, or files, including filtered files. They must
all be of the same type .

Unlike image and imagemask, colorimage does not have an alternate form in
which the parameters are bundled into a single image dictionary operand. In
Level 2 implementations, given the appropriate image dictionary, the image
operator can do anything that colorimage can do, and many other things. For
example, image can interpret color samples in any color space, whereas
colorimage is limited to the DeviceGray, DeviceRGB, and DeviceCMYK color
spaces.

Execution of this operator is not permitted in certain circumstances.

ERRORS: invalidaccess, ioerror, limitcheck, rangecheck, stackunderflow,
typecheck,
undefined, undefinedresult

SEE ALSO: image, imagemask
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*concat* matrix concat -

concatenates matrix with the current transformation matrix (CTM).
Precisely, concat replaces the CTM by matrix x CTM . The effect of this is
to define a new user space whose coordinates are transformed into the
former user space according to matrix.

Examples

[72 0 0 72 0 0] concat
72 72 scale

The two examples have the same effect on the current transformation.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: concatmatrix, matrix, rotate, scale, setmatrix, translate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*concatmatrix* matrix1 matrix2 matrix3 concatmatrix matrix3

replaces the value of matrix3 by the result of multiplying matrix1 x
matrix2, and pushes the modified matrix3 back on the operand stack. This
operator does not affect the CTM.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: concat, matrix, rotate, scale, setmatrix, translate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*condition* - condition condition DPS

creates a new condition object, unequal to any condition object already in
existence, and pushes it on the operand stack. The condition initially has
no contexts waiting on it . Since a condition is a composite object,
creating one consumes VM. The condition's value is allocated in local or
global VM according to the current VM allocation mode.

ERRORS: stackoverflow, VMerror

SEE ALSO: wait, notify
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*configurationerror* (error) LEVEL 2

occurs when setpagedevice or setdevparams has been executed with a request
for a feature that either is not available in the interpreter
implementation or is not currently available because of the state of the
hardware. For setpagedevice, this error is generated only if the PolicyDict
entry in a page device dictionary specifies that an error should be
generated.

When a configurationerror is generated, a two-element array called
errorinfo is placed in $error. This array contains the key and value of the
request that could not be met.

SEE ALSO: setpagedevice, setdevparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*copy* any1 ... anyn n copy any1 ... anyn any1 ... anyn

array1 array2 copy subarray2
dict1 dict2 copy dict2
string1 string2 copy substring2
packedarray1 array2 copy subarray2
gstate1 gstate2 copy gstate2

performs two entirely different functions, depending on the type of the
topmost operand.

In the first instance, where the top element on the operand stack is a
non-negative integer n, copy pops n from the stack and duplicates the top n
elements on the operand stack as shown above. This form of copy operates
only on the objects themselves, not on the values of composite objects.

EXAMPLE:
1 2 3 2 copy -> 1 2 3 2 3
1 2 3 0 copy -> 1 2 3

In the other instances, copy copies all the elements of the first composite
object into the second. The composite object operands must be of the same
type, except that a packed array can be copied into an array. This form of
copy copies the value of a composite object. This is quite different from
dup and other operators that copy only the objects themselves . However,
copy performs only one level of copying. It does not apply recursively to
elements that are themselves composite objects; instead, the values of
those elements become shared.

In the case of arrays or strings, the length of the second object must be
at least as great as the first; copy returns the initial subarray or
substring of the second operand into which the elements were copied. Any
remaining elements of array2 or string2 are unaffected. copy cannot copy
into packed arrays, because they are read-only, but it can copy packed
arrays into ordinary arrays.

In the case of dictionaries, Level 1 implementations require that dict2
have a length of zero and a maxlength at least as great as the length of
dict1. Level 2 implementations do not impose this restriction, since
dictionaries can expand when necessary.

The attributes (literal or executable and access) of the result are
normally the same as those of the second operand. However, in Level 1
implementations, the access attribute of dict2 is copied from that of
dict1.

If the value of the destination object is in global VM and any of the
elements copied from the source object are composite objects whose values
are in local VM, an invalidaccess error occurs .

EXAMPLE:
/a1 [1 2 3] def
a1 dup length array copy -> [1 2 3]

ERRORS: invalidaccess, stackoverflow, rangecheck, stackunderflow, typecheck

SEE ALSO: dup, get, put, putinterval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*copypage* - copypage -

transmits one copy of the current page to the current output device without
erasing the current page or changing the graphics state. This is in
contrast to showpage, which performs the equivalent of an erasepage and an
initgraphics. Aside from these differences, the behavior of copypage is
identical to that of showpage.

copypage is intended primarily as a debugging aid or as a means of printing
successive pages with incrementally accumulated contents. Routine use of
copypage as a substitute for showpage may severely degrade the page
throughput of some PostScript printers. To print multiple copies of the
same page, use the #copies implicit parameter of showpage or the NumCopies
parameter of setpagedevice.

ERRORS: (none)

SEE ALSO: showpage, erasepage
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cos* angle cos real

returns the cosine of angle, which is interpreted as an angle in degrees.
The result is a real.

EXAMPLE:
0 cos -> 1.0
90 cos -> 0.0

ERRORS: stackunderflow, typecheck

SEE ALSO: atan, sin
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*count* any1 ... anyn count any1 ... anyn n

counts the number of items on the operand stack and pushes this count on
the operand stack.

EXAMPLE:
clear count -> 0
clear 1 2 3 count -> 1 2 3 3

ERRORS: stackoverflow

SEE ALSO: counttomark
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*countdictstack* - countdictstack int

counts the number of dictionaries currently on the dictionary stack and
pushes this count on the operand stack.

ERRORS: stackoverflow

SEE ALSO: dictstack, begin, end
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*countexecstack* - countexecstack int

counts the number of objects on the execution stack and pushes this count
on the operand stack.

ERRORS: stackoverflow

SEE ALSO: execstack
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*counttomark* mark obj1 ... objn counttomark mark obj1 ... objn n

counts the number of objects on the operand stack starting with the top
element and continuing down to but not including the first mark
encountered. obj1 through objn are any objects other than marks.

EXAMPLE:
1 mark 2 3 counttomark -> 1 mark 2 3 2
1 mark counttomark -> 1 mark 0

ERRORS: stackoverflow, unmatchedmark

SEE ALSO: mark, count
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cshow* proc string cshow - LEVEL 2

invokes proc once for each operation of the font mapping algorithm. The
value of currentfont during
the execution of proc is the base font that the algorithm ultimately
selects. When proc is invoked, the stack contains three values: the
selected character's code (an integer) and the x and y components of the
width vector for the character in the user coordinate system. cshow does
not paint the character and does not change the current point, although
proc may do so. When proc completes execution, the value of currentfont is
restored.

cshow can be used to provide careful positioning of individual characters
while taking advantage of the composite font mapping machinery of the
interpreter. cshow is intended primarily for use with composite fonts .
However, it can also be used with a base font. The mapping algorithm for a
base font simply selects consecutive characters from the string.

ERRORS: invalidfont, invalidaccess, nocurrentpoint, rangecheck,
stackunderflow, typecheck

SEE ALSO: ashow, awidthshow, kshow, show ,widthshow, xshow, xyshow, yshow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentblackgeneration* - currentblackgeneration proc LEVEL 2

returns the current black generation function in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setblackgeneration
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcacheparams* - currentcacheparams mark size lower upper LEVEL 2

pushes a mark object followed by the current cache parameters on the
operand stack. The number of cache parameters returned is variable (see
setcacheparams).

ERRORS: stackoverflow

SEE ALSO: setcacheparams, setsystemparams, setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcmykcolor* - currentcmykcolor cyan magenta yellow black LEVEL 2

returns the current color in the graphics state according to the
cyan-magenta-yellow-black color space. If the current color space is
DeviceCMYK, currentcmykcolor returns the color values most recently
specified by setcmykcolor or setcolor. If the current color space is
DeviceRGB or DeviceGray, currentcmykcolor converts the current color to
CMYK. For any other color space, currentcmykcolor returns 0.0 0.0 0.0 1.0.

ERRORS: stackoverflow

SEE ALSO: setcmykcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcolor* - currentcolor comp1 comp2 ... compm LEVEL 2

returns the components, in the current color space, of the color specified
by the current color parameters in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setcolor, setcolorspace
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcolorrendering* - currentcolorrendering dict LEVEL 2

returns the value of the CIE based color rendering dictionary parameter in
the graphics state.

ERRORS: stackoverflow

SEE ALSO: setcolorrendering
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcolorscreen* - currentcolorscreen redfreq redang redproc LEVEL 2
greenfreq greenang greenproc
bluefreq blueang blueproc
grayfreq grayang grayproc

     If the current halftone screen was specified by setcolorscreen,
     currentcolorscreen returns all 12 current halftone screen parameters
     in the graphics state.

     If the current screen was specified by setscreen,
     currentcolorscreen returns the three screen parameters repeated four
     times.

     If the current screen was specified by sethalftone,
     currentcolorscreen returns 60, 0, and the halftone dictionary,
     repeated four times.

ERRORS: stackoverflow

SEE ALSO: setcolorscreen, setscreen, sethalftone
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcolorspace* - currentcolorspace array LEVEL 2

returns an array containing the identifying key and parameters of the color
space in the graphics state. currentcolorspace always returns an array,
even if the color space has no parameters and was selected by presenting
just a name to setcolorspace.

ERRORS: stackoverflow

SEE ALSO: setcolorspace, setcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcolortransfer* - currentcolortransfer redproc greenproc blueproc
grayproc LEVEL 2

returns the current transfer functions in the graphics state for all four
color components.
If the current transfer functions were specified by setcolortransfer,
currentcolortransfer returns those four operands.
If settransfer was used, currentcolortransfer returns the single transfer
function, repeated four times.

ERRORS: stackoverflow

SEE ALSO: setcolortransfer, settransfer
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentcontext* - currentcontext context DPS

returns an integer that identifies the current execution context.

ERRORS: stackoverflow

SEE ALSO: fork, join, detach
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentdash* - currentdash array offset

returns the current dash array and offset in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setdash, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentdevparams* string currentdevparams dict LEVEL 2

returns a dictionary containing the keys and current values of all
parameters for the device identified by string. The returned dictionary is
merely a container for key-value pairs. Each execution of currentdevparams
allocates and returns a new dictionary.

ERRORS: stackoverflow, VMerror

SEE ALSO: setdevparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentdict* - currentdict dict

pushes the current dictionary (the dictionary on top of the dictionary
stack) on the operand stack. currentdict does not pop the dictionary stack;
it just pushes a duplicate of its top element on the operand stack.

ERRORS: stackoverflow

SEE ALSO: begin, dictstack
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentfile* - currentfile file

returns the file object from which the PostScript interpreter is currently
or was most recently reading program input. Precisely, currentfile returns
the topmost file object on the execution stack. If there isn't one, it
returns an invalid file object that doesn't correspond to any file. This
never occurs during execution of ordinary user programs.

The file returned by currentfile is usually but not always the standard
input file. An important exception occurs during interactive mode operation
.. In this case, the interpreter does not read directly from the standard
input file; instead, it reads from a file representing an edited statement
(each statement is represented by a different file).

The currentfile operator is useful for obtaining images or other data
residing in the program file itself (see the example below). At any given
time, this file is positioned at the end of the last PostScript
language token read from the file by the interpreter. If that token was a
number or a name immediately followed by a white space character, the file
is positioned after the white space character (the first, if there are
several). Otherwise it is positioned after the last character of the token.

EXAMPLE:
/str 100 string def
currentfile str readline
here is a line of text
pop /textline exch def

After execution of this example, the name /textline
is associated with the string "here is a line of text".

ERRORS: stackoverflow

SEE ALSO: exec, run
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentflat* - currentflat num

returns the current value of the flatness parameter in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setflat, flattenpath, stroke, fill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentfont* - currentfont font

returns the current font dictionary in the graphics state. Normally, this
is the font most recently established by setfont or selectfont. However,
when executed inside a font's BuildGlyph or BuildChar procedure or a
procedure invoked by cshow, currentfont returns the currently selected base
font (descendant of a composite font).

ERRORS: stackoverflow

SEE ALSO: rootfont, selectfont, setfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentglobal* - currentglobal bool LEVEL 2

returns the VM allocation mode currently in effect.

ERRORS: stackoverflow

SEE ALSO: setglobal
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentgray* - currentgray num

returns the gray value of the current color parameter in the graphics
state. If the current color space is DeviceGray, currentgray returns the
color value most recently specified to setgray or setcolor. If the current
color space is DeviceRGB or DeviceCMYK, currentgray converts the current
color to a gray value. For any other color space, currentgray returns 0.0.

ERRORS: stackoverflow

SEE ALSO: setgray, currentcolor, currentcolorspace, currenthsbcolor,
currentrgbcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentgstate* gstate currentgstate gstate LEVEL 2

replaces the value of the gstate object by a copy of the current graphics
state and pushes gstate back on the operand stack. If gstate is in global
VM , currentgstate will generate an invalidaccess error if any of the
composite objects in the current graphics state are in local VM. Such
objects might include the current font, screen function, halftone
dictionary, transfer function, or dash pattern. In general, allocating
gstate objects in global VM is risky and should be avoided.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: gstate, setgstate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currenthalftone* - currenthalftone halftone LEVEL 2

returns the current halftone dictionary in the graphics state. If the
current halftone was defined by setscreen or setcolorscreen instead of by
sethalftone, currenthalftone fabricates and returns a halftone dictionary
(type 1 or 2) that contains the screen parameters.

ERRORS: stackoverflow, VMerror

SEE ALSO: setscreen, setcolorscreen , sethalftone
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currenthalftonephase* - currenthalftonephase x y DPS

returns the current values of the halftone phase parameters in the graphics
state. If sethalftonephase has not been executed, zero is returned for both
values.

ERRORS: stackoverflow

SEE ALSO: sethalftonephase
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currenthsbcolor* - currenthsbcolor hue saturation brightness

returns the current color parameter in the graphics state according to the
huesaturation-brightness model. If the current color space is DeviceRGB,
currenthsbcolor returns the color values most recently specified by
sethsbcolor, setrgbcolor, or setcolor, converting them from RGB to HSB
coordinates if necessary. If the current color space is DeviceGray or
DeviceCMYK, currenthsbcolor first converts the current color to RGB.
For any other color space, currenthsbcolor returns 0.0 0.0 0.0.

ERRORS: stackoverflow

SEE ALSO: sethsbcolor, currentcolor, currentgray, currentrgbcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentlinecap* - currentlinecap int

returns the current value of the line cap parameter in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setlinecap, stroke, currentlinejoin
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentlinejoin* - currentlinejoin int

returns the current value of the line join parameter in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setlinejoin, stroke, currentlinecap
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentlinewidth* - currentlinewidth num

returns the current value of the line width parameter in the graphics
state.

ERRORS: stackoverflow

SEE ALSO: setlinewidth, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentmatrix* matrix currentmatrix matrix

replaces the value of matrix with the value of the current transformation
matrix (CTM) in the graphics state, and pushes the modified matrix back on
the operand stack .

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: setmatrix, defaultmatrix, initmatrix, rotate, scale, translate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentmiterlimit* - currentmiterlimit num

returns the current value of the miter limit parameter in the graphics
state.

ERRORS: stackoverflow

SEE ALSO: setmiterlimit, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentobjectformat* - currentobjectformat int LEVEL 2

returns the object format parameter currently in effect.

ERRORS: stackoverflow

SEE ALSO: setobjectformat
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentoverprint* - currentoverprint bool LEVEL 2

returns the value of the overprint parameter in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setoverprint
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentpacking* - currentpacking bool LEVEL 2

returns the array packing mode currently in effect.

ERRORS: stackoverflow

SEE ALSO: setpacking, packedarray
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentpagedevice* - currentpagedevice dict LEVEL 2

returns a read-only dictionary that describes the page-oriented output
device in the current graphics state. currentpagedevice creates a new
dictionary if necessary. If the device in the current graphics state is not
a page device, currentpagedevice returns an empty dictionary (length of 0).

Changes made to the hardware state of the output device since the last
execution of setpagedevice, such as changing paper trays or switches, are
not immediately reflected in this dictionary. If the current context is
under the control of a job server, the server sets up a device that matches
the hardware state before starting each job. At the beginning of each job,
therefore, the dictionary currentpagedevice returns matches the current
hardware state.

ERRORS: stackoverflow, VMerror

SEE ALSO: setpagedevice
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentpoint* - currentpoint x y

returns the x and y coordinates of the current point in the graphics state
(i.e., the trailing endpoint of the current path). If the current point is
undefined because the current path is empty, currentpoint executes the
nocurrentpoint error.
The current point is reported in the user coordinate system. Points entered
into a path are immediately converted to device coordinates by the current
transformation matrix (CTM); existing points are not changed by subsequent
modifications to the CTM. currentpoint computes the user space coordinate
that corresponds to the current point according to the current value of the
CTM. If a current point is set and then the CTM is changed, currentpoint
will report a different position in user space than it did before.

ERRORS: nocurrentpoint, stackoverflow, undefinedresult

SEE ALSO: lineto, moveto, curveto, arc
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentrgbcolor* - currentrgbcolor red green blue

returns the three components of the current color in the graphics state
according to the red-green-blue color model. If the current color space is
DeviceRGB, currentrgbcolor returns the color values most recently specified
to setrgbcolor or setcolor (or transformed values specified to
sethsbcolor). If the current color space is DeviceGray or DeviceCMYK,
currentrgbcolor converts the current color to RGB.
For any other color space, currentrgbcolor returns 0.0 0.0 0.0.

ERRORS: stackoverflow

SEE ALSO: setrgbcolor, currentcolor, currentgray, currenthsbcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentscreen* - currentscreen frequency angle proc
- currentscreen 60 0 halftone

returns the current halftone screen parameters (frequency, angle, and proc)
in the graphics state, assuming the current screen was established by
setscreen. If setcolorscreen was executed, currentscreen returns the
parameters for the gray screen.
If sethalftone was executed, currentscreen returns a frequency of 60, an
angle of 0, and the halftone dictionary.

ERRORS: stackoverflow

SEE ALSO: setcolorscreen, setscreen, sethalftone
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentshared* - currentshared bool LEVEL 2

has the same semantics as currentglobal. This operator is defined for
compatibility with existing Display PostScript applications.

ERRORS: stackoverflow

SEE ALSO: setglobal, setshared
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentstrokeadjust* - currentstrokeadjust bool LEVEL 2

returns the current stroke adjust parameter in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setstrokeadjust
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentsystemparams* - currentsystemparams dict LEVEL 2

returns a dictionary containing the keys and current values of all system
parameters that are defined in the implementation. The returned dictionary
is merely a container for key-value pairs. Each execution of
currentsystemparams allocates and returns a new dictionary.

ERRORS: stackoverflow, VMerror

SEE ALSO: setsystemparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currenttransfer* - currenttransfer proc

returns the current transfer function in the graphics state, assuming that
it was established by settransfer. If setcolortransfer was executed,
currenttransfer returns the gray transfer function.

ERRORS: stackoverflow

SEE ALSO: settransfer, setcolortransfer
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentundercolorremoval* - currentundercolorremoval proc LEVEL 2

returns the current undercolor removal function in the graphics state.

ERRORS: stackoverflow

SEE ALSO: setundercolorremoval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*currentuserparams* - currentuserparams dict

returns a dictionary containing the keys and current values of all user
parameters that are defined in the implementation. The returned dictionary
is a container for key-value pairs. Each execution of currentuserparams
allocates and returns a new dictionary.

ERRORS: stackoverflow, VMerror

SEE ALSO: setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*curveto* x1 y1 x2 y2 x3 y3 curveto -

adds a Bezier cubic section to the current path between the current point,
referred to here as (x0, y0), and the point (x3, y3), using (x1, y1) and
(x2, y2) as the Bezier cubic control points. After constructing the curve,
curveto makes (x3, y3) the new current point. If the current point is
undefined because the current path is empty, curveto executes the error
nocurrentpoint.

The four points define the shape of the curve geometrically. The curve
starts at (x0, y0), it is tangent to the line from (x0, y0) to (x1, y1) at
that point, and it leaves the point in that direction. The curve ends at
(x3, y3), it is tangent to the line from (x2, y2) to (x3, y3) at that
point, and it approaches the point from that direction. The lengths of the
lines (x0, y0) to (x1, y1) and (x2, y2) to (x3, y3) represent, in a sense,
the "velocity" of the path at the endpoints. The curve is always entirely
enclosed by the convex quadrilateral defined by the four points.

The mathematical formulation of a Bezier cubic curve is derived from a pair
of parametric cubic equations:

The cubic section produced by curveto is the path traced by x(t) and y(t)
as t ranges from 0 to 1. The Bezier control points corresponding to this
curve are:

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck

SEE ALSO: lineto, moveto, arc, arcn, arct, arcto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvi* num cvi int
string cvi int

(convert to integer) takes an integer, real, or string object from the
stack and produces an integer result. If the operand is an integer, cvi
simply returns it. If the operand is a real, it truncates any fractional
part (i.e., rounds it toward 0) and converts it to an integer. If the
operand is a string, it interprets the characters of the string as a number
according to the PostScript syntax rules. If that number is a real, cvi
converts it to an integer. cvi executes a rangecheck error if a real is too
large to convert to an integer. (See the round, truncate, floor, and
ceiling operators, which remove fractional parts without performing type
conversion.)

EXAMPLE:
(3.3E1) cvi -> 33
-47.8 cvi -> -47
520.9 cvi -> 520

ERRORS: invalidaccess, rangecheck, stackunderflow, syntaxerror, typecheck,
undefinedresult

SEE ALSO: cvr, ceiling, floor, round, truncate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvlit* any cvlit any

(convert to literal) makes the object on the top of the operand stack have
the literal instead of executable attribute.

ERRORS: stackunderflow

SEE ALSO: cvx, xcheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvn* string cvn name

(convert to name) converts the string operand to a name object that is
lexically the same as the string. The name object is executable if the
string was.

EXAMPLE:
(abc) cvn -> /abc
(abc) cvx cvn -> abc

ERRORS: invalidaccess, limitcheck, stackunderflow, typecheck

SEE ALSO: cvs, type
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvr* num cvr real
string cvr real

(convert to real) takes an integer, real, or string object and produces a
real result. If the operand is an integer, cvr converts it to a real. If
the operand is a real, cvr simply returns it. If the operand is a string,
it interprets the characters of the string as a number according to the
PostScript syntax rules. If that number is an integer, cvr converts it to a
real.

ERRORS: invalidaccess, limitcheck, stackunderflow, syntaxerror, typecheck,
undefinedresult

SEE ALSO: cvi
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvrs* num radix string cvrs substring

(convert to string with radix) produces a text representation of the number
num in the specified radix, stores the text into the supplied string
(overwriting some initial portion of its value), and returns a string
object designating the substring actually used. If string is too small to
hold the result of the conversion, cvrs executes the error rangecheck.

If radix is 10, cvrs produces the same result as cvs when applied to either
an integer or a real. That is, it produces a signed integer or real token
that conforms to the PostScript language syntax for that number.

If radix is not 10, cvrs converts num to an integer, as if by cvi. Then it
treats the machine representation of that integer as an unsigned positive
integer and converts it to text form according to the specific radix. The
resulting text is not necessarily a valid number. However, if it is
immediately preceded by the same radix and #, the combination is a valid
PostScript language token that represents the same number.

EXAMPLE:
/temp 12 string def
123 10 temp cvrs -> (123)
-123 10 temp cvrs -> (-123)
123.4 10 temp cvrs -> (123.4)
123 16 temp cvrs -> (7B)
-123 16 temp cvrs -> (FFFFFF85)
123.4 16 temp cvrs -> (7B)

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck

SEE ALSO: cvs
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvs* any string cvs substring

(convert to string) produces a text representation of an arbitrary object
any, stores the text into the supplied string (overwriting some initial
portion of its value), and returns a string object designating the
substring actually used. If the string is too small to hold the result of
conversion, cvs executes the error rangecheck.

If any is a number, cvs produces a string representation of that number. If
any is a boolean, cvs produces either the string true or the string false.
If any is a string, cvs copies its contents into string. If any is a name
or an operator, cvs produces the text representation of that name or the
operator's name. If any is any other type, cvs produces the text
--nostringval--.

If any is a real number, the precise format of the result string is
implementation dependent and not under program control. For example, the
value 0.001 might be represented as 0.001 or as 1.0E-3.

EXAMPLE:
/str 20 string def
123 456 add str cvs -> (579)
mark str cvs -> (--nostringval--)

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck

SEE ALSO: cvi, cvr, string, type
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*cvx* any cvx any

(convert to executable) makes the object on top of the operand stack have
the executable instead of literal attribute.

ERRORS: stackunderflow

SEE ALSO: cvlit, xcheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*def* key value def
- associates key with value in the current dictionary-the one on the top of
the dictionary stack . If key is already present in the current dictionary,
def simply replaces its value. Otherwise, def creates a new entry for key
and stores value with it.

If the current dictionary is in global VM and value is a composite object
whose value is in local VM, an invalidaccess error occurs .

EXAMPLE:
/ncnt 1 def % Define ncnt to be 1 in current
dict
/ncnt ncnt 1 add def % ncnt now has value 2

ERRORS: dictfull, invalidaccess, limitcheck, stackunderflow, typecheck,
VMerror

SEE ALSO: store, put
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*defaultmatrix* matrix defaultmatrix matrix

replaces the value of matrix with the default transformation matrix for the
current output device and pushes this modified matrix back on the operand
stack.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: currentmatrix, initmatrix, setmatrix
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*definefont* key font definefont font

registers font as a font dictionary associated with key (usually a name).
definefont first checks that font is a well-formed font dictionary-in other
words, contains all required key-value pairs. It inserts an additional
entry whose key is FID and whose value is an object of type fontID. The
dictionary must be large enough to accommodate this additional entry. It
makes the dictionary's access read-only. Finally, it associates key with
font in the font directory.

In Level 2, it is permissible to associate a font dictionary with more than
one key. If font has already been registered, definefont does not alter it
in any way.

If font is a composite font , definefont also inserts the entries MIDVector
and CurMID, and adds entries PrefEnc, EscChar, ShiftIn, and ShiftOut if
they are required and are not already present. All the descendant fonts
must have been registered by definefont previously.

Subsequent invocation of findfont with key will return font. Font
registration is subject to the normal semantics of VM . In particular, the
lifetime of the definition depends on the VM allocation mode at the time
definefont is executed. A local definition can be undone by a subsequent
restore.

definefont is actually a special case of defineresource operating on the
Font category.

ERRORS: limitcheck, rangecheck, dictfull, invalidfont, stackunderflow,
typecheck, invalidaccess

SEE ALSO: makefont, scalefont, setfont, defineresource, FontDirectory,
GlobalFontDirectory, setglobal
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*defineresource* key instance category defineresource instance LEVEL 2

associates a resource instance with a resource name in a specified
category. category is a name object that identifies a resource category,
such as Font . key is a name or string object that will be used to identify
the resource instance. (Names and strings are interchangeable; other types
of keys are permitted but are not recommended.) instance is the resource
instance itself; its type must be appropriate to the resource category.

Before defining the resource instance, defineresource verifies that the
instance object is the correct type. Depending on the resource category, it
may also perform additional validation of the object and may have other
side effects. Finally, it makes the object read-only if its access is not
already restricted.

The lifetime of the definition depends on the VM allocation mode in effect
at the time defineresource is executed. If local VM allocation is in effect
(currentglobal returns false), the effect of defineresource is undone by
the next nonnested restore. If global VM allocation is in effect
(currentglobal returns true), the effect of defineresource persists until
global VM is restored at the end of the job. If the current job is not
encapsulated, the effect of a global defineresource persists indefinitely,
and may be visible to other execution contexts.

Local and global definitions are maintained separately. If a new resource
instance is defined with the same category and key as an existing one, the
new definition overrides the old one. The precise effect depends on whether
the old definition is local or global and whether the new definition
(current VM allocation mode) is local or global. There are two main cases:

   * New definition is local-defineresource installs the new local
     definition, replacing an existing local definition if there is one. If
     there is an existing global definition, defineresource does not
     disturb it. However, the global definition is obscured by the local
     one. If the local definition is later removed, the global definition
     reappears.

   * New definition is global-defineresource first removes an existing
     local definition if there is one. It then installs the new global
     definition, replacing an existing global definition if there is one.

It is permissible to use defineresource multiple times to associate a given
resource instance with more than one key.

If the category name is unknown, an undefined error occurs. If the instance
is of the wrong type for the specified category, a typecheck error occurs.
If the instance is in local VM but the current VM allocation mode is
global, an invalidaccess error occurs. This is analogous to storing a local
object into a global dictionary. Other errors can occur for specific
categories. For example, when dealing with the Font category,
defineresource can execute an invalidfont error.

ERRORS: invalidaccess, stackunderflow, typecheck, undefined

SEE ALSO: undefineresource, findresource, resourcestatus, resourceforall
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*defineusername* index name defineusername - DPS

establishes an association between the non-negative integer index and the
name object name in the user name table. Subsequently, the scanner will
substitute name when it encounters any binary encoded name token or object
that refers to the specified user name index. Because binary encoded names
specify their own literal or executable attributes, it does not matter
whether name is literal or executable.

The user name table is an adjunct to the current context's local VM. The
effect of adding an entry to the table is immediately visible to all
contexts that share the same local VM. Additions to the table are not
affected by save and restore. The association between index and name
persists for the remaining lifetime of the local VM.

The specified index must previously be unused in the name table or must
already be associated with the same name. Changing an existing association
is not permitted (an invalidaccess error will occur). There may be an
implementation limit on index values. Assigning index values sequentially
starting at zero is strongly recommended.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*defineuserobject* index any defineuserobject - LEVEL 2

establishes an association between the non-negative integer index and the
object any in the UserObjects array. First, it creates a UserObjects array
in userdict if one is not already present. It extends an existing
UserObjects array if necessary. It then executes the equivalent of

userdict /UserObjects get
3 1 roll put

In other words, it simply stores any into the array at the position
specified by index.

If defineuserobject creates or extends the UserObjects array, it allocates
the array in local VM, regardless of the current VM allocation mode.

The behavior of defineuserobject obeys normal PostScript language semantics
in all respects. In particular, the modification to the UserObjects array
and to userdict, if any, is immediately visible to all contexts that share
the same local VM. It can be undone by a subsequent restore according to
the usual VM rules. index values must be within the range permitted for
arrays; a large index value may cause allocation of an array that would
exhaust VM resources. Assigning index values sequentially starting at zero
is strongly recommended.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck, VMerror

SEE ALSO: execuserobject, undefineuserobject, UserObjects
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*deletefile* filename deletefile - LEVEL 2

removes the specified file from its storage device. If no such file exists,
an undefinedfilename error occurs. If the device does not allow this
operation, an invalidfileaccess error occurs. If an environment dependent
error is detected, an ioerror occurs.

ERRORS: invalidfileaccess, ioerror, stackunderflow, typecheck ,
undefinedfilename

SEE ALSO: file, renamefile, status
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*detach* context detach - DPS

specifies that the execution context identified by the integer context is
to terminate immediately when it finishes executing its top-level
procedure, whereas ordinarily it would wait for a join. If the context is
already waiting for a join, detach causes it to terminate immediately.

detach executes an invalidcontext error if context is not a valid context
identifier or if the context has already been joined or detached. It is
permissible for context to identify the current context.

ERRORS: invalidcontext, stackunderflow, typecheck

SEE ALSO: currentcontext, fork, join
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*deviceinfo* - deviceinfo dict DPS

returns a read-only dictionary containing static information about the
current device. The composition of this dictionary varies according to the
properties of the device. The information in the dictionary may not be
meaningful for a page-oriented or other non-display device.

The use of deviceinfo after a setcachedevice operation within the scope of
a BuildChar procedure is not permitted. An undefined error results.

ERRORS: stackoverflow, undefined
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dict* int dict dict

creates an empty dictionary with an initial capacity of int elements and
pushes the created dictionary object on the operand stack. int is expected
to be a nonnegative integer. The dictionary is allocated in local or global
VM according to the VM allocation mode.

In Level 1 implementations, the resulting dictionary has a maximum capacity
of int elements. Attempting to exceed that limit causes a dictfull error.

In Level 2 implementations, the int operand specifies only the initial
capacity; the dictionary can grow beyond that capacity if necessary. The
dict operator immediately consumes sufficient VM to hold int key-value
pairs. If more than that number of entries are subsequently stored in the
dictionary, additional VM is consumed at that time.

There is a cost associated with expanding a dictionary beyond its initial
allocation. For efficiency reasons, a dictionary is expanded in chunks
rather than one element at a time, so it may contain a substantial amount
of unused space. If a program knows how large a dictionary it needs, it
should create one of that size initially. On the other hand, if a program
cannot predict how large the dictionary will eventually grow, it should
choose a small initial allocation sufficient for its immediate needs. The
built-in writable dictionaries (for example, userdict) follow the latter
convention.

ERRORS: limitcheck, stackunderflow, typecheck, VMerror

SEE ALSO: begin, end, length, maxlength
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dictfull* (error)

occurs when def, put, or store attempts to define a new entry in a
dictionary that is already full-in other words, whose length and maxlength
are already equal. This can occur only in Level 1 implementations, where a
dictionary has a fixed limit on the number of entries with distinct keys it
can hold. This limit is established by the operand to the dict operator
that creates the dictionary.

SEE ALSO: def, put, store, dict
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dictstack* array dictstack subarray

stores all elements of the dictionary stack into array and returns an
object describing the initial n-element subarray of array, where n is the
current depth of the dictionary stack. dictstack copies the topmost
dictionary into element n-1 of array and the bottommost one into element 0
of array. The dictionary stack itself is unchanged. If the length of array
is less than the depth of the dictionary stack, dictstack executes a
rangecheck error.

ERRORS: invalidaccess, rangecheck, , stackunderflow, typecheck

SEE ALSO: countdictstack
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dictstackoverflow* (error)

The dictionary stack has grown too large. Too many begin operators without
corresponding end operators have pushed too many dictionaries on the
dictionary stack.

Before invoking this error, the interpreter creates an array containing all
elements of the dictionary stack stored as if by dictstack, pushes this
array on the operand stack, and resets the dictionary stack to contain only
the permanent entries.

SEE ALSO: begin, countdictstack, cleardictstack
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dictstackunderflow* (error)

An attempt has been made to remove (end) the bottommost instance of
userdict from the dictionary stack. This occurs if an end is executed for
which there was no corresponding begin.

SEE ALSO: end
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*div* num1 num2 div quotient

divides num1 by num2, producing a result that is always a real even if both
operands are integers. Use idiv if an integer result is desired.

EXAMPLE:
3 2 div -> 1.5
4 2 div -> 2.0

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: idiv, add, mul, sub, mod
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dtransform* dx dy dtransform dx` dy`
dx dy matrix dtransform dx` dy`

With no matrix operand, dtransform (delta transform) transforms the
distance vector (dx, dy) by the CTM to produce the corresponding distance
vector (dx`, dy`) in device space. If the matrix operand is supplied,
dtransform transforms the distance vector by matrix rather than by CTM.

A delta transformation is similar to a normal transformation , but the
translation components (tx and ty) of the transformation matrix are not
used, making the distance vectors positionless in both user space and
device space. This is useful for determining how distances map from user
space to device space.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: idtransform, transform, itransform
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*dup* any dup any any

duplicates the top element on the operand stack. Note that dup copies only
the object. The value of a composite object is not copied but is shared.

ERRORS: stackoverflow, stackunderflow

SEE ALSO: copy, index
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*echo* bool echo
- specifies whether the special files %lineedit and %statementedit are to
copy characters from the standard input file to the standard output file.
This affects only the behavior of executive; it does not apply to normal
communication with the PostScript interpreter.
echo is not defined in products that do not support executive.

ERRORS: stackunderflow, typecheck

SEE ALSO: executive, file
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*eexec* file eexec
string eexec -

causes the contents of file (open for reading) or string to be decrypted
and then executed in a manner similar to the exec operator. The decryption
operation does not cause the file or string to be modified.

eexec creates a new file object that serves as a decryption filter on the
specified file or string. It pushes the new file object on the execution
stack, making it the current file for the PostScript interpreter.
Subsequently, each time the interpreter reads a character from this file,
or a program reads explicitly from currentfile, the decryption filter reads
one character from the original file or string and decrypts it.

The decryption filter file is closed automatically when the end of the
original file or string is encountered. It may also be closed explicitly by
closefile. If the file passed to eexec was currentfile, this resumes direct
execution of that file with the decryption filter removed. The file may
consist of encrypted text followed by unencrypted text if the last thing
executed in the encrypted text is currentfile closefile.

Before beginning execution, eexec pushes systemdict on the dictionary
stack. This ensures that the operators executed by the encrypted program
have their standard meanings. When the decryption filter file is closed
either explicitly or implicitly, the dictionary stack is popped. The
program must be aware that it is being executed with systemdict as the
current dictionary; in particular, any definitions that it makes must be
into a specific dictionary rather than the current one, since systemdict is
read-only.

The encrypted file may be represented in either binary or hex; the eexec
operator can decrypt it without being told which type it is. The
recommended representation is hex, because hex data can be transmitted
through communication channels that are not completely transparent.
Regardless of the representation of the encrypted file, the encryption and
decryption processes are transparent. That is, an arbitrary binary file can
be encrypted, transmitted as either binary or hex, and decrypted to yield
the original information.

The encryption employed by eexec is intended primarily for use in Type 1
font programs. The book Adobe Type 1 Font Format contains a complete
description of the encryption algorithm and recommended uses of eexec.

ERRORS: dictstackoverflow, invalidaccess, invalidfileaccess, limitcheck,
stackunderflow, typecheck

SEE ALSO: exec, filter
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*end* - end -

pops the current dictionary off the dictionary stack, making the dictionary
below it the current dictionary. If end tries to pop the bottommost
instance of userdict, it executes the error dictstackunderflow.

ERRORS: dictstackunderflow

SEE ALSO: begin, dictstack, countdictstack
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*eoclip* - eoclip -

intersects the inside of the current clipping path with the inside of the
current path to produce a new, smaller current clipping path. The inside of
the current path is determined by the even-odd rule, while the inside of
the current clipping path is determined by whatever rule was used at the
time that path was created.

Except for the choice of insideness rule, the behavior of eoclip is
identical to that of clip.

ERRORS: limitcheck

SEE ALSO: clip, clippath, initclip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*eofill* - eofill -

paints the inside of the current path with the current color, using the
even-odd rule to determine what points are inside. Except for the choice of
insideness rule, the behavior of eofill is identical to that of fill.

ERRORS: limitcheck

SEE ALSO: fill, ineofill, ueofill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*eoviewclip* - eoviewclip LEVEL 2

is similar to viewclip, except that it uses the even-odd rule to determine
the inside of the current path.

ERRORS: limitcheck

SEE ALSO: viewclip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*eq* any1 any2 eq bool

pops two objects from the operand stack and pushes the boolean value true
if they are equal, false if not. The definition of equality depends on the
types of the objects being compared. Simple objects are equal if their
types and values are the same. Strings are equal if their lengths and
individual elements are equal. Other composite objects (arrays and
dictionaries) are equal only if they share the same value. Separate values
are considered unequal, even if all the components of those values are the
same.

Some type conversions are performed by eq. Integers and reals can be
compared freely: An integer and a real representing the same mathematical
value are considered equal by eq. Strings and names can likewise be
compared freely: A name defined by some sequence of characters is equal to
a string whose elements are the same sequence of characters.

The literal/executable and access attributes of objects are not considered
in comparisons between objects.

EXAMPLE:
4.0 4 eq -> true % A real and an integer may be equal
(abc) (abc) eq -> true % Strings with equal elements are equal

(abc) /abc eq -> true % A string and a name may be equal
[1 2 3] dup eq -> true % An array is equal to itself
[1 2 3] [1 2 3] eq -> false % Distinct array objects not equal

ERRORS: invalidaccess, stackunderflow

SEE ALSO: ne, le, lt, ge, gt
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*erasepage* - erasepage -

% different in the NeXT implementation

This standard PostScript operator has the following effect in the NeXT
implementation of the Display PostScript system: It erases the entire
window to opaque white.

erases the entire current page by painting it with gray level 1, which is
ordinarily white, but may be some other color if an atypical transfer
function has been defined. The entire page is erased, regardless of the
clip path currently in force. erasepage affects only the contents of raster
memory. It does not modify the graphics state nor does it cause a page to
be transmitted to the output device.

erasepage is executed automatically by showpage after imaging. There are
few situations in which a PostScript language page description should
execute erasepage explicitly, because the operator affects portions of the
current page outside the current clip path. It is usually more appropriate
to erase just the inside of the current clip path (see clippath). Then the
page description can be embedded within another, composite page without
undesirable effects.

ERRORS: invalidid

SEE ALSO: showpage, clippath, fill, copypage
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*errordict* - errordict dict

pushes the dictionary object errordict on the operand stack . errordict is
not an operator; it is a name in systemdict associated with the dictionary
object.

ERRORS: stackoverflow

SEE ALSO: $error
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*exch* any1 any2 exch any2 any1

exchanges the top two elements on the operand stack.

EXAMPLE:
1 2 exch -> 2 1

ERRORS: stackunderflow

SEE ALSO: dup, roll, index, pop
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*exec* any exec -

pushes the operand on the execution stack, executing it immediately. The
effect of executing an object depends on the object's type and
literal/executable attribute. In particular, executing a literal object
will cause it only to be pushed back on the operand stack. Executing a
procedure, however, will cause the procedure to be called.

EXAMPLE:
(3 2 add) cvx exec -> 5
3 2 /add exec -> 3 2 /add
3 2 /add cvx exec -> 5

In the first line, the string (3 2 add) is made executable and then
executed. Executing a string causes its characters to be scanned and
interpreted according to the PostScript language syntax rules.

In the second line, the literal objects 3, 2, and /add are pushed on the
operand stack, then exec is applied to the add. Since the add is a literal
name, executing it simply causes it to be pushed back on the operand stack.
The exec in this case has no useful effect.

In the third line, the literal name /add on the top of the operand stack is
made executable by cvx. Applying exec to this executable name causes it to
be looked up and the add operation to be performed.

ERRORS: stackunderflow

SEE ALSO: xcheck, cvx, run
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*execform* form execform - LEVEL 2

paints a form specified by a form dictionary . The graphical output
produced by execform is defined by the form dictionary's PaintProc
procedure.

If this is the first invocation of execform for form, execform first
verifies that the dictionary contains the required entries. Then it adds an
entry to the dictionary with the key Implementation, whose value is private
to the implementation. Finally, it makes the dictionary read-only.
(execform performs these alterations directly to the operand dictionary; it
does not copy the dictionary.)

When execform needs to call the PaintProc procedure, it pushes the form
dictionary on the operand stack, then executes the equivalent of

gsave % Operand stack: dict
dup /Matrix get concat
dup /BBox get aload pop % Stack: dict llx lly urx ury
exch 3 index sub
exch 2 index sub % Stack: dict llx lly width height
rectclip % Also does a newpath
dup /PaintProc get % Stack: dict proc
exec % Execute PaintProc with dict on stack
grestore

The PaintProc procedure is expected to consume the dictionary operand and
to execute a sequence of graphics operators to paint the form. The
PaintProc must always produce the same output, given the same graphics
state parameters, independent of the number of times it is called and
independent, for example, of the contents of userdict. The PostScript
language program should not expect any particular execution of execform to
cause execution of the specified PaintProc.

The documented errors are those produced directly by execform. Obviously,
the PaintProc can cause other errors.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck, undefined,
VMerror

SEE ALSO: findresource
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*execstack* array execstack subarray

stores all elements of the execution stack into array and returns an object
describing the initial n-element subarray of array, where n is the current
depth of the execution stack. execstack copies the topmost object into
element n-1 of array and the bottommost one into element 0 of array. The
execution stack itself is unchanged.
If the length of array is less than the depth of the execution stack,
execstack executes a rangecheck error.

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck

SEE ALSO: countexecstack, exec
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*execstackoverflow* (error)

The execution stack has grown too large; procedure invocation is nested
deeper than the PostScript interpreter permits.

SEE ALSO: exec
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*execuserobject* index execuserobject - LEVEL 2

executes the object associated with the non-negative integer index in the
UserObjects array. execuserobject is equivalent to:

userdict /UserObjects get
exch get exec

execuserobject's semantics are similar to those of exec or other explicit
execution operators. That is, if the object is executable, it is executed;
otherwise, it is pushed on the operand stack.

If UserObjects is not defined in userdict because defineuserobject has
never been executed, an undefined error occurs. If index is not a valid
index for the existing UserObjects array, a rangecheck error occurs. If
index is a valid index but defineuserobject has not been executed
previously for that index, a null object is returned.

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck , undefined

SEE ALSO: defineuserobject, undefineuserobject, UserObjects
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*executeonly* array executeonly array
packedarray executeonly packedarray
file executeonly file
string executeonly string

reduces the access attribute of an array, packed array, file, or string
object to execute-only .Access can only be reduced by these means, never
increased. When an object is execute-only, its value cannot be read or
modified explicitly by PostScript operators (an invalidaccess error will
result), but it can still be executed by the PostScript interpreter-for
example, by invoking it with exec.
executeonly affects the access attribute only of the object that it
returns. If there are other composite objects that share the same value,
their access attributes are unaffected.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: rcheck, wcheck, xcheck, readonly, noaccess
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*executive* - executive -

invokes the interactive executive, which facilitates direct user
interaction with the PostScript interpreter.

executive uses the special %statementedit file to obtain commands from the
user . The echo operator and the value of prompt also affect the behavior
of executive.

executive is not necessarily defined in all products.
It should not be considered a standard part of the PostScript language.

ERRORS: undefined

SEE ALSO: prompt, echo, file
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*exit* - exit -

terminates execution of the innermost, dynamically enclosing instance of a
looping context without regard to lexical relationship. A looping context
is a procedure invoked repeatedly by one of the following control
operators:

cshow forall pathforall
filenameforall kshow repeat
for loop resourceforall

exit pops the execution stack down to the level of that operator. The
interpreter then resumes execution at the next object in normal sequence
after that operator.

exit does not affect the operand or dictionary stacks. Any objects pushed
on those stacks during execution of the looping context remain after the
context is exited.

If exit would escape from the context of a run or stopped operator, it
executes the invalidexit error (still in the context of the run or
stopped). If there is no enclosing looping context, the interpreter prints
an error message and executes the built-in operator quit. This never occurs
during execution of ordinary user programs, because they are enclosed by a
stopped context.

ERRORS: invalidexit

SEE ALSO: stop, stopped
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*exitserver* - exitserver -

---------------------------------------------------------------------------
---------------------------------------------------------------------------

*exp* base exponent exp real

raises base to the exponent power. The operands may be either integers or
reals. If the exponent has a fractional part, the result is meaningful only
if the base is non-negative. The result is always a real.

EXAMPLE:
9 0.5 exp -> 3.0
-9 -1 exp -> -0.111111

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: sqrt, ln, log, mul
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*false* - false false
pushes a boolean object whose value is false on the operand stack.
false is not an operator; it is a name in systemdict associated with the
boolean value false.

ERRORS: stackoverflow

SEE ALSO: true, and, or, not, xor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*file* filename access file file

creates a file object for the file identified by filename, accessing it as
specified by access. Both operands are strings. Conventions for both file
names and access specifications depend on the operating system environment
in which the PostScript interpreter is running.

Once created and opened, the file object remains valid until the file is
closed either explicitly (by executing closefile) or implicitly (by
encountering end-offile while reading or executing the file). A file is
also closed by restore if the file object was created more recently than
the save snapshot being restored, or is closed by garbage collection if the
file object is no longer accessible. There is a limit on the number of
files that can be open simultaneously.

If the specified filename is malformed or if the file doesn't exist and
access does not permit creating a new file, file executes an
undefinedfilename error. If access is malformed or the requested access is
not permitted by the device, an invalidfileaccess error occurs. If the
number of files opened by the current context exceeds an implementation
limit, a limitcheck error occurs. If an environmentdependent error is
detected, an ioerror occurs.

EXAMPLE:
(%stdin) (r) file -> % standard input file object
(myfile) (w) file -> % output file object, writing to named file

ERRORS: invalidfileaccess, ioerror, limitcheck, stackunderflow, typecheck,
undefinedfilename

SEE ALSO: closefile, currentfile, filter, status
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*filenameforall* template proc scratch filenameforall - LEVEL 2

enumerates all files whose names match the specified template string. For
each matching file, filenameforall copies the file's name into the supplied
scratch string, pushes a string object designating the substring of scratch
actually used, and calls proc. filenameforall does not return any results
of its own, but proc may do so.

The details of template matching are device dependent, but the following
convention is typical. All characters in the template are treated literally
and are case sensitive, except the following special characters:

* matches zero or more consecutive characters.

? matches exactly one character.

causes the next character of the template to be treated literally, even if
it is *, ?, or /.

If template does not begin with %, it is matched against device relative
file names of all devices in the search order. When a match occurs, the
file name passed to proc
is likewise device relative-in other words, it does not have a %device%
prefix.

If template does begin with %, it is matched against complete file names in
the form %device%file. Template matching can be performed on the device,
the file, or both parts of the name. When a match occurs, the file name
passed to proc is likewise in the complete form %device%file.

The order of enumeration is unspecified and device dependent. There are no
restrictions on what proc can do. However, if proc causes new files to be
created, it is unspecified whether or not those files will be encountered
later in the same enumeration. Likewise, the set of file names considered
for template matching is device dependent.

ERRORS: invalidaccess, ioerror, rangecheck, stackoverflow, stackunderflow,
typecheck

SEE ALSO: file, status
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*fileposition* file fileposition position LEVEL 2

returns the current position in an existing open file. The result is a
non-negative integer interpreted as number of bytes from the beginning of
the file. If the file object is not valid or the underlying file is not
positionable, an ioerror occurs.

ERRORS: ioerror, stackunderflow, typecheck

SEE ALSO: setfileposition, file
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*fill* - fill
- paints the area enclosed by the current path with the current color.
Any previous contents of that area on the current page are obscured, so
areas may be erased by filling with color set to white.

Before painting, fill implicitly closes any open subpaths of the current
path. The inside of the current path is determined by the normal non-zero
winding number rule .

fill implicitly performs a newpath after it has finished filling the
current path. To preserve the current path across a fill operation, use the
sequence:

gsave fill grestore

ERRORS: limitcheck

SEE ALSO: clip, eofill, stroke, ufill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*filter* source/target param1 ... paramn name filter file LEVEL 2

creates and returns a filtered file.

The source/target operand specifies the underlying data source or data
target that the filter is to read or write. It can be a file, procedure, or
string.

The param1 ... paramn operands are additional parameters that control how
the filter is to operate. The number and types of these operands depend on
the filter name. Most filters require no additional parameters.

The name operand identifies the data transformation that the filter is to
perform. The standard filter names are:

     ASCIIHexEncode ASCIIHexDecode
     ASCII85Encode ASCII85Decode
     LZWEncode LZWDecode
     RunLengthEncode RunLengthDecode
     CCITTFaxEncode CCITTFaxDecode
     DCTEncode DCTDecode
     NullEncode SubFileDecode

An encoding filter is an output (writable) file. A decoding filter is an
input (readable) file. The file object returned by the filter can be used
as an operand of normal file input and output operators, such as read and
write. Reading from an input filtered file causes the filter to read from
the underlying data source and transform the data. Similarly, writing to an
output filtered file causes the filter to transform the data and write it
to the underlying data target.

ERRORS: limitcheck, undefined, typecheck, rangecheck, stackunderflow,
invalidaccess

SEE ALSO: file, closefile, resourceforall
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*findencoding* key findencoding array LEVEL 2

obtains an encoding vector identified by the specified key and pushes it
onto the operand stack.

findencoding is a special case of findresource applied to the Encoding
category . If the encoding array specified by key does not exist or cannot
be found, findencoding executes the undefinedresource error.

ERRORS: stackunderflow, typecheck, undefinedresource

SEE ALSO: findresource, StandardEncoding, ISOLatin1Encoding
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*findfont* key findfont font

obtains a font dictionary identified by the specified key and pushes it on
the operand stack . key may be a key previously passed to definefont, in
which case the font dictionary associated with key (in the font directory)
is returned.

If key is not registered as a font in VM, findfont takes an action that
varies according to the environment in which the PostScript interpreter is
operating. In some environments, findfont may attempt to read a font
definition from an external source, such as a file. In other environments,
findfont substitutes a default font or executes the error invalidfont.
findfont is a special case of findresource applied to the Font category.

findfont, like findresource, normally looks first for fonts defined in
local VM, then for fonts defined in global VM. However, if the current VM
allocation mode is global, findfont considers only fonts defined in global
VM. If findfont needs to load a font into VM, it may use either local or
global VM, depending on the font. Generally, Type 1 fonts are loaded into
global VM; fonts of other types are loaded in to local VM.

findfont is not an operator, but rather a built-in procedure. It may be
redefined by a PostScript language program that requires different
strategies for finding fonts.

ERRORS: invalidfont, stackunderflow, typecheck

SEE ALSO: scalefont, makefont, setfont, selectfont, definefont,
findresource, FontDirectory, GlobalFontDirectory
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*findresource* key category findresource instance LEVEL 2

attempts to obtain a named resource instance in a specified category.
category is a name object that identifies a resource category, such as Font
.. key is a name or string object that identifies the resource instance.
(Names and strings are interchangeable; other types of keys are permitted
but are not recommended.) If it succeeds, findresource pushes the resource
instance on the operand stack; this is an object whose type depends on the
resource category.

findresource first attempts to obtain a resource instance that has
previously been defined in VM by defineresource. If the current VM
allocation mode is local, findresource considers local resource definitions
first, then global definitions (see defineresource). However, if the
current VM allocation mode is global, findresource considers only global
resource definitions.

If the requested resource instance is not currently defined in VM,
findresource attempts to obtain it from an external source. The way this is
done is not specified by the PostScript language; it varies among different
implementations and different resource categories. The effect of this
action is to create an object in VM and execute defineresource.
findresource then returns the newly created object. If key is not a name or
string, findresource will not attempt to obtain an external resource.

When findresource loads an object into VM, it ordinarily attempts to use
global VM, regardless of the current VM allocation mode. In other words, it
sets the VM allocation mode to global (true setglobal) while loading the
resource instance and executing defineresource. However, certain resource
instances do not function correctly when loaded into global VM;
findresource uses local VM instead. This always occurs for type 3 font
definitions and for any resource instance whose definition includes an
explicit false setglobal.

During its execution, findresource may remove the definitions of resource
instances that were previously loaded into VM by findresource. The
mechanisms and policies for this depend on the category and the
implementation; reclamation of resources may occur at times other than
during execution of findresource. However, resource definitions that were
made by explicit execution of defineresource are never disturbed by
automatic reclamation.

If the specified resource category does not exist, an undefined error
occurs. If the category exists but there is no instance whose name is key,
an undefinedresource error occurs.

ERRORS: stackunderflow, typecheck, undefined, undefinedresource

SEE ALSO: defineresource, resourcestatus, resourceforall, undefineresource
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*flattenpath* - flattenpath
- replaces the current path with an equivalent path that preserves all
straight line segments, but has all curveto segments replaced by sequences
of lineto (straight line) segments that approximate the curves. If the
current path does not contain any curveto segments, flattenpath leaves it
unchanged.

This "flattening" of curves to straight line segments is done automatically
when a path is used to control painting (for example, by stroke, fill, or
clip). Only rarely does a program need to flatten a path explicitly (see
pathbbox). The accuracy of the approximation to the curve is controlled by
the current flatness parameter in the graphics state (see setflat).

ERRORS: limitcheck

SEE ALSO: setflat, curveto, lineto, pathbbox
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*floor* num1 floor num2

returns the greatest integer value less than or equal to num1. The type of
the result is the same as the type of the operand.

EXAMPLE:
3.2 floor -> 3.0
-4.8 floor -> -5.0
99 floor -> 99

ERRORS: stackunderflow, typecheck

SEE ALSO: ceiling, round, truncate, cvi
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*flush* - flush

- causes any buffered characters for the standard output file to be
delivered immediately. In general, a program requiring output to be sent
immediately, such as during real-time, two-way interactions, should call
flush after generating that output.

ERRORS: ioerror

SEE ALSO: flushfile, print
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*flushfile* file flushfile

- If file is an output file, flushfile causes any buffered characters for
that file to be delivered immediately. In general, a program requiring
output to be sent immediately, such as during real-time, two-way
interactions, should call flushfile after generating that output.

If file is an input file, flushfile reads and discards data from file until
the end-offile indication is encountered. This is useful during error
recovery, and the PostScript job server uses it for that purpose. flushfile
does not close the file, unless it is a decoding filter file.

ERRORS: ioerror, stackunderflow, typecheck

SEE ALSO: flush, read, write
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*FontDirectory* - FontDirectory dict

pushes a dictionary of defined fonts on the operand stack. FontDirectory is
not an operator; it is a name in systemdict associated with the dictionary
object.

The FontDirectory dictionary associates font names with font dictionaries.
definefont places entries in FontDirectory, and findfont looks there first.
The dictionary is read-only; only definefont and undefinefont can change
it.

Although FontDirectory contains all fonts that are currently defined in VM,
it does not necessarily describe all the fonts available to a PostScript
language program. This is because the findfont operator
can sometimes obtain fonts from an external source and load them into VM
dynamically. Consequently, examining FontDirectory is not a reliable method
of inquiring about available fonts. The preferred method is to use the
resourcestatus and resourceforall operators, which are Level 2 features, to
inquire about the Font resource category.

In Level 2, when global VM allocation mode is in effect, the name
FontDirectory is temporarily
rebound to the value of GlobalFontDirectory, which contains only those
fonts that have been defined in global VM. This ensures the correct
behavior of fonts that are defined in terms of other fonts.

ERRORS: stackoverflow

SEE ALSO: definefont, undefinefont, findfont, findresource,
GlobalFontDirectory
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*for* initial increment limit proc for -

executes proc repeatedly, passing it a sequence of values from initial by
steps of increment to limit. The for operator expects initial, increment,
and limit to be numbers. It maintains a temporary internal variable, known
as the control variable, which it first sets to initial. Then, before each
repetition, it compares the control variable with the termination value
limit. If limit has not been exceeded, it pushes the control variable on
the operand stack, executes proc, and adds increment to the control
variable.

The termination condition depends on whether increment is positive or
negative. If increment is positive, for terminates when the control
variable becomes greater than limit. If increment is negative, for
terminates when the control variable becomes less than limit. If initial
meets the termination condition, for does not execute proc at all. If proc
executes the exit operator, for terminates prematurely.

Usually, proc will use the value on the operand stack for some purpose.
However, if proc does not remove the value, it will remain there.
Successive executions of proc will cause successive values of the control
variable to accumulate on the operand stack.

EXAMPLE:
0 1 1 4 {add} for -> 10
1 2 6 { } for -> 1 3 5
3 -.5 1 {-> } for -> 3.0 2.5 2.0 1.5 1.0

In the first example, the value of the control variable is added to
whatever is on the stack, so 1, 2, 3, and 4 are added in turn to a running
sum whose initial value is 0. The second example has an empty procedure, so
the successive values of the control variable are left on the stack. The
last example counts backward from 3 to 1 by halves, leaving the successive
values on the stack.

Beware of using reals instead of integers for any of the first three
operands. Most real numbers are not represented exactly. This can cause an
error to accumulate in the value of the control variable, with possibly
surprising results. In particular, if the difference between initial and
limit is a multiple of increment, as in the third line of the example, the
control variable may not achieve the limit value.

ERRORS: stackoverflow stackunderflow, typecheck

SEE ALSO: repeat, loop, forall, exit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*forall* array proc forall
packedarray proc forall
dict proc forall
string proc forall -

enumerates the elements of the first operand, executing the procedure proc
for each element. If the first operand is an array, string, or packed
array, forall pushes an element on the operand stack and executes proc for
each element in the array, string, or packed array, beginning with the
element whose index is 0 and continuing sequentially. The objects pushed on
the operand stack are the array, packed array, or string elements. In the
case of a string, these elements are integers in the range 0 to 255, not
one-character strings.

If the first operand is a dictionary, forall pushes a key and a value on
the operand stack and executes proc for each key-value pair in the
dictionary. The order in which forall enumerates the entries in the
dictionary is arbitrary. New entries put in the dictionary during execution
of proc may or may not be included in the enumeration.

If the first operand is empty (i.e., has length 0), forall does not execute
proc at all. If proc executes the exit operator, forall terminates
prematurely.

Although forall does not leave any results on the operand stack when it is
finished, the execution of proc may leave arbitrary results there. If proc
does not remove each enumerated element from the operand stack, the
elements will accumulate there.

EXAMPLE:
0 [13 29 3 -8 21] {add} forall -> 58
/d 2 dict def
d /abc 123 put
d /xyz (test) put
d {} forall -> /xyz (test) /abc 123

ERRORS: invalidaccess, stackoverflow stackunderflow, typecheck

SEE ALSO: for, repeat, loop, exit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*fork* mark obj1 ... objn proc fork context DPS

creates a new execution context using the same local and global VM as the
current context. The new context begins execution concurrent with continued
execution of the current context. Which context executes first is
unpredictable.

The new context's environment is formed by copying the dictionary and
graphics state stacks of the current context. The initial operand stack
consists of obj1 through objn, pushed in the same order (obj1 through objn
are objects of any type other than mark). fork consumes all operands down
to and including the topmost mark. It then pushes an integer that uniquely
identifies the new context. The forked context inherits its object format
from the current context; other percontext parameters are initialized to
default values.

When the new context begins execution, it executes the procedure proc. If
proc runs to completion and returns, the context ordinarily will suspend
until some other context executes a join on context. However, if the
context has been detached, it will terminate immediately (see join and
detach).

If proc executes a stop that causes the execution of proc to end
prematurely, the context will terminate immediately. proc is effectively
called as follows:

proc stopped {handleerror quit} if
% ...Wait for join or detach...
quit

In other words, if proc stops due to an error, the context invokes the
error handler in the usual way to report the error. Then it terminates
regardless of whether it has been detached.

It is illegal to execute fork if there has been any previous save not yet
matched by a restore. Attempting to do so will cause an invalidcontext
error.

ERRORS: invalidaccess, invalidcontext, limitcheck, stackunderflow,
typecheck, unmatchedmark

SEE ALSO: join, detach, currentcontext
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*gcheck* any gcheck bool LEVEL 2

returns true if the operand is simple or if it is composite and its value
resides in global VM. It returns false if the operand is composite and its
value resides in local VM. In other words, gcheck returns true if one could
legally store its operand as an element of another object in global VM.

ERRORS: stackunderflow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ge* num1 num2 ge bool
string1 string2 ge bool

pops two objects from the operand stack and pushes the boolean value true
if the first operand is greater than or equal to the second, false
otherwise. If both operands are numbers, ge compares their mathematical
values. If both operands are strings, ge compares them element by element,
treating the elements as integers in the range 0 to 255, to determine
whether the first string is lexically greater than or equal to the second.
If the operands are of other types or one is a string and the other is a
number, ge executes the typecheck error.

EXAMPLE:
4.2 4 ge -> true
(abc)(d) ge -> false
(aba)(ab) ge -> true
(aba)(aba) ge -> true

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: gt, eq, ne, le, lt
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*get* array index get any
packedarray index get any
dict key get any
string index get int

gets a single element from the value of an array, packed array, dictionary,
or string.

If the first operand is an array, packed array, or string, get treats the
second operand as an index and returns the element identified by the index,
counting from zero. index must be in the range 0 to n-1, where n is the
length of the array, packed array, or string. If it is outside this range,
get will execute a rangecheck error.

If the first operand is a dictionary, get looks up the second operand as a
key in the dictionary and returns the associated value. If the key is not
present in the dictionary, get executes the undefined error.

EXAMPLE:
[31 41 59] 0 get -> 31
[0 (a mixed-type array) [ ] {add 2 div}]
2 get -> [ ] % An empty array

/mykey (myvalue) def
currentdict /mykey get -> (myvalue)

(abc) 1 get -> 98 % Character code for "b"
(a) 0 get -> 97

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck, undefined

SEE ALSO: put, getinterval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*getinterval* array index count getinterval subarray
packedarray index count getinterval subarray
string index count getinterval substring

creates a new array, packed array, or string object whose value consists of
some subsequence of the original array, packed array, or string. The
subsequence consists of count elements starting at the specified index in
the original object. The elements in the subsequence are shared between the
original and new objects.

The returned subarray or substring is an ordinary array, packed array, or
string object whose length is count and whose elements are indexed starting
at 0. The element at index 0 in subarray is the same as the element at
index index in the original array.

getinterval requires index to be a valid index in the original object and
count to be a non-negative integer such that index + count is not greater
than the length of the original object.

EXAMPLE:
[9 8 7 6 5] 1 3 getinterval -> [8 7 6]
(abcde) 1 3 getinterval -> (bcd)
(abcde) 0 0 getinterval -> () % An empty string

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck

SEE ALSO: get, putinterval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*globaldict* - globaldict dict LEVEL 2

pushes the dictionary object globaldict on the operand stack . globaldict
is not an operator; it is a name in systemdict associated with the
dictionary object.

ERRORS: stackoverflow

SEE ALSO: systemdict, userdict
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*GlobalFontDirectory* - GlobalFontDirectory dict LEVEL 2

pushes a dictionary of defined fonts on the operand stack. Its contents are
limited to those fonts that have been defined in global VM.
GlobalFontDirectory is not an operator; it is a name in systemdict
associated with the dictionary object.

ERRORS: stackoverflow

SEE ALSO: FontDirectory
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*glyphshow* name glyphshow - LEVEL 2

shows a single character, identified by name, from the current font. Unlike
all other show variants, glyphshow bypasses the current font's Encoding. It
can access any character in the font, whether or not that character's name
is present in the font's encoding vector.

The behavior of glyphshow depends on the current font's FontType. For
FontType 1, glyphshow looks up name in the font's CharStrings dictionary to
obtain a character description to execute. If name is not present in the
CharStrings dictionary, glyphshow substitutes the .notdef entry, which must
be present in every Type 1 font.

For FontType 3, if the font dictionary contains a BuildGlyph procedure,
glyphshow pushes the current font dictionary and name on the operand stack,
then invokes BuildGlyph in the usual way . If there is no BuildGlyph
procedure, but only a BuildChar procedure, glyphshow searches the font's
Encoding array for an occurrence of name. If it finds one, it pushes the
font dictionary and the array index on the operand stack, then invokes
BuildChar in the usual way. If name is not present in the encoding,
glyphshow substitutes the name .notdef and repeats the search. If .notdef
isn't present either, an invalidfont error occurs.

Like show, glyphshow can access characters that are already in the font
cache. glyphshow does not always need to execute the character's
description.

glyphshow operates only with base fonts. If the current font is composite
(FontType 0), an invalidfont error occurs.

ERRORS: invalidaccess, invalidfont, nocurrentpoint, stackunderflow,
typecheck

SEE ALSO: show
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*grestore* - grestore -

resets the current graphics state from the one on the top of the graphics
state stack and pops the graphics state stack, restoring the graphics state
in effect at the time of the matching gsave. This operator provides a
simple way to undo complicated transformations and other graphics state
modifications without having to re-establish all graphics state parameters
individually.

If there is no matching gsave or if the most recent gsave preceded the most
recent unmatched save, grestore does not pop the graphics state stack,
although it does restore the graphics state from the top of the graphics
state stack.

ERRORS: (none)

SEE ALSO: gsave, grestoreall, setgstate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*grestoreall* - grestoreall -

repeatedly pops the graphics state stack until it encounters either the
bottommost graphics state or one that was saved by save as opposed to
gsave, leaving that state on top of the graphics state stack. It then
resets the current graphics state from that saved one.

ERRORS: (none)

SEE ALSO: gsave, grestore, setgstate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*gsave* - gsave -

pushes a copy of the current graphics state on the graphics state stack.
All elements of the graphics state are saved, including the CTM, current
path, clip path, and identity of the raster output device, but not the
contents of raster memory. The saved state may later be restored by a
matching grestore.

The save operator implicitly performs a gsave, but restoring a graphics
state saved by save is slightly different from restoring one saved by gsave
(see the descriptions of grestore and grestoreall).

Note that, unlike save, gsave does not return a save object on the operand
stack to represent the saved state. gsave and grestore work strictly in a
stack-like fashion, except for the wholesale restoration performed by
restore and grestoreall.

ERRORS: limitcheck

SEE ALSO: grestore, grestoreall, restore, save, gstate, currentgstate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*gstate* - gstate gstate LEVEL 2

creates a new gstate (graphics state) object and pushes it on the operand
stack. Its initial value is a copy of the current graphics state.

This operator consumes VM; it is the only graphics state operator that
does. The gstate is allocated in either local or global VM according to the
current VM allocation mode

If gstate is allocated in global VM, gstate will generate an invalidaccess
error if any of the composite objects in the current graphics state are in
local VM. Such objects might include the current font, screen function,
halftone dictionary, transfer function, or dash pattern. In general,
allocating gstate objects in global VM is risky and should be avoided.

ERRORS: invalidaccess, stackoverflow, VMerror

SEE ALSO: currentgstate, setgstate
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*gt* num1 num2 gt bool
string1 string2 gt bool

pops two objects from the operand stack and pushes the boolean value
true if the first operand is greater than the second, false otherwise. If
both operands are numbers, gt compares their mathematical values. If both
operands are strings, gt compares them element by element, treating the
elements as integers in the range 0 to 255, to determine whether the first
string is lexically greater than the second. If the operands are of other
types or one is a string and the other is a number, gt executes the
typecheck error.

ERRORS: invalidaccess, stackoverflow, typecheck

SEE ALSO: ge, eq, ne, le, lt
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*handleerror* (error)

is looked up in errordict and executed to report error information saved by
the default error handlers . There is also a procedure named handleerror in
systemdict; it merely calls the procedure in errordict.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*identmatrix* matrix identmatrix matrix

replaces the value of matrix with the value of the identity matrix

[1.0 0.0 0.0 1.0 0.0 0.0]

and pushes this modified matrix back on the operand stack. The identity
matrix transforms any coordinate to itself.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: matrix, currentmatrix, defaultmatrix, initmatrix
---------------------------------------------------------------------------
---------------------------------------------------------------------------

idiv int1 int2 idiv quotient
divides int1 by int2 and returns the integer part of the quotient, with any
fractional part discarded. Both operands of idiv must be integers and the
result is an integer.

EXAMPLE:
3 2 idiv -> 1
4 2 idiv -> 2
-5 2 idiv -> -2

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: div, add, mul, sub, mod, cvi
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*idtransform* dx` dy` idtransform dx dy
dx` dy` matrix idtransform dx dy

With no matrix operand, idtransform (inverse delta transform) transforms
the device space distance vector (dx`, dy`) by the inverse of CTM to
produce the corresponding distance vector (dx, dy) in user space.

If the matrix operand is supplied, idtransform transforms the distance
vector by the inverse of matrix rather than by the inverse of CTM.

A delta transformation is similar to a normal transformation, but the
translation components (tx and ty) of the transformation matrix are not
used, making the distance vectors be positionless in both user space and
device space.
idtransform is the inverse of dtransform. It is useful for determining how
distances map from device space to user space.

ERRORS: rangecheck, stackunderflow, typecheck, undefinedresult

SEE ALSO: dtransform, transform, itransform
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*if* bool proc if -

removes both operands from the stack, then executes proc if bool is true.
The if operator pushes no results of its own on the operand stack, but the
proc may do so.

EXAMPLE:

3 4 lt {(3 is less than 4)} if -> (3 is less than 4)

ERRORS: stackunderflow, typecheck

SEE ALSO: ifelse
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ifelse* bool proc1 proc2 ifelse -

removes all three operands from the stack, then executes proc1 if bool is
true or proc2 if bool is false. The ifelse operator pushes no results of
its own on the operand stack, but the procedure it executes may do so.

EXAMPLE:

4 3 lt {(TruePart)} {(FalsePart)} ifelse -> (FalsePart) % Since 4 is not
less than 3

ERRORS: stackunderflow, typecheck

SEE ALSO: if
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*image* width height bits/sample matrix datasrc image
dict image -

paints a sampled image onto the current page. The description here only
summarizes the image operator.

The sampled image is a rectangular array of width x height sample values,
each of which consists of bits/sample bits of data (1, 2, 4, 8, or 12). The
data is received as a sequence of characters-in other words, 8-bit integers
in the range 0 to 255. If bits/sample is less than 8, sample values are
packed left to right within a character

In the first form of image, the parameters are specified as separate
operands. This is the only form Level 1 implementations support. image
renders a monochrome image according to the DeviceGray color space,
regardless of the current color space.

In the second form, the parameters are contained as key-value pairs in an
image dictionary, which is specified as the single operand of image. This
form is a Level 2 feature. image renders either a monochrome or color image
according to the current color space parameter in the graphics state. The
number of component values per source sample and the interpretations of
those values depend on the current color space.

The image is considered to exist in its own coordinate system. The
rectangular boundary of the image has its lower-left corner at (0, 0) and
its upper-right corner at (width, height). The matrix operand specifies a
transformation from user space to the image coordinate system.

In Level 1, datasrc must be a procedure. In Level 2, datasrc may be any
data source ,-a procedure, string, or readable file object (including a
filtered file).

If datasrc is a procedure, image executes datasrc repeatedly to obtain the
actual image data. datasrc must return (on the operand stack) a string
containing any number of additional characters of sample data.

If datasrc returns a string of length zero, image will terminate execution
prematurely. The sample values are assumed to be received in a fixed order:
(0, 0) through (width-1, 0), then (0, 1) through (width-1, 1), and so on.

Execution of this operator is not permitted in certain circumstances.

ERRORS: limitcheck, invalidaccess, ioerror, rangecheck, stackunderflow,
typecheck, undefinedresult, undefined

SEE ALSO: imagemask, colorimage
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*imagemask* width height polarity matrix datasrc imagemask -
dict imagemask -

is similar to the image operator. However, it treats the source image as a
mask of 1-bit samples that are used to control where to apply paint with
the current color and where not to apply any paint.

In the first form of imagemask, the parameters are specified as separate
operands. This is the only form Level 1 implementations support. In the
second form, the parameters are contained as key-value pairs in an image
dictionary. The second form is a Level 2 feature. The semantics of
imagemask do not depend on which way the operands are specified.

imagemask uses the width, height, matrix, and datasrc operands in precisely
the same way image uses them. The polarity operand is a boolean that
determines the polarity of the mask. It controls the sense of the mask
only; it has no effect on the color of the pixels that are painted. If
polarity is false, portions of the image corresponding to source sample
values of 0 are painted, while those corresponding to sample values of 1
are left unchanged. If polarity is true, sample values of 1 are painted and
sample values of 0 are left unchanged.

In the second form of imagemask, the polarity is specified by means of the
Decode entry in the image dictionary. Decode values of [0 1] and [1 0]
correspond to polarity values of false and true, respectively.

In Level 1, datasrc must be a procedure. In Level 2, datasrc may
be any data source ,-a procedure, string, or readable file object
(including a filtered file).

imagemask is most useful for painting characters represented as bitmaps.
Such bitmaps represent masks through which a color is to be transferred;
the bitmaps themselves do not have a color.

EXAMPLE:
54 112 translate % Locate lower-left corner of square
120 120 scale % Scale 1 unit to 120 points
0 0 moveto 0 1 lineto % Fill square with gray background
1 1 lineto 1 0 lineto closepath
..9 setgray fill
0 setgray % Paint mask black
24 23 % Dimensions of source mask
true % Paint the 1 bits
[24 0 0 -23 0 23] % Map unit square to mask

{<003B00 002700 002480 0E4940 114920 14B220 3CB650 75FE88 17FF8C 175F14
1C07E2 3803C4 703182 F8EDFC B2BBC2 BB6F84 31BFC2 18EA3C 0E3E00 07FC00
03F800 1E1800 1FF800>} % Mask data
imagemask

ERRORS: stackunderflow, typecheck, undefinedresult, limitcheck,
invalidaccess, ioerror

SEE ALSO: image, colorimage
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*index* anyn ... any0 n index anyn ... any0 anyn

removes the non-negative integer n from the operand stack, counts down to
the nth element from the top of the stack, and pushes a copy of that
element on the stack.

EXAMPLE:

(a)(b)(c)(d) 0 index -> (a)(b)(c)(d)(d)
(a)(b)(c)(d) 3 index -> (a)(b)(c)(d)(a)

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: copy, dup, roll
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ineofill* x y ineofill bool
userpath ineofill bool LEVEL 2

is similar to infill, but its "insideness" test is based on eofill instead
of fill.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: eofill, infill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*infill* x y infill bool
userpath infill bool LEVEL 2

The first form returns true if the device pixel containing the point (x, y)
in user space would be painted by a fill of the current path in the
graphics state. Otherwise, it returns false.

In the second form, the device pixels that would be painted by filling
userpath become an "aperture." This form of the operator returns true if
any of the pixels in the aperture would be painted by a fill of the current
path in the graphics state. Otherwise, it returns false.

Both forms of this operator ignore the current clipping path and current
view clip; that is, they detect a "hit" anywhere within the current path,
even if filling that path would not mark the current page due to clipping.
They do not place any marks on the current page nor do they disturb the
current path. The following program fragment takes the current clipping
path into account:

gsave clippath x y infill grestore
x y infill and

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: fill, ineofill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*initclip* - initclip -

replaces the current clip path parameter in the graphics state by the
default clip path for the current output device. This path usually
corresponds to the boundary of the maximum imageable area for the current
output device. For a pageoriented output device, its dimensions are those
established by the setpagedevice operator. For a display device, the
clipping region established by initclip is not well defined. Display
PostScript applications should not make the assumption that the clipping
region corresponds to the window boundary (see viewclippath).

There are few situations in which a PostScript language program should
execute initclip explicitly. A page description that executes initclip
usually produces incorrect results if it is embedded within another,
composite page.

ERRORS: (none)

SEE ALSO: clip, eoclip, clippath, initgraphics
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*initgraphics* - initgraphics -

% different in the NeXT implementation

This standard PostScript operator has these additional effects in the NeXT
implementation of the Display PostScript System:

S Sets the coverage parameter in the current window's graphics state to 1
(opaque)

S Turns off instance drawing

resets several values in the current graphics state to their default
values:

current transformation matrix (default for current device)
current path (empty)
current point (undefined)
current clipping path (default for current device)
current color space (DeviceGray)
current color (black)
current line width (one user space unit)
current line cap style (butt end caps)
current line join style (miter joins)
current dash description (undashed, i.e., solid lines)
current miter limit (10)

The initgraphics operator does not change the other graphics state
parameters. These include the current output device, font, stroke adjust,
and all devicedependent parameters. This operator affects only the graphics
state, not the contents of raster memory or the output device.

initgraphics is equivalent to the PostScript language sequence:

initmatrix newpath initclip
1 setlinewidth 0 setlinecap 0 setlinejoin
[ ] 0 setdash 0 setgray 10 setmiterlimit

There are few situations in which a PostScript language program should
execute initgraphics explicitly. A page description that executes
initgraphics usually produces incorrect results if it is embedded within
another, composite page. A program requiring information about its initial
graphics state should read and save that state at the beginning of the
program rather than assume that the default state prevailed initially.

ERRORS: (none)

SEE ALSO: grestoreall, hideinstance, newinstance, setalpha, setinstance
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*initmatrix* - initmatrix -

sets the current transformation matrix (CTM) to the default matrix for the
current output device. This matrix transforms the default user coordinate
system to device space. For a page-oriented device, the default matrix is
initially established
by the setpagedevice operator.

There are few situations in which a PostScript language program should
execute initmatrix explicitly. A page description that executes initmatrix
usually produces incorrect results if it is embedded within another,
composite page.

ERRORS: (none)

SEE ALSO: defaultmatrix, currentmatrix, setmatrix
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*initviewclip* - initviewclip - DPS
returns the context to its initial view clipping state, in which no view
clipping path exists.

ERRORS: (none)

SEE ALSO: viewclip, viewclippath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*instroke* x y instroke bool
userpath instroke bool LEVEL 2

The first form returns true if the device pixel containing the point (x, y)
in user space would be painted by a stroke of the current path in the
graphics state. Otherwise, it returns false. It does not place any marks on
the current page nor does it disturb the current path.

In the second form of the operator, the device pixels that would be painted
by filling userpath become an "aperture." instroke returns true if any of
the pixels in the aperture would be painted by a stroke of the current path
in the graphics state. Otherwise, it returns false.

As with infill, this operator ignores the current clipping path and current
view clip; that is, it detects a "hit" on any pixel that lies beneath a
stroke drawn along the current path, even if stroking that path would not
mark the current page due to clipping.

The shape against which the point (x, y) or the aperture, userpath, is
tested is computed according to the current, stroke-related parameters in
the graphics state: line width, line cap, line join, miter limit, dash
pattern, and stroke adjust. If the current line width is zero, the set of
pixels considered to be part of the stroke is device dependent.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: infill, inustroke, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*internaldict* int internaldict dict

pushes the internal dictionary object on the operand stack. The int operand
must be the integer 1183615869. The internal dictionary is in local VM and
is writable. It contains operators and other information whose purpose is
internal to the PostScript interpreter. It should be referenced only in
special circumstances, such as during construction of Type 1 font programs.

The contents of internaldict are undocumented and subject to change at any
time.

This operator is not present in some PostScript interpreters.

ERRORS: invalidaccess, stackunderflow, undefined
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*interrupt* (error)

processes an external request to interrupt execution of a PostScript
language program. When the interpreter receives an interrupt request, it
executes interrupt as if it were an error-in other words, it looks up the
name interrupt in errordict. Execution of interrupt is sandwiched between
execution of two objects being interpreted in normal sequence.

Unlike most other errors, occurrence of an interrupt does not cause the
object being executed to be pushed on the operand stack nor does it disturb
the operand stack in any way.

The precise nature of an external interrupt request depends on the
environment in which the PostScript interpreter is running. For example, in
some environments, receipt of a control-C character from a serial
communication channel gives rise to the interrupt error. This enables a
user to explicitly abort a PostScript computation. The default definition
of interrupt executes a stop.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*inueofill* x y userpath inueofill bool
userpath1 userpath2 inueofill bool LEVEL 2

is similar to inufill, but its "insideness" test is based on ueofill
instead of ufill.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: inufill, eofill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*inufill* x y userpath inufill bool LEVEL 2
userpath1 userpath2 inufill bool

The first form returns true if the device pixel containing the point (x, y)
in user space would be painted by a ufill of the specified userpath .
Otherwise, it returns false.

In the second form, the device pixels that would be painted by filling
userpath1 become an "aperture." inufill returns true if any of the pixels
in the aperture would be painted by a ufill of userpath2. Otherwise, it
returns false.

This operator does not place any marks on the current page nor does it
disturb the current path in the graphics state. Except for the manner in
which the path is specified, inufill behaves the same as infill.

By itself, this operator is seemingly a trivial composition of several
other operators:

gsave
newpath uappend
infill
grestore

However, when used with a user path that specifies ucache, inufill can
access the user path cache, potentially resulting in improved performance.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: inueofill, infill, ufill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*inustroke* x y userpath inustroke bool LEVEL 2
x y userpath matrix inustroke bool
userpath1 userpath2 inustroke bool
userpath1 userpath2 matrix inustroke bool

The first form returns true if the device pixel containing the point (x, y)
in user space would be painted by a ustroke applied to the same operands.
Otherwise it returns false.

In the second form, inustroke concatenates matrix to the CTM after
interpreting the user paths, but before computing the stroke (see ustroke
operator).

In the third and fourth forms, the device pixels that would be painted by
filling userpath1 become an "aperture." inustroke returns true if any of
the pixels in the aperture would be painted by a ustroke of userpath2.
Otherwise it returns false.

This operator does not place any marks on the current page nor does it
disturb the current path in the graphics state. Except for the manner in
which the path is specified, inustroke behaves the same as instroke.

As with inufill, if userpath is already present in the user path cache,
inustroke can take advantage of the cached information to optimize
execution.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: stroke, ustroke, instroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidaccess* (error)

An access violation has occurred. Principal causes of invalidaccess are:

   * Accessing the value of a composite object in violation of its
     accessattribute
     (for example, storing into a read-only array).

   * Storing a composite object in local VM as an element of a composite
     object in global VM.

   * Executing pathforall if the current path contains an outline for a
     protected font.

SEE ALSO: rcheck, wcheck, gcheck, readonly, executeonly, noaccess
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidcontext* (error) DPS

indicates that an invalid use of the context synchronization facilities has
been detected.
Possible causes include:

   * Presenting an invalid context identifier to join or detach.

   * Executing monitor on a lock already held by the current context.

   * Executing wait on a lock not held by the current context.

   * Executing any of several synchronization operators when an
     unmatched save is pending if the result would be a deadlock.

The PostScript interpreter detects only the simplest types of deadlock.
It is possible to encounter deadlocks for which no invalidcontext error is
generated.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidexit* (error)

An exit has been executed for which there is no dynamically enclosing
looping context (for example, for, loop, repeat, or pathforall) or it has
attempted to leave the context of a run or stopped operator.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidfileaccess* (error)

The access string specification to the file operator is unacceptable or a
file operation has been attempted (for example, deletefile) that is not
permitted by the storage device.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidfont* (error)

Either the operand to findfont is not a valid font name or the operand to
makefont or setfont is not a well-formed font dictionary. The invalidfont
error may also be executed by other font operators upon discovering a font
dictionary is malformed.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidid* (error) DPS

indicates that an invalid identifier has been presented to a window system
specific operator. In each integration of the Display PostScript system
with a window system, there is a collection of window system specific
operators. The operands of such operators are usually integers that
identify windows and other objects that exist outside the PostScript
language. This error occurs when the operand does not identify a valid
object. It is generated only by window system specific operators and not by
any standard operator.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invalidrestore* (error)

An improper restore has been attempted. One or more of the operand,
dictionary, or execution stacks contains composite objects whose values
were created more recently than the save whose context is being restored.
Since restore would destroy those values, but the stacks are unaffected by
restore, the outcome would be undefined and cannot be allowed.

SEE ALSO: restore, save
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*invertmatrix* matrix1 matrix2 invertmatrix matrix2

replaces the value of matrix2 with the result of inverting matrix1 and
pushes the modified matrix2 back on the operand stack. The result of
inverting a matrix is that if matrix1 transforms a coordinate (x, y) to
(x`, y`) then matrix2 transforms (x`, y`) to (x, y).

ERRORS rangecheck, stackunderflow, typecheck , undefinedresult

SEE ALSO: itransform, idtransform
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ioerror* (error)

An exception other than end-of-file has occurred during execution of one of
the file operators. The nature of the exception is environment dependent,
but may include such events as parity or checksum errors, or broken network
connections. Attempting to write to an input file or to a file that has
been closed will also cause an ioerror. Occurrence of an ioerror does not
cause the file to become closed unless it was already closed or the error
occurs during closefile.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ISOLatin1Encoding* - ISOLatin1Encoding array LEVEL 2

pushes the ISO Latin-1 encoding vector on the operand stack. This is a
256-element literal array object, indexed by character codes whose values
are the character names for those codes. ISOLatin1Encoding is not an
operator; it is a name in systemdict associated with the array object.

Roman text fonts produced by Adobe usually use the StandardEncoding
encoding vector. However, they contain all the characters needed to support
the use of ISOLatin1Encoding.

ERRORS: stackoverflow

SEE ALSO: StandardEncoding, findencoding
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*itransform* x` y` itransform x y
x` y` matrix itransform x y

With no matrix operand, itransform (inverse transform) transforms the
device space coordinate (x', y') by the inverse of CTM to produce the
corresponding user space coordinate (x, y). If the matrix operand is
supplied, itransform transforms (x', y') by the inverse of matrix rather
than by the inverse of CTM.

ERRORS: rangecheck, stackunderflow, typecheck , undefinedresult

SEE ALSO: transform, dtransform, idtransform, invertmatrix
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*join* context join mark obj1 ... objn DPS

waits for the execution context identified by the integer context to finish
executing its top-level procedure (the proc operand of fork). It then
pushes a mark followed by the entire contents of that context's operand
stack onto the current context's operand stack. Finally, it causes the
other context to terminate.

The objects obj1 through objn are those left on the operand stack by the
context that is terminating. Ordinarily, there should not be a mark among
those objects, because its presence might cause confusion in the context
that executes the join.

If context is not a valid context identifier, perhaps because the context
has terminated prematurely due to executing quit or encountering an error,
join executes an invalidcontext error. This also occurs if the context has
already been joined or detached, if context identifies the current context,
or if the context does not share the current context's
local and global VM.

It is illegal to execute join if there has been any previous save not yet
matched by a restore. Attempting to do so will cause an invalidcontext
error.

ERRORS: invalidcontext, stackunderflow, stackoverflow, typecheck

SEE ALSO: fork, detach, currentcontext
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*known* dict key known bool

returns the boolean value true if there is an entry in the dictionary dict
whose key is key. Otherwise, it returns false. dict does not have to be on
the dictionary stack.

EXAMPLE:

/mydict 5 dict def
mydict /total 0 put
mydict /total known -> true
mydict /badname known -> false

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: where, load, get
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*kshow* proc string kshow -

paints the characters of string in a manner similar to show, but allowing
program intervention between characters. If the character codes in string
are c0, c1, ... cn, kshow proceeds as follows: First it shows c0 at the
current point, updating the current point by c0's width. Then it pushes the
character codes c0 and c1 on the operand stack (as integers) and executes
proc. The proc may perform any actions it wishes; typically, it will modify
the current point to affect the subsequent placement of c1. kshow continues
by showing c1, pushing c1 and c2 on the stack, executing proc, and so on.
It finishes by pushing cn-1 and cn on the stack, executing proc, and
finally showing cn.

When proc is called for the first time, the graphics state (in particular,
the CTM) is the same as it was at the time kshow was invoked, except that
the current point has been updated by the width of c0. Execution of proc is
permitted to have any side effects, including changes to the graphics
state. Such changes persist from one call of proc to the next and may
affect graphical output for the remainder of kshow's execution and
afterward.

The name kshow is derived from "kern-show." To kern characters is to adjust
the spacing between adjacent pairs of characters in order to achieve a
visually pleasing result. The kshow operator enables user-defined kerning
and other manipulations, because arbitrary computations can be performed
between each pair of characters.

kshow can be applied only to base fonts. If the current font is composite,
kshow issues an invalidfont error.

ERRORS: invalidaccess, invalidfont, nocurrentpoint, stackunderflow,
typecheck

SEE ALSO: show, ashow, awidthshow, widthshow, xshow, xyshow, yshow, cshow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*languagelevel* - languagelevel int LEVEL 2

is an integer designating the PostScript language level supported by the
PostScript interpreter. If the value of languagelevel is 2, the PostScript
interpreter supports all PostScript Level 2 language features.
If the value of languagelevel is 1 or if languagelevel is not defined in
systemdict, the PostScript interpreter does not support all PostScript
Level 2 language features.

ERRORS: stackoverflow, undefined

SEE ALSO: product, revision, serialnumber, version
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*le* num1 num2 le bool
string1 string2 le bool

pops two objects from the operand stack and pushes the boolean value true
if the first operand is less than or equal to the second, false otherwise.
If both operands are numbers, le compares their mathematical values. If
both operands are strings, le compares them element by element (treating
the elements as integers in the range 0 to 255) to determine whether the
first string is lexically less than or equal to the second. If the operands
are of other types or one is a string and the other is a number, le
executes the typecheck error.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: lt, eq, ne, ge, gt
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*length* array length int
packedarray length int
dict length int
string length int
name length int

depends on the type of its operand. If the operand is an array, packed
array, or string, length returns the number of elements in its value. If
the operand is a dictionary, length returns the current number of key-value
pairs it contains, as opposed to its maximum capacity, which is returned by
maxlength. If the operand is a name object, the length is the number of
characters in the text string that defines it.

EXAMPLE:

[1 2 4] length -> 3
[] length -> 0 % An array of zero length
/ar 20 array def ar length -> 20

/mydict 5 dict def
mydict length -> 0
mydict /firstkey (firstvalue) put
mydict length -> 1

(abclength -> 4 % The "is one character
() length -> 0 % No characters between ( and )
/foo length -> 3

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: maxlength
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*limitcheck* (error)

An implementation limit has been exceeded
(for example, too many files have been opened simultaneously or a path has
become too complex).
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*lineto* x y lineto

- appends a straight line segment to the current path . The line extends
from the current point to the point (x, y) in user space; (x, y) then
becomes the current point. If the current point is undefined because the
current path is empty, lineto executes the error nocurrentpoint.

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck

SEE ALSO: rlineto, moveto, arc, curveto, closepath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ln* num ln real

returns the natural logarithm (base e) of num. The result is a real.

EXAMPLE:

10 ln -> 2.30259
100 ln -> 4.60517

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: log, exp
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*load* key load value

searches for key in each dictionary on the dictionary stack, starting with
the topmost (current) dictionary. If key is found in some dictionary, load
pushes the associated value on the operand stack. If key is not found in
any dictionary on the dictionary stack, load executes the error undefined.

load looks up key the same way the interpreter looks up executable names
that it encounters during execution. However, load always pushes the
associated value on the operand stack; it never executes that value.

EXAMPLE:

/avg {add 2 div} def
/avg load -> {add 2 div}

ERRORS: invalidaccess, stackunderflow, typecheck, undefined

SEE ALSO: where, get, store
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*lock* - lock lock DPS

creates a new lock object, unequal to any lock object already in existence,
and pushes it on the operand stack. The state of the lock is initially free
..

Since a lock is a composite object, creating one consumes VM. The lock's
value is allocated in local or global VM according to the current VM
allocation mode .

ERRORS: stackoverflow, VMerror

SEE ALSO: monitor, wait
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*log* num log real

returns the common logarithm (base 10) of num. The result is a real.

EXAMPLE:

10 log -> 1.0
100 log -> 2.0

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: ln, exp
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*loop* proc loop

- repeatedly executes proc until proc executes the exit operator, at which
point interpretation resumes at the object next in sequence after the loop.
Control also leaves proc if the stop operator is executed. If proc never
executes exit or stop, an infinite loop results, which can be broken only
via an external interrupt (see interrupt).

ERRORS: stackunderflow, typecheck

SEE ALSO: for, repeat, forall, exit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*lt* num1 num2 lt bool
string1 string2 lt bool

pops two objects from the operand stack and pushes the boolean value true
if the first operand is less than the second, false otherwise. If both
operands are numbers, lt compares their mathematical values. If both
operands are strings, lt compares them element by element (treating the
elements as integers in the range 0 to 255) to determine whether the first
string is lexically less than the second. If the operands are of other
types or one is a string and the other is a number, lt executes the
typecheck error.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: le, eq, ne, ge, gt
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*makefont* font matrix makefont font'

applies matrix to font, producing a new font' whose characters are
transformed by matrix when they are shown. makefont first creates a copy of
font. Then it replaces the new font's FontMatrix entry with the result of
concatenating the existing FontMatrix with matrix. It inserts two
additional entries, OrigFont and ScaleMatrix, whose purpose is internal to
the implementation. Finally, it returns the result as font'.

The makefont, scalefont, and selectfont operators produce a font dictionary
derived from an original font dictionary, but with the FontMatrix entry
altered. The derived font dictionary is allocated in local or global VM
according to whether the original font dictionary is in local or global VM.
This is independent of the current VM allocation mode.

Normally, makefont copies only the font dictionary. Subsidiary objects,
such as the CharStrings and FontInfo dictionaries, are shared with the
original font. However, if font is a composite font, makefont also copies
the font dictionaries of any descendant composite fonts. It does not copy
descendant base fonts.

Showing characters from the transformed font produces the same results as
showing from the original font after having transformed user space by the
same matrix. makefont is essentially a convenience operator that permits
the desired transformation to be encapsulated in the font description. The
most common transformation is to scale a font by a uniform factor in both x
and y. scalefont is a special case of the more general makefont and should
be used for such uniform scaling. Another operator, selectfont, combines
the effects of findfont and makefont.

The interpreter keeps track of font dictionaries recently created by
makefont. Calling makefont multiple times with the same font and matrix
will usually return the same font' rather than create a new one. However,
it is usually more efficient for a PostScript language program to apply
makefont only once for each font that it needs and to keep track of the
resulting font dictionaries on its own.

EXAMPLE:
/Helvetica findfont [10 0 0 12 0 0] makefont setfont

This obtains the standard Helvetica font, which is defined with a one unit
line height, and scales it by a factor of 10 in the x dimension and 12 in
the y dimension. This produces a 12-unit high font (i.e., a 12-point font
in default user space) whose characters are "condensed" in the x dimension
by a ratio of 10/12.

ERRORS: invalidfont, rangecheck, stackunderflow, typecheck, VMerror

SEE ALSO: scalefont, setfont, findfont, selectfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*makepattern* dict matrix makepattern pattern LEVEL 2

verifies that dict is a prototype pattern dictionary with all required
key-value pairs . It then creates a copy of dict in local VM, adding an
entry, with key Implementation, for use by the implementation. makepattern
copies only the contents of dict itself, not the values of subsidiary
composite objects, which are shared with the original dictionary.

makepattern saves a copy of the current graphics state, to be used later
when the interpreter calls the PaintProc to render the pattern cell. It
then modifies certain parameters in the saved graphics state, as follows:

1. Concatenates matrix with the saved copy of the CTM.
2. Adjusts the resulting matrix to ensure that the device space can be
   tiled properly with a pattern cell of the given size in accordance
   with the TilingType.
3. Resets the path to empty.
4. Replaces the clipping path by the pattern cell bounding box specified
   by the BBox entry in the pattern dictionary.
5. Replaces the device by a special one the implementation provides.

Finally, makepattern makes the new dictionary read-only and pushes it on
the operand stack. The resulting pattern dictionary is suitable for use as
an operand of setpattern or as a "color value" in the Pattern color space.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck, undefined,
VMerror

SEE ALSO: setpattern, findresource
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*mark* - mark mark

pushes a mark (an object whose type is mark, not the mark operator itself)
on the operand stack. All marks are identical, and the operand stack may
contain any number of them at once.

The primary use of marks is to indicate the stack position of the beginning
of an indefinitely long list of operands being passed to an operator or
procedure. The ] operator (array construction) is the most common operator
that works this way. It treats as operands all elements of the stack down
to a mark that was pushed by the [ operator ( [ is a synonym for mark). It
is possible to define procedures that work similarly. Operators such as
counttomark and cleartomark are useful within such procedures.

ERRORS: stackoverflow

SEE ALSO: counttomark, cleartomark, pop
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*matrix* - matrix matrix

creates a 6-element array object, fills it in with the values of an
identity matrix
[1.0 0.0 0.0 1.0 0.0 0.0] and pushes this array on the operand stack. The
array is allocated in local or global VM according to the current VM
allocation mode.

EXAMPLE:

matrix -> [1.0 0.0 0.0 1.0 0.0 0.0]
6 array identmatrix -> [1.0 0.0 0.0 1.0 0.0 0.0]

The two lines in the example yield identical results.

ERRORS: stackoverflow, VMerror

SEE ALSO: currentmatrix, defaultmatrix, initmatrix, setmatrix, array
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*maxlength* dict maxlength int

returns the capacity of dict-in other words, the maximum number of
key-value pairs that dict can hold using the VM currently allocated to it.
In Level 1 implementations, maxlength returns the length operand of the
dict operator that created the dictionary; this is the dictionary's maximum
capacity (exceeding it causes a dictfull error). In a Level 2
implementation, which permits a dictionary to grow beyond its initial
capacity, maxlength returns its current capacity, a number at least as
large as that returned by length.

EXAMPLE:

/mydict 5 dict def
mydict length -> 0
mydict maxlength -> 5

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: length, dict
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*mod* int1 int2 mod remainder

returns the remainder that results from dividing int1 by int2. The sign of
the result is the same as the sign of the dividend int1. Both operands must
be integers. The result is an integer.

EXAMPLE:

5 3 mod -> 2
5 2 mod -> 1
-5 3 mod -> -2

The last line of the example demonstrates that mod is a remainder operation
rather than a true modulo operation.

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: idiv, div
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*monitor* lock proc monitor - DPS

acquires lock, first waiting if necessary for it to become free, then
executes proc, and finally releases lock again. The release of lock occurs
whether proc runs to completion or terminates prematurely for any reason.
If lock is already held by the current context, monitor executes an
invalidcontext error without disturbing the lock. If the current context
has previously executed a save not yet matched by a restore and lock is
already held by another context sharing the same local VM as the current
context, an invalidcontext error results. These restrictions prevent the
most straightforward cases of a context deadlocking with itself.

ERRORS: invalidcontext, stackunderflow, typecheck

SEE ALSO: lock, fork, wait
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*moveto* x y moveto -

starts a new subpath of the current path. moveto sets the current point in
the graphics state to the user space coordinate (x, y) without adding any
line segments to the current path.
If the previous path operation in the current path was also a moveto or
rmoveto, that point is deleted from the current path and the new moveto
point replaces it.

ERRORS: limitcheck, stackunderflow, typecheck

SEE ALSO: rmoveto, lineto, curveto, arc, closepath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*mul* num1 num2 mul product

returns the product of num1 and num2. If both operands are integers and the
result is within integer range, the result is an integer. Otherwise, the
result is a real.

ERRORS: stackunderflow, typecheck, undefinedresult

SEE ALSO: div, idiv, add, sub, mod
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ne* any1 any2 ne bool

pops two objects from the operand stack and pushes the boolean value false
if they are equal, true if not. What it means for objects to be equal is
presented in the description of the eq operator.

ERRORS: invalidaccess, stackunderflow

SEE ALSO: eq, ge, gt, le, lt
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*neg* num1 neg num2

returns the negative of num1. The type of the result is the same as the
type of num1, unless num1 is the most negative integer, in which case the
result is a real.

EXAMPLE:

4.5 neg -> -4.5
-3 neg -> 3

ERRORS: stackunderflow, typecheck

SEE ALSO: abs
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*newpath* - newpath

- initializes the current path to be empty, causing the current point to
become undefined.

ERRORS: (none)

SEE ALSO: closepath, stroke, fill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*noaccess* array noaccess array

packedarray noaccess packedarray
dict noaccess dict
file noaccess file
string noaccess string

reduces the access attribute of an array, packed array, dictionary, file,
or string object to none. The value of a noaccess object cannot be executed
or accessed directly by PostScript operators. Noaccess objects are of no
use to PostScript language programs, but serve certain internal purposes
that are not documented in this manual.

For an array, packed array, file, or string, noaccess affects the access
attribute only of the object that it returns. If there are other objects
that share the same value, their access attributes are unaffected. However,
in the case of a dictionary, noaccess affects the value of the object, so
all dictionary objects sharing the same dictionary are affected.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: rcheck, wcheck, xcheck, readonly, executeonly
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*nocurrentpoint* (error)

The current path is empty, and thus there is no current point, but an
operator requiring a current point has been executed (for example, lineto,
curveto, currentpoint, show). The most common cause of this error is
neglecting to perform an initial moveto.

SEE ALSO: moveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*not* bool1 not bool2
int1 not int2

If the operand is a boolean, not returns its logical negation. If the
operand is an integer, not returns the bitwise complement (one's
complement) of its binary representation.

EXAMPLE:
true not -> false % A complete truth table
false not -> true

52 not -> -53

ERRORS: stackunderflow, typecheck

SEE ALSO: and, or, xor, if
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*notify* condition notify - DPS

resumes execution of all contexts, if any, that are suspended in a wait for
condition.
Ordinarily, notify should be invoked only within the execution of a monitor
that references the same lock used in the wait for condition. This ensures
that notifications cannot be lost due to a race between a context executing
notify and one executing wait. However, this recommendation is not enforced
by the language.

ERRORS: stackunderflow, typecheck

SEE ALSO: wait, monitor, condition
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*null* - null null

pushes a literal null object on the operand stack. null is not an operator;
it is a name in systemdict associated with the null object.

ERRORS: stackoverflow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*nulldevice* - nulldevice -

installs the "null device" as the current output device. The null device
corresponds to no physical output device and has no raster memory
associated with it. Marks placed on the current page by painting operators
(for example, show or stroke) are discarded; output operators (showpage and
copypage) do nothing. However, in all other respects the null device
behaves like a real raster output device: the graphics operators have their
normal side-effects on the graphics state, the character operators invoke
the font machinery, and so on.

nulldevice sets the default transformation matrix to be the identity
transform
[1.0 0.0 0.0 1.0 0.0 0.0]. A PostScript language program may change this to
any other matrix (using setmatrix) if it desires to simulate the device
coordinate system of some real device. nulldevice also establishes the
clipping path as a degenerate path consisting of a single point at the
origin.

The null device is useful for exercising the PostScript interpreter's
graphics and font machinery for such purposes as operating on paths,
computing bounding boxes for graphical shapes, and performing coordinate
transformations using CTM without generating output. Such manipulations
should be bracketed by gsave and grestore so the former device can be
reinstated and the other side effects of nulldevice undone.

ERRORS: (none)

SEE ALSO: setpagedevice
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*or* bool 1 bool 2

or bool 3 int1 int2
or int3

If the operands are booleans, or returns their logical disjunction. If the
operands are integers, or returns the bitwise "inclusive or" of their
binary representations.

EXAMPLE:

true false or -> true
true false or -> true
false true or -> true
false false or -> false

17 5 or -> 21

ERRORS: stackunderflow, typecheck

SEE ALSO: and, not, xor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*packedarray* any0 ... anyn-1 n packedarray packedarray LEVEL 2

creates a packed array object of length n containing the objects any0
through anyn-1 as elements. packedarray first removes the non-negative
integer n from the operand stack. It then removes that number of objects
from the operand stack, creates a packed array containing those objects as
elements, and finally pushes the resulting packed array object on the
operand stack.

The resulting object has a type of packedarraytype, a literal attribute,
and readonly access. In all other respects, its behavior is identical to
that of an ordinary array object.
v The packed array is allocated in local or global VM according to the
current VM allocation mode. An invalidaccess error occurs if the packed
array is in global VM and any of any0 ... anyn-1 are in local VM.

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck, VMerror

SEE ALSO: aload
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*pathbbox* - pathbbox llx lly urx ury

returns the bounding box of the current path in the current user coordinate
system. The results are four real numbers: lower-left x, lower-left y,
upper-right x, and upper-right y. These coordinates describe a rectangle,
oriented with its sides parallel to the x and y axes in user space, that
completely encloses all elements of the path. If the current path is empty,
pathbbox executes the error nocurrentpoint.

pathbbox first computes the bounding box of the current path in device
space. It then transforms these coordinates to user space by the inverse of
CTM and computes the bounding box of the resulting figure in user space. If
the user coordinate system is rotated (other than by multiples of 90
degrees) or skewed, pathbbox may return a bounding box that is larger than
expected.

If the path includes curve segments, the bounding box encloses the control
points of the curves as well as the curves themselves. To obtain a bounding
box that fits the path more tightly, one should first "flatten" the curve
segments by executing flattenpath.

In Level 2 implementations of the PostScript language, if the current path
ends with a moveto, the bounding box does not necessarily include it,
unless the moveto is the only element of the path. If an explicit bounding
box has been established by setbbox, pathbbox returns a result derived from
that bounding box, not from the actual path.

ERRORS: nocurrentpoint, stackoverflow

SEE ALSO: flattenpath, clippath, charpath, setbbox
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*pathforall* move line curve close pathforall

- removes four operands from the stack, all of which must be procedures.
pathforall then enumerates the current path in order, executing one of the
four procedures for each element in the path. The four basic kinds of
elements in a path are moveto, lineto, curveto, and closepath. The relative
variants rmoveto, rlineto, and rcurveto are converted to the corresponding
absolute forms; arc, arcn, and arcto are converted to sequences of curveto.
For each element in the path, pathforall pushes the element's coordinates
on the operand stack and executes one of the four procedures as follows:

moveto push x y; execute move
lineto push x y; execute line
curveto push x1 y1 x2 y2 x3 y3; execute curve
closepath execute close

The operands passed to the procedures are coordinates in user space.
pathforall transforms them from device space to user space using the
inverse of the CTM. Ordinarily, these coordinates will be the same as the
ones originally entered by moveto, lineto, and so forth. However, if the
CTM has been changed since the path was constructed, the coordinates
reported by pathforall will be different from those originally entered.

Among other uses, pathforall enables a path constructed in one user
coordinate system to be read out in another user coordinate system.

pathforall enumerates the current path existing at the time it begins
execution. If any of the procedures change the current path, such changes
do not alter the behavior of pathforall.

If charpath was used to construct any portion of the current path from a
font whose outlines are protected, pathforall is not allowed. Its execution
will produce an invalidaccess error (see charpath).

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck

SEE ALSO: moveto, lineto, curveto, closepath, charpath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*pop* any pop

- removes the top element from the operand stack and discards it.

EXAMPLE:

1 2 3 pop -> 1 2
1 2 3 pop pop -> 1

ERRORS: stackunderflow

SEE ALSO: clear, dup
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*print* string print

- writes the characters of string to the standard output file. The print
operator provides the simplest means to send text to an application or an
interactive user. Note that print is a file operator that has nothing to do
with painting character shapes on the current page (see show) or with
sending the current page to a raster output device (see showpage).

ERRORS: invalidaccess, ioerror, stackunderflow, typecheck

SEE ALSO: write, flush, =, ==, printobject
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*printobject* obj tag printobject - LEVEL 2

writes a binary object sequence to the standard output file. The binary
object sequence contains a top-level array whose length is one; its single
element is an encoding of obj. If obj is composite, the binary object
sequence also includes subsidiary array and string values for the
components of obj.
The tag operand, which must be an integer in the range 0 to 255, is used to
tag the top-level object; it appears as the second byte of the object's
representation.
Tag values 0 through 249 are available for general use;
tag values 250 through 255 are reserved for special purposes, such as
reporting errors.

The binary object sequence uses the number representation established by
the most recent execution of setobjectformat. The token type given as the
first byte of the binary object sequence reflects the number representation
that was used. If the object format parameter has been set to zero,
printobject executes an undefined error.

The object obj and its components must be of type null, integer, real,
name, boolean, string, array, or mark. Appearance of an object of any other
type, including packed array, will result in a typecheck error. If arrays
are nested too deeply or are cyclical, a limitcheck error occurs.

printobject always encodes a name object as a reference to a text name in
the string value portion of the binary object sequence, never as a system
or user name index.

As is the case for all operators that write to files, the output produced
by printobject may accumulate in a buffer instead of being transmitted
immediately. To ensure immediate transmission, a flush is required. This is
particularly important in situations where the output produced by
printobject is the response to a query from the application.

ERRORS: invalidaccess, ioerror, limitcheck, rangecheck, stackunderflow,
typecheck, undefined

SEE ALSO: print, setobjectformat, writeobject
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*product* - product string LEVEL 2

is a read-only string object that is the name of the product in which the
PostScript interpreter is running. The value of this string is typically a
manufacturer defined trademark; it has no direct connection with specific
features of the PostScript language.

ERRORS: stackoverflow

SEE ALSO: languagelevel, revision, serialnumber, version
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*prompt* - prompt

- is a procedure executed by executive whenever it is ready for the user to
enter a new statement. The standard definition of prompt is "(PS>) print
flush" and is defined in systemdict; it can be overridden by defining
prompt in userdict or some other dictionary higher on the dictionary stack.
prompt is not defined in products that do not support executive.

ERRORS: (none)

SEE ALSO: executive
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*pstack* any1 ... anyn pstack any1 ... anyn

writes text representations of every object on the stack to the standard
output file, but leaves the stack unchanged. pstack applies the == operator
to each element of the stack, starting with the topmost element. See the ==
operator for a description of its effects.

ERRORS: (none)

SEE ALSO: stack, =, ==
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*put* array index any put -
dict key any put -
string index int put -

replaces a single element of the value of an array, dictionary, or string.

If the first operand is an array or string, put treats the second operand
as an index and stores the third operand at the position identified by the
index, counting from zero. index must be in the range 0 to n-1,where n is
the length of the array or string. If it is outside this range, put will
execute a rangecheck error.

If the first operand is a dictionary, put uses the second operand as a key
and the third operand as a value, and it stores this key-value pair into
dict. If key is already present as a key in dict, put simply replaces its
value by any. Otherwise, put creates a new entry for key and associates any
with it. In Level 1 implementations, if dict is already full, put executes
the error dictfull.

If the value of array or dict is in global VM and any is a composite object
whose value is in local VM, an invalidaccess error occurs.

EXAMPLE:

/ar [5 17 3 8] def
ar 2 (abcd) put
ar -> [5 17 (abcd) 8]

/d 5 dict def
d /abc 123 put
d {} forall -> /abc 123

/st (abc) def
st 0 65 put % 65 is ASCII code for character "A"
st -> (Abc)

ERRORS: dictfull, invalidaccess, rangecheck, stackunderflow, typecheck

SEE ALSO: get, putinterval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*putinterval* array1 index array2 putinterval -
array1 index packedarray2 putinterval -
string1 index string2 putinterval -

replaces a subsequence of the elements of the first operand by the entire
contents of the third operand. The subsequence that is replaced begins at
the specified index in the first operand; its length is the same as the
length of the third operand.

The objects are copied from the third operand to the first, as if by a
sequence of individual gets and puts. In the case of arrays, if the copied
elements are themselves composite objects, the values of those objects are
shared between array2 and array1.

putinterval requires index to be a valid index in array1 or string1 such
that index plus the length of array2 or string2 is not greater than the
length of array1 or string1.

If the value of array1 is in global VM and any of the elements copied from
array2 or packedarray2 are composite objects whose values are in local VM,
an invalidaccess error occurs.

EXAMPLE:

/ar [5 8 2 7 3] def
ar 1 [(a) (b) (c)] putinterval
ar -> [5 (a) (b) (c) 3]

/st (abc) def
st 1 (de) putinterval
st -> (ade)

ERRORS: invalidaccess, rangecheck, stackunderflow, typecheck

SEE ALSO: getinterval, put
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*quit* - quit

- terminates operation of the interpreter. The precise action of quit
depends on the environment in which the PostScript interpreter is running.
It may give control to an operating system command interpreter, halt or
restart the machine, and so on.

In an interpreter that supports multiple execution contexts , the quit
operator causes termination of the current context only. Termination is
immediate, even if the context was created by fork in the expectation of a
subsequent join.

In a context that is under the control of a job server , the definition of
the quit operator in systemdict is masked by another definition of quit in
userdict, which usually is searched before systemdict. The default
definition of quit in userdict is the same as stop, which terminates the
current job, but not the interpreter as a whole. The quit operator in
systemdict can be executed only by an unencapsulated job; in an
encapsulated job, it causes an invalidaccess error.

ERRORS: invalidaccess

SEE ALSO: stop, start
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rand* - rand int

returns a random integer in the range 0 to 231 - 1, produced by a
pseudo-random number generator. The random number generator's state can be
reset by srand and interrogated by rrand.

ERRORS: stackoverflow

SEE ALSO: srand, rrand
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rangecheck* (error)

A numeric operand's value is outside the range expected by an operator-for
example, an array or string index is out of bounds, or a negative number
appears where a non-negative number is required. rangecheck can also occur
if a matrix operand does not contain exactly six elements.
---------------------------------------------------------------------------

rcheck array rcheck bool
packedarray rcheck bool
dict rcheck bool
file rcheck bool
string rcheck bool

tests whether the operand's access permits its value to be read explicitly
by PostScript operators.
rcheck returns true if the operand's access is unlimited or readonly, false
otherwise.

ERRORS: stackunderflow, typecheck

SEE ALSO: executeonly, noaccess, readonly, wcheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rcurveto* dx1 dy1 dx2 dy2 dx3 dy3 rcurveto

- (relative curveto) adds a Bezier cubic section to the current path in the
same manner as curveto. However, the three number pairs are interpreted as
displacements relative to the current point (x0, y0) rather than as
absolute coordinates. That is, rcurveto constructs a curve from (x0, y0) to
(x0+dx3, y0+dy3), using (x0+dx1, y0+dy1) and (x0+dx2, y0+dy2) as Bezier
control points. See the description of curveto for complete information.

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck ,
undefinedresult

SEE ALSO: curveto, rlineto, rmoveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*read* file read int true (if not end-of-file)
false (if end-of-file)

reads the next character from the input file file, pushes it on the stack
as an integer, and pushes true as an indication of success.
If an end-of-file indication is encountered before a character has been
read, read closes the file and returns false.
If some other error indication is encountered (for example, parity or
checksum error), read executes ioerror.

ERRORS: invalidaccess, ioerror, stackoverflow, stackunderflow, typecheck

SEE ALSO: readhexstring, readline, readstring, bytesavailable
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*readhexstring* file string readhexstring substring bool

reads characters from file, expecting to encounter a sequence of
hexadecimal digits 0 through 9 and A through F (or a through f).
readhexstring interprets each successive pair of digits as a two-digit
hexadecimal number representing an integer value in the range 0 to 255. It
then stores these values into successive elements of string starting at
index 0 until either the entire string has been filled or an end-of-file
indication is encountered in file. Finally, readhexstring returns the
substring of string that was filled and a boolean indicating the outcome
(true normally, false if end-of-file was encountered before the string was
filled).

readhexstring ignores any characters that are not valid hexadecimal digits,
so the data in file may be interspersed with spaces, newlines, etc.,
without changing the interpretation of the data.

ERRORS: invalidaccess, ioerror, rangecheck, stackunderflow, typecheck

SEE ALSO: read, readline, readstring, filter
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*readline* file string readline substring bool

reads a line of characters (terminated by a newline character) from file
and stores them into successive elements of string. readline then returns
the substring of string that was filled and a boolean indicating the
outcome (true normally, false if end-of-file was encountered before a
newline character was read).

A "line of characters" is a sequential string of ASCII characters,
including space, tab, and non-printing "control" characters. A line
terminates with a newline-a carriage return character, a line-feed
character, or both.

The terminating newline character is not stored into string or included at
the end of the returned substring. If readline completely fills string
before encountering a newline character, it executes the error rangecheck.

ERRORS: invalidaccess, ioerror, rangecheck, stackunderflow, typecheck

SEE ALSO: read, readhexstring, readonly
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*readonly* array readonly array
packedarray readonly packedarray
dict readonly dict
file readonly file
string readonly string

reduces the access attribute of an array, packed array, dictionary, file,
or string object to read-only. Access can only be reduced this way, never
increased. When an object is read-only, its value cannot be modified by
PostScript operators (an invalidaccess error will result), but it can still
be read by operators or executed by the PostScript interpreter.

For an array, packed array, file, or string, readonly affects the access
attribute only of the object that it returns. If there are other objects
that share the same value, their access attributes are unaffected. However,
in the case of a dictionary, readonly affects the value of the object, so
all dictionary objects sharing the same dictionary are affected.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: executeonly, noaccess, rcheck, wcheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*readstring* file string readstring substring bool

reads characters from file and stores them into successive elements of
string until either the entire string has been filled or an end-of-file
indication is encountered in file. readstring then returns the substring of
string that was filled and a boolean indicating the outcome (true normally,
false if end-of-file was encountered before the string was filled).

All character codes are treated the same-as integers in the range 0 to 255.
There are no special characters (in particular, the newline character is
not treated specially). However, the communication channel may usurp
certain control characters.

ERRORS: invalidaccess, ioerror, rangecheck, stackunderflow, typecheck

SEE ALSO: read, readhexstring, readline
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*realtime* - realtime int LEVEL 2

returns the value of a clock that counts in real time, independent of the
execution of the PostScript interpreter. The clock's starting value is
arbitrary; it has no defined meaning in terms of calendar time. The unit of
time represented by the realtime value is one millisecond. However, the
rate at which it changes is implementation dependent. As the time value
becomes greater than the largest integer allowed in a particular
implementation, it "wraps" to the smallest (most negative) integer.

ERRORS: stackoverflow

SEE ALSO: usertime
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rectclip* x y width height rectclip -
numarray rectclip -
numstring rectclip - LEVEL 2

intersects the inside of the current clipping path with a rectangular path
the operands describe. In the first form, the operands are four numbers
that describe a single rectangle. In the other two forms, the operand is an
array or an encoded number string that describes an arbitrary number of
rectangles. After computing the new clipping path, rectclip resets the
current path to empty, as if by newpath.

In the first form, assuming width and height are positive, rectclip is
equivalent to:

newpath
x y moveto
width 0 rlineto
0 height rlineto
width neg 0 rlineto
closepath
clip
newpath

Note that if the second or third form is used to specify multiple
rectangles, the rectangles are treated together as a single path and used
for a single clip operation. The "inside" of this combined path is the
union of all the rectangular subpaths, because the paths are all drawn in
the same direction and the non-zero winding number rule is used.

ERRORS: limitcheck, stackunderflow, typecheck

SEE ALSO: clip, rectfill, rectstroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rectfill* x y width height rectfill -
numarray rectfill -
numstring rectfill - LEVEL 2

fills a path consisting of one or more rectangles the operands describe. In
the first form, the operands are four numbers that describe a single
rectangle. In the other two forms, the operand is an array or an encoded
number string that describes an arbitrary number of rectangles rectfill
neither reads nor alters the current path in the graphics state.

In the first form, assuming width and height are positive, rectfill is
equivalent to:

gsave
newpath
x y moveto
width 0 rlineto
0 height rlineto
width neg 0 rlineto
closepath
fill
grestore

ERRORS: limitcheck, stackunderflow, typecheck

SEE ALSO: fill, rectclip, rectstroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rectstroke* x y width height rectstroke -
x y width height matrix rectstroke -
numarray rectstroke-
numarray matrix rectstroke -
numstring rectstroke -
numstring matrix rectstroke - LEVEL 2

strokes a path consisting of one or more rectangles the operands describe.
In the first two forms, the operands are four numbers that describe a
single rectangle. In the remaining forms, the operand is an array or an
encoded number string that describes an arbitrary number of rectangles
rectstroke neither reads nor alters the current path in the graphics state.

If the matrix operand is present, rectstroke concatenates matrix to the CTM
after defining the path, but before stroking it. The matrix applies to the
line width and dash pattern, if any, but not to the path itself.

In the first two forms, assuming width and height are positive, rectstroke
is equivalent to:

gsave
newpath
x y moveto
width 0 rlineto
0 height rlineto
width neg 0 rlineto
closepath
matrix concat % If matrix operand is supplied
stroke
grestore

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: stroke, rectclip, rectfill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rectviewclip* x y width height rectviewclip
- numarray rectviewclip
- numstring rectviewclip - LEVEL 2

replaces the current view clip with a rectangular path the operands
describe. In the first form, the operands are four numbers that describe a
single rectangle. In the other two forms, the operand is an array or an
encoded number string that describes an arbitrary number of rectangles.
After computing the new view clipping path, rectviewclip resets the current
path to empty, as if by newpath.

Except for the manner in which the path is defined, rectviewclip behaves
the same as viewclip.
Note that if the second or third form is used to specify multiple
rectangles, the rectangles are treated together as a single path and used
for a single viewclip operation. The "inside" of this combined path is the
union of all the rectangular subpaths, because the paths are all drawn in
the same direction and the nonzero winding number rule is used.

ERRORS: limitcheck, stackunderflow, typecheck

SEE ALSO: rectclip, viewclip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*renamefile* old new renamefile - LEVEL 2

changes the name of a file from old to new, where old and new are strings
that specify file names on the same storage device.
If no such file exists, an undefinedfilename error occurs.
If the device does not allow this operation, an invalidfileaccess error
occurs.
If an environment-dependent error is detected, an ioerror occurs.
Whether or not an error occurs if a file named new already exists is
environment dependent.

ERRORS: invalidfileaccess, ioerror, stackunderflow, typecheck,
undefinedfilename

SEE ALSO: file, deletefile, status
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*repeat* int proc repeat

- executes proc int times, where int is a non-negative integer. The repeat
operator removes both operands from the stack before executing proc for the
first time. If proc executes the exit operator, repeat terminates
prematurely. repeat leaves no results of its own on the stack, but proc may
do so.

EXAMPLE:
4 {(abc)} repeat -> (abc)(abc)(abc)(abc)
1 2 3 4 3 {pop} repeat -> 1 % Pops 3 values (down to the 1)

4 {} repeat -> % Does nothing four times

mark 0 {(won't happen)} repeat -> mark

In the last example, a zero repeat count meant that the procedure is not
executed at all, hence the mark is still topmost on the stack.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: for, loop, forall, exit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*resetfile* file resetfile - LEVEL 2

discards buffered characters belonging to a file object. For an input file,
resetfile discards any characters that have been received from the source,
but not yet consumed. For an output file, it discards any characters that
have been written to the file, but not yet delivered to their destination.

resetfile may have other side effects that depend on the properties of the
underlying file. For example, it may restart communication via a channel
that was blocked waiting for buffer space to become available. resetfile
never waits for characters to be received or transmitted.

ERRORS: stackunderflow, typecheck

SEE ALSO: file, closefile, flushfile
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*resourceforall* template proc scratch category resourceforall - LEVEL 2

enumerates the names of all instances of a specified resource category or a
subset selected by template. category is a name object that identifies a
resource category, such as Font.
template is a string object to be matched against names of resource
instances. For each matching name, resourceforall copies the name into the
supplied scratch string, pushes a string object that is the substring of
scratch that was actually used, and calls proc. resourceforall does not
return any results of its own, but proc may do so.

The template is matched against the names of resource instances, treating
them as if they were strings. Within the template, all characters are
treated literally and are case sensitive, with the exception of the
following:

* matches zero or more consecutive characters.

? matches exactly one character.

causes the next character of the template to be treated literally, even if
it is *, ?, or /.

Note that the scratch string is reused during every call to proc. If proc
wishes to save the string that is passed to it, it must make a copy or use
cvn to convert the string to a name. Use of strings instead of names allows
resourceforall to function without creating new name objects, which would
consume VM needlessly during a large enumeration. It is prudent to provide
a scratch string at least as long as the implementation limit for names.

It is possible for a resource instance to have a key which is not a name or
string. Such a key matches only the template (*). In this case,
resourceforall passes the key directly to proc instead of copying it into
the scratch string. This case can arise only for a resource instance
defined in VM by a previous defineresource; the keys for external resource
instances are always names or strings.

Like resourcestatus, but unlike findresource, resourceforall never loads a
resource instance into VM.

resourceforall enumerates the resource instances in order of status (the
status value returned by resourcestatus); that is, it enumerates groups in
this order:

     1. Instances defined in VM by an explicit defineresource; not subject
     to automatic removal.

     2. Instances defined in VM by a previous execution of findresource;
     subject to automatic removal.

     3. Instances not currently defined in VM, but available from external
     storage.

Within each group, the order of enumeration is unpredictable. It is
unrelated to order of definition or to whether the definition is local or
global. A given resource instance is enumerated only once, even if it
exists in more than one group. If proc adds or removes resource instances,
those instances may or may not appear later in the same enumeration.

Like resourcestatus, resourceforall considers both local and global
definitions if the current VM allocation mode is local, but only global
definitions if the current VM allocation mode is global (see resourcestatus
and defineresource).

If the specified resource category does not exist, an undefined error
occurs. However, no error occurs if there are no instances whose names
match the template. Of course, the proc that is called can generate errors
of its own.

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck, undefined

SEE ALSO: defineresource, undefineresource, findresource, resourcestatus
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*resourcestatus* key category resourcestatus status size true LEVEL 2
(if resource exists)
false (if not)

returns status information about a named resource instance. category is a
name object that identifies a resource category, such as Font. key is a
name or string object that identifies the resource instance. (Names and
strings are interchangeable; keys of other types are permitted but are not
recommended.)

If the named resource instance exists, either defined in VM or available
from some external source, resourcestatus returns two integers and the
value true; otherwise, it returns false. Unlike findresource,
resourcestatus never loads a resource instance into VM.

status is an integer with the following meanings:

     0 Defined in VM by an explicit defineresource; not subject to
     automatic removal.

     1 Defined in VM by a previous execution of findresource; subject to
     automatic removal.

     2 Not currently defined in VM, but available from external storage.

size is an integer giving the estimated VM consumption of the resource
instance in bytes. This information may not be available for certain
resources; if the size is unknown, -1 is returned. Usually, resourcestatus
can obtain the size of a status 1 or 2 resource (derived from the %%VMusage
comment in the resource file), but it has no general way to determine the
size of a status 0 resource. A size value of 0 is returned for implicit
resources, whose instances do not occupy VM.

If the current VM allocation mode is local, resourcestatus considers both
local and global resource definitions, in that order (see defineresource).
However, if the current VM allocation mode is global, only global resource
definitions are visible to resourcestatus. Resource instances in external
storage are visible without regard to the current VM allocation mode.

If the specified resource category does not exist, an undefined error
occurs.

ERRORS: stackoverflow, stackunderflow, typecheck, undefined

SEE ALSO: defineresource, undefineresource, findresource, resourceforall
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*restore* save restore

- resets the virtual memory (VM) to the state represented by the supplied
save object-in other words, the state at the time the corresponding save
was executed.

If the current execution context supports job encapsulation and if save
represents the outermost saved VM state for this context, then objects in
both local and global VM revert to their saved state. If the current
context does not support job encapsulation or if save is not the outermost
saved VM state for this context, then only objects in local VM revert to
their saved state; objects in global VM are undisturbed.

restore can reset the VM to the state represented by any save object that
is still valid, not necessarily the one produced by the most recent save.
After restoring the VM, restore invalidates its save operand along with any
other save objects created more recently than that one. That is, a VM
snapshot can be used only once; to restore the same environment repeatedly,
it is necessary to do a new save each time.

restore does not alter the contents of the operand, dictionary, or
execution stack, except to pop its save operand. If any of these stacks
contains composite objects whose values reside in local VM and are newer
than the snapshot being restored, restore executes the invalidrestore
error. This restriction applies to save objects and, in Level 1
implementations, to name objects.

restore does alter the graphics state stack: It performs the equivalent of
a grestoreall and then removes the graphics state created by save from the
graphics state stack. restore also resets several per-context parameters to
their state at the time of save. These include:

   * Array packing mode (see setpacking).

   * VM allocation mode (see setglobal).

   * Object output format (see setobjectformat).

   * View clipping path (see viewclip).

   * All user interpreter parameters (see setuserparams).

ERRORS: invalidrestore, stackunderflow, typecheck

SEE ALSO: save, grestoreall, vmstatus, startjob
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*reversepath* - reversepath

- replaces the current path with an equivalent one whose segments are
defined in the reverse order. Precisely, reversepath reverses the
directions and order of segments within each subpath of the current path.
However, it does not alter the order of the subpaths in the path with
respect to each other.

ERRORS: limitcheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*revision* - revision int LEVEL 2

is an integer designating the current revision level of the product in
which the PostScript interpreter is running. Each product has its own
numbering system for revisions, independent of those of any other product.
This is distinct from the value of version in systemdict, which is the
revision level of the PostScript interpreter, without regard to the product
in which it is running.

ERRORS: stackoverflow

SEE ALSO: languagelevel, product, serialnumber, version
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rlineto* dx dy rlineto

- (relative lineto) appends a straight line segment to the current path in
the same manner as lineto. However, the number pair is interpreted as a
displacement relative to the current point (x, y) rather than as an
absolute coordinate. That is, rlineto constructs a line from (x, y) to (x +
dx, y + dy) and makes (x + dx, y + dy) the new current point.
If the current point is undefined because the current path is empty,
rlineto executes the error nocurrentpoint.

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck

SEE ALSO: lineto, rmoveto, rcurveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rmoveto* dx dy rmoveto

- (relative moveto) starts a new subpath of the current path in the same
manner as moveto. However, the number pair is interpreted as a displacement
relative to the current point (x, y) rather than as an absolute coordinate.
That is, rmoveto makes (x + dx, y + dy) the new current point, without
connecting it to the previous point.
If the current point is undefined because the current path is empty,
rmoveto executes the error nocurrentpoint.

ERRORS: limitcheck, nocurrentpoint, stackunderflow, typecheck

SEE ALSO: moveto, rlineto, rcurveto
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*roll* anyn-1 ... any0 n j roll any (j-1) mod n ... any0 anyn-1 ... 
anyj mod n

performs a circular shift of the objects anyn-1 through any0 on the operand
stack by the amount j. Positive j indicates upward motion on the stack,
whereas negative j indicates downward motion.

n must be a non-negative integer and j must be an integer. roll first
removes these operands from the stack; there must be at least n additional
elements. roll then performs a circular shift of these n elements by j
positions.

If j is positive, each shift consists of removing an element from the top
of the stack and inserting it between element n - 1 and element n of the
stack, moving all intervening elements one level higher on the stack. If j
is negative, each shift consists of removing element n - 1 of the stack and
pushing it on the top of the stack, moving all intervening elements one
level lower on the stack.

EXAMPLE:

(a)(b)(c) 3 -1 roll -> (b)(c)(a)
(a)(b)(c) 3 1 roll -> (c)(a)(b)
(a)(b)(c) 3 0 roll -> (a)(b)(c)

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: exch, index, copy, pop
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rootfont* - rootfont font LEVEL 2

returns the font that has been selected most recently by setfont or
selectfont. Normally, rootfont returns the same result as currentfont. If
the current font is a composite font and rootfont is invoked from a
descendant font's BuildGlyph or BuildChar procedure or from cshow, rootfont
returns the root composite font, whereas currentfont would return the
currently selected base font.

ERRORS: stackoverflow

SEE ALSO: setfont, selectfont, currentfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rotate* angle rotate
- angle matrix rotate matrix

With no matrix operand, rotate builds a temporary matrix where q is the
operand angle in degrees, and concatenates this matrix with the current
transformation matrix (CTM). Precisely, rotate replaces the CTM by R x CTM.
The effect of this is to rotate the user coordinate system axes about their
origin by angle degrees (positive is counterclockwise) with respect to
their former orientation. The position of the user coordinate origin and
the sizes of the x and y units are unchanged.

If the matrix operand is supplied, rotate replaces the value of matrix by R
and pushes the modified matrix back on the operand stack. In this case,
rotate does not affect the CTM.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: scale, translate, concat
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*round* num1 round num2

returns the integer value nearest to num1. If num1 is equally close to its
two nearest integers, round returns the greater of the two. The type of the
result is the same as the type of the operand.

EXAMPLE:
3.2 round -> 3.0
6.5 round -> 7.0
-4.8 round -> -5.0
-6.5 round -> -6.0
99 round -> 99

ERRORS: stackunderflow, typecheck

SEE ALSO: ceiling, floor, truncate, cvi
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*rrand* - rrand int

returns an integer representing the current state of the random number
generator used by rand. This may later be presented as an operand to srand
to reset the random number generator to the current position in the
sequence of numbers produced.

ERRORS: stackoverflow

SEE ALSO: rand, srand
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*run* string run

- executes the contents of the file identified by string-in other words,
interprets the characters in that file as a PostScript language program.
When run encounters end-of-file or terminates for some other reason (for
example, stop), it closes the file.

run is essentially a convenience operator for the sequence

(r) file cvx exec

except for its behavior upon abnormal termination. Also, the context of a
run cannot be left by executing exit; an attempt to do so produces the
error invalidexit. The run operator leaves no results on the operand stack,
but the program executed by run may alter the stacks arbitrarily.

ERRORS: ioerror, limitcheck, stackunderflow, typecheck, undefinedfilename

SEE ALSO: exec, file
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*save* - save

save creates a snapshot of the current state of the virtual memory (VM) and
returns a save object representing that snapshot. Subsequently, this save
object may be presented to restore to reset the VM to this snapshot. See
the restore operator for a detailed description of what is saved in the
snapshot. save also saves the current graphics state by pushing a copy of
it on the graphics state stack in a manner similar to gsave. This saved
graphics state is restored by restore and grestoreall.

EXAMPLE:

/saveobj save def
....arbitrary computation...
saveobj restore % Restore saved VM state

ERRORS: limitcheck, stackoverflow

SEE ALSO: restore, gsave, grestoreall, vmstatus
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*scale* sx sy scale sx sy matrix scale matrix

With no matrix operand, scale builds a temporary matrix and concatenates
this matrix with the current transformation matrix (CTM). Precisely, scale
replaces the CTM by S x CTM. The effect of this is to make the x and y
units in the user coordinate system the size of sx and sy units in the
former user coordinate system. The position of the user coordinate origin
and the orientation of the axes are unchanged. If the matrix operand is
supplied, scale replaces the value of matrix by S and pushes the modified
matrix back on the operand stack In this case, scale does not affect the
CTM.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: rotate, translate, concat
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*scalefont* font scale scalefont font'

applies the scale factor scale to font, producing a new font' whose
characters are scaled by scale (in both x and y) when they are shown.
scalefont first creates a copy of font, then replaces the new font's
FontMatrix entry with the result of scaling the existing FontMatrix by
scale.
It inserts two additional entries, OrigFont and ScaleMatrix, whose purpose
is internal to the implementation. Finally, it returns the result as font'.
Showing characters from the transformed font produces the same results as
showing from the original font after having scaled user space by the factor
scale in both x and y by means of the scale operator.
scalefont is essentially a convenience operator that enables the desired
scale factor to be encapsulated in the font description. Another operator,
makefont, performs more general transformations than simple scaling. See
the description of makefont for more information on how the transformed
font is derived. selectfont combines the effects of findfont and scalefont.
The interpreter keeps track of font dictionaries recently created by
scalefont.
Calling scalefont multiple times with the same font and scale will usually
return the same font' rather than create a new one each time. However, it
is usually more efficient for a PostScript language program to apply
scalefont only once for each font that it needs and to keep track of the
resulting font dictionaries on its own."
The makefont, scalefont, and selectfont operators produce a font dictionary
derived from an original font dictionary, but with the FontMatrix entry
altered. The derived font dictionary is allocated in local or global VM
according to whether the original font dictionary is in local or global VM.
This is independent of the current VM allocation mode.

EXAMPLE:

/Helvetica findfont 12 scalefont setfont

This obtains the standard Helvetica font, which is defined with a 1-unit
line height, and scales it by a factor of 12 in both x and y dimensions.
This produces a 12-unit high font (i.e., a 12-point font in default user
space) whose characters have the same proportions as those in the original
font.

ERRORS: invalidfont, stackunderflow, typecheck, undefined

SEE ALSO: makefont, setfont, findfont, selectfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*scheck* any scheck bool LEVEL 2

has the same semantics as gcheck. This operator is defined for
compatibility with existing Display PostScript applications.

ERRORS: stackunderflow

SEE ALSO: gcheck
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*search* string seek search post match pre true (if found)
string false (if not found)

looks for the first occurrence of the string seek within string and returns
results of this search on the operand stack. The topmost result is a
boolean that indicates if the search succeeded. If search finds a
subsequence of string whose elements are equal to the elements of seek, it
splits string into three segments: pre, the portion of string preceding the
match; match, the portion of string that matches seek; and post, the
remainder of string. It then pushes the string objects post, match, and pre
on the operand stack, followed by the boolean true. All three of these
strings are substrings sharing intervals of the value of the original
string. If search does not find a match, it pushes the original string and
the boolean false.

EXAMPLE:
(abbc) (ab) search -> (bc) (ab) ( ) true
(abbc) (bb) search -> (c) (bb) (a) true
(abbc) (bc) search -> ( ) (bc) (ab) true
(abbc) (B) search -> (abbc) false

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck

SEE ALSO: anchorsearch, token
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*selectfont* key scale selectfont - key matrix selectfont - LEVEL 2

obtains a font whose name is key, transforms it according to scale or
matrix, and establishes it as the current font dictionary in the graphics
state.
selectfont is equivalent to one of the following, according to whether the
second operand is a number or a matrix:
key findfont scale scalefont setfont key findfont matrix makefont setfont

If the font named by key is already defined in VM, selectfont obtains the
font dictionary directly and does not execute findfont. However, if the
font is not defined, selectfont invokes findfont in the normal way. In the
latter case, it actually executes the name object findfont, so it uses the
current definition of that name in the environment of the dictionary stack.

On the other hand, redefining exch, scalefont, makefont, or setfont would
not alter the behavior of selectfont. selectfont can give rise to any of
the errors possible for the component operations, including arbitrary
errors from a user-defined findfont procedure.

EXAMPLE:
/Helvetica 10 selectfont /Helvetica findfont 10 scalefont setfont

The two lines of the example have the same effect, but the first one is
almost always more efficient. The makefont, scalefont, and selectfont
operators produce a font dictionary derived from an original font
dictionary, but with the FontMatrix entry altered.
The derived font dictionary is allocated in local or global VM according to
whether the original font dictionary is in local or global VM. This is
independent of the current VM allocation mode.

ERRORS: invalidfont, rangecheck, stackunderflow, typecheck

SEE ALSO: findfont, makefont, scalefont, setfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*serialnumber* - serialnumber int LEVEL 2

returns an integer that purports to represent the specific machine on which
the PostScript interpreter is running. The precise significance of this
number (including any claim of its uniqueness) is product dependent.

ERRORS: stackoverflow

SEE ALSO: languagelevel, product, revision, version
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setbbox* llx lly urx ury setbbox

- establishes a bounding box for the current path, within which the
coordinates of all subsequent path construction operators must fall.
The bounding box is defined by two pairs of coordinates in user space:
llx and lly specify the lower-left corner,
urx and ury the upper-right corner.
It is a rectangle oriented with the user space coordinate system axes. The
bounding box remains in effect for the lifetime of the current path-that
is, until the next newpath or operator that resets the path implicitly. Any
attempt to append a path element with a coordinate lying outside the
bounding box will give rise to a rangecheck error.
Note that arcs are converted to sequences of curveto operations. The
coordinates computed as control points for those curvetos must also fall
within the bounding box. This means that the figure of the arc must be
entirely enclosed by the bounding box. On the other hand, the bounds
checking applies only to the path itself, not to the result of rendering
the path.
For example, stroking the path may place marks outside the bounding box.
This does not cause an error. Although the setbbox operator can be used
when defining any path, its main use is in defining a user path, where it
is mandatory. That is, a user path procedure passed to one of the user path
rendering operators, such as ufill, must begin with a setbbox optionally
preceded by a ucache.
The bounding box information passed to setbbox enables the user path
rendering operator to optimize execution.
If setbbox appears more than once during definition of a path, the path's
effective bounding box is successively enlarged to enclose the union of all
specified bounding boxes. This is not legal in a user path definition.
However, this case might arise if uappend is executed multiple times in
building up a single current path by concatenating several user paths.
If setbbox has established a bounding box, execution of pathbbox returns a
result derived from that bounding box instead of one derived from the
actual path. The upper-right coordinate values must be greater than or
equal to the lower-left values. Otherwise, a rangecheck error will occur.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: pathbbox
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setblackgeneration* proc setblackgeneration - LEVEL 2

sets the black generation function parameter in the graphics state. The
proc operand must be a procedure that can be called with a number in the
range 0.0 to 1.0 (inclusive) on the operand stack and that returns a number
in the same range. This procedure computes the value of the black component
during conversion from DeviceRGB color space to DeviceCMYK.
setblackgeneration sets a graphics state parameter whose effect is device
dependent. It should not be used in a page description that is intended to
be device independent.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: setundercolorremoval
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcachedevice* wx wy llx lly urx ury setcachedevice

- passes width and bounding box information to the PostScript interpreter's
font machinery. setcachedevice may be executed only within the context of
the BuildGlyph or BuildChar procedure for a type 3 font.
BuildGlyph or BuildChar must invoke setcachedevice, setcachedevice2, or
setcharwidth before executing graphics operators to define and paint the
character. setcachedevice requests the font machinery to transfer the
results of those operators both into the font cache, if possible, and onto
the current page. The operands to setcachedevice are all numbers
interpreted in the character coordinate system .
wx and wy comprise the basic width vector for this character-in other
words, the normal position of the origin of the next character relative to
origin of this one. llx and lly are the coordinates of the lower-left
corner and urx and ury are the coordinates of the upper-right corner of the
character bounding box. The character bounding box is the smallest
rectangle, oriented with the character coordinate system axes, that
completely encloses all marks placed on the page as a result of executing
the character's description.
For a character defined as a path, this may be determined by means of the
pathbbox operator. The font machinery needs this information to make
decisions about clipping and caching. The declared bounding box must be
correct-in other words, sufficiently large to enclose the entire character.
If any marks fall outside this bounding box, they will be clipped off and
not moved to the current page. setcachedevice installs identical sets of
metrics for writing modes 0 and 1, while setcachedevice2 installs separate
metrics.
After execution of setcachedevice and until the termination of the
BuildGlyph or BuildChar procedure, execution of color setting operators or
image is not allowed. Note that use of the imagemask operator is permitted.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: setcachedevice2, setcharwidth, setcachelimit, cachestatus
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcachedevice2* w0x w0y llx lly urx ury w1x w1y vx vy setcachedevice2 -
LEVEL 2

passes two sets of character metrics to the font machinery.

w0x and w0y are the distances from the current point
to the new current point when showing text in writing mode 0.

llx,lly and urx,ury are the distances from origin 0
to the lower-left and upper-right corners of the character bounding box.

w1x, w1y are the distances from the current point to the new current point
when showing text in writing mode 1.

vx and vy are the distances from origin 0 to origin 1.

Aside from its interpretation of the operands, setcachedevice2 works the
same as setcachedevice in all respects. After execution of setcachedevice2
and until the termination of the BuildGlyph or BuildChar procedure,
execution of color setting operators or image is not allowed. Note that use
of the imagemask operator is permitted.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: setcachedevice, setcharwidth, setcachelimit, cachestatus
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcachelimit* int setcachelimit

- establishes the maximum number of bytes the pixel array of a single
cached character may occupy. Any character larger than this (according to
the character bounding box information passed to setcachedevice) is not
saved in the font cache. Instead, its description is executed every time
the character is encountered. setcachelimit affects the decision whether to
place new characters in the font cache; it does not disturb any characters
already in the cache.
Making the limit larger allows larger characters to be cached, but may
decrease the total number of different characters that can be held in the
cache simultaneously. Changing this parameter is appropriate only in very
unusual situations.
The maximum limit for int is implementation dependent, representing the
total available size of the font cache (see cachestatus). As a practical
matter, int should not be larger than a small fraction of the total font
cache size. Modifications to the cache limit parameter obey save and
restore.
In a Display PostScript system, which supports multiple contexts, this
parameter is maintained separately for each context. The parameter set by
setcachelimit is the same as the MaxFontItem user parameter set by
setuserparams.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: cachestatus, setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcacheparams* mark size lower upper setcacheparams - LEVEL 2

sets cache parameters as specified by the integer objects above the topmost
mark on the stack, then removes all operands and the mark object as if by
cleartomark. The number of cache parameters is variable.
In future versions of the PostScript interpreter, there may be more than
three cache parameters defined. If more operands are supplied to
setcacheparams than are needed, the topmost ones are used and the remainder
ignored. If fewer are supplied than are needed, setcacheparams implicitly
inserts default values between the mark and the first supplied operand.
The upper operand specifies the maximum number of bytes the pixel array of
a single cached character may occupy, as determined from the information
presented by the setcachedevice operator. This is the same parameter set by
setcachelimit.
The lower operand specifies the threshold at which characters may be stored
in compressed form rather than as full pixel arrays. If a character's pixel
array requires more than lower bytes to represent, it may be compressed in
the cache and reconstituted from the compressed representation each time it
is needed. Some devices do not support compression of characters. Setting
lower to zero forces all characters to be compressed, permitting more
characters to be stored in the cache, but increasing the work required to
print them. Setting lower to a value greater than or equal to upper
disables compression altogether.
The size operand specifies the new size of the font cache in bytes (the
bmax value returned by cachestatus). If size is not specified, the font
cache size is unchanged. If size lies outside the range of font cache sizes
permitted by the implementation, the nearest permissible size is
substituted with no error indication.
Reducing the font cache size can cause some existing cached characters to
be discarded, increasing execution time when those characters are next
shown. The parameters set by setcacheparams are the same as the
MaxFontCache system parameter and the MinFontCompress and MaxFontItem user
parameters, set by setsystemparams and setuserparams, respectively .

ERRORS: rangecheck, typecheck, unmatchedmark

SEE ALSO: currentcacheparams, setcachelimit, setsystemparams, setuserparams

---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcharwidth* wx wy setcharwidth

- is similar to setcachedevice, but it passes only width information to the
PostScript interpreter's font machinery and it declares that the character
being defined is not to be placed in the font cache. setcharwidth is
useful, for example, in defining characters that incorporate two or more
specific opaque colors, such as opaque black and opaque white.
This is unusual. Most characters have no inherent color, but are painted
with the current color within the character's outline, leaving the area
outside unpainted (transparent). Another use of setcharwidth is in defining
characters that intentionally change their behavior based on the
environment in which they execute. Such characters must not be cached,
because that would subvert the intended variable behavior.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: setcachedevice, setcachedevice2
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcmykcolor* cyan magenta yellow black setcmykcolor - LEVEL 2

sets the color space to DeviceCMYK, then sets the current color parameter
in the graphics state to a color described by the parameters cyan, magenta,
yellow, and black, each of which must be a number in the range 0.0 to 1.0.
This establishes the color subsequently used to paint shapes, such as
lines, areas, and characters on the current page. Color values set by
setcmykcolor are not affected by the black generation and undercolor
removal operations.
setcmykcolor does not give an error for a value outside the range 0 to 1.
It substitutes the nearest legal value.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: setcolorspace, setcolor, currentcmykcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcolor* comp1 comp2 ... compn setcolor - LEVEL 2

sets the current color parameter in the graphics state to that described by
the color components comp1, comp2 ..., compn in the current color space.
The number of color components and the valid range of color component
values depends on the current color space. If the wrong number of
components is specified, an error will occur, such as stackunderflow or
typecheck. If a component value is outside the valid range, the nearest
valid value will be substituted without error indication. The initial value
of the color parameter varies by color space. It is initialized by the
setcolorspace operator.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: currentcolor, setcolorspace
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcolorrendering* dict setcolorrendering - LEVEL 2

establishes dict as the current CIE based color rendering dictionary in the
graphics state. The default color rendering dictionary is device dependent
). setcolorrendering sets a graphics state parameter whose effect is device
dependent. It should not be used in a page description that is intended to
be device independent.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck limitcheck, rangecheck, undefined

SEE ALSO: currentcolorrendering
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcolorscreen*
redfreq redang redproc
greenfreq greenang greenproc
bluefreq blueang blueproc
grayfreq grayang grayproc setcolorscreen - LEVEL 2

sets the halftone parameter in the graphics state. setcolorscreen specifies
halftone screen definitions for all four primary color components of the
output device: red, green, blue, and gray or their complements: cyan,
magenta, yellow, and black. For each component, setcolorscreen expects
frequency, angle, and spot function operands, which it interprets the same
as setscreen . setcolorscreen sets a graphics state parameter whose effect
is device dependent. It should not be used in a page description that is
intended to be device independent.

EXAMPLE:

% 50 line dot screen with 75 degree cyan, 15 degree magenta
% 0 degree yellow, and 45 degree black angled screens,
% which are commonly used for color printing
/sfreq 50 def % 50 halftone cells per inch
/sproc {dup mul exch dup mul add 1 exch sub} def % Dot-screen spot function

sfreq 75 /sproc load % 75 degree red (cyan) screen
sfreq 15 /sproc load % 15 degree green (magenta) screen
sfreq 0 /sproc load % 0 degree blue (yellow) screen
sfreq 45 /sproc load % 45 degree gray (black) screen setcolorscreen

Execution of this operator is not permitted in certain circumstances.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: currentcolorscreen, setscreen, sethalftone
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcolorspace* array setcolorspace
name setcolorspace - LEVEL 2

- The first form sets the color space parameter in the graphics state to
that described by the specified array.
The array must be in the form [ key param1 ... paramn] where key is a name
that identifies the color space family and the parameters param1 ... paramn
further describe the space as a whole.
The second form specifies a color space by giving just its name. This is
allowed only for those color spaces that require no parameters, namely
DeviceGray, DeviceRGB, DeviceCMYK, and Pattern. Specifying a color space by
name is equivalent to specifying it by an array containing just that name.
The setcolorspace operator also sets the current color parameter in the
graphics state to its initial value, which depends on the color space.
Execution of this operator is not permitted in certain circumstances. The
details of the color space parameters, the definitions of the components of
a specific color in the space, and initial values of those components vary
from one color space to another. The initial value of the color space
parameter is /DeviceGray.

ERRORS: stackunderflow, typecheck , rangecheck, undefined

SEE ALSO: currentcolorspace, setcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setcolortransfer* redproc greenproc blueproc grayproc setcolortransfer -
LEVEL 2

sets the transfer function parameter in the graphics state.
setcolortransfer specifies transfer functions for all four primary color
components of the output device: red, green, blue, and gray or their
complements: cyan, magenta, yellow, and black.
Each operand must be a PostScript language procedure that may be called
with a number in the range 0.0 to 1.0 (inclusive) on the operand stack and
that will return a number in the same range. These procedures adjust the
values of device color components.
Only those transfer functions corresponding to color components supported
by a device will have an effect on that device's output. For example,
redproc, greenproc, and blueproc will have no effect on a black-and-white
device, while grayproc will have no effect on an RGB device.
setcolortransfer sets a graphics state parameter whose effect is device
dependent. It should not be used in a page description that is intended to
be device independent.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: currentcolortransfer, settransfer
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setdash* array offset setdash

- sets the dash pattern parameter in the graphics state, controlling the
dash pattern used during subsequent executions of the stroke operator and
operators based on stroke, such as rectstroke and ustroke.
If array is empty (i.e., its length is zero), stroke produces a normal,
unbroken line.
If array is not empty, stroke produces dashed lines whose pattern is given
by the elements of array, all of which must be non-negative numbers and not
all zero. stroke interprets the elements of array in sequence as distances
along the path, measured in user space.
These distances alternately specify the length of a dash and the length of
a gap between dashes. stroke uses the contents of array cyclically. When it
reaches the end of the array, it starts again at the beginning. Dashed
lines wrap around curves and corners just as normal strokes do.
The ends of each dash are treated with the current line cap; corners within
a dash are treated with the current line join. stroke does not take any
measures to coordinate the dash pattern with features of the path. It
simply dispenses dashes along the path as specified by array.
The offset operand may be thought of as the "phase" of the dash pattern
relative to the start of the path. It is interpreted as a distance into the
dash pattern (measured in user space) at which the pattern should be
started.
Before beginning to stroke a path, stroke cycles through the elements of
array, adding up distances and alternating dashes and gaps as usual, but
without generating any output. When it has travelled the offset distance
into the dash pattern, it starts stroking the path from its beginning,
using the dash pattern from the point that has been reached. Each subpath
of a path is treated independently-in other words, the dash pattern is
restarted and offset applied to it at the beginning of each subpath.

EXAMPLE:
[ ] 0 setdash % Turn dashing off: solid lines
[3] 0 setdash % 3-unit on, 3-unit off,
.... [2] 1 setdash % 1 on, 2 off, 2 on, 2 off,
.... [2 1] 0 setdash % 2 on, 1 off, 2 on, 1 off,
.... [3 5] 6 setdash % 2 off, 3 on, 5 off, 3 on, 5 off,
.... [2 3] 11 setdash % 1 on, 3 off, 2 on, 3 off, 2 on, ...

ERRORS: limitcheck, stackunderflow, typecheck

SEE ALSO: currentdash, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setdevparams* string dict setdevparams - LEVEL 2

attempts to set one or more parameters for the device identified by string
according to keys and new values contained in the dict operand. The string
identifies a storage or I/O device
.. The dictionary is a container for key-value pairs; setdevparams reads the
information from the dictionary but does not retain the dictionary itself.
Device parameters whose keys are not mentioned in dict are left unchanged.
Each parameter is identified by a key, which is always a name object. The
value is usually (but not necessarily) an integer. The names of I/O devices
and the names and semantics of their parameters are product-dependent. They
are not documented in this manual, but rather in product-specific
documentation.
Permission to alter device parameters is controlled by a password. The
dictionary must contain an entry named Password whose value is the system
parameter password (a string or integer). If the password is incorrect,
setdevparams executes an invalidaccess error and does not alter any
parameters. Some device parameters can be set permanently in non-volatile
storage that survives restarts of the PostScript interpreter. This
capability is implementation dependent.
No error occurs if parameters cannot be stored permanently. Various errors
are possible. Details of error behavior are product dependent, but the
following behavior is typical:

   * If a parameter name is not known to the implementation, an undefined
     error occurs.
   * If a parameter value is of the wrong type, a typecheck error occurs.
   * If a parameter value is unreasonable-for instance, a negative integer
     for a parameter that must be positive-a rangecheck error occurs.
   * If a parameter value is reasonable but cannot be achieved by the
     implementation, either the nearest achievable value is substituted or
     a configurationerror occurs, depending on the device and the
     parameter.

ERRORS: configurationerror, invalidaccess, rangecheck, stackunderflow,
typecheck, undefined

SEE ALSO: currentdevparams, setsystemparams, setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setfileposition* file position setfileposition - LEVEL 2

repositions an existing open file to a new position so the next read or
write operation will commence at that position. The position operand is a
non-negative integer interpreted as number of bytes from the beginning of
the file. For an output file, setfileposition first performs an implicit
flushfile . The result of positioning beyond end-of-file for both reading
and writing depends on the behavior of the underlying file system.
Typically, positioning beyond the existing end-of-file will lengthen the
file if it is open for writing and the file's access permits. The storage
appended to the file has unspecified contents. If lengthening the file is
not permitted, an ioerror occurs. Possible causes of an ioerror are: the
file object is not valid, the underlying file is not positionable, the
specified position is invalid for the file, or a device-dependent error
condition is detected.

ERRORS: ioerror, rangecheck, stackunderflow, typecheck , undefinedfilename

SEE ALSO: fileposition, file
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setflat* num setflat

- sets the flatness parameter in the graphics state to num, which must be a
positive number. This controls the accuracy with which curved path segments
are to be rendered on the raster output device by operators such as stroke,
fill, and clip. Those operators render curves by approximating them with a
series of straight line segments. "Flatness" is an informal term for the
error tolerance of this approximation; it is the maximum distance of any
point of the approximation from the corresponding point on the true curve,
measured in output device pixels.
If the flatness parameter is large enough to cause visible straight line
segments to appear, the result is unpredictable. The purpose of setflat is
to control the accuracy of curve rendering, not to draw inscribed polygons.

The choice of flatness value is a trade-off between accuracy and execution
efficiency. Very small values (less than 1 device pixel) produce very
accurate curves at high cost, because enormous numbers of tiny line
segments must be produced. Larger values produce cruder approximations with
substantially less computation. A default value of the flatness parameter
is established by the device setup routine for each raster output device.
This value is based on characteristics of that device and is the one
suitable for most applications.
The acceptable range of values for num is 0.2 to 100. Values outside this
range are forced into range without error indication. setflat sets a
graphics state parameter whose effect is device dependent. It should not be
used in a page description that is intended to be device independent.

ERRORS: stackunderflow, typecheck

SEE ALSO: currentflat, flattenpath, stroke, fill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setfont* font setfont

- establishes the font dictionary parameter in the graphics state. This
specifies the font to be used by subsequent character operators, such as
show and stringwidth. font must be a valid font dictionary previously
returned by findfont, scalefont, or makefont.

EXAMPLE:
/Helvetica findfont % Obtain prototype
Helvetica font 10 scalefont % Scale it to 10-unit size
setfont % Establish it as current font

ERRORS: invalidfont, stackunderflow, typecheck

SEE ALSO: currentfont, scalefont, makefont, findfont, selectfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setglobal* bool setglobal - LEVEL 2

sets the VM allocation mode: true denotes global, false denotes local. This
controls the VM region in which the values of new composite objects are to
be allocated. It applies to objects created implicitly by the scanner and
to those created explicitly by PostScript operators. Modifications to the
VM allocation mode are subject to save and restore. In a Display PostScript
system, which supports multiple execution contexts, the VM allocation mode
is maintained separately for each context. The standard error handlers in
errordict execute false setglobal, reverting to local VM allocation mode if
an error occurs.

ERRORS: stackunderflow, typecheck

SEE ALSO: currentglobal
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setgray* num setgray

- sets the color space to DeviceGray, then sets the current color parameter
in the graphics state to a gray shade corresponding to num. This must be a
number between 0 and 1, with 0 corresponding to black, 1 corresponding to
white, and intermediate values corresponding to intermediate shades of
gray. setgray establishes the color subsequently used to paint shapes, such
as lines, areas, and characters, on the current page. setgray does not give
a rangecheck error for a value outside the range 0 to 1; it substitutes the
nearest legal value.
Execution of this operator is not permitted in certain circumstances

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: currentgray, setcolorspace, setcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setgstate* gstate setgstate - LEVEL 2

replaces the current graphics state by the value of the gstate object. This
is a copying operation, so subsequent modifications to the value of gstate
will not affect the current graphics state or vice versa. Note that this is
a wholesale replacement of all components of the graphics state; in
particular, the current clipping path is replaced by the value in gstate,
not intersected with it.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: gstate, currentgstate, gsave, grestore
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*sethalftone* halftone sethalftone - LEVEL 2

establishes halftone as the halftone parameter in the graphics state. Once
established, the halftone dictionary should be treated as readonly. If the
halftone dictionary's HalftoneType value is out of bounds or is not
supported by the PostScript interpreter, a rangecheck error occurs. If a
required entry is missing or its value is of the wrong type, a typecheck
error occurs. sethalftone sets a graphics state parameter whose effect is
device dependent. It should not be used in a page description that is
intended to be device independent.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: currenthalftone, setscreen, setcolorscreen
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*sethalftonephase* x y sethalftonephase

- DPS sets the halftone phase parameters in the graphics state. x and y are
integers specifying the new halftone phase, interpreted in device space.
sethalftonephase sets a graphics state parameter whose effect is device
dependent. It should not be used in a page description that is intended to
be device independent.

ERRORS: stackunderflow, typecheck

SEE ALSO: currenthalftonephase
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*sethsbcolor* hue saturation brightness sethsbcolor

- sets the color space to DeviceRGB, then sets the current color parameter
in the graphics state to a color described by the parameters hue,
saturation, and brightness, each of which must be a number in the range 0
to 1. This establishes the color subsequently used to paint shapes, such as
lines, areas, and characters on the current page. Note that the color value
entered by sethsbcolor is immediately converted into the RGB model and used
with the DeviceRGB color space. HSB is not a color space in its own right,
merely a means for entering RGB color values in a different coordinate
system. sethsbcolor does not give a rangecheck error for a value outside
the range 0 to 1; it substitutes the nearest legal value.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: currenthsbcolor, setrgbcolor, setcolorspace, setcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setlinecap* int setlinecap

- sets the line cap parameter in the graphics state to int, which must be
one of the integers 0, 1, or 2. This establishes the shape to be put at the
ends of open subpaths painted by the stroke operator .

The integers select the following shapes:

   * Butt cap -the stroke is squared off at the endpoint of the path. There
     is no projection beyond the end of the path.
   * Round cap -a semicircular arc with diameter equal to the line width is
     drawn around the endpoint and filled in.
   * Projecting square cap -the stroke continues beyond the endpoint of the
     path for a distance equal to half the line width and is squared off.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: currentlinecap, setlinejoin, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setlinejoin* int setlinejoin

- sets the line join parameter in the graphics state to int, which must be
one of the integers 0, 1, or 2. This establishes the shape to be put at
corners in paths painted by the stroke operator .
The integers select the following shapes:

   * Miter join
     -the outer edges of the strokes for the two segments are extended
     until they meet at an angle, as in a picture frame. If the segments
     meet at too sharp an angle, a bevel join is used instead. This is
     controlled by the miter limit parameter established by setmiterlimit.

   * Round join
     -a circular arc with diameter equal to the line width is drawn around
     the point where the segments meet and is filled in, producing a
     rounded corner. stroke draws a full circle at this point. If path
     segments shorter than one-half the line width meet at sharp angles, an
     unintentional "wrong side" of this circle may appear.

   * Bevel join
     -the meeting path segments are finished with butt end caps (see
     setlinecap); then the resulting notch beyond the ends of the segments
     is filled with a triangle. Join styles are significant only at points
     where consecutive segments of a path connect at an angle. Segments
     that meet or intersect fortuitously receive no special treatment.
     Curved lines are actually rendered as sequences of straight line
     segments, and the current line join is applied to the "corners"
     between those segments. However, for typical values of the flatness
     parameter (see setflat), the corners are so shallow that the
     difference between join styles is not visible.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: currentlinejoin, setlinecap, stroke, setmiterlimit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setlinewidth* num setlinewidth

- sets the line width parameter in the graphics state to num. This controls
the thickness of lines rendered by subsequent execution of the stroke
operator. stroke paints all points whose perpendicular distance from the
current path in user space is less than or equal to one-half the absolute
value of num. The effect produced in device space depends on the current
transformation matrix (CTM) in effect at the time of the stroke.
If the CTM specifies scaling by different factors in the x and y
dimensions, the thickness of stroked lines in device space will vary
according to their orientation. A line width of zero is acceptable: It is
interpreted as the thinnest line that can be rendered at device
resolution-in other words, one device pixel wide. Some devices cannot
reproduce one-pixel lines, and on high-resolution devices, such lines are
nearly invisible.
Since the results of rendering such "zero-width" lines are device
dependent, their use is not recommended. The actual line width achieved by
stroke can differ from the requested width by as much as two device pixels,
depending on the positions of lines with respect to the pixel grid. One can
enable automatic stroke adjustment (by setstrokeadjust) to assure uniform
line width.

ERRORS: stackunderflow, typecheck

SEE ALSO: currentlinewidth, stroke, setstrokeadjust
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setmatrix* matrix setmatrix

- replaces the current transformation matrix (CTM) in the graphics state by
the value of matrix.
This establishes an arbitrary transformation from user space to device
space without reference to the former CTM. Except in device setup
procedures, use of setmatrix should be very rare. PostScript language
programs should ordinarily modify the CTM (by use of the translate, scale,
rotate, and concat operators) rather than replace it.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: currentmatrix, defaultmatrix, initmatrix, rotate, scale,
translate, concat
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setmiterlimit* num setmiterlimit

- sets the miter limit parameter in the graphics state to num, which must
be a number greater than or equal to 1. The miter limit controls the stroke
operator's treatment of corners when miter joins have been specified (see
setlinejoin).
When path segments connect at a sharp angle, a miter join results in a
spike that extends well beyond the connection point. The purpose of the
miter limit is to cut off such spikes when they become objectionably long.
At any given corner, the miter length is the distance from the point at
which the inner edges of the stroke intersect to the point at which the
outside edges of the strokes intersect-in other words, the diagonal length
of the miter.
This distance increases as the angle between the segments decreases. If the
ratio of the miter length to the line width exceeds the miter limit
parameter, stroke treats the corner with a bevel join instead of a miter
join. The ratio of miter length to line width is directly related to the
angle j between the segments in user space by the formula:
Examples of miter limit values are: 1.415 cuts off miters (converts them to
bevels) at angles less than 90 degrees, 2.0 cuts off miters at angles less
than 60 degrees, and 10.0 cuts off miters at angles less than 11 degrees.
The default value of the miter limit is 10. Setting the miter limit to 1
cuts off miters at all angles so that bevels are always produced even when
miters are specified.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: currentmiterlimit, stroke, setlinejoin
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setobjectformat* int setobjectformat - LEVEL 2

establishes the number representation to be used in binary object sequences
written by subsequent execution of printobject and writeobject. Output
produced by those operators will have a token type that identifies the
representation used.
The int operand is one of the following :

   * Disable binary encodings (see below).
   * High-order byte first, IEEE standard real format.
   * Low-order byte first, IEEE standard real format.
   * High-order byte first, native real format.
   * Low-order byte first, native real format.

Note that any of the latter four values specifies the number representation
only for output. Incoming binary encoded numbers use a representation that
is specified as part of each token (in the initial token type character).
The value 0 disables all binary encodings for both input and output. That
is, the PostScript language scanner treats all incoming characters as part
of the ASCII encoding, even if a token starts with a character code in the
range 128 to 159.
The printobject and writeobject operators are disabled; executing them will
cause an undefined error. This mode is provided for compatibility with
certain existing PostScript language programs. The initial value of this
parameter is implementation dependent. A program must execute
setobjectformat to generate output with a predictable number
representation.
Modifications to the object format parameter obey save and restore. In a
Display PostScript system, which supports multiple contexts, this parameter
is maintained seperately for each context.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: currentobjectformat, printobject, writeobject
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setoverprint* bool setoverprint - LEVEL 2

sets the overprint parameter in the graphics state. This rendering
parameter is used when the device is producing separations.
It specifies whether painting on one separation causes the corresponding
areas of other separations to be erased (false) or left unchanged (true).
setoverprint sets a graphics state parameter whose effect is device
dependent. It should not be used in a program that is intended to be device
independent.

ERRORS: stackunderflow, typecheck

SEE ALSO: currentoverprint, setcolorspace
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setpacking* bool setpacking - LEVEL 2

sets the array packing mode to the specified boolean value. This determines
the type of executable arrays subsequently created by the PostScript
language scanner. The value true selects packed arrays; false selects
ordinary arrays. The packing mode affects only the creation of procedures
by the scanner when it encounters program text bracketed by { and } during
interpretation of an executable file or string object, or during execution
of the token operator.
It does not affect the creation of literal arrays by the [ and ] operators
or by the array operator. Modifications to the array packing mode parameter
obey save and restore. In a Display PostScript system, which supports
multiple contexts, this parameter is maintained seperately for each
context.

EXAMPLE:
systemdict /setpacking known
{/savepacking currentpacking def true setpacking } if
....Arbitrary procedure definitions
.... systemdict /setpacking known {savepacking setpacking} if

This illustrates how to use packed arrays in a way that is compatible with
Level 1 and Level 2 interpreters. If the packed array facility is
available, the procedures represented by "arbitrary procedure definitions"
are defined as packed arrays; otherwise, they are defined as ordinary
arrays. This example is careful to preserve the array packing mode in
effect before its execution.

ERRORS: stackunderflow, typecheck

SEE ALSO: currentpacking, packedarray
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setpagedevice* dict setpagedevice - LEVEL 2

installs a new raster output device in the graphics state based on a
combination of the information in the current device and the information
found in the dictionary operand.
The dictionary is a container for communicating requests as property-value
pairs, which are logically passed by value and copied by the setpagedevice
machinery into internal storage.
Calls to setpagedevice are cumulative: information established in a
previous call to setpagedevice will persist unless overridden explicitly in
a subsequent call.
Therefore, there are no required keys in any particular call. This behavior
applies not only to the top-level dictionary, but recursively to the
sub-dictionaries Policies, InputAttributes, and OutputAttributes.
The result of executing setpagedevice is to instantiate a device, perform
the equivalent of initgraphics and erasepage, and install the device as an
implicit part of the graphics state. The effects of setpagedevice are
subject to save and restore, gsave and grestore, and setgstate.
setpagedevice can be used by system administrators to establish a default
state of the device by executing it as part of an unencapsulated job.
This default state persists until the next restart of the PostScript
interpreter. Some PostScript interpreter implementations store some of the
device values in persistent storage when setpagedevice is executed as part
of an unencapsulated job, making those parameters persist through
interpreter restart. setpagedevice reinitializes everything in the graphics
state, including parameters not affected by initgraphics. Device-dependent
rendering parameters, such as halftone, transfer functions, flatness, and
color rendering, are reset to built-in default values or to ones provided
in the Install procedure of the page device dictionary.
When the device in the current graphics state is not a page device, such as
after nulldevice has been executed, or when an interactive display device
is active, setpagedevice creates a new device from scratch before merging
in the parameters from dict. The properties of that device are specific to
each implementation.

ERRORS: configurationerror, typecheck, rangecheck, stackunderflow,
limitcheck, invalidaccess

SEE ALSO: currentpagedevice, nulldevice, gsave, grestore
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setpattern* pattern setpattern - LEVEL 2
comp1 ... compn pattern setpattern

- establishes the specified pattern as the current color in the graphics
state. Subsequent painting operations (except image and colorimage) use the
pattern to tile the areas of the page that are to be painted.
The pattern operand is a pattern dictionary and instantiated by
makepattern. setpattern is a convenience operator that sets the current
color space to Pattern, then sets the current "color" to a specific
pattern. Normally, setpattern establishes a Pattern color space whose
underlying color space parameter is the color space in effect prior to
execution of setpattern.
However, if the current color space is already a Pattern color space,
setpattern leaves it unchanged. setpattern then invokes setcolor with the
operands given to setpattern.
The behavior depends on the PaintType entry of the pattern dictionary:

   * If pattern defines a colored pattern (PaintType is 1), the color of
     the pattern is part of the pattern itself; there are no underlying
     color components.
     Therefore, the comp1 ... compn operands of setpattern should not be
     specified.

   * If pattern defines an uncolored pattern (PaintType is 2), the pattern
     itself has no color; the color must be specified separately by the
     operands comp1 ... compn, interpreted as components of the underlying
     color space of the Pattern color space.

If the Pattern color space does not have an underlying color space
parameter, a rangecheck error occurs.
setpattern is equivalent to:

currentcolorspace 0 get
/Pattern ne { [/Pattern currentcolorspace] setcolorspace} if setcolor

Execution of this operator is not permitted in certain circumstances.

ERRORS: rangecheck, stackunderflow, typecheck, undefined , invalidid

SEE ALSO: findresource, makepattern, setcolor, setcolorspace
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setrgbcolor* red green blue setrgbcolor

- sets the color space to DeviceRGB, then sets the current color parameter
in the graphics state to a color described by the parameters red, green,
and blue, each of which must be a number in the range 0 to 1. This
establishes the color subsequently used to paint shapes, such as lines,
areas, and characters, on the current page.
For an explanation of these color parameters. setrgbcolor does not give a
rangecheck for a value outside the range 0 to 1; it substitutes the nearest
legal value.

Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: currentrgbcolor, setgray, sethsbcolor, setcolorspace, setcolor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setscreen* frequency angle proc setscreen
- num1 num2 halftone setscreen

- sets the halftone parameter in the graphics state. The frequency operand
is a number that specifies the screen frequency, measured in halftone cells
per inch in device space.
The angle operand specifies the number of degrees by which the halftone
screen is to be rotated with respect to the device coordinate system.
The proc operand is a PostScript procedure defining the spot function,
which determines the order in which pixels within a halftone cell are
whitened to produce any desired shade of gray.
A rangecheck occurs if proc returns a result outside the range -1 to 1.
A limitcheck occurs if the size of the screen cell exceeds implementation
limits. setscreen sets the screens for all four color components (red,
green, blue, and gray) to the same value. setcolorscreen sets the screens
individually.
If the topmost operand is a halftone dictionary instead of a procedure,
setscreen performs the equivalent of sethalftone and discards the other two
operands. setscreen sets a graphics state parameter whose effect is device
dependent. It should not be used in a page description that is intended to
be device independent.
Execution of this operator is not permitted in certain circumstances.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: currentscreen, sethalftone
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setshared* bool setshared - LEVEL 2

has the same semantics as setglobal. This operator is defined for
compatibility with existing Display PostScript applications.

ERRORS: stackunderflow, typecheck

SEE ALSO: setglobal
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setstrokeadjust* bool setstrokeadjust - LEVEL 2

sets the stroke adjust parameter in the graphics state to bool. If bool is
true, automatic stroke adjustment will be performed during subsequent
execution of stroke and related operators, including strokepath .
If bool is false, stroke adjustment will not be performed. The initial
value of the stroke adjustment parameter is device dependent; typically it
is true for displays and false for printers.
It is set to false when a font's BuildChar or BuildGlyph procedure is
called, but the procedure can change it. It is not altered by initgraphics.

ERRORS: stackunderflow, typecheck

SEE ALSO: currentstrokeadjust, stroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setsystemparams* dict setsystemparams - LEVEL 2

attempts to set one or more system parameters whose keys and new values are
contained in the dict operand. The dictionary is merely a container for
key-value pairs; setsystemparams reads the information from the dictionary,
but does not retain the dictionary itself. System parameters whose keys are
not mentioned in dict are left unchanged.
Each parameter is identified by a key, which is always a name object. The
value is usually (but not necessarily) an integer. If the named system
parameter does not exist in the implementation, it is ignored. If the
specified value is the correct type, but is not achievable by the
implementation, the nearest achievable value is substituted without error
indication.
Some user parameters have default values that can be specified as system
parameters with the same names. Permission to alter system parameters is
controlled by a password. The dictionary must contain an entry named
Password whose value is the system parameter password (a string or
integer).
If the password is incorrect, setsystemparams executes an invalidaccess
error and does not alter any parameters. Some system parameters can be set
permanently in non-volatile storage that survives restarts of the
PostScript interpreter. This capability is implementation dependent. No
error occurs if parameters cannot be stored permanently.

EXAMPLE:
/MaxFontCache 500000 /MaxFontItem 7500 /Password (xxxx) >> setsystemparams

This attempts to set the MaxFontCache system parameter to 500000 and to set
the default value of the MaxFontItem user parameter to 7500.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: currentsystemparams, setuserparams, setdevparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*settransfer* proc settransfer

- sets the transfer function parameter in the graphics state. The proc
operand must be a procedure that can be called with a number in the range 0
to 1 (inclusive) on the operand stack and will return a number in the same
range. This procedure adjusts the values of the gray color component.
settransfer actually sets the transfer functions for all four color
components (red, green, blue, and gray) to the same value. setcolortransfer
sets the transfer functions individually. settransfer sets a graphics state
parameter whose effect is device dependent. It should not be used in a page
description that is intended to be device independent.
Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck

SEE ALSO: currenttransfer, setcolortransfer, sethalftone
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setucacheparams* mark blimit setucacheparams - LEVEL 2

sets user path cache parameters as specified by the integer objects above
the topmost mark on the stack, then removes all operands and the mark
object as if by cleartomark. The number of cache parameters is variable and
may increase in future versions of the PostScript interpreter.
If more operands are supplied to setucacheparams than are needed, the
topmost ones are used and the remainder ignored. If too few are supplied,
setucacheparams implicitly inserts default values between the mark and the
first supplied operand. blimit specifies the maximum number of bytes that
can be occupied by the reduced representation of a single path in the user
path cache.
Any reduced path larger than this is not saved in the cache. Changing
blimit does not disturb any paths that are already in the cache. A blimit
value that is too large is automatically reduced to the maximum permissible
value without error indication.
Modifications to the cache limit parameter obey save and restore. In a
Display PostScript system, which supports multiple contexts, this parameter
is maintained separately for each context. The parameter that
setucacheparams sets is the same as the MaxUPathItem user parameter set by
setuserparams.

ERRORS: rangecheck, typecheck, unmatchedmark

SEE ALSO: ucachestatus, setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setundercolorremoval* proc setundercolorremoval - LEVEL 2

sets the undercolor removal function parameter in the graphics state. The
proc operand must be a procedure that may be called with a number in the
range 0.0 to 1.0 (inclusive) on the operand stack and that will return a
number in the range -1.0 (to increase the color components) to +1.0 (to
decrease the color components).
This procedure computes the amount to subtract from the cyan, magenta, and
yellow components during conversion of color values from DeviceRGB color
space to DeviceCMYK. setundercolorremoval sets a graphics state parameter
whose effect is device dependent.
It should not be used in a page description that is intended to be device
independent.

Execution of this operator is not permitted in certain circumstances.

ERRORS: stackunderflow, typecheck, undefined

SEE ALSO: currentundercolorremoval, setblackgeneration
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setuserparams* dict setuserparams - LEVEL 2

attempts to set one or more user parameters whose keys and new values are
contained in the dict operand. The dictionary is merely a container for
key-value pairs; setuserparams reads the information from the dictionary,
but does not retain the dictionary itself.
User parameters whose keys are not mentioned in dict are left unchanged.
Each parameter is identified by a key, which is always a name object. The
value is usually (but not necessarily) an integer. If the named user
parameter does not exist in the implementation, it is ignored.
If the specified value is the correct type, but is not achievable by the
implementation, the nearest achievable value is substituted without error
indication.
Some user parameters have default values that are system parameters with
the same names. These defaults can be set by setsystemparams. User
parameters, unlike system parameters, can be set without supplying a
password. Alterations to user parameters are subject to save and restore.
In a Display PostScript system, which supports multiple execution contexts,
user parameters are maintained separately for each context.

EXAMPLE: /MaxFontItem 7500 >> setuserparams

This attempts to set the MaxFontItem user parameter to 7500.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: currentuserparams, setsystemparams, setdevparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*setvmthreshold* int setvmthreshold - LEVEL 2

sets the allocation threshold used to trigger garbage collections. If the
specified value is less than the implementation-dependent minimum value,
the threshold is set to that minimum value.
If the specified value is greater than the implementation-dependent maximum
value, the threshold is set to that maximum value. If the value specified
is -1, then the threshold is set to the implementationdependent default
value. All other negative values result in a rangecheck error.
Modifications to the allocation threshhold parameter obey save and restore.

In a Display PostScript system, which supports multiple contexts, this
parameter is maintained seperately for each context. The parameter
specified by setvmthreshold is the same as the VMThreshold user parameter
set by setuserparams.

ERRORS: rangecheck

SEE ALSO: setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*shareddict* - shareddict dict LEVEL 2

is the same dictionary as globaldict.
The name shareddict is defined for compatibility with existing Display
PostScript applications.

ERRORS: stackoverflow

SEE ALSO: globaldict
---------------------------------------------------------------------------
[Image]Troubleshooting index [Image]Postscript Index
---------------------------------------------------------------------------

SharedFontDirectory - SharedFontDirectory dict LEVEL 2

is the same dictionary as GlobalFontDirectory.
The name SharedFontDirectory is defined for compatibility with existing
Display PostScript applications.

ERRORS: stackoverflow

SEE ALSO: GlobalFontDirectory
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*show* string show

- paints the characters identified by the elements of string on the current
page starting at the current point, using the font face, size, and
orientation specified by the most recent setfont or selectfont.
The spacing from each character of the string to the next is determined by
the character's width, which is an (x, y) displacement that is part of the
character's definition. When it is finished, show adjusts the current point
in the graphics state by the sum of the widths of all the characters shown.
show requires that the current point initially be defined (for example, by
a moveto); otherwise, it executes the error nocurrentpoint.
If a character code would index beyond the end of the font's Encoding, or
the character mapping algorithm goes out of bounds in other ways, a
rangecheck error occurs.

ERRORS: invalidaccess, invalidfont, nocurrentpoint, rangecheck,
stackunderflow, typecheck

SEE ALSO: ashow, awidthshow, widthshow, kshow, cshow, xshow, yshow, xyshow,
charpath, moveto, setfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*showpage* - showpage

- % different in the NeXT implementation
This standard PostScript operator has no effect if the current device is a
window. transmits the current page to the raster output device, causing any
marks painted on the current page to appear. showpage then executes the
equivalent of erasepage (usually) and initgraphics (always) in preparation
for composing the next page.
If the device is a page device that was installed by setpagedevice (a Level
2 feature), the detailed behavior of showpage is determined by parameters
of the device dictionary .
The main actions are as follows:

   * showpage executes the EndPage procedure in the device dictionary. It
     passes two operands to EndPage, a page count and a reason indicator.
     The EndPage procedure is expected to return a boolean result. The
     default EndPage procedure always returns true.

   * If the result from EndPage is true, showpage transmits the page to the
     output device and executes the equivalent of erasepage. If the result
     is false, showpage does not transmit the page or execute an erasepage.

   * showpage executes the equivalent of initgraphics.

   * showpage executes the BeginPage procedure in the device dictionary,
     passing it a page-count operand.

For a device that produces physical output, such as printed paper, showpage
optionally produces multiple copies of each page as part of transmitting it
to the output device (step 2, above). The number of copies is specified in
one of two ways. If the device dictionary contains a NumCopies entry whose
value is a nonnegative integer, that is the number of copies.
Otherwise, showpage looks up the value of #copies in the environment of the
dictionary stack. The default value of #copies is 1, defined in userdict.
The #copies method for specifying number of copies is available in Level 1
implementations. The behavior of showpage is further modified by the
Collate, Duplex, and perhaps other entries in the device dictionary.
Whether or not the device is a page device, the precise manner in which the
current page is transmitted is device dependent. For certain devices, such
as displays, no action is required because the current page is visible
while it is being composed.

EXAMPLE:

/#copies 5 def showpage

This prints five copies of the current page, then erases the current page
and initializes the graphics state.

ERRORS: (none)

SEE ALSO: copypage, erasepage, setpagedevice
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*sin* angle sin real

returns the sine of angle, which is interpreted as an angle in degrees. The
result is a real.

ERRORS: stackunderflow, typecheck

SEE ALSO: cos, atan
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*sqrt* num sqrt real

returns the square root of num, which must be a non-negative number. The
result is a real.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: exp
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*srand* int srand

- initializes the random number generator with the seed int, which may be
any integer value. Executing srand with a particular value causes
subsequent invocations of rand to generate a reproducible sequence of
results.

ERRORS: stackunderflow, typecheck

SEE ALSO: rand, rrand
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stack* any1 ... anyn stack any1

.... anyn writes text representations of every object on the stack to the
standard output file, but leaves the stack unchanged. stack applies the =
operator to each element of the stack, starting with the topmost element.
See the = operator for a description of its effects.

ERRORS: (none)

SEE ALSO: pstack, =, ==, count
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stackoverflow* (error)

The operand stack has grown too large. Too many objects have been pushed on
the stack and not popped off. Before invoking this error, the interpreter
creates an array containing all elements of the operand stack (stored as if
by astore), resets the operand stack to empty, and pushes the array on the
operand stack.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stackunderflow* (error)

An attempt has been made to remove an object from the operand stack when it
is empty. This usually occurs because some operator did not have all of its
required operands on the stack.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*StandardEncoding - StandardEncoding array

pushes the standard encoding vector on the operand stack. This is a
256-element literal array object, indexed by character codes, whose values
are the character names for those codes. For an explanation of encoding
vectors. StandardEncoding is not an operator; it is a name in systemdict
associated with the array object. StandardEncoding is the Adobe standard
encoding vector used by most Roman text fonts, but not by special fonts,
such as Symbol. A new Roman text font having no unusual encoding
requirements should specify its Encoding entry to be the value of
StandardEncoding rather than define its own private array.

ERRORS: stackoverflow

SEE ALSO: ISOLatin1Encoding, findencoding
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*start* - start

- is executed by the PostScript interpreter when it starts up. After
setting up the VM (restoring it from a file, if appropriate), the
interpreter executes the name start in the context of the default
dictionary stack (systemdict, globaldict, and userdict).
The procedure associated with the name start is expected to provide
whatever top-level control is required-for example, for receiving page
descriptions, interacting with a user, or recovering from errors. The
precise definition of start depends on the environment in which the
PostScript interpreter is operating. It is not of any interest to ordinary
PostScript language programs and the effect of executing it explicitly is
undefined.

ERRORS: (none)

SEE ALSO: quit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*startjob* bool password startjob bool LEVEL 2

conditionally starts a new job whose execution may alter the initial VM for
subsequent jobs. The bool operand specifies whether the new job's side
effects are to be persistent. The behavior of startjob depends on whether
all three of the following conditions are true:

   * The current execution context supports job encapsulation-in other
     words, is under the control of a job server.

   * The password is correct-in other words, matches the StartJobPassword
     system parameter.

   * The current level of save nesting is not any deeper than it was at the
     time the current job started. If all three conditions are satisfied,
     startjob performs the following actions:

     1. Ends the current job-in other words, resets the stacks and, if the
     current job was encapsulated, executes a restore.
     2. Begins a new job. If the bool operand is true, the usual save at
     the beginning of the job is omitted, enabling the new job to make
     persistent alterations to the initial VM. If the bool operand is
     false, the usual save is performed, encapsulating the new job.
     3. Returns true on the operand stack.

If any of the three conditions is not satisfied, startjob pushes false on
the operand stack. It has no other effect. The password is a string that
authorizes switching between encapsulated and unencapsulated jobs. If
password is an integer, it is first converted to a string, as if by cvs. It
is compared to the StartJobPassword system parameter, which is established
by means of the setsystemparams operator .

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: exitserver, setsystemparams, save, restore
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*status* file status bool

string status pages bytes referenced created true (if found)
false (if not found)

If the operand is a file object, status returns true if it is still valid
(i.e., is associated with an open file), false otherwise. If the operand is
a string, status treats it as a file name according to the conventions of
"Named Files." If there is a file by that name, status pushes four integers
of status information followed by the value true; otherwise, it pushes
false.
The four integer values are:

   * pages
   * Storage space occupied by the file, in implementation dependent units.
   * bytes Length of file in characters.
   * referenced Date and time when the file was last referenced for reading
     or writing.

The interpretation of the value is according to the conventions of the
underlying operating system. The only assumption that a program can make is
that larger values indicate later times. created Date and time when the
information in the file was created.

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck

SEE ALSO: file, closefile, filenameforall
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*statusdict* - statusdict dict

pushes a product-dependent dictionary on the operand stack. statusdict is
not an operator; it is a name associated with the dictionary in systemdict.

The statusdict dictionary is in local VM and is writable. statusdict
contains product-dependent operators and other data whose names and values
vary from product to product, and sometimes from one version of a product
to another. Information in statusdict is associated with unique features of
a product that cannot be accessed in any standard way.
The contents of statusdict are not documented here, but in product-specific
documentation. In Level 1 implementations, statusdict includes operators to
select print-engine features, to set communication parameters, and to
control other aspects of the interpreter's operating environment. In Level
2, most of these functions have been subsumed by standard operators, such
as setpagedevice, setdevparams, and setsystemparams. statusdict is not
necessarily defined in all products. Any reference to statusdict in a
PostScript language program impairs the portability of that program.

ERRORS: stackoverflow, undefined
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stop* - stop

- terminates execution of the innermost, dynamically enclosing instance of
a stopped context, without regard to lexical relationship.
A stopped context is a procedure or other executable object invoked by the
stopped operator. stop pops the execution stack down to the level of the
stopped operator. The interpreter then pushes the boolean true on the
operand stack and resumes execution at the next object in normal sequence
after the stopped. It thus appears that stopped returned the value true,
whereas it normally returns false. stop does not affect the operand or
dictionary stacks.
Any objects pushed on those stacks during the execution of the stopped
context remain after the context is terminated. If stop is executed when
there is no enclosing stopped context, the interpreter prints an error
message and executes the built-in operator quit. This never occurs during
execution of ordinary user programs.

ERRORS: (none)

SEE ALSO: stopped, exit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stopped* any stopped bool

executes any, which is typically, but not necessarily, a procedure,
executable file, or executable string object. If any runs to completion
normally, stopped returns false on the operand stack.
If any terminates prematurely as a result of executing stop, stopped
returns true on the operand stack. Regardless of the outcome, the
interpreter resumes execution at the next object in normal sequence after
stopped.
This mechanism provides an effective way for a PostScript language program
to "catch" errors or other premature terminations, retain control, and
perhaps perform its own error recovery.

EXAMPLE:
{ ... } stopped {handleerror} if

If execution of the procedure {...} causes an error,
the default error-reporting procedure is invoked (by handleerror).
In any event, normal execution continues at the token following the if.

ERRORS: stackunderflow

SEE ALSO: stop store key value
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*store* store

- searches for key in each dictionary on the dictionary stack, starting
with the topmost (current) dictionary. If key is found in some dictionary,
store replaces its value by the value operand. If key is not found in any
dictionary on the dictionary stack, store creates a new entry with key and
value in the current dictionary. If the chosen dictionary is in global VM
and value is a composite object whose value is in local VM, an
invalidaccess error occurs .

EXAMPLE:

/abc 123 store /abc where { } {currentdict} ifelse
/abc 123 put

The two lines of the example have the same effect.

ERRORS: dictfull, invalidaccess, limitcheck, stackunderflow

SEE ALSO: def, put, where, load
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*string* int string string

creates a string of length int, each of whose elements is initialized with
the integer 0, and pushes this string on the operand stack.
The int operand must be a non-negative integer not greater than the maximum
allowable string length . The string is allocated in local or global VM
according to the current VM allocation mode.

ERRORS: limitcheck, rangecheck, stackunderflow, typecheck, VMerror

SEE ALSO: length, type
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stringwidth* string stringwidth wx wy

calculates the change in the current point that would occur if string were
given as the operand to show with the current font. wx and wy are computed
by adding together the width vectors of all the individual characters in
string and converting the result to user space.
They form a distance vector in x and y describing the width of the entire
string in user space. To obtain the character widths, stringwidth may
execute the descriptions of one or more of the characters in the current
font and may cause the results to be placed in the font cache.
However, stringwidth prevents the graphics operators that are executed from
painting anything into the current page. Note that the "width" of a string
is defined as movement of the current point. It has nothing to do with the
dimensions of the character outlines (see charpath and pathbbox).

ERRORS: invalidaccess, invalidfont, rangecheck, stackunderflow, typecheck

SEE ALSO: show, setfont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*stroke* - stroke

- paints a line following the current path and using the current color.
This line is centered on the path, has sides parallel to the path segments,
and has a width (thickness) given by the current line width parameter in
the graphics state (see setlinewidth).
stroke paints the joints between connected path segments with the current
line join (see setlinejoin) and the ends of open subpaths with the current
line cap (see setlinecap). The line is either solid or broken according to
the dash pattern established by setdash.
Uniform stroke width can be assured by enabling automatic stroke adjustment
(see setstrokeadjust). The parameters in the graphics state controlling
line rendition (line width, line join, and so on) are consulted at the time
stroke is executed.
Their values during the time the path is being constructed are irrelevant.
A degenerate subpath is a subpath consisting of a single point closed path
or two or more points at the same coordinates. If a subpath is degenerate,
stroke paints it only if round line caps have been specified, producing a
filled circle centered at that point.
If butt or projecting square line caps have been specified, stroke produces
no output, because the orientation of the caps would be indeterminate. If a
subpath consists of a single point non-closed path, no output is produced.
stroke implicitly performs a newpath after it has finished painting the
current path. To preserve the current path across a stroke operation, use
the sequence
gsave
stroke
grestore

ERRORS: limitcheck

SEE ALSO: setlinewidth, setlinejoin, setmiterlimit, setlinecap, setdash,
setstrokeadjust, ustroke
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*strokepath* - strokepath

- replaces the current path with one enclosing the shape that would result
if the stroke operator were applied to the current path. The path resulting
from strokepath is suitable as the implicit operand to fill, clip, or
pathbbox. In general, this path is not suitable for stroke, as it may
contain interior segments or disconnected subpaths produced by strokepath's
stroke to outline conversion process.

ERRORS: limitcheck

SEE ALSO: fill, clip, stroke, pathbbox, charpath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*sub* num1 num2 sub

difference returns the result of subtracting num2 from num1. If both
operands are integers and the result is within integer range, the result is
an integer. Otherwise, the result is a real.

ERRORS: stackunderflow, typecheck , undefinedresult

SEE ALSO: add, div, mul, idiv, mod
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*syntaxerror* (error)

The scanner has encountered program text that does not conform to the
PostScript language syntax rules. This can occur either during
interpretation of an executable file or string object, or during explicit
invocation of the token operator. Because the syntax of the PostScript
language is simple, the set of possible causes for a syntaxerror is very
small:

   * An opening string or procedure bracket, (, , ~, or {, is not matched
     by a corresponding closing bracket before the end of the file or
     string being interpreted.

   * A closing string or procedure bracket, ), >, ~>, or }, appears for
     which there is no previous matching opening bracket. o A character
     other than a hexadecimal digit or white space character appears within
     a hexadecimal string literal bracketed by ...>.

   * An encoding violation occurs in an ASCII base-85 string literal
     bracketed by ~...~>.

   * A binary token or binary object sequence has incorrect structure .
     Erroneous tokens, such as malformed numbers, do not produce a
     syntaxerror; such tokens are instead treated as name objects (often
     producing an undefined error when executed).
     Tokens that exceed implementation limits, such as names that are too
     long or numbers whose values are too large, produce a limitcheck .
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*systemdict* - systemdict dict

pushes the dictionary object systemdict on the operand stack . systemdict
is not an operator; it is a name in systemdict associated with the
dictionary object.

ERRORS: stackoverflow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*timeout* (error)

A time limit has been exceeded; that is, a PostScript language program has
executed for too long or has waited too long for some external event to
occur.

Execution of timeout is sandwiched between execution of two objects being
interpreted in normal sequence. Unlike most other errors, occurrence of a
timeout does not cause the object being executed to be pushed on the
operand stack nor does it disturb the operand stack in any way.

The PostScript language does not define any standard causes for timeout
errors. However, a PostScript interpreter running in a particular
environment may provide a set of timeout facilities appropriate for that
environment.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*token* file token any true (if found)
false (if not found)
string token post any true (if found)
false (if not found)

reads characters from file or string, interpreting them according to the
PostScript language syntax rules, until it has scanned and constructed an
entire object.

In the file case, token normally pushes the scanned object followed by
true. If token reaches end-of-file before encountering any characters
besides white space, it closes file and returns false.

In the string case, token normally pushes post (the substring of string
beyond the portion consumed by token), the scanned object, and true. If
token reaches the end of string before encountering any characters besides
white space, it simply returns false.

In either case, the any result is an ordinary object. It may be simple-an
integer, real, or name-or composite-a string bracketed by (...) or a
procedure bracketed by {...}. The object returned by token is the same as
the object that would be encountered by the interpreter if the file or
string were executed directly. However, token scans just a single object
and it always pushes that object on the operand stack rather than executing
it.

token consumes all characters of the token and sometimes the terminating
character as well. If the token is a name or a number followed by a
white-space character, token consumes the white-space character (only the
first one if there are several). If the token is terminated by a special
character that is part of the token-one of ), >, ], or }-token consumes
that character, but no following ones. If the token is terminated by a
special character that is part of the next token-one of /, (, <, [, or
{-token does not consume that character, but leaves it in the input
sequence. If the token is a binary token or a binary object sequence, token
consumes no additional characters.

EXAMPLE:

(15(St1) {1 2 add}) token -> ((St1) {1 2 add}) 15 true
((St1) {1 2 add}) token -> ( {1 2 add}) (St1) true
( {1 2 add}) token -> ( ) {1 2 add} true
( ) token -> false

ERRORS: invalidaccess, ioerror, limitcheck, stackoverflow, stackunderflow,
syntaxerror, typecheck, undefinedresult, VMerror

SEE ALSO: search, anchorsearch, read
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*transform* x y transform x' y'
x y matrix transform x' y'

With no matrix operand, transform transforms the user space coordinate (x,
y) by CTM to produce the corresponding device space coordinate (x', y'). If
the matrix operand is supplied, transform transforms (x, y) by matrix
rather than by CTM.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: itransform, dtransform, idtransform
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*translate* tx ty translate
- tx ty matrix translate matrix

With no matrix operand, translate builds a temporary matrix and
concatenates this matrix with the current transformation matrix (CTM).
Precisely, translate replaces the CTM by T x CTM. The effect of this is to
move the origin of the user coordinate system by tx units in the x
direction and ty units in the y direction relative to the former user
coordinate system. The sizes of the x and y units and the orientation of
the axes are unchanged.

If the matrix operand is supplied, translate replaces the value of matrix
by T and pushes the modified matrix back on the operand stack. In this
case, translate does not affect the CTM.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: rotate, scale, concat, setmatrix
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*true* - true true

pushes a boolean object whose value is true on the operand stack. true is
not an operator; it is a name in systemdict associated with the boolean
value true.

ERRORS: stackoverflow

SEE ALSO: false, and, or, not, xor
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*truncate* num1 truncate num2

truncates num1 toward zero by removing its fractional part. The type of the
result is the same as the type of the operand.

EXAMPLE:

3.2 truncate -> 3.0
-4.8 truncate -> -4.0
99 truncate -> 99

ERRORS: stackunderflow, typecheck

SEE ALSO: ceiling, floor, round, cvi
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*type* any type name

returns a name object that identifies the type of the object any. The
possible names that type can return are as follows:

     arraytype marktype
     booleantype nametype
     conditiontype nulltype
     dicttype operatortype
     filetype packedarraytype
     fonttype realtype
     gstatetype savetype
     integertype stringtype
     locktype

The name fonttype identifies an object of type fontID. It has nothing to do
with a font dictionary, which is identified by dicttype the same as any
other dictionary.

The returned name has the executable attribute. This makes it convenient to
perform type-dependent processing of an object simply by executing the name
returned by type in the context of a dictionary that defines all the type
names to have procedure values (this is how == works).

The set of types is subject to enlargement in future revisions of the
language. A program that examines the types of arbitrary objects should be
prepared to behave reasonably if type returns a name that is not in this
list.

ERRORS: stackunderflow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*typecheck* (error)

Some operand's type is different from what an operator expects. This is
probably the most frequent error encountered. It is often the result of
faulty stack manipulation, such as operands supplied in the wrong order or
procedures leaving results on the stack when they are not supposed to.

Certain operators require dictionaries or other composite objects as
operands, constructed according to specific rules (for example, pattern
dictionaries or user paths). A typecheck error can occur if the contents of
such objects are of incorrect type or are otherwise malformed.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*uappend* userpath uappend - LEVEL 2

interprets a user path definition and appends the result to the current
path in the graphics state.
If userpath is an ordinary user path (in other words, an array or packed
array whose length is at least 5),
uappend is equivalent to:

systemdict begin % Ensure standard operator meanings
cvx exec % Interpret userpath
end

If userpath is an encoded user path, uappend interprets it and performs the
encoded operations. It does not matter whether the userpath object is
literal or executable.

Note that uappend uses the standard definitions of all operator names
mentioned in the user path, unaffected by any name redefinition that may
have occurred.

A ucache appearing in userpath may or may not have an effect, depending on
the environment in which uappend is executed. If the current path is
initially empty and no path construction operators are executed after
uappend, a subsequent painting operator may access the user path cache.
Otherwise, it definitely will not. This is particularly useful in the case
of clip and viewclip.

uappend performs a temporary adjustment to the current transformation
matrix as part of its execution. This adjustment consists of rounding the
tx and ty components of the CTM to the nearest integer values.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: upath, ucache
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ucache* - ucache - LEVEL 2

notifies the PostScript interpreter that the enclosing user path is to be
retained in the cache if it is not already there. If present, this operator
must appear as the first element of a user path definition (before the
mandatory setbbox).

The ucache operator has no effect of its own when executed; if executed
outside a user path definition, it does nothing. It is useful only with a
user path painting operator, such as ufill or ustroke, that takes the user
path as an operand. If the user path is not already in the cache, the
painting operator performs the path construction operations specified in
the user path and places the results (referred to as the reduced path) in
the cache. If the user path is already present in the cache, the painting
operator does not interpret the user path, but rather obtains the reduced
path from the cache.

ERRORS: (none)

SEE ALSO: uappend, upath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ucachestatus* - ucachestatus mark bsize bmax rsize rmax blimit LEVEL 2

reports the current consumption and limit for two user path cache
resources: bytes of reduced path storage (bsize and bmax) and total number
of cached reduced paths (rsize and rmax).
It also reports the limit on the number of bytes occupied by a single
reduced path (blimit)-reduced paths that are larger than this are not
cached. All ucachestatus results except blimit are for information only. A
PostScript language program can change blimit (see setucacheparams).

The number of values pushed on the operand stack is variable. Future
versions of the PostScript interpreter may push additional values between
mark and bsize. The purpose of the mark is to delimit the values returned
by ucachestatus. This enables a program to determine how many values were
returned (by counttomark) and to discard any unused ones (by cleartomark).

The bsize, bmax, and blimit parameters reported by ucachestatus are the
same as the CurUPathCache and MaxUPathCache system parameters and
MaxUPathItem user parameter reported by currentsystemparams and
currentuserparams, respectively.

ERRORS: stackoverflow

SEE ALSO: setucacheparams, setsystemparams, setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ueofill* userpath ueofill - LEVEL 2

is similar to ufill, but does eofill instead of fill.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: eofill, ufill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ufill* userpath ufill - LEVEL 2

interprets a user path definition and fills the resulting path as if by
fill. The entire operation is effectively enclosed by gsave and grestore,
so ufill has no lasting effect on the graphics state.
ufill is equivalent to:

gsave newpath uappend fill grestore

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: fill, uappend, ueofill
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undef* dict key undef - LEVEL 2

removes key and its associated value from the dictionary dict. dict does
not need to be on the dictionary stack.
No error occurs if key is not present in dict.

If the value of dict is in local VM, the effect of undef can be undone by a
subsequent restore.
That is, if key was present in dict at the time of the matching save,
restore will reinstate key and its former value.
But if dict is in global VM, the effect of undef is permanent.

ERRORS: invalidaccess, stackunderflow, typecheck

SEE ALSO: def, put, undefinefont
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefined* (error)

A name used as a dictionary key in some context cannot be found. This
occurs if a name is looked up explicitly in a specified dictionary (get) or
in the current dictionary stack (load) and is not found. It also occurs if
an executable name is encountered by the interpreter and is not found in
any dictionary on the dictionary stack.

A few PostScript operators are disabled in certain contexts-for example, it
is illegal to execute image, or operators that specify colors or set
color-related parameters in the graphics state, after a setcachedevice or
setcachedevice2 in a BuildChar or BuildGlyph procedure. Attempting to
execute such disabled operators results in an undefined error.

SEE ALSO: known, where, load, exec, get
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefinedfilename* (error)

A file identified by a name string operand of file, run, deletefile, or
renamefile cannot be found or cannot be opened.
The undefinedfilename error also occurs if the special file %statementedit
or %lineedit is opened when the standard input file has reached
end-of-file.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefinedresource* (error) LEVEL 2

A named resource instance sought by findresource cannot be found; that is,
no such instance exists either in VM or in external storage. This error
arises only in the case of findresource with a defined resource category.
If the category itself is not defined, resource operators execute the
undefined error.

SEE ALSO: findresource
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefinedresult* (error)

A numeric computation would produce a meaningless result or one that cannot
be represented as a number. Possible causes include numeric overflow or
underflow, division by zero, or inverse transformation of a non-invertible
matrix. A large number of graphics and font operators can generate an
undefinedresult error if the CTM is not invertible (scaled by zero, for
instance).
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefinefont* key undefinefont - LEVEL 2

removes key and its associated value (a font dictionary) from the font
directory, reversing the effect of a previous definefont. undefinefont is a
special case of the undefineresource operator applied to the Font category.

ERRORS: stackunderflow, typecheck

SEE ALSO: definefont, undefineresource
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefineresource* key category undefineresource - LEVEL 2

removes the named resource instance identified by key from the specified
category.
This undoes the effect of a previous defineresource. If no such resource
instance exists in VM, undefineresource does nothing; no error occurs.
However, the resource category must exist, or else an undefined error
occurs.

Local and global resource definitions are maintained separately; the
precise effect of undefineresource depends on the current VM allocation
mode:

   * Local-undefineresource removes a local definition if there is one. If
     there is a global definition with the same key, undefineresource does
     not disturb it; the global definition, formerly obscured by the local
     one, now reappears.

   * Global-undefineresource removes a local definition, a global
     definition, or both.

Depending on the resource category, undefineresource may have other side
effects . However, it does not alter the resource instance in any way. If
the instance is still accessible (say, stored directly in some dictionary
or defined as a resource under another name), it can still be used in
whatever ways are appropriate. The object becomes a candidate for garbage
collection only if it is no longer accessible.

The effect of undefineresource is subject to normal VM semantics. In
particular, removal of a local resource instance can be undone by a
subsequent non-nested restore. In this case, the resource instance is not a
candidate for garbage collection.

undefineresource removes the resource instance definition from VM only. If
the resource instance also exists in external storage, it can still be
found by findresource, resourcestatus, and resourceforall.

ERRORS: stackunderflow, typecheck , undefined

SEE ALSO: defineresource, findresource, resourcestatus, resourceforall
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*undefineuserobject* index undefineuserobject - LEVEL 2

breaks the association between the non-negative integer index and an object
established by some previous execution of defineuserobject. It does so
simply by replacing the specified UserObjects array element by the null
object. This is equivalent to:

userdict /UserObjects get
exch null put

undefineuserobject does not take any other actions such as shrinking the
UserObjects array.
If index is not a valid index for the existing UserObjects array, a
rangecheck error occurs.

There is no need to execute undefineuserobject prior to executing a
defineuserobject that reuses the same index.
The purpose of undefineuserobject is to eliminate references to objects
that are no longer needed.
This may enable the garbage collector to reclaim such objects.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: defineuserobject, UserObjects
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*unmatchedmark* (error)

A mark object is sought on the operand stack by the ], >>, cleartomark,
counttomark, fork, setcacheparams, or setucacheparams operator, but none is
present.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*unregistered* (error)

An operator object has been executed for which the interpreter has no
built-in action. This represents an internal malfunction in the PostScript
interpreter and should not occur.
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*upath* bool upath userpath LEVEL 2

creates a new user path object that is equivalent to the current path in
the graphics state. upath creates a new executable array object of the
appropriate length and fills it with the operands and operators needed to
describe the current path. upath produces only an ordinary user path array,
not an encoded user path. It does not disturb the current path in the
graphics state.

The bool operand specifies whether the resulting user path is to include
ucache as its first element.

Since the current path's coordinates are maintained in device space, upath
transforms them to user space using the inverse of the CTM while
constructing the user path. Applying uappend to the resulting user path
will reproduce the same current path in the graphics state, but only if the
same CTM is in effect at that time.

upath is equivalent to:

[
exch {/ucache cvx} if
pathbbox /setbbox cvx
{/moveto cvx} {/lineto cvx} {/curveto cvx} {/closepath cvx} pathforall
] cvx

If charpath was used to construct any portion of the current path from a
font whose outlines are protected, upath is not allowed. Its execution will
produce an invalidaccess error (see charpath).

ERRORS: invalidaccess, stackunderflow, typecheck, VMerror

SEE ALSO: uappend, ucache, pathforall
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*userdict* - userdict dict

pushes the dictionary object userdict on the operand stack. userdict is not
an operator; it is a name in systemdict associated with the dictionary
object.

ERRORS: stackoverflow

SEE ALSO: systemdict, globaldict, errordict
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*UserObjects* - UserObjects array LEVEL 2

returns the current UserObjects array defined in userdict. UserObjects is
not an operator; it is simply a name associated with an array in userdict.
This array is created and managed by the operators defineuserobject,
undefineuserobject, and execuserobject. It defines a mapping from small
integers (used as array indices) to arbitrary objects (the elements of the
array).

The UserObjects entry in userdict is present only if defineuserobject has
been executed at least once by the current execution context or a context
that shares the same local VM. The length of the array depends on the index
operands of all previous executions of defineuserobject.

Note that defineuserobject, undefineuserobject, and execuserobject operate
on the value of UserObjects in userdict, without regard to the dictionaries
currently on the dictionary stack. Defining UserObjects in some other
dictionary on the dictionary stack changes the value returned by executing
the name object UserObjects, but does not alter the behavior of the user
object operators.

Although UserObjects is an ordinary array object, it should be manipulated
only by the user object operators. Improper direct alteration of
UserObjects can subsequently cause the user object operators to
malfunction.

ERRORS: stackoverflow, undefined

SEE ALSO: defineuserobject, undefineuserobject, execuserobject
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*usertime* - usertime int

returns the value of a clock that increments by 1 for every millisecond of
execution by the PostScript interpreter. The value has no defined meaning
in terms of calendar time or time of day; its only use is interval timing.
The accuracy and stability of the clock depends on the environment in which
the PostScript interpreter is running. As the time value becomes greater
than the largest integer allowed in the implementation, it wraps to the
smallest (most negative) integer.

In a Display PostScript system that supports multiple execution contexts,
the value returned by usertime reports execution time on behalf of the
current context only. A context that executes usertime can subsequently
execute with reduced efficiency, because in order to perform user time
accounting, the PostScript interpreter must perform an operating system
call whenever it switches control to and from that context. Therefore, one
should not execute usertime gratuitously.

ERRORS: stackoverflow

SEE ALSO: realtime
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ustroke* userpath ustroke
- userpath matrix ustroke - LEVEL 2

interprets a user path definition and strokes the resulting path as if by
stroke. The entire operation is effectively enclosed by gsave and grestore,
so ustroke has no lasting effect on the graphics state

In the first form (with no matrix operand), ustroke is equivalent to:

gsave newpath uappend stroke grestore

In the second form, ustroke concatenates matrix to the CTM after
interpreting userpath, but before executing stroke. The matrix applies to
the line width and the dash pattern, if any, but not to the path itself.
This form of ustroke is equivalent to:

gsave
newpath
exch uappend % Interpret userpath
concat % Concat matrix to CTM
stroke
grestore

The main use of the second form of ustroke is to compensate for variations
in line width and dash pattern that occur if the CTM has been scaled by
different amounts in x and y. This is accomplished by defining matrix to be
the inverse of the unequal scaling transformation.

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: stroke, uappend
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*ustrokepath* userpath ustrokepath - LEVEL 2
userpath matrix ustrokepath

- replaces the current path with one enclosing the shape that would result
if the ustroke operator were applied to the same operands. The path
resulting from ustrokepath is suitable as the implicit operand to a
subsequent fill, clip, or pathbbox. In general, this path is not suitable
for stroke, as it may contain interior segments or disconnected subpaths
produced by ustrokepath's stroke to outline conversion process.

In the first form, ustrokepath is equivalent to:

newpath uappend strokepath

In the second form, ustrokepath is equivalent to:

newpath
exch uappend % Interpret userpath
matrix currentmatrix % Save CTM
exch concat % Concat matrix to CTM
strokepath % Compute outline of stroke
setmatrix % Restore original CTM

ERRORS: invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck

SEE ALSO: ustroke, strokepath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*version* - version

string returns a string that identifies the version of the PostScript
interpreter being used. This identification does not include information
about the language features or the hardware or operating system environment
in which the PostScript interpreter is running.

ERRORS: stackoverflow

SEE ALSO: languagelevel, product, revision, serialnumber
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*viewclip* - viewclip

- DPS replaces the current view clipping path by a copy of the current path
in the graphics state. The inside of the current path is determined by the
normal non-zero winding number rule. viewclip implicitly closes any open
subpaths of the view clipping path. After setting the view clip, viewclip
resets the current path to empty, as if by newpath. viewclip is similar to
clip in that it causes subsequent painting operations to affect only those
areas of the current page that lie inside the new view clipping path.
However, it differs from clip in three important respects:

   * The view clipping path is independent of the current clipping path,
     which is unaffected. A subsequent clippath returns the current
     clipping path, uninfluenced by the additional clipping imposed by the
     view clip.

   * viewclip entirely replaces the current view clipping path, whereas
     clip computes the intersection of the current and new clipping paths.

   * viewclip performs an implicit newpath at the end of its execution,
     whereas clip leaves the current path unchanged.

The view clipping path is independent of the graphics state; it is
maintained separately for each execution context. Modifications to the view
clipping path obey save and restore. The view clipping path can be
described by a user path. This is accomplished by: newpath userpath uappend
viewclip If userpath specifies ucache, this operation may take advantage of
information in the user path cache.

ERRORS: limitcheck

SEE ALSO: initviewclip, viewclippath, clip
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*viewclippath* - viewclippath - DPS

replaces the current path by a copy of the current view clipping path. If
no view clipping path exists, it replaces the current path by one that
exactly corresponds to the bounding rectangle of the imageable area of the
output device.

EXAMPLE:
initviewclip viewclippath pathbbox

If the current device is a window device, this returns the bounding box of
the window.

ERRORS: (none)

SEE ALSO: viewclip, initviewclip, clippath
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*VMerror* (error)

An error has occurred in the virtual memory (VM) machinery. The most likely
problems are:

   * An attempt to create a new composite object (string, array,
     dictionary, or packed array) would exhaust VM resources. Either the
     program's requirements exceed available capacity or, more likely, the
     program has failed to use the save/restore facility appropriately.

   * The interpreter has attempted to perform an operation that should be
     impossible due to access restrictions (for example, store into
     systemdict, which is read-only). This represents an internal error in
     the interpreter. The default handler for this error, unlike those for
     all other errors, does not snapshot the stacks.

---------------------------------------------------------------------------
---------------------------------------------------------------------------

*vmreclaim* int vmreclaim - LEVEL 2

controls the garbage collection machinery as specified by int:

     -2 Disable automatic collection in both local and global VM.

     -1 Disable automatic collection in local VM.

     0 Enable automatic collection.

     1 Perform immediate collection in local VM.

     2 Perform immediate collection in local and global VM.

This can take a long time, because it must consult the local VMs of all
execution contexts. Garbage collection causes the memory occupied by the
values of inaccessible objects to be reclaimed and made available for
reuse. It does not have any effects that are visible to the PostScript
language program. There is normally no need to execute the vmreclaim
operator, because garbage collection is invoked automatically when
necessary. However, there are a few situations in which this operator may
be useful: o In an interactive application that is temporarily idle, the
idle time can be put to good use by invoking an immediate garbage
collection. This defers the need to perform an automatic collection
subsequently. In a context that is under the control of a job server.

garbage collection is invoked automatically between jobs.

   * When monitoring the VM consumption of a program, one must invoke
     garbage
     collection before executing vmstatus to obtain meaningful results.

   * When measuring the execution time of a program, one must disable
     automatic
     garbage collection to obtain repeatable results. The negative values
     that disable
     garbage collection apply only to the current execution context; that
     is, they do
     not prevent collection from occurring during execution of other
     contexts.

Note that disabling garbage collection for too long may eventually cause a
program to run out of memory and fail with a VMerror. Executing vmreclaim
with an operand of 0, -1, or -2 has the same effect as setting the
VMReclaim user parameter to the same value by means of setuserparams.

ERRORS: rangecheck, stackunderflow, typecheck

SEE ALSO: setvmthreshold, setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*vmstatus* - vmstatus
level used maximum returns three integers describing the state of the
PostScript interpreter's virtual memory (VM).

level is the current depth of save nesting-in other words, the number of
saves that haven't been matched by a restore. used and maximum measure VM
resources in units of 8-bit bytes; used is the number of bytes currently in
use and maximum is the maximum available capacity. VM consumption is
monitored separately for local and global VM.
The used and maximum values apply to either local or global VM according to
the current VM allocation mode (see setglobal).
The used value is meaningful only immediately after a garbage collection
has taken place (see vmreclaim). At other times, it may be too large
because it includes memory occupied by objects that have become
inaccessible, but have not yet been reclaimed.
The maximum value is an estimate of the maximum size to which the current
VM (local or global) could grow, assuming that all other uses of available
memory remain constant. Because that assumption is never valid in practice,
there is some uncertainty about the maximum value.
Also, in some environments (workstations, for instance), the PostScript
interpreter can obtain more memory from the operating system. In this case,
memory is essentially inexhaustible and the maximum value is meaningless-it
is an extremely large number.

ERRORS: stackoverflow

SEE ALSO: setuserparams
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*wait* lock condition wait - DPS

releases lock, waits for condition to be notified by some other execution

context, and finally reacquires lock. The lock must originally have been
acquired by the current context, which means that wait can be invoked only
within the execution of a monitor that references the same lock .

If lock is initially held by some other context or is not held by any
context, wait executes an invalidcontext error. On the other hand, during
the wait for condition, the lock can be acquired by some other context.
After condition is notified, wait will wait an arbitrary length of time to
reacquire lock.

If the current context has previously executed a save not yet matched by a
restore, wait executes invalidcontext unless both lock and condition are in
global VM. The latter case is permitted under the assumption that the wait
is synchronizing with some context whose local VM is different from that of
the current context.

ERRORS: invalidcontext, stackunderflow, typecheck

SEE ALSO: condition, lock, monitor, notify
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*wcheck* array wcheck bool
packedarray wcheck false
dict wcheck bool
file wcheck bool
string wcheck bool

tests whether the operand's access permits its value to be written
explicitly by PostScript operators.
wcheck returns true if the operand's access is unlimited, false otherwise.

ERRORS: stackunderflow, typecheck

SEE ALSO: rcheck, readonly, executeonly, noaccess
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*where* key where dict true (if found)
false (if not found)

determines which dictionary on the dictionary stack, if any, contains an
entry whose key is key. where searches for key in each dictionary on the
dictionary stack, starting with the topmost (current) dictionary. If key is
found in some dictionary, where returns that dictionary object and the
boolean true. If key is not found in any dictionary on the dictionary
stack, where simply returns false.

ERRORS: invalidaccess, stackoverflow, stackunderflow, typecheck

SEE ALSO: known, load, get
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*widthshow* cx cy char string widthshow

- paints the characters of string in a manner similar to show. But while
doing so, widthshow adjusts the width of each occurrence of the character
char by adding cx to its x width and cy to its y width, thus modifying the
spacing between it and the next character. char is an integer used as a
character code. This operator enables fitting a string of text to a
specific width by adjusting the width of all occurrences of some specific
character, such as the space character.

For a base font, char is simply an integer in the range 0 to 255 compared
to successive elements of string. For a composite font, char is compared to
an integer computed from the font mapping algorithm. The font number, f,
and character code, c, that are selected by the font mapping algorithm are
combined into a single integer according to the FMapType of the immediate
parent of the selected base font.
For FMapType values of 4 and 5, the integer value is (f x 128) + c;
for all other FMapType values, it is (f x 256) + c.

EXAMPLE:
/Helvetica findfont 12 scalefont setfont
14 60 moveto (Normal spacing) show
14 46 moveto 6 0 8#040 (Wide word spacing) widthshow

ERRORS: invalidaccess, invalidfont, nocurrentpoint, stackunderflow,
typecheck, rangecheck

SEE ALSO: show, ashow, awidthshow, kshow, xshow, yshow, xyshow, stringwidth

---------------------------------------------------------------------------
---------------------------------------------------------------------------

*write* file int write

- appends a single character to the output file file. The int operand
should be an integer in the range 0 to 255 representing a character code
(values outside this range are reduced modulo 256). If file is not a valid
output file or some error is encountered, write executes ioerror.

As is the case for all operators that write to files, the output produced
by write may accumulate in a buffer instead of being transmitted
immediately. To ensure immediate transmission, a flushfile is required.

ERRORS: invalidaccess, ioerror, stackunderflow, typecheck

SEE ALSO: read, writehexstring, writestring, file
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*writehexstring* file string writehexstring

- writes all of the characters of string to file as hexadecimal digits.

For each element of string (an integer in the range 0 to 255),
writehexstring appends a two-digit hexadecimal number composed of the
characters 0 through 9 and a through f.

(%stdout)(w) file (abz) writehexstring
writes the six characters 61627a to the standard output file.

As is the case for all operators that write to files, the output produced
by writehexstring may accumulate in a buffer instead of being transmitted
immediately. To ensure immediate transmission, a flushfile is required.

ERRORS: invalidaccess, ioerror, stackunderflow, typecheck

SEE ALSO: readhexstring, write, writestring, file, filter
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*writeobject* file obj tag writeobject - LEVEL 2

writes a binary object sequence to file. Except for taking an explicit file
operand, writeobject is identical to printobject in all respects.

As is the case for all operators that write to files, the output produced
by writeobject may accumulate in a buffer instead of being transmitted
immediately. To ensure immediate transmission, a flushfile is required.

ERRORS: invalidaccess, ioerror, limitcheck, rangecheck, stackunderflow,
typecheck , undefined

SEE ALSO: printobject, setobjectformat
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*writestring* file string writestring -

writes the characters of string to the output file file. writestring does
not append a newline character or interpret the value of string, which can
contain arbitrary binary data. However, the communication channel may usurp
certain control characters or impose other restrictions.

As is the case for all operators that write to files, the output produced
by writestring may accumulate in a buffer instead of being transmitted
immediately. To ensure immediate transmission, a flushfile is required.

ERRORS: invalidaccess, ioerror, stackunderflow, typecheck

SEE ALSO: readstring, write, writehexstring, file, filter
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*wtranslation* - wtranslation x y DPS

returns the translation from the window origin to the PostScript
interpreter's device space origin. The integers x and y are the amounts
that need to be added to a window system coordinate to produce the device
space coordinate for the same position.
That coordinate may in turn be transformed to user space by the itransform
operator. Window system and device space coordinates always correspond in
resolution and orientation; they differ only in the positions of their
origins. The translation from one origin to the other may change as windows
are moved and resized. The precise behavior is window system specific.

ERRORS: stackoverflow
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*xcheck* any xcheck bool

tests whether the operand has the executable or literal attribute,
returning true if it is executable or false if it is literal. This has
nothing to do with the object's access attribute-for example, execute-only.

ERRORS: stackunderflow

SEE ALSO: cvx, cvlit
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*xor* bool1 bool2 xor bool3
int1 int2 xor int3

If the operands are booleans, xor pushes their logical "exclusive or." If
the operands are integers, xor pushes the bitwise "exclusive or" of their
binary representations.

% A complete truth table
true true xor -> false
true false xor -> true
false true xor -> true
false false xor -> false
7 3 xor -> 4 12 3 xor -> 15

ERRORS: stackunderflow, typecheck

SEE ALSO: or, and, not
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*xshow* string numarray xshow
- string numstring xshow - LEVEL 2

is similar to xyshow. However, for each character shown, xshow extracts
only one number from numarray or numstring. It uses that number as the x
displacement and the value zero as the y displacement. In all other
respects, xshow behaves the same as xyshow.

ERRORS: invalidaccess, invalidfont, nocurrentpoint, rangecheck,
stackunderflow, typecheck

SEE ALSO: xyshow, show
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*xyshow* string numarray xyshow - string numstring xyshow - LEVEL 2

paints successive characters of string in a manner similar to show. After
painting each character, it extracts two successive numbers from the array
numarray or the encoded number string numstring. These two numbers,
interpreted in user space, determine the position of the origin of the next
character relative to the origin of the character just shown. The first
number is the x displacement and the second number is the y displacement.
In other words, the two numbers override the character's normal width. If
numarray or numstring is exhausted before all the characters of string have
been shown, a rangecheck error will occur.

ERRORS: invalidaccess, invalidfont, nocurrentpoint, rangecheck,
stackunderflow, typecheck

SEE ALSO: xshow, yshow, show
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*yield* - yield - DPS

suspends the current execution context until all other contexts have had a
chance to execute. This should not be used as a synchronization primitive,
because there is no way to predict how much execution the other contexts
will be able to accomplish. The purpose of yield is to break up
long-running computations that might lock out other contexts.

ERRORS: (none)
---------------------------------------------------------------------------
---------------------------------------------------------------------------

*yshow* string numarray yshow - string numstring yshow - LEVEL 2

is similar to xyshow. However, for each character shown, yshow extracts
only one number from numarray or numstring. It uses that number as the y
displacement and the value zero as the x displacement. In all other
respects, it behaves the same as xyshow.

ERRORS: invalidaccess, invalidfont, nocurrentpoint, rangecheck,
stackunderflow, typecheck

SEE ALSO: xyshow, show
---------------------------------------------------------------------------
---------------------------------------------------------------------------