Função CreateDirectoryExA (winbase.h)

Artigo
06/02/2023

Cria um novo diretório com os atributos de um diretório de modelo especificado. Se o sistema de arquivos subjacente der suporte à segurança em arquivos e diretórios, a função aplicará um descritor de segurança especificado ao novo diretório. O novo diretório retém os outros atributos do diretório de modelo especificado.

Para executar essa operação como uma operação transacionada, use a função CreateDirectoryTransacted .

Sintaxe

BOOL CreateDirectoryExA(
  [in]           LPCSTR                lpTemplateDirectory,
  [in]           LPCSTR                lpNewDirectory,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parâmetros

[in] lpTemplateDirectory

O caminho do diretório a ser usado como modelo ao criar o novo diretório.

Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

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 de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

[in] lpNewDirectory

O caminho do diretório a ser criado.

Dica

[in, optional] lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para o novo diretório.

Se lpSecurityAttributes for NULL, o diretório receberá um descritor de segurança padrão. As ACL (listas de controle de acesso) no descritor de segurança padrão para um diretório são herdadas de seu diretório pai.

O sistema de arquivos de destino deve dar suporte à segurança em arquivos e diretórios para que esse parâmetro tenha um efeito. Isso é indicado quando GetVolumeInformation retorna FS_PERSISTENT_ACLS.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero (0). Para obter informações de erro estendidas, chame GetLastError. Os possíveis erros incluem o seguinte.

Código de retorno	Descrição
ERROR_ALREADY_EXISTS	O diretório especificado já existe.
ERROR_PATH_NOT_FOUND	Um ou mais diretórios intermediários não existem. Essa função só cria o diretório final no caminho. Para criar todos os diretórios intermediários no caminho, use a função SHCreateDirectoryEx .

Comentários

A função CreateDirectoryEx permite que você crie diretórios que herdam informações de fluxo de outros diretórios. Essa função é útil, por exemplo, quando você está usando diretórios Macintosh, que têm um fluxo de recursos necessário para identificar corretamente o conteúdo do diretório como um atributo.

Alguns sistemas de arquivos, como o sistema de arquivos NTFS, dão suporte à compactação ou criptografia para arquivos e diretórios individuais. Em volumes formatados para esse sistema de arquivos, um novo diretório herda os atributos de compactação e criptografia de seu diretório pai.

Você pode obter um identificador para um diretório chamando a função CreateFile com o sinalizador FILE_FLAG_BACKUP_SEMANTICS definido. Para obter um exemplo de código, consulte CreateFile.

Para dar suporte a funções de herança que consultam o descritor de segurança desse objeto, é possível determinar e relatar heuristicamente que a herança está em vigor. Para obter mais informações, consulte Propagação automática de ACEs herdáveis.

Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0	Sim
TFO (Failover Transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de volume compartilhado de cluster (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Observação

O cabeçalho winbase.h define CreateDirectoryEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll