This is a behavioral specification for multiprocess/multiprogram GDB. This specification is phrased in terms of user-visible behavior, and generally organized according to the format of the GDB manual. There is a technical distinction to be made between the term "multiprogram" and "multiprocess". Most precisely, "multiprogram" or "multiexec" refers to the ability to work with several different executables at the same time within a debugging session. (Currently, GDB can only handle one at a time; a command bringing in an executable, such as "file", causes the previous one to be removed.) Conversely, the term "multiprocess" is appropriate when GDB has several inferiors, which may or may not be associated with the same executable. However, since the two are being implemented together, the distinction will not be important to users. This spec borrows liberally from the HPD draft standard. Definitions Exec: Short for executable program, which is defined as a file that contains a program which may be run independently of other programs. Program: Synonym for exec. (Informally, "program" is preferable for user documentation, while "exec" is preferable for GDB internals documentation.) Inferior: A GDB object representing a futurely-, currently- or formerly-running program. There must be an inferior for each execution of each program. (Informally, an inferior corresponds to a process or corefile.) Address space: A GDB object providing an interpretation of a CORE_ADDR. Execs and inferiors each have at least one address space, and may have several, with contents distinguished in a target-specific way. Multiple execs and inferiors may share an address space. Thread: A single locus of control within an inferior. Inferior/thread set: A collection of inferiors and/or threads, abbreviated "itset". Generalities Basic multiprogram and multiprocess support in GDB will be automatically available in every version of GDB; there will be no special configuration flags or compiletime options. Support for simultaneous control of multiple inferiors will typically require target-specific additions, and so some targets may not include these additions; GDB will warn but do nothing else if the user attempts to run more than one inferior at a time on these targets. GDB's behavior in the case of one program and one inferior will be the same as formerly, with the possible exception of some rarely-seen edge cases. * Inferiors and inferior sets An inferior object is a representation of a single program run. While conceptually similar to a Unix process, it is more general; an inferior may be created before a program starts running, and it may continue to exist after the program exits. Running or attaching to a program creates an inferior if one does not exist for the program already. The default name of the inferior depends on the target, but is typically a number corresponding to process id. The syntax for symbols and source lines is extended to allow reference to specific inferiors. An inferior-specific symbol reference is '##', while a general source line reference has the form '##:'. If an inferior is not specified, GDB will use a most logical inferior, such as the last one used, or one from the current itset. An inferior/thread set is a collection of inferiors and threads within those inferiors. Itsets may enumerate their members explicitly, or be determined dynamically; for instance, the itset named "all" automatically includes all inferiors and all threads. Itsets may have names. The command-line syntax for inferior/thread sets is '[]', where may take several forms. [] Specifies the named itset . [] Specifies the inferior named (which may be a number). [] Specifies the default inferior corresponding to the program named . [,,,...] Specifies the union of the itsets specified by speci. [.] Specifies thread of inferior . Both and may be '*', which specifies all of each. [all] Specifies all inferiors and all threads. [TBD: Allow '[]' to be optional when it is unambiguous, as in focus command?] focus Sets the effect of subsequent commands to apply only to the inferiors and threads in the given itset. This set is known as the "current" itset. It will be possible to create inferiors manually. This will be useful to set up complicated runs involving multiple instances of execs. add-inferior [-copies ] [-name ] Creates (default 1) inferiors, all associated with the exec . The inferiors will be numbered consecutively, with as a common prefix if specified. remove-inferior Deletes the inferiors included in . Autogenerated inferiors, such as for execs, cannot be removed manually, but will go away when the associated exec or other object is removed. name-inferior Change the inferior named to have the name . info inferiors Lists all inferiors in existence. ... Apply to everything in . * Invoking GDB GDB will allow multiple programs to be specified on the command line. The basic form will be gdb prog1 prog2 prog3 ... If progi is recognized as a core file, then GDB will take it as a core file corresponding to the most recently specified executable; it will be an error if the previous argument is not an executable. Similarly, if progi is a decimal number, GDB will interpret it as a process id, corresponding to the last executable specified. For instance, gdb prog1 core1 prog2 core2 sets up to debug two programs prog1 and prog2, each with a corresponding core file. Conversely, gdb prog1 prog2 core1 core2 sets up to debug prog1 and two crashes of prog2, each with its own core file. For the sake of compatibility, the options -exec, -symbols, and -core will clear the list of files already seen on the command line, and replace them with the single file that is supplied with the option. (This is so that "gdb -exec foo -exec bar" continues to work as before.) * Running Programs under GDB The run command will run all the execs in the current itset. The arguments to run will be passed to all execs; if no arguments are supplied, then the arguments will be those associated with the exec's inferior; either those set manually with "set args", or the same arguments as used in the previous run. attach ... Attaches to each process listed, and creates an inferior named after the pid. detach [] Detaches from each process mentioned in the optional . If is omitted, GDB will detach from all process in the current itset. kill [] Kills each process included in the optional . If is omitted, GDB will attempt to kill every process in the current itset. set args ... Set the list of arguments to be used the next time any of the inferiors in the current itset starts. set environment ... Similarly, for the environment. set follow-fork-mode both On targets that support process forking, lets the developer choose to include both parent and child of a fork as processes being debugged. set follow_exec true On targets that support process exec'ing, lets the developer debug processes created via exec/execl. * Stopping and Continuing Breakpoints, watchpoints, etc, are intrinsically global; any given breakpoint may apply to a number of locations in each of several executables. For instance, "break main" can cause every program under GDB's control to stop soon after it starts; to break in only some executables, the syntax "break ##main" would be necessary. [TBD: have a way to delete "locations" from a breakpoint? too complicated?] By default, the break and watch commands only associates a breakpoint with members of the current itset. Step only affects a single inferior, while continue may cause one or all inferiors to resume execution. When one of the inferiors/threads stops, GDB sets the current itset to consist of just the inferior and thread that actually stopped. The user is free to change the focus thereafter. info program Displays the status of each inferior currently in existence, including whether it is stopped and why. * Examining the Stack By default, the backtrace and frame commands apply only to the current thread in the current itset. [TBD: Extend frame command syntax to ## ? ] * Examining Source Files By default, an argument to the list command is interpreted as referring to the first exec found in the current itset. An argument may be prefixed with the '#' syntax designating a particular inferior. * Examining Data By default, the expression given to a print command is evaluated relative to each member of the current itset. If there are multiple threads and/or inferiors, each distinct value is printed separately, prefixed by an itset spec showing which threads and/or inferiors yielded that value. * GDB Files file ... exec-file ... symbol-file ... Replace all files/exec files/symbol files with the given file(s). add-file ... Adds arguments to the list of executables and to the list of symbol files. remove-file Removes from the list of executables and from the list of symbol files. info files Lists all the execs that are being debugged. add-exec-file ... Adds to the list of executables being debugged. remove-exec-file Removes from the list of executables being debugged. * Specifying a Debugging Target Targets will need internal changes in order to support multiple inferiors, but they need not change in any user-visible way. The remote protocol will optionally send and receive id's identifying the inferior to which each packet applies. Packets not identifying an inferior will be assumed to refer to the current itset; if the current itset contains more than one inferior, then they will be assumed to be sharing the same address space. * The GDB/MI Interface [TBD] ** Planned limitations of the first version The proposed set of extensions is a considerable amount of work, too much to be done all at once. This section suggests a set of limitations on the general capability that still yield a usable multiprocess debugger. The itset prefix to commands is not implemented. Definition of named itsets is not supported. The focus command only allows sets consisting of a single exec, and focus in general is only on one inferior. The attach command takes only one pid. The detach and kill commands take no arguments. All inferiors must use the same target stack. (All remote, all native, etc) The "both" follow-fork-mode and the follow-exec options are not available. The file etc commands do not take multiple arguments. The MI interface is not supported.