test

Guía de seguimiento dinámico de Solaris

Capítulo 14 Utilidad dtrace(1M)

El comando dtrace(1M) es un componente frontal genérico de la utilidad DTrace. El comando implementa una interfaz simple para llamar al compilador del lenguaje D, permite recuperar los datos de seguimiento almacenados en la memoria intermedia de la utilidad del núcleo de DTrace e incluye un conjunto de rutinas básicas para dar formato a los datos de seguimiento e imprimirlos. En este capítulo se proporciona una completa referencia del comando dtrace.

Descripción

El comando dtrace ofrece una interfaz genérica a todos los servicios fundamentales proporcionados por la utilidad DTrace, incluidos los siguientes:

dtrace también puede utilizarse para crear secuencias de comandos del lenguaje D mediante su uso en una declaración #! con el fin de crear un archivo de intérprete (consulte el Capítulo 15Secuencias de comandos). Por último, puede utilizar dtrace para intentar compilar programas D y determinar sus propiedades, sin habilitar realmente ningún seguimiento mediante la opción -e, como se describe a continuación.

Opciones

El comando dtrace acepta las siguientes opciones:

dtrace [-32 | -64] [-aACeFGHlqSvVwZ] [-b bufsz] [-c cmd] [-D name [=def]] [-I path] [-L path] [-o output] [-p pid] [-s script] [-U name] [-x arg [=val]] [-Xa | c | s | t] [-P provider [ [predicado]acción]] [-m [ [provider:]module [ [predicado]acción]]] [-f [ [provider:]module: ]func [ [predicado]acción]] [-n [ [ [provider:]module:]func:]name [ [predicado]acción]] [-i probe-id [ [predicado]acción]]

donde predicate es cualquier predicado del lenguaje D incluido entre barras diagonales / / y action es cualquier instrucción del lenguaje D incluido entre llaves { }, según la sintaxis del lenguaje D descrita anteriormente. Si el código del programa D se proporciona como argumento para las opciones -P, -m, -f, - n o -i, este texto debe ir convenientemente entrecomillado para evitar que la shell lo interprete. Las opciones son las siguientes:

-32, -64

El compilador del lenguaje D genera programas utilizado el modelo de datos nativo del núcleo del sistema operativo. Puede utilizar el comando isainfo(1) -b para determinar el modelo de datos del sistema operativo actual. Si se especifica la opción -32, dtrace forzará al compilador del lenguaje D a que compile un programa D con el modelo de datos de 32 bits. Si se especifica la opción -64, dtrace forzará al compilador del lenguaje D a que compile un programa D con el modelo de datos de 64 bits. Normalmente, estas opciones no son necesarias, ya que dtrace selecciona el modelo de datos nativo como modelo predeterminado. El modelo de datos afecta a los tamaños de los tipos de enteros y a otras propiedades de lenguaje. Los programas D compilados para cualquier modelo de datos pueden ejecutarse en núcleos de 32 y 64 bits. Las opciones -32 y -64 también determinan el formato de archivo ELF (ELF32 o ELF64) generado por la opción -G.

-a

Permite reclamar el estado de seguimiento anónimo y visualizar los datos de los que se realiza seguimiento. Puede combinar la opción -a con la opción -e para forzar que dtrace salga inmediatamente después de consumir el estado de seguimiento anónimo, en lugar de seguir esperando los nuevos datos. Consulte el Capítulo 36Seguimiento anónimo para obtener más información sobre el seguimiento anónimo.

-A

Permite generar directivas driver.conf(4) para el seguimiento anónimo. Si se especifica la opción -A, dtrace compila todos los programas D especificados mediante la opción -s o en la línea de comandos y crea un conjunto de directivas de archivo de configuración de dtrace(7D) para habilitar el seguimiento anónimo en los sondeos especificados (consulte el Capítulo 36Seguimiento anónimo) y, a continuación, sale. De forma predeterminada, dtrace intenta almacenar las directivas en el archivo /kernel/drv/dtrace.conf. Este comportamiento puede modificarse mediante la opción -o para especificar un archivo de salida alternativo.

-b

Permite establecer el tamaño de la memoria intermedia de seguimiento principal. El tamaño de la memoria intermedia de seguimiento puede incluir los sufijos de tamaño k, m, g o t, como se describe en el Capítulo 36Seguimiento anónimo. Si no puede asignarse el espacio de la memoria intermedia, dtrace intenta reducir el tamaño de la memoria intermedia o salir, en función de la configuración de la propiedad bufresize.

-c

Permite ejecutar el comando cmd especificado y salir una vez completado. Si hay varias opciones -c en la línea de comandos, dtrace sale cuando se han cerrado todos los comandos, informando del estado de salida de cada proceso secundario a medida que finalizan. El Id. de proceso del primer comando se facilita a cualquier programa D especificado en la línea de comandos o mediante la opción -s a través de la variable de macro $target. Consulte el Capítulo 15Secuencias de comandos para obtener más información sobre las variables de macro.

-C

Permite ejecutar el preprocesador cpp(1) del lenguaje C en programas D antes de compilarlos. Las opciones pueden transferirse al preprocesador de C mediante las opciones -D, - U, -I y -H. El grado de conformidad con el estándar C puede seleccionarse mediante la opción -X. Consulte la descripción de la opción -X para obtener una descripción de los conjuntos de símbolos definidos por el compilador del lenguaje D al llamar al preprocesador del lenguaje C.

-D

Permite definir el nombre, nombre, especificado al llamar a cpp(1) (habilitado mediante la opción -C). Si se especifica un signo igual ( =) y un elemento value adicional, al nombre se le asigna el valor correspondiente. Esta opción transfiere la opción - D a cada llamada a cpp.

-e

Permite salir después de compilar las solicitudes y consumir el estado de seguimiento anónimo (opción -a), pero antes de habilitar los sondeos. Esta opción puede combinarse con la opción -a para imprimir los datos de seguimiento anónimo y salir, o con las opciones del compilador del lenguaje D para comprobar que los programas realicen la compilación sin ejecutarlos realmente ni habilitar la instrumentación correspondiente.

-f

Permite especificar el nombre de la función a la que realizar el seguimiento o listar (opción -l). El argumento correspondiente puede incluir cualquiera de los formatos de descripción de sondeo, provider:module:function, module:function, o function . Los campos de descripción de sondeo no especificados se dejan en blanco y se hacen coincidir con cualquiera de los sondeos, independientemente de los valores de esos campos. Si no se especifica ningún calificador diferente a función en la descripción, se harán coincidir todos los sondeos con el elemento función correspondiente. El argumento -f puede incluir como sufijo una cláusula de sondeo de D opcional. Pueden especificarse simultáneamente varias opciones -f en la línea de comandos.

-F

Permite combinar la salida del seguimiento mediante la identificación de la entrada y la devolución de la función. Los informes de sondeos de entrada de la función se justifican con una sangría y su salida suele ir precedida de ->. Los informes de sondeos de devolución de la función no se justifican con una sangría, y su salida suele ir precedida de <.

-G

Permite generar un archivo ELF que contiene un programa de DTrace incrustado. Los sondeos de DTrace especificados en el programa se guardan dentro de un objeto ELF reubicable que puede vincularse a otro programa. Si está presente la opción -o, se guarda el archivo ELF utilizando el nombre de ruta especificado como argumento de este operando. Si, por el contrario, no está presente la opción -o y el programa de DTrace se encuentra incluido en un archivo cuyo nombre es nombre_archivo.s, el archivo ELF se guarda con el nombre file .o; de lo contrario, el archivo ELF se guarda con el nombre d.out.

-H

Permite imprimir los nombres de ruta de los archivos incluidos al llamar a cpp(1) (habilitado mediante la opción -C). Esta opción transfiere la opción -H a cada llamada a cpp, lo que provoca que se muestre la lista de parámetros, uno por línea, en stderr.

-i

Permite especificar el identificador de sondeo al que realizar el seguimiento o listar (opción -l ). Los Id. de sondeo se especifican mediante números enteros decimales, como muestra dtrace -l. El argumento -i puede incluir como sufijo una cláusula de sondeo de D opcional. Pueden especificarse simultáneamente varias opciones -i en la línea de comandos.

-I

Permite agregar la ruta del directorio especificado (ruta) a la ruta de búsqueda de los archivos #include al llamar a cpp(1) (habilitado mediante la opción -C). Esta opción transfiere la opción -I a cada llamada a cpp. El directorio especificado se inserta en la ruta de búsqueda al frente de la lista de directorios predeterminados.

-l

Permite enumerar los sondeos en lugar de habilitarlos. Si se especifica la opción -l, dtrace genera un informe con los sondeos que coinciden con las descripciones especificadas mediante las opciones -P, -m, - f, -n, -i y -s. Si no se especifica ninguna de estas opciones, se enumeran todos los sondeos.

-L

Permite agregar la ruta, path, de directorio especificada a la ruta de búsqueda de las bibliotecas de DTrace. Estas bibliotecas se utilizan para contener las definiciones habituales que pueden usarse al escribir programas D. La ruta, path, especificada se agrega detrás de la ruta de búsqueda de la biblioteca predeterminada.

-m

Permite especificar el nombre del módulo al que realizar el seguimiento o listar (opción -l). El argumento correspondiente puede incluir cualquiera de los formatos de descripción de sondeo, provider:module o module. Los campos de descripción de sondeo no especificados se dejan en blanco y se hacen coincidir con cualquiera de los sondeos, independientemente de los valores de esos campos. Si no se especifica ningún calificador diferente a módulo en la descripción, se harán coincidir todos los sondeos con el elemento módulo correspondiente. El argumento -m puede incluir como sufijo una cláusula de sondeo de D opcional. Pueden especificarse varias opciones -m simultáneamente en la línea de comandos.

-n

Permite especificar el nombre del sondeo en el seguimiento o la lista (opción -l). El argumento correspondiente puede incluir cualquiera de los formatos de descripción de sondeo, provider:module:function:name, module:function:name, function:name o name. Los campos de descripción de sondeo no especificados se dejan en blanco y se hacen coincidir con cualquiera de los sondeos, independientemente de los valores de esos campos. Si no se especifica ningún calificador diferente a nombre en la descripción, se harán coincidir todos los sondeos con el elemento nombre correspondiente. El argumento -n puede incluir como sufijo una cláusula de sondeo de D opcional. Pueden especificarse simultáneamente varias opciones -n en la línea de comandos.

-o

Permite especificar el archivo de salida, output, para las opciones - A , -G e -l o para los datos de los que se realiza un seguimiento. Si está presente la opción -A, pero no está presente la opción -o, el archivo de salida predeterminado es /kernel/drv/dtrace.conf. Si está presente la opción -G y el argumento de la opción -s presenta el formato nombre_archivo.d, pero no está presente la opción -o, el archivo de salida predeterminado es nombre_archivo .o; de lo contrario, el archivo de salida predeterminado es d.out.

-p

Permite obtener el Id. de proceso, pid especificado, almacena en caché sus tablas de símbolos y sale una vez completado. Si hay varias opciones -p en la línea de comandos, dtrace sale cuando se han cerrado todos los comandos, informando del estado de salida de cada proceso secundario a medida que finalizan. El primer Id. de proceso se facilita a cualquier programa D especificado en la línea de comandos o mediante la opción -s a través de la variable de macro $target. Consulte el Capítulo 15Secuencias de comandos para obtener más información sobre las variables de macro.

-P

Permite especificar el nombre del proveedor al que realizar el seguimiento o listar (opción -l). Los campos de descripción de sondeo restantes módulo, función y nombre, se dejan en blanco y se hacen coincidir con cualquier sondeo, independientemente del valor de esos campos. El argumento -P puede incluir como sufijo una cláusula de sondeo de D opcional. Pueden especificarse simultáneamente varias opciones -P en la línea de comandos.

-q

Permite establecer el modo silencioso. dtrace suprimirá los mensajes como, por ejemplo, el número de sondeos que se han hecho coincidir mediante las opciones y los programas D, y no imprimirá los encabezados de columna ni el Id. de CPU ni el Id. de sondeo, o insertará nuevas líneas en la salida. Sólo los datos de los que el programa D ha realizado un seguimiento y a los que les ha aplicado un formato como, por ejemplo, trace() y printf() se mostrarán en stdout.

-s

Permite compilar el archivo de origen del programa D especificado. Si está presente la opción -e, se compila el programa, pero no se habilita la instrumentación. Si está presente la opción -l, se compila el programa y se hace coincidir el conjunto de sondeos enumerados, pero no se realizará ninguna instrumentación. Si no está presente la opción -e ni la opción -l, se habilita la instrumentación especificada por el programa D y se inicia el seguimiento.

-S

Permite mostrar el código intermedio del compilador del lenguaje D. El compilador del lenguaje D elaborará un informe del código intermedio generado para cada programa D en stderr.

-U

Permite anular la definición del nombre, nombre, especificado al llamar a cpp(1) (habilitado mediante la opción -C). Esta opción transfiere la opción -U a cada llamada a cpp.

-v

Permite establecer el modo detallado. Si se especifica la opción -v, dtrace genera un informe de estabilidad de programas que muestra la estabilidad mínima de la interfaz y el nivel de dependencia de los programas D especificados. Los niveles de estabilidad de DTrace se describen de forma más detallada en el Capítulo 39Estabilidad.

-V

Informa de la versión superior de la interfaz de programación del lenguaje D admitida por dtrace. La información de la versión se imprime en stdout y, a continuación, se cierra el comando dtrace. Consulte el Capítulo 41Versiones para obtener más información sobre las funciones de las versiones de DTrace.

-w

Permite especificar acciones destructivas en los programas D mediante las opciones - s, -P, -m, -f, - n o -i. Si no se especifica la opción -w, dtrace no permitirá la compilación ni la habilitación de un programa D que contenga acciones destructivas. Las acciones destructivas se describen de forma más detallada en el Capítulo 10Acciones y subrutinas.

-x

Permite habilitar o modificar una opción del compilador del lenguaje D o una acción de tiempo de ejecución de DTrace. Las opciones se muestran en el Capítulo 16Opciones y optimizables. Para habilitar las opciones booleanas, debe especificar su nombre. Las opciones con valores se establecen insertando un signo igual (=) entre el nombre de la opción y el valor.

-X

Especifica el grado de conformidad con el estándar de C ISO que debería seleccionar al llamar a cpp(1) (habilitado mediante la opción -C). El argumento de la opción -X afecta al valor y la presencia de la macro __STDC__ en función del valor de la letra del argumento:

a (predeterminado)

Estándar de C ISO más las extensiones de compatibilidad K&R con los cambios semánticos necesarios para C ISO. Este modo es el predeterminado si no se ha especificado -X. La macro predefinida __STDC__ tiene el valor 0 cuando se llama a cpp junto con la opción -Xa.

c (conformidad)

Conformidad rigurosa con el estándar de C ISO, sin las extensiones de compatibilidad de C K&R. La macro predefinida __STDC__ tiene el valor 1 cuando se llama a cpp junto con la opción -Xc.

s (K&R C)

Sólo las extensiones de K&R C. La macro __STDC__ no se define cuando se llama a cpp junto con la opción -Xs.

t (transición)

Estándar de C ISO más las extensiones de compatibilidad de C K&R, sin los cambios semánticos necesarios para C ISO. La macro predefinida__STDC__ tiene el valor cerocuando se llama a cpp junto con la opción -Xt.

Como la opción -X sólo afecta a cómo el compilador del lenguaje D llama al preprocesador de C, las opciones -Xa y - Xt son equivalentes desde la perspectiva del lenguaje D. Ambas opciones se proporcionan para facilitar la reutilización de la configuración de un entorno de creación de C.

Independientemente del modo de -X, siempre se especifican las siguientes definiciones del preprocesador de C adicionales y son válidas en todos los modos:

  • __sun

  • __unix

  • __SVR4

  • __sparc (sólo en sistemas SPARC®)

  • __sparcv9 (sólo en sistemas SPARC® al compilar programas de 64 bits)

  • __i386 (sólo en sistemas x86 al compilar programas de 32 bits)

  • __amd64 (sólo en sistemas x86 al compilar programas de 64 bits)

  • __'uname -s' _'uname -r', que sustituye al coma flotante en la salida de uname con el guión de subrayado (_), al igual que en __SunOS_5_10

  • __SUNW_D=1

  • __SUNW_D_VERSION=0xMMmmmuuu (donde MM es el valor de versión superior expresado en valores hexadecimales, mmm es el valor de versión inferior expresado en valores hexadecimales y uuu es el valor de microversión expresado en valores hexadecimales. Consulte el Capítulo 41Versiones para obtener más información acerca de las versiones de DTrace)

-Z

Permite utilizar las descripciones de sondeos que no coinciden con ningún sondeo. Si no se especifica la opción - Z, dtrace informará de un error y saldrá cuando alguna de las descripciones de sondeos especificadas en los programas D (opción - s) o en la línea de comandos (opciones -P, -m, - f, -n o -i) contenga descripciones que no coincidan con ninguno de los sondeos conocidos.

Operandos

Pueden especificarse cero o más argumentos en la línea de comandos de dtrace para definir un conjunto de variables de macro ($1, $2, etc.) que se utilizarán en cualquier programa D especificado mediante la opción -s o en la línea de comandos. El uso de las variables de macro se describe detalladamente en el Capítulo 15Secuencias de comandos.

Estado de salida

La utilidad dtrace devuelve los siguientes valores de salida:

0

Las solicitudes especificadas se han completado satisfactoriamente. Para las solicitudes de programas D, el estado de salida 0 indica que se han compilado los programas, se han habilitado los sondeos o se ha recuperado el estado anónimo satisfactoriamente. dtrace devuelve el valor 0, aunque las solicitudes de seguimiento especificadas hayan detectado errores o anulaciones.

1

Se ha producido un error grave. Para las solicitudes de programas D, el estado de salida 1 indica que ha fallado la compilación del programa o que no se ha podido satisfacer la solicitud especificada.

2

Se han especificado argumentos u opciones de la línea de comandos no válidos.