CcPinRead function (ntifs.h)

The CcPinRead routine pins the specified byte range of a cached file and reads the pinned data into a buffer in memory.

Syntax

BOOLEAN CcPinRead(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  ULONG          Flags,
  [out] PVOID          *Bcb,
  [out] PVOID          *Buffer
);

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 of desired data in bytes.

[in] Flags

Bitmask of flags specifying how the pinning operation is to be performed. ORed combination of one or more of the following values:

[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.

[out] Buffer

Pointer to a buffer containing the pinned data.

Return value

CcPinRead returns TRUE if the data for the cached file was pinned and read successfully, FALSE otherwise.

Remarks

If the PIN_WAIT flag is set, CcPinRead is guaranteed to complete the pinning request and return TRUE. If the required pages of the cached file are already resident in memory, the data is pinned immediately and no blocking occurs. If any needed pages are not resident, the caller is put in a wait state until all required pages have been made resident and the data can be pinned. If the PIN_WAIT flag is not set, but the data cannot be pinned immediately, CcPinRead returns FALSE, and its output parameter values are meaningless.

If the caller subsequently modifies the data read by CcPinRead, it must also call CcSetDirtyPinnedData so that the modified data will eventually be written to disk.

Every successful call to CcPinRead must be matched by a subsequent call to CcUnpinData.

The pointer returned in Buffer is valid until CcUnpinData is called. If CcPinMappedData is called while this pointer is still valid, the pointer remains valid after the call to CcPinMappedData (but only until CcUnpinData is called).

CcPinRead 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, CcPinRead raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcPinRead raises a STATUS_INSUFFICIENT_RESOURCES exception; if an I/O error occurs, CcPinRead raises the status exception of the I/O error. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcPinRead 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.

Requirements

See also

CcInitializeCacheMap

CcMapData

CcPinMappedData

CcPreparePinWrite

CcSetDirtyPinnedData

CcUnpinData