Images

Déclarations dans : be/kernel/image.h

Librairie : libroot.so

Non, il ne s'agit pas de graphismes. Une image est du code compilé, lequel peut-être l'un de ces trois types : des images applicatives, des images de libraries de code et des images de composants (add-on). Une image applicative est du code exécutable qui peut être lancé. Une image de librarie est une collection de code partagé avec laquelle vous liez (link) votre application lorsque vous la compiler. Une image de composant est du code qu'une application peut charger et exécuter pendant le fonctionnement même de celle-ci. Notez qu'un add-on peut aussi être une application; autrement dit, vous pouvez créer une image qui peut être lancée toute seule, ou qui peut être chargée dans une autre application.

Pour plus d'information sur la crétion et l'utilisation des images, consultez "Concepts d'image".

Fonctions

get_image_info() , get_next_image_info() , image_info

	status_t get_image_info(image_id image, image_info *info) status_t get_next_image_info(team_id team,       int32 *cookie,       image_info *info) struct {} image_info

Ces fonctions copient, dans l'argument info, la structure image_info pour une image particulière. La fonction get_image_info() obtient les informations de l'image directement identifiée par image.

La version get_next_image_info(), elle, vous permet de parcourir la liste de toutes les images d'une team, par appel successifs. L'argument team identifie la team que vous voulez observer; une valeur 0 de team signifie la team du thread appelant. L'argument cookie est un marqueur, positionnez-le à 0 lors du premier appel, la fonction s'occupe du reste. Celle-ci retourne B_BAD_VALUE lorsqu'il n'y a plus d'images à visiter :

   /* Obtenir l'image_info pour chaque image de cette team. */
   image_info info;
   int32 cookie = 0;
   
   while (get_next_image_info(0, &cookie, &info) == B_OK)
      ...

La structure image_info est 

	typedef struct {          image_id id;           image_type type;          int32 sequence;          int32 init_order;          B_PFV init_routine;          B_PFV term_routine;          dev_t device;          ino_t node;           char name[MAXPATHLEN];           void *text;           void *data;          int32 text_size;           int32 data_size;       } image_info

Les champs sont :

• id. L'image_id de l'image.

• type. Une constante (liste ci-dessous) indiquant si c'est une image applicative, de librairie de code ou d'un add-on.

• sequence et init_order. Ces nombres indiquent l'ordre (0 = premier) respectivement de chargement et d'initialisation de cette image, comparée à toutes les autres images dans cette team.

• init_routine et term_routine. Ce sont des pointeurs sur les fonctions utilisées pour initialiser et terminer l'image (plus précisément, le thread principal de l'image). Le type B_PFV est un type abstrait pour un pointeur sur une fonction (void*).

• device. Le périphérique contenant le fichier de l'image.

• node. Le numéro de noeud (node) du fichier de l'image.

• name. Le chemin complet du fichier d'où provient l'image.

• text et text_size. L'adresse et la taille (en octets) du segment de code (text segment) de l'image.

• data and data_size. L'adresse et la taille (en octets) du segment de données (data segment) de l'image.

Les constantes bien-nommées d'image_type sont :

Constantes image_type
B_APP_IMAGE
B_LIBRARY_IMAGE
B_ADD_ON_IMAGE

CODES DE RETOUR

• B_OK. L'image a été trouvée; info contient des informations valides.

• B_BAD_VALUE. image n'identifie pas une image existante, team n'identifie pas une team existante, ou il n'y a plus d'images à visiter.

get_image_symbol() , get_nth_image_symbol()

	status_t get_image_symbol(image_id image,       char *symbol_name,       int32 symbol_type,       void **location) status_t get_nth_image_symbol(image_id image,       int32 n,       char *name,       int32 *name_length,       int32 *symbol_type,       void **location)

get_image_symbol() retourne, dans location, un pointeur sur l'adresse du symbole identifié par les arguments image, symbol_name, et symbol_type. Un exemple démontrant l'usage de cette fonction est donné dans "Symboles."

get_nth_image_symbol(), elle, retourne des informations sur le nième symbole dans l'image donnée. Les informations sont retournées dans les arguments :

• name est le nom du symbole. Vous devez allouer le buffer name avant de le passer—la fonction copie le nom dans ce buffer.

• Vous pointez name_length sur un entier donnant la taille du buffer name que vous passez. La fonction utilise cette valeur pour tronquer la chaine qu'elle recopie dans name. La fonction modifie ensuite name_length à la taille complète (non tronqué) du nom du symbole (plus un octet pour recevoir un NULL de terminaison). Pour s'assurer que vous avez obtenu le nom complet du symbole, vous devez comparer la valeur en entrée de name_length avec celle modifiée par la fonction. Si celle en entrée est plus petite que la longueur complète, vous pouvez alors ré-invoquer get_nth_image_symbol() avec un buffer name agrandi en conséquence, et la valeur de name_length ajustée.

  Gardez à l'esprit que name_length est modifée chaque fois que vous appellez get_nth_image_symbol(). Si vous appellez cette fonction de manière successive (pour obtenir tous les symboles d'une image), vous devez ré-affecter la valeur de name_length entre chaque appel.

• La fonction positionne symbol_type à B_SYMBOL_TYPE_DATA si le symbole est une variable, B_SYMBOL_TYPE_TEXT si le symbole est une fonction, ou B_SYMBOL_TYPE_ANY si le format exécutable ne fait pas de distinction entre les deux. La valeur de l'argument en entrée de fonction est sans conséquence.

• La fonction modifie location pour pointer sur l'adresse du symbole.

Pour obtenir les image_id sur lequels ces fonctions peuvent opérer, utilisez la fonction get_next_image_info(). Ces identifiants sont également retournés directement lorsque vous chargez une image d'add-on via la fonction load_add_on().

CODES DE RETOUR

• B_OK. Le symbole a été trouvé.

• B_BAD_IMAGE_ID. image n'identifie pas une image existante.

• B_BAD_INDEX. n est hors limite.

load_add_on() , unload_add_on()

	image_id load_add_on(const char *pathname) status_t unload_add_on(image_id image)

load_add_on() charge une image d'add-on (composant), identifiée par pathname, dans l'espace d'adressage de votre application.

• pathname peut être absolu ou relatif; s'il est relatif, il est évalué à partir du chemin spécifié par la variable d'environnement ADDON_PATH.

• La fonction retourne un image_id (un entier positif) qui représente l'image chargée. Les IDs d'images sont uniques à travers tout le système.

Un exemple démontrant l'usage de load_add_on() est donné dans "Chargez une image d'add-on."

Vous pouvez charger la même image d'add-on plusieurs fois; chaque fois que vous chargez l'add-on un nouveau, unique, image_id est créé et retourné.

unload_add_on() décharge l'image d'add-on identifiée par l'argument. Les symboles de l'image sont retirés, et la mémoire qu'ils représentaient est libérée. Si l'argument n'identifie pas une image valide, la fonction retourne B_ERROR. Autrement, elle retourne B_OK.

CODES DE RETOUR

• Valeur de image_id positive (load) ou B_OK (unload). Succès.

• B_ERROR. L'image n'a pas pu être chargée (pour une raison quelconque), ou image n'est pas un ID d'image valide.

load_image()

	thread_id load_image(int argc,       const char **argv,       const char **env)

Charge une image applicative dans le système (cela ne charge pas l'image dans l'espace d'adressage de l'appelant), créer une team séparée pour la nouvelle application, et engendre et retourne l'ID du thread principal de la team. L'image est identifiée par le chemin d'accès donné dans argv[0].

Les arguments sont passés à la fonction main() de l'image (ils apparaissent dans les arguments de mêmes noms de cette fonction) :

• argc indique le nombre d'entrées dans le tableau argv.

• La première chaine du tableau argv doit être le chemin d'accès au fichier de l'image. Vous ajoutez ensuite tous les autres arguments désirés dans le tableau, et vous terminez ce tableau par une entrée NULL. Notez que la valeur de argc ne doit pas prendre en compte le NULL terminant argv.

• envp est un tableau de variables d'environnement qui sont passées aussi à main(). Typiquement, vous utilisez le pointeur global environ :

      extern char **environ;
      
      load_image(..., environ);

Les tableaux argv et envp sont copiés dans l'espace d'adresses du nouveau thread. Si vous allouez l'un ou l'autre de ces tableaux, vous pouvez le(s) libérer sans risque immédiatement après le retour de load_image().

Le thread retourné par load_image() est suspendu. Pour démarrer l'exécution du thread, vous passez le thread_id à resume_thread() ou wait_for_thread().

Un exemple démontrant l'usage de load_image() est donné dans "Charger une image applicative."

CODES DE RETOUR

• Entiers positifs. Succès.

• B_ERROR. Echec, pour une raison quelconque.