[DTrace-devel] [PATCH 6/6] docs: document uresolve() in the user guide

[Alan Maguire]

Signed-off-by: Alan Maguire <alan.maguire at oracle.com>
Assisted-by: OpenAI Codex (GPT-5) <codex at openai.com>
---
 doc/userguide/index.md                       |  1 +
 doc/userguide/reference/dtrace_functions.md  |  4 ++
 doc/userguide/reference/function_uresolve.md | 61 ++++++++++++++++++++
 3 files changed, 66 insertions(+)
 create mode 100644 doc/userguide/reference/function_uresolve.md

diff --git a/doc/userguide/index.md b/doc/userguide/index.md
index 3bf731c6..348ecc8c 100644
--- a/doc/userguide/index.md
+++ b/doc/userguide/index.md
@@ -181,6 +181,7 @@
     -   [tracemem](reference/function_tracemem.md)
     -   [trunc](reference/function_trunc.md)
     -   [uaddr](reference/function_uaddr.md)
+    -   [uresolve](reference/function_uresolve.md)
     -   [ufunc](reference/function_ufunc.md)
     -   [umod](reference/function_umod.md)
     -   [ustack](reference/function_ustack.md)
diff --git a/doc/userguide/reference/dtrace_functions.md b/doc/userguide/reference/dtrace_functions.md
index 7bf37794..021e599d 100644
--- a/doc/userguide/reference/dtrace_functions.md
+++ b/doc/userguide/reference/dtrace_functions.md
@@ -191,6 +191,8 @@ Functions can be grouped according to their general use case and might appear in
 
     -   [`uaddr`](function_uaddr.md): Prints the symbol for a specified address.
 
+    -   [`uresolve`](function_uresolve.md): Returns the process-specific address of a user-space symbol.
+
     -   [`ufunc`](function_ufunc.md): Prints the symbol for a specified user space address. An alias for `usym`.
 
     -   [`umod`](function_umod.md): Prints the module name that corresponds to a specified user space address.
@@ -398,6 +400,8 @@ Returns a string translation of a hardware address.
  Truncates keys from an aggregation.
 -   **[uaddr](../reference/function_uaddr.md)**  
  Prints the symbol for a specified address.
+-   **[uresolve](../reference/function_uresolve.md)**
+ Returns the process-specific address of a user-space symbol.
 -   **[ufunc](../reference/function_ufunc.md)**  
  Prints the symbol for a specified user space address. An alias for `usym`.
 -   **[umod](../reference/function_umod.md)**  
diff --git a/doc/userguide/reference/function_uresolve.md b/doc/userguide/reference/function_uresolve.md
new file mode 100644
index 00000000..3241ecfa
--- /dev/null
+++ b/doc/userguide/reference/function_uresolve.md
@@ -0,0 +1,61 @@
+
+# uresolve
+
+Returns the process-specific address of a user-space symbol.
+
+```
+uintptr_t uresolve(string symbol[, uintptr_t fallback])
+```
+
+The `uresolve` function resolves a symbol in the user-space object that's associated with the current user-space probe and returns the address of that symbol in the process that fired the probe. The result is a user-space address and is typically passed to functions such as [`copyin`](function_copyin.md) or [`copyinstr`](function_copyinstr.md).
+
+The *symbol* argument must be a string constant. It can use either of these forms:
+
+-   `symbol`: Resolve *symbol* in the object associated with the current probe.
+
+-   ``object`symbol``: Resolve *symbol* in the named object. The object name can be a full path or a module name such as `a.out` or `libc.so.6`.
+
+When a target process is specified with `-c` or `-p`, DTrace can use that process and its `/proc` mappings to find the symbol's object-relative offset. For system-wide user-space probes, DTrace can use the probed object file instead. In both cases, the address returned at probe firing is computed for the process that fired the current probe, so the result remains valid across ASLR and across different processes that map the same object at different addresses.
+
+If *fallback* is supplied and the symbol lookup fails, `uresolve` returns the fallback value. If *fallback* isn't supplied, failing to resolve the symbol is a compilation error.
+
+`uresolve` is intended for user-space probe contexts, such as `pid`, USDT, and `stapsdt` probes, where DTrace can identify the current probed user object. It doesn't read memory by itself and doesn't verify that the returned address is readable. Use `copyin` or `copyinstr` to read data from the returned address.
+
+## How to use uresolve to read a user-space variable
+
+This example resolves the global variable `my_counter` in the target program, reads its value, and prints it when `update_counter` is entered:
+
+```
+pid$target:a.out:update_counter:entry
+{
+        this->addr = uresolve("a.out`my_counter");
+        this->value = (int *)copyin(this->addr, sizeof(int));
+        printf("my_counter = %d\n", *this->value);
+}
+```
+
+## How to use uresolve with system-wide user-space probes
+
+This example resolves `_PyThreadState_Current` in each process that fires the Python function-entry probe. The address is computed for the process that fired the probe:
+
+```
+python*:libpython3.6m.so::function-entry
+{
+        this->addr = uresolve("_PyThreadState_Current", 0);
+        this->statep = (uintptr_t *)copyin(this->addr, sizeof(uintptr_t));
+        printf("%d %p\n", pid, *this->statep);
+}
+```
+
+The fallback value of `0` lets the script compile and run on systems or Python builds where the symbol isn't present. If the fallback is returned, the subsequent `copyin` would attempt to read from address 0, so real scripts should guard that case before reading:
+
+```
+python*:libpython3.6m.so::function-entry
+/(this->addr = uresolve("_PyThreadState_Current", 0)) != 0/
+{
+        this->statep = (uintptr_t *)copyin(this->addr, sizeof(uintptr_t));
+        printf("%d %p\n", pid, *this->statep);
+}
+```
+
+**Parent topic:** [DTrace Function Reference](../reference/dtrace_functions.md)
-- 
2.43.5