CcPinMappedData function (ntifs.h)
The CcPinMappedData routine pins the specified byte range of a cached file.
Syntax
BOOLEAN CcPinMappedData(
[in] PFILE_OBJECT FileObject,
[in] PLARGE_INTEGER FileOffset,
[in] ULONG Length,
[in] ULONG Flags,
[in, out] PVOID *Bcb
);
Parameters
[in] FileObject
Pointer to a file object for the cached file in which a range of data is to be pinned.
[in] FileOffset
Pointer to a variable that specifies the starting byte offset within the cached file where the desired data resides.
[in] Length
Length in bytes of the data to be pinned.
[in] Flags
Bitmask of flags specifying how the pinning operation is to be performed. ORed combination of one or more of the following values:
| Flag | Meaning |
|---|---|
| PIN_WAIT | The caller can be put into a wait state until the data has been pinned. |
| PIN_EXCLUSIVE | The buffer control block (BCB) is to be acquired exclusively. If this flag is set, PIN_WAIT must also be set. |
| PIN_NO_READ | Only pages that are already resident in memory are to be pinned. If this flag is set, PIN_WAIT must also be set. |
| PIN_IF_BCB | The data is to be pinned only if a BCB already exists. Otherwise, the pin fails and Bcb is set to NULL. |
[in, out] Bcb
On the first call this returns a pointer to a buffer control block (BCB). This pointer must be supplied as input on all subsequent calls for this buffer.
Return value
CcPinMappedData returns TRUE if the data for the cached file was pinned successfully, FALSE otherwise.
Remarks
A successful return from CcPinMappedData guarantees that the data previously mapped in a call to CcMapData is pinned in the cache and data in the specified range can be safely modified. If the caller subsequently modifies the data pinned by CcPinMappedData, it must also call CcSetDirtyPinnedData so that the modified data will eventually be written to disk.
CcPinMappedData cannot pin data across view boundaries in the cache manager. The cache manager manages files in the system in 256 KB-aligned views. (The cache manager's view size is specified by the system-defined constant VACB_MAPPING_GRANULARITY, which is set to 256 KB in ntifs.h.) Pinned regions cannot span more than one 256 KB view. Therefore, the largest region that can be pinned is 256 KB, beginning at a 256 KB-aligned offset in the file.
Pinning a byte range in a cached file does not ensure that the pages remain resident in memory. As long as the pages are pinned, the byte range is guaranteed to stay mapped into the system cache virtual address space, but the memory manager can page out the physical pages as the system's memory demand requires.
If any failure occurs, CcPinMappedData raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcPinMappedData raises a STATUS_INSUFFICIENT_RESOURCES exception; if an I/O error occurs, CcPinMappedData raises the status exception of the I/O error. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcPinMappedData in a try-except or try-finally statement.
To map data for a cached file, use the CcMapData routine. To cache a file, use CcInitializeCacheMap.
It is not necessary to call CcUnpinData after calling CcPinMappedData since the pin reference is matched to CcMapData.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |