File handling macros

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

The following two macros define values for invalid file and directory handles, respectively:

`PLGFWFILE_ROGUE`	An invalid file handle.
`PLGFWDIR_ROGUE`	An invalid directory handle.

The following macros define discrete values for file object types. Not all of these apply to all plat‐ forms. To find out if a particular type applies to your platform, supply it to the

PLGFWFILE_TYPE POSSIBLE macro:

`PLGFWFILE_TYPE_DIR`	A directory
`PLGFWFILE_TYPE_FILE`	A file
`PLGFWFILE_TYPE_UNKNOWN`	An unknown file type.

This macro tests a file type value to see if it is relevant to the current platform. It returns TRUE if it applies to the platform; FALSE if it does not.

PLGFWFILE_TYPE POSSIBLE(type)

Returns TRUE if the submitted type is relevant to the platform.

These two macros define generic flags which apply individually or collectively to several of the functions listed below, as noted:

`PLGFWFILE_FLAG_RECURSIVE`	Recurse into the directory tree.
`PLGFWFILE_FLAG_CAN_EXIST`	Do not raise an error if the object already exists.

The following macros define bit flags which determine the access with which a file is to be opened. Only one of the bits should be set:

`PLGFW_OPEN_RDONLY`	Open with read only access
`PLGFW_OPEN_WRONLY`	Open with write only access
`PLGFW_OPEN_RDWR`	Open with read and write access

The following macros define bit flags which refine the treatment of a file opened for writing. These flags are only relevant if the file is being opened for writing:

`PLGFW_OPEN_APPEND`	Open to append
`PLGFW_OPEN_CREAT`	Create the file if it does not already exist
`PLGFW_OPEN_APPEND`	Truncate the file to zero length

This flag attempts to open a file with exclusive access. Depending on the platform, this may or may not have any effect:

PLGFW_OPEN_EXCL

Open the file with exclusive access

This flag directs the file management system to optimize for sequential access. On some platforms this bit allows the file management system to improve performance when accessing a file sequentially, with the side effect that non‐sequential access could be less efficient as a result. It may be ignored if PLGFW_OPEN_EXCL is also set:

PLGFW_OPEN_OPTIMISE_SEQUENTIAL

Open the file with optimization for sequential access

These three flags specify the way in which a file offset is to be used by a seek operation:

`PLGFW_SEEK_SET`	The offset is an absolute offset from the beginning of the file
`PLGFW_SEEK_INCR`	The offset is relative to the current file position
`PLGFW_SEEK_XTND`	The offset is relative to the end of the file
`PLGFWFILE_INFO_LINK`	Do not use. This flag is deprecated as it is only relevant to UNIX and Macintosh platforms.