The Kernel Kit: Images

The Kernel Kit Table of Contents | The Kernel Kit Index

# Images

Declared in: be/kernel/image.h

Library: libroot.so

This isn't about graphics. An image is compiled code, of which there are three types: app images, library images, and add-on images. An app image is executable code that can be launched. A library image is a collection of shared code that you link against when you're compiling your application. An add-on image is code that an app can load and run while the app itself is running. Note that an add-on can also be an app; in other words, you can create an image that can be launched by itself, or that can be loaded into another application.

For more information on creating and using images, see "Image Concepts".

## Image Functions

### 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 `

These functions copy, into the info argument, the `image_info` structure for a particular image. The `get_image_info()` function gets the information for the image identified by image.

The `get_next_image_info()` function lets you step through the list of a team's images through iterated calls. The team argument identifies the team you want to look at; a team value of 0 means the team of the calling thread. The cookie argument is a placemark; you set it to 0 on your first call, and let the function do the rest. The function returns `B_BAD_VALUE` when there are no more images to visit:

       /* Get the image_info for every image in this team. */
       image_info info;
       int32 cookie = 0;

       while (get_next_image_info(0, &cookie, &info) == B_OK)
          ...

The `image_info` structure is:

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

`

The fields are:

- `id`. The image's `image_id` number.

- `type`. A constant (listed below) that tells whether this is an app, library, or add-on image.

- `sequence` and `init_order`. These are zero-based ordinal numbers that give the order in which the image was loaded and initialized, compared to all the other images in this team.

- `init_routine` and `term_routine`. These are pointers to the functions that are used to intialize and terminate the image (more specifically, the image's main thread). The `B_PFV` type is a cover for a pointer to a `(void`*) function.

- `device`. The device that the image file lives on.

- `node`. The node number of the image file.

- `name`. The full pathname of the file whence sprang the image.

- `text` and `text_size`. The address and the size (in bytes) of the image's text segment.

- `data` and `data_size`. The address and size of the image's data segment.

The self-explanatory `image_type` constants are:

`image_type` Constants
`B_APP_IMAGE`
`B_LIBRARY_IMAGE`
`B_ADD_ON_IMAGE`

RETURN CODES

`B_OK`. The image was found; info contains valid information.

- `B_BAD_VALUE`. image doesn>t identify an existing image, team doesn>t identify an existing team, or there are no more images to visit.

### 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()` returns, in location, a pointer to the address of the symbol that's identified by the image, symbol_name, and symbol_type arguments. An example demonstrating the use of this function is given in "Symbols."

`get_nth_image_symbol()` returns information about the n'th symbol in the given image. The information is returned in the arguments:

- name is the name of the symbol. You have to allocate the name buffer before you pass it in—the function copies the name into the buffer.

- You point name_length to an integer that gives the length of the name buffer that you're passing in. The function uses this value to truncate the string that it copies into name. The function then resets name_length to the full (untruncated) length of the symbol's name (plus one byte to accommodate a terminating `NULL`). To ensure that you've gotten the symbol's full name, you should compare the in-going value of name_length with the value that the function sets it to. If the in-going value is less than the full length, you can then re-invoke `get_nth_image_symbol()` with an adequately lengthened name buffer, and an increased name_length value.

  Keep in mind that name_length is reset each time you call `get_nth_image_symbol()`. If you're calling the function iteratively (to retrieve all the symbols in an image), you need to reset the name_length value between calls.

- The function sets symbol_type to `B_SYMBOL_TYPE_DATA` if the symbol is a variable, `B_SYMBOL_TYPE_TEXT` if the symbol is a function, or `B_SYMBOL_TYPE_ANY` if the executable format doesn't distinguish between the two. The argument's value going into the function is of no consequence.

- The function sets location to point to the symbol's address.

To retrieve `image_id` numbers on which these functions can act, use the `get_next_image_info()` function. Such numbers are also returned directly when you load an add-on image through the `load_add_on()` function.

RETURN CODES

`B_OK`. The symbol was found.

- `B_BAD_IMAGE_ID`. image doesn>t identify an existing image.

- `B_BAD_INDEX`. n is out-of-bounds.

### 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()` loads an add-on image, identified by pathname, into your application's address space.

- pathname can be absolute or relative; if it's relative, it's reckoned off the base path specified by the `ADDON_PATH` environment variable.

- The function returns an `image_id` (a positive integer) that represents the loaded image. Image ID numbers are unique across the system.

An example that demonstrates the use of`load_add_on()` is given in "Loading an Add-on Image."

You can load the same add-on image twice; each time you load the add-on a new, unique `image_id` is created and returned.

`unload_add_on()` removes the add-on image identified by the argument. The image's symbols are removed, and the memory that they represent is freed. If the argument doesn't identify a valid image, the function returns `B_ERROR`. Otherwise, it returns `B_OK`.

RETURN CODES

Positive `image_id value` (load) or `B_OK` (unload). Success.

- `B_ERROR`. The image couldn't be loaded (for whatever reason), or image isn't a valid image ID.

### load_image()

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

Loads an app image into the system (it doesn't load the image into the caller's address space), creates a separate team for the new application, and spawns and returns the ID of the team's main thread. The image is identified by the pathname given in argv[0].

The arguments are passed to the image's `main()` function (they show up there as the function's similarly named arguments):

- argc gives the number of entries that are in the argv array.

- The first string in the argv array must be the name of the image file. You then install any other arguments you want in the array, and terminate the array with a `NULL` entry. Note that the value of argc shouldn't count argv's terminating `NULL`.

- envp is an array of environment variables that are also passed to `main()`. Typically, you use the global `environ` pointer:

          extern char **environ;

          load_image(..., environ);

The argv and envp arrays are copied into the new thread's address space. If you allocated either of these arrays, it's safe to free them immediately after `load_image()` returns.

The thread that's returned by`load_image()` is in a suspended state. To start the thread running, you pass the `thread_id` to `resume_thread()` or `wait_for_thread()`.

An example that demonstrates the use of `load_image()` is given in "Loading an App Image."

RETURN CODES

- Positive integers. Success.

- `B_ERROR`. Failure, for whatever reason.

The Kernel Kit Table of Contents | The Kernel Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..