hc
2023-11-06 15ade055295d13f95d49e3d99b09f3bbfb4a43e7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.
 
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.
 
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Selecting Pretty-Printers</title>
 
<meta name="description" content="Debugging with GDB: Selecting Pretty-Printers">
<meta name="keywords" content="Debugging with GDB: Selecting Pretty-Printers">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Python-API.html#Python-API" rel="up" title="Python API">
<link href="Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter" rel="next" title="Writing a Pretty-Printer">
<link href="Pretty-Printing-API.html#Pretty-Printing-API" rel="previous" title="Pretty Printing API">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
 
 
</head>
 
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Selecting-Pretty_002dPrinters"></a>
<div class="header">
<p>
Next: <a href="Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter" accesskey="n" rel="next">Writing a Pretty-Printer</a>, Previous: <a href="Pretty-Printing-API.html#Pretty-Printing-API" accesskey="p" rel="previous">Pretty Printing API</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> &nbsp; [<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>
</div>
<hr>
<a name="Selecting-Pretty_002dPrinters-1"></a>
<h4 class="subsubsection">23.2.2.6 Selecting Pretty-Printers</h4>
<a name="index-selecting-python-pretty_002dprinters"></a>
 
<p><small>GDB</small> provides several ways to register a pretty-printer:
globally, per program space, and per objfile.  When choosing how to
register your pretty-printer, a good rule is to register it with the
smallest scope possible: that is prefer a specific objfile first, then
a program space, and only register a printer globally as a last
resort.
</p>
<a name="index-gdb_002epretty_005fprinters"></a>
<dl>
<dt><a name="index-gdb_002epretty_005fprinters-1"></a>Variable: <strong>gdb.pretty_printers</strong></dt>
<dd><p>The Python list <code>gdb.pretty_printers</code> contains an array of
functions or callable objects that have been registered via addition
as a pretty-printer.  Printers in this list are called <code>global</code>
printers, they&rsquo;re available when debugging all inferiors.
</p></dd></dl>
 
<p>Each <code>gdb.Progspace</code> contains a <code>pretty_printers</code> attribute.
Each <code>gdb.Objfile</code> also contains a <code>pretty_printers</code>
attribute.
</p>
<p>Each function on these lists is passed a single <code>gdb.Value</code>
argument and should return a pretty-printer object conforming to the
interface definition above (see <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>).  If a function
cannot create a pretty-printer for the value, it should return
<code>None</code>.
</p>
<p><small>GDB</small> first checks the <code>pretty_printers</code> attribute of each
<code>gdb.Objfile</code> in the current program space and iteratively calls
each enabled lookup routine in the list for that <code>gdb.Objfile</code>
until it receives a pretty-printer object.
If no pretty-printer is found in the objfile lists, <small>GDB</small> then
searches the pretty-printer list of the current program space,
calling each enabled function until an object is returned.
After these lists have been exhausted, it tries the global
<code>gdb.pretty_printers</code> list, again calling each enabled function until an
object is returned.
</p>
<p>The order in which the objfiles are searched is not specified.  For a
given list, functions are always invoked from the head of the list,
and iterated over sequentially until the end of the list, or a printer
object is returned.
</p>
<p>For various reasons a pretty-printer may not work.
For example, the underlying data structure may have changed and
the pretty-printer is out of date.
</p>
<p>The consequences of a broken pretty-printer are severe enough that
<small>GDB</small> provides support for enabling and disabling individual
printers.  For example, if <code>print frame-arguments</code> is on,
a backtrace can become highly illegible if any argument is printed
with a broken printer.
</p>
<p>Pretty-printers are enabled and disabled by attaching an <code>enabled</code>
attribute to the registered function or callable object.  If this attribute
is present and its value is <code>False</code>, the printer is disabled, otherwise
the printer is enabled.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter" accesskey="n" rel="next">Writing a Pretty-Printer</a>, Previous: <a href="Pretty-Printing-API.html#Pretty-Printing-API" accesskey="p" rel="previous">Pretty Printing API</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> &nbsp; [<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>
</div>
 
 
 
</body>
</html>