From: Tom Tromey <tromey@redhat.com>
Date: Mon, 29 Apr 2013 17:30:26 +0000 (+0000)
Subject: 	* gdb.texinfo (Python API): Mention Python help and keyword
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=60155234922f698050f1ba7c1a28879ea72e9131;p=binutils-gdb.git

	* gdb.texinfo (Python API): Mention Python help and keyword
	arguments.  Move pagination text to Basic Python.
	(Basic Python): Put pagination text here.  Document
	close-on-exec, SIGCHLD, and SIGINT.
---

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 81ddabc3db4..d4dc4576326 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,10 @@
+2013-04-29  Tom Tromey  <tromey@redhat.com>
+
+	* gdb.texinfo (Python API): Mention Python help and keyword
+	arguments.  Move pagination text to Basic Python.
+	(Basic Python): Put pagination text here.  Document
+	close-on-exec, SIGCHLD, and SIGINT.
+
 2013-04-19  Pedro Alves  <palves@redhat.com>
 
 	* gdbint.texinfo (Misc Guidelines) <Compiler Warnings>: Write
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 47b1188ad9c..9a2b09025cc 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -22984,13 +22984,13 @@ and thus is always available.
 @cindex python api
 @cindex programming in python
 
-@cindex python stdout
-@cindex python pagination
-At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
-@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
-A Python program which outputs to one of these streams may have its
-output interrupted by the user (@pxref{Screen Size}).  In this
-situation, a Python @code{KeyboardInterrupt} exception is thrown.
+You can get quick online help for @value{GDBN}'s Python API by issuing
+the command @w{@kbd{python help (gdb)}}.
+
+Functions and methods which have two or more optional arguments allow
+them to be specified using keyword syntax.  This allows passing some
+optional arguments while skipping others.  Example:
+@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
 
 @menu
 * Basic Python::                Basic Python Functions.
@@ -23023,6 +23023,35 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 @node Basic Python
 @subsubsection Basic Python
 
+@cindex python stdout
+@cindex python pagination
+At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
+@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
+A Python program which outputs to one of these streams may have its
+output interrupted by the user (@pxref{Screen Size}).  In this
+situation, a Python @code{KeyboardInterrupt} exception is thrown.
+
+Some care must be taken when writing Python code to run in
+@value{GDBN}.  Two things worth noting in particular:
+
+@itemize @bullet
+@item
+@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
+Python code must not override these, or even change the options using
+@code{sigaction}.  If your program changes the handling of these
+signals, @value{GDBN} will most likely stop working correctly.  Note
+that it is unfortunately common for GUI toolkits to install a
+@code{SIGCHLD} handler.
+
+@item
+@value{GDBN} 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.
+@end itemize
+
 @cindex python functions
 @cindex python module
 @cindex gdb module