1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 2"http://www.w3.org/TR/html4/loose.dtd"> 3<html> 4<head> 5<title>Ghostscript and the PostScript language</title> 6<!-- $Id: Language.htm,v 1.98 2005/10/20 19:46:23 ray Exp $ --> 7<!-- Originally: language.txt --> 8<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 9</head> 10 11<body> 12<!-- [1.0 begin visible header] ============================================ --> 13 14<!-- [1.1 begin headline] ================================================== --> 15 16<h1>Ghostscript and the PostScript language</h1> 17 18<!-- [1.1 end headline] ==================================================== --> 19 20<!-- [1.2 begin table of contents] ========================================= --> 21 22<h2>Table of contents</h2> 23 24<blockquote><ul> 25<li><a href="#Capabilities">Ghostscript's capabilities in relation to PostScript</a> 26<li><a href="#Implementation_limits">Implementation limits</a> 27<ul> 28<li><a href="#Architectural_limits">Architectural limits</a> 29<li><a href="#Typical_memory_limits">Typical memory limits in LanguageLevel 1</a> 30<li><a href="#VM_consumption">Other differences in VM consumption</a> 31</ul> 32<li><a href="#Additional_operators">Additional operators in Ghostscript</a> 33<ul> 34<li><a href="#Graphics_and_text">Graphics and text operators</a> 35<ul> 36<li><a href="#Transparency">Transparency</a> 37<ul> 38<li><a href="#Transparency_graphics_state_operators">Graphics state operators</a> 39<li><a href="#Transparency_rendering_stack_operators">Rendering stack operators</a> 40<li><a href="#Transparency_ImageType">New ImageType</a> 41</ul> 42<li><a href="#Graphics_state">Other graphics state operators</a> 43<li><a href="#Path">Path operators</a> 44<li><a href="#Painting">Painting operators</a> 45<li><a href="#Character">Character operators</a> 46</ul> 47<li><a href="#Other">Other operators</a> 48<ul> 49<li><a href="#Mathematical">Mathematical operators</a> 50<li><a href="#Dictionary">Dictionary operators</a> 51<li><a href="#String">String and name operators</a> 52<li><a href="#Relational">Relational operators</a> 53<li><a href="#File">File operators</a> 54<li><a href="#Virtual_memory">Virtual memory operators</a> 55<li><a href="#Miscellaneous">Miscellaneous operators</a> 56<li><a href="#Device">Device operators</a> 57</ul> 58</ul> 59<li><a href="#Filters">Filters</a> 60<ul> 61<li><a href="#Standard_filters">Standard filters</a> 62<li><a href="#Non_standard_filters">Non-standard filters</a> 63<li><a href="#Unstable_filters">Unstable filters</a> 64</ul> 65<li><a href="#Device_parameters">Device parameters</a> 66<li><a href="#User_parameters">User parameters</a> 67<li><a href="#Miscellaneous_additions">Miscellaneous additions</a> 68<ul> 69<li><a href="#Extended_semantics_of_run">Extended semantics of 'run'</a> 70<li><a href="#DecodingResources">Decoding resources</a> 71<li><a href="#CIDDecodingResources">CIDDecoding resources</a> 72<li><a href="#GlyphNames2Unicode">GlyphNames2Unicode</a> 73<li><a href="#MultipleResourceDirectories">Multiple Resource directories</a> 74</ul> 75</ul></blockquote> 76 77<!-- [1.2 end table of contents] =========================================== --> 78 79<!-- [1.3 begin hint] ====================================================== --> 80 81<p>For other information, see the <a href="Readme.htm">Ghostscript 82overview</a>. 83 84<!-- [1.3 end hint] ======================================================== --> 85 86<hr> 87 88<!-- [1.0 end visible header] ============================================== --> 89 90<!-- [2.0 begin contents] ================================================== --> 91 92<h2><a name="Capabilities"></a>Ghostscript's capabilities in relation to PostScript</h2> 93 94<p> 95The Ghostscript interpreter, except as noted below, is intended to execute 96properly any source program written in the (LanguageLevel 3) 97<b>PostScript</b> language as defined in the <cite>PostScript 98Language Reference, Third Edition</cite> (ISBN 0-201-37922-8) published by 99Addison-Wesley in mid-1999. However, the interpreter is configurable in 100ways that can restrict it to various subsets of this language. 101Specifically, the base interpreter accepts the Level 1 subset of the 102PostScript language, as defined in the first edition of the <cite>PostScript 103Language Reference Manual</cite> (ISBN 0-201-10174-2) Addison-Wesley 1985, 104plus the file system, version 25.0 language, and miscellaneous additions 105listed in sections A.1.6, A.1.7, and A.1.8 of the Second Edition 106respectively, including allowing a string operand for the 107"<b><tt>status</tt></b>" operator. The base interpreter may be configured 108(see the <a href="Make.htm">documentation on building Ghostscript</a> for 109how to configure it) by adding any combination of the following: 110 111<ul> 112<li>The ability to process PostScript Type 1 fonts. This facility is 113normally included in the interpreter. 114 115<li>The CMYK color extensions listed in section A.1.4 of the Second Edition 116(including <b><tt>colorimage</tt></b>). These facilities are available 117only if the <b><tt>color</tt></b>, <b><tt>dps</tt></b>, or 118<b><tt>level2</tt></b> feature was selected when Ghostscript was built. 119 120<li>The Display PostScript extensions listed in section A.1.3 of the Second 121Edition, but excluding the operators listed in section A.1.2. These 122facilities are available only if the <b><tt>dps</tt></b> feature or the 123<b><tt>level2</tt></b> feature was selected when Ghostscript was built. 124 125<li>The composite font extensions listed in section A.1.5 of the Second 126Edition, and the ability to handle Type 0 fonts. These facilities are 127available only if the <b><tt>compfont</tt></b> feature or the 128<b><tt>level2</tt></b> feature was selected when Ghostscript was built. 129 130<li>The ability to load TrueType fonts and to handle PostScript Type 42 131(encapsulated TrueType) fonts. These facilities are available only if the 132<b><tt>ttfont</tt></b> feature was selected when Ghostscript was built. 133 134<li>The PostScript Level 2 "filter" facilities except the 135<b><tt>DCTEncode</tt></b> and <b><tt>DCTDecode</tt></b> filters. These 136facilities are available only if the <b><tt>filter</tt></b>, 137<b><tt>dps</tt></b>, or <b><tt>level2</tt></b> feature was selected when 138Ghostscript was built. 139 140<li>The PostScript Level 2 <b><tt>DCTEncode</tt></b> and 141<b><tt>DCTDecode</tt></b> filters. These facilities are available only if 142the <b><tt>dct</tt></b> or <b><tt>level2</tt></b> feature was selected when 143Ghostscript was built. 144 145<li>All the other PostScript Level 2 operators and facilities listed in 146section A.1.1 of the Second Edition and not listed in any of the other 147A.1.n sections. These facilities are available only if the 148<b><tt>level2</tt></b> feature was selected when Ghostscript was built. 149 150<li>All PostScript LanguageLevel 3 operators and facilities listed in the 151Third Edition, except as noted below. These facilities are available only 152if the <b><tt>psl3</tt></b> feature was selected when Ghostscript was built. 153 154<li>The ability to recognize DOS EPSF files and process only the PostScript 155part, ignoring bitmap previews or other information. This facility is 156available only if the <b><tt>epsf</tt></b> feature was selected when 157Ghostscript was built. 158</ul> 159 160<p> 161Ghostscript currently does not implement the following PostScript 162LanguageLevel 3 facilities: 163 164<ul> 165<li>Native <b><tt>Separation</tt></b> and <b><tt>DeviceN</tt></b> color 166spaces -- the alternate space is always used. 167 168<li>Settable <b><tt>ProcessColorModel</tt></b> for page devices, except for 169a very few special devices. 170 171<li><b><tt>IODevice</tt></b>s other than <b><tt>%stdin</tt></b>, 172<b><tt>%stdout</tt></b>, <b><tt>%stderr</tt></b>, <b><tt>%lineedit</tt></b>, 173<b><tt>%statementedit</tt></b>, <b><tt>%os%</tt></b>, and (if configured) 174<b><tt>%pipe%</tt></b> and <b><tt>%disk0%</tt></b> through <b><tt>%disk0%</tt></b>. 175</ul> 176 177<p> 178Ghostscript can also interpret files in the Portable Document Format (PDF) 1791.3 format defined in the <a 180href="http://partners.adobe.com/asn/developer/PDFS/TN/PLRM.pdf"><em>Portable 181Document Format Reference Manual</em> Version 1.3</a> of March 11, 1999, 182distributed by <a href="http://www.adobe.com/">Adobe Systems 183Incorporated</a>, except as noted below. This facility is available only if 184the <b><tt>pdf</tt></b> feature was selected when Ghostscript was built. 185 186<p> 187Ghostscript currently does not implement the following PDF 1.3 facilities: 188 189<ul> 190<li>Native <b><tt>Separation</tt></b> and <b><tt>DeviceN</tt></b> color 191spaces, as noted above for PostScript. 192 193<li>Native <b><tt>ICCBased</tt></b> color spaces -- these too always use the 194alternate space. 195</ul> 196 197<p> 198Ghostscript also includes a number of 199<a href="#Additional_operators">additional operators</a> defined below that 200are not in the PostScript language defined by Adobe. 201 202<hr> 203 204<h2><a name="Implementation_limits"></a>Implementation limits</h2> 205 206<p> 207The implementation limits show here correspond to those in Tables B.1 and 208B.2 of the Second and Third Editions, which describe the quantities fully. 209Where Ghostscript's limits are different from those of Adobe's 210implementations (as shown in the Third Edition), Adobe's limits are also 211shown. 212 213<h3><a name="Architectural_limits"></a>Architectural limits</h3> 214 215<blockquote><table cellpadding=0 cellspacing=0> 216<tr><th colspan=7 bgcolor="#CCCC00"><hr><font size="+1">Architectural limits (corresponds to Adobe table B.1)</font><hr> 217<tr valign=bottom> 218 <th align=left>Quantity 219 <td> 220 <th align=left>Limit 221 <td> 222 <th align=left>Type 223 <td> 224 <th align=left>Adobe 225<tr> <td colspan=7><hr> 226<tr valign=top> <td>integer 227 <td> 228 <td>32-bit 229 <td> 230 <td>twos complement integer 231 <td> 232 <td> 233<tr valign=top> <td>real 234 <td> 235 <td>single-precision 236 <td> 237 <td>IEEE float 238 <td> 239 <td> 240<tr valign=top> <td>array 241 <td> 242 <td>65535 243 <td> 244 <td>elements 245 <td> 246 <td> 247<tr valign=top> <td>dictionary 248 <td> 249 <td>65534 250 <td> 251 <td>elements 252 <td> 253 <td>65535 254<tr valign=top> <td>string 255 <td> 256 <td>65535 257 <td> 258 <td>characters 259 <td> 260 <td> 261<tr valign=top> <td>name 262 <td> 263 <td>16383 264 <td> 265 <td>characters 266 <td> 267 <td>127 268<tr valign=top> <td>filename 269 <td> 270 <td>128* 271 <td> 272 <td>characters 273 <td> 274 <td> 275<tr valign=top> <td><b><tt>save</tt></b> level 276 <td> 277 <td>none 278 <td> 279 <td>(capacity of memory) 280 <td> 281 <td>15 282<tr valign=top> <td><b><tt>gsave</tt></b> level 283 <td> 284 <td>none 285 <td> 286 <td>(capacity of memory) 287 <td> 288 <td>13 289</table></blockquote> 290 291<p> 292* The limit on the length of a file name is 128 characters if the name 293starts with a %...% IODevice designation, or 124 characters if it does not. 294 295<h3><a name="Typical_memory_limits"></a>Typical memory limits in LanguageLevel 1</h3> 296 297<blockquote><table cellpadding=0 cellspacing=0> 298 299<tr><th colspan=7 bgcolor="#CCCC00"><hr><font size="+1">Memory limits (corresponds to Adobe table B.2)</font><hr> 300<tr valign=bottom> 301 <th align=left>Quantity 302 <td> 303 <th align=left>Limit 304 <td> 305 <th align=left>Type 306 <td> 307 <th align=left>Adobe 308<tr> <td colspan=7><hr> 309<tr valign=top> <td><b><tt>userdict</tt></b> 310 <td> 311 <td>200 312 <td> 313 <td> 314 <td> 315 <td> 316<tr valign=top> <td><b><tt>FontDirectory</tt></b> 317 <td> 318 <td>100 319 <td> 320 <td> 321 <td> 322 <td> 323<tr valign=top> <td>operand stack 324 <td> 325 <td>800 326 <td> 327 <td> 328 <td> 329 <td>500 330<tr valign=top> <td>dictionary stack 331 <td> 332 <td>20 333 <td> 334 <td> 335<tr valign=top> <td>execution stack 336 <td> 337 <td>250 338 <td> 339 <td> 340<tr valign=top> <td>interpreter level 341 <td> 342 <td>none 343 <td> 344 <td>(capacity of memory) 345 <td> 346 <td>10 347<tr valign=top> <td>path 348 <td> 349 <td>none 350 <td> 351 <td>(capacity of memory) 352 <td> 353 <td>1500 354<tr valign=top> <td>dash 355 <td> 356 <td>11 357 <td> 358 <td> 359<tr valign=top> <td>VM 360 <td> 361 <td>none 362 <td> 363 <td>(capacity of memory) 364 <td> 365 <td>240000 366<tr valign=top> <td>file 367 <td> 368 <td>none 369 <td> 370 <td>(determined by operating system) 371 <td> 372 <td>6 373<tr valign=top> <td>image 374 <td> 375 <td>65535 376 <td> 377 <td>values (samples × components)<br>for1-, 2-, 4-, or 8-bit samples 378 <td> 379 <td>3300 380<tr valign=top> <td> 381 <td> 382 <td>32767 383 <td> 384 <td>values for 12-bit samples 385 <td> 386 <td>3300 387</table></blockquote> 388 389<h3><a name="VM_consumption"></a>Other differences in VM consumption</h3> 390 391<p> 392Packed array elements occupy either 2 bytes or 8 bytes. The average 393element size is probably about 5 bytes. Names occupy 12 bytes plus the 394space for the string. 395<p> 396The garbage collector doesn't reclaim portions of arrays obtained with 397<tt>getinterval</tt>, rather it collects entire arrays. 398<hr> 399 400<h2><a name="Additional_operators"></a>Additional operators in Ghostscript</h2> 401 402<h3><a name="Graphics_and_text"></a>Graphics and text operators</h3> 403 404<h4><a name="Transparency"></a>Transparency</h4> 405 406<p> 407Ghostscript provides a set of operators for implementing the transparency 408and compositing facilities of PDF 1.4. These are defined only if the 409<b><tt>transpar</tt></b> option was selected when Ghostscript was built. We 410do not attempt to explain the underlying graphics model here: for details, 411see <a 412href="http://partners.adobe.com/asn/developer/technotes.html#acrobat-pdf" 413class="offsite">Adobe 414Technical Note</a> #5407, "<a 415href="http://partners.adobe.com/asn/developer/acrosdk/DOCS/PDF_Transparency.pdf" 416class="offsite">Transparency 417in PDF</a>". Note, however, that 418Ghostscript's model generalizes that of PDF 1.4 in that Ghostscript 419maintains separate alpha and mask values for opacity and shape, rather than 420a single value with a Boolean that says whether it represents opacity or 421shape. EVERYTHING IN THIS SECTION IS SUBJECT TO CHANGE. 422 423<h5><a name="Transparency_graphics_state_operators"></a>Graphics state 424operators</h5> 425 426<dl> 427<dt><b><tt><modename> .setblendmode -</tt></b> 428<dd>Sets the blending mode in the graphics state. If the mode name is not 429recognized, causes a <b><tt>rangecheck</tt></b> error. The initial value of 430the blending mode is <b><tt>/Compatible</tt></b>. 431</dl> 432 433<dl> 434<dt><b><tt>- .currentblendmode <modename></tt></b> 435<dd>Returns the current blending mode. 436</dl> 437 438<dl> 439<dt><b><tt><0..1> .setopacityalpha -</tt></b> 440<dd>Sets the opacity alpha value in the graphics state. 441The initial opacity alpha value is 1. 442</dl> 443 444<dl> 445<dt><b><tt>- .currentopacityalpha <0..1></tt></b> 446<dd>Returns the current opacity alpha value. 447</dl> 448 449<dl> 450<dt><b><tt><0..1> .setshapealpha -</tt></b> 451<dd>Sets the shape alpha value in the graphics state. 452The initial shape alpha value is 1. 453</dl> 454 455<dl> 456<dt><b><tt>- .currentshapealpha <0..1></tt></b> 457<dd>Returns the current shape alpha value. 458</dl> 459 460<dl> 461<dt><b><tt><bool> .settextknockout -</tt></b> 462<dd>Sets the text knockout flag in the graphics state. 463The initial value of the text knockout flag is <b><tt>true</tt></b>. 464</dl> 465 466<dl> 467<dt><b><tt>- .currenttextknockout <bool></tt></b> 468<dd>Returns the current text knockout flag. 469</dl> 470 471<h5><a name="Transparency_rendering_stack_operators"></a>Rendering stack 472operators</h5> 473 474<p> 475The interpreter state is extended to include a (per-context) rendering stack 476for handling transparency groups and masks (generically, "layers"). Groups 477accumulate a full value for each pixel (paint plus transparency); masks 478accumulate only a coverage value. Layers must be properly nested, i.e., the 479'end' or 'discard' operator must match the corresponding 'begin' operator. 480 481<p> 482Beginning and ending layers must nest properly with respect to 483<b><tt>save</tt></b> and <b><tt>restore</tt></b>: <b><tt>save</tt></b> and 484<b><tt>restore</tt></b> do not save and restore the layer stack. Currently, 485layers are not required to nest with respect to <b><tt>gsave</tt></b> and 486<b><tt>grestore</tt></b>, except that the device that is current in the 487graphics state when ending a layer must be the same as the device that was 488current when beginning the layer. THIS AREA IS SUBJECT TO CHANGE. 489 490<dl> 491<dt><b><tt><paramdict> <llx> <lly> <urx> <ury> 492.begintransparencygroup -</tt></b> 493<dd>Begins a new transparency group. The <b><tt>ll/ur</tt></b> coordinates 494are the bounding box of the group in the current user coordinate system. 495<b><tt>paramdict</tt></b> has the following keys: 496<dl> 497<dt><b><tt>/Isolated</tt></b> 498<dd>(optional) Boolean; default value = <b><tt>false</tt></b>. 499<dt><b><tt>/Knockout</tt></b> 500<dd>(optional) Boolean; default value = <b><tt>false</tt></b>. 501</dl> 502</dl> 503 504<dl> 505<dt><b><tt>- .discardtransparencygroup -</tt></b> 506<dd>Ends and discards the current transparency group. 507</dl> 508 509<dl> 510<dt><b><tt>- .endtransparencygroup -</tt></b> 511<dd>Ends the current transparency group, compositing the group being ended 512onto the group that now becomes current. 513</dl> 514 515<dl> 516<dt><b><tt><paramdict> <llx> <lly> <urx> <ury> 517.begintransparencymaskgroup -</tt></b> 518<dd>Begins a new transparency mask, which is represented as a group. 519The <b><tt>ll/ur</tt></b> coordinates 520are the bounding box of the mask in the current user coordinate system. 521<b><tt>paramdict</tt></b> has the following keys: 522<dl> 523<dt><b><tt>/Subtype</tt></b> 524<dd>(required) Name, either <b><tt>/Alpha</tt></b> or 525<b><tt>/Luminosity</tt></b>. 526<dt><b><tt>/Background</tt></b> 527<dd>(optional) Array of number. 528<dt><b><tt>/TransferFunction</tt></b> 529<dd>(optional) Function object (produced by applying 530<b><tt>.buildfunction</tt></b> to a Function dictionary). 531</dl> 532</dl> 533 534<dl> 535<dt><b><tt>- .begintransparencymaskimage -</tt></b> 536<dd>Begins a new transparency mask, which is represented as a single image. 537</dl> 538</dl> 539 540<dl> 541<dt><b><tt>- .discardtransparencymask -</tt></b> 542<dd>Ends and discards the current transparency mask. 543</dl> 544 545<dl> 546<dt><b><tt><masknum> .endtransparencymask -</tt></b> 547<dd>Ends the current transparency mask, installing it as the current opacity 548(<b><tt>masknum</tt></b> = 0) or shape (<b><tt>masknum</tt></b> = 1) mask in 549the graphics state. 550</dl> 551 552<dl> 553<dt><b><tt><masknum> .inittransparencymask -</tt></b> 554<dd>Resets the current opacity (<b><tt>masknum</tt></b> = 0) or shape 555(<b><tt>masknum</tt></b> = 1) mask to an infinite mask with alpha = 1 556everywhere. 557</dl> 558 559<h5><a name="Transparency_ImageType"></a>New ImageType</h5> 560 561<p> 562The transparency extension defines a new ImageType 103, similar to ImageType 5633 with the following differences: 564 565<ul> 566 567<li>The required <b><tt>MaskDict</tt></b> is replaced by two optional 568dictionaries, <b><tt>OpacityMaskDict</tt></b> and 569<b><tt>ShapeMaskDict</tt></b>. If present, these dictionaries must have a 570<b><tt>BitsPerComponent</tt></b> entry, whose value may be greater than 1. 571Note that in contrast to ImageType 3, where any non-zero chunky mask value 572is equivalent to 1, ImageType 103 simply takes the low-order bits of chunky 573mask values. 574 575<li>A <b><tt>Matte</tt></b> entry may be present in one or both mask 576dictionaries, indicating premultiplication of the data values. If both 577<b><tt>MaskDict</tt></b>s have a <b><tt>Matte</tt></b> entry and the values 578of the two <b><tt>Matte</tt></b> entries are different, a 579<b><tt>rangecheck</tt></b> error occurs. 580 581<li><b><tt>InterleaveType</tt></b> appears in the <b><tt>MaskDict</tt></b>s, 582not the <b><tt>DataDict</tt></b>, because each mask has its own 583<b><tt>InterleaveType</tt></b>. <b><tt>InterleaveType</tt></b> 2 584(interlaced scan lines) is not supported. 585 586</ul> 587 588<h4><a name="Graphics_state"></a>Other graphics state operators</h4> 589 590<dl> 591<dt><b><tt><bool> .setaccuratecurves -</tt></b> 592<dd>Sets a graphics state flag that determines whether curves and arcs, 593when flattened, always start and end with a line that is a segment of the 594tangent; this also causes butt and square caps to be properly perpendicular 595to the tangent. <b><tt>initgraphics</tt></b> sets this flag to false, to 596match other PostScript implementations. 597</dl> 598 599<dl> 600<dt><b><tt>- .currentaccuratecurves <bool></tt></b> 601<dd>Returns the current value of the accurate curves flag. 602</dl> 603 604<dl> 605<dt><b><tt><int> .setcurvejoin -</tt></b> 606<dd>Obsolete, left for backward compatibility. 607<dd>Sets a graphics state parameter that determines how to treat the joins 608between the line segments produced when a curve is flattened. The parameter 609value may be either -1 or a value acceptable to <b><tt>setlinejoin</tt></b>. 610If the parameter value is -1, the join used for flattened curve line 611segments is given by the current line join parameter in the graphics state 612(except that if the line join value is "none", a bevel join is used), which 613matches the Adobe Red Book, but not some old Adobe implementations; if the curve 614join parameter value is a line join value, that type of join is used for 615flattened curve line segments, regardless of the value of the graphics state 616line join parameter. The initial (and default) value of the curve join 617parameter is -1, causing the compatibility to Red Book and to modern Adobe 618implementations. <b><tt>initgraphics</tt></b> sets the parameter to its 619default value. 620</dl> 621 622<dl> 623<dt><b><tt>- .currentcurvejoin <int></tt></b> 624<dd>Obsolete, left for backward compatibility. 625<dd>Returns the current value of the curve join parameter. 626</dl> 627 628<dl> 629<dt><b><tt><bool> .setdashadapt -</tt></b> 630<dd>Sets a graphics state flag that determines whether dash patterns do 631(true) or do not (false) automatically scale themselves so that each line 632segment consists of an integral number of pattern repetitions. 633<b><tt>initgraphics</tt></b> sets this flag to false. 634</dl> 635 636<dl> 637<dt><b><tt>- .currentdashadapt <bool></tt></b> 638<dd>Returns the current value of the dash adaptation flag. 639</dl> 640 641<dl> 642<dt><b><tt><matrix> .setdefaultmatrix -</tt></b> 643<dd>Sets the default matrix that is returned by 644<b><tt>defaultmatrix</tt></b> and installed by <b><tt>initmatrix</tt></b>. 645Ordinary programs should not use this operator. 646</dl> 647 648<dl> 649<dt><b><tt><num> <bool> .setdotlength -</tt></b> 650<dd>Sets a graphics state parameter that determines the handling of 651zero-length lines (dots). If the dot length is zero, dots are painted as 652circles if round line caps are in effect, otherwise they are not painted at 653all. If the dot length is non-zero, dots are treated exactly like lines of 654the given length: the length is specified in user coordinates (like line 655width) if <b><tt>bool</tt></b> is false, or in default user coordinates of 656points (units of 1/72in; see the <a href="Devices.htm#Measurements">notes 657on measurements</a> in the documentation on devices) if 658<b><tt>bool</tt></b> is true. Dots occurring as part of dash patterns will 659be oriented correctly; isolated dots will be oriented as though they were 660part of a vertical line. <b><tt>initgraphics</tt></b> sets the dot length 661to zero. 662</dl> 663 664<dl> 665<dt><b><tt>- .currentdotlength <num> <bool></tt></b> 666<dd>Returns the current dot length and dot length mode. 667</dl> 668 669<dl> 670<dt><b><tt><dx> <dy> .setfilladjust2 -</tt></b> 671<dd>Sets graphics state parameters that cause all filled and stroked 672regions to be "fattened" by the given amount relative to an algorithm that 673only paints pixels whose centers fall within the region to be painted. 674<b><tt>dx</tt></b> and <b><tt>dy</tt></b> are numbers between 0 and 0.5, 675measured in device space. The only two values that are likely to be useful 676are 0, which gives a pure center-of-pixel rule, and 0.5, which gives 677Adobe's any-part-of-pixel rule. (0.5 is treated slightly specially in 678order to create half-open pixels per Adobe's specification.) 679</dl> 680 681<dl> 682<dt><b><tt>- .currentfilladjust2 <dx> <dy></tt></b> 683<dd>Returns the current fill adjustment values. 684</dl> 685 686<dl> 687<dt><b><tt><bool> .setlimitclamp -</tt></b> 688<dd>Sets a graphics state flag that determines whether attempts to set the 689current point outside the internally representable range should clamp the 690value to the largest representable value (true) or give a 691<b><tt>limitcheck</tt></b> error (false). <b><tt>initgraphics</tt></b> sets 692this flag to false, to match other PostScript implementations. 693</dl> 694 695<dl> 696<dt><b><tt>- .currentlimitclamp <bool></tt></b> 697<dd>Returns the current value of the limit clamp flag. 698</dl> 699 700<dl> 701<dt><b><tt><int> .setoverprintmode -</tt></b> 702<dd>Sets the overprint mode in the graphics state. Legal values are 0 or 1. 703Per the PDF 1.3 specification, if the overprint mode is 1, then when the 704current color space is <b><tt>DeviceCMYK</tt></b>, color components whose 705value is 0 do not write into the target, rather than writing a 0 value. 706THIS BEHAVIOR IS NOT IMPLEMENTED YET. The initial value of the overprint 707mode is 0. 708</dl> 709 710<dl> 711<dt><b><tt>- .currentoverprintmode <int></tt></b> 712<dd>Returns the current overprint mode. 713</dl> 714 715<h4><a name="Path"></a>Path operators</h4> 716 717<dl> 718<dt><b><tt>- .dashpath -</tt></b> 719<dd>If there is no current dash pattern, does nothing. Otherwise, does the 720equivalent of <b><tt>flattenpath</tt></b> and then chops up the path as 721determined by the dash pattern. 722</dl> 723 724<dl> 725<dt><b><tt><x> <y> <width> <height> .rectappend -</tt></b> 726<dt><b><tt><numarray> .rectappend -</tt></b> 727<dt><b><tt><numstring> .rectappend -</tt></b> 728<dd>Appends a rectangle or rectangles to the current path, in the same 729manner as <b><tt>rectfill</tt></b>, <b><tt>rectclip</tt></b>, etc. Defined 730only if the <b><tt>dps</tt></b> or <b><tt>level2</tt></b> option was 731selected when Ghostscript was built. 732</dl> 733 734<h4><a name="Painting"></a>Painting operators</h4> 735 736<p> 737Ghostscript supports an experimental extension of the PostScript imaging 738model to include <b><tt>RasterOp</tt></b> and some related facilities. 739This extension is available only if the <b><tt>rasterop</tt></b> option was 740selected when building Ghostscript. 741 742<p> 743With the <b><tt>RasterOp</tt></b> extension, imaging operations compute a 744function <b>D = f(D,S,T)</b> in RGB space, where <b>f</b> is an 745arbitrary 3-input Boolean function, <b>D</b> is the destination (frame 746buffer or print buffer), <b>S</b> is the source (described below), and 747<b>T</b> is the texture (the current PostScript color, which may be a 748pattern). The source and texture depend on the PostScript imaging 749operation: 750 751<ul> 752<li>For <b><tt>fill</tt></b> and <b><tt>stroke</tt></b>, the source is 753solid black, covering the region to be painted; the texture is the current 754PostScript color. 755 756<li>For <b><tt>show</tt></b> and <b><tt>imagemask</tt></b>, the source is 757solid black, covering the pixels to be painted; the texture is the current 758PostScript color. 759 760<li>For <b><tt>image</tt></b> and <b><tt>colorimage</tt></b>, the source is 761the image data; the texture depends on an optional Boolean parameter, 762<b><tt>CombineWithColor</tt></b>, in the image dictionary. If 763<b><tt>CombineWithColor</tt></b> is false (the default), the texture is 764solid black. If <b><tt>CombineWithColor</tt></b> is true, the texture is 765the current color. For the non-dictionary form of the image operator, 766<b><tt>CombineWithColor</tt></b> is considered to be false. 767</ul> 768 769<p> 770The <b><tt>rasterop</tt></b> option adds the following operators: 771 772<dl> 773<dt><b><tt><int8> .setrasterop -</tt></b> 774<dd>Sets the <b><tt>RasterOp</tt></b> function in the graphics state. The 775default function is 252, Source | Texture. 776</dl> 777 778<dl> 779<dt><b><tt>- .currentrasterop <int8></tt></b> 780<dd>Returns the current <b><tt>RasterOp</tt></b> function. 781</dl> 782 783<dl> 784<dt><b><tt><bool> .setsourcetransparent -</tt></b> 785<dd>Sets source transparency in the graphics state. When source 786transparency is true, white source pixels prevent storing into the 787destination, regardless of what the <b><tt>RasterOp</tt></b> function 788returns. The default source transparency is false. 789</dl> 790 791<dl> 792<dt><b><tt>- .currentsourcetransparent <bool> -</tt></b> 793<dd>Returns the current source transparency. 794</dl> 795 796<dl> 797<dt><b><tt><bool> .settexturetransparent -</tt></b> 798<dd>Sets texture transparency in the graphics state. When texture 799transparency is true, white texture pixels prevent storing into the 800destination, regardless of what the <b><tt>RasterOp</tt></b> function 801returns. The default texture transparency is false. 802</dl> 803 804<dl> 805<dt><b><tt>- .currenttexturetransparent <bool> -</tt></b> 806<dd>Returns the current texture transparency. 807</dl> 808 809<p> 810For more information on RasterOp and transparency, please consult chapter 5 811of the "PCL 5 Color Technical Reference Manual", 812<a href="http://www.hp.com/cposupport/printers/support_doc/bpl01354.html">Hewlett-Packard 813Manual Part No. 5961-0635</a>. 814 815<h4><a name="Character"></a>Character operators</h4> 816 817<dl> 818<dt><b><tt><string> <bool> .charboxpath -</tt></b> 819<dd>For each character <b>C</b> in the rendering of <string>, let the 820bounding box of <b>C</b> <b><em>in device space</em></b> be the four 821<b><em>user-space</em></b> points p1x/y, p2x/y, p3x/y, and p4x/y. For each 822character in order, <b><tt>.charboxpath</tt></b> appends the following to 823the current path: 824 825<ul><li>If <b><tt><bool></tt></b> is true, the equivalent of: 826 827<blockquote> 828p1x p1y <b><tt>moveto</tt></b><br> 829p2x p2y <b><tt>lineto</tt></b><br> 830p3x p3y <b><tt>lineto</tt></b><br> 831p4x p4y <b><tt>lineto</tt></b><br> 832<b><tt>closepath</tt></b> 833</blockquote> 834</ul> 835 836<p> 837This creates a path whose <b><tt>pathbbox</tt></b> is the 838<b><tt>bbox</tt></b> of the string. 839 840<ul><li>If <b><tt><bool></tt></b> is false, the equivalent of: 841 842<blockquote> 843p1x p1y <b><tt>moveto</tt></b><br> 844p3x p3y <b><tt>lineto</tt></b> 845</blockquote> 846</ul> 847 848<p> 849If the CTM is well-behaved (consists only of reflection, scaling, and 850rotation by multiples of 90 degrees), this too creates a (simpler) path 851whose <b><tt>pathbbox</tt></b> is the <b><tt>bbox</tt></b> of the string. 852</dl> 853 854<dl> 855<dt><b><tt><font> <charname|charcode> <charname> <charstring> .type1execchar -</tt></b> 856<dd>Does all the work for rendering a Type 1 outline. This operator, like 857<b><tt>setcharwidth</tt></b> and <b><tt>setcachedevice</tt></b>, is valid 858only in the context of a show operator -- that is, it must only be called 859from within a <b><tt>BuildChar</tt></b> or <b><tt>BuildGlyph</tt></b> 860procedure. 861</dl> 862 863<dl> 864<dt><b><tt><font> <charcode> %Type1BuildChar -</tt></b> 865<dd>This is not a new operator: rather, it is a name known specially to the 866interpreter. Whenever the interpreter needs to render a character (during 867a ...<b><tt>show</tt></b>, <b><tt>stringwidth</tt></b>, or 868<b><tt>charpath</tt></b>), it looks up the name <b><tt>BuildChar</tt></b> 869in the font dictionary to find a procedure to run. If it does not find 870this name, and if the <b><tt>FontType</tt></b> is 1, the interpreter 871instead uses the value (looked up on the dictionary stack in the usual way) 872of the name <b><tt>%Type1BuildChar</tt></b>. 873 874<p> 875The standard definition of <b><tt>%Type1BuildChar</tt></b> is in the 876initialization file <b><tt>gs_type1.ps</tt></b>. Users should not need to 877redefine <b><tt>%Type1BuildChar</tt></b>, except perhaps for tracing or 878debugging. 879</dl> 880 881<dl> 882<dt><b><tt><font> <charname> %Type1BuildGlyph -</tt></b> 883<dd>Provides the Type 1 implementation of <b><tt>BuildGlyph</tt></b>. 884</dl> 885 886<h3><a name="Other"></a>Other operators</h3> 887 888<h4><a name="Mathematical"></a>Mathematical operators</h4> 889 890<dl> 891<dt><b><tt><number> arccos <number></tt></b> 892<dd>Computes the arc cosine of a number between -1 and 1. 893</dl> 894 895<dl> 896<dt><b><tt><number> arcsin <number></tt></b> 897<dd>Computes the arc sine of a number between -1 and 1. 898</dl> 899 900<h4><a name="Dictionary"></a>Dictionary operators</h4> 901 902<dl> 903<dt><b><tt>mark <key1> <value1> <key2> <value2> ... .dicttomark <dict></tt></b> 904<dd>Creates and returns a dictionary with the given keys and values. This 905is the same as the PostScript Level 2 <b><tt>>></tt></b> operator, 906but is available even in Level 1 configurations. 907</dl> 908 909<dl> 910<dt><b><tt><dict> <key> <value> .forceput - </tt></b> 911<dd>Equivalent to <b><tt>put</tt></b>, but works even if 912<b><tt>dict</tt></b> is not writable, and (if <b><tt>dict</tt></b> is 913<b><tt>systemdict</tt></b> or the current save level is 0) even if 914<b><tt>dict</tt></b> is in global VM and <b><tt>key</tt></b> and/or 915<b><tt>value</tt></b> is in local VM. <strong>This operator should be used 916only initialization code, and only in executeonly procedures: it must not be 917accessible after initialization.</strong> 918</dl> 919 920<dl> 921<dt><b><tt><dict> <key> .forceundef - </tt></b> 922<dd>Equivalent to <b><tt>undef</tt></b>, but works even if 923<b><tt>dict</tt></b> is not writable. <strong>This operator should be used 924only initialization code, and only in executeonly procedures: it must not be 925accessible after initialization.</strong> 926</dl> 927 928 929<dl> 930<dt><b><tt><dict> <key> .knownget <value> true</tt></b> 931<dt><b><tt><dict> <key> .knownget false</tt></b> 932<dd>Combines <b><tt>known</tt></b> and <b><tt>get</tt></b> in the 933obvious way. 934</dl> 935 936<dl> 937<dt><b><tt><dict> <integer> .setmaxlength -</tt></b> 938<dd>Sets the capacity (<b><tt>maxlength</tt></b>) of a dictionary. 939Causes a <b><tt>dictfull</tt></b> error if the dictionary has more 940occupied entries than the requested capacity. 941</dl> 942 943<h4><a name="String"></a>String and name operators</h4> 944 945<dl> 946<dt><b><tt><integer> .bytestring <bytestring></tt></b> 947<dd>Allocates and returns a bytestring, a special data type that can be 948larger than the maximum size of a string (64K-1 bytes) and can be used in 949place of a string with a very few operators. 950</dl> 951 952<dl> 953<dt><b><tt><name> .namestring <string></tt></b> 954<dd>Returns the (read-only) string for a name. 955</dl> 956 957<dl> 958<dt><b><tt><string> <charstring> .stringbreak <index|null></tt></b> 959<dd>Searches for a character in <b><tt>string</tt></b> that appears 960somewhere in <b><tt>charstring</tt></b>. If such a character is found, 961returns the index of the first such character; if no such character is 962found, returns <b><tt>null</tt></b>. 963</dl> 964 965<dl> 966<dt><b><tt><obj> <pattern> .stringmatch <bool></tt></b> 967<dd>Matches <b><tt>obj</tt></b> against a pattern in which '*' matches 0 or 968more characters and '?' matches any single character. If 969<b><tt>obj</tt></b> is a string or a name, matches its characters against 970the pattern; if <b><tt>obj</tt></b> is of any other type, the result is 971<b><tt>true</tt></b> if the pattern is the single character "*" and 972<b><tt>false</tt></b> otherwise. 973</dl> 974 975<dl> 976<dt><b><tt><state> <fromString> <toString> .type1encrypt <newState> <toSubstring></tt></b> 977<dd>Encrypts <b><tt>fromString</tt></b> according to the algorithm for 978Adobe Type 1 fonts, writing the result into <b><tt>toString</tt></b>. 979<b><tt>toString</tt></b> must be at least as long as 980<b><tt>fromString</tt></b>, or a rangecheck error occurs. 981<b><tt>state</tt></b> is the initial state of the encryption algorithm (a 98216-bit non-negative integer); <b><tt>newState</tt></b> is the new state of 983the algorithm. 984</dl> 985 986<dl> 987<dt><b><tt><state> <fromString> <toString> .type1decrypt <newState> <toSubstring></tt></b> 988<dd>Decrypts <b><tt>fromString</tt></b> according to the algorithm for 989Adobe Type 1 fonts, writing the result into <b><tt>toString</tt></b>. 990Other specifications are as for <b><tt>type1encrypt</tt></b>. 991</dl> 992 993<h4><a name="Relational"></a>Relational operators</h4> 994 995<dl> 996<dt><b><tt><number|string> <number|string> max <number|string></tt></b> 997<dd>Returns the larger of two numbers or strings. 998</dl> 999 1000<dl> 1001<dt><b><tt><number|string> <number|string> min <number|string></tt></b> 1002<dd>Returns the smaller of two numbers or strings. 1003</dl> 1004 1005<h4><a name="File"></a>File operators</h4> 1006 1007<dl> 1008<dt><b><tt><file> .filename <string> true</tt></b> 1009<dt><b><tt><file> .filename false</tt></b> 1010<dd>If the file was opened by the <b><tt>file</tt></b> or 1011<b><tt>.tempfile</tt></b> operator, returns the file name and 1012<b><tt>true</tt></b>; if the file is a filter, returns 1013<b><tt>false</tt></b>. 1014</dl> 1015 1016<dl> 1017<dt><b><tt><file> .fileposition <integer> true</tt></b> 1018<dd>Returns the position of <b><tt>file</tt></b>. Unlike the standard 1019<b><tt>fileposition</tt></b> operator, which causes an error if the file is 1020not positionable, <b><tt>.fileposition</tt></b> works on all files, 1021including filters: for non-positionable files, it returns the total number 1022of bytes read or written since the file was opened. 1023</dl> 1024 1025<dl> 1026<dt><b><tt><string> findlibfile <foundstring> <file> true</tt></b> 1027<dt><b><tt><string> findlibfile <string> false</tt></b> 1028<dd>Opens the file of the given name for reading, searching through 1029directories <a href="Use.htm#Finding_files">as described in the usage 1030documentation</a>. If the search fails, <b><tt>findlibfile</tt></b> simply 1031pushes false on the stack and returns, rather than causing an error. 1032</dl> 1033 1034<dl> 1035<dt><b><tt><file> <string> .peekstring <substring> <filled_bool></tt></b> 1036<dd>Reads bytes from a file like <b><tt>readstring</tt></b>, but also leaves 1037the bytes in the file buffer so they will be read again by a subsequent read 1038operation. Currently gives a <b><tt>rangecheck</tt></b> error if 1039<b><tt>string</tt></b> is larger than the file's buffer. 1040</dl> 1041 1042<a name=Tempfile></a> 1043<dl> 1044<dt><b><tt><prefix_string|null> <access_string> .tempfile 1045<string> <file></tt></b> 1046<dd>Creates and opens a temporary file 1047like the <b><tt>file</tt></b> operator, also returning the file name. There 1048are three cases for the <b><tt><prefix_string|null></tt></b> operand: 1049 1050<ul> 1051<p> 1052<li><b><tt>null</tt></b>: create the file in the same directory and with the 1053same name conventions as other temporary files created by the Ghostscript 1054implementation on this platform. E.g., the temporary file might be named 1055<b><tt>/tmp/gs_a1234</tt></b>. 1056<p> 1057<li>A string that contains only alphanumeric characters, underline, 1058and dash: create the file in the standard temporary directory, but use 1059the 1060<b><tt><prefix_string></tt></b> as the first part of the file name. 1061E.g., if <b><tt><prefix_string></tt></b> is <b><tt>xx</tt></b>, the 1062temporary file might be named <b><tt>/tmp/xxa1234</tt></b>. 1063<p> 1064<li>A string that is the beginning of an absolute file name: use the 1065<b><tt><prefix_string></tt></b> as the first part of the file name. 1066E.g., if <b><tt><prefix_string></tt></b> is 1067<b><tt>/my/tmpdir/zz</tt></b>, the temporary file might be named 1068<b><tt>/my/tmpdir/zza1234</tt></b>. 1069<p> 1070When running in <b><tt>SAFER</tt></b> mode, the absolute path must 1071be one of the strings on the list given by the <b><tt>PermitFileWriting</tt></b> 1072userparameter. Temporary files created with <b><tt>.tempfile</tt></b> can 1073be deleted when in SAFER mode, and can be renamed to one of the paths 1074that is on <b>both</b> the PermitFileControl and PermitFileWriting 1075paths. 1076</ul> 1077 1078</dl> 1079 1080<dl> 1081<dt><b><tt><file> <integer> .unread -</tt></b> 1082<dd>Pushes back the last-read character onto the front of the file. If the 1083file is open only for writing, or if the integer argument is not the same 1084as the last character read from the file, causes an <b><tt>ioerror</tt></b> 1085error. May also cause an <b><tt>ioerror</tt></b> if the last operation on 1086the file was not a reading operation. This operator is now deprecated: 1087use <b><tt>.peekstring</tt></b> in new code. 1088</dl> 1089 1090<p> 1091Ghostscript also supports the following <b><tt>IODevice</tt></b> in 1092addition to a subset of those defined in the Adobe documentation: 1093<ul> 1094<li> 1095<b><tt>%pipe%command</tt></b>, which opens a pipe on the given command. 1096This is supported only on operating systems that provide 1097<b><tt>popen</tt></b> (primarily Unix systems, and not all of those). 1098<p> 1099<li> 1100<b><tt>%disk#%</tt></b>, which emulates the %disk0 1101through %disk9 devices on some Adobe PostScript printers. This pseudo 1102device provides a flat filenaming system with a user definable location 1103for the files (/Root). These devices will only be present if the 1104diskn.dev feature is specified during the build. 1105<p> 1106This feature is intended to allow compatibility with font downloaders 1107that expect to store fonts on the %disk device of the printer. 1108<p> 1109Use of the %disk#% devices requires that the location of files be given 1110by the user setting the /Root device parameter. The syntax for setting 1111the /Root parameter is:<pre> 1112 mark /Root (directory_specification) (%disk#) .putdevparams 1113</pre> 1114For example, to store the files of the %disk0 device on the directory 1115/tmp/disk0, use:<pre> 1116 mark /Root (/tmp/disk0/) (%disk0) .putdevparams 1117</pre> 1118The files will be stored in the specified directory with arbitrary names. 1119A mapping file is used to store the association between the file 1120names given for the file operations on the %diskn# device and the file 1121that resides in the /Root directory. 1122</ul> 1123 1124<h4><a name="Virtual_memory"></a>Virtual memory operators</h4> 1125 1126<dl> 1127<dt><b><tt><save> .forgetsave -</tt></b> 1128<dd>Cancels the effect of a save, making it as though the save never 1129happened. 1130</dl> 1131 1132<h4><a name="Miscellaneous"></a>Miscellaneous operators</h4> 1133 1134<dl> 1135<dt><b><tt><array> bind <array></tt></b> 1136<dd>Depending on the command line parameters <b><tt>bind</tt></b> is redefined as: 1137</dl> 1138 1139<blockquote><table cellpadding=0 cellspacing=0> 1140<tr valign=bottom> 1141 <th valign=bottom align=left>Flag 1142 <td> 1143 <th valign=bottom align=left>Definition 1144<tr> <td colspan=3><hr> 1145<tr valign=top> <td>NOBIND 1146 <td> 1147 <td>/bind {} def ; 1148 no operation, returns the argument 1149<tr valign=top> <td>DELAYBIND 1150 <td> 1151 <td>returns the argument, stores the argument for later use by <b><tt>.bindnow</b></tt> 1152</table></blockquote> 1153 1154 1155<dl> 1156<dt><b><tt><array> .bind <array></tt></b> 1157<dd>Performs standard <b><tt>bind</tt></b> operation as defined in PLRM regardless of 1158NOBIND or DELAYBIND flags. 1159</dl> 1160 1161<a name="bindnow"></a> 1162<dl> 1163<dt><b><tt>- .bindnow -</tt></b> 1164<dd>Applies <b><tt>bind</tt></b> operator to all savad procedures after binding has been 1165deferred through -dDELAYBIND. Note that idiom recognition has no effect for the deferred 1166binding because the value returned from <b><tt>bind</tt></b> is discarded. 1167<p> 1168Since v. 8.12 <b><tt>.bindnow</tt></b> undefines itself and restores standard definition of 1169<b><tt>bind</tt></b> operator. In earlier versions after calling <b><tt>.bindnow</tt></b>, 1170the postscript <b><tt>bind</tt></b> operator needs to be rebound to the internal implementation 1171<b><tt>.bind</tt></b>, as in this fragment from the ps2ascii script: 1172<blockquote><pre><tt>DELAYBIND { 1173 .bindnow 1174 /bind /.bind load def 1175} if 1176</tt></pre></blockquote> 1177This is necessary for correct behavior with later code that uses the <b><tt>bind</tt></b> operator. 1178</dl> 1179 1180<dl> 1181<dt><b><tt><obj1> <obj2> ... <objn> <n> .execn ...</tt></b> 1182<dd>This executes <b><tt>obj1</tt></b> through <b><tt>objn</tt></b> in that 1183order, essentially equivalent to 1184 1185<blockquote><pre> 1186<obj1> <obj2> ... <objn> <n> array astore {exec} forall 1187</pre></blockquote> 1188 1189<p> 1190except that it doesn't actually create the array. 1191</dl> 1192 1193<dl> 1194<dt><b><tt><string> getenv <string> true</tt></b> 1195<dt><b><tt><string> getenv false</tt></b> 1196<dd>Looks up a name in the shell environment. If the name is found, 1197returns the corresponding value and true; if the name is not found, returns 1198false. 1199</dl> 1200 1201<dl> 1202<dt><b><tt><name> <array> .makeoperator <operator></tt></b> 1203<dd>Constructs and returns a new operator that is actually the given 1204procedure in disguise. The name is only used for printing. The operator 1205has the executable attribute. 1206 1207<p> 1208Operators defined in this way do one other thing besides running the 1209procedure: if an error occurs during the execution of the procedure, and 1210there has been no net reduction in operand or dictionary stack depth, the 1211operand or dictionary stack pointer respectively is reset to its position 1212at the beginning of the procedure. 1213</dl> 1214 1215<dl> 1216<dt><b><tt><string> <boolean> .setdebug -</tt></b> 1217<dd>If the Ghostscript interpreter was built with the <b><tt>DEBUG</tt></b> 1218flag set, sets or resets any subset of the debugging flags normally 1219controlled by <b><tt>-Z</tt></b> in the command line. Has no effect 1220otherwise. 1221</dl> 1222 1223<dl> 1224<dt><b><tt>- .oserrno <errno></tt></b> 1225<dd>Returns the error code for the most recent operating system error. 1226</dl> 1227 1228<dl> 1229<dt><b><tt>- .oserrorstring <string></tt></b> 1230<dd>Returns the error string for the most recent operating system error. 1231</dl> 1232 1233<a name="Runandhide"></a> 1234<dl> 1235<dt><b><tt><array> <procedure> .runandhide ... <array></tt></b> 1236<dd>Runs the <i><tt><procedure></tt></i> after removing the 1237<i><tt><array></tt></i> from the stack. As long as <i><tt><array></tt></i> 1238is not contained in any readable dictionaries or elsewhere on stacks, it 1239will not be accessible to <i><tt><procedure></tt></i>. 1240<p> 1241This operator is intended to allow hiding a <i><tt><save></tt></i> object 1242during execution of procedures or files that run in <b>SAFER</b> mode. 1243If a <b><tt>save</tt></b> is performed prior to entering <b>SAFER</b> mode 1244with <b><tt>.setsafe</tt></b>, using the save object as the operand to 1245<b><tt>restore</tt></b> will return to <b>NOSAFER</b> mode. In order to 1246prevent the procedures running in <b>SAFER</b> mode from being able to 1247return to <b>NOSAFER</b> mode, this operator should be used. 1248Upon return from the file or procedure <b><tt>restore</tt></b> can be used 1249to return to <b>NOSAFER</b> mode. 1250<p> 1251<b>Note:</b> The array operand hidden during the execution of the file or 1252procedure will be placed at the top of the operand stack which may be on 1253top of objects that the file or procedure leaves on top of the stack. 1254Thus removing objects below the array may be needed to prevent an 1255<b><tt>invalidrestore</tt></b> error. 1256<p> 1257For example, in order for a script or job server to execute a file 1258<tt>somefile.ps</tt> with the <b>SAFER</b> mode restrictions in place, returning 1259to unrestricted <b>NOSAFER</b> mode when the procedure exits is as follows: 1260<pre> 1261 Start Ghostscript with <b>-dNOSAFER</b> 1262 1263 ... % perform any device set up w/o restrictions 1264 [ save ] % create a save object before SAFER 1265 (somefile.ps) (r) file cvx % open the file to process 1266 .setsafe % enter SAFER mode 1267 .runandhide % run the file hiding the save object 1268 count 1 roll % place array below anything left over 1269 count 1 sub { pop } repeat % pop left over stuff 1270 cleardictstack % prevent invalidrestore from dicts 1271 0 get restore % go back to NOSAFER mode 1272</pre> 1273Another refinement on the above would be to execute <b><tt>.runandhide</tt></b> 1274using <b><tt>stopped</tt></b> in order to report errors but continue processing. 1275</dl> 1276 1277<dl> 1278<dt><b><tt>- .setsafe -</tt></b> 1279<dd>If Ghostscript is started with <b><tt>-dNOSAFER</tt></b> or 1280<b><tt>-dDELAYSAFER</tt></b>, this operator can be used to enter <b>SAFER</b> 1281mode (see <a href="Use.htm#Safer"><b>-dSAFER</b></a>) 1282<p> 1283Since <b>SAFER</b> mode is implemented with userparameters and device parameters, 1284it is possible to use <b><tt>save</tt></b> and <b><tt>restore</tt></b> before 1285and after <b><tt>.setsafe</tt></b> to return to <b>NOSAFER</b> mode, but care 1286should be taken to ensure that the <i><tt>save</tt></i> object is not 1287accessible to any procedures or file run in <b>SAFER</b> mode (see 1288<a href="#Runandhide"><b>.runandhide</b></a> above). 1289<p> 1290<b>Note: This uses setpagedevice to change .LockSafetyParams, so the page 1291will be erased as a side effect of this operator</b> 1292</dl> 1293 1294<dl> 1295<dt><b><tt>- .locksafe -</tt></b> 1296<dd> 1297This operator sets the current device's <b><tt>.LockSafetyParams</tt></b> 1298and the <b><tt>LockFilePermissions</tt></b> userparameter true as well as 1299adding the paths on LIBPATH and FONTPATH and the paths given by the 1300system params /GenericResourceDir and /FontResourceDir to the current 1301PermitFileReading list of paths. 1302<p> 1303If Ghostscript is started with <b><tt>-dNOSAFER</tt></b> or 1304<b><tt>-dDELAYSAFER</tt></b>, this operator can be used to enter <b>SAFER</b> 1305mode with the current set of <b><tt>PermitFile...</tt></b> user parameters 1306in effect. Since <b><tt>.setsafe</tt></b> sets the <b><tt>PermitFile...</tt></b> 1307user parameters to empty arrays, a script or job server that needs to 1308enable certain paths for file Reading, Writing and/or Control can use this 1309operator to perform the locking needed to enter <b>SAFER</b> mode. 1310<p> 1311For example, to enable reading everywhere, but disallow writing and file 1312control (deleting and renaming files), the following can be used: 1313<pre> 1314 { << /PermitFileReading [ (*) ] 1315 /PermitFileWriting [ ] 1316 /PermitFileControl [ ] 1317 >> setuserparams 1318 .locksafe 1319 } stopped pop 1320</pre> 1321In the above example, use of stopped will allow the use of this sequence on 1322older versions of Ghostscript where <b><tt>.locksafe</tt></b> was not an operator. 1323<p> 1324<b>Note: This uses setpagedevice to change .LockSafetyParams, so the page 1325will be erased as a side effect of this operator</b> 1326<p> 1327See also <a href="#LockSafetyParams">.LockSafetyParams</a> and 1328<a href="#User_parameters">User Parameters</a>. 1329<p> 1330</dl> 1331 1332<dl><a name=".setpdfwrite"></a> 1333<dt><b><tt>.setpdfwrite</tt></b></dt> 1334<dd>This operator conditions the environment for the <tt>pdfwrite</tt> output device. 1335It is a shorthand for setting parameters that have been deemed benificial. While not strictly necessary, it is usually helpful to set call this when using the pdfwrite device. 1336For example, this is how the ps2pdf script calls Ghostscript: 1337<blockquote><b><tt> 1338gs -q -dSAFER -dNOPAUSE -dBATCH -sOutputFile=file.pdf </tt></b><em>[more options]</em><b><tt> \<br> 1339 -sDEVICE=pdfwrite -c .setpdfwrite -f </b></tt><em>source1.ps [more files]</em> 1340</blockquote> 1341<p>Currently, the operator just sets a minimum 3 MB vmthreshold to allow for 1342accumulating shared object data and to reduce the incidence of garbage 1343collection as a performance improvement. Additional settings may be added in the future. 1344</dl> 1345 1346<dl> 1347<dt><b><tt>.color_test</tt></b> and <b><tt>.color_test_all</tt></b></dt> 1348<dd>These operators are used for the verification of device encode_color and 1349decode_color routines. They are for internal use only. Their function 1350can, and probably will, change as Artifex's requirements change. 1351<p> 1352<dd>Currently these operators loop through a set of possible values for the inputs 1353to the encode_color routine and then veify that the decode_color routines produce 1354values that match the input set to within a tolerance which is based upon the number 1355of bits used to encode a pixel. The operators also verify that if the device 1356is 'separable' then that the values produced by gx_default_encode_color and 1357gx_default_decode_color (the default encode/decode color handlers for a separable 1358device) are consistent to within the same tolerance. 1359</dl> 1360 1361<h4><a name="Device"></a>Device operators</h4> 1362 1363<dl> 1364<dt><b><tt><device> copydevice <device></tt></b> 1365<dd>Copies a device. The copy is writable and installable. The copy is 1366created in the current VM (local or global), usually local VM for executing 1367ordinary PostScript files. 1368</dl> 1369 1370<dl> 1371<dt><b><tt><devicename> finddevice <device></tt></b> 1372<dd>Creates a default instance of a device specified by name. The instance 1373is created in global VM. If <b><tt>finddevice</tt></b> is called more than 1374once with the same device name, it creates the default instance the first 1375time, and returns the same instance thereafter. 1376</dl> 1377 1378<dl> 1379<dt><b><tt><devicename> findprotodevice <device></tt></b> 1380<dd>Finds the prototype of a device specified by name. A prototype can be 1381used with <b><tt>.getdeviceparams</tt></b> or other parameter-reading 1382operators, but it is read-only and cannot be set with 1383<b><tt>setdevice</tt></b>: it must be copied first. 1384</dl> 1385 1386<dl> 1387<dt><b><tt><device> <x> <y> <width> <max_height> <alpha?> <std_depth|null> <string> .getbitsrect <height> <substring></tt></b> 1388<dd>Reads a rectangle of rendered bits back from a device. This is only 1389guaranteed to be implemented for image devices (see below). 1390<b><tt>alpha?</tt></b> is 0 for no alpha, -1 for alpha first, 1 for alpha 1391last. <b><tt>std_depth</tt></b> is null for native pixels, number of bits 1392per component for a standard color space. 1393</dl> 1394 1395<dl> 1396<dt><b><tt><index> .getdevice <device></tt></b> 1397<dd>Returns a device from the set of devices known to the system. The 1398first device, which is the default, is numbered 0. If the 1399<b><tt>index</tt></b> is out of range, causes a <b><tt>rangecheck</tt></b> 1400error. This device is actually a prototype, not a directly usable device, 1401and is marked read-only; it cannot have its parameters changed or be 1402installed as the current device. 1403</dl> 1404 1405<dl> 1406<dt><b><tt><matrix> <width> <height> <palette> makeimagedevice <device></tt></b> 1407<dd>Makes a new device that accumulates an image in memory. <b><tt> 1408matrix</tt></b> is the initial transformation matrix: it must be orthogonal 1409(that is, [a 0 0 b x y] or 1410[0 a b 0 x y]). <b><tt>palette</tt></b> is a 1411string of 2^<small><sup><b>N</b></sup></small> or 14123 × 2^<small><sup><b>N</b></sup></small> elements, 1413specifying how the 2^<small><sup><b>N</b></sup></small> possible pixel 1414values will be interpreted. Each element is interpreted as a gray value, 1415or as RGB values, multiplied by 255. For example, if you want a monochrome 1416image for which 0=white and 1=black, the palette should be 1417<b><tt><ff 00></tt></b>; if you want a 3-bit deep image with 1418just the primary colors and their complements (ignoring the fact that 3-bit 1419images are not supported), the palette might be <b><tt><000000 0000ff 142000ff00 00ffff ff0000 ff00ff ffff00 ffffff></tt></b>. At present, the 1421palette must contain exactly 2, 4, 16, or 256 entries, and must contain an 1422entry for black and an entry for white; if it contains any entries that 1423aren't black, white, or gray, it must contain at least the six primary 1424colors (red, green, blue, and their complements cyan, magenta, and yellow); 1425aside from this, its contents are arbitrary. 1426 1427<p> 1428Alternatively, palette can be 16, 24, 32, or null (equivalent to 24). 1429These are interpreted as: 1430 1431<blockquote><table cellpadding=0 cellspacing=0> 1432<tr valign=bottom> 1433 <th valign=bottom align=left>Palette 1434 <td> 1435 <th valign=bottom align=left>Bits allocated per color 1436<tr> <td colspan=3><hr> 1437<tr valign=top> <td>16 1438 <td> 1439 <td>5 red, 6 green, 5 blue 1440<tr valign=top> <td>24 1441 <td> 1442 <td>8 red, 8 green, 8 blue 1443<tr valign=top> <td>32 1444 <td> 1445 <td>8C, 8M, 8Y, 8K 1446</table></blockquote> 1447 1448<p> 1449Note that one can also make an image device (with the same palette as an 1450existing image device) by copying a device using the 1451<b><tt>copydevice</tt></b> operator. 1452</dl> 1453 1454<dl> 1455<dt><b><tt><matrix> <width> <height> <palette> <word?> makewordimagedevice <device></tt></b> 1456<dd>Makes an image device as described above. <b><tt>word?</tt></b> is a 1457Boolean value indicating whether the data should be stored in a 1458word-oriented format internally. No ordinary PostScript programs should 1459use this operator. 1460</dl> 1461 1462<dl> 1463<dt><b><tt><device> <index> <string> copyscanlines <substring></tt></b> 1464<dd>Copies one or more scan lines from an image device into a string, 1465starting at a given scan line in the image. The data is in the same format 1466as for the <b><tt>image</tt></b> operator. It is an error if the device is 1467not an image device or if the string is too small to hold at least one 1468complete scan line. Always copies an integral number of scan lines. 1469</dl> 1470 1471<dl> 1472<dt><b><tt><device> setdevice -</tt></b> 1473<dd> 1474<p> 1475Sets the current device to the specified device. Also resets the 1476transformation and clipping path to the initial values for the device. 1477Signals an <b><tt>invalidaccess</tt></b> error if the device is a 1478prototype or if <a href="Language.htm#LockSafetyParams">.LockSafetyParams</a> 1479is true for the current device. 1480<p> 1481Some device properties may need to be set with <tt>putdeviceprops</tt> before 1482<b><tt>setdevice</tt></b> is called. For example, the pdfwrite device will try 1483to open its output file, causing an <tt>undefinedfilename</tt> error if 1484<tt>OutputFile</tt> hasn't been set to a valid filename. Another method in such 1485cases is to use the level 2 operator instead: 1486 1487 <tt><< /OutputDevice /pdfwrite /OutputFile (MyPDF.pdf) >> <b>setpagedevice</b></tt>. 1488 1489</dl> 1490 1491<dl> 1492<dt><b><tt>- currentdevice <device></tt></b> 1493<dd>Gets the current device from the graphics state. 1494</dl> 1495 1496<dl> 1497<dt><b><tt><device> getdeviceprops <mark> <name1> <value1> ... <namen> <valuen></tt></b> 1498<dd>Gets the properties of a device. See the section on 1499<a href="#Device_parameters">device parameters</a> below for details. 1500</dl> 1501 1502<dl> 1503<dt><b><tt><mark> <name1> <value1> ... <namen> <valuen> <device> putdeviceprops <device></tt></b> 1504<dd>Sets properties of a device. May cause <b><tt>undefined</tt></b>, 1505<b><tt>invalidaccess</tt></b>, <b><tt>typecheck</tt></b>, <b><tt>rangecheck</tt></b>, or 1506<b><tt>limitcheck</tt></b> errors. 1507</dl> 1508 1509<dl> 1510<dt><b><tt>- flushpage -</tt></b> 1511<dd>On displays, flushes any buffered output, so that it is guaranteed to 1512show up on the screen; on printers, has no effect. 1513</dl> 1514 1515<hr> 1516 1517<h2><a name="Filters"></a>Filters</h2> 1518 1519<h3><a name="Standard_filters"></a>Standard filters</h3> 1520 1521<p> 1522In its usual configuration, Ghostscript supports all the standard PostScript 1523LanguageLevel 3 filters, both encoding and decoding, except that it does not 1524currently support: 1525 1526<ul> 1527 1528<li>the <b><tt>EarlyChange</tt></b> key in the <b><tt>LZWEncode</tt></b> 1529filter. 1530 1531</ul> 1532 1533<p> 1534Ghostscript also supports additional keys in the optional dictionary 1535operands for some filters. For the <b><tt>LZWDecode</tt></b> filter: 1536 1537<dl> 1538<dt><b><tt>InitialCodeLength <integer></tt></b> (default 8) 1539<dd>An integer between 2 and 11 specifying the initial number of data bits 1540per code. Note that the actual initial code length is 1 greater than this, 1541to allow for the reset and end-of-data code values. 1542</dl> 1543 1544<dl> 1545<dt><b><tt>FirstBitLowOrder <boolean></tt></b> (default false) 1546<dd>If true, codes appear with their low-order bit first. 1547</dl> 1548 1549<dl> 1550<dt><b><tt>BlockData <boolean></tt></b> (default false) 1551<dd>If true, the data is broken into blocks in the manner specified for the 1552GIF file format. 1553</dl> 1554 1555<p> 1556For the <b><tt>CCITTFaxEncode</tt></b> and <b><tt>CCITTFaxDecode</tt></b> 1557filters: 1558 1559<dl> 1560<dt><b><tt>DecodedByteAlign <integer></tt></b> (default 1) 1561<dd>An integer <b>N</b> with the value 1, 2, 4, 8, or 16, specifying that 1562decoded data scan lines are always a multiple of <b>N</b> bytes. The 1563encoding filter skips data in each scan line from Columns to the next 1564multiple of <b>N</b> bytes; the decoding filter pads each scan line to a 1565multiple of <b>N</b> bytes. 1566</dl> 1567 1568<h3><a name="Non_standard_filters"></a>Non-standard filters</h3> 1569 1570<p> 1571In addition to the standard PostScript LanguageLevel 3 filters, Ghostscript 1572supports the following non-standard filters. Many of these filters are used 1573internally to implement standard filters or facilities; they are almost 1574certain to remain, in their present form or a backward-compatible one, in 1575future Ghostscript releases. 1576 1577<dl> 1578<dt><b><tt><target> /BCPEncode filter <file></tt></b> 1579<dt><b><tt><source> /BCPDecode filter <file></tt></b> 1580<dd>Create filters that implement the Adobe Binary Communications Protocol. 1581See Adobe documentation for details. 1582</dl> 1583 1584<dl> 1585<dt><b><tt><target> <seed_integer> /eexecEncode filter <file></tt></b> 1586<dd>Creates a filter for encrypting data into the encrypted format described 1587in the Adobe Type 1 Font Format documentation. The 1588<b><tt>seed_integer</tt></b> must be 55665 for the <b><tt>eexec</tt></b> 1589section of a font, or 4330 for a <b><tt>CharString</tt></b>. Note that for 1590the <b><tt>eexec</tt></b> section of a font, this filter produces binary 1591output and does not include the initial 4 (or <b><tt>lenIV</tt></b>) garbage 1592bytes. 1593</dl> 1594 1595<dl> 1596<dt><b><tt><source> <seed_integer> /eexecDecode filter <file></tt></b> 1597<dt><b><tt><source> <dict> /eexecDecode filter <file></tt></b> 1598<dd>Creates a filter for decrypting data encrypted as described in the Adobe 1599Type 1 Font Format documentation. The <b><tt>seed_integer</tt></b> must be 160055665 or 4330 as described just above. Recognized dictionary keys are: 1601 1602<blockquote> 1603<b><tt>seed <16-bit integer></tt></b> (required)<br> 1604<b><tt>lenIV <non-negative integer></tt></b> (default=4)<br> 1605<b><tt>eexec <bool></tt></b> (default=<b><tt>false</b></tt>) 1606</blockquote> 1607</dl> 1608 1609<dl> 1610<dt><b><tt><target> /MD5Encode filter <file></tt></b> 1611<dd>Creates a filter that produces the 16-byte MD5 digest of the input. 1612Note that no output is produced until the filter is closed. 1613</dl> 1614 1615<dl> 1616<dt><b><tt><source> <hex_boolean> /PFBDecode filter <file></tt></b> 1617<dd>Creates a filter that decodes data in <b><tt>.PFB</tt></b> format, the 1618usual semi-binary representation for Type 1 font files on IBM PC and 1619compatible systems. If <b><tt>hex_boolean</tt></b> is true, binary packets 1620are converted to hex; if false, binary packets are not converted. 1621</dl> 1622 1623<dl> 1624<dt><b><tt><target> <dict> /PixelDifferenceEncode filter <file></tt></b> 1625<dt><b><tt><source> <dict> /PixelDifferenceDecode filter <file></tt></b> 1626<dd>Implements the Predictor=2 pixel-differencing option of the LZW 1627filters. Recognized keys are: 1628 1629<blockquote> 1630<b><tt>Colors <integer></tt></b> (1 to 4, default=1)<br> 1631<b><tt>BitsPerComponent <integer></tt></b> (1, 2, 4, or 8, default=8)<br> 1632<b><tt>Columns <integer></tt></b> (>= 0, required) 1633</blockquote> 1634 1635<p> 1636See the Adobe <a 1637href="http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf"><em>Portable 1638Document Format Reference Manual</em></a> for details. 1639</dl> 1640 1641<dl> 1642<dt><b><tt><target> <dict> /PNGPredictorEncode filter <file></tt></b> 1643<dt><b><tt><source> <dict> /PNGPredictorDecode filter <file></tt></b> 1644<dd>Implements the "filter" algorithms of the 1645<a href="http://www.libpng.org/pub/png/">Portable Network Graphics (PNG) 1646graphics format</a>. Recognized keys are: 1647 1648<blockquote><table cellpadding=0 cellspacing=0> 1649<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Keys recognized in PNG filter algorithms</font><hr> 1650<tr valign=bottom> 1651 <th align=left>Key 1652 <td> 1653 <th align=left>Range 1654 <td> 1655 <th align=left>Default 1656<tr> <td colspan=5><hr> 1657<tr valign=top> <td><b><tt>Colors <integer></tt></b> 1658 <td> 1659 <td>1 to 16 1660 <td> 1661 <td>16 1662<tr valign=top> <td><b><tt>BitsPerComponent <integer></tt></b> 1663 <td> 1664 <td>1, 2, 4, 8, or 16 1665 <td> 1666 <td>8 1667<tr valign=top> <td><b><tt>Columns <integer></tt></b> 1668 <td> 1669 <td>>= 0 1670 <td> 1671 <td>1 1672<tr valign=top> <td><b><tt>Predictor <integer></tt></b> 1673 <td> 1674 <td>10 to 15 1675 <td> 1676 <td>15 1677</table></blockquote> 1678 1679<p> 1680The <b><tt>Predictor</tt></b> is the PNG algorithm number + 10 for the 1681<b><tt>Encoding</tt></b> filter; the <b><tt>Decoding</tt></b> filter 1682ignores <b><tt>Predictor</tt></b>. 15 means the encoder attempts to 1683optimize the choice of algorithm. For more details see the PNG 1684specification 1685 1686<blockquote> 1687<a href="http://www.w3.org/TR/WD-png-960128.html">http://www.w3.org/TR/WD-png-960128.html</a> 1688</blockquote> 1689</dl> 1690 1691<dl> 1692<dt><b><tt><target> /TBCPEncode filter <file></tt></b> 1693<dt><b><tt><source> /TBCPDecode filter <file></tt></b> 1694<dd>Create filters that implement the Adobe Tagged Binary Communications 1695Protocol. See Adobe documentation for details. 1696</dl> 1697 1698<dl> 1699<dt><b><tt><target> /zlibEncode filter <file></tt></b> 1700<dt><b><tt><source> /zlibDecode filter <file></tt></b> 1701<dd>Creates filters that use the data compression method variously known as 1702'zlib' (the name of a popular library that implements it), 'Deflate' (as in 1703<a href="http://www.ietf.org/rfc/rfc1951.txt">RFC 1951</a>, which is a 1704detailed specification for the method), 'gzip' (the name of a popular 1705compression application that uses it), or 'Flate' (Adobe's name). Note that 1706the PostScript <b><tt>Flate</tt></b> filters are actually a combination of 1707this filter with an optional predictor filter. 1708</dl> 1709 1710<h3><a name="Unstable_filters"></a>Unstable filters</h3> 1711 1712<p> 1713Some versions of Ghostscript may also support other non-standard filters for 1714experimental purposes. The current version includes the following such 1715filters, which are not documented further. No code should assume that these 1716filters will exist in compatible form, or at all, in future versions. 1717 1718<dl> 1719<dt><b><tt><target/source> <string> ByteTranslateEncode/Decode filter <file></tt></b> 1720<dd><b><tt>string</tt></b> must be a string of exactly 256 bytes. Creates a 1721filter that converts each input byte <em>b</em> to 1722<b><tt>string</tt></b>[<em>b</em>]. Note that the <b><tt>Encode</tt></b> 1723and <b><tt>Decode</tt></b> filters operate identically: the client must 1724provide a <b><tt>string</tt></b> for the <b><tt>Decode</tt></b> filter that 1725is the inverse mapping of the <b><tt>string</tt></b> for the 1726<b><tt>Encode</tt></b> filter. 1727</dl> 1728 1729<dl> 1730<dt><b><tt><target/source> <dict> BoundedHuffmanEncode/Decode filter <file></tt></b> 1731<dd>These filters encode and decode data using Huffman codes. Since these 1732filters aren't used anywhere, we don't document them further, except to note 1733the recognized dictionary keys, which must be set identically for encoding 1734and decoding: 1735 1736<blockquote> 1737<b><tt>FirstBitLowOrder <bool></tt></b> (default=false)<br> 1738<b><tt>MaxCodeLength <int></tt></b> (default=16)<br> 1739<b><tt>EndOfData <bool></tt></b> (default=true)<br> 1740<b><tt>EncodeZeroRuns <int></tt></b> (default=256)<br> 1741<b><tt>Tables <int_array></tt></b> 1742</blockquote> 1743</dl> 1744 1745<dl> 1746<dt><b><tt><target/source> <dict> BWBlockSortEncode/Decode filter <file></tt></b> 1747<dd>This filter implements the Burroughs-Wheeler block sorting compression 1748method, which we've heard is also used in the popular <b><tt>bzip2</tt></b> 1749compression application. See <a 1750href="http://sources.redhat.com/bzip2/">http://sources.redhat.com/bzip2/</a> 1751for more information. The only recognized dictionary key is: 1752 1753<blockquote> 1754<b><tt>BlockSize <integer></tt></b> (default=16384) 1755</blockquote> 1756</dl> 1757 1758<dl> 1759<dt><b><tt><target/source> MoveToFrontEncode/Decode filter <file></tt></b> 1760 1761<dd>The <b><tt>Encode</tt></b> filter starts by initializing an internal 1762256-byte array <b><tt>a</tt></b> to the values 0 .. 255. This array will 1763always hold a permutation of these values. Then for each input byte 1764<em>b</em>, the filter outputs the index <em>i</em> such that 1765<b><tt>a</tt></b>[<em>i</em>] = <em>b</em>, and moves that element to the 1766front (element 0) of <b><tt>a</tt></b>, moving elements 0 .. <em>i-1</em> to 1767positions 1 .. <em>i</em>. The <b><tt>Decode</tt></b> filter inverts this 1768process. 1769</dl> 1770 1771<hr> 1772 1773<h2><a name="Device_parameters"></a>Device parameters</h2> 1774 1775Ghostscript supports the concept of device parameters for all devices, not 1776just page devices. (For non-page devices, these are accessible through 1777<b><tt>getdeviceprops</tt></b> and <b><tt>putdeviceprops</tt></b>, as 1778indicated above.) Here are the currently defined parameters for all 1779devices: 1780 1781<dl> 1782<a name="LockSafetyParams"></a> 1783<dt><b><tt>.LockSafetyParams <boolean></tt></b> 1784<dd>This parameter allows for improved system security by preventing 1785PostScript programs from being able to change potentially dangerous 1786device paramters such as OutputFile. This parameter cannot be set false 1787if it is already true. 1788<p> 1789If this parameter is true for the current device, attempt to set a new 1790device that has <b><tt>.LockSafetyParams</tt></b> false will signal an 1791<tt><b> invalidaccess</b></tt> error. 1792</dl> 1793 1794<dl> 1795<dt><b><tt>BitsPerPixel <integer> (usually read-only)</tt></b> 1796<dd>Number of bits per pixel. 1797</dl> 1798 1799<dl> 1800<dt><b><tt>.HWMargins [<four floats>]</tt></b> 1801<dd>Size of non-imageable regions around the edges of the page, in points 1802(units of 1/72in; see the <a href="Devices.htm#Measurements">notes on 1803measurements</a> in the documentation on devices). 1804</dl> 1805 1806<dl> 1807<dt><b><tt>HWSize [<integer> <integer>]</tt></b> 1808<dd>X and Y size in pixels. 1809</dl> 1810 1811<dl> 1812<dt><b><tt>Name <string> (read-only)</tt></b> 1813<dd>The device name. Currently the same as <b><tt>OutputDevice</tt></b>. 1814</dl> 1815 1816<dl> 1817<dt><b><tt>Colors, GrayValues, RedValues, GreenValues, BlueValues, ColorValues (usually read-only)</tt></b> 1818<dd>As for the <b><tt>deviceinfo</tt></b> operator of Display PostScript. 1819<b><tt>Red</tt></b>, <b><tt>Green</tt></b>, <b><tt>Blue</tt></b>, and 1820<b><tt>ColorValues</tt></b> are only defined if 1821<b><tt>Colors</tt></b> > 1. 1822</dl> 1823 1824<dl> 1825<dt><b><tt>TextAlphaBits, GraphicsAlphaBits (usually read-only)</tt></b> 1826<dd>The number of bits of anti-aliasing information for text or graphics 1827respectively. Legal values are 1 (no anti-aliasing, the default for most 1828devices), 2, or 4. 1829</dl> 1830 1831<p> 1832Ghostscript also supports the following read-only parameter that is not a 1833true device parameter: 1834 1835<dl> 1836<dt><b><tt>.EmbedFontObjects <integer></tt></b> 1837<dd>If non-zero, indicates that the device may embed font objects (as 1838opposed to bitmaps for individual characters) in the output. The purpose of 1839this parameter is to disable third-party font renderers for such devices. 1840(This is zero for almost all devices.) 1841</dl> 1842 1843<p> 1844In addition, the following are defined per Adobe's documentation for the 1845<b><tt>setpagedevice</tt></b> operator: 1846 1847<blockquote> 1848<b><tt>Duplex</tt></b> (if supported)<br> 1849<b><tt>HWResolution</tt></b><br> 1850<b><tt>ImagingBBox</tt></b><br> 1851<b><tt>Margins</tt></b><br> 1852<b><tt>NumCopies</tt></b> (for printers only)<br> 1853<b><tt>Orientation</tt></b> (if supported)<br> 1854<b><tt>OutputDevice</tt></b><br> 1855<b><tt>PageOffset</tt></b> (write-only)<br> 1856<b><tt>PageSize</tt></b><br> 1857<b><tt>ProcessColorModel</tt></b> (usually read-only)<br> 1858</blockquote> 1859 1860<p> 1861Some devices may only allow certain values for <b><tt>HWResolution</tt></b> 1862and <b><tt>PageSize</tt></b>. The null device ignores attempts to set 1863<b><tt>PageSize</tt></b>; its size is always <b><tt>[0 0]</tt></b>. 1864 1865<p> 1866It should be noted that calling <tt>setpagedevice</tt> with one of the above keys may reset the effects of any <b><tt>pdfmark</tt></b> commands up to that point. In particular this is true of HWResolution, a behavior that differs from Adobe Distiller. 1867 1868<p> 1869For printers these are also defined: 1870 1871<dl> 1872<dt><b><tt>BufferSpace <integer></tt></b> 1873<dd>Buffer space for band lists, if the bitmap is too big to fit in memory. 1874</dl> 1875 1876<dl> 1877<dt><b><tt>MaxBitmap <integer></tt></b> 1878<dd>Maximum space for a full bitmap in memory. 1879</dl> 1880 1881<dl> 1882<dt><b><tt>OutputFile <string></tt></b> 1883 1884<dd>An empty string means "send to printer directly", otherwise specifies 1885the file name for output; <b><tt>%d</tt></b> is replaced by the page number 1886for page-oriented output devices; 1887on Unix systems <b><tt>%pipe%</tt></b><em>command</em> writes to a pipe. 1888(<b><tt>|</tt></b><em>command</em> also writes to a pipe, but is now 1889deprecated.) 1890<p> 1891Attempts to set this parameter if <tt><b>.LockSafetyParams</b></tt> is true 1892will signal an <tt><b>invalidaccess</b></tt> error. 1893</dl> 1894 1895<dl> 1896<dt><b><tt>OpenOutputFile <boolean></tt></b> 1897<dd>If true, open the device's output file when the device is opened, 1898rather than waiting until the first page is ready to print. 1899</dl> 1900 1901<dl> 1902<dt><b><tt>PageCount <integer> (read-only)</tt></b> 1903<dd>Counts the number of pages printed on the device. 1904</dl> 1905 1906<p> 1907The following parameters are for use only by very specialized applications 1908that separate band construction from band rasterization. Improper use may 1909cause unpredictable errors. In particular, if you only want to allocate 1910more memory for banding, to increase band size and improve performance, use 1911the <b><tt>BufferSpace</tt></b> parameter, not 1912<b><tt>BandBufferSpace</tt></b>. 1913 1914<dl> 1915<dt><b><tt>BandHeight <integer></tt></b> 1916<dd>The height of bands when banding. 0 means use the largest band height 1917that will fit within the BandBufferSpace (or BufferSpace, if 1918BandBufferSpace is not specified). 1919</dl> 1920 1921<dl> 1922<dt><b><tt>BandWidth <integer></tt></b> 1923<dd>The width of bands in the rasterizing pass, in pixels. 0 means use the 1924actual page width. 1925</dl> 1926 1927<dl> 1928<dt><b><tt>BandBufferSpace <integer></tt></b> 1929<dd>The size of the band buffer in the rasterizing pass, in bytes. 0 means 1930use the same buffer size as for the interpretation pass. 1931</dl> 1932 1933<p> 1934Ghostscript supports the following parameter for 1935<b><tt>setpagedevice</tt></b> and <b><tt>currentpagedevice</tt></b> that is 1936not a device parameter per se: 1937 1938<dl> 1939<dt><b><tt>ViewerPreProcess <procedure></tt></b> 1940<dd>Specifies a procedure to be applied to the page device dictionary 1941before any other processing is done. The procedure may not alter the 1942dictionary, but it may return a modified copy. This "hook" is provided for 1943use by viewing programs such as GSview. 1944</dl> 1945 1946<hr> 1947 1948<h2><a name="User_parameters"></a>User parameters</h2> 1949 1950Ghostscript supports the following non-standard user parameters: 1951 1952<dl> 1953<dt><b><tt>ProcessDSCComment <procedure|null></tt></b> 1954<dd>If not null, this procedure is called whenever the scanner detects a DSC 1955comment (comment beginning with <b><tt>%%</tt></b> or <b><tt>%!</tt></b>). 1956There are two operands, the file and the comment (minus any terminating 1957EOL), which the procedure must consume. 1958</dl> 1959 1960<dl> 1961<dt><b><tt>ProcessComment <procedure|null></tt></b> 1962<dd>If not null, this procedure is called whenever the scanner detects a 1963comment (or, if <b><tt>ProcessDSCComment</tt></b> is also not null, a 1964comment other than a DSC comment). The operands are the same as for 1965<b><tt>ProcessDSCComment</tt></b>. 1966</dl> 1967 1968<dl> 1969<dt><b><tt>LockFilePermissions <boolean></tt></b> 1970<dd>If <tt>true</tt>, this parameter and the three <tt>PermitFile...</tt> 1971parameters cannot be changed. Attempts to change any of the values 1972when LockFilePermissions is <tt>true</tt> will signal <b><tt>invalidaccess</tt></b>. 1973Also, when this value is <tt>true</tt>, the <b><tt>file</tt></b> operator 1974will give <b><tt>invalidaccess</tt></b> when attempting to open files 1975(processes) using the <b><tt>%pipe</tt></b> device. 1976<p> 1977Also when <b><tt>LockFilePermissions</tt></b> is <tt>true</tt>, strings 1978cannot reference the parent directory (platform specific). For example 1979<b><tt>(../../xyz)</tt></b> is illegal on unix, Windows 1980and Macintosh, and <b><tt>([.#.#.XYZ])</tt></b> is illegal on VMS. 1981<p> 1982This parameter is set <tt>true</tt> by the <b><tt>.setsafe</tt></b> and 1983<b><tt>.locksafe</tt></b> operators. 1984</dl> 1985 1986<dl> 1987<dt><b><tt>PermitFileReading <array of strings></tt></b> 1988<dt><b><tt>PermitFileWriting <array of strings></tt></b> 1989<dt><b><tt>PermitFileControl <array of strings></tt></b> 1990<dd>These parameters specify paths where file reading, writing and the 1991'control' operations are permitted, respectively. File control 1992operations are <b><tt>deletefile</tt></b> and <b><tt>renamefile</tt></b>. 1993For <b><tt>renamefile</tt></b>, the filename for the current filename 1994must match one of the paths on the PermitFileControl list, and the 1995new filename must be on <b>both</b> the PermitFileControl and the 1996PermitFileWriting lists of paths. 1997<p> 1998The strings can contain wildcard characters as for the <b><tt>filenameforall</tt></b> 1999operator and unless specifying a single file, will end with a <b>*</b> 2000for directories (folders) to allow access to all files and sub-directories 2001in that directory. 2002<p> 2003<b>Note:</b> The strings are used for stringmatch operations similar 2004to <b><tt>filenameforall</tt></b>, thus on MS Windows platforms, use the '/' 2005character to separate directories and filenames or use '\\\\' to 2006have the string contain '\\' which will match a single '\' in the 2007target filename (use of '/' is strongly recommended). 2008<p> 2009The <a href=Use.htm#Safer><b>SAFER</b></a> mode and the 2010<b><tt>.setsafe</tt></b> operator set all three lists to empty arrays, 2011thus the only files that can be read are the <b><tt>%stdin</tt></b> device and 2012on LIBPATH or FONTPATH or the Resource paths specified by the /FontResourceDir 2013or /GenericResourceDir system params. Files cannot be opened for writing 2014anywhere and cannot be deleted or renamed except for files created with the 2015<a href=#Tempfile><b>.tempfile</b></a> operator). 2016<p> 2017<b>Note: </b>Limiting file reading as above is <b>NOT</b> compatible with 2018SAFER mode in release versions before 7.11 and corresponds to the use of 2019<b><tt>-dPARANOIDSAFER</tt></b> in version 7.04 (up to and not including 2020version 7.10) and GPL versions 6.53 (up to and not including 6.60). 2021</dl> 2022 2023<dl> 2024<dt><b><tt>AlignToPixels <integer></tt></b> 2025<dd>Control sub-pixel positioning of character glyphs (where 2026applicable). A value of 1 specifies alignment of text characters to 2027pixels boundaries. A value of 0 to subpixels where the division factor 2028is set by the device parameter <b><tt>TextAlphaBits</tt></b>. If the 2029latter is 1, the same rendering results regardless of the value of 2030<b><tt>AlignToPixels</tt></b>. The initial value defaults to 1, but this 2031may be overridden by the command line argument 2032<b><tt>-dAlignToPixels</tt></b>. 2033</dl> 2034 2035 2036<dl> 2037<a name="GridFitTT"></a> 2038<dt><b><tt>GridFitTT <integer></tt></b> 2039<dd>Control the use of True Type grid fitting. 2040Ghostscript implements a reduced True Type bytecode interpreter, 2041which can interpret the subset of True Type glyph instructions 2042not covered by Apple's patents. This allows proper rasterization 2043of the Dynalab fonts. 2044<p> 2045The reduced interpreter can't properly grid fit 2046fonts with patented instructions. Therefore Ghostscript implements 2047another grid fitting method for True Type fonts, based on a spot topology analysis. 2048<p> 2049This parameter controls the action of the reduced interpreter and the grid fitter: 2050<ul> 2051<li> 2052A value of 0 disables grid fitting for all True Type fonts. This is a backward compatibility mode. 2053</li> 2054 2055<li> 2056A value of 1 enables the grid fitting for glyphs that don't involve 2057patented instructions, using the reduced True Type bytecode interpreter. 2058When a patented instruction is encountered, a warning is printed to stderr, 2059and the glyph is rendered ignoring the entire grid fitting program. 2060</li> 2061 2062<li> 2063A value of 2 invokes the topological grid fitter. This value is recommended 2064for common use. 2065</li> 2066 2067<li> 2068A value of 3 specifies that the bytecode interpreter to be used 2069to grid fit glyphs that have no patented instructions, 2070and other glyphs are grid fitted topologically. This mode may 2071improve the rendering of some fonts, but in general the best result 2072is not guaranteed. 2073</li> 2074</ul> 2075<p> 2076This parameter defaults to 2, but this 2077may be overridden on the command line with 2078<b><tt>-dGridFitTT=n</tt></b>. 2079<p> 2080The reduced bytecode interpreter is based in part of the work of the 2081<a href="http://freetype.org/">FreeType</a> Team. 2082The topological grid fitting is a new original Ghostscript method. 2083</dl> 2084 2085<dl> 2086<dt><b><tt>UseWTS <boolean></tt></b> 2087<dd>If <tt>true</tt>, and if AccurateScreens are specified (either as 2088a user parameter, or as a type 1 halftone dictionary parameter), then 2089the Well Tempered Screening algorithm is used for 2090halftoning. Otherwise, a rational tangent algorithm is chosen, which 2091will typically result in significant differences between the screen 2092angle and ruling requested, and actually rendered. Currently, the 2093performance of WTS is reasonably good when rendering to a full page 2094buffer, but not optimized for banded mode. Thus, when using WTS, 2095disable banding (setting 2096<b><tt>-dMaxBitmap=500000000</tt></b> should work). In a future 2097version, WTS will be optimized for banded mode, and 2098<b><tt>UseWTS</tt></b> will be <tt>true</tt> by default. 2099 2100<p> 2101<b>Note:</b> Currently, <b><tt>UseWTS</tt></b> can only be set using 2102the PostScript user parameters mechanism, not on the command line with 2103a <b><tt>-d</tt></b> switch. Use this code to enable it: 2104 2105<blockquote><pre> 2106<< /UseWTS true >> setuserparams 2107</pre></blockquote> 2108</dl> 2109 2110<hr> 2111 2112<h2><a name="Miscellaneous_additions"></a>Miscellaneous additions</h2> 2113 2114<h3><a name="Extended_semantics_of_run"></a>Extended semantics of 'run'</h3> 2115 2116<p> 2117The operator <b><tt>run</tt></b> can take either a string or a file as its argument. In 2118the latter case, it just runs the file, closing it at the end, and trapping 2119errors just as for the string case. 2120 2121<h3><a name="DecodingResources"></a>Decoding resources</h3> 2122 2123<p> 2124<b><tt>Decoding</tt></b> is a Ghostscript-specific resource category. It contains 2125various resources for emulating PostScript fonts with other font technologies. 2126Instances of the <tt>Decoding</tt> category are tables which map PostScript glyph 2127names to character codes used with TrueType, Intellifont, Microtype and other font formats. 2128 2129<p> 2130Currently Ghostscript is capable of PostScript font emulation in 2 ways : 2131<li> 21321. Through <a href="./Use.htm#FAPI_run">FAPI</a> plugins, and 2133</li> 2134<li> 21352. With TrueType font files, using the native font renderer, by 2136specifying TrueType font names or files in <a href="../lib/Fontmap">lib/Fontmap</a>. 2137</li> 2138<p> 2139<b><tt>Decoding</tt></b> resources are not current used by the native font renderer. 2140 2141<p> 2142An instance of the <b><tt>Decoding</tt></b> resource category is 2143a dictionary. The dictionary keys are PostScript glyph names and the 2144values are character codes. The name of the resource instance should 2145reflect the character set for which it maps. For example, 2146<b><tt>/Unicode</tt></b> <b><tt>/Decoding</tt></b> resource maps to 2147Unicode UTF-16. 2148 2149<p> 2150The rules for using <b><tt>Decoding</tt></b> resources in particular 2151cases are specified in the configuration file 2152<a href="../lib/xlatmap">lib/xlatmap</a>. See the file itself for more 2153information. 2154 2155<p> 2156The file format for <b><tt>Decoding</tt></b> resource files is 2157generic PostScript. 2158Users may want to define custom <b><tt>Decoding</tt></b> resources. 2159The <b><tt>ParseDecoding</tt></b> procset defined in 2160<a href="../lib/gs_ciddc.ps">lib/gs_ciddc.ps</a> allows representation 2161of the table in a comfortable form. 2162 2163 2164<h3><a name="CIDDecodingResources"></a>CIDDecoding resources</h3> 2165 2166<p> 2167<b><tt>CIDDecoding</tt></b> resources are similar to <b><tt>Decoding</tt></b> 2168resources, except they map Charaacter Identifiers (CIDs) rather than glyph names. 2169Another difference is that the native Ghostscript font renderer already uses 2170<b><tt>CIDDecoding</tt></b> resources while emulate CID fonts with TrueType. 2171 2172<p> 2173An instance of the <b><tt>CIDDecoding</tt></b> resource category is 2174a dictionary of strings. Keys in the dictionary are integers, 2175which correspond to high order byte of a CID. Values are 2176512-bytes strings. Each string represents 256 character codes, 2177corresponding various values of the lower byte of CID. 2178Each character code ocupies 2 bytes, high order byte first. 2179Two zero bytes represent mapping to the default character. 2180 2181<p> 2182The Ghostscript library is capable of generating some <b><tt>CIDDecoding</tt></b> 2183instances automatically, using the appropriate <b><tt>CMap</tt></b> (character map) 2184resources. This covers most of practical cases if the neccessary <b><tt>CMap</tt></b> 2185resources are provided. See the table <b><tt>.CMapChooser</tt></b> in 2186<a href="../lib/gs_ciddc.ps">lib/gs_ciddc.ps</a> 2187for the names of automatically gerenated resources and associated <b><tt>CMap</tt></b>s. 2188They allow to mapping CNS1, GB1, Japan1, Japan2 and Korea1 CID sets to TrueType 2189character sets known as Unicode (exactly UTF-16), Big5, 2190GB1213, ShiftJIS, Johab and Wansung. 2191 2192<p> 2193The file format for <b><tt>CIDDecoding</tt></b> resource file is 2194generic PostScript. 2195Users may want to define custom resources to <b><tt>CIDDecoding</tt></b> 2196resource category. 2197 2198<h3><a name="GlyphNames2Unicode"></a>GlyphNames2Unicode</h3> 2199<p> 2200<b><tt>GlyphNames2Unicode</tt></b> is an undocumented dictionary which Adobe 2201PostScript printer driver uses to communicate with Adobe Distiller. 2202In this dictionary the keys are glyph names, the values are Unicode UTF-16 codes for them. 2203The dictionaly is stored in the <b><tt>FontInfo</tt></b> dictionary under 2204the key <b><tt>GlyphNames2Unicode</tt></b>. Ghostscript recognises it and uses 2205to generate <b><tt>ToUnicode</tt></b> CMaps with pdfwrite. 2206<p> 2207 2208<h3><a name="MultipleResourceDirectories"></a>Multiple Resource directories</h3> 2209 2210<p> 2211Since 8.10 release Ghostscript maintains multiple resource directories. 2212 2213<p> 2214Ghostscript does not distinguish <b><tt>lib</b></tt> and <b><tt>Resource</b></tt> directories. 2215There is no file name conflicts because 2216<b><tt>lib</b></tt> does not contain subdirectories, but <b><tt>Resource</b></tt> 2217always store files in subdirectories. 2218 2219<p> 2220The search method with multiple resource directories 2221appears not fully conforming to PLRM. We cannot unconditionally call 2222<b><tt>ResourceFileName</b></tt> while executing <b><tt>findresource</b></tt> 2223or <b><tt>resourcestatus</b></tt>, <b><tt>resourceforall</b></tt>, because per PLRM it always 2224returns a single path. Therefore Ghostscript implements 2225an extended search method in <b><tt>findresource</b></tt>, 2226<b><tt>resourcestatus</b></tt> and <b><tt>resourceforall</b></tt>, which first calls 2227<b><tt>ResourceFileName</b></tt> and checks whether the returned path 2228points to an existing file. If yes, the file is used, 2229othervise Ghostscript searches all directories specified in 2230<b><tt>LIB_PATH</tt></b>. With a single resource directory 2231it appears conforming to PLRM and equivalent to Adobe implementations. 2232 2233<p> 2234<b><tt>ResourceFileName</b></tt> may be used for obtaining a path 2235where a resource file to be installed. In this case 2236Ghostscript to be invoked with <b><tt>-sGenericResourceDir=path</b></tt>, 2237specifying an absolute path. The default value for 2238<b><tt>GenericResourceDir</b></tt> is a relative path. Therefore 2239a default invocation with a PostScript installer 2240will install resource files into <b><tt>/gs/Resource</tt></b>. 2241 2242<p> 2243 2244<!-- [2.0 end contents] ==================================================== --> 2245 2246<!-- [3.0 begin visible trailer] =========================================== --> 2247<hr> 2248 2249<p> 2250<small>Copyright © 1996-2005 artofcode LLC. All rights 2251reserved.</small> 2252 2253<p> 2254This software is provided AS-IS with no warranty, either express or 2255implied. 2256 2257This software is distributed under license and may not be copied, 2258modified or distributed except as expressly authorized under the terms 2259of the license contained in the file LICENSE in this distribution. 2260 2261For more information about licensing, please refer to 2262http://www.ghostscript.com/licensing/. For information on 2263commercial licensing, go to http://www.artifex.com/licensing/ or 2264contact Artifex Software, Inc., 101 Lucas Valley Road #110, 2265San Rafael, CA 94903, U.S.A., +1(415)492-9861. 2266 2267<p> 2268<small>Ghostscript version 8.53, 20 October 2005 2269 2270<!-- [3.0 end visible trailer] ============================================= --> 2271 2272</body> 2273</html> 2274