Funzione CreateHardLinkA (winbase.h)

Articolo
03/03/2024

Stabilisce un collegamento rigido tra un file esistente e un nuovo file. Questa funzione è supportata solo nel file system NTFS e solo per i file, non per le directory.

Per eseguire questa operazione come operazione transazionata, utilizzare la funzione CreateHardLinkTransacted .

Sintassi

BOOL CreateHardLinkA(
  [in] LPCSTR                lpFileName,
  [in] LPCSTR                lpExistingFileName,
       LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parametri

[in] lpFileName

Nome del nuovo file.

Questo parametro può includere il percorso, ma non può specificare il nome di una directory.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, anteporre "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

Suggerimento

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente a rimuovere la limitazione MAX_PATH senza anteporre "\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di Denominazione di file, percorsi e spazi dei nomi .

[in] lpExistingFileName

Nome del file esistente.

Questo parametro può includere il percorso non può specificare il nome di una directory.

Suggerimento

lpSecurityAttributes

Riservati; deve essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero (0). Per informazioni dettagliate sull'errore, chiamare GetLastError.

Il numero massimo di collegamenti reali che è possibile creare con questa funzione è 1023 per file. Se vengono creati più di 1023 collegamenti per un file, viene restituito un errore.

Se si passa un nome più lungo di MAX_PATH caratteri al parametro lpFileName o lpExistingFileName della versione ANSI di questa funzione o alla versione Unicode di questa funzione senza anteporre "\?\\" al percorso, la funzione restituisce ERROR_PATH_NOT_FOUND.

Commenti

Qualsiasi voce di directory per un file creato con CreateFile o CreateHardLink è un collegamento rigido a un file associato. Un collegamento rigido aggiuntivo creato con la funzione CreateHardLink consente di avere più voci di directory per un file, ovvero più collegamenti reali allo stesso file, che possono essere nomi diversi nella stessa directory o nomi uguali o diversi in directory diverse. Tuttavia, tutti i collegamenti rigidi a un file devono trovarsi nello stesso volume.

Poiché i collegamenti rigidi sono solo voci di directory per un file, molte modifiche al file sono immediatamente visibili alle applicazioni che vi accedono tramite i collegamenti reali che vi fanno riferimento. Tuttavia, le dimensioni della voce di directory e le informazioni sull'attributo vengono aggiornate solo per il collegamento tramite il quale è stata apportata la modifica.

Il descrittore di sicurezza appartiene al file a cui punta un collegamento rigido. Il collegamento stesso è solo una voce di directory e non dispone di un descrittore di sicurezza. Pertanto, quando si modifica il descrittore di sicurezza di un collegamento rigido, si modifica il descrittore di sicurezza del file sottostante e tutti i collegamenti reali che puntano al file consentono l'accesso appena specificato. Non è possibile assegnare a un file descrittori di sicurezza diversi per ogni collegamento rigido.

Questa funzione non modifica il descrittore di sicurezza del file in modo che sia collegato, anche se le informazioni sul descrittore di sicurezza vengono passate nel parametro lpSecurityAttributes .

Usare DeleteFile per eliminare i collegamenti reali. È possibile eliminarli in qualsiasi ordine indipendentemente dall'ordine in cui vengono creati.

Flag, attributi, accesso e condivisione specificati in CreateFile operano in base ai singoli file. Ovvero, se si apre un file che non consente la condivisione, un'altra applicazione non può condividere il file creando un nuovo collegamento rigido al file.

Quando si crea un collegamento rigido nel file system NTFS, le informazioni sull'attributo del file nella voce di directory vengono aggiornate solo quando il file viene aperto o quando viene chiamato GetFileInformationByHandle con l'handle di un file specifico.

Comportamento del collegamento simbolico: se il percorso punta a un collegamento simbolico, la funzione crea un collegamento rigido al collegamento simbolico.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	No
SMB 3.0 con condivisioni file di scalabilità orizzontale (SO)	No
File system del volume condiviso cluster (CsvFS)	Sì
Resilient File System (ReFS)	No

Si noti che SMB 3.0 non supporta la creazione di collegamenti reali nelle condivisioni con funzionalità di disponibilità continua.

Esempio

Il frammento di codice seguente illustra come chiamare CreateHardLink in modo che non modifichi il descrittore di sicurezza di un file. Il parametro pszExistingFileName può essere il nome file originale o qualsiasi collegamento esistente a un file. Dopo l'esecuzione di questo codice, pszNewLinkName fa riferimento al file .

  BOOL fCreatedLink = CreateHardLink( pszNewLinkName, 
                                      pszExistingFileName, 
                                      NULL ); // reserved, must be NULL

  if ( fCreatedLink == FALSE )
   {
    ;// handle error condition
   }

Nota

L'intestazione winbase.h definisce CreateHardLink come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll