Virtual Memory: 3.2 Using Virtual Memory: Opening or Creating a VM File

• File name
  This argument is a pointer to a string of characters. This string is a relative or absolute path specifying the file to open; if a temporary file is being created, the string is the path of the directory in which to place that file, followed by fourteen null bytes (counting the string-ending null). The name of the temporary file is appended to the path.
• VMAccessFlags
This argument is a set of flags which specifies how the file is accessed. The flags are described below.
• VMOpenType enumerated type
  This argument specifies how the file should be opened. The VMOpenType are described below.
• Compaction threshold
  This is the minimum percentage of a file which must be used for data at any given time. If the percentage drops below this threshold, the file is compacted. If you pass a threshold of zero, the system default threshold is used. The compaction threshold is set only when the file is created; this argument is ignored if an existing file is opened.

When you use VMOpen() , you must specify how the file should be opened. You do this by passing a member of the VMOpenType enumerated type. The types are as follows:

VMO_TEMP_FILE

If this is passed, the file will be a temporary data file. When you create a temporary file, you pass a directory path, not a file name. The path should be followed by fourteen null bytes, including the string's terminating null. The system will choose an appropriate file name and add it to the path string.

VMO_CREATE_ONLY

If this is passed, the document will be created. If a document with the specified name already exists in the working directory, VMOpen() will return an error condition.

VMO_CREATE

If this is passed, the file will be created if it does not already exist; otherwise it will be opened.

VMO_CREATE_TRUNCATE

If this is passed, the file will be created if it does not already exist; otherwise, it will be opened and truncated (all data blocks will be freed).

VMO_OPEN

Open an existing file. If the file does not exist, return an error condition.

VMO_NATIVE_WITH_EXT_ATTRS

The file will have a name compatible with the native filesystem, but it will have GEOS extended attributes. This flag can be combined with any of the other VMOpenType values with a bit-wise or .

You also have to specify what type of access to the file you would like. You do this by passing a record of VMAccessFlags . This is a byte-length bitfield. The following flags are available:

VMAF_FORCE_READ_ONLY

If set, the file will be opened read-only, even if the default would be to open the file read/write. Blocks in read-only files cannot be dirtied, and changes in memory blocks will not be updated to the disk VM blocks.

VMAF_FORCE_READ_WRITE

If set, the file will be opened for read/write access, even if the default would be to open the file for read-only access.

VMAF_SHARED_MEMORY

If set, the VM manager should try to use shared memory when locking VM blocks; that is, the same memory block will be used for a given VM block no matter which thread locks the block.

VMAF_FORCE_DENY_WRITE

If set, the file will be opened deny-write; that is, no other threads will be allowed to open the file for read/write access.

VMAF_DISALLOW_SHARED_MULTIPLE

If this flag is set, files with the file attribute GFHF_SHARED_MULTIPLE cannot be opened.

VMAF_USE_BLOCK_LEVEL_SYNCHRONIZATION

If set, the block-level synchronization mechanism of the VM manager is assumed to be sufficient; the more restrictive file-level synchronization is not used. This is primarily intended for system software. (See File-Access Synchronization .)

If you open a file with VMAF_FORCE_READ_ONLY, it's generally a good idea to also open it with VMAF_FORCE_DENY_WRITE. When you open a file VMAF_FORCE_READ_ONLY, if the file is writable, and is located on a writable device which can be used by other machines (e.g. a network drive), the kernel will load the entire file into memory and make the blocks non-discardable (even when they are clean); this keeps the file you see consistent, even if another user changes the version of the file on the disk. However, this can cause problems if the machine has limited swap space. If the file is opened with VMAF_FORCE_DENY_WRITE, no other device will be allowed to change the file while you have it open, which means the kernel can just load and discard blocks as necessary.

The routine VMOpen() returns the file handle. If it cannot satisfy the request, it returns a null handle and sets the thread error word. The error word can be recovered with the ThreadGetError() routine. The possible error conditions are:

VM_FILE_EXISTS

VMOpen() was passed VMO_CREATE_ONLY, but the file already exists.

VM_FILE_NOT_FOUND

VMOpen() was passed VMO_OPEN, but the file does not exist.

VM_SHARING_DENIED

The file was opened by another geode, and access was denied.

VM_OPEN_INVALID_VM_FILE

VMOpen() was instructed to open an invalid VM file (or a non-VM file).

VM_CANNOT_CREATE

VMOpen() cannot create the file (but it does not already exist).

VM_TRUNCATE_FAILED

VMOpen() was passed VMO_CREATE_TRUNCATE; the file exists but could not be truncated.

VM_WRITE_PROTECTED

VMOpen() was passed VMAF_FORCE_READ_WRITE, but the file or disk was write-protected.

GEOS SDK TechDocs

3.1 How to Use VM

3.3 Changing VM File Attributes