Symbolic Link Effects on File Systems Functions
Collapse the table of content
Expand the table of content

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

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

 

 

Show:
© 2016 Microsoft