(v13) open_file open a file on the device

This page applies to Harlequin v13.1r0 and later; and to Harlequin Core but not Harlequin MultiRIP

DEVICE_FILEDESCRIPTOR open_file ( DEVICELIST * dev, uint8 *filename; int32 openflags);

For a device-relative device, filename gives a NUL-terminated name. For a single-file device, the filename is undefined and should be ignored.

The openflags parameter is one of the following (defined in swdevice.h ):

TEXT

                            SW_RDONLY
                            SW_WRONLY
                            SW_RDWR
                            SW_APPEND
                            SW_CREAT
                            SW_TRUNC
                            SW_EXCL

The return value is -1 if the file could not be opened, or the descriptor if it succeeds. This descriptor is passed to other calls for this device to indicate which file the operation is intended for.

Descriptors have to be unique only for each device; different devices (even of the same device type) can use the same number for different files without confusion.

last_error should be one of:

`DeviceUndefined`	If the filename is invalid for the device, or the file does not exist and the value of `openflags` does not imply creation (but see (v13) Files and file names ).
`DeviceInvalidAccess`	If the requested access status values, set by `openflags` , are not allowed for this file.
`DeviceLimitCheck`	If the file cannot be opened because to do so would exceed some implementation-defined limit on the number of open files.
`DeviceIOError`	Other errors should cause `last_error` to return `DeviceIOError` .

As discussed above, the PostScript language model of files is of a stream of bytes; that is, there is no record structure or distinction between binary and text files. The implementation of the open_file call must open the file in the appropriate way to support this (for example, by opening all files in binary mode on MS-DOS).

As an example, on a UNIX system, the file system device open routine could prefix the file name with a prefix stored in the device's private structure, and then call the system open call. Devices with different prefixes would represent directory trees rooted at different places in the underlying UNIX directory tree.

For a device implementing a socket communication channel, the routine could perform the appropriate bind, listen , and accept calls to open a socket stream when opening the file for writing, or the connect call when opening the file for reading.

Note that the PostScript language defines that when a file is opened that does not explicitly specify a device in the name passed to the file or run operator (or whatever), the file is created on the first device on which it can be opened successfully.