test

Guia de rastreamento dinâmico Solaris

Capítulo 14 Utilitário dtrace(1M)

O comando dtrace(1M) é um front-end genérico para o recurso DTrace. O comando implementa uma única interface simples para chamar o compilador da linguagem D, a capacidade de recuperar dados de rastreio armazenados em buffer a partir do recurso de kernel do DTrace, e um conjunto de rotinas básicas para formatar e imprimir dados rastreados. Este capítulo fornece uma referência completa ao comando dtrace.

Descrição

O comando dtrace oferece uma interface genérica para todos os serviços essenciais fornecidos pelo recurso DTrace, incluindo:

O dtrace também pode ser usado para criar scripts de D ao ser usado em uma declaração #! para criar um arquivo de intérprete (consulte o Capítulo 15Script). Finalmente, você pode usar o dtrace para tentar compilar programas em D e determinar suas propriedades sem realmente ativar qualquer rastreamento com a opção -e, descrita abaixo.

Opções

O comando dtrace aceita as seguintes opções:

dtrace [-32 | -64] [-aACeFGHlqSvVwZ] [-b bufsz] [-c cmd] [-D nome [=def]] [-I caminho] [-L caminho] [-o saída] [-p pid] [-s script] [-U nome] [-x arg [=val]] [-Xa | f | s | t] [-P provedor [ [predicado]ação]] [-m [ [provedor:]módulo [ [predicado]ação]]] [-f [ [provedor:]módulo:]func [ [predicado]ação]] [-n [ [ [provedor:]módulo:]func:]nome [ [predicado]ação]] [-i id de teste [ [predicado]ação]]

onde predicado é qualquer predicado de D entre barras / / e ação é qualquer lista de declarações de D entre chaves { }, de acordo com a sintaxe da linguagem D descrita anteriormente. Se o código do programa em D for fornecido como um argumento para as opções -P, -m, -f, - n ou -i, este texto deve ser colocado entre aspas apropriadamente para evitar interpretação pelo shell. As opções são as seguintes:

-32, -64

O compilador de D produz programas usando o modelo de dados nativo do kernel do sistema operacional. Você pode usar o comando isainfo(1) -b para determinar o modelo de dados atual do sistema operacional. Se a opção - 32 for especificada, o dtrace forçará o compilador de D a compilar um programa em D usando o modelo de dados de 32 bits. Se a opção - 64 for especificada, o dtrace forçará o compilador de D a compilar um programa em D usando o modelo de dados de 64 bits. Estas opções geralmente não são necessárias, quando o dtrace seleciona o modelo de dados nativo como o padrão. O modelo de dados afeta o tamanho dos tipos de inteiro e de outras propriedades de outras linguagens. Os programas em D compilados para qualquer modelo de dados pode ser executado em kernels de 32 bits e de 64 bits. As opções -32 e -64 também determinam o formato de arquivo ELF (ELF32 ou ELF64) produzido pela opção -G.

-a

Declara o estado de rastreio anônimo e exibe os dados rastreados. Você pode combinar a opção -a com a opção -e para forçar o dtrace a sair imediatamente após consumir o estado de rastreio anônimo em vez de continuar a esperar por novos dados. Consulte o Capítulo 36Rastreio anônimo para obter mais informações sobre rastreio anônimo.

-A

Gera diretivas de driver.conf(4) para rastreio anônimo. Se a opção -A for especificada, o dtrace compila quaisquer programas em D especificados usando a opção -s ou na linha de comando, e constrói um conjunto de diretivas de arquivo de configuração de dtrace(7D) para ativar os testes especificados para rastreio anônimo (consulte o Capítulo 36Rastreio anônimo) e, a seguir, sai. Por padrão, o dtrace tenta armazenar as diretivas no arquivo /kernel/drv/dtrace.conf. Este comportamento pode ser modificado com a opção -o para especificar um arquivo de saída alternativo.

-b

Define o tamanho de buffer de rastreio principal. O tamanho de buffer de rastreio pode incluir quaisquer sufixos de tamanho k, m, g ou t, conforme descrito no Capítulo 36Rastreio anônimo. Se o espaço do buffer não puder ser alocado, o dtrace tentará reduzir o tamanho do buffer ou sairá, dependendo da configuração da propriedade bufresize.

-c

Executa o comando cmd especificado e sai após a sua conclusão. Se mais de uma opção -c estiver presente na linha compilada, o dtrace sairá quando todos os comandos tiverem saído, informando o status de saída de cada processo filho, quando ele termina. O ID do processo do primeiro comando é disponibilizado para quaisquer programas em D especificados na linha de comando ou com a opção -s através da variável de macro $target. Consulte o Capítulo 15Script para obter mais informações sobre variáveis de macro.

-C

Executa o pré-processador de C cpp(1) sobre programas em D antes de compilá-los. As opções podem ser passadas para o pré-processador de C usando as opções -D, - U, -I e -H. O grau de conformidade padrão de C pode ser selecionado com a opção -X. Consulte a descrição da opção -X para obter informações sobre o conjunto de símbolos definidos pelo compilador de D ao chamar o pré-processador de C.

-D

Define o nome especificado ao chamar cpp(1) (ativado com a opção -C). Se um sinal de igual ( =) e um valor adicional forem especificados, o valor correspondente será atribuído ao nome. Esta opção passa a opção - D para cada chamada de cpp.

-e

Sai depois de compilar quaisquer solicitações e consumir o estado de rastreio anônimo (opção -a) mas antes de ativar quaisquer testes. Esta opção pode ser combinada com a opção -a para imprimir dados de rastreio anônimo e sair, ou ela pode ser combinada com as opções do compilador de D para verificar se os programas compilam sem realmente serem executados e ativar a instrumentação correspondente.

-f

Especifica o nome da função para rastrear ou listar (opção -l). O argumento correspondente pode incluir quaisquer formatos de descrição de teste provedor:módulo:função, módulo:função ou função. Os campos de descrição de teste não especificados são deixados em branco e correspondem a quaisquer testes, independentemente dos valores desses campos. Se nenhum qualificador diferente da função for especificado na descrição, todos os testes com a função correspondente serão correspondidos. O argumento -f pode ser sufixado com uma cláusula de teste de D opcional. Mais de uma opção -f pode ser especificada na linha de comando de cada vez.

-F

Adere a saída do rastreio identificando a entrada e o retorno da função. Os relatórios do teste de entrada da função são recuados e sua saída é prefixada com ->. Os relatórios de teste de retorno da função têm o recuo cancelado e sua saída é prefixada com <- .

-G

Gera um arquivo ELF contendo um programa do DTrace incorporado. Os testes do DTrace especificados no programa são salvos dentro de um objeto ELF realocável que pode ser vinculado em outro programa. Se a opção -o estiver presente, o arquivo ELF será salvo com o nome de caminho especificado como o argumento deste operando. Se a opção -o não estiver presente e o programa do DTrace estiver em um arquivo cujo nome é nome do arquivo.s, então o arquivo ELF será salvo com o nome arquivo.o. Caso contrário, o arquivo ELF é salvo com o nome d.out.

-H

Imprime os nomes de caminho de arquivos incluídos ao chamar cpp(1) (ativado com a opção -C). Esta opção passa a opção -H para cada chamada de cpp, fazendo com que seja exibida a lista de nomes de caminho, um por linha, para stderr.

-i

Especifica o identificador de teste para rastrear ou listar (opção -l). Os IDs de teste são especificados com inteiros decimais, conforme mostrado por dtrace -l. O argumento -i pode ser sufixado com uma cláusula de teste de D opcional. Mais de uma opção -i pode ser especificada na linha de comando de cada vez.

-I

Adiciona o caminho do diretório especificado ao caminho de pesquisa dos arquivos #include ao chamar cpp(1) (ativado com a opção -C). Esta opção passa a opção - I para cada chamada de cpp. O diretório especificado é inserido no caminho de pesquisa antes da lista de diretórios padrão.

-l

Lista os testes em vez de ativá-los. Se a opção -l for especificada, o dtrace produzirá um relatório dos testes que correspondem às descrições fornecidas com as opções -P, -m, - f, -n, -i e -s. Se nenhuma destas opções forem especificadas, todos os testes serão listados.

-L

Adiciona o caminho do diretório especificado ao caminho de pesquisa das bibliotecas do DTrace. As bibliotecas do DTrace são usadas para armazenar definições comuns que podem ser usadas quando são escritos os programas em D. O caminho especificado é adicionado depois do caminho de pesquisa de biblioteca padrão.

-m

Especifica o nome do módulo a ser rastreado ou listado (opção -l). O argumento correspondente pode incluir quaisquer formatos de descrição de teste provedor:módulo ou módulo. Os campos de descrição de teste não especificados são deixados em branco e correspondem a quaisquer testes, independentemente dos valores desses campos. Se nenhum qualificador diferente do módulo for especificado na descrição, todos os testes com o módulo correspondente serão correspondidos. O argumento -m pode ser sufixado com uma cláusula de teste de D opcional. Mais de uma opção -m pode ser especificada na linha de comando de cada vez.

-n

Especifica o nome do teste para rastrear ou listar (opção -l). O argumento correspondente pode incluir qualquer um dos formatos de descrição de teste provedor:módulo:função:nome, módulo:função:nome , função:nome ou nome. Os campos de descrição de teste não especificados são deixados em branco e correspondem a quaisquer testes, independentemente dos valores desses campos. Se nenhum qualificador diferente do nome for especificado na descrição, todos os testes com um nome correspondente serão correspondidos. O argumento -n pode ser sufixado com uma cláusula de teste de D opcional. Mais de uma opção -n pode ser especificada na linha de comando de cada vez.

-o

Especifica o arquivo de saída das opções - A, -G e -l, ou dos dados rastreados. Se a opção -A estiver presente e -o não estiver presente, o arquivo de saída padrão será /kernel/drv/dtrace.conf. Se a opção -G estiver presente e o argumento da opção -s for do formato nome de arquivo .d e -o não estiver presente, o arquivo de saída padrão será nome de arquivo.o. Caso contrário, o arquivo de saída padrão será d.out.

-p

Obtém o ID de processo especificado pid, armazena em cache suas tabelas de símbolos e sai após a sua conclusão. Se mais de uma opção -p estiver presente na linha de comando, o dtrace sairá quando todos os comandos tiverem saído, informando o status de saída de cada processo quando ele termina. O primeiro ID do processo é disponibilizado para quaisquer programas em D especificados na linha de comando ou com a opção -s através da variável de macro $target. Consulte o Capítulo 15Script para obter mais informações sobre variáveis de macro.

-P

Especifica o nome do provedor para rastrear ou listar (opção -l). O nome, a função e o módulo dos campos de descrição de teste restantes são deixados em branco e correspondem a quaisquer testes, independentemente dos valores desses campos. O argumento - P pode ser sufixado com uma cláusula de teste de D opcional. Mais de uma opção -P pode ser especificada na linha de comando de cada vez.

-q

Define o modo silencioso. O dtrace eliminará mensagens tais como o número de testes correspondidos pelas opções especificadas e os programas em D não imprimirão os cabeçalhos de coluna, o ID da CPU, o ID do teste, ou inserirão linhas novas na saída. Somente dados rastreados e formatados por declarações de programas em D, tais como trace() e printf(), serão exibidos para stdout.

-s

Compila o arquivo-fonte do programa em D especificado. Se a opção -e não estiver presente, o programa será compilado, mas nenhuma instrumentação será ativada. Se a opção -l estiver presente, o programa será compilado e o conjunto de testes correspondidos por ele será lista, mas nenhuma instrumentação será ativada. Se nem -e ou -l estiver presente, a instrumentação especificada pelo programa em D será ativada e o rastreio começa.

-S

Mostra o código intermediário do compilador de D. O compilador de D produzirá um relatório do código intermediário gerado para cada programa em D para stderr.

-U

Indefine o nome especificado ao chamar cpp(1) (ativado com a opção -C). Esta opção passa a opção -U para cada chamada de cpp.

-v

Define o modo verboso. Se a opção -v for especificada, o dtrace produzirá um relatório de estabilidade do programa mostrando a estabilidade mínima da interface e o nível de dependência dos programas em D especificados. Os níveis de estabilidade do DTrace são explicados em maiores detalhes no Capítulo 39Estabilidade.

-V

Informa a versão da interface de programação em D mais alta aceita pelo dtrace. As informações de versão são impressas no stdout e o comando dtrace sai. Consulte o Capítulo 41Versionamento para obter mais informações sobre os recursos de versão do DTrace.

-w

Permite ações destrutivas nos programas em D especificadas com as opções -s, -P, -m, -f, -n ou -i. Se a opção -w não for especificada, o dtrace não permitirá a compilação ou ativação de um programa em D que contenha ações destrutivas. As ações destrutivas são descritas em maiores detalhes no Capítulo 10Ações e sub-rotinas.

-x

Ativa ou modifica uma opção de tempo de execução do DTrace ou a opção do compilador de D. As opções estão listadas no Capítulo 16Opções e ajustáveis. As opções booleanas são ativadas através da especificação de seus nomes. As opções com valores são definidas, separando o nome e o valor da opção com um sinal de igual (=).

-X

Especifica o grau de conformidade com o padrão ISO C que deve ser selecionado ao chamar cpp(1) (ativado com a opção -C). O argumento da opção -X afeta o valor e a presença da macro __STDC__, dependendo do valor da letra do argumento:

a (padrão)

As extensões de compatibilidade ISO C mais K&R, com alterações semânticas requeridas pela ISO C. Este modo será o padrão, se -X não for especificada. A macro predefinida __STDC__ possui um valor 0 quando cpp é chamado junto com a opção -Xa.

c (conformidade)

Conforme estritamente com ISO C, sem extensões de compatibilidade K&R C. A macro predefinida __STDC__ possui um valor 1 quando cpp é chamado junto com a opção -Xa.

s (K&R C)

K&R C somente. A macro __STDC__ não é definida quando cpp é chamado junto com a opção -Xs.

t (transição)

ISO C mais extensões de compatibilidade K&R C, sem alterações semânticas requeridas pela ISO C. A macro predefinida __STDC__ possui um valor 0 quando cpp é chamada em conjunto com a opção - Xt.

Como a opção -X afeta somente como o compilador de D chama o pré-processador de C, as opções -Xa e - Xt são equivalentes da perspectiva de D. Ambas as opções são fornecidas para fácil reutilização das configurações de um ambiente de construção de C.

Independentemente do modo -X, as definições do pré-processador de C adicionais são sempre especificadas e válidas em todos os modos:

  • __sun

  • __unix

  • __SVR4

  • __sparc (somente em sistemas SPARC®)

  • __sparcv9 (somente em sistemas SPARC® quando programas de 64–bits são compilados)

  • __i386 (somente em sistemas x86 quando programas de 32 bits são compilados)

  • __amd64 (somente em sistemas x86 quando programas de 64–bits são compilados)

  • __'uname -s' _'uname -r', substituindo o ponto decimal na saída de uname por um sublinhado (_), como em __SunOS_5_10

  • __SUNW_D=1

  • __SUNW_D_VERSION=0xMMmmmuuu (onde MM é o valor de versão Principal em hexadecimal, mmm é o valor de versão Secundário em hexadecimal, e uuu é o valor de versão Micro em hexadecimal. Consulte o Capítulo 41Versionamento para obter mais informações sobre a versão do DTrace)

-Z

Permite as descrições de teste que correspondem a zero teste. Se a opção - Z não for especificada, o dtrace informará um erro e sairá, se nenhuma descrição de teste especificada em arquivos de programa em D (opção - s) ou na linha de comando (opções -P, -m, - f, -n ou -i) contiver descrições que não correspondam a quaisquer testes conhecidos.

Operandos

Zero ou mais argumentos adicionais podem ser especificados na linha de comando do dtrace para definir um conjunto de variáveis de macro ($1, $2, e assim por diante) a serem usadas em quaisquer programas em D especificados com a opção -s ou na linha de comando. O uso de variáveis de macro é descrito em mais detalhes no Capítulo 15Script.

Status de saída

Os valores de saída seguintes são retornados pelo utilitário dtrace:

0

As solicitações especificadas foram concluídas com êxito. Para solicitações de programas em D, o status de saída 0 indica que os programas foram compilados com êxito, os testes foram ativados com êxito ou o estado anônimo foi recuperado com êxito. dtrace retorna 0 mesmo se as solicitações de rastreio especificadas encontraram erros ou solturas.

1

Ocorreu um erro fatal. Para solicitações de programa em D, o status de saída 1 indica que a compilação do programa falhou ou que a solicitação especificada não foi satisfeita.

2

Opções de linha de comando inválidas ou argumentos não especificados.