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

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.

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

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