1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Xmethod API</title> 18 19<meta name="description" content="Debugging with GDB: Xmethod API"> 20<meta name="keywords" content="Debugging with GDB: Xmethod API"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Python-API.html#Python-API" rel="up" title="Python API"> 29<link href="Writing-an-Xmethod.html#Writing-an-Xmethod" rel="next" title="Writing an Xmethod"> 30<link href="Xmethods-In-Python.html#Xmethods-In-Python" rel="previous" title="Xmethods In Python"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Xmethod-API"></a> 65<div class="header"> 66<p> 67Next: <a href="Writing-an-Xmethod.html#Writing-an-Xmethod" accesskey="n" rel="next">Writing an Xmethod</a>, Previous: <a href="Xmethods-In-Python.html#Xmethods-In-Python" accesskey="p" rel="previous">Xmethods In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Xmethod-API-1"></a> 71<h4 class="subsubsection">23.2.2.14 Xmethod API</h4> 72<a name="index-xmethod-API"></a> 73 74<p>The <small>GDB</small> Python API provides classes, interfaces and functions 75to implement, register and manipulate xmethods. 76See <a href="Xmethods-In-Python.html#Xmethods-In-Python">Xmethods In Python</a>. 77</p> 78<p>An xmethod matcher should be an instance of a class derived from 79<code>XMethodMatcher</code> defined in the module <code>gdb.xmethod</code>, or an 80object with similar interface and attributes. An instance of 81<code>XMethodMatcher</code> has the following attributes: 82</p> 83<dl> 84<dt><a name="index-name"></a>Variable: <strong>name</strong></dt> 85<dd><p>The name of the matcher. 86</p></dd></dl> 87 88<dl> 89<dt><a name="index-enabled"></a>Variable: <strong>enabled</strong></dt> 90<dd><p>A boolean value indicating whether the matcher is enabled or disabled. 91</p></dd></dl> 92 93<dl> 94<dt><a name="index-methods"></a>Variable: <strong>methods</strong></dt> 95<dd><p>A list of named methods managed by the matcher. Each object in the list 96is an instance of the class <code>XMethod</code> defined in the module 97<code>gdb.xmethod</code>, or any object with the following attributes: 98</p> 99<dl compact="compact"> 100<dt><code>name</code></dt> 101<dd><p>Name of the xmethod which should be unique for each xmethod 102managed by the matcher. 103</p> 104</dd> 105<dt><code>enabled</code></dt> 106<dd><p>A boolean value indicating whether the xmethod is enabled or 107disabled. 108</p> 109</dd> 110</dl> 111 112<p>The class <code>XMethod</code> is a convenience class with same 113attributes as above along with the following constructor: 114</p> 115<dl> 116<dt><a name="index-XMethod_002e_005f_005finit_005f_005f"></a>Function: <strong>XMethod.__init__</strong> <em>(self, name)</em></dt> 117<dd><p>Constructs an enabled xmethod with name <var>name</var>. 118</p></dd></dl> 119</dd></dl> 120 121<p>The <code>XMethodMatcher</code> class has the following methods: 122</p> 123<dl> 124<dt><a name="index-XMethodMatcher_002e_005f_005finit_005f_005f"></a>Function: <strong>XMethodMatcher.__init__</strong> <em>(self, name)</em></dt> 125<dd><p>Constructs an enabled xmethod matcher with name <var>name</var>. The 126<code>methods</code> attribute is initialized to <code>None</code>. 127</p></dd></dl> 128 129<dl> 130<dt><a name="index-XMethodMatcher_002ematch"></a>Function: <strong>XMethodMatcher.match</strong> <em>(self, class_type, method_name)</em></dt> 131<dd><p>Derived classes should override this method. It should return a 132xmethod worker object (or a sequence of xmethod worker 133objects) matching the <var>class_type</var> and <var>method_name</var>. 134<var>class_type</var> is a <code>gdb.Type</code> object, and <var>method_name</var> 135is a string value. If the matcher manages named methods as listed in 136its <code>methods</code> attribute, then only those worker objects whose 137corresponding entries in the <code>methods</code> list are enabled should be 138returned. 139</p></dd></dl> 140 141<p>An xmethod worker should be an instance of a class derived from 142<code>XMethodWorker</code> defined in the module <code>gdb.xmethod</code>, 143or support the following interface: 144</p> 145<dl> 146<dt><a name="index-XMethodWorker_002eget_005farg_005ftypes"></a>Function: <strong>XMethodWorker.get_arg_types</strong> <em>(self)</em></dt> 147<dd><p>This method returns a sequence of <code>gdb.Type</code> objects corresponding 148to the arguments that the xmethod takes. It can return an empty 149sequence or <code>None</code> if the xmethod does not take any arguments. 150If the xmethod takes a single argument, then a single 151<code>gdb.Type</code> object corresponding to it can be returned. 152</p></dd></dl> 153 154<dl> 155<dt><a name="index-XMethodWorker_002eget_005fresult_005ftype"></a>Function: <strong>XMethodWorker.get_result_type</strong> <em>(self, *args)</em></dt> 156<dd><p>This method returns a <code>gdb.Type</code> object representing the type 157of the result of invoking this xmethod. 158The <var>args</var> argument is the same tuple of arguments that would be 159passed to the <code>__call__</code> method of this worker. 160</p></dd></dl> 161 162<dl> 163<dt><a name="index-XMethodWorker_002e_005f_005fcall_005f_005f"></a>Function: <strong>XMethodWorker.__call__</strong> <em>(self, *args)</em></dt> 164<dd><p>This is the method which does the <em>work</em> of the xmethod. The 165<var>args</var> arguments is the tuple of arguments to the xmethod. Each 166element in this tuple is a gdb.Value object. The first element is 167always the <code>this</code> pointer value. 168</p></dd></dl> 169 170<p>For <small>GDB</small> to lookup xmethods, the xmethod matchers 171should be registered using the following function defined in the module 172<code>gdb.xmethod</code>: 173</p> 174<dl> 175<dt><a name="index-register_005fxmethod_005fmatcher"></a>Function: <strong>register_xmethod_matcher</strong> <em>(locus, matcher, replace=False)</em></dt> 176<dd><p>The <code>matcher</code> is registered with <code>locus</code>, replacing an 177existing matcher with the same name as <code>matcher</code> if 178<code>replace</code> is <code>True</code>. <code>locus</code> can be a 179<code>gdb.Objfile</code> object (see <a href="Objfiles-In-Python.html#Objfiles-In-Python">Objfiles In Python</a>), or a 180<code>gdb.Progspace</code> object (see <a href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>), or 181<code>None</code>. If it is <code>None</code>, then <code>matcher</code> is registered 182globally. 183</p></dd></dl> 184 185<hr> 186<div class="header"> 187<p> 188Next: <a href="Writing-an-Xmethod.html#Writing-an-Xmethod" accesskey="n" rel="next">Writing an Xmethod</a>, Previous: <a href="Xmethods-In-Python.html#Xmethods-In-Python" accesskey="p" rel="previous">Xmethods In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 189</div> 190 191 192 193</body> 194</html> 195