ida_xref
========

.. py:module:: ida_xref

.. autoapi-nested-parse::

   Functions that deal with cross-references (xrefs).

   There are 2 groups of xrefs: CODE and DATA references. All xrefs are kept in the bTree except the ordinary execution flow to the next instruction. The ordinary execution flow to the next instruction is kept in flags (see bytes.hpp)

   The source address of an xref must be an item head (is_head) or a structure member id. Even if an xref is generated by an element in the middle of the item, the item head address must be used. There are some exceptions to the rule but they are not worth mentioning here.

   Xrefs are automatically sorted by addresses. However, the flow to the next instruction is always at the beginning of the list.

   Xrefs are usually created by the processor module, as a reaction to the ev_emu_insn event. Plugins may create xrefs too but please note that upon a reanalysis of an item, all its xrefs, except the ones marked with XREF_USER, are deleted by the kernel. 

   .. tip:: 
      The `IDA Domain API <https://ida-domain.docs.hex-rays.com/>`_ simplifies 
      common tasks and provides better type hints, while remaining fully compatible 
      with IDAPython for advanced use cases.
      
      For cross-reference operations, see :mod:`ida_domain.xrefs`.



Attributes
----------

.. autoapisummary::

   ida_xref.fl_U
   ida_xref.fl_CF
   ida_xref.fl_CN
   ida_xref.fl_JF
   ida_xref.fl_JN
   ida_xref.fl_USobsolete
   ida_xref.fl_F
   ida_xref.dr_U
   ida_xref.dr_O
   ida_xref.dr_W
   ida_xref.dr_R
   ida_xref.dr_T
   ida_xref.dr_I
   ida_xref.dr_S
   ida_xref.XREF_USER
   ida_xref.XREF_TAIL
   ida_xref.XREF_BASE
   ida_xref.XREF_MASK
   ida_xref.XREF_PASTEND
   ida_xref.XREF_FLOW
   ida_xref.XREF_NOFLOW
   ida_xref.XREF_DATA
   ida_xref.XREF_CODE
   ida_xref.XREF_EA
   ida_xref.XREF_TID
   ida_xref.XREF_ALL
   ida_xref.XREF_FAR
   ida_xref.XREF_ALL
   ida_xref.XREF_FAR


Classes
-------

.. autoapisummary::

   ida_xref.cases_and_targets_t
   ida_xref.xrefblk_t
   ida_xref.casevec_t


Functions
---------

.. autoapisummary::

   ida_xref.create_switch_xrefs
   ida_xref.calc_switch_cases
   ida_xref.create_switch_table
   ida_xref.xrefchar
   ida_xref.add_cref
   ida_xref.del_cref
   ida_xref.add_dref
   ida_xref.del_dref
   ida_xref.get_first_dref_from
   ida_xref.get_next_dref_from
   ida_xref.get_first_dref_to
   ida_xref.get_next_dref_to
   ida_xref.get_first_cref_from
   ida_xref.get_next_cref_from
   ida_xref.get_first_cref_to
   ida_xref.get_next_cref_to
   ida_xref.get_first_fcref_from
   ida_xref.get_next_fcref_from
   ida_xref.get_first_fcref_to
   ida_xref.get_next_fcref_to
   ida_xref.has_external_refs
   ida_xref.has_jump_or_flow_xref
   ida_xref.delete_switch_table


Module Contents
---------------

.. py:function:: create_switch_xrefs(ea, si)

   This function creates xrefs from the indirect jump.

   Usually there is no need to call this function directly because the kernel
   will call it for switch tables

   Note: Custom switch information are not supported yet.

   :param ea: address of the 'indirect jump' instruction
   :param si: switch information

   :returns: Boolean


.. py:class:: cases_and_targets_t

   Bases: :py:obj:`object`


   .. py:attribute:: thisown


   .. py:attribute:: cases
      :type:  casevec_t


   .. py:attribute:: targets
      :type:  eavec_t


.. py:function:: calc_switch_cases(ea, si)

   Get information about a switch's cases.

   The returned information can be used as follows:

       for idx in range(len(results.cases)):
           cur_case = results.cases[idx]
           for cidx in range(len(cur_case)):
               print("case: %d" % cur_case[cidx])
           print("  goto 0x%x" % results.targets[idx])

   :param ea: address of the 'indirect jump' instruction
   :param si: switch information

   :returns: a structure with 2 members: 'cases', and 'targets'.


.. py:function:: create_switch_table(ea, si)

   Create switch table from the switch information

   :param ea: address of the 'indirect jump' instruction
   :param si: switch information

   :returns: Boolean


.. py:data:: fl_U

   unknown - for compatibility with old versions. Should not be used anymore. 
             


.. py:data:: fl_CF

   Call Far This xref creates a function at the referenced location 
             


.. py:data:: fl_CN

   Call Near This xref creates a function at the referenced location 
             


.. py:data:: fl_JF

   Jump Far.


.. py:data:: fl_JN

   Jump Near.


.. py:data:: fl_USobsolete

   User specified (obsolete)


.. py:data:: fl_F

   Ordinary flow: used to specify execution flow to the next instruction. 
             


.. py:data:: dr_U

   Unknown - for compatibility with old versions. Should not be used anymore. 
             


.. py:data:: dr_O

   Offset The reference uses 'offset' of data rather than its value OR The reference appeared because the "OFFSET" flag of instruction is set. The meaning of this type is IDP dependent. 
             


.. py:data:: dr_W

   Write access.


.. py:data:: dr_R

   Read access.


.. py:data:: dr_T

   Text (for forced operands only) Name of data is used in manual operand 
             


.. py:data:: dr_I

   Informational (a derived java class references its base class informationally) 
             


.. py:data:: dr_S

   Reference to enum member (symbolic constant)


.. py:data:: XREF_USER

   User specified xref. This xref will not be deleted by IDA. This bit should be combined with the existing xref types (cref_t & dref_t) Cannot be used for fl_F xrefs 
           


.. py:data:: XREF_TAIL

   Reference to tail byte in extrn symbols.


.. py:data:: XREF_BASE

   Reference to the base part of an offset.


.. py:data:: XREF_MASK

   Mask to get xref type.


.. py:data:: XREF_PASTEND

   Reference is past item. This bit may be passed to add_dref() functions but it won't be saved in the database. It will prevent the destruction of eventual alignment directives. 
           


.. py:function:: xrefchar(xrtype: char) -> char

   Get character describing the xref type. 
           
   :param xrtype: combination of Cross-Reference type flags and a cref_t of dref_t value


.. py:function:: add_cref(frm: ida_idaapi.ea_t, to: ida_idaapi.ea_t, type: cref_t) -> bool

   Create a code cross-reference. 
           
   :param to: linear address of referenced instruction
   :param type: cross-reference type
   :returns: success


.. py:function:: del_cref(frm: ida_idaapi.ea_t, to: ida_idaapi.ea_t, expand: bool) -> bool

   Delete a code cross-reference. 
           
   :param to: linear address of referenced instruction
   :param expand: policy to delete the referenced instruction
   * 1: plan to delete the referenced instruction if it has no more references.
   * 0: don't delete the referenced instruction even if no more cross-references point to it
   :returns: true: if the referenced instruction will be deleted


.. py:function:: add_dref(frm: ida_idaapi.ea_t, to: ida_idaapi.ea_t, type: dref_t) -> bool

   Create a data cross-reference. 
           
   :param to: linear address of referenced data
   :param type: cross-reference type
   :returns: success (may fail if user-defined xref exists from->to)


.. py:function:: del_dref(frm: ida_idaapi.ea_t, to: ida_idaapi.ea_t) -> None

   Delete a data cross-reference. 
           
   :param to: linear address of referenced data


.. py:class:: xrefblk_t

   Bases: :py:obj:`object`


   .. py:attribute:: thisown


   .. py:attribute:: frm
      :type:  ida_idaapi.ea_t


   .. py:attribute:: to
      :type:  ida_idaapi.ea_t

      the referenced address - filled by first_from(), next_from()



   .. py:attribute:: iscode
      :type:  bool

      is code reference (cref_t)? otherwise it is a data reference (dref_t) 
              



   .. py:attribute:: type
      :type:  uchar

      type of the last returned reference (cref_t & dref_t)



   .. py:attribute:: user
      :type:  bool

      is user defined xref? otherwise defined by ida



   .. py:method:: first_from(_from: ida_idaapi.ea_t, flags: int = 0) -> bool


   .. py:method:: first_to(_to: ida_idaapi.ea_t, flags: int = 0) -> bool


   .. py:method:: next_from(*args) -> bool


   .. py:method:: next_to(*args) -> bool


   .. py:method:: crefs_to(ea)

      Provide an iterator on code references to ea including flow references



   .. py:method:: fcrefs_to(ea)

      Provide an iterator on code references to ea



   .. py:method:: crefs_from(ea)

      Provide an iterator on code references from ea including flow references



   .. py:method:: fcrefs_from(ea)

      Provide an iterator on code references from ea



   .. py:method:: drefs_to(ea)

      Provide an iterator on data references to ea



   .. py:method:: drefs_from(ea)

      Provide an iterator on data references from ea



   .. py:method:: refs_from(ea, flag)

      Provide an iterator on from reference represented by flag



   .. py:method:: refs_to(ea, flag)

      Provide an iterator on to reference represented by flag



.. py:data:: XREF_FLOW

   return all references, including ordinary flow xrefs


.. py:data:: XREF_NOFLOW

   skip ordinary flow xrefs (code xrefs to the next insn) 
           


.. py:data:: XREF_DATA

   return only data references (dr_...)


.. py:data:: XREF_CODE

   return only code references (fl_...)


.. py:data:: XREF_EA

   return only program addresses


.. py:data:: XREF_TID

   return only type ids. XREF_EA and XREF_TID are exclusive, only one of them can be specified 
           


.. py:function:: get_first_dref_from(frm: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get first data referenced from the specified address. 
           
   :returns: linear address of first (lowest) data referenced from the specified address. Return BADADDR if the specified instruction/data doesn't reference to anything.


.. py:function:: get_next_dref_from(frm: ida_idaapi.ea_t, current: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get next data referenced from the specified address. 
           
   :param current: linear address of current referenced data. This value is returned by get_first_dref_from() or previous call to get_next_dref_from() functions.
   :returns: linear address of next data or BADADDR.


.. py:function:: get_first_dref_to(to: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get address of instruction/data referencing to the specified data. 
           
   :param to: linear address of referencing instruction or data
   :returns: BADADDR if nobody refers to the specified data.


.. py:function:: get_next_dref_to(to: ida_idaapi.ea_t, current: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get address of instruction/data referencing to the specified data 
           
   :param to: linear address of referencing instruction or data
   :param current: current linear address. This value is returned by get_first_dref_to() or previous call to get_next_dref_to() functions.
   :returns: BADADDR if nobody refers to the specified data.


.. py:function:: get_first_cref_from(frm: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get first instruction referenced from the specified instruction. If the specified instruction passes execution to the next instruction then the next instruction is returned. Otherwise the lowest referenced address is returned (remember that xrefs are kept sorted!). 
           
   :returns: first referenced address. If the specified instruction doesn't reference to other instructions then returns BADADDR.


.. py:function:: get_next_cref_from(frm: ida_idaapi.ea_t, current: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get next instruction referenced from the specified instruction. 
           
   :param current: linear address of current referenced instruction This value is returned by get_first_cref_from() or previous call to get_next_cref_from() functions.
   :returns: next referenced address or BADADDR.


.. py:function:: get_first_cref_to(to: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get first instruction referencing to the specified instruction. If the specified instruction may be executed immediately after its previous instruction then the previous instruction is returned. Otherwise the lowest referencing address is returned. (remember that xrefs are kept sorted!). 
           
   :param to: linear address of referenced instruction
   :returns: linear address of the first referencing instruction or BADADDR.


.. py:function:: get_next_cref_to(to: ida_idaapi.ea_t, current: ida_idaapi.ea_t) -> ida_idaapi.ea_t

   Get next instruction referencing to the specified instruction. 
           
   :param to: linear address of referenced instruction
   :param current: linear address of current referenced instruction This value is returned by get_first_cref_to() or previous call to get_next_cref_to() functions.
   :returns: linear address of the next referencing instruction or BADADDR.


.. py:function:: get_first_fcref_from(frm: ida_idaapi.ea_t) -> ida_idaapi.ea_t

.. py:function:: get_next_fcref_from(frm: ida_idaapi.ea_t, current: ida_idaapi.ea_t) -> ida_idaapi.ea_t

.. py:function:: get_first_fcref_to(to: ida_idaapi.ea_t) -> ida_idaapi.ea_t

.. py:function:: get_next_fcref_to(to: ida_idaapi.ea_t, current: ida_idaapi.ea_t) -> ida_idaapi.ea_t

.. py:function:: has_external_refs(pfn: func_t *, ea: ida_idaapi.ea_t) -> bool

   Does 'ea' have references from outside of 'pfn'?


.. py:function:: has_jump_or_flow_xref(ea: ida_idaapi.ea_t) -> bool

   Are there jump or flow references to EA?


.. py:function:: delete_switch_table(jump_ea: ida_idaapi.ea_t, si: switch_info_t) -> None

.. py:data:: XREF_ALL

.. py:data:: XREF_FAR

.. py:class:: casevec_t(*args)

   Bases: :py:obj:`object`


   .. py:attribute:: thisown


   .. py:method:: push_back(*args) -> qvector< long long > &


   .. py:method:: pop_back() -> None


   .. py:method:: size() -> size_t


   .. py:method:: empty() -> bool


   .. py:method:: at(_idx: size_t) -> qvector< long long > const &


   .. py:method:: qclear() -> None


   .. py:method:: clear() -> None


   .. py:method:: resize(*args) -> None


   .. py:method:: grow(*args) -> None


   .. py:method:: capacity() -> size_t


   .. py:method:: reserve(cnt: size_t) -> None


   .. py:method:: truncate() -> None


   .. py:method:: swap(r: casevec_t) -> None


   .. py:method:: extract() -> qvector< long long > *


   .. py:method:: inject(s: qvector< long long > *, len: size_t) -> None


   .. py:method:: begin(*args) -> qvector< qvector< long long > >::const_iterator


   .. py:method:: end(*args) -> qvector< qvector< long long > >::const_iterator


   .. py:method:: insert(it: qvector< qvector< long long > >::iterator, x: qvector< long long > const &) -> qvector< qvector< long long > >::iterator


   .. py:method:: erase(*args) -> qvector< qvector< long long > >::iterator


   .. py:method:: find(*args) -> qvector< qvector< long long > >::const_iterator


   .. py:method:: has(x: qvector< long long > const &) -> bool


   .. py:method:: add_unique(x: qvector< long long > const &) -> bool


   .. py:method:: append(x: qvector< long long > const &) -> None


   .. py:method:: extend(x: casevec_t) -> None


   .. py:attribute:: front


   .. py:attribute:: back


.. py:data:: XREF_ALL

.. py:data:: XREF_FAR

