LLDB

https://lldb.llvm.org
Admin
LLDB is a next-generation, high-performance debugger built on reusable components from the LLVM...
Tokens:9,219,442
Snippets:92,070
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get Start Configuration Help

Source: https://lldb.llvm.org/cpp_reference/TraceIntelPT_8cpp_source.html

Provides a help message detailing the configuration parameters for starting an Intel PT trace.

```cpp
608const char *TraceIntelPT::GetStartConfigurationHelp() {
609 static std::optional<std::string> message;
610 if (!message) {
611 message.emplace(formatv(R"(Parameters:
612
613 See the jLLDBTraceStart section in lldb/docs/lldb-gdb-remote.txt for a
614 description of each parameter below.
615
616 - int iptTraceSize (defaults to {0} bytes):
617 [process and thread tracing]
619 - boolean enableTsc (default to {1}):
620 [process and thread tracing]
621
622 - int psbPeriod (defaults to {2}):
623 [process and thread tracing]
624
625 - boolean perCpuTracing (default to {3}):
626 [process tracing only]
627
628 - int processBufferSizeLimit (defaults to {4} MiB):
629 [process tracing only]
630
631 - boolean disableCgroupFiltering (default to {5}):
632 [process tracing only])",
633 kDefaultIptTraceSize, kDefaultEnableTscValue,
634 kDefaultPsbPeriod, kDefaultPerCpuTracing,
635 kDefaultProcessBufferSizeLimit / 1024 / 1024,
636 kDefaultDisableCgroupFiltering));
637 }
638 return message->c_str();
639}
```

--------------------------------

### Start

Source: https://lldb.llvm.org/cpp_reference/SBTrace_8cpp_source.html

Starts tracing with the provided configuration.

```cpp
SBError SBTrace::Start(const SBStructuredData &configuration) {
 LLDB_INSTRUMENT_VA(this, configuration);
 SBError error;
 if (!m_opaque_sp)
 error = Status::FromErrorString("error: invalid trace");
 else if (llvm::Error err =
 m_opaque_sp->Start(configuration.m_impl_up->GetObjectSP()))
 error = Status::FromErrorString(llvm::toString(std::move(err)).c_str());
 return error;
}
```

--------------------------------

### Start()

Source: https://lldb.llvm.org/cpp_reference/classlldb__private_1_1Trace.html

Starts tracing a live process using the provided configuration.

```APIDOC
## virtual llvm::Error Start(StructuredData::ObjectSP configuration)

### Description
Starts tracing a live process. The configuration object determines the parameters of the trace.

### Parameters
- **configuration** (StructuredData::ObjectSP) - Optional - Configuration details for the trace session.
```

--------------------------------

### Platform::Install implementation

Source: https://lldb.llvm.org/cpp_reference/Platform_8cpp_source.html

Installs files or directories to the platform, handling path resolution and destination directory setup.

```cpp
Status Platform::Install(const FileSpec &src, const FileSpec &dst) {
Status error;

Log *log = GetLog(LLDBLog::Platform);
LLDB_LOGF(log, "Platform::Install (src='%s', dst='%s')",
src.GetPath().c_str(), dst.GetPath().c_str());
FileSpec fixed_dst(dst);

if (fixed_dst.GetFilename().empty())
fixed_dst.SetFilename(src.GetFilename());

FileSpec working_dir = GetWorkingDirectory();

if (dst) {
if (!dst.GetDirectory().empty()) {
const char first_dst_dir_char = dst.GetDirectory().front();
if (first_dst_dir_char == '/' || first_dst_dir_char == '\\') {
fixed_dst.SetDirectory(dst.GetDirectory());
}
// If the fixed destination file doesn't have a directory yet, then we
// must have a relative path. We will resolve this relative path against
// the platform's working directory
if (fixed_dst.GetDirectory().empty()) {
FileSpec relative_spec;
if (working_dir) {
relative_spec = working_dir;
relative_spec.AppendPathComponent(dst.GetPath());
fixed_dst.SetDirectory(relative_spec.GetDirectory());
} else {
error = Status::FromErrorStringWithFormat(
"platform working directory must be valid for relative path '%s'",
dst.GetPath().c_str());
return error;
}
}
} else {
if (working_dir) {
fixed_dst.SetDirectory(working_dir.GetPath());
} else {
error = Status::FromErrorStringWithFormat(
"platform working directory must be valid for relative path '%s'",
dst.GetPath().c_str());
return error;
}
}
} else {
if (working_dir) {
fixed_dst.SetDirectory(working_dir.GetPath());
} else {
error =
Status::FromErrorString("platform working directory must be valid "
"when destination directory is empty");
return error;
}
}

LLDB_LOGF(log, "Platform::Install (src='%s', dst='%s') fixed_dst='%s'",
src.GetPath().c_str(), dst.GetPath().c_str(),
fixed_dst.GetPath().c_str());

if (GetSupportsRSync()) {
error = PutFile(src, dst);
} else {
namespace fs = llvm::sys::fs;
switch (fs::get_file_type(src.GetPath(), false)) {
case fs::file_type::directory_file: {
llvm::sys::fs::remove(fixed_dst.GetPath());
uint32_t permissions = FileSystem::Instance().GetPermissions(src);
if (permissions == 0)
permissions = eFilePermissionsDirectoryDefault;
```

--------------------------------

### SBProtocolServer Start Method

Source: https://lldb.llvm.org/cpp_reference/SBProtocolServer_8cpp_source.html

Starts the protocol server with a connection URI.

```cpp
SBError SBProtocolServer::Start(const char *connection_uri) {
 LLDB_INSTRUMENT_VA(this, connection_uri);

 SBError error;
 if (!m_opaque_up->server) {
 error.SetErrorString("invalid protocol server");
 return error;
 }

 const char *connection_error =
 "unsupported connection specifier, expected 'accept:///path' or "
 "'listen://[host]:port'";
 std::optional<URI> uri = URI::Parse(connection_uri ? connection_uri : "");
 if (!uri) {
 error.SetErrorString(connection_error);
 return error;
 }

 std::optional<Socket::ProtocolModePair> protocol_and_mode =
 Socket::GetProtocolAndMode(uri->scheme);
 if (!protocol_and_mode || protocol_and_mode->second != Socket::ModeAccept) {
 error.SetErrorString(connection_error);
 return error;
 }

 ProtocolServer::Connection connection;
```

--------------------------------

### Start

Source: https://lldb.llvm.org/cpp_reference/Trace_8h_source.html

Starts tracing a live process.

```APIDOC
## virtual llvm::Error Start(StructuredData::ObjectSP configuration)

### Description
Starts tracing a live process using the provided configuration.

### Parameters
- **configuration** (StructuredData::ObjectSP) - Optional configuration object.
```

--------------------------------

### Start(const char * connection_uri)

Source: https://lldb.llvm.org/cpp_reference/classlldb_1_1SBProtocolServer.html

Starts listening for clients on the specified connection URI.

```APIDOC
## SBError Start(const char * connection_uri)

### Description
Starts listening for clients on `connection_uri`. The URI must be an accepting URI such as "listen://[host]:port" or "accept:///path".

### Parameters
- **connection_uri** (const char *) - The URI to listen on.
```

--------------------------------

### RunCommandInterpreter Example

Source: https://lldb.llvm.org/python_api/lldb.SBDebugger.html

Demonstrates how to start an interactive LLDB session from a Python script using a pre-existing debugger object.

```python
# Start an interactive lldb session from a script (with a valid debugger object
# created beforehand):
n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True,
    False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)
```

--------------------------------

### Start (Live Tracing)

Source: https://lldb.llvm.org/cpp_reference/TraceIntelPT_8h_source.html

Starts tracing live threads with specified configuration parameters.

```APIDOC
## Start(uint64_t ipt_trace_size, uint64_t total_buffer_size_limit, bool enable_tsc, std::optional<uint64_t> psb_period, bool m_per_cpu_tracing, bool disable_cgroup_filtering)

### Description
Starts an Intel PT trace session with specific buffer and timing configurations.

### Parameters
- **ipt_trace_size** (uint64_t) - Trace size per thread or per cpu core in bytes.
- **total_buffer_size_limit** (uint64_t) - Maximum total trace size per process in bytes.
- **enable_tsc** (bool) - Whether to use enable TSC timestamps or not.
- **psb_period** (std::optional<uint64_t>) - The period in which PSB packets will be generated.
- **m_per_cpu_tracing** (bool) - Defines whether to have an intel pt trace buffer per thread or per cpu core.
- **disable_cgroup_filtering** (bool) - Disable the cgroup filtering that is automatically applied when doing per cpu tracing.

### Returns
- **llvm::Error** - Returns llvm::Error::success if successful, otherwise an error.
```

--------------------------------

### Install dependencies in QEMU

Source: https://lldb.llvm.org/resources/qemu-testing.html

Install the required development libraries inside the emulation environment.

```bash
$ sudo apt install python-dev libedit-dev libncurses5-dev libexpat1-dev
```

--------------------------------

### Setup Frontend Action and Parser

Source: https://lldb.llvm.org/cpp_reference/ClangModulesDeclVendor_8cpp_source.html

This snippet completes the setup by configuring the frontend action, target info, and initializing the parser for the Clang module vendor.

```cpp
std::unique_ptr<clang::FrontendAction> action(new clang::SyntaxOnlyAction);

instance->setTarget(clang::TargetInfo::CreateTargetInfo(
*diagnostics_engine, instance->getInvocation().getTargetOpts()));

if (!instance->hasTarget())
return nullptr;

instance->getTarget().adjust(*diagnostics_engine, instance->getLangOpts(),
/*AuxTarget=*/nullptr);

if (!action->BeginSourceFile(*instance,
instance->getFrontendOpts().Inputs[0]))
return nullptr;

instance->createASTReader();

instance->createSema(action->getTranslationUnitKind(), nullptr);

const bool skipFunctionBodies = false;
std::unique_ptr<clang::Parser> parser(new clang::Parser(
instance->getPreprocessor(), instance->getSema(), skipFunctionBodies));

instance->getPreprocessor().EnterMainSourceFile();
parser->Initialize();

clang::Parser::DeclGroupPtrTy parsed;
auto ImportState = clang::Sema::ModuleImportState::NotACXX20Module;
while (!parser->ParseTopLevelDecl(parsed, ImportState))
;

return new ClangModulesDeclVendorImpl(
std::move(diag_options_up), std::move(diagnostics_engine),
std::move(invocation), std::move(instance), std::move(parser));
```

--------------------------------

### Package and install the extension

Source: https://lldb.llvm.org/resources/lldbdap-contributing.html

Commands to compile and install the extension locally from the extension directory.

```bash
cd /path/to/lldb/tools/lldb-dap/extension
npm install
npm run package # This also compiles the extension.
npm run vscode-install
```

--------------------------------

### Get help for LLDB commands

Source: https://lldb.llvm.org/man/lldb.html

Use the help command to find descriptions and examples for specific commands.

```text
help breakpoint set
```

--------------------------------

### Install

Source: https://lldb.llvm.org/python_api/lldb.SBTarget.html

Installs binaries on a remote platform. Does nothing on the host system.

```APIDOC
## Install(self)

### Description
Installs any binaries that need to be installed. When connected to remote platforms, the target's main executable and modules with an install path are installed on the remote platform.

### Returns
- **SBError** - An error object describing any issues during installation.
```

--------------------------------

### Install

Source: https://lldb.llvm.org/cpp_reference/Platform_8h_source.html

Installs a file or directory on the remote system.

```APIDOC
## Status Install(const FileSpec &src, const FileSpec &dst)

### Description
Installs a file or directory on the remote system. If the destination path is relative, it is prepended with the platform working directory.

### Parameters
- **src** (FileSpec) - Required - The source file or directory to install.
- **dst** (FileSpec) - Required - The destination path on the remote system.

### Returns
- **Status** - An error object describing any issues encountered during installation.
```

--------------------------------

### Install system prerequisites for documentation

Source: https://lldb.llvm.org/resources/build.html

Install the necessary system-level tools on Debian/Ubuntu to support documentation generation.

```bash
$ sudo apt-get install doxygen graphviz swig
```

--------------------------------

### Start

Source: https://lldb.llvm.org/cpp_reference/IntelPTSingleBufferTrace_8h_source.html

Starts tracing using a single Intel PT trace buffer.

```APIDOC
## static llvm::Expected< IntelPTSingleBufferTrace > Start(const TraceIntelPTStartRequest &request, std::optional< lldb::tid_t > tid, std::optional< lldb::cpu_id_t > cpu_id=std::nullopt, bool disabled=false, std::optional< int > cgroup_fd=std::nullopt)

### Description
Starts tracing using a single Intel PT trace buffer based on the provided request and optional thread or CPU identifiers.

### Parameters
- **request** (const TraceIntelPTStartRequest &) - Required - The configuration request for the Intel PT trace.
- **tid** (std::optional< lldb::tid_t >) - Optional - The thread ID to trace.
- **cpu_id** (std::optional< lldb::cpu_id_t >) - Optional - The CPU ID to trace.
- **disabled** (bool) - Optional - Whether the trace should start in a disabled state.
- **cgroup_fd** (std::optional< int >) - Optional - The file descriptor for the cgroup.
```

--------------------------------

### SBProtocolServer.Start

Source: https://lldb.llvm.org/python_api/lldb.SBProtocolServer.html

Starts the server listener.

```APIDOC
## Start(connection_uri)

### Description
Starts listening for incoming client connections on the specified URI. The URI must be an accepting format such as "listen://[host]:port" or "accept:///path".

### Parameters
- **connection_uri** (string) - The URI string to listen on.
```

--------------------------------

### GDB Breakpoint Examples

Source: https://lldb.llvm.org/use/tutorial.html

Examples of setting breakpoints in GDB for comparison.

```text
(gdb) break foo.c:12
```

```text
(gdb) break foo
```

--------------------------------

### Example dotest.py command options for Windows

Source: https://lldb.llvm.org/resources/test.html

Example arguments for configuring the test suite execution in Visual Studio, provided as a list of flags and paths.

```text
--arch=i686
# Path to debug lldb.exe
--executable D:/src/llvmbuild/ninja/bin/lldb.exe
# Directory to store log files
-s D:/src/llvmbuild/ninja/lldb-test-traces
-u CXXFLAGS -u CFLAGS
# If a test crashes, show JIT debugging dialog.
--enable-crash-dialog
# Path to release clang.exe
-C d:\src\llvmbuild\ninja_release\bin\clang.exe
# Path to the particular test you want to debug.
-p TestPaths.py
# Root of test tree
D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test
```

--------------------------------

### Get Start Address of SBLineEntry

Source: https://lldb.llvm.org/python_reference/lldb.SBLineEntry-class.html

Retrieves the starting SBAddress associated with the SBLineEntry. This indicates the beginning of the instruction range.

```python
GetStartAddress(SBLineEntry self) -> SBAddress
```

--------------------------------

### SBTarget Install

Source: https://lldb.llvm.org/python_reference/lldb.SBTarget-class.html

Installs the target. This operation might be used in specific debugging scenarios to finalize target setup.

```python
Install(self) -> SBError
```

--------------------------------

### IOHandlerCursesGUI Activation and Menu Setup

Source: https://lldb.llvm.org/cpp_reference/IOHandlerCursesGUI_8cpp_source.html

Initializes the application, creates the main window, and populates the menu bar with LLDB, Target, Process, Thread, View, and Help menus.

```cpp
7615void IOHandlerCursesGUI::Activate() {
7616 IOHandler::Activate();
7617 if (!m_app_up) {
7618 m_app_up = std::make_unique<Application>(
7619 m_input_sp ? m_input_sp->GetStream() : nullptr,
7620 m_output_sp ? m_input_sp->GetStream() : nullptr);
7621
7622 // This is both a window and a menu delegate
7623 std::shared_ptr<ApplicationDelegate> app_delegate_sp(
7624 new ApplicationDelegate(*m_app_up, m_debugger));
7625
7626 MenuDelegateSP app_menu_delegate_sp =
7627 std::static_pointer_cast<MenuDelegate>(app_delegate_sp);
7628 MenuSP lldb_menu_sp(
7629 new Menu("LLDB", "F1", KEY_F(1), ApplicationDelegate::eMenuID_LLDB));
7630 MenuSP exit_menuitem_sp(
7631 new Menu("Exit", nullptr, 'x', ApplicationDelegate::eMenuID_LLDBExit));
7632 exit_menuitem_sp->SetCannedResult(MenuActionResult::Quit);
7633 lldb_menu_sp->AddSubmenu(std::make_shared<Menu>(
7634 "About LLDB", nullptr, 'a', ApplicationDelegate::eMenuID_LLDBAbout));
7635 lldb_menu_sp->AddSubmenu(std::make_shared<Menu>(Menu::Type::Separator));
7636 lldb_menu_sp->AddSubmenu(exit_menuitem_sp);
7637
7638 MenuSP target_menu_sp(new Menu("Target", "F2", KEY_F(2),
7639 ApplicationDelegate::eMenuID_Target));
7640 target_menu_sp->AddSubmenu(std::make_shared<Menu>(
7641 "Create", nullptr, 'c', ApplicationDelegate::eMenuID_TargetCreate));
7642 target_menu_sp->AddSubmenu(std::make_shared<Menu>(
7643 "Delete", nullptr, 'd', ApplicationDelegate::eMenuID_TargetDelete));
7644
7645 MenuSP process_menu_sp(new Menu("Process", "F3", KEY_F(3),
7646 ApplicationDelegate::eMenuID_Process));
7647 process_menu_sp->AddSubmenu(std::make_shared<Menu>(
7648 "Attach", nullptr, 'a', ApplicationDelegate::eMenuID_ProcessAttach));
7649 process_menu_sp->AddSubmenu(std::make_shared<Menu>(
7650 "Detach and resume", nullptr, 'd',
7651 ApplicationDelegate::eMenuID_ProcessDetachResume));
7652 process_menu_sp->AddSubmenu(std::make_shared<Menu>(
7653 "Detach suspended", nullptr, 's',
7654 ApplicationDelegate::eMenuID_ProcessDetachSuspended));
7655 process_menu_sp->AddSubmenu(std::make_shared<Menu>(
7656 "Launch", nullptr, 'l', ApplicationDelegate::eMenuID_ProcessLaunch));
7657 process_menu_sp->AddSubmenu(std::make_shared<Menu>(Menu::Type::Separator));
7658 process_menu_sp->AddSubmenu(
7659 std::make_shared<Menu>("Continue", nullptr, 'c',
7660 ApplicationDelegate::eMenuID_ProcessContinue));
7661 process_menu_sp->AddSubmenu(std::make_shared<Menu>(
7662 "Halt", nullptr, 'h', ApplicationDelegate::eMenuID_ProcessHalt));
7663 process_menu_sp->AddSubmenu(std::make_shared<Menu>(
7664 "Kill", nullptr, 'k', ApplicationDelegate::eMenuID_ProcessKill));
7665
7666 MenuSP thread_menu_sp(new Menu("Thread", "F4", KEY_F(4),
7667 ApplicationDelegate::eMenuID_Thread));
7668 thread_menu_sp->AddSubmenu(std::make_shared<Menu>(
7669 "Step In", nullptr, 'i', ApplicationDelegate::eMenuID_ThreadStepIn));
7670 thread_menu_sp->AddSubmenu(
7671 std::make_shared<Menu>("Step Over", nullptr, 'v',
7672 ApplicationDelegate::eMenuID_ThreadStepOver));
7673 thread_menu_sp->AddSubmenu(std::make_shared<Menu>(
7674 "Step Out", nullptr, 'o', ApplicationDelegate::eMenuID_ThreadStepOut));
7675
7676 MenuSP view_menu_sp(
7677 new Menu("View", "F5", KEY_F(5), ApplicationDelegate::eMenuID_View));
7678 view_menu_sp->AddSubmenu(std::make_shared<Menu>(
7679 "Backtrace", nullptr, 't', ApplicationDelegate::eMenuID_ViewBacktrace));
7680 view_menu_sp->AddSubmenu(std::make_shared<Menu>(
7681 "Registers", nullptr, 'r', ApplicationDelegate::eMenuID_ViewRegisters));
7682 view_menu_sp->AddSubmenu(std::make_shared<Menu>(
7683 "Source", nullptr, 's', ApplicationDelegate::eMenuID_ViewSource));
7684 view_menu_sp->AddSubmenu(std::make_shared<Menu>(
7685 "Variables", nullptr, 'v', ApplicationDelegate::eMenuID_ViewVariables));
7686 view_menu_sp->AddSubmenu(
7687 std::make_shared<Menu>("Breakpoints", nullptr, 'b',
7688 ApplicationDelegate::eMenuID_ViewBreakpoints));
7689
7690 MenuSP help_menu_sp(
7691 new Menu("Help", "F6", KEY_F(6), ApplicationDelegate::eMenuID_Help));
7692 help_menu_sp->AddSubmenu(std::make_shared<Menu>(
7693 "GUI Help", nullptr, 'g', ApplicationDelegate::eMenuID_HelpGUIHelp));
7694
7695 m_app_up->Initialize();
7696 WindowSP &main_window_sp = m_app_up->GetMainWindow();
7697
7698 MenuSP menubar_sp(new Menu(Menu::Type::Bar));
7699 menubar_sp->AddSubmenu(lldb_menu_sp);
7700 menubar_sp->AddSubmenu(target_menu_sp);
7701 menubar_sp->AddSubmenu(process_menu_sp);
7702 menubar_sp->AddSubmenu(thread_menu_sp);
7703 menubar_sp->AddSubmenu(view_menu_sp);
7704 menubar_sp->AddSubmenu(help_menu_sp);
7705 menubar_sp->SetDelegate(app_menu_delegate_sp);
```

--------------------------------

### Getting Remote Install File Specification for SBModule

Source: https://lldb.llvm.org/python_reference/lldb.SBModule-class.html

Demonstrates how to retrieve the file specification for a module that has been installed on a remote system. This is relevant in cross-debugging scenarios.

```python
GetRemoteInstallFileSpec(SBModule self) -> SBFileSpec
```

--------------------------------

### Get Start Address

Source: https://lldb.llvm.org/cpp_reference/DynamicLoaderDarwin_8cpp_source.html

Retrieves the address of the _dyld_start symbol from the DYLD module.

```cpp
std::optional<lldb_private::Address> DynamicLoaderDarwin::GetStartAddress() {
  Log *log = GetLog(LLDBLog::DynamicLoader);

  auto log_err = [log](llvm::StringLiteral err_msg) -> std::nullopt_t {
    LLDB_LOG_VERBOSE(log, "{}", err_msg);
    return std::nullopt;
  };

  ModuleSP dyld_sp = GetDYLDModule();
  if (!dyld_sp)
    return log_err("Couldn't retrieve DYLD module. Cannot get `start` symbol.");

  const Symbol *symbol =
      dyld_sp->FindFirstSymbolWithNameAndType(ConstString("_dyld_start"));
  if (!symbol)
    return log_err("Cannot find `start` symbol in DYLD module.");

  return symbol->GetAddress();
}
```

--------------------------------

### DoLaunch method

Source: https://lldb.llvm.org/cpp_reference/ProcessGDBRemote_8cpp_source.html

Launches a new process.

```cpp
Status DoLaunch(Module *exe_module, ProcessLaunchInfo &launch_info) override
```

--------------------------------

### GetStartConfigurationHelp

Source: https://lldb.llvm.org/cpp_reference/Trace_8h_source.html

Returns a description of parameters for the Trace::Start method.

```cpp
virtual const char *GetStartConfigurationHelp() = 0;
```

--------------------------------

### Trace GetProcessTraceStartCommand Method

Source: https://lldb.llvm.org/cpp_reference/CommandObjectProcess_8cpp_source.html

Gets the command handle for starting process tracing.

```cpp
virtual lldb::CommandObjectSP GetProcessTraceStartCommand(CommandInterpreter &interpreter)=0
```

--------------------------------

### DoExecute Method for Protocol Server Start

Source: https://lldb.llvm.org/cpp_reference/CommandObjectProtocolServer_8cpp_source.html

Implements the logic to parse arguments, validate the protocol, parse the connection URI, and start the server.

```cpp
protected:
 void DoExecute(Args &args, CommandReturnObject &result) override {
 if (args.GetArgumentCount() < 1) {
 result.AppendError("no protocol specified");
 return;
 }

 llvm::StringRef protocol = args.GetArgumentAtIndex(0);
 ProtocolServer *server = ProtocolServer::GetOrCreate(protocol);
 if (!server) {
 result.AppendErrorWithFormatv(
 "unsupported protocol: {0}. Supported protocols are: {1}", protocol,
 llvm::join(ProtocolServer::GetSupportedProtocols(), ", "));
 return;
 }

 std::string connection_uri = "listen://[localhost]:0";
 if (args.GetArgumentCount() >= 2)
 connection_uri = args.GetArgumentAtIndex(1);

 const char *connection_error =
 "unsupported connection specifier, expected 'accept:///path' "
 "or 'listen://[host]:port', got '{0}'.";
 auto uri = lldb_private::URI::Parse(connection_uri);
 if (!uri) {
 result.AppendErrorWithFormatv(connection_error, connection_uri);
 return;
 }

 std::optional<Socket::ProtocolModePair> protocol_and_mode =
 Socket::GetProtocolAndMode(uri->scheme);
 if (!protocol_and_mode || protocol_and_mode->second != Socket::ModeAccept) {
 result.AppendErrorWithFormatv(connection_error, connection_uri);
 return;
 }

 ProtocolServer::Connection connection;
 connection.protocol = protocol_and_mode->first;
 if (connection.protocol == Socket::SocketProtocol::ProtocolUnixDomain)
 connection.name = uri->path;
 else
 connection.name = formatv(
 "[{0}]:{1}", uri->hostname.empty() ? "0.0.0.0" : uri->hostname,
 uri->port.value_or(0));

 if (llvm::Error error = server->Start(connection)) {
 result.AppendErrorWithFormatv("{0}", llvm::fmt_consume(std::move(error)));
 return;
 }

 if (Socket *socket = server->GetSocket()) {
 std::string address =
 llvm::join(socket->GetListeningConnectionURI(), ", ");
 result.AppendMessageWithFormatv(
 "{0} server started with connection listeners: {1}", protocol,
 address);
 }
 result.SetStatus(eReturnStatusSuccessFinishNoResult);
 }
```

--------------------------------

### CommandObjectProtocolServer Constructor

Source: https://lldb.llvm.org/cpp_reference/CommandObjectProtocolServer_8cpp_source.html

Initializes the multiword command object and registers the start, stop, and get subcommands.

```cpp
CommandObjectProtocolServer::CommandObjectProtocolServer(
 CommandInterpreter &interpreter)
 : CommandObjectMultiword(interpreter, "protocol-server",
 "Start, stop, and query protocol servers.",
 "protocol-server") {
 LoadSubCommand("start", CommandObjectSP(new CommandObjectProtocolServerStart(
 interpreter)));
 LoadSubCommand("stop", CommandObjectSP(
 new CommandObjectProtocolServerStop(interpreter)));
 LoadSubCommand(
 "get", CommandObjectSP(new CommandObjectProtocolServerGet(interpreter)));
}

CommandObjectProtocolServer::~CommandObjectProtocolServer() = default;
```

--------------------------------

### Get Offset of SBAddress

Source: https://lldb.llvm.org/python_reference/lldb.SBAddress-class.html

Retrieves the offset of the SBAddress from its section. This is the address relative to the start of the section.

```python
address.GetOffset()
```

--------------------------------

### SBTrace::GetStartConfigurationHelp

Source: https://lldb.llvm.org/cpp_reference/SBTrace_8h_source.html

Retrieves help information for trace start parameters.

```cpp
const char * GetStartConfigurationHelp()
```

--------------------------------

### jAcceleratorPluginInitialize Example Response

Source: https://lldb.llvm.org/resources/lldbgdbremote.html

An example of a successful response containing a single accelerator plugin configuration.

```json
LLDB SENDS:    jAcceleratorPluginInitialize
STUB REPLIES:  [{"plugin_name":"amdgpu","session_name":"AMD GPU Session","identifier":0}]
```

--------------------------------

### DidLaunch Method

Source: https://lldb.llvm.org/cpp_reference/DynamicLoaderDarwin_8cpp_source.html

Executes initialization steps after launching a process, including fetching initial images and setting notification breakpoints.

```cpp
void DynamicLoaderDarwin::DidLaunch() {
 PrivateInitialize(m_process);
 DoInitialImageFetch();
 SetNotificationBreakpoint();
}
```

--------------------------------

### Start MCP Server with Custom URI

Source: https://lldb.llvm.org/use/mcp.html

Starts an MCP server listening on a specific host and port.

```text
(lldb) protocol-server start MCP listen://localhost:59999
```

--------------------------------

### InstallContext Method

Source: https://lldb.llvm.org/cpp_reference/UserExpression_8h_source.html

Populates context information based on the environment.

```cpp
void InstallContext(ExecutionContext &exe_ctx);
```

--------------------------------

### SBTrace::GetStartConfigurationHelp

Source: https://lldb.llvm.org/cpp_reference/classlldb_1_1SBTrace.html

Returns a description of the parameters to use for the SBTrace::Start method.

```APIDOC
## const char * SBTrace::GetStartConfigurationHelp()

### Description
Returns a description of the parameters to use for the SBTrace::Start method, or null if the object is invalid.
```

--------------------------------

### Get File Address

Source: https://lldb.llvm.org/python_reference/lldb.SBSection-class.html

Returns the file address of the section. This is the address where the section's content starts in the executable file on disk.

```python
GetFileAddress(SBSection self) -> lldb::addr_t
```

--------------------------------

### Launch Process with SBError

Source: https://lldb.llvm.org/python_reference/lldb.SBError-class.html

This example demonstrates launching a process and verifying its success using SBError. It's used when starting a new program to be debugged.

```python
# Assuming target is an initialized lldb.SBTarget instance
# Assuming listener is an initialized lldb.SBListener instance
# Assuming PROCESS_IS_VALID is a defined constant

error = lldb.SBError()
process = target.Launch(listener, None, None, None, None, None, None, 0, False, error)
self.assertTrue(error.Success() and process, PROCESS_IS_VALID)
```

--------------------------------

### Getting SBModule File Specifications

Source: https://lldb.llvm.org/python_reference/lldb.SBModule-class.html

Provides examples for retrieving the file specifications associated with an SBModule. This includes the local file specification and the platform-specific file specification.

```python
GetFileSpec(SBModule self) -> SBFileSpec
```

```python
GetPlatformFileSpec(SBModule self) -> SBFileSpec
```

--------------------------------

### InstallContext Method

Source: https://lldb.llvm.org/cpp_reference/UserExpression_8cpp_source.html

Sets up the execution context for the expression by capturing the process and the current stack frame's code address.

```cpp
void UserExpression::InstallContext(ExecutionContext &exe_ctx) {
 m_jit_process_wp = exe_ctx.GetProcessSP();

 lldb::StackFrameSP frame_sp = exe_ctx.GetFrameSP();

 if (frame_sp)
 m_address = frame_sp->GetFrameCodeAddress();
}
```

--------------------------------

### Start lldb-server in platform mode

Source: https://lldb.llvm.org/use/remote.html

Run this command on the remote system to start the LLDB platform and listen for incoming connections on a specified port.

```bash
remote% lldb-server platform --listen "*:1234" --server
```

--------------------------------

### Loading Platform Binary and Setup

Source: https://lldb.llvm.org/cpp_reference/PlatformDarwinKernel_8cpp_source.html

Configures the target platform and dynamic loader for a kernel debug session if a valid kernel binary is found.

```cpp
bool PlatformDarwinKernel::LoadPlatformBinaryAndSetup(Process *process,
lldb::addr_t input_addr,
bool notify) {
Log *log =
GetLog(LLDBLog::Platform | LLDBLog::DynamicLoader | LLDBLog::Process);

if (!process)
return false;

addr_t actual_address = find_kernel_in_macho_fileset(process, input_addr);

if (actual_address == LLDB_INVALID_ADDRESS)
return false;

LLDB_LOGF(log,
"PlatformDarwinKernel::%s check address 0x%" PRIx64 " for "
"a macho fileset, got back kernel address 0x%" PRIx64,
__FUNCTION__, input_addr, actual_address);

// We have a xnu kernel binary, this is a kernel debug session.
// Set the Target's Platform to be PlatformDarwinKernel, and the
// Process' DynamicLoader to be DynamicLoaderDarwinKernel.

PlatformSP platform_sp =
process->GetTarget().GetDebugger().GetPlatformList().Create(
PlatformDarwinKernel::GetPluginNameStatic());
if (platform_sp)
process->GetTarget().SetPlatform(platform_sp);

DynamicLoaderUP dyld_up =
std::make_unique<DynamicLoaderDarwinKernel>(process, actual_address);
if (!dyld_up)
return false;

// Process owns it now
process->SetDynamicLoader(std::move(dyld_up));

return true;
}
```

--------------------------------

### Start tracing a specific thread

Source: https://lldb.llvm.org/cpp_reference/SBTrace_8h_source.html

Starts tracing a specific thread using a provided configuration. This is equivalent to the 'thread trace start' command.

```cpp
SBError Start(const SBThread &thread, const SBStructuredData &configuration);
```

--------------------------------

### Start SBCommunication Read Thread

Source: https://lldb.llvm.org/python_reference/lldb.SBCommunication-class.html

Starts a dedicated thread for reading data from the communication channel. Returns true if the thread started successfully.

```python
ReadThreadStart(self) -> bool
```

--------------------------------

### SBTrace.GetStartConfigurationHelp

Source: https://lldb.llvm.org/python_api/lldb.SBTrace.html

Retrieves help information for trace configuration parameters.

```APIDOC
## SBTrace.GetStartConfigurationHelp()

### Description
Returns a description of the parameters to use for the SBTrace::Start method.

### Returns
- **string** - A description of the parameters, or null if the object is invalid.
```

--------------------------------

### Server Constructor

Source: https://lldb.llvm.org/cpp_reference/Server_8cpp_source.html

Initializes a new Server instance with a name, version, and log callback.

```cpp
133Server::Server(std::string name, std::string version, LogCallback log_callback)
134 : m_name(std::move(name)), m_version(std::move(version)),
135 m_log_callback(std::move(log_callback)) {}
```

--------------------------------

### InstallASTContext method

Source: https://lldb.llvm.org/cpp_reference/ClangASTSource_8cpp_source.html

Configures the AST context and registers the current source with the AST importer.

```cpp
void ClangASTSource::InstallASTContext(TypeSystemClang &clang_ast_context) {
 m_ast_context = &clang_ast_context.getASTContext();
 m_clang_ast_context = &clang_ast_context;
 m_file_manager = &m_ast_context->getSourceManager().getFileManager();
 m_ast_importer_sp->InstallMapCompleter(m_ast_context, *this);
}
```

--------------------------------

### Address::DumpStyleFileAddress Example

Source: https://lldb.llvm.org/cpp_reference/Address_8h_source.html

Example output for the DumpStyleFileAddress dump style.

```cpp
// address for printf in libSystem.B.dylib as a file address
0x000000000005dcff
```

--------------------------------

### Address::DumpStyleSectionPointerOffset Example

Source: https://lldb.llvm.org/cpp_reference/Address_8h_source.html

Example output for the DumpStyleSectionPointerOffset dump style.

```cpp
// address for printf in libSystem.B.dylib as a section pointer +
// offset (lldb::Section *)0x35cc50 + 0x000000000005cfdf
```

--------------------------------

### SetupLangOpts Utility

Source: https://lldb.llvm.org/cpp_reference/ClangExpressionParser_8cpp_source.html

Sets up language options for the Clang compiler instance.

```cpp
static void SetupLangOpts(CompilerInstance &compiler, ExecutionContextScope &exe_scope, const Expression &expr, DiagnosticManager &diagnostic_manager)
```

--------------------------------

### LaunchPlatformServer Method

Source: https://lldb.llvm.org/cpp_reference/PlatformWebInspectorWasm_8cpp_source.html

Configures and launches the platform server process, then attempts to connect to it via a socket.

```cpp
92 args.AppendArgument(llvm::utostr(platform_port));
93 args.AppendArgument("--debugserver");
94 args.AppendArgument(llvm::utostr(debugserver_port));
95 launch_info.SetArguments(args, /*first_arg_is_executable=*/true);
96 launch_info.SetLaunchInSeparateProcessGroup(true);
97 launch_info.GetFlags().Clear(eLaunchFlagDebug);
98
99 launch_info.SetMonitorProcessCallback(
100 [log](lldb::pid_t pid, int signal, int status) {
101 LLDB_LOG(log,
102 "Platform exited: pid = {0}, signal = "
103 "{1}, status = {2}",
104 pid, signal, status);
105 });
106
107 LLDB_LOG(log, "{0}", GetArgRange(launch_info.GetArguments()));
108
109 Status status = Host::LaunchProcess(launch_info);
110 if (status.Fail())
111 return status.takeError();
112
113 m_server_pid = launch_info.GetProcessID();
114 LLDB_LOG(log, "Platform launched: pid = {0}", m_server_pid);
115
116 Args connect_args;
117 connect_args.AppendArgument(
118 llvm::formatv("connect://localhost:{0}", platform_port).str());
119
120 // The platform may need some time to bind a socket to the requested port.
121 for (uint8_t attempt = 0; attempt < kConnectAttempts; attempt++) {
122 status = PlatformWasm::ConnectRemote(connect_args);
123 if (status.Success())
124 return llvm::Error::success();
125
126 LLDB_LOG(
127 log,
128 "[{0}/{1}] platform not yet listening on port {2}: trying again in {3}",
129 attempt, kConnectAttempts, platform_port, kConnectDelay);
130 std::this_thread::sleep_for(kConnectDelay);
131 }
132 return status.takeError();
133}
```

--------------------------------

### Address::DumpStyleSectionNameOffset Example

Source: https://lldb.llvm.org/cpp_reference/Address_8h_source.html

Example output for the DumpStyleSectionNameOffset dump style.

```cpp
// address for printf in libSystem.B.dylib as a section name + offset
libSystem.B.dylib.__TEXT.__text + 0x0005cfdf
```

--------------------------------

### Python API Example for SBCommandInterpreter

Source: https://lldb.llvm.org/python_reference/lldb.SBCommandInterpreter-class.html

This example demonstrates how to create a target, retrieve the command interpreter, and use its methods to check for commands, aliases, and execute debugger commands.

```python
import lldb
import os


def command_interpreter_api(self):
    '''Test the SBCommandInterpreter APIs.'''
    exe = os.path.join(os.getcwd(), 'a.out')

    # Create a target by the debugger.
    target = self.dbg.CreateTarget(exe)
    self.assertTrue(target, VALID_TARGET)

    # Retrieve the associated command interpreter from our debugger.
    ci = self.dbg.GetCommandInterpreter()
    self.assertTrue(ci, VALID_COMMAND_INTERPRETER)

    # Exercise some APIs....

    self.assertTrue(ci.HasCommands())
    self.assertTrue(ci.HasAliases())
    self.assertTrue(ci.HasAliasOptions())
    self.assertTrue(ci.CommandExists('breakpoint'))
    self.assertTrue(ci.CommandExists('target'))
    self.assertTrue(ci.CommandExists('platform'))
    self.assertTrue(ci.AliasExists('file'))
    self.assertTrue(ci.AliasExists('run'))
    self.assertTrue(ci.AliasExists('bt'))

    res = lldb.SBCommandReturnObject()
    ci.HandleCommand('breakpoint set -f main.c -l %d' % self.line, res)
    self.assertTrue(res.Succeeded())
    ci.HandleCommand('process launch', res)
    self.assertTrue(res.Succeeded())

    process = ci.GetProcess()
    self.assertTrue(process)

    ...
```

--------------------------------

### jAcceleratorPluginBreakpointHit Example

Source: https://lldb.llvm.org/resources/lldbgdbremote.html

An example of the JSON request and response for the jAcceleratorPluginBreakpointHit packet.

```json
LLDB SENDS:    jAcceleratorPluginBreakpointHit:{"plugin_name":"mock","breakpoint":{"identifier":1,"symbol_names":[]},"symbol_values":[]}
STUB REPLIES:  {"disable_bp":true,"auto_resume_native":false,"actions":{"plugin_name":"mock","session_name":"","identifier":2,"breakpoints":[{"identifier":2,"by_name":{"function_name":"exit"},"symbol_names":[]}]}}
```

--------------------------------

### Initialize()

Source: https://lldb.llvm.org/cpp_reference/classlldb__private_1_1FileSystem.html

Initializes the FileSystem instance.

```APIDOC
## Initialize()

### Description
Initializes the FileSystem singleton.

### Signature
`template<class... T> void Initialize(T &&... t)`
```

--------------------------------

### lldb::SBTarget::Install

Source: https://lldb.llvm.org/cpp_reference/SBTarget_8cpp_source.html

Installs any binaries associated with the target that require installation.

```APIDOC
## SBError Install()

### Description
Install any binaries that need to be installed.
```

--------------------------------

### void PopulateServer(lldb_protocol::mcp::Server &server)

Source: https://lldb.llvm.org/cpp_reference/namespacelldb__private_1_1mcp.html

Installs the standard LLDB tool and resource-provider set on the specified server instance.

```APIDOC
## void PopulateServer(lldb_protocol::mcp::Server &server)

### Description
Installs the standard LLDB tool and resource-provider set on the provided `server` object. This ensures that every MCP server remains consistent, regardless of whether it runs in a plugin or is hosted in-process by an embedder.

### Parameters
- **server** (lldb_protocol::mcp::Server &) - Required - The server instance to be populated with standard tools and resource providers.
```

--------------------------------

### Implement setup_command_definition

Source: https://lldb.llvm.org/use/tutorials/writing-custom-commands.html

This method is called when the command is added to LLDB to define options and their types.

```python
def setup_command_definition(self):
```

--------------------------------

### lldb_private::ExecutionContext::GetFrameSP

Source: https://lldb.llvm.org/cpp_reference/ScriptInterpreterLua_8cpp_source.html

Get accessor to get the frame shared pointer.

```cpp
const lldb::StackFrameSP & GetFrameSP() const
```

--------------------------------

### StartTrace

Source: https://lldb.llvm.org/python_reference/lldb.SBProcess-class.html

Starts tracing the process with specified options.

```APIDOC
## StartTrace

### Description
Starts tracing the process with specified options.

### Method
SBProcess.StartTrace(SBTraceOptions options, SBError error)

### Parameters
* **options** (SBTraceOptions) - The tracing options.
* **error** (SBError) - An SBError object to store any error information.
```

--------------------------------

### GetValueForVariablePath pointer dereference examples

Source: https://lldb.llvm.org/python_api/lldb.SBFrame.html

Examples of variable paths for pointer dereferences.

```text
*this->foo_ptr
**argv
```

--------------------------------

### Initialize

Source: https://lldb.llvm.org/cpp_reference/PlatformWindows_8cpp_source.html

Registers the Windows platform plugin and sets the host platform if running on Windows.

```cpp
void PlatformWindows::Initialize() {
 Platform::Initialize();

 if (g_initialize_count++ == 0) {
#if defined(_WIN32)
 // Force a host flag to true for the default platform object.
 PlatformSP default_platform_sp(new PlatformWindows(true));
 default_platform_sp->SetSystemArchitecture(HostInfo::GetArchitecture());
 Platform::SetHostPlatform(default_platform_sp);
#endif
 PluginManager::RegisterPlugin(
 PlatformWindows::GetPluginNameStatic(false),
 PlatformWindows::GetPluginDescriptionStatic(false),
 PlatformWindows::CreateInstance, PlatformWindows::DebuggerInitialize);
 }
}
```

--------------------------------

### GetExtraStartupCommands

Source: https://lldb.llvm.org/cpp_reference/PlatformDarwin_8cpp_source.html

Retrieves additional startup commands for the platform.

```cpp
Args GetExtraStartupCommands() override
```

--------------------------------

### SystemInitializerFull::Initialize

Source: https://lldb.llvm.org/cpp_reference/classlldb__private_1_1SystemInitializerFull.html

Initializes the LLDB system components.

```APIDOC
## llvm::Error Initialize()

### Description
Initializes the full LLDB system. This method overrides the base class implementation to perform comprehensive system setup.

### Returns
- **llvm::Error** - Returns an error object if initialization fails, or a success value otherwise.
```

--------------------------------

### ANSI Escape Start Definition

Source: https://lldb.llvm.org/cpp_reference/FormatEntity_8cpp_source.html

Macro definition for the start of an ANSI escape sequence.

```cpp
#define ANSI_ESC_START
```

--------------------------------

### FileSystem::Initialize

Source: https://lldb.llvm.org/cpp_reference/classlldb__private_1_1FileSystem.html

Initializes the global FileSystem instance.

```APIDOC
## static void Initialize(T &&...t)

### Description
Initializes the FileSystem singleton with the provided arguments.

### Parameters
- **t** (T&&...) - Variadic arguments used for initialization.
```

--------------------------------

### DumpStyleLoadAddress Example

Source: https://lldb.llvm.org/cpp_reference/Address_8h_source.html

Example output for the DumpStyleLoadAddress style, showing a resolved load address.

```cpp
// address for printf in libSystem.B.dylib as a load address
0x00007fff8306bcff
```

--------------------------------

### bootWithOptions:error:

Source: https://lldb.llvm.org/cpp_reference/protocolLLDBCoreSimulatorSupport-p.html

Boots the simulator with the specified options.

```APIDOC
## - (BOOL)bootWithOptions:(NSDictionary *)options error:(NSError **)error

### Description
Attempts to boot the simulator instance using the provided configuration options.

### Parameters
- **options** (NSDictionary *) - Configuration options for the boot process.
- **error** (NSError **) - Pointer to an error object that will be populated if the operation fails.
```
Tokens:
Raw