Função CreateDirectoryA (fileapi.h)

Artigo
11/20/2024

Cria um novo diretório. 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.

Para especificar um diretório de modelo, use a função CreateDirectoryEx.

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

Sintaxe

BOOL CreateDirectoryA(
  [in]           LPCSTR                lpPathName,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parâmetros

[in] lpPathName

O caminho do diretório a ser criado.

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, optional] lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES. O lpSecurityDescriptor membro da estrutura especifica um descritor de segurança para o novo diretório. Se lpSecurityAttributes for NULL, o diretório obterá um descritor de segurança padrão. As ACLs 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 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. 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 criará apenas o diretório final no caminho.

Observações

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.

Um aplicativo pode obter um identificador para um diretório chamando 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 pode determinar heuristicamente e relatar que a herança está em vigor. Consulte Propagação Automática de ACEs Herdáveis para obter mais informações.

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	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

Exemplos

Para obter um exemplo, consulte Recuperar e alterar atributos de arquivo.

Nota

O cabeçalho fileapi.h define CreateDirectory 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 [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	fileapi.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll