Module ida_segment

Add a new segment, second form. Segment alignment is set to 'saRelByte' . Segment combination is "public" or "stack" (if segment class is "STACK"). Addressing mode of segment is taken as default (16bit or 32bit). Default segment registers are set to 'BADSEL' . If a segment already exists at the specified range of addresses, this segment will be truncated. Instructions and data in the old segment will be deleted if the new segment has another addressing mode or another segment base address.

Parameters:

• para - segment base paragraph. if paragraph can't fit in 16bit, then a new selector is allocated and mapped to the paragraph. (C++: ea_t)
• start - start address of the segment. if start== BADADDR then start <- to_ea(para,0). (C++: ea_t)
• end - end address of the segment. end address should be higher than start address. For emulate empty segments, use SEG_NULL segment type. If the end address is lower than start address, then fail. If end== BADADDR , then a segment up to the next segment will be created (if the next segment doesn't exist, then 1 byte segment will be created). If 'end' is too high and the new segment would overlap the next segment, 'end' is adjusted properly. (C++: ea_t)
• name - name of new segment. may be NULL (C++: const char *)
• sclass - class of the segment. may be NULL. type of the new segment is modified if class is one of predefined names: "CODE" -> SEG_CODE "DATA" -> SEG_DATA "CONST" -> SEG_DATA "STACK" -> SEG_BSS "BSS" -> SEG_BSS "XTRN" -> SEG_XTRN "COMM" -> SEG_COMM "ABS" -> SEG_ABSSYM (C++: const char *)
• flags, (C++ - int)

Returns: bool

Add a new segment. If a segment already exists at the specified range of addresses, this segment will be truncated. Instructions and data in the old segment will be deleted if the new segment has another addressing mode or another segment base address.

Parameters:

• s - pointer to filled segment structure. segment selector should have proper mapping (see set_selector() ). if s.start_ea== BADADDR then s.start_ea <- get_segm_base(&s) if s.end_ea== BADADDR , then a segment up to the next segment will be created (if the next segment doesn't exist, then 1 byte segment will be created). if the s.end_ea < s.start_ea, then fail. if s.end_ea is too high and the new segment would overlap the next segment, s.end_ea is adjusted properly. (C++: segment_t *)
• name - name of new segment. may be NULL. if specified, the segment is immediately renamed (C++: const char *)
• sclass - class of the segment. may be NULL. if specified, the segment class is immediately changed (C++: const char *)
• flags - Add segment flags (C++: int)

Returns: bool

Add segment translation.

Parameters:

• segstart - start address of the segment to add translation to (C++: ea_t)
• mappedseg - start address of the overlayed segment (C++: ea_t)

Returns: bool

Allocate a selector for a segment unconditionally. You must call this function before calling 'add_segm_ex()' . 'add_segm()' calls this function itself, so you don't need to allocate a selector. This function will allocate a new free selector and setup its mapping using 'find_free_selector()' and 'set_selector()' functions.

Parameters:

• segbase - a new segment base paragraph (C++: ea_t)

Returns: sel_t

the allocated selector number

Convert a debugger segment to a regular segment and vice versa. When converting debug->regular, the memory contents will be copied to the database.

Parameters:

• s - segment to modify (C++: segment_t *)
• is_deb_segm - new status of the segment (C++: bool)

Returns: int

Change segment status result codes

Delete a segment.

Parameters:

• ea - any address belonging to the segment (C++: ea_t)
• flags - Segment modification flags (C++: int)

Returns: bool

Delete the translation list

Parameters:

• segstart - start address of the segment to delete translation list (C++: ea_t)

Delete mapping of a selector. Be wary of deleting selectors that are being used in the program, this can make a mess in the segments.

Parameters:

• selector - number of selector to remove from the translation table (C++: sel_t)

Find first unused selector.

Returns: sel_t

a number >= 1

Find a selector that has mapping to the specified paragraph.

Parameters:

• base - paragraph to search in the translation table (C++: ea_t)

Returns: sel_t

selector value or base

Get common selector for a group of segments.

Parameters:

• grpsel - selector of group segment (C++: sel_t)

Returns: sel_t

common selector of the group or 'grpsel' if no such group is found

Get pointer to the next segment.

Parameters:

• ea, (C++ - ea_t)

Returns: segment_t

Get pointer to the previous segment.

Parameters:

• ea, (C++ - ea_t)

Returns: segment_t

Get segment base linear address. Segment base linear address is used to calculate virtual addresses. The virtual address of the first byte of the segment will be (start address of segment - segment base linear address)

Parameters:

• s - pointer to segment (C++: const segment_t *)

Returns: ea_t

0 if s == NULL, otherwise segment base linear address

Get pointer to segment by its name. If there are several segments with the same name, returns the first of them.

Parameters:

• name - segment name. may be NULL. (C++: const char *)

Returns: segment_t

NULL or pointer to segment structure

Get pointer to segment structure. This function finds a segment by its selector. If there are several segments with the same selectors, the last one will be returned.

Parameters:

• selector - a segment with the specified selector will be returned (C++: sel_t)

Returns: segment_t

pointer to segment or NULL

Get segment class. Segment class is arbitrary text (max 8 characters).

Parameters:

• s - pointer to segment (C++: const segment_t *)

Returns: str

size of segment class (-1 if s==NULL or bufsize<=0)

Get true segment name by pointer to segment.

Parameters:

• s - pointer to segment (C++: const segment_t *)
• flags - 0-return name as is; 1-substitute bad symbols with _ 1 corresponds to GN_VISIBLE (C++: int)

Returns: str

size of segment name (-1 if s==NULL)

Get number of segment by address.

Parameters:

• ea - linear address belonging to the segment (C++: ea_t)

Returns: int

-1 if no segment occupies the specified address. otherwise returns number of the specified segment (0.. get_segm_qty() -1)

Get segment base paragraph. Segment base paragraph may be converted to segment base linear address using 'to_ea()' function. In fact, to_ea(get_segm_para(s), 0) == get_segm_base(s).

Parameters:

• s - pointer to segment (C++: const segment_t *)

Returns: ea_t

0 if s == NULL, the segment base paragraph

Get text representation of segment alignment code.

Parameters:

• align, (C++ - uchar)

Returns: char const *

text digestable by IBM PC assembler.

Get segment comment.

Parameters:

• s - pointer to segment structure (C++: const segment_t *)
• repeatable - 0: get regular comment. 1: get repeatable comment. (C++: bool)

Returns: str

size of comment or -1

Get text representation of segment combination code.

Parameters:

• comb, (C++ - uchar)

Returns: char const *

text digestable by IBM PC assembler.

Get segment translation list.

Parameters:

• transmap - vector of segment start addresses for the translation list (C++: eavec_t *)
• segstart - start address of the segment to get information about (C++: ea_t)

Returns: ssize_t

-1 if no translation list or bad segstart. otherwise returns size of translation list.

Get segment name by pointer to segment.

Parameters:

• s - pointer to segment (C++: const segment_t *)

Returns: str

size of segment name (-1 if s==NULL)

Get description of selector (0.. 'get_selector_qty()' -1)

Parameters:

• n, (C++ - int)

Returns: bool

Get pointer to segment by its number.Obsoleted because it can slow down the debugger (it has to refresh the whole memory segmentation to calculate the correct answer)

Parameters:

• n - segment number in the range (0.. get_segm_qty() -1) (C++: int)

Returns: segment_t

NULL or pointer to segment structure

Get pointer to segment by linear address.

Parameters:

• ea - linear address belonging to the segment (C++: ea_t)

Returns: segment_t

NULL or pointer to segment structure

See 'SFL_HIDDEN' , 'SCF_SHHID_SEGM' .

Parameters:

• s, (C++ - segment_t *)

Returns: bool

Is the database a miniidb created by the debugger?.

Returns: bool

true if the database contains no segments or only debugger segments

Is a segment pointer locked?

Parameters:

• segm, (C++ - const segment_t *)

Returns: bool

Does the address belong to a segment with a special type?. ( 'SEG_XTRN' , 'SEG_GRP' , 'SEG_ABSSYM' , 'SEG_COMM' )

Parameters:

• ea - linear address (C++: ea_t)

Returns: bool

Has segment a special type?. ( 'SEG_XTRN' , 'SEG_GRP' , 'SEG_ABSSYM' , 'SEG_COMM' )

Parameters:

• seg_type, (C++ - uchar)

Returns: bool

See 'SFL_HIDDEN' .

Parameters:

• s, (C++ - segment_t *)

Returns: bool

Lock segment pointer Locked pointers are guaranteed to remain valid until they are unlocked. Ranges with locked pointers cannot be deleted or moved.

Parameters:

• segm, (C++ - const segment_t *)
• lock, (C++ - bool)

Move a segment to a new address. This function moves all information to the new address. It fixes up address sensitive information in the kernel. The total effect is equal to reloading the segment to the target address. For the file format dependent address sensitive information, 'loader_t::move_segm' is called. Also IDB notification event 'idb_event::segm_moved' is called.

Parameters:

• s - segment to move (C++: segment_t *)
• to - new segment start address (C++: ea_t)
• flags - Move segment flags (C++: int)

Returns: int

Move segment result codes

Move segment start. The main difference between this function and 'set_segm_start()' is that this function may expand the previous segment while 'set_segm_start()' never does it. So, this function allows to change bounds of two segments simultaneously. If the previous segment and the specified segment have the same addressing mode and segment base, then instructions and data are not destroyed - they simply move from one segment to another. Otherwise all instructions/data which migrate from one segment to another are destroyed.this function never disables addresses.

Parameters:

• ea - any address belonging to the segment (C++: ea_t)
• newstart - new start address of the segment note that segment start address should be higher than segment base linear address. (C++: ea_t)
• mode - policy for destroying defined items 0: if it is necessary to destroy defined items, display a dialog box and ask confirmation 1: if it is necessary to destroy defined items, just destroy them without asking the user -1: if it is necessary to destroy defined items, don't destroy them (i.e. function will fail) -2: don't destroy defined items (function will succeed) (C++: int)

Returns: bool

Rebase the whole program by 'delta' bytes.

Parameters:

• delta - number of bytes to move the program (C++: adiff_t)
• flags - Move segment flags it is recommended to use MSF_FIXONCE so that the loader takes care of global variables it stored in the database (C++: int)

Returns: int

Move segment result codes

Truncate and sign extend a delta depending on the segment.

Parameters:

• s, (C++ - const segment_t *)
• delta, (C++ - adiff_t)

Returns: adiff_t

Truncate an address depending on the segment.

Parameters:

• s, (C++ - const segment_t *)
• ea, (C++ - ea_t)

Returns: ea_t

Get segment type.

Parameters:

• ea - any linear address within the segment (C++: ea_t)

Returns: uchar

Segment types , SEG_UNDF if no segment found at 'ea'

Get mapping of a selector as a linear address.

Parameters:

• selector - number of selector to translate to linear address (C++: sel_t)

Returns: ea_t

linear address the specified selector is mapped to. if there is no mapping, returns to_ea(selector,0);

Get mapping of a selector.

Parameters:

• selector - number of selector to translate (C++: sel_t)

Returns: ea_t

paragraph the specified selector is mapped to. if there is no mapping, returns 'selector'.

Initialize groups. The kernel calls this function at the start of work.Create a new group of segments (used OMF files).

Parameters:

• grp - selector of group segment (segment type is SEG_GRP ) You should create an 'empty' (1 byte) group segment It won't contain anything and will be used to redirect references to the group of segments to the common selector. (C++: sel_t)
• sel - common selector of all segments belonging to the segment You should create all segments within the group with the same selector value. (C++: sel_t)

Returns: int

1 ok

Change segment addressing mode (16, 32, 64 bits). You must use this function to change segment addressing, never change the 'bitness' field directly. This function will delete all instructions, comments and names in the segment

Parameters:

• s - pointer to segment (C++: segment_t *)
• bitness - new addressing mode of segment 2: 64bit segment 1: 32bit segment 0: 16bit segment (C++: size_t)

Returns: bool

success

Internal function.

Parameters:

• s, (C++ - segment_t *)
• newbase, (C++ - ea_t)

Returns: bool

Set segment class.

Parameters:

• s - pointer to segment (may be NULL) (C++: segment_t *)
• sclass - segment class (may be NULL). If segment type is SEG_NORM and segment class is one of predefined names, then segment type is changed to: "CODE" -> SEG_CODE "DATA" -> SEG_DATA "STACK" -> SEG_BSS "BSS" -> SEG_BSS if "UNK" then segment type is reset to SEG_NORM . (C++: const char *)
• flags, (C++ - int)

Returns: int

Set segment end address. The next segment is shrinked to allow expansion of the specified segment. The kernel might even delete the next segment if necessary. The kernel will ask the user for a permission to destroy instructions or data going out of segment scope if such instructions exist.

Parameters:

• ea - any address belonging to the segment (C++: ea_t)
• newend - new end address of the segment (C++: ea_t)
• flags - Segment modification flags (C++: int)

Returns: bool

Rename segment. The new name is validated (see validate_name). A segment always has a name. If you hadn't specified a name, the kernel will assign it "seg###" name where ### is segment number.

Parameters:

• s - pointer to segment (may be NULL) (C++: segment_t *)
• name - new segment name (C++: const char *)
• flags - ADDSEG_IDBENC or 0 (C++: int)

Returns: int

Set segment start address. The previous segment is trimmed to allow expansion of the specified segment. The kernel might even delete the previous segment if necessary. The kernel will ask the user for a permission to destroy instructions or data going out of segment scope if such instructions exist.

Parameters:

• ea - any address belonging to the segment (C++: ea_t)
• newstart - new start address of the segment note that segment start address should be higher than segment base linear address. (C++: ea_t)
• flags - Segment modification flags (C++: int)

Returns: bool

Set segment comment.

Parameters:

• s - pointer to segment structure (C++: const segment_t *)
• cmt - comment string, may be multiline (with ' '). maximal size is 4096 bytes. Use empty str ("") to delete comment (C++: const char *)
• repeatable - 0: set regular comment. 1: set repeatable comment. (C++: bool)

Set new translation list.

Parameters:

• segstart - start address of the segment to add translation to (C++: ea_t)
• transmap - vector of segment start addresses for the translation list. If transmap is empty, the translation list is deleted. (C++: const eavec_t &)

Returns: bool

Set mapping of selector to a paragraph. You should call this functionbeforecreating a segment which uses the selector, otherwise the creation of the segment will fail.

Parameters:

• selector - number of selector to map if selector == BADSEL , then return 0 (fail) if the selector has had a mapping, old mapping is destroyed if the selector number is equal to paragraph value, then the mapping is destroyed because we don't need to keep trivial mappings. (C++: sel_t)
• paragraph - paragraph to map selector (C++: ea_t)

Returns: int

See 'SFL_HIDDEN' .

Parameters:

• s, (C++ - segment_t *)
• visible, (C++ - bool)

Allocate a selector for a segment if necessary. You must call this function before calling 'add_segm_ex()' . 'add_segm()' calls this function itself, so you don't need to allocate a selector. This function will allocate a selector if 'segbase' requires more than 16 bits and the current processor is IBM PC. Otherwise it will return the segbase value.

Parameters:

• segbase - a new segment base paragraph (C++: ea_t)

Returns: sel_t

the allocated selector number

Generate segment footer line as a comment line. This function may be used in IDP modules to generate segment footer if the target assembler doesn't have 'ends' directive.

Parameters:

• ctx, (C++ - struct outctx_t &)
• seg, (C++ - segment_t *)

Take a memory snapshot of the running process.

Parameters:

• only_loader_segs - only is_loader_segm() segments will be affected (C++: bool)

Returns: bool

success