Capítulo 9. API de pDI-Tools

Tabla de contenidos
9.1. beconfig.h - Gestión de ficheros de comandos
9.2. ebeif.h - Interfaz del "Elf Backend"
9.3. log.h - Sistema de "log"
9.4. pdiconfig.h - Gestión de la configuración
9.5. threadid.h - Gestión del "thread id resolver"

Finalmente se describe el API de pDI-Tools. Esta API permitirá al programador de "backends" realizar desde su código muchas operaciones de pDI-Tools como cargar "backends", instalar interposiciones, gestionar ficheros de comandos, etc.

En este capítulo se subdivide el API en diferentes partes según el fichero de cabecera donde está definida cada función.

9.1. beconfig.h - Gestión de ficheros de comandos

Este módulo ofrece un conjunto de herramientas para leer y manipular ficheros de configuración para los "backends", y también para aplicar dicha configuración en el proceso actual. En dichos ficheros se especifican los objetos y funciones sobre los que realizaremos interposiciones de código, y evidentemente, los "backends" y sus funciones de interposición.

Esta API se ofrece para que los "backend", si lo desean, puedan cargar y procesar ficheros de comandos y así instalar configuraciones complejas de interposiciones de un modo casi automático.

BECFG_OBJ_INFO *_pdi_becfg_addCommand(BECFG_CONFIG *cfg, int type, BECFG_OBJ_INFO *trgObj, char *trgFunc, BECFG_OBJ_INFO *backend, char *wrapper);

Descripción. Añade un nuevo comando de interposición a la configuración cfg.

Parámetros.

  • cfg. Configuración que manipulamos.

  • type. Tipo de comando. Puede tomar los valores BECFG_IT_RELINK, BECFG_IT_REDEFINITION o BECFG_IT_CALLBACK.

  • trgObj. Objeto que afectara esta definición (NULL si se usa un comodín).

  • trgFunc. Función a la que afectará (o NULL si comodín).

  • backend. El "backend" encargado de gestionar esta interposición.

  • wrapper. El nombre de la función "wrapper" (o nuevo "generic wrapper" en caso de ser un "callback") que gestionará la interposición. NULL si no se indica ninguna.

Valor devuelto. 0 en caso de éxito, -1 en caso de error.

BECFG_OBJ_INFO *_pdi_becfg_addObject(BECFG_CONFIG *cfg, char *o_path, char *o_alias, int is_backend);

Descripción. Añade un nuevo objeto a la lista de objetos en la configuración.

Parámetros.

  • cfg. Configuración que manipulamos.

  • o_path. Ruta al binario.

  • o_alias. Alias que le asignamos.

  • is_backend. Distinto de cero si declaramos un "backend".

Valor devuelto. Un puntero a la información del nuevo objeto en caso de éxito, NULL en caso de error.

int _pdi_becfg_applyBackendConfig(BECFG_OBJ_INFO *cfg);

Descripción. Ejecuta la lista de comandos de interposición contenida en la configuración cfg.

Parámetros.

  • cfg. Configuración a aplicar.

Valor devuelto. 0 en caso de éxito, o -1 en caso de error.

void _pdi_becfg_destroyConfig(BECFG_CONFIG *cfg);

Descripción. La función _pdi_becfg_destroyConfig() destruye la estructura BECFG_CONFIG devuelta por _pdi_becfg_newConfig() y libera memoria.

Parámetros.

  • cfg. Puntero a la configuración a destruir.

Valor devuelto. La función no devuelve nada.

void _pdi_becfg_finalizeRead(BECFG_CONFIG *cfg);

Descripción. _pdi_becfg_finalizeRead() termina la lectura del fichero de comandos activa en la estructura cfg.

Parámetros.

  • cfg. Puntero a la configuración sobre la que trabajaremos.

Valor devuelto. La función _pdi_becfg_finalizeRead() no devuelve nada.

int _pdi_becfg_initializeRead(BECFG_CONFIG *cfg, FILE *f);

Descripción. Prepara la estructura de configuración cfg para empezar a leer un fichero de comandos a través del descriptor fichero f.

Parámetros.

  • cfg. Puntero a la configuración sobre la que trabajaremos.

  • f. Puntero a un descriptor de fichero desde donde leeremos el fichero de comandos.

Valor devuelto. La función _pdi_becfg_initializeRead() devuelve 0 en caso de éxito, o -1 en caso de error.

BECFG_OBJ_INFO *_pdi_becfg_getObjectByPath(BECFG_CONFIG *cfg, char *path);

BECFG_OBJ_INFO *_pdi_becfg_getObjectByAlias(BECFG_CONFIG *cfg, char *alias);

BECFG_OBJ_INFO *_pdi_becfg_getObject(BECFG_CONFIG *cfg, char *x);

Descripción. La primera, _pdi_becfg_getObjectByPath(), busca la información sobre un objeto en una configuración por la ruta a su binario. _pdi_becfg_getObjectByAlias() busca el objeto por su alias y la última, _pdi_becfg_getObject() busca primero por el alias y en caso de no encontrarse vuelve a buscar por la ruta al binario.

Parámetros.

  • cfg. Puntero a la configuración donde haremos la búsqueda.

  • alias. Cadena con el alias a buscar.

  • path. Cadena con el binario a buscar.

  • x. Cadena con la ruta al binario o el alias a buscar.

Valor devuelto. Estas funciones devuelven NULL si no se encontró el objeto, en caso de éxito se devuelve un puntero a una estructura BECFG_OBJ_INFO.

char *_pdi_becfg_getObjectName(BECFG_OBJ_INFO *object);

Descripción. Esta función devuelve el nombre del objeto (la ruta al binario, o el alias en su defecto).

Parámetros.

  • object. Puntero con información sobre el objeto.

Valor devuelto. Una cadena con el nombre del objeto, o NULL en caso de error.

BECFG_OBJ_INFO *_pdi_becfg_loadBackendConfigFromFile(FILE *f, char *wrapper);

BECFG_OBJ_INFO *_pdi_becfg_loadBackendConfig(char *fname);

Descripción. Estas funciones permiten cargar desde fichero(s) la configuración de los "backend" en memoria. No comprueban que los símbolos, objetos, "backends", etc. existan, tan solo los declara.

Parámetros.

  • fname. Nombre del fichero a abrir y a procesar.

  • f. Fichero desde el cual se lee el fichero de comandos.

Valor devuelto. NULL en caso de error, un puntero a una configuración en caso de éxito.

int _pdi_becfg_mergeBackendConfigFiles(BECFG_OBJ_INFO *ctrg, BECFG_OBJ_INFO *csrc);

Descripción. Combina las configuraciones csrc y ctrg y deja el resultado en la configuración ctrg.

Parámetros.

  • csrc. Configuración origen.

  • ctrg. Configuración destino.

Valor devuelto. 0 en caso de éxito, o -1 en caso de error.

Aviso

Si la ejecución falla (devuelve un valor distinto de cero), se desaconseja usar la configuración ctrg ya que esta puede quedar en un estado corrupto.

BECFG_CONFIG *_pdi_becfg_newConfig(char *name);

Descripción. La primera función, _pdi_becfg_newConfig(), reserva memoria para una nueva lista de comandos de interposición.

Parámetros.

  • name. Nombre del fichero de comandos (generalmente suele ponerse el nombre del fichero desde donde la hemos leído).

Valor devuelto. Devuelve un puntero a una configuración o NULL en caso de error.

int _pdi_becfg_setObjectAlias(BECFG_OBJ_INFO *object, char *new_alias);

Descripción. Esta función devuelve el nombre del objeto (la ruta al binario, o el alias en su defecto).

Parámetros.

  • object. Puntero con información sobre el objeto.

  • new_alias. Nuevo alias a asignar. NULL si se desea quitarle el alias actual.

Valor devuelto. 0 en caso de éxito, -1 en caso de error

int _pdi_becfg_showObjects(int nivel, BECFG_OBJ_INFO *cfg);

Descripción. Imprime por el canal de "log" la lista de objetos que contiene la configuración cfg. El parámetro nivel puede tomar uno de los valores LOG_LEVEL_* definidos en log.h e indica a partir de que nivel de verbosidad debe mostrarse la lista.

Parámetros.

  • nivel. Nivel de verbosidad con el que mostramos la lista.

  • ctrg. Configuración que queremos examinar.

Valor devuelto. Nada.