_CrtSetDbgFlag

Recupera ou modifica o estado do sinalizador _crtDbgFlag para controlar o comportamento de alocação do gerenciador de heap de depuração (somente versão de depuração).

Sintaxe

int _CrtSetDbgFlag(
   int newFlag
);

Parâmetros

newFlag
Novo estado para _crtDbgFlag.

Valor retornado

Retorna o estado anterior de _crtDbgFlag.

Comentários

A função _CrtSetDbgFlag permite que o aplicativo controle como o gerenciador de heap de depuração rastreia alocações de memória modificando os campos de bit do sinalizador _crtDbgFlag. Ao definir os campos de bits, o aplicativo pode instruir o gerenciador de heap de depuração a executar operações especiais de depuração. Existem várias operações possíveis:

• Verificar se há vazamentos de memória quando o aplicativo é encerrado e relatar se algum for encontrado,
• Simulando condições de pouca memória especificando que os blocos de memória liberados devem permanecer na lista vinculada do heap,
• Verificar a integridade do heap inspecionando cada bloco de memória em cada solicitação de alocação.

Quando _DEBUG não está definido, as chamadas para _CrtSetDbgFlag são removidas durante o pré-processamento.

A tabela a seguir lista os campos de bits para _crtDbgFlag e descreve seu comportamento. Como a definição dos bits resulta em maior saída de diagnóstico e redução da velocidade de execução do programa, esses bits não são definidos (ficam desativados) por padrão. Para obter mais informações sobre esses campos de bits, consulte Funções de relatório de estado de heap.

Campo de bits	Padrão	Descrição
_CRTDBG_ALLOC_MEM_DF	ATIVADO	ON: habilite alocações do heap de depuração e o uso de identificadores de tipo de bloco de memória, como _CLIENT_BLOCK. OFF: adicione novas alocações à lista vinculada do heap, mas defina o tipo de bloco como _IGNORE_BLOCK. Também pode ser combinado com qualquer uma das macros de verificação da frequência de heap.
_CRTDBG_CHECK_ALWAYS_DF	OFF	ON: chame _CrtCheckMemory em qualquer solicitação de alocação e desalocação. OFF: _CrtCheckMemory deve ser chamado explicitamente. As macros de verificação da frequência de heap não entram em vigor quando esse sinalizador está definido.
_CRTDBG_CHECK_CRT_DF	OFF	ON: inclua tipos _CRT_BLOCK na detecção de perda e em operações de diferença de estado da memória. OFF: a memória usada internamente pela biblioteca em tempo de execução é ignorada por essas operações. Também pode ser combinado com qualquer uma das macros de verificação da frequência de heap.
_CRTDBG_DELAY_FREE_MEM_DF	OFF	ON: mantenha os blocos de memória liberados na lista vinculada do heap, atribua-os ao tipo _FREE_BLOCK e preencha-os com o valor de byte 0xDD. OFF: não mantenha blocos liberados na lista vinculada do heap. Também pode ser combinado com qualquer uma das macros de verificação da frequência de heap.
_CRTDBG_LEAK_CHECK_DF	OFF	ON: realize a verificação automática de perda na saída do programa por meio de uma chamada a _CrtDumpMemoryLeaks e, caso o aplicativo não libere toda a memória alocada, gere um relatório de erros. OFF: não realize a verificação automática de perda na saída do programa. Também pode ser combinado com qualquer uma das macros de verificação da frequência de heap.

Macros de frequência da verificação de heap

É possível especificar com que frequência a biblioteca de runtime C realiza a validação do heap de depuração (_CrtCheckMemory) com base no número de chamadas para malloc, realloc, free e _msize.

Em seguida, _CrtSetDbgFlag inspeciona os 16 bits superiores do parâmetro newFlag em busca de um valor. O valor especificado é o número de chamadas malloc, realloc, free e _msize entre as chamadas _CrtCheckMemory. Quatro macros predefinidas são fornecidas com essa finalidade.

Macro	Número de chamadas malloc, realloc, free e _msize entre chamadas para _CrtCheckMemory
_CRTDBG_CHECK_EVERY_16_DF	16
_CRTDBG_CHECK_EVERY_128_DF	128
_CRTDBG_CHECK_EVERY_1024_DF	1024
_CRTDBG_CHECK_DEFAULT_DF	0 (por padrão, sem verificações de heap)

Por padrão, _CrtCheckMemory não é chamado durante operações de memória. Você pode alterar isso enviando os sinalizadores mostrados acima para _CrtSetDbgFlag().

Por exemplo, é possível especificar uma verificação de heap a cada 16 operações malloc, realloc, free e _msize com o código a seguir:

#include <crtdbg.h>
int main( )
{
    int tmp;

    // Get the current bits
    tmp = _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG);

    // Clear the upper 16 bits and OR in the desired frequency
    tmp = (tmp & 0x0000FFFF) | _CRTDBG_CHECK_EVERY_16_DF;

    // Set the new bits
    _CrtSetDbgFlag(tmp);
}

Os 16 bits superiores do parâmetro newFlag são ignorados quando _CRTDBG_CHECK_ALWAYS_DF é especificado. Nesse caso, _CrtCheckMemory é chamado sempre que malloc, realloc, free e _msize são chamados.

newFlag é o novo estado a ser aplicado a _crtDbgFlag e é uma combinação dos valores de cada um dos campos de bits.

Para alterar um ou mais desses campos de bit e criar um novo estado para o sinalizador

1. Chame _CrtSetDbgFlag com newFlag igual a _CRTDBG_REPORT_FLAG para obter o estado _crtDbgFlag atual e armazene o valor retornado em uma variável temporária.

2. Ative todos os bits por um "or" (|) bit a bit da variável temporária usando as bitmasks correspondentes (representadas no código do aplicativo por constantes de manifesto).

3. Desative os outros bits com um "and" (&) bit a bit da variável usando um "not" (~) bit a bit das bitmasks apropriadas.

4. Chame _CrtSetDbgFlag com newFlag igual ao valor armazenado na variável temporária para definir o novo estado de _crtDbgFlag.

O código a seguir demonstra como simular condições de pouca memória mantendo os blocos de memória liberados na lista vinculada do heap e evitando que _CrtCheckMemory seja chamado em todas as solicitações de alocação:

// Get the current state of the flag
// and store it in a temporary variable
int tmpFlag = _CrtSetDbgFlag( _CRTDBG_REPORT_FLAG );

// Turn On (OR) - Keep freed memory blocks in the
// heap's linked list and mark them as freed
tmpFlag |= _CRTDBG_DELAY_FREE_MEM_DF;

// Turn Off (AND) - prevent _CrtCheckMemory from
// being called at every allocation request
tmpFlag &= ~_CRTDBG_CHECK_ALWAYS_DF;

// Set the new state for the flag
_CrtSetDbgFlag( tmpFlag );

Para obter uma visão geral do gerenciamento de memória e do heap de depuração, consulte Detalhes do heap de depuração do CRT.

Para desabilitar um sinalizador com a função _CrtSetDbgFlag, você deve usar um "and" (&) bit a bit da variável com o "not" (~) bit a bit da bitmask.

Se newFlag não for um valor válido, essa função invocará o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essa função definirá errno como EINVAL e retornará o estado anterior de _crtDbgFlag.

Requisitos

Rotina	Cabeçalho necessário
_CrtSetDbgFlag	<crtdbg.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Bibliotecas

Somente versões de depuração de bibliotecas de tempo de execução C.

Exemplo

// crt_crtsetdflag.c
// compile with: /c -D_DEBUG /MTd -Od -Zi -W3 /link -verbose:lib /debug

// This program concentrates on allocating and freeing memory
// blocks to test the functionality of the _crtDbgFlag flag.

#include <string.h>
#include <malloc.h>
#include <crtdbg.h>

int main( )
{
    char *p1, *p2;
    int tmpDbgFlag;

    _CrtSetReportMode( _CRT_ERROR, _CRTDBG_MODE_FILE );
    _CrtSetReportFile( _CRT_ERROR, _CRTDBG_FILE_STDERR );

    // Set the debug-heap flag to keep freed blocks in the
    // heap's linked list - This will allow us to catch any
    // inadvertent use of freed memory
    tmpDbgFlag = _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG);
    tmpDbgFlag |= _CRTDBG_DELAY_FREE_MEM_DF;
    tmpDbgFlag |= _CRTDBG_LEAK_CHECK_DF;
    _CrtSetDbgFlag(tmpDbgFlag);

    // Allocate 2 memory blocks and store a string in each
    p1 = malloc( 34 );
    p2 = malloc( 38 );
    strcpy_s( p1, 34, "p1 points to a Normal allocation block" );
    strcpy_s( p2, 38, "p2 points to a Client allocation block" );

    // Free both memory blocks
    free( p2 );
    free( p1 );

    // Set the debug-heap flag to no longer keep freed blocks in the
    // heap's linked list and turn on Debug type allocations (CLIENT)
    tmpDbgFlag = _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG);
    tmpDbgFlag |= _CRTDBG_ALLOC_MEM_DF;
    tmpDbgFlag &= ~_CRTDBG_DELAY_FREE_MEM_DF;
    _CrtSetDbgFlag(tmpDbgFlag);

    // Explicitly call _malloc_dbg to obtain the filename and
    // line number of our allocation request and also so we can
    // allocate CLIENT type blocks specifically for tracking
    p1 = _malloc_dbg( 40, _NORMAL_BLOCK, __FILE__, __LINE__ );
    p2 = _malloc_dbg( 40, _CLIENT_BLOCK, __FILE__, __LINE__ );
    strcpy_s( p1, 40, "p1 points to a Normal allocation block" );
    strcpy_s( p2, 40, "p2 points to a Client allocation block" );

    // _free_dbg must be called to free the CLIENT block
    _free_dbg( p2, _CLIENT_BLOCK );
    free( p1 );

    // Allocate p1 again and then exit - this will leave unfreed
    // memory on the heap
    p1 = malloc( 10 );
}

Confira também

Rotinas de depuração
_crtDbgFlag
_CrtCheckMemory