Windows Directory Management 2

 

 

 

 

Reparse Points

 

A file or directory can contain a reparse point, which is a collection of user-defined data. The format of this data is understood by the application which stores the data, and a file system filter, which you install to interpret the data and process the file. When an application sets a reparse point, it stores this data, plus a reparse tag, which uniquely identifies the data it is storing. When the file system opens a file with a reparse point, it attempts to find the file system filter associated with the data format identified by the reparse tag. If a file system filter is found, the filter processes the file as directed by the reparse data. If a file system filter is not found, the file open operation fails.

For example, reparse points are used to implement NTFS file system links and the Microsoft Remote Storage Server (RSS). RSS uses an administrator-defined set of rules to move infrequently used files to long term storage, such as tape or optical media. It uses reparse points to store information about the file in the file system. This information is stored in a stub file that contains a reparse point whose data points to the device where the actual file is now located. The file system filter can use this information to retrieve the file. Reparse points are also used to implement mounted folders. The following restrictions apply to reparse points:

1. Reparse points can be established for a directory, but the directory must be empty. Otherwise, the NTFS file system fails to establish the reparse point. In addition, you cannot create directories or files in a directory that contains a reparse point.
2. Reparse points and extended attributes are mutually exclusive. The NTFS file system cannot create a reparse point when the file contains extended attributes, and it cannot create extended attributes on a file that contains a reparse point.
3. Reparse point data, including the tag and optional GUID, cannot exceed 16 kilobytes. Setting a reparse point fails if the amount of data to be placed in the reparse point exceeds this limit.
4. There is a limit of 31 reparse points on any given path.

 

Reparse Point Tags

 

Each reparse point has an identifier tag so that you can efficiently differentiate between the different types of reparse points, without having to examine the user-defined data in the reparse point. The system uses a set of predefined tags and a range of tags reserved for Microsoft. If you use any of the reserved tags when setting a reparse point, the operation fails. Tags not included in these ranges are not reserved and are available for your application. When you set a reparse point, you must tag the data to be placed in the reparse point. After the reparse point has been established, a new set operation fails if the tag for the new data does not match the tag for the existing data. If the tags match, the set operation overwrites the existing reparse point. To retrieve the reparse point tag, use the FindFirstFile() function. If the dwFileAttributes member includes the FILE_ATTRIBUTE_REPARSE_POINT attribute, then the dwReserved0 member specifies the reparse point.

 

Tag Contents

 

Reparse tags are stored as DWORD values. The bits define certain attributes, as shown in the following diagram.

 

3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1

1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

+-+-+-+-+-----------------------+-------------------------------+

|M|R|N|R|     Reserved bits     |      Reparse tag value        |

+-+-+-+-+-----------------------+-------------------------------+

 

The low 16 bits determine the kind of reparse point. The high 16 bits have 12 bits reserved for future use and 4 bits that denote specific attributes of the tags and the data represented by the reparse point. The following table describes these bits.

 

 

The following macros exist to assist in testing tags:

 

1. IsReparseTagMicrosoft() - Determines whether a reparse point tag indicates a Microsoft reparse point.
2. IsReparseTagNameSurrogate() - Determines whether a tag's associated reparse point is a surrogate for another named entity (for example, a mounted folder).

 

Each macro returns a nonzero value if the associated bit is set. The following are Microsoft's predefined reparse tag values; they are defined in Winnt.h:

 

1. IO_REPARSE_TAG_DFS
2. IO_REPARSE_TAG_DFSR
3. IO_REPARSE_TAG_HSM
4. IO_REPARSE_TAG_HSM2
5. IO_REPARSE_TAG_MOUNT_POINT
6. IO_REPARSE_TAG_SIS
7. IO_REPARSE_TAG_SYMLINK

 

To ensure uniqueness of tags, Microsoft provides a mechanism to distribute new tags as explained in the Installable File System (IFS) Kit. Also available the Installable File System Filter test, which verifies whether the behavior in the file system stack is consistent with the typical behavior of a file system. This is a regression test suite.

 

Reparse Point Operations

 

To determine whether a file system supports reparse points, call the GetVolumeInformation() function and examine the FILE_SUPPORTS_REPARSE_POINTS bit flag. The DeviceIoControl() function enables you to set, modify, obtain, and remove reparse points. The following table describes the reparse point operations that you can perform using DeviceIoControl().

 

 

If you are modifying, getting, or deleting a reparse point, you must specify the same reparse tag in the operation that is contained in the file. Otherwise, the operation will fail with the error ERROR_REPARSE_TAG_MISMATCH. If you are modifying or deleting a reparse point, you must also specify the reparse GUID in the operation that is contained in the file. Otherwise, the operation will fail with the error ERROR_REPARSE_ATTRIBUTE_CONFLICT. To determine whether a file or directory contains a reparse point, use the GetFileAttributes() function. If the file or directory has an associated reparse point, the FILE_ATTRIBUTE_REPARSE_POINT attribute is set. To overwrite an existing reparse point without already having a handle to the file or directory, call CreateFile() with FILE_FLAG_OPEN_REPARSE_POINT. This flag allows you to open the file whether or not the corresponding file system filter is installed and working correctly.

 

Reparse Points and File Operations

 

Reparse points enable file system behavior that departs from the behavior most Windows developers may be accustomed to, therefore being aware of these behaviors when writing applications that manipulate files is vital to robust and reliable applications intended to access file systems that support reparse points. The extent of these considerations will depend on the specific implementation and associated file system filter behavior of a particular reparse point, which can be user-defined. Consider the following examples regarding NTFS reparse point implementations, which include mounted folders, linked files, and the Microsoft Remote Storage Server:

 

1. Backup applications that use file streams should specify BACKUP_REPARSE_DATA in the WIN32_STREAM_ID structure when backing up files with reparse points.
2. Applications that use the CreateFile() function should specify the FILE_FLAG_OPEN_REPARSE_POINT flag when opening the file if it is a reparse point.
3. The process of de-fragmenting files requires special handling for reparse points.
4. Virus detection applications should search for reparse points that indicate linked files.
5. Most applications should take special actions for files that have been moved to long-term storage, if only to notify the user that it may take a while to retrieve the file.
6. The OpenFileById() function will either open the file or the reparse point, depending on the use of the FILE_FLAG_OPEN_REPARSE_POINT flag.
7. Symbolic links, as reparse points, have certain programming considerations specific to them.
8. Volume management activities for reading journal records require special handling for reparse points when using the USN_RECORD and READ_USN_JOURNAL_DATA structures.

 

 

 

< Windows Directory 1 | Win32 Programming | Win32 Directory Index | Windows Directory 3 >