aarch64-linux-gnu-9.2/share/doc/gdb/Basic-Python.html - toolchains/linux-x86/gcc - Git at Google

 <html lang="en">
 <head>
 <title>Basic Python - Debugging with GDB</title>
 <meta http-equiv="Content-Type" content="text/html">
 <meta name="description" content="Debugging with GDB">
 <meta name="generator" content="makeinfo 4.13">
 <link title="Top" rel="start" href="index.html#Top">
 <link rel="up" href="Python-API.html#Python-API" title="Python API">
 <link rel="next" href="Exception-Handling.html#Exception-Handling" title="Exception Handling">
 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
 <!--
 Copyright (C) 1988-2019 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.''
 -->
 <meta http-equiv="Content-Style-Type" content="text/css">
 <style type="text/css"><!--
   pre.display { font-family:inherit }
   pre.format  { font-family:inherit }
   pre.smalldisplay { font-family:inherit; font-size:smaller }
   pre.smallformat  { font-family:inherit; font-size:smaller }
   pre.smallexample { font-size:smaller }
   pre.smalllisp    { font-size:smaller }
   span.sc    { font-variant:small-caps }
   span.roman { font-family:serif; font-weight:normal; }
   span.sansserif { font-family:sans-serif; font-weight:normal; }
 --></style>
 </head>
 <body>
 <div class="node">
 <a name="Basic-Python"></a>
 <p>
 Next:&nbsp;<a rel="next" accesskey="n" href="Exception-Handling.html#Exception-Handling">Exception Handling</a>,
 Up:&nbsp;<a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a>
 <hr>
 </div>

 <h5 class="subsubsection">23.2.2.1 Basic Python</h5>

 <p><a name="index-python-stdout-1848"></a><a name="index-python-pagination-1849"></a>At startup, <span class="sc">gdb</span> overrides Python's <code>sys.stdout</code> and
 <code>sys.stderr</code> to print using <span class="sc">gdb</span>'s output-paging streams.
 A Python program which outputs to one of these streams may have its
 output interrupted by the user (see <a href="Screen-Size.html#Screen-Size">Screen Size</a>).  In this
 situation, a Python <code>KeyboardInterrupt</code> exception is thrown.

    <p>Some care must be taken when writing Python code to run in
 <span class="sc">gdb</span>.  Two things worth noting in particular:

      <ul>
 <li><span class="sc">gdb</span> install handlers for <code>SIGCHLD</code> and <code>SIGINT</code>.
 Python code must not override these, or even change the options using
 <code>sigaction</code>.  If your program changes the handling of these
 signals, <span class="sc">gdb</span> will most likely stop working correctly.  Note
 that it is unfortunately common for GUI toolkits to install a
 <code>SIGCHLD</code> handler.

      <li><span class="sc">gdb</span> takes care to mark its internal file descriptors as
 close-on-exec.  However, this cannot be done in a thread-safe way on
 all platforms.  Your Python programs should be aware of this and
 should both create new file descriptors with the close-on-exec flag
 set and arrange to close unneeded file descriptors before starting a
 child process.
 </ul>

    <p><a name="index-python-functions-1850"></a><a name="index-python-module-1851"></a><a name="index-gdb-module-1852"></a><span class="sc">gdb</span> introduces a new Python module, named <code>gdb</code>.  All
 methods and classes added by <span class="sc">gdb</span> are placed in this module.
 <span class="sc">gdb</span> automatically <code>import</code>s the <code>gdb</code> module for
 use in all scripts evaluated by the <code>python</code> command.

    <p>Some types of the <code>gdb</code> module come with a textual representation
 (accessible through the <code>repr</code> or <code>str</code> functions).  These are
 offered for debugging purposes only, expect them to change over time.

    <p><a name="index-gdb_002ePYTHONDIR-1853"></a>

 <div class="defun">
 &mdash; Variable: <b>gdb.PYTHONDIR</b><var><a name="index-gdb_002ePYTHONDIR-1854"></a></var><br>
 <blockquote><p>A string containing the python directory (see <a href="Python.html#Python">Python</a>).
 </p></blockquote></div>

    <p><a name="index-gdb_002eexecute-1855"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.execute</b> (<var>command </var><span class="roman">[</span><var>, from_tty </var><span class="roman">[</span><var>, to_string</var><span class="roman">]]</span>)<var><a name="index-gdb_002eexecute-1856"></a></var><br>
 <blockquote><p>Evaluate <var>command</var>, a string, as a <span class="sc">gdb</span> CLI command.
 If a GDB exception happens while <var>command</var> runs, it is
 translated as described in <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>.

         <p>The <var>from_tty</var> flag specifies whether <span class="sc">gdb</span> ought to consider this
 command as having originated from the user invoking it interactively.
 It must be a boolean value.  If omitted, it defaults to <code>False</code>.

         <p>By default, any output produced by <var>command</var> is sent to
 <span class="sc">gdb</span>'s standard output (and to the log output if logging is
 turned on).  If the <var>to_string</var> parameter is
 <code>True</code>, then output will be collected by <code>gdb.execute</code> and
 returned as a string.  The default is <code>False</code>, in which case the
 return value is <code>None</code>.  If <var>to_string</var> is <code>True</code>, the
 <span class="sc">gdb</span> virtual terminal will be temporarily set to unlimited width
 and height, and its pagination will be disabled; see <a href="Screen-Size.html#Screen-Size">Screen Size</a>.
 </p></blockquote></div>

    <p><a name="index-gdb_002ebreakpoints-1857"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.breakpoints</b> ()<var><a name="index-gdb_002ebreakpoints-1858"></a></var><br>
 <blockquote><p>Return a sequence holding all of <span class="sc">gdb</span>'s breakpoints.
 See <a href="Breakpoints-In-Python.html#Breakpoints-In-Python">Breakpoints In Python</a>, for more information.  In <span class="sc">gdb</span>
 version 7.11 and earlier, this function returned <code>None</code> if there
 were no breakpoints.  This peculiarity was subsequently fixed, and now
 <code>gdb.breakpoints</code> returns an empty sequence in this case.
 </p></blockquote></div>

 <div class="defun">
 &mdash; Function: <b>gdb.rbreak</b> (<var>regex </var><span class="roman">[</span><var>, minsyms </var><span class="roman">[</span><var>, throttle, </var><span class="roman">[</span><var>, symtabs </var><span class="roman">]]]</span>)<var><a name="index-gdb_002erbreak-1859"></a></var><br>
 <blockquote><p>Return a Python list holding a collection of newly set
 <code>gdb.Breakpoint</code> objects matching function names defined by the
 <var>regex</var> pattern.  If the <var>minsyms</var> keyword is <code>True</code>, all
 system functions (those not explicitly defined in the inferior) will
 also be included in the match.  The <var>throttle</var> keyword takes an
 integer that defines the maximum number of pattern matches for
 functions matched by the <var>regex</var> pattern.  If the number of
 matches exceeds the integer value of <var>throttle</var>, a
 <code>RuntimeError</code> will be raised and no breakpoints will be created.
 If <var>throttle</var> is not defined then there is no imposed limit on the
 maximum number of matches and breakpoints to be created.  The
 <var>symtabs</var> keyword takes a Python iterable that yields a collection
 of <code>gdb.Symtab</code> objects and will restrict the search to those
 functions only contained within the <code>gdb.Symtab</code> objects.
 </p></blockquote></div>

    <p><a name="index-gdb_002eparameter-1860"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.parameter</b> (<var>parameter</var>)<var><a name="index-gdb_002eparameter-1861"></a></var><br>
 <blockquote><p>Return the value of a <span class="sc">gdb</span> <var>parameter</var> given by its name,
 a string; the parameter name string may contain spaces if the parameter has a
 multi-part name.  For example, &lsquo;<samp><span class="samp">print object</span></samp>&rsquo; is a valid
 parameter name.

         <p>If the named parameter does not exist, this function throws a
 <code>gdb.error</code> (see <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>).  Otherwise, the
 parameter's value is converted to a Python value of the appropriate
 type, and returned.
 </p></blockquote></div>

    <p><a name="index-gdb_002ehistory-1862"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.history</b> (<var>number</var>)<var><a name="index-gdb_002ehistory-1863"></a></var><br>
 <blockquote><p>Return a value from <span class="sc">gdb</span>'s value history (see <a href="Value-History.html#Value-History">Value History</a>).  The <var>number</var> argument indicates which history element to return.
 If <var>number</var> is negative, then <span class="sc">gdb</span> will take its absolute value
 and count backward from the last element (i.e., the most recent element) to
 find the value to return.  If <var>number</var> is zero, then <span class="sc">gdb</span> will
 return the most recent element.  If the element specified by <var>number</var>
 doesn't exist in the value history, a <code>gdb.error</code> exception will be
 raised.

         <p>If no exception is raised, the return value is always an instance of
 <code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>).
 </p></blockquote></div>

    <p><a name="index-gdb_002econvenience_005fvariable-1864"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.convenience_variable</b> (<var>name</var>)<var><a name="index-gdb_002econvenience_005fvariable-1865"></a></var><br>
 <blockquote><p>Return the value of the convenience variable (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>) named <var>name</var>.  <var>name</var> must be a string.  The name
 should not include the &lsquo;<samp><span class="samp">$</span></samp>&rsquo; that is used to mark a convenience
 variable in an expression.  If the convenience variable does not
 exist, then <code>None</code> is returned.
 </p></blockquote></div>

    <p><a name="index-gdb_002eset_005fconvenience_005fvariable-1866"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.set_convenience_variable</b> (<var>name, value</var>)<var><a name="index-gdb_002eset_005fconvenience_005fvariable-1867"></a></var><br>
 <blockquote><p>Set the value of the convenience variable (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>)
 named <var>name</var>.  <var>name</var> must be a string.  The name should not
 include the &lsquo;<samp><span class="samp">$</span></samp>&rsquo; that is used to mark a convenience variable in an
 expression.  If <var>value</var> is <code>None</code>, then the convenience
 variable is removed.  Otherwise, if <var>value</var> is not a
 <code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>), it is is converted
 using the <code>gdb.Value</code> constructor.
 </p></blockquote></div>

    <p><a name="index-gdb_002eparse_005fand_005feval-1868"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.parse_and_eval</b> (<var>expression</var>)<var><a name="index-gdb_002eparse_005fand_005feval-1869"></a></var><br>
 <blockquote><p>Parse <var>expression</var>, which must be a string, as an expression in
 the current language, evaluate it, and return the result as a
 <code>gdb.Value</code>.

         <p>This function can be useful when implementing a new command
 (see <a href="Commands-In-Python.html#Commands-In-Python">Commands In Python</a>), as it provides a way to parse the
 command's argument as an expression.  It is also useful simply to
 compute values.
 </p></blockquote></div>

    <p><a name="index-gdb_002efind_005fpc_005fline-1870"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.find_pc_line</b> (<var>pc</var>)<var><a name="index-gdb_002efind_005fpc_005fline-1871"></a></var><br>
 <blockquote><p>Return the <code>gdb.Symtab_and_line</code> object corresponding to the
 <var>pc</var> value.  See <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>.  If an invalid
 value of <var>pc</var> is passed as an argument, then the <code>symtab</code> and
 <code>line</code> attributes of the returned <code>gdb.Symtab_and_line</code> object
 will be <code>None</code> and 0 respectively.  This is identical to
 <code>gdb.current_progspace().find_pc_line(pc)</code> and is included for
 historical compatibility.
 </p></blockquote></div>

    <p><a name="index-gdb_002epost_005fevent-1872"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.post_event</b> (<var>event</var>)<var><a name="index-gdb_002epost_005fevent-1873"></a></var><br>
 <blockquote><p>Put <var>event</var>, a callable object taking no arguments, into
 <span class="sc">gdb</span>'s internal event queue.  This callable will be invoked at
 some later point, during <span class="sc">gdb</span>'s event processing.  Events
 posted using <code>post_event</code> will be run in the order in which they
 were posted; however, there is no way to know when they will be
 processed relative to other events inside <span class="sc">gdb</span>.

         <p><span class="sc">gdb</span> is not thread-safe.  If your Python program uses multiple
 threads, you must be careful to only call <span class="sc">gdb</span>-specific
 functions in the <span class="sc">gdb</span> thread.  <code>post_event</code> ensures
 this.  For example:

      <pre class="smallexample">          (gdb) python
           &gt;import threading
           &gt;
           &gt;class Writer():
           &gt; def __init__(self, message):
           &gt;        self.message = message;
           &gt; def __call__(self):
           &gt;        gdb.write(self.message)
           &gt;
           &gt;class MyThread1 (threading.Thread):
           &gt; def run (self):
           &gt;        gdb.post_event(Writer("Hello "))
           &gt;
           &gt;class MyThread2 (threading.Thread):
           &gt; def run (self):
           &gt;        gdb.post_event(Writer("World\n"))
           &gt;
           &gt;MyThread1().start()
           &gt;MyThread2().start()
           &gt;end
           (gdb) Hello World
 </pre>
         </blockquote></div>

    <p><a name="index-gdb_002ewrite-1874"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.write</b> (<var>string </var><span class="roman">[</span><var>, stream</var>])<var><a name="index-gdb_002ewrite-1875"></a></var><br>
 <blockquote><p>Print a string to <span class="sc">gdb</span>'s paginated output stream.  The
 optional <var>stream</var> determines the stream to print to.  The default
 stream is <span class="sc">gdb</span>'s standard output stream.  Possible stream
 values are:


 <a name="index-STDOUT-1876"></a>
 <a name="index-gdb_002eSTDOUT-1877"></a>
 <dl><dt><code>gdb.STDOUT</code><dd><span class="sc">gdb</span>'s standard output stream.

           <p><a name="index-STDERR-1878"></a><a name="index-gdb_002eSTDERR-1879"></a><br><dt><code>gdb.STDERR</code><dd><span class="sc">gdb</span>'s standard error stream.

           <p><a name="index-STDLOG-1880"></a><a name="index-gdb_002eSTDLOG-1881"></a><br><dt><code>gdb.STDLOG</code><dd><span class="sc">gdb</span>'s log stream (see <a href="Logging-Output.html#Logging-Output">Logging Output</a>).
 </dl>

         <p>Writing to <code>sys.stdout</code> or <code>sys.stderr</code> will automatically
 call this function and will automatically direct the output to the
 relevant stream.
 </p></blockquote></div>

    <p><a name="index-gdb_002eflush-1882"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.flush</b> ()<var><a name="index-gdb_002eflush-1883"></a></var><br>
 <blockquote><p>Flush the buffer of a <span class="sc">gdb</span> paginated stream so that the
 contents are displayed immediately.  <span class="sc">gdb</span> will flush the
 contents of a stream automatically when it encounters a newline in the
 buffer.  The optional <var>stream</var> determines the stream to flush.  The
 default stream is <span class="sc">gdb</span>'s standard output stream.  Possible
 stream values are:


 <a name="index-STDOUT-1884"></a>
 <a name="index-gdb_002eSTDOUT-1885"></a>
 <dl><dt><code>gdb.STDOUT</code><dd><span class="sc">gdb</span>'s standard output stream.

           <p><a name="index-STDERR-1886"></a><a name="index-gdb_002eSTDERR-1887"></a><br><dt><code>gdb.STDERR</code><dd><span class="sc">gdb</span>'s standard error stream.

           <p><a name="index-STDLOG-1888"></a><a name="index-gdb_002eSTDLOG-1889"></a><br><dt><code>gdb.STDLOG</code><dd><span class="sc">gdb</span>'s log stream (see <a href="Logging-Output.html#Logging-Output">Logging Output</a>).

         </dl>

         <p>Flushing <code>sys.stdout</code> or <code>sys.stderr</code> will automatically
 call this function for the relevant stream.
 </p></blockquote></div>

    <p><a name="index-gdb_002etarget_005fcharset-1890"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.target_charset</b> ()<var><a name="index-gdb_002etarget_005fcharset-1891"></a></var><br>
 <blockquote><p>Return the name of the current target character set (see <a href="Character-Sets.html#Character-Sets">Character Sets</a>).  This differs from <code>gdb.parameter('target-charset')</code> in
 that &lsquo;<samp><span class="samp">auto</span></samp>&rsquo; is never returned.
 </p></blockquote></div>

    <p><a name="index-gdb_002etarget_005fwide_005fcharset-1892"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.target_wide_charset</b> ()<var><a name="index-gdb_002etarget_005fwide_005fcharset-1893"></a></var><br>
 <blockquote><p>Return the name of the current target wide character set
 (see <a href="Character-Sets.html#Character-Sets">Character Sets</a>).  This differs from
 <code>gdb.parameter('target-wide-charset')</code> in that &lsquo;<samp><span class="samp">auto</span></samp>&rsquo; is
 never returned.
 </p></blockquote></div>

    <p><a name="index-gdb_002esolib_005fname-1894"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.solib_name</b> (<var>address</var>)<var><a name="index-gdb_002esolib_005fname-1895"></a></var><br>
 <blockquote><p>Return the name of the shared library holding the given <var>address</var>
 as a string, or <code>None</code>.  This is identical to
 <code>gdb.current_progspace().solib_name(address)</code> and is included for
 historical compatibility.
 </p></blockquote></div>

    <p><a name="index-gdb_002edecode_005fline-1896"></a>

 <div class="defun">
 &mdash; Function: <b>gdb.decode_line</b> (<span class="roman">[</span><var>expression</var><span class="roman">]</span>)<var><a name="index-gdb_002edecode_005fline-1897"></a></var><br>
 <blockquote><p>Return locations of the line specified by <var>expression</var>, or of the
 current line if no argument was given.  This function returns a Python
 tuple containing two elements.  The first element contains a string
 holding any unparsed section of <var>expression</var> (or <code>None</code> if
 the expression has been fully parsed).  The second element contains
 either <code>None</code> or another tuple that contains all the locations
 that match the expression represented as <code>gdb.Symtab_and_line</code>
 objects (see <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>).  If <var>expression</var> is
 provided, it is decoded the way that <span class="sc">gdb</span>'s inbuilt
 <code>break</code> or <code>edit</code> commands do (see <a href="Specify-Location.html#Specify-Location">Specify Location</a>).
 </p></blockquote></div>

 <div class="defun">
 &mdash; Function: <b>gdb.prompt_hook</b> (<var>current_prompt</var>)<var><a name="index-gdb_002eprompt_005fhook-1898"></a></var><br>
 <blockquote><p><a name="prompt_005fhook"></a>If <var>prompt_hook</var> is callable, <span class="sc">gdb</span> will call the method
 assigned to this operation before a prompt is displayed by
 <span class="sc">gdb</span>.

         <p>The parameter <code>current_prompt</code> contains the current <span class="sc">gdb</span>
 prompt.  This method must return a Python string, or <code>None</code>.  If
 a string is returned, the <span class="sc">gdb</span> prompt will be set to that
 string.  If <code>None</code> is returned, <span class="sc">gdb</span> will continue to use
 the current prompt.

         <p>Some prompts cannot be substituted in <span class="sc">gdb</span>.  Secondary prompts
 such as those used by readline for command input, and annotation
 related prompts are prohibited from being changed.
 </p></blockquote></div>

    </body></html>
	<html lang="en">
	<head>
	<title>Basic Python - Debugging with GDB</title>
	<meta http-equiv="Content-Type" content="text/html">
	<meta name="description" content="Debugging with GDB">
	<meta name="generator" content="makeinfo 4.13">
	<link title="Top" rel="start" href="index.html#Top">
	<link rel="up" href="Python-API.html#Python-API" title="Python API">
	<link rel="next" href="Exception-Handling.html#Exception-Handling" title="Exception Handling">
	<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
	<!--
	Copyright (C) 1988-2019 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.''
	-->
	<meta http-equiv="Content-Style-Type" content="text/css">
	<style type="text/css"><!--
	pre.display { font-family:inherit }
	pre.format { font-family:inherit }
	pre.smalldisplay { font-family:inherit; font-size:smaller }
	pre.smallformat { font-family:inherit; font-size:smaller }
	pre.smallexample { font-size:smaller }
	pre.smalllisp { font-size:smaller }
	span.sc { font-variant:small-caps }
	span.roman { font-family:serif; font-weight:normal; }
	span.sansserif { font-family:sans-serif; font-weight:normal; }
	--></style>
	</head>
	<body>
	<div class="node">
	<a name="Basic-Python"></a>
	<p>
	Next: <a rel="next" accesskey="n" href="Exception-Handling.html#Exception-Handling">Exception Handling</a>,
	Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a>
	<hr>
	</div>

	<h5 class="subsubsection">23.2.2.1 Basic Python</h5>

	<p><a name="index-python-stdout-1848"></a><a name="index-python-pagination-1849"></a>At startup, <span class="sc">gdb</span> overrides Python's <code>sys.stdout</code> and
	<code>sys.stderr</code> to print using <span class="sc">gdb</span>'s output-paging streams.
	A Python program which outputs to one of these streams may have its
	output interrupted by the user (see <a href="Screen-Size.html#Screen-Size">Screen Size</a>). In this
	situation, a Python <code>KeyboardInterrupt</code> exception is thrown.

	<p>Some care must be taken when writing Python code to run in
	<span class="sc">gdb</span>. Two things worth noting in particular:

	<ul>
	<li><span class="sc">gdb</span> install handlers for <code>SIGCHLD</code> and <code>SIGINT</code>.
	Python code must not override these, or even change the options using
	<code>sigaction</code>. If your program changes the handling of these
	signals, <span class="sc">gdb</span> will most likely stop working correctly. Note
	that it is unfortunately common for GUI toolkits to install a
	<code>SIGCHLD</code> handler.

	<li><span class="sc">gdb</span> takes care to mark its internal file descriptors as
	close-on-exec. However, this cannot be done in a thread-safe way on
	all platforms. Your Python programs should be aware of this and
	should both create new file descriptors with the close-on-exec flag
	set and arrange to close unneeded file descriptors before starting a
	child process.
	</ul>

	<p><a name="index-python-functions-1850"></a><a name="index-python-module-1851"></a><a name="index-gdb-module-1852"></a><span class="sc">gdb</span> introduces a new Python module, named <code>gdb</code>. All
	methods and classes added by <span class="sc">gdb</span> are placed in this module.
	<span class="sc">gdb</span> automatically <code>import</code>s the <code>gdb</code> module for
	use in all scripts evaluated by the <code>python</code> command.

	<p>Some types of the <code>gdb</code> module come with a textual representation
	(accessible through the <code>repr</code> or <code>str</code> functions). These are
	offered for debugging purposes only, expect them to change over time.

	<p><a name="index-gdb_002ePYTHONDIR-1853"></a>

	<div class="defun">
	— Variable: <b>gdb.PYTHONDIR</b><var><a name="index-gdb_002ePYTHONDIR-1854"></a></var><br>
	<blockquote><p>A string containing the python directory (see <a href="Python.html#Python">Python</a>).
	</p></blockquote></div>

	<p><a name="index-gdb_002eexecute-1855"></a>

	<div class="defun">
	— Function: <b>gdb.execute</b> (<var>command </var><span class="roman">[</span><var>, from_tty </var><span class="roman">[</span><var>, to_string</var><span class="roman">]]</span>)<var><a name="index-gdb_002eexecute-1856"></a></var><br>
	<blockquote><p>Evaluate <var>command</var>, a string, as a <span class="sc">gdb</span> CLI command.
	If a GDB exception happens while <var>command</var> runs, it is
	translated as described in <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>.

	<p>The <var>from_tty</var> flag specifies whether <span class="sc">gdb</span> ought to consider this
	command as having originated from the user invoking it interactively.
	It must be a boolean value. If omitted, it defaults to <code>False</code>.

	<p>By default, any output produced by <var>command</var> is sent to
	<span class="sc">gdb</span>'s standard output (and to the log output if logging is
	turned on). If the <var>to_string</var> parameter is
	<code>True</code>, then output will be collected by <code>gdb.execute</code> and
	returned as a string. The default is <code>False</code>, in which case the
	return value is <code>None</code>. If <var>to_string</var> is <code>True</code>, the
	<span class="sc">gdb</span> virtual terminal will be temporarily set to unlimited width
	and height, and its pagination will be disabled; see <a href="Screen-Size.html#Screen-Size">Screen Size</a>.
	</p></blockquote></div>

	<p><a name="index-gdb_002ebreakpoints-1857"></a>

	<div class="defun">
	— Function: <b>gdb.breakpoints</b> ()<var><a name="index-gdb_002ebreakpoints-1858"></a></var><br>
	<blockquote><p>Return a sequence holding all of <span class="sc">gdb</span>'s breakpoints.
	See <a href="Breakpoints-In-Python.html#Breakpoints-In-Python">Breakpoints In Python</a>, for more information. In <span class="sc">gdb</span>
	version 7.11 and earlier, this function returned <code>None</code> if there
	were no breakpoints. This peculiarity was subsequently fixed, and now
	<code>gdb.breakpoints</code> returns an empty sequence in this case.
	</p></blockquote></div>

	<div class="defun">
	— Function: <b>gdb.rbreak</b> (<var>regex </var><span class="roman">[</span><var>, minsyms </var><span class="roman">[</span><var>, throttle, </var><span class="roman">[</span><var>, symtabs </var><span class="roman">]]]</span>)<var><a name="index-gdb_002erbreak-1859"></a></var><br>
	<blockquote><p>Return a Python list holding a collection of newly set
	<code>gdb.Breakpoint</code> objects matching function names defined by the
	<var>regex</var> pattern. If the <var>minsyms</var> keyword is <code>True</code>, all
	system functions (those not explicitly defined in the inferior) will
	also be included in the match. The <var>throttle</var> keyword takes an
	integer that defines the maximum number of pattern matches for
	functions matched by the <var>regex</var> pattern. If the number of
	matches exceeds the integer value of <var>throttle</var>, a
	<code>RuntimeError</code> will be raised and no breakpoints will be created.
	If <var>throttle</var> is not defined then there is no imposed limit on the
	maximum number of matches and breakpoints to be created. The
	<var>symtabs</var> keyword takes a Python iterable that yields a collection
	of <code>gdb.Symtab</code> objects and will restrict the search to those
	functions only contained within the <code>gdb.Symtab</code> objects.
	</p></blockquote></div>

	<p><a name="index-gdb_002eparameter-1860"></a>

	<div class="defun">
	— Function: <b>gdb.parameter</b> (<var>parameter</var>)<var><a name="index-gdb_002eparameter-1861"></a></var><br>
	<blockquote><p>Return the value of a <span class="sc">gdb</span> <var>parameter</var> given by its name,
	a string; the parameter name string may contain spaces if the parameter has a
	multi-part name. For example, ‘<samp><span class="samp">print object</span></samp>’ is a valid
	parameter name.

	<p>If the named parameter does not exist, this function throws a
	<code>gdb.error</code> (see <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>). Otherwise, the
	parameter's value is converted to a Python value of the appropriate
	type, and returned.
	</p></blockquote></div>

	<p><a name="index-gdb_002ehistory-1862"></a>

	<div class="defun">
	— Function: <b>gdb.history</b> (<var>number</var>)<var><a name="index-gdb_002ehistory-1863"></a></var><br>
	<blockquote><p>Return a value from <span class="sc">gdb</span>'s value history (see <a href="Value-History.html#Value-History">Value History</a>). The <var>number</var> argument indicates which history element to return.
	If <var>number</var> is negative, then <span class="sc">gdb</span> will take its absolute value
	and count backward from the last element (i.e., the most recent element) to
	find the value to return. If <var>number</var> is zero, then <span class="sc">gdb</span> will
	return the most recent element. If the element specified by <var>number</var>
	doesn't exist in the value history, a <code>gdb.error</code> exception will be
	raised.

	<p>If no exception is raised, the return value is always an instance of
	<code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>).
	</p></blockquote></div>

	<p><a name="index-gdb_002econvenience_005fvariable-1864"></a>

	<div class="defun">
	— Function: <b>gdb.convenience_variable</b> (<var>name</var>)<var><a name="index-gdb_002econvenience_005fvariable-1865"></a></var><br>
	<blockquote><p>Return the value of the convenience variable (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>) named <var>name</var>. <var>name</var> must be a string. The name
	should not include the ‘<samp><span class="samp">$</span></samp>’ that is used to mark a convenience
	variable in an expression. If the convenience variable does not
	exist, then <code>None</code> is returned.
	</p></blockquote></div>

	<p><a name="index-gdb_002eset_005fconvenience_005fvariable-1866"></a>

	<div class="defun">
	— Function: <b>gdb.set_convenience_variable</b> (<var>name, value</var>)<var><a name="index-gdb_002eset_005fconvenience_005fvariable-1867"></a></var><br>
	<blockquote><p>Set the value of the convenience variable (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>)
	named <var>name</var>. <var>name</var> must be a string. The name should not
	include the ‘<samp><span class="samp">$</span></samp>’ that is used to mark a convenience variable in an
	expression. If <var>value</var> is <code>None</code>, then the convenience
	variable is removed. Otherwise, if <var>value</var> is not a
	<code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>), it is is converted
	using the <code>gdb.Value</code> constructor.
	</p></blockquote></div>

	<p><a name="index-gdb_002eparse_005fand_005feval-1868"></a>

	<div class="defun">
	— Function: <b>gdb.parse_and_eval</b> (<var>expression</var>)<var><a name="index-gdb_002eparse_005fand_005feval-1869"></a></var><br>
	<blockquote><p>Parse <var>expression</var>, which must be a string, as an expression in
	the current language, evaluate it, and return the result as a
	<code>gdb.Value</code>.

	<p>This function can be useful when implementing a new command
	(see <a href="Commands-In-Python.html#Commands-In-Python">Commands In Python</a>), as it provides a way to parse the
	command's argument as an expression. It is also useful simply to
	compute values.
	</p></blockquote></div>

	<p><a name="index-gdb_002efind_005fpc_005fline-1870"></a>

	<div class="defun">
	— Function: <b>gdb.find_pc_line</b> (<var>pc</var>)<var><a name="index-gdb_002efind_005fpc_005fline-1871"></a></var><br>
	<blockquote><p>Return the <code>gdb.Symtab_and_line</code> object corresponding to the
	<var>pc</var> value. See <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>. If an invalid
	value of <var>pc</var> is passed as an argument, then the <code>symtab</code> and
	<code>line</code> attributes of the returned <code>gdb.Symtab_and_line</code> object
	will be <code>None</code> and 0 respectively. This is identical to
	<code>gdb.current_progspace().find_pc_line(pc)</code> and is included for
	historical compatibility.
	</p></blockquote></div>

	<p><a name="index-gdb_002epost_005fevent-1872"></a>

	<div class="defun">
	— Function: <b>gdb.post_event</b> (<var>event</var>)<var><a name="index-gdb_002epost_005fevent-1873"></a></var><br>
	<blockquote><p>Put <var>event</var>, a callable object taking no arguments, into
	<span class="sc">gdb</span>'s internal event queue. This callable will be invoked at
	some later point, during <span class="sc">gdb</span>'s event processing. Events
	posted using <code>post_event</code> will be run in the order in which they
	were posted; however, there is no way to know when they will be
	processed relative to other events inside <span class="sc">gdb</span>.

	<p><span class="sc">gdb</span> is not thread-safe. If your Python program uses multiple
	threads, you must be careful to only call <span class="sc">gdb</span>-specific
	functions in the <span class="sc">gdb</span> thread. <code>post_event</code> ensures
	this. For example:

	<pre class="smallexample"> (gdb) python
	>import threading
	>
	>class Writer():
	> def __init__(self, message):
	> self.message = message;
	> def __call__(self):
	> gdb.write(self.message)
	>
	>class MyThread1 (threading.Thread):
	> def run (self):
	> gdb.post_event(Writer("Hello "))
	>
	>class MyThread2 (threading.Thread):
	> def run (self):
	> gdb.post_event(Writer("World\n"))
	>
	>MyThread1().start()
	>MyThread2().start()
	>end
	(gdb) Hello World
	</pre>
	</blockquote></div>

	<p><a name="index-gdb_002ewrite-1874"></a>

	<div class="defun">
	— Function: <b>gdb.write</b> (<var>string </var><span class="roman">[</span><var>, stream</var>])<var><a name="index-gdb_002ewrite-1875"></a></var><br>
	<blockquote><p>Print a string to <span class="sc">gdb</span>'s paginated output stream. The
	optional <var>stream</var> determines the stream to print to. The default
	stream is <span class="sc">gdb</span>'s standard output stream. Possible stream
	values are:


	<a name="index-STDOUT-1876"></a>
	<a name="index-gdb_002eSTDOUT-1877"></a>
	<dl><dt><code>gdb.STDOUT</code><dd><span class="sc">gdb</span>'s standard output stream.

	<p><a name="index-STDERR-1878"></a><a name="index-gdb_002eSTDERR-1879"></a><br><dt><code>gdb.STDERR</code><dd><span class="sc">gdb</span>'s standard error stream.

	<p><a name="index-STDLOG-1880"></a><a name="index-gdb_002eSTDLOG-1881"></a><br><dt><code>gdb.STDLOG</code><dd><span class="sc">gdb</span>'s log stream (see <a href="Logging-Output.html#Logging-Output">Logging Output</a>).
	</dl>

	<p>Writing to <code>sys.stdout</code> or <code>sys.stderr</code> will automatically
	call this function and will automatically direct the output to the
	relevant stream.
	</p></blockquote></div>

	<p><a name="index-gdb_002eflush-1882"></a>

	<div class="defun">
	— Function: <b>gdb.flush</b> ()<var><a name="index-gdb_002eflush-1883"></a></var><br>
	<blockquote><p>Flush the buffer of a <span class="sc">gdb</span> paginated stream so that the
	contents are displayed immediately. <span class="sc">gdb</span> will flush the
	contents of a stream automatically when it encounters a newline in the
	buffer. The optional <var>stream</var> determines the stream to flush. The
	default stream is <span class="sc">gdb</span>'s standard output stream. Possible
	stream values are:


	<a name="index-STDOUT-1884"></a>
	<a name="index-gdb_002eSTDOUT-1885"></a>
	<dl><dt><code>gdb.STDOUT</code><dd><span class="sc">gdb</span>'s standard output stream.

	<p><a name="index-STDERR-1886"></a><a name="index-gdb_002eSTDERR-1887"></a><br><dt><code>gdb.STDERR</code><dd><span class="sc">gdb</span>'s standard error stream.

	<p><a name="index-STDLOG-1888"></a><a name="index-gdb_002eSTDLOG-1889"></a><br><dt><code>gdb.STDLOG</code><dd><span class="sc">gdb</span>'s log stream (see <a href="Logging-Output.html#Logging-Output">Logging Output</a>).

	</dl>

	<p>Flushing <code>sys.stdout</code> or <code>sys.stderr</code> will automatically
	call this function for the relevant stream.
	</p></blockquote></div>

	<p><a name="index-gdb_002etarget_005fcharset-1890"></a>

	<div class="defun">
	— Function: <b>gdb.target_charset</b> ()<var><a name="index-gdb_002etarget_005fcharset-1891"></a></var><br>
	<blockquote><p>Return the name of the current target character set (see <a href="Character-Sets.html#Character-Sets">Character Sets</a>). This differs from <code>gdb.parameter('target-charset')</code> in
	that ‘<samp><span class="samp">auto</span></samp>’ is never returned.
	</p></blockquote></div>

	<p><a name="index-gdb_002etarget_005fwide_005fcharset-1892"></a>

	<div class="defun">
	— Function: <b>gdb.target_wide_charset</b> ()<var><a name="index-gdb_002etarget_005fwide_005fcharset-1893"></a></var><br>
	<blockquote><p>Return the name of the current target wide character set
	(see <a href="Character-Sets.html#Character-Sets">Character Sets</a>). This differs from
	<code>gdb.parameter('target-wide-charset')</code> in that ‘<samp><span class="samp">auto</span></samp>’ is
	never returned.
	</p></blockquote></div>

	<p><a name="index-gdb_002esolib_005fname-1894"></a>

	<div class="defun">
	— Function: <b>gdb.solib_name</b> (<var>address</var>)<var><a name="index-gdb_002esolib_005fname-1895"></a></var><br>
	<blockquote><p>Return the name of the shared library holding the given <var>address</var>
	as a string, or <code>None</code>. This is identical to
	<code>gdb.current_progspace().solib_name(address)</code> and is included for
	historical compatibility.
	</p></blockquote></div>

	<p><a name="index-gdb_002edecode_005fline-1896"></a>

	<div class="defun">
	— Function: <b>gdb.decode_line</b> (<span class="roman">[</span><var>expression</var><span class="roman">]</span>)<var><a name="index-gdb_002edecode_005fline-1897"></a></var><br>
	<blockquote><p>Return locations of the line specified by <var>expression</var>, or of the
	current line if no argument was given. This function returns a Python
	tuple containing two elements. The first element contains a string
	holding any unparsed section of <var>expression</var> (or <code>None</code> if
	the expression has been fully parsed). The second element contains
	either <code>None</code> or another tuple that contains all the locations
	that match the expression represented as <code>gdb.Symtab_and_line</code>
	objects (see <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>). If <var>expression</var> is
	provided, it is decoded the way that <span class="sc">gdb</span>'s inbuilt
	<code>break</code> or <code>edit</code> commands do (see <a href="Specify-Location.html#Specify-Location">Specify Location</a>).
	</p></blockquote></div>

	<div class="defun">
	— Function: <b>gdb.prompt_hook</b> (<var>current_prompt</var>)<var><a name="index-gdb_002eprompt_005fhook-1898"></a></var><br>
	<blockquote><p><a name="prompt_005fhook"></a>If <var>prompt_hook</var> is callable, <span class="sc">gdb</span> will call the method
	assigned to this operation before a prompt is displayed by
	<span class="sc">gdb</span>.

	<p>The parameter <code>current_prompt</code> contains the current <span class="sc">gdb</span>
	prompt. This method must return a Python string, or <code>None</code>. If
	a string is returned, the <span class="sc">gdb</span> prompt will be set to that
	string. If <code>None</code> is returned, <span class="sc">gdb</span> will continue to use
	the current prompt.

	<p>Some prompts cannot be substituted in <span class="sc">gdb</span>. Secondary prompts
	such as those used by readline for command input, and annotation
	related prompts are prohibited from being changed.
	</p></blockquote></div>

	</body></html>