Função CreateFileMappingNumaW (memoryapi.h)

Artigo
11/20/2024

Cria ou abre um objeto de mapeamento de arquivo nomeado ou sem nome para um arquivo especificado e especifica o nó NUMA para a memória física.

Sintaxe

HANDLE CreateFileMappingNumaW(
  [in]           HANDLE                hFile,
  [in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  [in]           DWORD                 flProtect,
  [in]           DWORD                 dwMaximumSizeHigh,
  [in]           DWORD                 dwMaximumSizeLow,
  [in, optional] LPCWSTR               lpName,
  [in]           DWORD                 nndPreferred
);

Parâmetros

[in] hFile

Um identificador para o arquivo do qual criar um objeto de mapeamento de arquivo.

O arquivo deve ser aberto com direitos de acesso compatíveis com os sinalizadores de proteção que o parâmetro flProtect especifica. Não é necessário, mas é recomendável que os arquivos que você pretende mapear sejam abertos para acesso exclusivo. Para obter mais informações, consulte de Segurança de Arquivos e Direitos de Acesso.

Se hFile for INVALID_HANDLE_VALUE, o processo de chamada também deverá especificar um tamanho para o objeto de mapeamento de arquivo nos parâmetros dwMaximumSizeHigh e dwMaximumSizeLow. Nesse cenário, CreateFileMappingNuma cria um objeto de mapeamento de arquivo de um tamanho especificado que é apoiado pelo arquivo de paginação do sistema em vez de por um arquivo no sistema de arquivos.

[in, optional] lpFileMappingAttributes

Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que determina se um identificador retornado pode ser herdado por processos filho. O lpSecurityDescriptor membro do
SECURITY_ATTRIBUTES estrutura especifica um descritor de segurança para um novo objeto de mapeamento de arquivo.

Se lpFileMappingAttributes for NULL, o identificador não poderá ser herdado e o objeto de mapeamento de arquivo obterá um descritor de segurança padrão. As ACL (listas de controle de acesso) no descritor de segurança padrão para um objeto de mapeamento de arquivo vêm do token primário ou de representação do criador. Para obter mais informações, consulte segurança de mapeamento de arquivos e direitos de acesso.

[in] flProtect

Especifica a proteção de página do objeto de mapeamento de arquivo. Todas as exibições mapeadas do objeto devem ser compatíveis com essa proteção.

Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
PAGE_EXECUTE_READ 0x20	Permite que as exibições sejam mapeadas para acesso somente leitura, cópia em gravação ou execução. O identificador de arquivo especificado pelo parâmetro hFile deve ser criado com os direitos de acesso GENERIC_READ e GENERIC_EXECUTE.
PAGE_EXECUTE_READWRITE 0x40	Permite que as exibições sejam mapeadas para acesso somente leitura, cópia na gravação, leitura/gravação ou execução. O identificador de arquivo especificado pelo parâmetro hFile deve ser criado com os direitos de acesso GENERIC_READ, GENERIC_WRITEe GENERIC_EXECUTE.
PAGE_EXECUTE_WRITECOPY 0x80	Permite que as exibições sejam mapeadas para acesso somente leitura, cópia em gravação ou execução. Esse valor é equivalente a PAGE_EXECUTE_READ. O identificador de arquivo especificado pelo parâmetro hFile deve ser criado com os direitos de acesso GENERIC_READ e GENERIC_EXECUTE. Windows Vista: Esse valor não estará disponível até o Windows Vista com SP1.
PAGE_READONLY 0x02	Permite que as exibições sejam mapeadas para acesso somente leitura ou cópia em gravação. Uma tentativa de gravar em uma região específica resulta em uma violação de acesso. O identificador de arquivo especificado pelo parâmetro hFile deve ser criado com o GENERIC_READ direito de acesso.
PAGE_READWRITE 0x04	Permite que as exibições sejam mapeadas para acesso somente leitura, cópia em gravação ou leitura/gravação. O identificador de arquivo especificado pelo parâmetro hFile deve ser criado com os direitos de acesso GENERIC_READ e GENERIC_WRITE.
PAGE_WRITECOPY 0x08	Permite que as exibições sejam mapeadas para acesso somente leitura ou cópia em gravação. Esse valor é equivalente a PAGE_READONLY. O identificador de arquivo especificado pelo parâmetro hFile deve ser criado com o GENERIC_READ direito de acesso.

Um aplicativo pode especificar um ou mais dos seguintes atributos para o objeto de mapeamento de arquivo combinando-os com um dos valores de proteção de página anteriores.

Valor	Significado
SEC_COMMIT 0x8000000	Aloca o armazenamento físico na memória ou no arquivo de paginação para todas as páginas. Essa é a configuração padrão.
SEC_IMAGE 0x1000000	Define o arquivo especificado para ser um arquivo de imagem executável. O atributo SEC_IMAGE deve ser combinado com um valor de proteção de página, como PAGE_READONLY. No entanto, esse valor de proteção de página não tem efeito sobre as exibições do arquivo de imagem executável. A proteção de página para exibições de um arquivo de imagem executável é determinada pelo próprio arquivo executável. Nenhum outro atributo é válido com SEC_IMAGE.
SEC_IMAGE_NO_EXECUTE 0x11000000	Especifica que o arquivo que o parâmetro hFile especifica é um arquivo de imagem executável que não será executado e o arquivo de imagem carregado não terá nenhuma execução de verificações de integridade forçadas. Além disso, mapear uma exibição de um objeto de mapeamento de arquivo criado com o atributo SEC_IMAGE_NO_EXECUTE não invocará retornos de chamada de driver registrados usando a API de kernel PsSetLoadImageNotifyRoutine . O atributo SEC_IMAGE_NO_EXECUTE deve ser combinado com o valor de proteção de página PAGE_READONLY. Nenhum outro atributo é válido com SEC_IMAGE_NO_EXECUTE. Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Esse valor não tem suporte antes do Windows Server 2012 e do Windows 8.
SEC_LARGE_PAGES 0x80000000	Permite que páginas grandes sejam usadas ao mapear imagens ou fazer backup do arquivo de página, mas não ao mapear dados para arquivos regulares. Especifique o tamanho máximo do objeto de mapeamento de arquivo como o tamanho mínimo de uma página grande relatada pela função GetLargePageMinimum e habilite o privilégio SeLockMemoryPrivilege.
SEC_NOCACHE 0x10000000	Define todas as páginas como não em cache. Os aplicativos não devem usar esse sinalizador, exceto quando explicitamente necessários para um dispositivo. Usar as funções intertravadas com memória mapeada com SEC_NOCACHE pode resultar em uma exceção EXCEPTION_ILLEGAL_INSTRUCTION. SEC_NOCACHE requer que SEC_RESERVE ou SEC_COMMIT sejam definidos.
SEC_RESERVE 0x4000000	Reserva todas as páginas sem alocar armazenamento físico. O intervalo reservado de páginas não pode ser usado por outras operações de alocação até que o intervalo de páginas seja liberado. As páginas reservadas podem ser identificadas em chamadas subsequentes para a função VirtualAllocExNuma. Esse atributo só será válido se o parâmetro hFile for INVALID_HANDLE_VALUE (ou seja, um objeto de mapeamento de arquivo que é apoiado pelo arquivo de paginação do sistema).
SEC_WRITECOMBINE 0x40000000	Define todas as páginas a serem combinadas com gravação. Os aplicativos não devem usar esse atributo, exceto quando explicitamente necessários para um dispositivo. Usar as funções intertravadas com memória mapeada com SEC_WRITECOMBINE pode resultar em uma exceção EXCEPTION_ILLEGAL_INSTRUCTION. SEC_WRITECOMBINE requer que o atributo SEC_RESERVE ou SEC_COMMIT seja definido.

[in] dwMaximumSizeHigh

A DWORD de alta ordem do tamanho máximo do objeto de mapeamento de arquivo.

[in] dwMaximumSizeLow

O DWORD de baixa ordem do tamanho máximo do objeto de mapeamento de arquivo.

Se esse parâmetro e o parâmetro dwMaximumSizeHigh forem 0 (zero), o tamanho máximo do objeto de mapeamento de arquivo será igual ao tamanho atual do arquivo identificado pelo hFile parâmetro.

Uma tentativa de mapear um arquivo com um comprimento de 0 (zero) falha com um código de erro de ERROR_FILE_INVALID. Os aplicativos devem testar arquivos com um comprimento de 0 (zero) e rejeitar esses arquivos.

[in, optional] lpName

O nome do objeto de mapeamento de arquivo.

Se esse parâmetro corresponder ao nome de um objeto de mapeamento de arquivo existente, a função solicitará acesso ao objeto com a proteção especificada pelo parâmetro flProtect.

Se esse parâmetro for NULL, o objeto de mapeamento de arquivo será criado sem um nome.

Se o parâmetro lpName corresponder ao nome de um evento existente, semáforo, mutex, temporizador de espera ou objeto de trabalho, a função falhará e a função GetLastError retornará ERROR_INVALID_HANDLE. Isso ocorre porque esses objetos compartilham o mesmo namespace.

O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). A criação de um objeto de mapeamento de arquivo no namespace global requer o privilégio SeCreateGlobalPrivilege. Para obter mais informações, consulte namespaces de objeto kernel.

A alternância rápida de usuário é implementada usando sessões dos Serviços de Terminal. O primeiro usuário a fazer logon usa a sessão 0 (zero), o próximo usuário a fazer logon usa a sessão 1 (uma) e assim por diante. Os nomes de objeto kernel devem seguir as diretrizes para que os aplicativos possam dar suporte a vários usuários.

[in] nndPreferred

O nó NUMA no qual a memória física deve residir.

Valor	Significado
NUMA_NO_PREFERRED_NODE 0xffffffff	Nenhum nó NUMA é preferencial. Isso é o mesmo que chamar a função CreateFileMapping.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de mapeamento de arquivo.

Se o objeto existir antes da chamada de função, a função retornará um identificador para o objeto existente (com seu tamanho atual, não o tamanho especificado) e a função GetLastError retornará ERROR_ALREADY_EXISTS.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame a função GetLastError.

Observações

Depois que um objeto de mapeamento de arquivo é criado, o tamanho do arquivo não deve exceder o tamanho do objeto de mapeamento de arquivo; se isso acontecer, nem todo o conteúdo do arquivo estará disponível para compartilhamento.

O objeto de mapeamento de arquivo pode ser compartilhado por duplicação, herança ou nome. O conteúdo inicial das páginas em um objeto de mapeamento de arquivo apoiado pelo arquivo de página é 0 (zero).

Se um aplicativo especificar um tamanho para o objeto de mapeamento de arquivo maior que o tamanho do arquivo nomeado real no disco e se a proteção de página permitir acesso de gravação (ou seja, o parâmetro flProtect especifica PAGE_READWRITE ou PAGE_EXECUTE_READWRITE), o arquivo no disco será aumentado para corresponder ao tamanho especificado do objeto de mapeamento de arquivo. Se o arquivo for estendido, o conteúdo do arquivo entre a extremidade antiga do arquivo e o novo final do arquivo não será garantido como zero; o comportamento é definido pelo sistema de arquivos.

Se o arquivo não puder ser aumentado, o resultado será uma falha ao criar o objeto de mapeamento de arquivo e a função GetLastError retornará ERROR_DISK_FULL.

O identificador que a função CreateFileMappingNuma retorna tem acesso total a um novo objeto de mapeamento de arquivo e pode ser usado com qualquer função que exija um identificador para um objeto de mapeamento de arquivo. Um objeto de mapeamento de arquivo pode ser compartilhado por meio da criação do processo, do identificador da duplicação ou do nome. Para obter mais informações, consulte as funções DuplicateHandle e OpenFileMapping.

A criação de um objeto de mapeamento de arquivo cria o potencial para mapear uma exibição do arquivo, mas não mapeia a exibição. A função MapViewOfFileExNuma mapeia uma exibição de um arquivo para um espaço de endereço do processo.

Com uma exceção importante, as exibições de arquivo derivadas de um único objeto de mapeamento de arquivo são coerentes ou idênticas em um momento específico. Se vários processos tiverem identificadores do mesmo objeto de mapeamento de arquivo, eles verão uma exibição coerente dos dados quando mapearem uma exibição do arquivo.

A exceção está relacionada a arquivos remotos. Embora a função CreateFileMappingNuma funcione com arquivos remotos, ela não os mantém coerentes. Por exemplo, se dois computadores mapearem um arquivo como gravável e ambos mudarem a mesma página, cada computador verá apenas suas próprias gravações na página. Quando os dados são atualizados no disco, a página não é mesclada.

Um arquivo mapeado e um arquivo que é acessado usando as funções de entrada e saída (E/S) ( ReadFile e WriteFile) não são necessariamente coerentes.

Para fechar totalmente um objeto de mapeamento de arquivo, um aplicativo deve desapacar todas as exibições mapeadas do objeto de mapeamento de arquivo chamando a função UnmapViewOfFile e, em seguida, fechar o identificador de objeto de mapeamento de arquivo chamando a função CloseHandle .

Essas funções podem ser chamadas em qualquer ordem. A chamada para a função UnmapViewOfFile é necessária, pois as exibições mapeadas de um objeto de mapeamento de arquivo mantêm identificadores abertos internos para o objeto e um objeto de mapeamento de arquivo não fecha até que todas as alças abertas sejam fechadas.

Ao modificar um arquivo por meio de uma exibição mapeada, o carimbo de data/hora da última modificação pode não ser atualizado automaticamente. Se necessário, o chamador deve usar SetFileTime para definir o carimbo de data/hora.

A criação de um objeto de mapeamento de arquivo de uma sessão diferente de zero de sessão requer o privilégio SeCreateGlobalPrivilege. Observe que essa verificação de privilégio é limitada à criação de objetos de mapeamento de arquivos e não se aplica à abertura dos existentes. Por exemplo, se um serviço ou o sistema criar um objeto de mapeamento de arquivo, qualquer processo em execução em qualquer sessão poderá acessar esse objeto de mapeamento de arquivo desde que o chamador tenha os direitos de acesso necessários.

Use o tratamento de exceção estruturado para proteger qualquer código que grava ou lê de um modo de exibição mapeado de memória. Para obter mais informações, consulte leitura e gravação de uma exibição de arquivo.

Para ter um mapeamento com permissões executáveis, um aplicativo deve chamar a função CreateFileMappingNuma com PAGE_EXECUTE_READWRITE ou PAGE_EXECUTE_READ e chamar a função MapViewOfFileExNuma com ou .

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	memoryapi.h (inclua Windows.h, Memoryapi.h)
biblioteca	onecore.lib
de DLL	Kernel32.dll