diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h index 192fbee9c0c6d..7419db2f3c398 100644 --- a/lldb/include/lldb/API/SBDebugger.h +++ b/lldb/include/lldb/API/SBDebugger.h @@ -44,6 +44,7 @@ class LLDB_API SBInputReader { class LLDB_API SBDebugger { public: + /// Broadcast bit definitions for the SBDebugger. FLAGS_ANONYMOUS_ENUM() { eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress, eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning, @@ -55,16 +56,33 @@ class LLDB_API SBDebugger { eBroadcastBitExternalProgressCategory = lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgressCategory, }; + + /// Default constructor creates an invalid SBDebugger instance. SBDebugger(); SBDebugger(const lldb::SBDebugger &rhs); ~SBDebugger(); + /// Get the broadcaster class name. + /// + /// \return The name of the broadcaster class. static const char *GetBroadcasterClass(); + /// Check if a specific language is supported by LLDB. + /// + /// \param [in] language + /// The language to check. + /// + /// \return + /// True if the language is supported, false otherwise. static bool SupportsLanguage(lldb::LanguageType language); + /// Get the broadcaster associated with this debugger. + /// + /// \return + /// A broadcaster object that allows subscribing to events from this + /// debugger. lldb::SBBroadcaster GetBroadcaster(); /// Get progress data from a SBEvent whose type is eBroadcastBitProgress. @@ -106,44 +124,116 @@ class LLDB_API SBDebugger { bool &is_debugger_specific); #endif + /// Get progress data from an event. + /// + /// \param [in] event + /// The event to extract the progress information from. + /// + /// \return + /// A structured data object containing progress information, or an invalid + /// SBStructuredData if the event was not a progress event. static lldb::SBStructuredData GetProgressDataFromEvent(const lldb::SBEvent &event); + /// Get diagnostic information from an event. + /// + /// \param [in] event + /// The event to extract the diagnostic information from. + /// + /// \return + /// A structured data object containing diagnostic information, or an + /// invalid SBStructuredData if the event was not a diagnostic event. static lldb::SBStructuredData GetDiagnosticFromEvent(const lldb::SBEvent &event); + /// Assignment operator. lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs); + /// Initialize LLDB and its subsystems. + /// + /// This function should be called before any other LLDB functions. It + /// initializes all required subsystems for proper LLDB functionality. static void Initialize(); + /// Initialize the LLDB debugger subsystem with error handling. + /// + /// Similar to Initialize(), but returns an error if initialization fails. + /// + /// \return + /// An SBError object that indicates success or failure. static lldb::SBError InitializeWithErrorHandling(); + /// Configure LLDB to print a stack trace when it crashes. static void PrintStackTraceOnError(); + /// Configure LLDB to print diagnostic information when it crashes. static void PrintDiagnosticsOnError(); + /// Terminate LLDB and its subsystems. + /// + /// This should be called when LLDB is no longer needed. static void Terminate(); + /// Create a new debugger instance (deprecated). + /// + /// \return + /// A new SBDebugger object. LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)") static lldb::SBDebugger Create(); + /// Create a new debugger instance. + /// + /// \param [in] source_init_files + /// If true, the debugger will source .lldbinit files from the home + /// directory and current directory. + /// + /// \return + /// A new SBDebugger object. static lldb::SBDebugger Create(bool source_init_files); + /// Create a new debugger instance with a custom log handler. + /// + /// \param [in] source_init_files + /// If true, the debugger will source .lldbinit files from the home + /// directory and current directory. + /// + /// \param [in] log_callback + /// A callback function to handle log messages. + /// + /// \param [in] baton + /// A user data pointer passed to the log callback function. + /// + /// \return + /// A new SBDebugger object. static lldb::SBDebugger Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton); + /// Destroy a debugger instance. + /// + /// \param [in] debugger + /// The debugger instance to destroy. static void Destroy(lldb::SBDebugger &debugger); + /// Notify the debugger that system memory pressure has been detected. + /// + /// This can be used to free up memory resources by clearing caches. static void MemoryPressureDetected(); + /// Check if this is a valid SBDebugger object. explicit operator bool() const; + /// Check if this is a valid SBDebugger object. bool IsValid() const; + /// Clear this debugger instance. + /// + /// This will close all IO handlers and reset the debugger to its initial + /// state. void Clear(); - /// Getting a specific setting value into SBStructuredData format. + /// Get debugger settings as structured data. + /// /// Client can specify empty string or null to get all settings. /// /// Example usages: @@ -153,70 +243,137 @@ class LLDB_API SBDebugger { /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0"); /// lldb::SBStructuredData settings = debugger.GetSetting("target"); /// - /// \param[out] setting + /// \param[in] setting /// Property setting path to retrieve values. e.g "target.source-map" /// + /// \return + /// An SBStructuredData object containing the requested settings. lldb::SBStructuredData GetSetting(const char *setting = nullptr); + /// Set whether the debugger should run in asynchronous mode. + /// + /// When in asynchronous mode, events are processed on a background thread. + /// + /// \param [in] b + /// True to enable asynchronous mode, false for synchronous mode. void SetAsync(bool b); + /// Get whether the debugger is running in asynchronous mode. + /// + /// \return + /// True if the debugger is in asynchronous mode, false otherwise. bool GetAsync(); + /// Set whether to skip loading .lldbinit files. + /// + /// \param [in] b + /// True to skip loading LLDB init files, false to load them. void SkipLLDBInitFiles(bool b); + /// Set whether to skip loading application-specific .lldbinit files. + /// + /// \param [in] b + /// True to skip loading application init files, false to load them. void SkipAppInitFiles(bool b); #ifndef SWIG + /// Set the input file handle for the debugger. void SetInputFileHandle(FILE *f, bool transfer_ownership); + /// Set the output file handle for the debugger. void SetOutputFileHandle(FILE *f, bool transfer_ownership); + /// Set the error file handle for the debugger. void SetErrorFileHandle(FILE *f, bool transfer_ownership); #endif #ifndef SWIG + /// Get the input file handle for the debugger. FILE *GetInputFileHandle(); + /// Get the output file handle for the debugger. FILE *GetOutputFileHandle(); + /// Get the error file handle for the debugger. FILE *GetErrorFileHandle(); #endif + /// Set the input from a string. SBError SetInputString(const char *data); + /// Set the input file for the debugger. SBError SetInputFile(SBFile file); + /// Set the output file for the debugger. SBError SetOutputFile(SBFile file); + /// Set the error file for the debugger. SBError SetErrorFile(SBFile file); + /// Set the input file for the debugger using a FileSP. SBError SetInputFile(FileSP file); + /// Set the output file for the debugger using a FileSP. SBError SetOutputFile(FileSP file); + /// Set the error file for the debugger using a FileSP. SBError SetErrorFile(FileSP file); + /// Get the input file for the debugger. SBFile GetInputFile(); + /// Get the output file for the debugger. SBFile GetOutputFile(); + /// Get the error file for the debugger. SBFile GetErrorFile(); + /// Save the current terminal state. + /// + /// This should be called before modifying terminal settings. void SaveInputTerminalState(); + /// Restore the previously saved terminal state. void RestoreInputTerminalState(); + /// Get the command interpreter for this debugger. lldb::SBCommandInterpreter GetCommandInterpreter(); + /// Execute a command in the command interpreter. + /// + /// \param [in] command + /// The command to execute. void HandleCommand(const char *command); + /// Request an interrupt of the current operation. void RequestInterrupt(); + + /// Cancel a previously requested interrupt. void CancelInterruptRequest(); + + /// Check if an interrupt has been requested. + /// + /// \return + /// True if an interrupt has been requested, false otherwise. bool InterruptRequested(); + /// Get the listener associated with this debugger. lldb::SBListener GetListener(); #ifndef SWIG + /// Handle a process event (deprecated). + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. LLDB_DEPRECATED_FIXME( "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, " "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, " @@ -226,64 +383,209 @@ class LLDB_API SBDebugger { const lldb::SBEvent &event, FILE *out, FILE *err); #endif + /// Handle a process event. + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, SBFile out, SBFile err); #ifdef SWIG + /// Handle a process event using FileSP objects. + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED); #else + /// Handle a process event using FileSP objects. + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, FileSP out, FileSP err); #endif + /// Create a target with the specified parameters. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \param [in] target_triple + /// The target triple string (e.g., "x86_64-apple-macosx"). + /// + /// \param [in] platform_name + /// The name of the platform to use. + /// + /// \param [in] add_dependent_modules + /// Whether to add dependent modules to the target. + /// + /// \param [out] error + /// An SBError object that will be set if there is an error. + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTarget(const char *filename, const char *target_triple, const char *platform_name, bool add_dependent_modules, lldb::SBError &error); + /// Create a target with the specified file and target triple. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \param [in] target_triple + /// The target triple string (e.g., "x86_64-apple-macosx"). + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename, const char *target_triple); + /// Create a target with the specified file and architecture. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \param [in] archname + /// The name of the architecture (e.g., "x86_64"). + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTargetWithFileAndArch(const char *filename, const char *archname); + /// Create a target with the specified file. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTarget(const char *filename); + /// Get the dummy target. + /// + /// The dummy target is used when no target is available. + /// + /// \return + /// The dummy target. lldb::SBTarget GetDummyTarget(); #ifndef SWIG - // Dispatch telemery from client to server if client-telemetry is enabled - // (by vendor), otherwise the data is ignored. - // Invoking this from python client (with SWIG) is not supported. + /// Dispatch telemetry data from client to server. + /// + /// This is used to send telemetry data from the client to the server if + /// client-telemetry is enabled. If not enabled, the data is ignored. + /// + /// \param [in] data + /// The telemetry data to dispatch. void DispatchClientTelemetry(const lldb::SBStructuredData &data); #endif - // Return true if target is deleted from the target list of the debugger. + /// Delete a target from the debugger. + /// + /// \param [in] target + /// The target to delete. + /// + /// \return + /// True if the target was successfully deleted, false otherwise. bool DeleteTarget(lldb::SBTarget &target); + /// Get a target by index. + /// + /// \param [in] idx + /// The index of the target to retrieve. + /// + /// \return + /// The target at the specified index. lldb::SBTarget GetTargetAtIndex(uint32_t idx); + /// Get the index of a target. + /// + /// \param [in] target + /// The target to find the index of. + /// + /// \return + /// The index of the target, or UINT32_MAX if not found. uint32_t GetIndexOfTarget(lldb::SBTarget target); + /// Find a target with the specified process ID. + /// + /// \param [in] pid + /// The process ID to search for. + /// + /// \return + /// The target with the specified process ID, or an invalid target if not + /// found. lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid); + /// Find a target with the specified file and architecture. + /// + /// \param [in] filename + /// The name of the executable file. + /// + /// \param [in] arch + /// The name of the architecture. + /// + /// \return + /// The target with the specified file and architecture, or an invalid + /// target if not found. lldb::SBTarget FindTargetWithFileAndArch(const char *filename, const char *arch); + /// Get the number of targets in the debugger. uint32_t GetNumTargets(); + /// Get the currently selected target. lldb::SBTarget GetSelectedTarget(); + /// Set the selected target. void SetSelectedTarget(SBTarget &target); + /// Get the selected platform. lldb::SBPlatform GetSelectedPlatform(); + /// Set the selected platform. void SetSelectedPlatform(lldb::SBPlatform &platform); /// Get the number of currently active platforms. uint32_t GetNumPlatforms(); /// Get one of the currently active platforms. + /// + /// \param [in] idx + /// The index of the platform to retrieve. + /// + /// \return + /// The platform at the specified index. lldb::SBPlatform GetPlatformAtIndex(uint32_t idx); /// Get the number of available platforms. @@ -292,200 +594,367 @@ class LLDB_API SBDebugger { /// "platform list" command. uint32_t GetNumAvailablePlatforms(); - /// Get the name and description of one of the available platforms. + /// Get information about one of the available platforms. /// /// \param[in] idx - /// Zero-based index of the platform for which info should be retrieved, - /// must be less than the value returned by GetNumAvailablePlatforms(). + /// Zero-based index of the platform for which info should be retrieved, + /// must be less than the value returned by GetNumAvailablePlatforms(). + /// + /// \return + /// A structured data object containing platform information. lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx); + /// Get the source manager for this debugger. lldb::SBSourceManager GetSourceManager(); - // REMOVE: just for a quick fix, need to expose platforms through - // SBPlatform from this class. + /// Set the current platform by name. + /// + /// \param [in] platform_name + /// The name of the platform to set as current. + /// + /// \return + /// An SBError object indicating success or failure. lldb::SBError SetCurrentPlatform(const char *platform_name); + /// Set the SDK root for the current platform. + /// + /// \param [in] sysroot + /// The path to the SDK root. + /// + /// \return + /// True if the SDK root was successfully set, false otherwise. bool SetCurrentPlatformSDKRoot(const char *sysroot); - // FIXME: Once we get the set show stuff in place, the driver won't need - // an interface to the Set/Get UseExternalEditor. + /// Set whether to use an external editor. bool SetUseExternalEditor(bool input); + /// Get whether an external editor is being used. bool GetUseExternalEditor(); + /// Set whether to use color in output. bool SetUseColor(bool use_color); + /// Get whether color is being used in output. bool GetUseColor() const; - bool SetShowInlineDiagnostics(bool); + /// Set whether to show inline diagnostics. + bool SetShowInlineDiagnostics(bool b); + /// Set whether to use the source cache. bool SetUseSourceCache(bool use_source_cache); + /// Get whether the source cache is being used. bool GetUseSourceCache() const; + /// Get the default architecture. + /// + /// \param [out] arch_name + /// A buffer to store the architecture name. + /// + /// \param [in] arch_name_len + /// The size of the buffer. + /// + /// \return + /// True if the default architecture was successfully retrieved, false + /// otherwise. static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len); + /// Set the default architecture. static bool SetDefaultArchitecture(const char *arch_name); + /// Get the scripting language by name. lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name); - SBStructuredData GetScriptInterpreterInfo(ScriptLanguage); + /// Get information about a script interpreter. + /// + /// \param [in] language + /// The scripting language to get information about. + /// + /// \return + /// A structured data object containing script interpreter information. + SBStructuredData GetScriptInterpreterInfo(ScriptLanguage language); + /// Get the LLDB version string. static const char *GetVersionString(); + /// Convert a state type to a string. static const char *StateAsCString(lldb::StateType state); + /// Get the build configuration. + /// + /// \return + /// A structured data object containing build configuration information. static SBStructuredData GetBuildConfiguration(); + /// Check if a state is a running state. static bool StateIsRunningState(lldb::StateType state); + /// Check if a state is a stopped state. static bool StateIsStoppedState(lldb::StateType state); + /// Enable logging for a specific channel. + /// + /// \param [in] channel + /// The name of the channel to enable. + /// + /// \param [in] categories + /// An array of category names to enable, terminated by nullptr. + /// + /// \return + /// True if logging was successfully enabled, false otherwise. bool EnableLog(const char *channel, const char **categories); + /// Set a callback for log output. + /// + /// \param [in] log_callback + /// The callback function to handle log output. + /// + /// \param [in] baton + /// A user data pointer passed to the callback function. void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton); - /// Clear all previously added callbacks and only add the given one. + /// Set a callback for when the debugger is destroyed (deprecated). + /// + /// \param [in] destroy_callback + /// The callback function to call when the debugger is destroyed. + /// + /// \param [in] baton + /// A user data pointer passed to the callback function. LLDB_DEPRECATED_FIXME("Use AddDestroyCallback and RemoveDestroyCallback", "AddDestroyCallback") void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback, void *baton); - /// Add a callback for when the debugger is destroyed. Return a token, which - /// can be used to remove said callback. Multiple callbacks can be added by - /// calling this function multiple times, and will be invoked in FIFO order. + /// Add a callback for when the debugger is destroyed. + /// + /// \param [in] destroy_callback + /// The callback function to call when the debugger is destroyed. + /// + /// \param [in] baton + /// A user data pointer passed to the callback function. + /// + /// \return + /// A token that can be used to remove the callback. lldb::callback_token_t AddDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback, void *baton); - /// Remove the specified callback. Return true if successful. + /// Remove a destroy callback. + /// + /// \param [in] token + /// The token returned from AddDestroyCallback. + /// + /// \return + /// True if the callback was successfully removed, false otherwise. bool RemoveDestroyCallback(lldb::callback_token_t token); #ifndef SWIG + /// Dispatch input to the debugger (deprecated). + /// + /// \param [in] baton + /// A user data pointer. + /// + /// \param [in] data + /// The input data. + /// + /// \param [in] data_len + /// The length of the input data. LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)", "DispatchInput(const void *, size_t)") void DispatchInput(void *baton, const void *data, size_t data_len); #endif + /// Dispatch input to the debugger. + /// + /// \param [in] data + /// The input data. + /// + /// \param [in] data_len + /// The length of the input data. void DispatchInput(const void *data, size_t data_len); + /// Interrupt the current input dispatch. void DispatchInputInterrupt(); + /// Signal end-of-file to the current input dispatch. void DispatchInputEndOfFile(); #ifndef SWIG + /// Push an input reader onto the IO handler stack. void PushInputReader(lldb::SBInputReader &reader); #endif + /// Get the instance name of this debugger. const char *GetInstanceName(); + /// Find a debugger by ID. + /// + /// \param [in] id + /// The ID of the debugger to find. + /// + /// \return + /// The debugger with the specified ID, or an invalid debugger if not found. static SBDebugger FindDebuggerWithID(int id); + /// Set an internal variable. + /// + /// \param [in] var_name + /// The name of the variable to set. + /// + /// \param [in] value + /// The value to set. + /// + /// \param [in] debugger_instance_name + /// The name of the debugger instance to set the variable in. + /// + /// \return + /// An SBError object indicating success or failure. static lldb::SBError SetInternalVariable(const char *var_name, const char *value, const char *debugger_instance_name); + /// Get the value of an internal variable. + /// + /// \param [in] var_name + /// The name of the variable to get. + /// + /// \param [in] debugger_instance_name + /// The name of the debugger instance to get the variable from. + /// + /// \return + /// A string list containing the variable value. static lldb::SBStringList GetInternalVariableValue(const char *var_name, const char *debugger_instance_name); + /// Get a description of this debugger. + /// + /// \param [out] description + /// A stream to write the description to. + /// + /// \return + /// True if the description was successfully written, false otherwise. bool GetDescription(lldb::SBStream &description); + /// Get the terminal width. uint32_t GetTerminalWidth() const; + /// Set the terminal width. void SetTerminalWidth(uint32_t term_width); + /// Get the terminal height. uint32_t GetTerminalHeight() const; + /// Set the terminal height. void SetTerminalHeight(uint32_t term_height); + /// Get the unique ID of this debugger. lldb::user_id_t GetID(); + /// Get the command prompt string. const char *GetPrompt() const; + /// Set the command prompt string. void SetPrompt(const char *prompt); + /// Get the path to the reproducer. const char *GetReproducerPath() const; + /// Get the current scripting language. lldb::ScriptLanguage GetScriptLanguage() const; + /// Set the current scripting language. void SetScriptLanguage(lldb::ScriptLanguage script_lang); + /// Get the current REPL language. lldb::LanguageType GetREPLLanguage() const; + /// Set the current REPL language. void SetREPLLanguage(lldb::LanguageType repl_lang); + /// Get whether to close input on EOF (deprecated). LLDB_DEPRECATED("SBDebugger::GetCloseInputOnEOF() is deprecated.") bool GetCloseInputOnEOF() const; + /// Set whether to close input on EOF (deprecated). LLDB_DEPRECATED("SBDebugger::SetCloseInputOnEOF() is deprecated.") void SetCloseInputOnEOF(bool b); + /// Get a type category by name. SBTypeCategory GetCategory(const char *category_name); + /// Get a type category by language. SBTypeCategory GetCategory(lldb::LanguageType lang_type); + /// Create a new type category. SBTypeCategory CreateCategory(const char *category_name); + /// Delete a type category. bool DeleteCategory(const char *category_name); + /// Get the number of type categories. uint32_t GetNumCategories(); - SBTypeCategory GetCategoryAtIndex(uint32_t); + /// Get a type category by index. + SBTypeCategory GetCategoryAtIndex(uint32_t index); + /// Get the default type category. SBTypeCategory GetDefaultCategory(); - SBTypeFormat GetFormatForType(SBTypeNameSpecifier); + /// Get the format for a type. + SBTypeFormat GetFormatForType(SBTypeNameSpecifier type_name_spec); - SBTypeSummary GetSummaryForType(SBTypeNameSpecifier); + /// Get the summary for a type. + SBTypeSummary GetSummaryForType(SBTypeNameSpecifier type_name_spec); - SBTypeFilter GetFilterForType(SBTypeNameSpecifier); + /// Get the filter for a type. + SBTypeFilter GetFilterForType(SBTypeNameSpecifier type_name_spec); - SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier); + /// Get the synthetic for a type. + SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier type_name_spec); - /// Clear collected statistics for targets belonging to this debugger. This - /// includes clearing symbol table and debug info parsing/index time for all - /// modules, breakpoint resolve time and target statistics. + /// Clear collected statistics for targets belonging to this debugger. + /// + /// This includes clearing symbol table and debug info parsing/index time for + /// all modules, breakpoint resolve time, and target statistics. void ResetStatistics(); #ifndef SWIG /// Run the command interpreter. /// /// \param[in] auto_handle_events - /// If true, automatically handle resulting events. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, automatically handle resulting events. This takes precedence + /// and overrides the corresponding option in + /// SBCommandInterpreterRunOptions. /// /// \param[in] spawn_thread - /// If true, start a new thread for IO handling. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, start a new thread for IO handling. This takes precedence and + /// overrides the corresponding option in SBCommandInterpreterRunOptions. void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread); #endif - /// Run the command interpreter. + /// Run the command interpreter with options. /// /// \param[in] auto_handle_events - /// If true, automatically handle resulting events. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, automatically handle resulting events. This takes precedence + /// and overrides the corresponding option in + /// SBCommandInterpreterRunOptions. /// /// \param[in] spawn_thread - /// If true, start a new thread for IO handling. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, start a new thread for IO handling. This takes precedence and + /// overrides the corresponding option in SBCommandInterpreterRunOptions. /// /// \param[in] options - /// Parameter collection of type SBCommandInterpreterRunOptions. + /// Parameter collection of type SBCommandInterpreterRunOptions. /// /// \param[out] num_errors - /// The number of errors. + /// The number of errors. /// /// \param[out] quit_requested - /// Whether a quit was requested. + /// Whether a quit was requested. /// /// \param[out] stopped_for_crash - /// Whether the interpreter stopped for a crash. + /// Whether the interpreter stopped for a crash. #ifdef SWIG %apply int& INOUT { int& num_errors }; %apply bool& INOUT { bool& quit_requested }; @@ -497,20 +966,43 @@ class LLDB_API SBDebugger { bool &stopped_for_crash); #ifndef SWIG + /// Run the command interpreter with options and return a result object. + /// + /// \param[in] options + /// Parameter collection of type SBCommandInterpreterRunOptions. + /// + /// \return + /// An SBCommandInterpreterRunResult object containing the result of running + /// the command interpreter. SBCommandInterpreterRunResult RunCommandInterpreter(const SBCommandInterpreterRunOptions &options); #endif + /// Run a REPL (Read-Eval-Print Loop) for the specified language. + /// + /// \param[in] language + /// The language to use for the REPL. + /// + /// \param[in] repl_options + /// Options for the REPL. + /// + /// \return + /// An SBError object indicating success or failure. SBError RunREPL(lldb::LanguageType language, const char *repl_options); - /// Load a trace from a trace description file and create Targets, - /// Processes and Threads based on the contents of such file. + /// Load a trace from a trace description file. + /// + /// This will create Targets, Processes and Threads based on the contents of + /// the file. /// /// \param[out] error /// An error if the trace could not be created. /// /// \param[in] trace_description_file /// The file containing the necessary information to load the trace. + /// + /// \return + /// An SBTrace object representing the loaded trace. SBTrace LoadTraceFromFile(SBError &error, const SBFileSpec &trace_description_file);