Postscript Operators 'f'

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

ERRORS: stackoverflow

SEE ALSO: true, and,

or, not, xor

Troubleshooting index Back to Postscript index

file filename access file file

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

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

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

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

ERRORS: invalidfileaccess, ioerror,

limitcheck, stackunderflow,

typecheck, undefinedfilename

SEE ALSO: closefile, currentfile,

filter, status

Troubleshooting index Back to Postscript index

filenameforall template proc scratch filenameforall - LEVEL 2

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

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

* matches zero or more consecutive characters.

? matches exactly one character.

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

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

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

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

ERRORS: invalidaccess, ioerror,

rangecheck, stackoverflow,

stackunderflow, typecheck

SEE ALSO: file, status

Troubleshooting index Postscript Index

fileposition file fileposition position LEVEL 2

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

ERRORS: ioerror, stackunderflow,

typecheck

SEE ALSO: setfileposition, file

Troubleshooting index Back to Postscript index

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

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

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

gsave fill grestore

ERRORS: limitcheck

SEE ALSO: clip, eofill,

stroke, ufill

Troubleshooting index Back to Postscript index

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

creates and returns a filtered file.

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

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

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

ASCIIHexEncode ASCIIHexDecode

ASCII85Encode ASCII85Decode

LZWEncode LZWDecode

RunLengthEncode RunLengthDecode

CCITTFaxEncode CCITTFaxDecode

DCTEncode DCTDecode

NullEncode SubFileDecode

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

ERRORS: limitcheck, undefined,

typecheck, rangecheck,

stackunderflow, invalidaccess

SEE ALSO: file, closefile,

resourceforall

Troubleshooting index Back to Postscript index

findencoding key findencoding array LEVEL 2

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

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

ERRORS: stackunderflow, typecheck,

undefinedresource

SEE ALSO: findresource, StandardEncoding,

ISOLatin1Encoding

Troubleshooting index Back to Postscript index

findfont key findfont font

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

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

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

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

ERRORS: invalidfont, stackunderflow,

typecheck

SEE ALSO: scalefont, makefont,

setfont, selectfont,

definefont, findresource,

FontDirectory, GlobalFontDirectory

Troubleshooting index Back to Postscript index

findresource key category findresource instance LEVEL 2

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

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

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

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

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

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

ERRORS: stackunderflow, typecheck,

undefined, undefinedresource

SEE ALSO: defineresource, resourcestatus,

resourceforall, undefineresource

Troubleshooting index Back to Postscript index

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

This "flattening" of curves to straight line segments is done automatically when a path is used to control painting (for example, by stroke,

fill, or clip). Only rarely does a program need to flatten a path explicitly (see pathbbox). The accuracy of the approximation to the curve is controlled by the current flatness parameter in the graphics state (see setflat).

ERRORS: limitcheck

SEE ALSO: setflat, curveto,

lineto, pathbbox

Troubleshooting index Back to Postscript index

floor num1 floor num2

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

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

ERRORS: stackunderflow, typecheck

SEE ALSO: ceiling, round,

truncate, cvi

Troubleshooting index Back to Postscript index

flush - flush

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

ERRORS: ioerror

SEE ALSO: flushfile, print

Troubleshooting index Back to Postscript index

flushfile file flushfile

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

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

ERRORS: ioerror, stackunderflow,

typecheck

SEE ALSO: flush, read,

write

Troubleshooting index Back to Postscript index

FontDirectory - FontDirectory dict

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

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

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

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

ERRORS: stackoverflow

SEE ALSO: definefont, undefinefont,

findfont, findresource,

GlobalFontDirectory

Troubleshooting index Back to Postscript index

for initial increment limit proc for -

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

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

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

EXAMPLE:
0 1 1 4 /{

add} for -> 10
1 2 6 /{

} for -> 1 3 5
3 -.5 1 /{

-> } for -> 3.0 2.5 2.0 1.5 1.0

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

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

ERRORS: stackoverflow stackunderflow,

typecheck

SEE ALSO: repeat, loop,

forall, exit

Troubleshooting index Postscript Index

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

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

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

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

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

EXAMPLE:
0 [13 29 3 -8 21] /{

add} forall -> 58
/d 2 dict def
d /abc 123 put
d /xyz (test) put
d /{

} forall -> /xyz (test) /abc 123

ERRORS: invalidaccess, stackoverflow

stackunderflow, typecheck

SEE ALSO: for, repeat,

loop, exit

Troubleshooting index Back to Postscript index

fork mark obj1 ... objn proc fork context DPS

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

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

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

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

proc stopped /{

handleerror quit} if
% ...Wait for join or detach...
quit

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

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

ERRORS: invalidaccess, invalidcontext,

limitcheck, stackunderflow,

typecheck, unmatchedmark

SEE ALSO: join, detach,

currentcontext

Troubleshooting index Back to Postscript index

Original file name: PSL2f