Limitação Máxima do Comprimento do Caminho

  • Artigo

Na API do Windows (com algumas exceções discutidas nos parágrafos a seguir), o comprimento máximo de um caminho é MAX_PATH, que é definido como 260 caracteres. Um caminho local é estruturado na seguinte ordem: letra da unidade, dois-pontos, barra invertida, componentes de nome separados por barras invertidas e um caractere nulo de terminação. Por exemplo, o caminho máximo na unidade D é "D:\some 256-character path string<NUL>" em que "<NUL>" representa o caractere nulo de terminação invisível para a página de código do sistema atual. (Os caracteres <> são usados aqui para maior clareza visual e não podem fazer parte de uma cadeia de caracteres de caminho válida.)

Por exemplo, você poderá atingir essa limitação se estiver clonando um repositório git que tenha nomes de arquivo longos em uma pasta que tenha um nome longo.

Observação

As funções de E/S de arquivo na API do Windows convertem "/" em "\" como parte da conversão do nome em um nome de estilo NT, exceto ao usar o prefixo "\\?\", conforme detalhado nas seções a seguir.

A API do Windows tem muitas funções que também têm versões Unicode para permitir um caminho de comprimento estendido para um comprimento de caminho total máximo de 32.767 caracteres. Esse tipo de caminho é composto por componentes separados por barras invertidas, cada um até o valor retornado no parâmetro lpMaximumComponentLength da função GetVolumeInformation (esse valor geralmente é de 255 caracteres). Para especificar um caminho de comprimento estendido, use o prefixo "\\?\". Por exemplo, "\\?\D:\caminho muito longo".

Observação

O caminho máximo de 32.767 caracteres é aproximado, pois o prefixo "\\?\" pode ser expandido para uma cadeia de caracteres mais longa pelo sistema em tempo de execução e essa expansão se aplica ao comprimento total.

O prefixo "\\?\" também pode ser usado com caminhos construídos de acordo com a UNC (convenção de nomenclatura universal). Para especificar esse caminho usando UNC, use o prefixo "\\?\UNC\". Por exemplo, "\\?\UNC\server\share", em que "server" é o nome do computador e "share" é o nome da pasta compartilhada. Esses prefixos não são usados como parte do caminho em si. Eles indicam que o caminho deve ser passado para o sistema com modificação mínima, o que significa que você não pode usar barras para representar separadores de caminho ou um período para representar o diretório atual ou dois ponto para representar o diretório pai. Como você não pode usar o prefixo "\\?\" com um caminho relativo, os caminhos relativos são sempre limitados a um total de MAX_PATH caracteres.

Não é necessário executar nenhuma normalização Unicode em cadeias de caracteres de nome de caminho e arquivo para uso pelas funções de API de E/S de arquivo do Windows porque o sistema de arquivos trata nomes de caminho e arquivo como uma sequência opaca de WCHARs. Qualquer normalização exigida pelo aplicativo deve ser executada com isso em mente, externo de todas as chamadas para funções de API de E/S de arquivo do Windows relacionadas.

Ao usar uma API para criar um diretório, o caminho especificado não pode ser tão longo que você não possa acrescentar um nome de arquivo 8.3 (ou seja, o nome do diretório não pode exceder MAX_PATH menos 12).

O shell e o sistema de arquivos têm requisitos diferentes. É possível criar um caminho com a API do Windows que a interface do usuário do shell não é capaz de interpretar corretamente.

Habilitar caminhos longos no Windows 10, versão 1607 e posterior

A partir do Windows 10, versão 1607, MAX_PATH limitações foram removidas das funções comuns de arquivo e diretório do Win32. No entanto, você deve aceitar o novo comportamento.

Para habilitar o novo comportamento de caminho longo, ambas as seguintes condições devem ser atendidas:

  • A chave Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled (Type: REG_DWORD) do Registro deve existir e ser definida como 1. O valor da chave será armazenado em cache pelo sistema (por processo) após a primeira chamada para um arquivo ou função de diretório Win32 afetado (veja abaixo a lista de funções). A chave do Registro não será recarregada durante o tempo de vida do processo. Para que todos os aplicativos no sistema reconheçam o valor da chave, uma reinicialização pode ser necessária porque alguns processos podem ter sido iniciados antes da chave ser definida.

Você também pode copiar esse código para um .reg arquivo que pode definir isso para você ou usar o comando do PowerShell de uma janela de terminal com privilégios elevados:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem]
"LongPathsEnabled"=dword:00000001

Observação

Essa chave do Registro também pode ser controlada por meio de Política de Grupo em Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths.

  • O manifesto do aplicativo também deve incluir o longPathAware elemento .

    <application xmlns="urn:schemas-microsoft-com:asm.v3">
    <windowsSettings xmlns:ws2="http://schemas.microsoft.com/SMI/2016/WindowsSettings">
        <ws2:longPathAware>true</ws2:longPathAware>
    </windowsSettings>
</application>

Essas são as funções de gerenciamento de diretório que não têm mais restrições de MAX_PATH se você optar por um comportamento de caminho longo: CreateDirectoryW, CreateDirectoryExW GetCurrentDirectoryW RemoveDirectoryW SetCurrentDirectoryW.

Essas são as funções de gerenciamento de arquivos que não têm mais restrições de MAX_PATH se você optar por um comportamento de caminho longo: CopyFileW, CopyFile2, CopyFileExW, CreateFileW, CreateFile2, CreateHardLinkW, CreateSymbolicLinkW, DeleteFileW, FindFirstFileW, FindFirstFileExW, FindNextFileW, GetFileAttributesW, GetFileAttributesExW, SetFileAttributesW, GetFullPathNameW, GetLongPathNameW, MoveFileW, MoveFileExW, MoveFileWithProgressW, ReplaceFileW, SearchPathW, FindFirstFileNameW, FindNextFileNameW, FindFirstStreamW, FindNextStreamW, GetCompressedFileSizeW, GetFinalPathNameByHandleW.