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