#include <oskit/exec/exec.h>typedef int exec_read_exec_func_t(void *handle, oskit_addr_t file_ofs, oskit_size_t file_size, oskit_addr_t mem_addr, oskit_size_t mem_size, exec_sectype_t section_type);
This type describes the function prototype of the read_exec callback function which the client OS must supply to the executable interpreter; it is used by the executable interpreter library to read actual executable code and data from the executable file to be copied or mapped into the loaded program's image. It is also used to indicate to the client where debugging information can be found in the executable, and what format it is in. The executable interpreter generally calls this function once for each ``section'' it finds in the executable file, indicating where in the executable file to load or map from and where in the resulting program image to copy or map to. The actual executable data itself never actually ``passes through'' the generic executable interpreter itself; instead, the interpreter merely ``directs'' the loading process, giving the client OS ultimate flexibility in the way the loading is performed. In fact, the client's callback function does not even necessarily need to ``load'' the executable: for example, if the client merely wants to determine the memory layout described by the executable file, it can provide a callback that does not actually load anything but instead just records the information passed by the executable interpreter.Note that not all sections in an executable file are necessarily relevant to the loaded program image itself: for example, the executable interpreter also calls this callback when it encounters debug sections that the client may be interested in. Therefore, to avoid choking on such sections, the client's implementation of this callback function should always check the section_type parameter and ignore sections for which EXEC_SECTYPE_ALLOC is not set and it doesn't otherwise know how to deal with.
- handle
- This is simply the opaque pointer value originally passed by the client in the call to the executable interpreter; the client's callbacks typically use it to locate any state relevant to the executable being loaded. The actual use or meaning of this parameter is completely opaque to the executable interpreter library.
- file_ofs
- This parameter indicates the offset in the file at which the section's data begins. This is only valid for sections that have file data: for example, for BSS sections, which are allocated but not loaded, this parameter is undefined.
- file_size
- Size of the section's data in the executable file, or zero for sections that have no file data, such as BSS sections.
- mem_addr
- The address in the loaded program's address space at which this section should be loaded. This address is found in or deduced from the executable file's metadata, and generally indicates the address for which this section of the program was linked. For sections that are not allocated in the program image (sections without the EXEC_SECTYPE_ALLOC flag), this parameter is undefined and should be ignored.
- mem_size
- The amount of memory to allocate for this section in the loaded program's address space. This is usually equal to file_size, but may be larger, in which case the remaining portion of the section past the end of the data actually loaded from the file must be initialized to zero.
- section_type
- Indicates the type of this section; it is a mask of the flag bits described below in Section 23.2.3.
Returns 0 on success, or an error code on failure. The error code may be either one of the EX_ error codes defined in exec.h, or it may be a caller-defined error code, which the executable interpreter code will simply pass directly back through to the original caller.