CreateHardLink

The CreateHardLink function establishes an NTFS hard link between an existing file and a new file. An NTFS hard link is similar to a POSIX hard link.

BOOL CreateHardLink(
  LPCTSTR lpFileName,                         // new file name
  LPCTSTR lpExistingFileName,                 // extant file name
  LPSECURITY_ATTRIBUTES lpSecurityAttributes  // SD
);

Parameters

lpFileName

[in] Pointer to the name of the new directory entry to be created.

lpExistingFileName

[in] Pointer to the name of the existing file to which the new link will point.

lpSecurityAttributes

[in] Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new file.

If this parameter is NULL, it leaves the file's existing security descriptor unmodified.

If this parameter is not NULL, it modifies the file's security descriptor.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Any directory entry for a file, whether created with CreateFile or CreateHardLink, is a hard link to the associated file. Additional hard links, created with the CreateHardLink function, allow you to have multiple directory entries for a file, that is, multiple hard links to the same file. These may be different names in the same directory, or they may be the same (or different) names in different directories. However, all hard links to a file must be on the same volume.

Because hard links are just directory entries for a file, whenever an application modifies a file through any hard link, all applications using any other hard link to the file see the changes. Also, all of the directory entries are updated if the file changes. For example, if the file's size changes, all of the hard links to the file will show the new size.

The security descriptor belongs to the file to which the hard link points. The link itself, being merely a directory entry, has no security descriptor. Thus, if you change the security descriptor of any hard link, you're actually changing the underlying file's security descriptor. All hard links that point to the file will thus allow the newly specified access. There is no way to give a file different security descriptors on a per-hard-link basis.

Use DeleteFile to delete hard links. You can delete them in any order regardless of the order in which they were created.

Flags, attributes, access, and sharing as specified in CreateFile operate on a per-file basis. That is, if you open a file with no sharing allowed, another application cannot share the file by creating a new hard link to the file.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

File Systems Overview, File System Functions, CreateFile, DeleteFile, SECURITY_ATTRIBUTES