Funzione CreateHardLinkW (winbase.h)
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, usare la funzione CreateHardLinkTransacted.
Sintassi
BOOL CreateHardLinkW(
[in] LPCWSTR lpFileName,
[in] LPCWSTR 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.
Mancia
A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, 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.
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.
Mancia
A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, percorsi e spazi dei nomi.
lpSecurityAttributes
Riservato; 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 ottenere informazioni estese sull'errore, chiamare GetLastError.
Il numero massimo di collegamenti rigidi che è possibile creare con questa funzione è 1023 per file. Se per un file vengono creati più di 1023 collegamenti, viene restituito un errore.
Se si passa un nome più lungo di MAX_PATH caratteri alla lpFileName o lpExistingFileName parametro della versione ANSI di questa funzione o alla versione Unicode di questa funzione senza anteporre "\?\\" al percorso, la funzione restituisce ERROR_PATH_NOT_FOUND.
Osservazioni
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 rigidi allo stesso file, che possono essere nomi diversi nella stessa directory o gli stessi nomi o nomi 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 apportate a tale file sono immediatamente visibili alle applicazioni che vi accedono tramite i collegamenti rigidi 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 è 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 rigidi 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 a cui essere collegato, anche se le informazioni sul descrittore di sicurezza vengono passate nel parametro lpSecurityAttributes.
Usare DeleteFile per eliminare i collegamenti rigidi. È possibile eliminarli in qualsiasi ordine indipendentemente dall'ordine in cui vengono creati.
Flag, attributi, accesso e condivisione specificati in CreateFile operare 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 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 | Sostenuto |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | No |
| Cluster Shared Volume File System (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.
Esempi
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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows Server 2003 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
winbase.h (include Windows.h) |
| libreria |
Kernel32.lib |
| dll | Kernel32.dll |