{"record":{"id":"fd5e5039793a1bbf","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-putmem-address-length-pages","errorCode":null,"errorMessage":"Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]","messagePattern":"Usage: ghidra trace putmem ADDRESS LENGTH \\[PAGES\\]","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":730,"sourceCode":"\n    Writes the given range of bytes from memory into the Ghidra trace. ADDRESS\n    is a memory address. It is expression evaluated within the current target.\n    LENGTH is the number of bytes to write, also evaluated within the current\n    target. PAGES is a boolean value. If true, the range will be quantized to\n    page boundaries that include the requested range.\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) == 2:\n        address = args[0]\n        length = args[1]\n        pages = True\n    elif len(args) == 3:\n        address = args[0]\n        length = args[1]\n        pages = (util.get_eval(args[2]).unsigned != 0)\n    else:\n        raise RuntimeError(\"Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]\")\n\n    STATE.require_tx()\n    putmem(address, length, result, pages)\n\n\n@convert_errors\ndef ghidra_trace_putval(debugger: lldb.SBDebugger, command: str,\n                        result: lldb.SBCommandReturnObject,\n                        internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Record the given value into the Ghidra trace, if it's in memory.\n\n    Usage: ghidra trace putval EXPRESSION [PAGES]\n\n    Evaluates the given expression within the current target. If the resulting\n    value has an address in the target's memory, the bytes comprising that value\n    are written into the Ghidra trace. If PAGES is true, then the full page(s)\n    containing those bytes are written. If the resulting value has no address,\n    or its address is not in memory, an error results.","sourceCodeStart":712,"sourceCodeEnd":748,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L712-L748","documentation":"Usage error raised by ghidra_trace_putmem when shlex.split(command) yields neither 2 nor 3 tokens. The command requires ADDRESS and LENGTH, with an optional third PAGES flag; any other arity is rejected before STATE.require_tx() is touched.","triggerScenarios":"Running 'ghidra trace putmem' with 0, 1, or 4+ tokens; forgetting LENGTH; passing extra unquoted spaces; quoting mistakes that collapse or inflate the token count.","commonSituations":"New users omit LENGTH thinking the command auto-sizes; users copy-paste a path with spaces that shlex splits into many tokens; passing flags like '-pages' that are not supported (PAGES is positional).","solutions":["Supply exactly two or three tokens: ADDRESS LENGTH [PAGES].","If ADDRESS or LENGTH contains spaces/special chars, ensure they are a single LLDB expression token (quote the whole command if needed).","Remember PAGES is a positional 0/1 expression, not a --pages flag."],"exampleFix":"// before\nghidra trace putmem 0x10000\n// after\nghidra trace putmem 0x10000 0x100","handlingStrategy":"validation","validationCode":"import shlex\n\ndef validate_putmem(command: str) -> None:\n    n = len(shlex.split(command))\n    if n not in (2, 3):\n        raise ValueError('ghidra trace putmem needs ADDRESS LENGTH [PAGES]')","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_putmem(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage:'):\n        result.SetError('Syntax: ' + str(e))\n    else:\n        raise","preventionTips":["Memorize the positional signature: ADDRESS LENGTH [PAGES].","Remember PAGES is positional 0/1, not a --pages flag.","Validate token count before invoking when scripting."],"tags":["ghidra-trace","argument-validation","cli-usage"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}