Função ZwCreateSection (wdm.h)

Artigo
03/01/2024

A rotina ZwCreateSection cria um objeto de seção.

Sintaxe

NTSYSAPI NTSTATUS ZwCreateSection(
  [out]          PHANDLE            SectionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PLARGE_INTEGER     MaximumSize,
  [in]           ULONG              SectionPageProtection,
  [in]           ULONG              AllocationAttributes,
  [in, optional] HANDLE             FileHandle
);

Parâmetros

[out] SectionHandle

Ponteiro para uma variável HANDLE que recebe um identificador para o objeto de seção.

[in] DesiredAccess

Especifica um valor ACCESS_MASK que determina o acesso solicitado ao objeto . Além dos direitos de acesso definidos para todos os tipos de objetos (consulte ACCESS_MASK), o chamador pode especificar qualquer um dos seguintes direitos de acesso, que são específicos para objetos de seção:

Sinalizador DesiredAccess	Permite que o chamador faça isso
SECTION_EXTEND_SIZE	Estenda dinamicamente o tamanho da seção.
SECTION_MAP_EXECUTE	Execute exibições da seção.
SECTION_MAP_READ	Ler exibições da seção.
SECTION_MAP_WRITE	Escreva exibições da seção.
SECTION_QUERY	Consulte o objeto section para obter informações sobre a seção. Os drivers devem definir esse sinalizador.
SECTION_ALL_ACCESS	Todos os sinalizadores anteriores combinados com STANDARD_RIGHTS_REQUIRED.

[in, optional] ObjectAttributes

Ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica o nome do objeto e outros atributos. Use InitializeObjectAttributes para inicializar essa estrutura. Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE quando chamar InitializeObjectAttributes.

[in, optional] MaximumSize

Especifica o tamanho máximo, em bytes, da seção . ZwCreateSection arredonda esse valor para cima até o múltiplo mais próximo de PAGE_SIZE. Se a seção for apoiada pelo arquivo de paginação, MaximumSize especificará o tamanho real da seção. Se a seção for apoiada por um arquivo comum, MaximumSize especificará o tamanho máximo para o qual o arquivo pode ser estendido ou mapeado.

[in] SectionPageProtection

Especifica a proteção a ser colocada em cada página da seção. Use um dos quatro valores a seguir: PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE ou PAGE_WRITECOPY. Para obter uma descrição desses valores, consulte CreateFileMapping.

[in] AllocationAttributes

Especifica uma máscara de bits de sinalizadores SEC_XXX que determina os atributos de alocação da seção. Para obter uma descrição desses sinalizadores, consulte CreateFileMapping.

[in, optional] FileHandle

Opcionalmente, especifica um identificador para um objeto de arquivo aberto. Se o valor de FileHandle for NULL, a seção será apoiada pelo arquivo de paginação. Caso contrário, a seção será apoiada pelo arquivo especificado.

Retornar valor

ZwCreateSection retorna STATUS_SUCCESS em caso de êxito ou o código de erro NTSTATUS apropriado em caso de falha. Possíveis códigos de status de erro incluem o seguinte:

Código de retorno	Descrição
STATUS_FILE_LOCK_CONFLICT	O arquivo especificado pelo parâmetro FileHandle está bloqueado.
STATUS_INVALID_FILE_FOR_SECTION	O arquivo especificado por FileHandle não dá suporte a seções.
STATUS_INVALID_PAGE_PROTECTION	O valor especificado para o parâmetro SectionPageProtection é inválido.
STATUS_MAPPED_FILE_SIZE_ZERO	O tamanho do arquivo especificado por FileHandle é zero e MaximumSize é zero.
STATUS_SECTION_TOO_BIG	O valor de MaximumSize é muito grande. Isso ocorre quando MaximumSize é maior que o máximo definido pelo sistema para seções ou se MaximumSize é maior que o arquivo especificado e a seção não é gravável.

Comentários

Depois que o identificador apontado por SectionHandle não estiver mais em uso, o driver deverá chamar ZwClose para fechá-lo.

Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá garantir que todos os identificadores que ele cria sejam identificadores privados. Caso contrário, o identificador pode ser acessado pelo processo em cujo contexto o driver está em execução. Para obter mais informações, consulte Identificadores de objeto.

Para obter mais informações sobre como configurar seções mapeadas e exibições de memória, consulte Seções e exibições.

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtCreateSection" em vez de "ZwCreateSection".

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Using Nt and Zw Versions of the Native System Services Routines.