Função CreateHardLinkW (winbase.h)
Estabelece um vínculo rígido entre um arquivo existente e um novo arquivo. Essa função só tem suporte no sistema de arquivos NTFS e somente para arquivos, não para diretórios.
Para executar essa operação como uma operação transacionada, use a função CreateHardLinkTransacted.
Sintaxe
BOOL CreateHardLinkW(
[in] LPCWSTR lpFileName,
[in] LPCWSTR lpExistingFileName,
LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
Parâmetros
[in] lpFileName
O nome do novo arquivo.
Esse parâmetro pode incluir o caminho, mas não pode especificar o nome de um diretório.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Ponta
A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de arquivos de nomenclatura, caminhos e namespaces para obter detalhes.
[in] lpExistingFileName
O nome do arquivo existente.
Esse parâmetro pode incluir o caminho que não pode especificar o nome de um diretório.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Ponta
A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de arquivos de nomenclatura, caminhos e namespaces para obter detalhes.
lpSecurityAttributes
Reservado; deve ser NULL.
Valor de retorno
Se a função for bem-sucedida, o valor retornado não será zero.
Se a função falhar, o valor retornado será zero (0). Para obter informações de erro estendidas, chame GetLastError.
O número máximo de links rígidos que podem ser criados com essa função é 1023 por arquivo. Se mais de 1023 links forem criados para um arquivo, um erro resultará.
Se você passar um nome maior que MAX_PATH caracteres para o lpFileName ou parâmetro lpExistingFileName da versão ANSI dessa função ou para a versão Unicode dessa função sem acrescentar "\\?\" ao caminho, a função retornará ERROR_PATH_NOT_FOUND.
Observações
Qualquer entrada de diretório para um arquivo criado com CreateFile ou CreateHardLink é um link rígido para um arquivo associado. Um link rígido adicional criado com a função CreateHardLink permite que você tenha várias entradas de diretório para um arquivo, ou seja, vários links rígidos para o mesmo arquivo, que podem ser nomes diferentes no mesmo diretório ou os mesmos nomes ou nomes diferentes em diretórios diferentes. No entanto, todos os links rígidos para um arquivo devem estar no mesmo volume.
Como os links rígidos são apenas entradas de diretório para um arquivo, muitas alterações nesse arquivo são instantaneamente visíveis para aplicativos que o acessam por meio dos links rígidos que fazem referência a ele. No entanto, as informações de tamanho e atributo da entrada do diretório são atualizadas apenas para o link por meio do qual a alteração foi feita.
O descritor de segurança pertence ao arquivo ao qual um link rígido aponta. O link em si é apenas uma entrada de diretório e não tem um descritor de segurança. Portanto, ao alterar o descritor de segurança de um link rígido, você altera o descritor de segurança do arquivo subjacente e todos os links rígidos que apontam para o arquivo permitem o acesso recém-especificado. Não é possível fornecer descritores de segurança diferentes a um arquivo por link rígido.
Essa função não modifica o descritor de segurança do arquivo ao qual estar vinculado, mesmo que as informações do descritor de segurança sejam passadas no parâmetro lpSecurityAttributes.
Use DeleteFile para excluir links rígidos. Você pode excluí-las em qualquer ordem, independentemente da ordem em que elas são criadas.
Sinalizadores, atributos, acesso e compartilhamento especificados no CreateFile operam por arquivo. Ou seja, se você abrir um arquivo que não permite o compartilhamento, outro aplicativo não poderá compartilhar o arquivo criando um novo link rígido para o arquivo.
Quando você cria um link rígido no sistema de arquivos NTFS, as informações de atributo de arquivo na entrada do diretório são atualizadas somente quando o arquivo é aberto ou quando GetFileInformationByHandle é chamado com o identificador de um arquivo específico.
Comportamento simbólico de vínculo — se o caminho apontar para um vínculo simbólico, a função criará um vínculo rígido com o vínculo simbólico.
No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Suportado |
|---|---|
| Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 | Sim |
| TFO (Failover Transparente) do SMB 3.0 | Não |
| SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) | Não |
| Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Não |
Observe que o SMB 3.0 não dá suporte à criação de links rígidos em compartilhamentos com capacidade de disponibilidade contínua.
Exemplos
O snippet de código a seguir mostra como chamar CreateHardLink para que ele não modifique o descritor de segurança de um arquivo. O parâmetro pszExistingFileName pode ser o nome do arquivo original ou qualquer link existente para um arquivo. Depois que esse código é executado, pszNewLinkName refere-se ao arquivo.
BOOL fCreatedLink = CreateHardLink( pszNewLinkName,
pszExistingFileName,
NULL ); // reserved, must be NULL
if ( fCreatedLink == FALSE )
{
;// handle error condition
}
Nota
O cabeçalho winbase.h define CreateHardLink como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winbase.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |