@item M-x grep-find
@itemx M-x find-grep
@itemx M-x rgrep
-Run @code{grep} via @code{find}, with user-specified arguments, and
-collect output in the buffer named @samp{*grep*}.
+Run @code{grep} via @code{find}, and collect output in the buffer
+named @samp{*grep*}.
+@item M-x zrgrep
+Run @code{zgrep} and collect output in the buffer named @samp{*grep*}.
@item M-x kill-grep
Kill the running @code{grep} subprocess.
@end table
@findex lgrep
@findex rgrep
+@findex zrgrep
The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
(recursive grep) are more user-friendly versions of @code{grep} and
@code{grep-find}, which prompt separately for the regular expression
to match, the files to search, and the base directory for the search.
-Case sensitivity of the search is controlled by the
-current value of @code{case-fold-search}.
+Case sensitivity of the search is controlled by the current value of
+@code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to
+@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to
+search the contents of gzipped files.
-These commands build the shell commands based on the variables
+ These commands build the shell commands based on the variables
@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
-(for @code{rgrep}).
+(for @code{rgrep}). The files to search can use aliases defined in
+the variable @code{grep-files-aliases}.
-The files to search can use aliases defined in the variable
-@code{grep-files-aliases}.
-
-Subdirectories listed in the variable
+ Subdirectories listed in the variable
@code{grep-find-ignored-directories} such as those typically used by
various version control systems, like CVS and arch, are automatically
skipped by @code{rgrep}.
* Source Buffers:: Use the mouse in the fringe/margin to
control your program.
* Breakpoints Buffer:: A breakpoint control panel.
+* Threads Buffer:: Displays your threads.
* Stack Buffer:: Select a frame from the call stack.
* Other GDB-UI Buffers:: Input/output, locals, registers,
assembler, threads and memory buffers.
* Watch Expressions:: Monitor variable values in the speedbar.
-* Reverse Debugging:: Execute and reverse debug your program.
+* Multithreaded Debugging:: Debugging programs with several threads.
@end menu
@node GDB-UI Layout
|--------------------------------+--------------------------------+
| Primary Source buffer | I/O buffer for debugged pgm |
|--------------------------------+--------------------------------+
-| Stack buffer | Breakpoints/Threads buffer |
+| Stack buffer | Breakpoints/Thread buffer |
+--------------------------------+--------------------------------+
@end group
@end smallexample
Visit the source line for the breakpoint you click on.
@end table
+@vindex gdb-show-threads-by-default
When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
shares its window with the threads buffer. To switch from one to the
other click with @kbd{Mouse-1} on the relevant button in the header
-line.
+line, or press @kbd{TAB} inside that buffer. If
+@code{gdb-show-threads-by-default} is non-@code{nil}, the threads
+buffer, rather than the breakpoints buffer, is shown at start up.
+
+@node Threads Buffer
+@subsubsection Threads Buffer
+
+@findex gdb-select-thread
+The threads buffer displays a summary of all threads currently in your
+program (@pxref{Threads, Threads, Debugging programs with multiple
+threads, gdb, The GNU debugger}). Move point to any thread in the list
+and press @key{RET} to select it (@code{gdb-select-thread}) and
+display the associated source in the primary source buffer.
+Alternatively, click @kbd{Mouse-2} on a thread to select it. Contents
+of all GDB buffers are updated whenever you select a thread.
+
+ You can customize variables under @code{gdb-buffers} group to select
+fields included in threads buffer.
+
+@table @code
+@item gdb-thread-buffer-verbose-names
+@vindex gdb-thread-buffer-verbose-names
+Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in
+threads buffer.
+
+@item gdb-thread-buffer-arguments
+@vindex gdb-thread-buffer-arguments
+Show arguments of thread top frames in threads buffer.
+
+@item gdb-thread-buffer-locations
+@vindex gdb-thread-buffer-locations
+Show file information or library names in threads buffer.
+
+@item gdb-thread-buffer-addresses
+@vindex gdb-thread-buffer-addresses
+Show addresses for thread frames in threads buffer.
+@end table
+
+ It’s possible to observe information for several threads
+simultaneously (in addition to buffers which show information for
+currently selected thread) using the following keys from the threads
+buffer.
+
+@table @kbd
+@item d
+@kindex d @r{(GDB threads buffer)}
+@findex gdb-display-disassembly-for-thread
+Display disassembly buffer for the thread at current line.
+(@code{gdb-display-disassembly-for-thread})
+
+@item f
+@kindex f @r{(GDB threads buffer)}
+@findex gdb-display-stack-for-thread
+Display stack buffer for the thread at current line.
+(@code{gdb-display-stack-for-thread}).
+
+@item l
+@kindex l @r{(GDB threads buffer)}
+@findex gdb-display-locals-for-thread
+Display locals buffer for the thread at current line.
+(@code{gdb-display-locals-for-thread}).
+
+@item r
+@kindex r @r{(GDB threads buffer)}
+@findex gdb-display-registers-for-thread
+Display registers buffer for the thread at current line.
+(@code{gdb-display-registers-for-thread}).
+@end table
+
+Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and
+@kbd{R} displays the corresponding buffer in a new frame.
+
+ When you create a buffer showing information about some specific
+thread, it becomes bound to that thread and keeps showing actual
+information while you debug your program. Every GDB buffer contains a
+number of thread it shows information for in its mode name. Thread
+number is also included in the buffer name of bound buffers to prevent
+buffer names clashing.
+
+Further commands are available in the threads buffer which depend on the
+mode of GDB that is used for controlling execution of your program.
+(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}).
@node Stack Buffer
@subsubsection Stack Buffer
@item Locals Buffer
The locals buffer displays the values of local variables of the
current frame for simple data types (@pxref{Frame Info, Frame Info,
-Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
+Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
click @kbd{Mouse-2} on the value if you want to edit it.
Arrays and structures display their type only. With GDB 6.4 or later,
press @key{SPC} to toggle the display of floating point registers
(@code{toggle-gdb-all-registers}).
-@item Assembler Buffer
-The assembler buffer displays the current frame as machine code. An
+@item Disassembly Buffer
+The disassembly buffer displays the current frame as machine code. An
arrow points to the current instruction, and you can set and remove
breakpoints as in a source buffer. Breakpoint icons also appear in
the fringe or margin.
-@item Threads Buffer
-@findex gdb-threads-select
-The threads buffer displays a summary of all threads currently in your
-program (@pxref{Threads, Threads, Debugging programs with multiple
-threads, gdb, The GNU debugger}). Move point to any thread in the
-list and press @key{RET} to select it (@code{gdb-threads-select}) and
-display the associated source in the primary source buffer.
-Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
-locals buffer is visible, its contents update to display the variables
-that are local in the new thread.
-
-When there is more than one main thread and the threads buffer is
-present, Emacs displays the selected thread number in the mode line of
-many of the GDB-UI Buffers.
-
@item Memory Buffer
The memory buffer lets you examine sections of program memory
(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
shares its window with the breakpoints buffer, and the locals buffer
-with the registers buffer. To switch from one to the other click with
-@kbd{Mouse-1} on the relevant button in the header line.
+with the registers buffer. To switch from one to the other click with
+@kbd{Mouse-1} on the relevant button in the header line or press
+@kbd{TAB} inside the buffer.
@node Watch Expressions
@subsubsection Watch Expressions
non-@code{nil}. This can be useful if you are debugging with a full
screen Emacs frame.
-@node Reverse Debugging
-@subsubsection Reverse Debugging
-
- The GDB tool bar shares many buttons with the other GUD debuggers
-for tasks like stepping and printing expressions. It also has a
-further set of buttons that allow reverse debugging (@pxref{Process
-Record and Replay, , ,gdb, The GNU debugger}). This is useful when it
-takes a long time to reproduce the conditions where your program fails
-or for transient problems, like race conditions in multi-threaded
-programs, where a failure might otherwise be hard to reproduce.
-
-To use reverse debugging, set a breakpoint slightly before the
-location of interest and run your program to that point. Enable
-process recording by clicking on the record button. At this point, a
-new set of buttons appear. These buttons allow program execution in
-the reverse direction. Run your program over the code where the
-problem occurs, and then use the new set of buttons to retrace your
-steps, examine values, and analyze the problem. When analysis is
-complete, turn off process recording by clicking on the record button
-again.
+@node Multithreaded Debugging
+@subsubsection Stopping and Starting Multi-threaded Programs
+@cindex Multithreaded debugging in GDB
+
+@subsubheading All-stop Debugging
+
+In all-stop mode, whenever your program stops, @emph{all} threads of
+execution stop. Likewise, whenever you restart the program, all
+threads start executing. @xref{All-Stop Mode, , All-Stop Mode, gdb,
+The GNU debugger}. You can enable this behaviour in Emacs by setting
+@code{gdb-non-stop-setting} to @code{nil} before starting a debugging
+session.
+
+@subsubheading Non-stop Debugging
+@cindex Non-stop debugging in GDB
+
+For some multi-threaded targets, GDB supports a further mode of
+operation in which you can examine stopped program threads in the
+debugger while other threads continue to execute freely.
+@xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}.
+This is referred to as @dfn{non-stop} mode.
+
+Versions of GDB prior to 7.0 do not support non-stop mode and it does
+not work on all targets. In such cases, Emacs uses all-stop mode
+regardless of the value of @code{gdb-non-stop-setting}.
+
+@vindex gdb-non-stop-setting
+If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the
+default value), Emacs tries to start GDB in non-stop mode. Note that
+GDB debugging session needs to be restarted for change of this setting
+to take effect.
+
+@vindex gdb-switch-when-another-stopped
+When a thread stops in non-stop mode, Emacs automatically switches to
+that thread. It may be undesirable to allow switching of current
+thread when some other stopped thread is already selected. Set
+@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this.
+
+@vindex gdb-switch-reasons
+Emacs can decide whether or not to switch to the stopped thread
+depending on the reason which caused the stop. Customize
+@code{gdb-switch-reasons} to select stop reasons which make Emacs
+switch thread.
+
+@vindex gdb-stopped-hooks
+The variable @code{gdb-stopped-hooks} allows you to execute your
+functions whenever some thread stops.
+
+ In non-stop mode, you can switch between different modes for GUD
+execution control commands.
+
+@vindex gdb-gud-control-all-threads
+@table @dfn
+@item Non-stop/A
+
+When @code{gdb-gud-control-all-threads} is @code{t} (the default
+value), interruption and continuation commands apply to all threads,
+so you can halt or continue all your threads with one command using
+@code{gud-stop-subjob} and @code{gud-cont}, respectively. The
+@samp{Go} button is shown on the toolbar when at least one thread is
+stopped, whereas @samp{Stop} button is shown when at least one thread
+is running.
+
+@item Non-stop/T
+
+When @code{gdb-gud-control-all-threads} is @code{nil}, only the
+current thread is stopped/continued. @samp{Go} and @samp{Stop}
+buttons on the GUD toolbar are shown depending on the state of current
+thread.
+@end table
+
+You can change the current value of @code{gdb-gud-control-all-threads}
+from the tool bar or from @samp{GUD->GDB-MI} menu.
+
+ Stepping commands always apply to the current thread.
+
+@subsubheading Fine Thread Control
+
+ In non-stop mode, you can interrupt/continue your threads without
+selecting them. Hitting @kbd{i} in threads buffer interrupts thread
+under point, @kbd{c} continues it, @kbd{s} steps through. More such
+commands may be added in the future.
+
+Combined with creating bound buffers for any thread, this allows you
+to change and track state of many threads in the same time.
+
+ Note that when you interrupt a thread, it stops with @samp{signal
+received} reason. If that reason is included in your
+@code{gdb-switch-reasons} (it is by default), Emacs will switch to
+that thread.
@node Executing Lisp
@section Executing Lisp Expressions
** New configure options for Emacs developers
These are not new features; only the configure flags are new.
-
+---
*** --enable-profiling builds Emacs with profiling enabled.
This might not work on all platforms.
-
+---
*** --enable-checking[=OPTIONS] builds emacs with extra runtime checks.
---
** `make install' now consistently ignores umask, creating a
world-readable install.
-** Emacs compiles with Gconf support by default, if it is detected.
+** Emacs compiles with Gconf support, if it is detected.
Use the configure option --without-gconf to disable this.
* Startup Changes in Emacs 23.2
-
++++
** The command-line option -Q (--quick) also inhibits loading X resources.
However, if Emacs is compiled with the Lucid or Motif toolkit, X
resource settings for the graphical widgets are still applied.
On Windows, the -Q option causes Emacs to ignore Registry settings,
but environment variables set on the Registry are still honored.
-
++++
*** The new variable `inhibit-x-resources' shows whether X resources
were loaded.
* Changes in Emacs 23.2
++++
** The maximum size of buffers (and the largest fixnum) is doubled.
On typical 32bit systems, buffers can now be up to 512MB.
+---
** The default value of `trash-directory' is now nil.
This means that `move-file-to-trash' trashes files according to
freedesktop.org specifications, the same method used by the Gnome,
via the XSETTINGS mechanism. This includes antialias, hinting,
hintstyle, RGBA, DPI and lcdfilter changes.
++++
** Killing a buffer with a running process now asks for confirmation.
To remove this query, remove `process-kill-buffer-query-function' from
`kill-buffer-query-functions', or set the appropriate process flag
with `set-process-query-on-exit-flag'.
** File-local variable changes
-
++++
*** Specifying a minor mode as a local variables enables that mode,
unconditionally. The previous behavior, toggling the mode, was
neither reliable nor generally desirable.
`copy-file-locals-to-dir-locals'.
** Internationalization changes
-
++++
*** Unibyte sessions are now considered obsolete.
This refers to the EMACS_UNIBYTE environment variable as well as the
--unibyte, --multibyte, --no-multibyte, and --no-unibyte command line
arguments. Customizing enable-multibyte-characters and setting
default-enable-multibyte-characters are also deprecated.
-
+---
*** New coding system `utf-8-hfs'.
This is suitable for default-file-name-coding-system on Mac OS X; see
international/ucs-normalize.el.
+---
** Function arguments in *Help* buffers are now shown in upper-case.
Customize `help-downcase-arguments' to t to show them in lower-case.
becomes the primary selection (for interaction with other window
applications). If you enable this, you might want to bind
`mouse-yank-primary' to Mouse-2.
-
++++
*** When `save-interprogram-paste-before-kill' is non-nil, the kill
commands save the interprogram-paste selection into the kill ring
before doing anything else. This avoids losing the selection.
-
++++
*** When `kill-do-not-save-duplicates' is non-nil, identical
subsequent kills are not duplicated in the `kill-ring'.
*** The new command `completion-at-point' provides mode-sensitive completion.
*** tab-always-indent set to `complete' lets TAB do completion as well.
-
++++
*** The new completion-style `initials' is available.
For instance, this can complete M-x lch to list-command-history.
+++
** The default value of `blink-matching-paren-distance' is increased.
+---
** M-n provides more default values in the minibuffer for commands
that read file names. These include the file name at point (when ffap
is loaded without ffap-bindings), the file name on the current line
(for Dired commands that operate on several directories, such as copy,
rename, or diff).
++++
** M-r is bound to the new `move-to-window-line-top-bottom'.
This moves point to the window center, top and bottom on successive
invocations, in the same spirit as the C-l (recenter-top-bottom)
command.
++++
** The new variable `recenter-positions' determines the default
cycling order of C-l (`recenter-top-bottom').
++++
+** The abbrevs file is now a file named abbrev_defs in
+user-emacs-directory; but the old location, ~/.abbrev_defs, is used if
+that file exists.
\f
* Changes in Specialized Modes and Packages in Emacs 23.2
** pcomplete provides a new command `pcomplete-std-completion' which
is similar to `pcomplete' but using the standard completion UI code.
-** .calc.el and .abbrev_defs obey user-emacs-directory.
+** Calc
++++
+*** The Calc settings file is now a file named calc.el in
+user-emacs-directory; but the old location, ~/.calc.el, is used if
+that file exists.
-** Calc graphing commands (`g f' etc.) now work on MS-Windows,
-if you have the native Windows port of Gnuplot version 3.8 or later
-installed.
+---
+*** Graphing commands (`g f' etc.) now work on MS-Windows, if you have
+the native Windows port of Gnuplot version 3.8 or later installed.
** Calendar and diary
watch expressions. These features require GDB 7.0 or later.
** Grep
-
-A new command `zrgrep' searches recursively in gzipped files.
++++
+*** A new command `zrgrep' searches recursively in gzipped files.
** Info
`default-directory' is already remote. Calling the external commands
is possible by `*su' or `*sudo', repectively.
+---
*** When running in a new enough xterm (newer than version 242), emacs
asks xterm what the background color is and it sets up faces
accordingly for a dark background if needed (the current default is to
** New function `completion-in-region' to use the standard completion
facilities on a particular region of text.
++++
** The 4th arg to all-completions (aka hide-spaces) is declared obsolete.
+---
** read-file-name-predicate is obsolete. It was used to pass the predicate
to read-file-name-internal because read-file-name-internal abused its `pred'
argument to pass the current directory, but this hack is not needed
** Frame parameter changes
++++
*** You can give the `fullscreen' frame parameter the value `maximized'.
This maximizes the frame.
*** The new frame parameter `sticky' makes Emacs frames sticky in
virtual desktops.
+---
** completion-base-size is obsoleted by completion-base-position.
This change causes a few backward incompatibilities, mostly with
choose-completion-string-functions where the `mini-p' argument has
a `process-file' call does not change a remote file. By this, file
name handlers like Tramp can apply optimizations.
++++
** Hash tables have a new printed representation that is readable.
The feature `hashtable-print-readable' identifies this new
functionality.
-** Functions performing Unicode normalization are added. They are:
+** New functions performing Unicode normalization are added:
ucs-normalize-NFD-region, ucs-normalize-NFD-string,
ucs-normalize-NFC-region, ucs-normalize-NFC-string,
ucs-normalize-NFKD-region, ucs-normalize-NFKD-string,
projects / emacs.git / commitdiff