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:

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.

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.

CopyFile

CopyFileTransacted

CopyFileEx

CreateFile

CreateFileTransacted

CreateHardLink

CreateHardLinkTransacted

DeleteFile

DeleteFileTransacted

FindFirstChangeNotification

FindFirstFile

FindFirstFileEx

FindFirstFileTransacted

FindNextFile

GetBinaryType

GetCompressedFileSize

GetCompressedFileSizeTransacted

GetDiskFreeSpace

GetDiskFreeSpaceEx

GetFileAttributes

GetFileAttributesEx

GetFileSecurity

GetTempPath

GetVolumeInformation

SetFileAttributes

SetFileSecurity