.. py:module:: segment segment -- Segment module ========================= This module provides a number of tools that can be used to enumerate or work with segments within a database. The base argument type for some of the utilities within this module is the :py:obj:`idaapi.segment_t`. This type is interchangeable with the address or the segment name and so either can be used to identify a segment. When listing or enumerating segments there are different types that one can use in order to filter or match them. These types are as follows: - ``name`` - Match according to the exact segment name - ``like`` - Filter the segment names according to a glob - ``regex`` - Filter the function names according to a regular-expression - ``index`` - Match the segment by its index - ``identifier`` - Match the segment by its identifier - ``selector`` - Match the segment by its selector - ``greater`` or ``ge`` - Filter the segments for any after the specified address (inclusive) - ``gt`` - Filter the segments for any after the specified address (exclusive) - ``less`` or ``le`` - Filter the segments for any before the specified address (inclusive) - ``lt`` - Filter the segments for any before the specified address (exclusive) - ``predicate`` - Filter the segments by passing their :py:obj:`idaapi.segment_t` to a callable Some examples of using these keywords are as follows:: > for l, r in database.segments(): ... > database.segments.list(regex=r'\\.r?data') > iterable = database.segments.iterate(like='*text*') > result = database.segments.search(greater=0x401000) ------------- Function list ------------- The functions that are available in this module use multicased functions and aliases. For more information on this, please see :ref:`multicase-aliases` and :ref:`multicase-functions`. .. py:function:: bottom() Return the bottom address of the current segment. .. py:function:: bottom(segment) Return the bottom address of the segment identified by ``segment``. :param segment: an identifier used to specify a segment .. py:function:: bounds() Return the bounds of the current segment. Aliases: :py:func:`segment.range` .. py:function:: bounds(segment) Return the bounds of the segment specified by ``segment``. Aliases: :py:func:`segment.range` :param segment: an identifier used to specify a segment .. py:function:: by(segment) Return a segment by its :py:obj:`idaapi.segment_t`. :param segment: an :py:obj:`idaapi.segment_t` to return :type segment: idaapi.segment_t .. py:function:: by(name) Return the segment by its ``name``. :param name: the name of the segment to return :type name: str .. py:function:: by(ea) Return the segment containing the address ``ea``. :param ea: an address belonging to the segment to return :type ea: int or long .. py:function:: by() Return the current segment. .. py:function:: by(\*\*type) Return the segment matching the specified keywords in ``type``. :param \*\*type: any keyword that can be used to match the segment with .. py:function:: by_address(ea) Return the segment that contains the specified ``ea``. Aliases: :py:func:`segment.byaddress` :param ea: an address belonging to the segment to return .. py:function:: by_name(name) Return the segment with the given ``name``. Aliases: :py:func:`segment.byname` :param name: the name of the segment to return .. py:function:: by_offset(offset) Return the specified ``offset`` translated to the beginning of the current segment. Aliases: :py:func:`segment.byoffset` :param offset: the offset into the current segment to return as an address :type offset: int or long .. py:function:: by_offset(segment, offset) Return the specified ``offset`` translated to the beginning of ``segment``. Aliases: :py:func:`segment.byoffset` :param segment: an identifier used to specify a segment :param offset: the offset into the segment to return as an address :type offset: int or long .. py:function:: by_selector(selector) Return the segment associated with ``selector``. Aliases: :py:func:`segment.byselector` :param selector: the selector belonging to the segment to return .. py:function:: color() Return the color of the current segment. .. py:function:: color(segment) Return the color of the segment identified by ``segment``. :param segment: an identifier used to specify a segment .. py:function:: color(none) Clear the color of the current segment. :param none: the python value :py:obj:`None` :type none: None .. py:function:: color(segment, none) Clear the color of the segment identified by ``segment``. :param segment: an identifier used to specify a segment :param none: the python value :py:obj:`None` :type none: None .. py:function:: color(segment, rgb) Sets the color of the segment identified by ``segment`` to ``rgb``. :param segment: an identifier used to specify a segment :param rgb: the color as a red, green, and blue integer (``0x00RRGGBB``) :type rgb: int or long .. py:function:: contains(ea) Returns true if the address ``ea`` is contained within the current segment. :param ea: an address in the database :type ea: int or long .. py:function:: contains(address, ea) Returns true if the address ``ea`` is contained within the segment belonging to the specified ``address``. :param address: an address belonging to a segment :type address: int or long :param ea: an address in the database :type ea: int or long .. py:function:: contains(name, ea) Returns true if the address ``ea`` is contained within the segment with the specified ``name``. :param name: the name of a segment :type name: str :param ea: an address in the database :type ea: int or long .. py:function:: contains(segment, ea) Returns true if the address ``ea`` is contained within the :py:obj:`idaapi.segment_t` specified by ``segment``. :param segment: an :py:obj:`idaapi.segment_t` to check :type segment: idaapi.segment_t :param ea: an address in the database :type ea: int or long .. py:function:: go_offset(offset) Go to the ``offset`` of the current segment. Aliases: :py:func:`segment.goof`, :py:func:`segment. gooffset`, :py:func:`segment.gotooffset` :param offset: an offset into the current segment :type offset: int or long .. py:function:: go_offset(segment, offset) Go to the ``offset`` of the specified ``segment``. Aliases: :py:func:`segment.goof`, :py:func:`segment. gooffset`, :py:func:`segment.gotooffset` :param segment: an identifier used to specify a segment :param offset: an offset into the segment :type offset: int or long .. py:function:: iterate() Iterate through all of the addresses within the current segment. .. py:function:: iterate(segment) Iterate through all of the addresses within the specified ``segment``. :param segment: an identifier used to specify a segment .. py:function:: iterate(segment) Iterate through all of the addresses within the :py:obj:`idaapi.segment_t` represented by ``segment``. :param segment: an :py:obj:`idaapi.segment_t` to iterate through :type segment: idaapi.segment_t .. py:function:: list(string) List all of the segments whose name matches the glob specified by ``string``. :param string: the glob to filter the segment names with :type string: str .. py:function:: list(\*\*type) List all of the segments in the database that match the keyword specified by ``type``. :param \*\*type: any keyword that can be used to filter the segments with .. py:function:: load(filename, ea, size=None, offset=0, \*\*kwds) Load the specified ``filename`` to the address ``ea`` as a segment. If ``size`` is not specified, use the length of the file. The keyword ``offset`` represents the offset into the file to use. The keyword ``name`` can be used to name the segment. :param filename: a filename to read from :param ea: the address to map to :param size: the number of bytes to map :param offset: the offset into the file to read from :param \*\*kwds: if ``name`` is specified as a string, then use it as the name for the new segment .. py:function:: map(ea, size, newea, \*\*kwds) Map ``size`` bytes of data from ``ea`` into a new segment at ``newea``. The keyword ``name`` can be used to name the segment. :param ea: the address of the data to map :param size: the number of bytes to map :param newea: the target address to map the data to :param \*\*kwds: if ``name`` is specified as a string, then use it as the name for the new segment .. py:function:: name() Return the name of the current segment. .. py:function:: name(segment) Return the name of the segment identified by ``segment``. :param segment: an identifier used to specify a segment .. py:function:: new(offset, size, name, \*\*kwds) Create a segment at ``offset`` with ``size`` and name it according to ``name``. The keyword ``bits`` can be used to specify the bit size of the segment The keyword ``comb`` can be used to specify any flags (idaapi.sc\*) The keyword ``align`` can be used to specify paragraph alignment (idaapi.sa\*) The keyword ``org`` specifies the origin of the segment (must be paragraph aligned due to ida) Aliases: :py:func:`segment.create` :param offset: the offset to create the segment at :param size: the size of the segment :param name: the name of the segment :param \*\*kwds: If :py:obj:`bits` is specified, then specify the bit size of the segment. :py:obj:`align` can be used to specify the paragraph alignment. :py:obj:`org` can be used to set the origin and :py:obj:`comb` can be used to specify any other flags .. py:function:: offset() Return the offset of the current address from the beginning of the current segment. .. py:function:: offset(ea) Return the offset of the address ``ea`` from the beginning of the current segment. :param ea: an address within the current segment :type ea: int or long .. py:function:: offset(segment, ea) Return the offset of the address ``ea`` from the beginning of ``segment``. :param segment: an identifier used to specify a segment :param ea: an address within the segment :type ea: int or long .. py:function:: read() Return the contents of the current segment. Aliases: :py:func:`segment.string` .. py:function:: read(segment) Return the contents of the segment identified by ``segment``. Aliases: :py:func:`segment.string` :param segment: an identifier used to specify a segment .. py:function:: remove(segment, contents=False) Remove the specified ``segment``. If the bool ``contents`` is specified, then remove the contents of the segment from the database. Aliases: :py:func:`segment.delete` :param segment: an identifier used to specify a segment :param contents: whether to remove the contents of the segment from the database .. py:function:: repr() Return the current segment in a printable form. .. py:function:: repr(segment) Return the specified ``segment`` in a printable form. :param segment: an identifier used to specify a segment .. py:function:: save(filename, segment, offset=0) Export the segment identified by ``segment`` to the file named ``filename``. If the int ``offset`` is specified, then begin writing into the file at the specified offset. Aliases: :py:func:`segment.export` :param filename: the path to the filename to write the segment to :param segment: an identifier used to specify a segment :param offset: the offset into the file to start writing the segment .. py:function:: search(name) Search through all the segments and return the first one matching the glob ``name``. :param name: the glob to match the segment name with :type name: str .. py:function:: search(\*\*type) Search through all the segments and return the first one that matches the keyword specified by ``type``. :param \*\*type: any keyword that can be used to filter segments with .. py:function:: size() Return the size of the current segment. .. py:function:: size(segment) Return the size of the segment specified by ``segment``. :param segment: an identifier used to specify a segment .. py:function:: top() Return the top address of the current segment. .. py:function:: top(segment) Return the top address of the segment identified by ``segment``. :param segment: an identifier used to specify a segment .. py:function:: type() Return the type of the current segment. .. py:function:: type(ea) Return the type of the segment containing the address ``ea``. :param ea: :type ea: int or long .. py:function:: type(name) Return the type of the segment with the specified ``name``. :param name: the name of the segment to return the type for :type name: str .. py:function:: type(segment) Return the type of the :py:obj:`idaapi.segment_t` specified by ``segment``. :param segment: an :py:obj:`idaapi.segment_t` to return the type for :type segment: idaapi.segment_t .. py:function:: type(segment, segtype) Return whether the given ``segment`` is of the provided ``segtype``. :param segment: an :py:obj:`idaapi.segment_t` to check the type for :param segtype: an integer containing the :py:obj:`idaapi.SEG_\*` value to check the type against :type segtype: int or long .. py:function:: within() Returns true if the current address is within any segment. .. py:function:: within(ea) Returns true if the address ``ea`` is within any segment. :param ea: an address in the database :type ea: int or long