Symbolic Link Effects on File Systems Functions
Several standard file functions that use path names to specify one or more files are affected by the use of symbolic links. This topic lists those functions and describes the changes in behavior:
- CopyFile and CopyFileTransacted
- CopyFileEx
- CreateFile and CreateFileTransacted
- CreateHardLink and CreateHardLinkTransacted
- DeleteFile and DeleteFileTransacted
- FindFirstChangeNotification
- FindFirstFile and FindFirstFileTransacted
- FindFirstFileEx
- FindNextFile
- GetBinaryType
- GetCompressedFileSize and GetCompressedFileSizeTransacted
- GetDiskFreeSpace
- GetDiskFreeSpaceEx
- GetFileAttributes
- GetFileAttributesEx
- GetFileSecurity
- GetTempPath
- GetVolumeInformation
- SetFileAttributes
- SetFileSecurity
- Related topics
In the descriptions below, the following terms are used:
- Source file—The original file that is to be copied.
- Destination file—The newly created copy of the file.
- Target—The entity that a symbolic link points to.
Note
The behavior of functions that accept a handle created using the CreateFile function, such as the GetFileTime function, will differ based on whether or not the CreateFile function was called using the FILE_FLAG_OPEN_REPARSE_POINT flag. For more information, see CreateFile and the following CreateFile and CreateFileTransacted section.
CopyFile and CopyFileTransacted
If the source file is a symbolic link, the actual file copied is the target of the symbolic link.
If the destination file already exists and is a symbolic link, the target of the symbolic link is overwritten by the source file.
CopyFileEx
If COPY_FILE_COPY_SYMLINK is specified and:
- If the source file is a symbolic link, the symbolic link is copied, not the target file.
- If the source file is not a symbolic link, there is no change in behavior.
- If the destination file is an existing symbolic link, the symbolic link is overwritten, not the target file.
- If COPY_FILE_FAIL_IF_EXISTS is also specified, and the destination file is an existing symbolic link, the operation fails in all cases.
If COPY_FILE_COPY_SYMLINK is not specified and:
- If COPY_FILE_FAIL_IF_EXISTS is also specified, and the destination file is an existing symbolic link, the operation fails only if the target of the symbolic link exists.
- If COPY_FILE_FAIL_IF_EXISTS is not specified, there is no change in behavior.
Windows Server 2003 and Windows XP: The COPY_FILE_COPY_SYMLINK flag is not supported. If the source file is a symbolic link, the actual file copied is the target of the symbolic link.
CreateFile and CreateFileTransacted
If the call to this function creates a new file, there is no change in behavior.
If FILE_FLAG_OPEN_REPARSE_POINT is specified and:
- If an existing file is opened and it is a symbolic link, the handle returned is a handle to the symbolic link.
- If CREATE_ALWAYS, TRUNCATE_EXISTING, or FILE_FLAG_DELETE_ON_CLOSE are specified, the file affected is a symbolic link.
If FILE_FLAG_OPEN_REPARSE_POINT is not specified and:
- If an existing file is opened and it is a symbolic link, the handle returned is a handle to the target.
- If CREATE_ALWAYS, TRUNCATE_EXISTING, or FILE_FLAG_DELETE_ON_CLOSE are specified, the file affected is the target.
CreateHardLink and CreateHardLinkTransacted
If the path points to a symbolic link, the function creates a hard link to the target.
DeleteFile and DeleteFileTransacted
If the path points to a symbolic link, the symbolic link is deleted, not the target. To delete a target, you must call CreateFile and specify FILE_FLAG_DELETE_ON_CLOSE.
FindFirstChangeNotification
If the path points to a symbolic link, the notification handle is created for the target. If an application has registered to receive change notifications for a directory that contains symbolic links, the application is only notified when the symbolic links have been changed, not the target files.
FindFirstFile and FindFirstFileTransacted
If the path points to a symbolic link, the WIN32_FIND_DATA buffer contains information about the symbolic link, not the target.
FindFirstFileEx
If the path points to a symbolic link, the WIN32_FIND_DATA buffer contains information about the symbolic link, not the target.
FindNextFile
If the path points to a symbolic link, the WIN32_FIND_DATA buffer contains information about the symbolic link, not the target.
GetBinaryType
If the path points to a symbolic link, the target file is used.
GetCompressedFileSize and GetCompressedFileSizeTransacted
If the path points to a symbolic link, the function returns the file size of the target.
GetDiskFreeSpace
If the path points to a symbolic link, the operation is performed on the target.
GetDiskFreeSpaceEx
If the path points to a symbolic link, the operation is performed on the target.
GetFileAttributes
If the path points to a symbolic link, the function returns attributes for the symbolic link.
GetFileAttributesEx
If the path points to a symbolic link, the function returns attributes for the symbolic link.
GetFileSecurity
If the path points to a symbolic link, the function returns attributes for the symbolic link.
GetTempPath
If the path points to a symbolic link, the temp path name maintains any symbolic links.
GetVolumeInformation
If the path points to a symbolic link, the function returns volume information for the target.
SetFileAttributes
If the path points to a symbolic link, the function retrieves attributes for the symbolic link.
SetFileSecurity
If the path points to a symbolic link, the function returns attributes for the symbolic link.
Related topics