File Mapping APIs. More...

#include <MacTypes.h>
#include <Files.h>
#include <Processes.h>

Data Structures
struct	MappedFileInformation

struct	FileViewInformation

Typedefs
typedef struct OpaqueBackingFileID *	BackingFileID

typedef UInt32	MappingPrivileges

typedef UInt32	MappedFileAttributes

typedef struct MappedFileInformation	MappedFileInformation

typedef UInt32	FileViewAccess

typedef OptionBits	FileViewOptions

typedef struct OpaqueFileViewID *	FileViewID

typedef struct FileViewInformation	FileViewInformation

Enumerations
enum	{ kInvalidMappedPrivileges = 0x00000000 , kCanReadMappedFile = 0x00000001 , kCanWriteMappedFile = 0x00000002 , kNoProcessMappedFile , kValidMappingPrivilegesMask }

enum	{ kIsMappedScratchFile = 0x00000001 }

enum	{ kMappedFileInformationVersion1 = 1 }

enum	{ kFileViewAccessReadBit = 0 , kFileViewAccessWriteBit = 1 , kFileViewAccessExecuteBit = 2 , kFileViewAccessReadMask = 1L << kFileViewAccessReadBit , kFileViewAccessWriteMask , kFileViewAccessExecuteMask , kFileViewAccessExcluded = 0 , kFileViewAccessReadOnly , kFileViewAccessReadWrite }

enum	{ kMapEntireFork = -1 }

enum	{ kFileViewInformationVersion1 = 1 }

Functions
OSErr	OpenMappedFile (const FSRef ref, UniCharCount forkNameLength, const UniChar forkName, MappingPrivileges privileges, BackingFileID *backingFile)

OSErr	FSpOpenMappedFile (const FSSpec spec, Boolean mapResFork, MappingPrivileges privileges, BackingFileID backingFile)

OSErr	OpenMappedScratchFile (FSVolumeRefNum volume, ByteCount fileSize, MappingPrivileges privileges, BackingFileID *backingFile)

OSErr	CloseMappedFile (BackingFileID backingFile)

OSErr	GetMappedFileInformation (BackingFileID backingFile, PBVersion version, MappedFileInformation *mappedFileInfo)

OSErr	GetNextMappedFile (BackingFileID *backingFile)

OSErr	SetMappedFileSize (BackingFileID backingFile, UInt16 positionMode, const SInt64 *positionOffset)

OSErr	GetFileViewAccessOptions (FileViewAccess access, FileViewOptions options)

OSErr	MapFileView (BackingFileID backingFile, const UInt64 backingBase, ByteCount backingLength, FileViewAccess access, ByteCount guardLength, FileViewOptions options, LogicalAddress viewBase, ByteCount viewLength, FileViewID theView)

OSErr	UnmapFileView (FileViewID theView)

OSErr	GetFileViewInformation (FileViewID theView, PBVersion version, FileViewInformation *fileViewInfo)

OSErr	GetFileViewFromAddress (LogicalAddress address, FileViewID *theView)

OSErr	GetNextFileView (FileViewID *theView)

OSErr	SetFileViewAccess (FileViewID theView, FileViewAccess access)

OSErr	SetFileViewBackingBase (FileViewID theView, const UInt64 *newBackingBase)

Detailed Description

File Mapping APIs.

Introduced In: 1.0

Avaliable From: Universal Interfaces 3.4.1

Copyright: © 1998-2001 by Apple Computer, Inc., all rights reserved.

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

OpenMappedFile()

Summary: Opens a file fork with the privileges requested for use as backing storage.

Discussion: The OpenMappedFile function opens the fork specified by the forkNameLength and forkName parameters of the file specified by the ref parameter and returns a BackingFileID in the backingFile parameter. You can pass the BackingFileID to other routines which accept a BackingFileID as an input parameter. The privileges parameter specifies what operations you want to perform on the mapped file fork. Programs can request either kCanReadMappedFile privileges, or both kCanReadMappedFile and kCanWriteMappedFile privileges. To disable Process Manager tracking of the mapped file fork and its mapped file views, you may also request kNoProcessMappedFile privileges.

Parameters:

ref: The file to map.

forkNameLength: The fork name length in Unicode characters.

forkName: The fork name in Unicode (NULL = data fork).

privileges: The requested MappingPrivileges.

backing Receives a BackingFileID which you can use to access the mapped file fork.

Result: An operating system result code: noErr, paramErr, vmMappingPrivilegesErr, or various File Manager and Memory Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

FSpOpenMappedFile()

Summary: Opens a file fork with the privileges requested for use as backing storage.

Discussion: The FSpOpenMappedFile function opens the fork specified by the mapResFork parameter of the file specified by the spec parameter and returns a BackingFileID in the backingFile parameter. You can pass the BackingFileID to other routines which accept a BackingFileID as an input parameter. The privileges parameter specifies what operations you want to perform on the mapped file fork. Programs can request either kCanReadMappedFile privileges, or both kCanReadMappedFile and kCanWriteMappedFile privileges. To disable Process Manager tracking of the mapped file fork and its mapped file views, you may also request kNoProcessMappedFile privileges.

Parameters:

spec: The file to map.

mapResFork: Fork to map: false = data fork; true = resource fork.

privileges: The requested MappingPrivileges.

backing Receives a BackingFileID which you can use to access the mapped file fork.

Result: An operating system result code: noErr, paramErr, vmMappingPrivilegesErr, or various File Manager and Memory Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

OpenMappedScratchFile()

Summary: Creates and opens a scratch file with the privileges requested for use as backing storage.

Discussion: The OpenMappedScratchFile function creates a file with the size specified by the fileSize parameter on the volume specified by the volume parameter. If kFSInvalidVolumeRefNum is passed as the volume parameter, the system code will choose the location of the file. OpenMappedScratchFile then opens the file and returns a BackingFileID in the backingFile parameter. You can pass the BackingFileID to other routines which accept a BackingFileID as an input parameter. The privileges parameter specifies what operations you want to perform on the mapped file fork. Programs can request either kCanReadMappedFile privileges, or both kCanReadMappedFile and kCanWriteMappedFile privileges. To disable Process Manager tracking of the mapped file fork and its mapped file views, you may also request kNoProcessMappedFile privileges. The data for a scratch file is only valid in an open mapped file view. When a mapped file view is first created for a scratch file with MapFileView, data on disk is not paged into memory. When that mapped file view is unmapped with UnmapFileView, changes are not flushed from memory to disk.

Parameters:

volume: The volume where scratch file should be created or kFSInvalidVolumeRefNum to let the system choose the volume.

fileSize: The size of the scratch file.

privileges: The requested MappingPrivileges.

backing Receives a BackingFileID which you can use to access the mapped file fork.

Result: An operating system result code: noErr, paramErr, vmMappingPrivilegesErr, or various File Manager and Memory Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

CloseMappedFile()

Summary: Closes a mapped file fork.

Discussion: The CloseMappedFile function closes the mapped file fork specified by the backingFile parameter. All mapped file views using the BackingFileID must be closed before closing the mapped file fork. If the BackingFileID is for a scratch file created with OpenMappedScratchFile, the scratch file is deleted by CloseMappedFile after it is closed.

Parameters:

backing The mapped file fork to close.

Result: An operating system result code: noErr, vmInvalidBackingFileIDErr, vmInvalidOwningProcessErr, vmBusyBackingFileErr, or various File Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

GetMappedFileInformation()

Summary: Returns information about a mapped file fork.

Discussion: The GetMappedFileInformation function returns information about the mapped file fork specified by the backingFile parameter. The struct version of the mappedFileInfo parameter is passed in the version parameter. The mapped file fork information is returned in the mappedFileInfo parameter.

Parameters:

backing The mapped file fork.

version: The version of the MappedFileInformation struct passed.

mappedFileInfo: A pointer to the MappedFileInformation struct where the information about a mapped file fork is returned.

Result: An operating system result code: noErr, paramErr, vmInvalidBackingFileIDErr, or various File Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

GetNextMappedFile()

Summary: Gets a list of mapped file forks.

Discussion: The GetNextMappedFile function returns the BackingFileID of the mapped file fork next in the list of mapped file forks. You can enumerate through the list of mapped file forks by passing kInvalidID as the backingFile parameter and then repetitively calling GetNextMappedFile with the last BackingFileID returned until the result code vmNoMoreBackingFilesErr is returned.

Parameters:

backing Input: The last BackingFileID returned by GetNextMappedFile, or kInvalidID to get the first mapped file fork. Output: If noErr, receives the BackingFileID of the next mapped file fork.

Result: An operating system result code: noErr, vmInvalidBackingFileIDErr, or vmNoMoreBackingFilesErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

SetMappedFileSize()

Summary: Changes the size (logical end-of-file) of a mapped file fork.

Discussion: The SetMappedFileSize function sets the logical end-of-file of the mapped file fork specified by backingFile. The new logical end-of-file is specified by the positionMode and positionOffset parameters.

Parameters:

backing The mapped file fork to change the size of.

positionMode: The base location for the new size: fsAtMark, fsFromStart, fsFromLEOF, or fsFromMark.

positionOffset: Pointer to a SInt64 which contains the offset of the size from the base.

Result: An operating system result code: noErr, paramErr, or various File Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

MapFileView()

Summary: Creates a mapped file view into a mapped file fork.

Discussion: The MapFileView function creates a mapped file view into the mapped file fork specified by the backingFile parameter. MapFileView returns a FileViewID in the theView parameter. You can pass the FileViewID to other routines which accept a FileViewID as an input parameter. The backingBase and backingLength parameters specify what part of the mapped file fork will be mapped to memory. The access parameter specifies the allowable access to the memory in a mapped file view. The guardLength parameter specifies the size, in bytes, of the excluded logical address ranges to place adjacent to each end of the mapped file view. The options parameter specifies the desired characteristics of the mapped file view. The viewBase parameter, as an optional input, specifies the requested viewBase. The backingBase parameter must be a whole multiple of the logical page size. If kMapEntireFork is passed as backingLength, accesses past the mapped file fork's logical end-of-file will not cause exceptions, but will have undefined behavior. Only accesses up to viewLength should be considered valid. The starting address of the mapped file view is returned in the viewBase parameter. The length of the mapped file view is returned in the viewLength parameter.

Parameters:

backing The mapped file fork to create a mapped file view from.

backingBase: Pointer to the offset into mapped file fork. Passing a NULL pointer is the same as passing an offset of zero.

backingLength: The number of bytes to map, or kMapEntireFork to map from backingBase to the mapped file fork's logical end-of-file.

access: The FileViewAccess.

guardLength: The size, in bytes, of the excluded logical address ranges to place adjacent to each end of the mapped file view.

options: The desired characteristics of the mapped file view.

viewBase: Input: The requested viewBase. Output: Receives the starting address of mapped file view.

viewLength: Receives the mapped file view length.

theView: Receives a FileViewID which you can use to access the mapped file view.

Result: An operating system result code: noErr, paramErr, vmInvalidBackingFileIDErr, vmInvalidOwningProcessErr, vmFileViewAccessErr, or various File Manager and Memory Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

Typedef Documentation

◆ BackingFileID

typedef struct OpaqueBackingFileID* BackingFileID

BackingFileID

Discussion: A BackingFileID is used to access a mapped file fork.

◆ FileViewAccess

typedef UInt32 FileViewAccess

FileViewAccess

Discussion: Values of type FileViewAccess represent allowable access to the memory in a mapped file view.

◆ FileViewID

typedef struct OpaqueFileViewID* FileViewID

FileViewID

Discussion: A FileViewID is used to access a mapped file view.

◆ FileViewOptions

typedef OptionBits FileViewOptions

FileViewOptions

Discussion: Values of type FileViewOptions specify desired characteristics of the mapped file view being created. At this time, only kNilOptions is supported.

◆ MappedFileAttributes

typedef UInt32 MappedFileAttributes

MappedFileAttributes

Discussion: A set of flags returned by GetMappedFileInformation that describe the attributes of a mapped file fork.

◆ MappingPrivileges

typedef UInt32 MappingPrivileges

MappingPrivileges

Discussion: A set of flags that describe what operations can be performed on a mapped file fork.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
kCanReadMappedFile	Allow the file fork to be mapped such that the memory can be read (this is required).
kCanWriteMappedFile	mapped file fork has read access Allow the file fork to be mapped such that the memory can be written. If not set, then the memory can be mapped read-only.
kNoProcessMappedFile	mapped file fork has write access The mapped file fork and its mapped file views are not tracked by process ID.
kValidMappingPrivilegesMask	mapped file fork and views are not tracked by process

◆ anonymous enum

anonymous enum

Enumerator
kIsMappedScratchFile	Set when the mapped file fork is a scratch file created with OpenMappedScratchFile.

◆ anonymous enum

anonymous enum

Enumerator
kMappedFileInformationVersion1	The version number of the MappedFileInformation struct.

◆ anonymous enum

anonymous enum

Enumerator
kFileViewAccessReadBit	Memory in mapped file view can be read from.
kFileViewAccessWriteBit	Reads allowed Memory in mapped file view can be written to.
kFileViewAccessExecuteBit	Writes allowed Instruction execution from mapped file view is permitted.
kFileViewAccessReadMask	Instruction execution permitted
kFileViewAccessWriteMask	Reads allowed
kFileViewAccessExecuteMask	Writes allowed
kFileViewAccessExcluded	Instruction execution permitted
kFileViewAccessReadOnly	All access is prohibited

◆ anonymous enum

anonymous enum

Enumerator
kMapEntireFork	Pass kMapEntireFork to MapFileView as the backingLength parameter to map from backingBase to logical end-of-file.

◆ anonymous enum

anonymous enum

Enumerator
kFileViewInformationVersion1	The version number of the FileViewInformation struct.

Function Documentation

◆ GetFileViewAccessOptions()

OSErr GetFileViewAccessOptions	(	FileViewAccess *	access,
		FileViewOptions *	options
	)

GetFileViewAccessOptions()

Summary: Returns the valid FileViewAccess and FileViewOptions bits.

Discussion: The GetFileViewAccessOptions function returns the valid FileViewAccess and FileViewOptions bits. Programs can use it to determine what FileViewAccess and FileViewOptions are available.

Parameters:

access: Receives the valid memory access flags.

options: Receives the valid view options.

Result: An operating system result code: noErr, or paramErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ GetFileViewFromAddress()

OSErr GetFileViewFromAddress	(	LogicalAddress	address,
		FileViewID *	theView
	)

GetFileViewFromAddress()

Summary: Returns the FileViewID for a given address.

Discussion: The GetFileViewFromAddress function returns the FileViewID for address specified in the address parameter.

Parameters:

address: The memory address.

theView: Receives a FileViewID for the given memory address.

Result: An operating system result code: noErr, paramErr, or vmAddressNotInFileViewErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ GetFileViewInformation()

OSErr GetFileViewInformation	(	FileViewID	theView,
		PBVersion	version,
		FileViewInformation *	fileViewInfo
	)

GetFileViewInformation()

Summary: Returns information about a mapped file view.

Discussion: The GetFileViewInformation function returns information about the mapped file view specified by the theView parameter. The struct version of the fileViewInfo parameter is passed in the version parameter. The mapped file view information is returned in the fileViewInfo parameter.

Parameters:

theView: The mapped file view.

version: The version of the FileViewInformation struct passed.

fileViewInfo: A pointer to the FileViewInformation struct where the information about a mapped file view is returned.

Result: An operating system result code: noErr, paramErr, or vmInvalidFileViewIDErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ GetNextFileView()

OSErr GetNextFileView ( FileViewID * theView )

GetNextFileView()

Summary: Gets a list of mapped file views.

Discussion: The GetNextView function returns the FileViewID of the mapped file view next in the list of mapped file views. You can enumerate through the list of mapped file views by passing kInvalidID as the theView parameter and then repetitively calling GetNextView with the last FileViewID returned until the result code vmNoMoreFileViewsErr is returned.

Parameters:

theView: Input: The last FileViewID returned by GetNextView, or kInvalidID to get the first mapped file view. Output: If noErr, receives the FileViewID of the next mapped file view.

Result: An operating system result code: noErr, paramErr, vmInvalidFileViewIDErr, or vmNoMoreFileViewsErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ MapFileView()

OSErr MapFileView	(	BackingFileID	backingFile,
		const UInt64 *	backingBase,
		ByteCount	backingLength,
		FileViewAccess	access,
		ByteCount	guardLength,
		FileViewOptions	options,
		LogicalAddress *	viewBase,
		ByteCount *	viewLength,
		FileViewID *	theView
	)

Parameters

backingLength can be NULL

◆ OpenMappedFile()

OSErr OpenMappedFile	(	const FSRef *	ref,
		UniCharCount	forkNameLength,
		const UniChar *	forkName,
		MappingPrivileges	privileges,
		BackingFileID *	backingFile
	)

Parameters

privileges can be NULL

◆ SetFileViewAccess()

OSErr SetFileViewAccess	(	FileViewID	theView,
		FileViewAccess	access
	)

SetFileViewAccess()

Summary: Changes a mapped file view's FileViewAccess.

Discussion: The SetViewAccess function changes the FileViewAccess of the mapped file view specified by the theView parameter. The new FileViewAccess is specified by the accessLevel parameter.

Parameters:

theView: The mapped file view.

access: The new FileViewAccess.

Result: An operating system result code: noErr, paramErr, vmInvalidFileViewIDErr, or vmFileViewAccessErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ SetFileViewBackingBase()

OSErr SetFileViewBackingBase	(	FileViewID	theView,
		const UInt64 *	newBackingBase
	)

SetFileViewBackingBase()

Summary: Changes the backing base of a mapped file view.

Discussion: The SetFileViewBackingBase function changes the backing base of the mapped file view specified by theView. The new backing base is specified by the newBackingBase parameter.

Parameters:

theView: The mapped file view.

newBackingBase: Pointer to the offset into mapped file fork. Passing a NULL pointer is the same as passing an offset of zero.

Result: An operating system result code: noErr, vmInvalidFileViewIDErr, or paramErr.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available: can be NULL

◆ UnmapFileView()

OSErr UnmapFileView ( FileViewID theView )

UnmapFileView()

Summary: Unmaps a mapped file view.

Discussion: The UnmapFileView function unmaps a mapped file view specified by the theView parameter from memory. All modified memory is flushed to the mapped file fork before the mapped file view is unmapped unless the mapped file view is to a scratch file.

Parameters:

theView: The mapped file view to unmap.

Result: An operating system result code: noErr, vmInvalidFileViewIDErr, vmInvalidOwningProcessErr, or various File Manager and Memory Manager errors.

Non-Carbon CFM: in InterfaceLib 9.1 and later

Carbon Lib: not available

Mac OS X: not available

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ BackingFileID

◆ FileViewAccess

◆ FileViewID

◆ FileViewOptions

◆ MappedFileAttributes

◆ MappingPrivileges

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ GetFileViewAccessOptions()

◆ GetFileViewFromAddress()

◆ GetFileViewInformation()

◆ GetNextFileView()

◆ MapFileView()

◆ OpenMappedFile()

◆ SetFileViewAccess()

◆ SetFileViewBackingBase()

◆ UnmapFileView()