in a register called the @dfn{frame pointer register}
(@pxref{Registers, $fp}) while execution is going on in that frame.
+@cindex frame level
@cindex frame number
-@value{GDBN} assigns numbers to all existing stack frames, starting with
-zero for the innermost frame, one for the frame that called it,
-and so on upward. These numbers do not really exist in your program;
-they are assigned by @value{GDBN} to give you a way of designating stack
-frames in @value{GDBN} commands.
+@value{GDBN} labels each existing stack frame with a @dfn{level}, a
+number that is zero for the innermost frame, one for the frame that
+called it, and so on upward. These level numbers give you a way of
+designating stack frames in @value{GDBN} commands. The terms
+@dfn{frame number} and @dfn{frame level} can be used interchangeably to
+describe this number.
@c The -fomit-frame-pointer below perennially causes hbox overflow
@c underflow problems.
@table @code
@kindex frame@r{, selecting}
@kindex f @r{(@code{frame})}
-@item frame @var{n}
-@itemx f @var{n}
-Select frame number @var{n}. Recall that frame zero is the innermost
+@item frame @r{[} @var{frame-selection-spec} @r{]}
+@item f @r{[} @var{frame-selection-spec} @r{]}
+The @command{frame} command allows different stack frames to be
+selected. The @var{frame-selection-spec} can be any of the following:
+
+@table @code
+@kindex frame level
+@item @var{num}
+@item level @var{num}
+Select frame level @var{num}. Recall that frame zero is the innermost
(currently executing) frame, frame one is the frame that called the
-innermost one, and so on. The highest-numbered frame is the one for
-@code{main}.
+innermost one, and so on. The highest level frame is usually the one
+for @code{main}.
+
+As this is the most common method of navigating the frame stack, the
+string @command{level} can be omitted. For example, the following two
+commands are equivalent:
+
+@smallexample
+(@value{GDBP}) frame 3
+(@value{GDBP}) frame level 3
+@end smallexample
+
+@kindex frame address
+@item address @var{stack-address}
+Select the frame with stack address @var{stack-address}. The
+@var{stack-address} for a frame can be seen in the output of
+@command{info frame}, for example:
+
+@smallexample
+(gdb) info frame
+Stack level 1, frame at 0x7fffffffda30:
+ rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
+ tail call frame, caller of frame at 0x7fffffffda30
+ source language c++.
+ Arglist at unknown address.
+ Locals at unknown address, Previous frame's sp is 0x7fffffffda30
+@end smallexample
-@item frame @var{stack-addr} [ @var{pc-addr} ]
-@itemx f @var{stack-addr} [ @var{pc-addr} ]
-Select the frame at address @var{stack-addr}. This is useful mainly if the
-chaining of stack frames has been damaged by a bug, making it
-impossible for @value{GDBN} to assign numbers properly to all frames. In
-addition, this can be useful when your program has multiple stacks and
-switches between them. The optional @var{pc-addr} can also be given to
-specify the value of PC for the stack frame.
+The @var{stack-address} for this frame is @code{0x7fffffffda30} as
+indicated by the line:
+
+@smallexample
+Stack level 1, frame at 0x7fffffffda30:
+@end smallexample
+
+@kindex frame function
+@item function @var{function-name}
+Select the stack frame for function @var{function-name}. If there are
+multiple stack frames for function @var{function-name} then the inner
+most stack frame is selected.
+
+@kindex frame view
+@item view @var{stack-address} @r{[} @var{pc-addr} @r{]}
+View a frame that is not part of @value{GDBN}'s backtrace. The frame
+viewed has stack address @var{stack-addr}, and optionally, a program
+counter address of @var{pc-addr}.
+
+This is useful mainly if the chaining of stack frames has been
+damaged by a bug, making it impossible for @value{GDBN} to assign
+numbers properly to all frames. In addition, this can be useful
+when your program has multiple stacks and switches between them.
+
+When viewing a frame outside the current backtrace using
+@command{frame view} then you can always return to the original
+stack using one of the previous stack frame selection instructions,
+for example @command{frame level 0}.
+
+@end table
@kindex up
@item up @var{n}
@table @code
@kindex select-frame
-@item select-frame
+@item select-frame @r{[} @var{frame-selection-spec} @r{]}
The @code{select-frame} command is a variant of @code{frame} that does
not display the new frame after selecting it. This command is
intended primarily for use in @value{GDBN} command scripts, where the
-output might be unnecessary and distracting.
+output might be unnecessary and distracting. The
+@var{frame-selection-spec} is as for the @command{frame} command
+described in @ref{Selection, ,Selecting a Frame}.
@kindex down-silently
@kindex up-silently
something has gone wrong that has made the stack format fail to fit
the usual conventions.
-@item info frame @var{addr}
-@itemx info f @var{addr}
-Print a verbose description of the frame at address @var{addr}, without
-selecting that frame. The selected frame remains unchanged by this
-command. This requires the same kind of address (more than one for some
-architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a Frame}.
+@item info frame @r{[} @var{frame-selection-spec} @r{]}
+@itemx info f @r{[} @var{frame-selection-spec} @r{]}
+Print a verbose description of the frame selected by
+@var{frame-selection-spec}. The @var{frame-selection-spec} is the
+same as for the @command{frame} command (@pxref{Selection, ,Selecting
+a Frame}). The selected frame remains unchanged by this command.
@kindex info args
@item info args
@item set index-cache directory @var{directory}
@itemx show index-cache directory
-Set/show the directory where index files will be saved. By default, the index
-is cached in the @file{gdb} subdirectory of the directory pointed to by the
-@env{XDG_CACHE_HOME} environment variable, if it is defined, else in the
-@file{.cache/gdb} subdirectory of your home directory.
+Set/show the directory where index files will be saved.
+
+The default value for this directory depends on the host platform. On
+most systems, the index is cached in the @file{gdb} subdirectory of
+the directory pointed to by the @env{XDG_CACHE_HOME} environment
+variable, if it is defined, else in the @file{.cache/gdb} subdirectory
+of your home directory. However, on some systems, the default may
+differ according to local convention.
There is no limit on the disk space used by index cache. It is perfectly safe
to delete the content of that directory to free up disk space.
@cindex process ID
@item info proc
@itemx info proc @var{process-id}
-Summarize available information about any running process. If a
+Summarize available information about a process. If a
process ID is specified by @var{process-id}, display information about
that process; otherwise display information about the program being
debugged. The summary includes the debugged process ID, the command
Show the name of executable of the process. This command is supported
on @sc{gnu}/Linux and FreeBSD.
+@item info proc files
+@cindex info proc files
+Show the file descriptors open by the process. For each open file
+descriptor, @value{GDBN} shows its number, type (file, directory,
+character device, socket), file pointer offset, and the name of the
+resource open on the descriptor. The resource name can be a file name
+(for files, directories, and devices) or a protocol followed by socket
+address (for network connections). This command is supported on
+FreeBSD.
+
+This example shows the open file descriptors for a process using a
+tty for standard input and output as well as two network sockets:
+
+@smallexample
+(gdb) info proc files 22136
+process 22136
+Open files:
+
+ FD Type Offset Flags Name
+ text file - r-------- /usr/bin/ssh
+ ctty chr - rw------- /dev/pts/20
+ cwd dir - r-------- /usr/home/john
+ root dir - r-------- /
+ 0 chr 0x32933a4 rw------- /dev/pts/20
+ 1 chr 0x32933a4 rw------- /dev/pts/20
+ 2 chr 0x32933a4 rw------- /dev/pts/20
+ 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22
+ 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456
+@end smallexample
+
@item info proc mappings
@cindex memory address space mappings
-Report the memory address space ranges accessible in the program. On
+Report the memory address space ranges accessible in a process. On
Solaris and FreeBSD systems, each memory range includes information on
whether the process has read, write, or execute access rights to each
range. On @sc{gnu}/Linux and FreeBSD systems, each memory range
projects / deliverable / binutils-gdb.git / blobdiff