Hardlink.cpp

Go to the documentation of this file.

#include <uLib/UtilFunc.h>
#include <uLib/StrFunc.h>
#include <uLib/_Internal.h>

//++ GetHardLinkCount ++-------------------------------------------------------

UINT GetHardLinkCount( CSTR FileName )
{
    UINT nLinks = 0;
    BY_HANDLE_FILE_INFORMATION bhi;
    if (GetFileInformationByName( FileName, &bhi )) nLinks = bhi.nNumberOfLinks;
    return nLinks;
}

//++ _CreateHardLink ++------------------------------------------------------------------
/*
_CreateHardLink() is based on the following KB article.
The OS has had this function since Win2k, so this is mostly for edification and memo.
The linker will exclude it if you don't use it, so no harm done :)
I dug this out from my old 1999 source base and solidified it with some more
error checks. (I was much more lax about such things in those days).
The function basically "restores" a link to the file.

HOWTO: Create Hard Links in Windows NT and Windows 2000  KB.ID: Q234727
-------------------------------------------------------------------------------
The information in this article applies to:
Microsoft Win32 Application Programming Interface (API), included with:
Microsoft Windows NT, versions 3.51, 4.0
Microsoft Windows 2000
-------------------------------------------------------------------------------
SUMMARY

Windows NT and Windows 2000 support hard links on NTFS disk volumes.
Following are two programmatic approaches that exist for creating hard links:

1) Use CreateHardLink() in Windows 2000.
2) Use the BackupWrite() to create a hard link in Windows NT and Windows 2000.

If your application requires Windows 2000, use method one because it is simpler;
if your application must run on Windows NT and Windows 2000, you should use
method two. The remainder of this article provides more detailed information
about hard links and how to create them with both methods.

MORE INFORMATION

A hard link is a directory entry for a file. Every file can be considered to
have at least one hard link. On NTFS volumes, each file can have multiple hard
links, and thus a single file can appear in many directories (or even in the same
directory with different names). Since all of the links reference the same file,
applications can open any of the links and modify the file. A file is deleted
from the file system only after all links to it have been deleted. Once a hard
link is created, applications can use it like any other file name. Therefore,
you can use the full Win32 file I/O API to access a file through a link. The
changes made to a file through one link will be reflected by all other links
(because they point to the same file). To remove a link use DeleteFile(). Hard
links are supported on NTFS only; they may not be created on FAT or FAT32 volumes.
In addition, a hard link must reside on the same volume as the file it references.
You cannot create a hard link on one volume that points to a file on another
volume. This is because a hard link is a directory entry that points to a file.

The security descriptor for a file belongs to the file, not the links that
reference it. Thus, all links to a file grant the same access to the file.
If the security descriptor for the file is changed by using one link, all other
links will reflect that change.

The hard links created with BackupWrite() and CreateHardLink() are identical;
the only difference is in the functions the applications call to create them.
Creating hard links with BackupWrite() is supported on Windows 2000 and should
be used when your application must also run on Windows NT version 4.0 and earlier.
If your application is designed to run on Windows 2000, use CreateHardLink()
because it is easier to use.

CreateHardLink() Example

The following code snippet demonstrates how to call CreateHardLink() so that it
doesn't modify the file's security descriptor.

// Set security descriptor argument to NULL to leave file's security
// descriptor alone.

fCreatedLink = CreateHardLink( pszNewLinkName, pszExistingFileName, NULL );
if (!fCreatedLink)
  ; // error occurred, handle it.

NOTE: PszExistingFileName can be the original filename, or any already-existing
link to the file. After this code is executed, pszNewLinkName will refer to the
file.

BackupWrite() Example

The sample code demonstrates how to use BackupWrite() to create a
hard link on an NTFS volume. Basically, it "restores" a link to the file.

PseudoCode Algorithm for Restoring POSIX File Links

  1.  While there are more files to restore
  2.    If the file is a LINK
  3.      Use the full path which was saved as data to open the file.
  4.      Init a WIN32_STREAM_ID structure with dwStreamId equal to BACKUP_LINK.
  5.      Init the dwStreamAttributes to 0.
  6.      Init the dwStreamNameSize to 0.
  7.      Init a UNICODE buffer containing the full path of the file you are restoring.
  8.      Init the dwStreamSizeHigh to 0.
  9.      Init the dwStreamSizeLow to the byte size of the buffer containing the full path.
  10.     Call BackupWrite() with the WIN32_STREAM_ID
  11.     Call BackupWrite() with the buffer containing the full path.
  12.   Else
  13.     Call BackupWrite() with the data stored on your backup media.
  14.   Endif
  15. EndWhile

  NOTE: The new link name must be supplied in Unicode to BackupWrite().

Last MS Review: June 16, 1999
Last LN Review: April, 2021
*/

#ifndef FILE_SUPPORTS_HARD_LINKS
#define FILE_SUPPORTS_HARD_LINKS 0x00400000
#endif

bool _CreateHardLink( CSTR LinkName, CSTR TargetName )
{
    HANDLE hToken, hTarget;
    TOKEN_PRIVILEGES tp = { 1, { 0,0,0 }};
    DWORD error = 0, volFlg;
    BOOL ok = false, prvOk;

    if (FileExist( LinkName ))
    {
        error = ERROR_FILE_EXISTS;
        goto __chl_Exit;
    }
  #if 1 // N.B: Flag declared in XP (but not implemented before Win7 ?).
    volFlg = __GetVolumeFlags( LinkName );
    ok = BITS_SET( FILE_SUPPORTS_HARD_LINKS, volFlg );
    if (!ok)
    {
        error = ERROR_CALL_NOT_IMPLEMENTED;
        goto __chl_Exit;
    }
  #else
    UNUSED( volFlg );
  #endif

    // BackupWrite requires the SE_RESTORE_NAME privilege.
    prvOk = __EnableProcPrivilege( SE_RESTORE_NAME, &tp.Privileges[0], &hToken );

    // Open existing file that we link to

    hTarget = CheckHandle( CreateFile(
        TargetName, FILE_WRITE_ATTRIB_EA, FILE_SHARE_READ, NULL,
        OPEN_EXISTING, 0, NULL
        ));
    ok = __ChkOkGetErr( hTarget != NULL, &error );
    if (ok)
    {
        // Validate and sanitize supplied link path.

        TCHAR szLinkName[ MAX_PATH ]; // Full pathname of link
        DWORD ccLinkName = GetFullPathName( LinkName, MAX_PATH, szLinkName, NULL );
        ok = __ChkOkGetErr( ccLinkName > 0, &error );
        if (ok)
        {
            // Hard links must be on the same volume, so rather than facing
            // ramifications of a BackupWrite failure, let's pre-check it.

            DWORD TargetVol = __GetHandleVolumeId( hTarget );
            DWORD LinkVol = __GetVolumeId( szLinkName );
            if (LinkVol != TargetVol)
            {
                error = ERROR_NOT_SAME_DEVICE;
                goto __chl_CloseTrg;
            }

          #ifdef _UNICODE
            #define wzLinkName  szLinkName
          #else
            WCHAR wzLinkName[ MAX_PATH ];
            // The full path MUST be Unicode for BackupWrite.
            MultiByteToWideChar( CP_ACP, 0, szLinkName,-1, wzLinkName, MAX_PATH );
          #endif
            DWORD cbLinkName = (ccLinkName+1) * sizeof(WCHAR);
            PVOID pBkupCtx = NULL; // Internal BackupWrite context.

            // Prepare and write the WIN32_STREAM_ID out

            WIN32_STREAM_ID sid;
            ZeroMemory( &sid, sizeof(WIN32_STREAM_ID) );
            sid.dwStreamId = BACKUP_LINK;
            sid.Size.u.LowPart = cbLinkName;

            DWORD cbWr, cbStreamHdr = FIELD_OFFSET( WIN32_STREAM_ID, cStreamName );

            ok = BackupWrite( hTarget,
                (PBYTE)&sid, cbStreamHdr, &cbWr, false, false,
                &pBkupCtx
                );
            if (__ChkOkGetErr( ok, &error ))
            {
                // Write out the buffer containing the link pathname.
                // FYI: Sadly, the OS is not as clever as I in determining if the link
                // and target are on the same volume, so this fails with ERROR_NOT_SAME_DEVICE
                // if you specify a share name for one and a dos path for the other, even
                // if they are the same physical volume. (I don't flunk that, see above).

                ok = BackupWrite( hTarget,
                    (PBYTE)wzLinkName, cbLinkName, &cbWr, false, false,
                    &pBkupCtx
                    );
                if (!ok) error = GetLastError();

                // Free the context

                BOOL bkOk = BackupWrite( hTarget, NULL, 0, &cbWr, true, false, &pBkupCtx );
                // Only pick up a "backup done" error if there was no previous error.
                if (ok && !bkOk) { ok = bkOk; error = GetLastError(); }
            }
        }
      __chl_CloseTrg:
        CloseHandle( hTarget );
    }
    if (prvOk) RestorePrivilege( hToken, &tp );
    if (hToken) CloseHandle( hToken );

  __chl_Exit:
    if (!ok && error) SetLastError( error );
    return bool_cast( ok );
}

//++ EnumerateHardLinks +------------------------------------------------------
#if (WINVER >= 0x0600) // FindFirstFileNameW requires Vista.

// Alphatest passed: Gives full path from relative input path on current drive.

UINT EnumerateHardLinks( CSTR FileName, PFnEnumHardLinks Action, PVOID usrData )
{
    UINT nLinks = 0;
    // In Unicode, the wzLink buffer is passed to Action verbatim.
    WSTR wzLink = mem_AllocWStr( MAX_PATH ); // Not on stack, for safety's sake.

    // FindFirstFileName/FindNextFileName doesn't give us a drive spec,
    // so do some value added processing to give the caller absolute paths.

    WSTR pwzLink = wzLink; // Buffer pointer for FindFirstFileName/FindNextFileName
    DWORD ccDrv = 0; // Drive spec length to subtract from buffer size

  #ifdef _UNICODE
    #define wzFile FileName
  #else // We need two char conversion buffers, since the APIs are W only.
    WSTR wzFile = mem_WDupAStr( FileName, CP_ACP ); // Convert FileName to unicode
    TSTR pzLink = mem_AllocAStr( MAX_PATH ); // Buffer for the Action call-out
  #endif

    WCSTR pwzSep = wcschr( wzFile, COLON ); // Do we have a drive spec ?
    if (pwzSep) // Yes.. Copy it to wzLink
    {
        ccDrv = DWORD( 1 + CharIndex( wzFile, pwzSep ));
        wcsncpyz( wzLink, wzFile, ccDrv+1 );
    }
    else if (GetFullPathNameW( wzFile, MAX_PATH, wzLink, NULL )) // No, get one into wzLink
    {
        wzLink[0] = towupper( wzLink[0] ); // Upper case drive char looks better
        pwzSep = wcschr( wzLink, COLON );  // Skip past drive spec
        ccDrv = DWORD( 1 + CharIndex( wzLink, pwzSep ));
    }
    pwzLink += ccDrv; // Fwd the buffer ptr past the drive spec

    // Now we can do the hardlink enumeration and produce absolute paths...

    DWORD ccLink = MAX_PATH - ccDrv;
    HANDLE hFind = CheckHandle( FindFirstFileNameW( wzFile, 0, &ccLink, pwzLink ));
    while( hFind )
    {
        nLinks++;
      #ifdef _UNICODE
        bool proceed = Action( wzLink, usrData );
      #else
        WideCharToMultiByte( CP_ACP, 0, wzLink, -1, pzLink, MAX_PATH, NULL, NULL );
        bool proceed = Action( pzLink, usrData );
      #endif
        ccLink = MAX_PATH - ccDrv;
        if (!proceed || !FindNextFileNameW( hFind, &ccLink, pwzLink ))
            hFind = FindCloseEx( hFind );
    }

    mem_Free( wzLink );
  #ifndef _UNICODE
    mem_Free( wzFile );
    mem_Free( pzLink );
  #endif
    return nLinks;
}

#endif//(WINVER >= 0x0600)
// EOF