PMSEARCHSETUP(3)

💖 PMSEARCHSETUP 💖

okay bestie, welcome to PMSEARCHSETUP(3) — it lives in the Library Functions Manual section, and it's literally the whole girlboss guide to plugging your app into PCP's full-text search. it's giving "search but make it PCP" ✨

---

✨ NAME ✨

pmSearchSetup, pmSearchSetSlots, pmSearchSetEventLoop, pmSearchSetConfiguration, pmSearchSetMetricRegistry, pmSearchClose — fast, scalable and full-text capable search services 🦋

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmwebapi.h>

int pmSearchSetup(pmSearchModule *module, void *arg);

int pmSearchSetSlots(pmSearchModule *module, void *slots);
int pmSearchSetEventLoop(pmSearchModule *module, void *events);
int pmSearchSetConfiguration(pmSearchModule *module,
                             struct dict *config);
int pmSearchSetMetricRegistry(pmSearchModule *module,
                              struct mmv_registry *registry);

int pmSearchClose(pmSearchModule *module);

cc ... -lpcp_web

---

🎀 DESCRIPTION 🎀

so the pmSearchSetup squad — that's her and all her related API besties — gets an application all prepped and pretty for accessing the full-text search functionality of the Performance Co-Pilot (PCP). no cap. 💅

the search engine is lowkey powered by a local SQLite FTS5 full-text index. there's a build-time base index sitting at $PCP_SHARE_DIR/lib/pmsearch.index that holds help text for literally every metric shipped with PCP. and every single night, pmsearch_daily(1) copies that base index over to $PCP_VAR_DIR/lib/pmsearch.index and extends it with instance names from the running system 🌙✨. when the nightly index exists, that's the one that gets used. otherwise? the base index is the fallback, and honestly good for her for showing up.

the interfaces described right here prepare a given search module, which associates callback routines with events that happen while servicing search requests. it's a whole vibe check for events.

as a general pattern (iykyk), all the interfaces in these APIs that need to invoke callbacks provided by the calling program take an opaque (void * pointer) arg parameter. that pointer gets passed through unchanged — no touchy, no changey — and it's typically used to access a data structure maintaining state within the calling program. iconic behaviour fr fr.

when pmSearchSetup completes, the on_setup callback gets invoked. that callback is part of the pmSearchModule structure you passed in, which also provides for custom diagnostics handling through the on_info callback. peek at <pcp/pmwebapi.h> for the exact calling conventions, bestie 👑

the callbacks registered by pmSearchSetup to handle events are as follows:

• pmSearchTextResultCallBack on_text_result — this callback is called once for each item of search result that matches a given query passed by pmSearchTextInDom(3), pmSearchTextQuery(3), pmSearchTextSuggest(3).
• pmSearchMetricsCallBack on_metrics — called for results of a call to pmSearchInfo(3).
• pmSearchDoneCallBack on_done — on completion of all asynchronous interfaces that return success (zero return code), this callback gets called. it provides a status code indicating overall success (zero) or failure (negative PMAPI code) of the operation.

now, the helper functions pmSearchSetSlots and pmSearchSetEventLoop? they're retained for API compatibility but have no effect 🙈 — so cute, so useless, we still love them. meanwhile pmSearchSetConfiguration (configuration file) and pmSearchSetMetricRegistry (MMV instrumentation) actually do provide a mechanism for passing in state for each of the associated subsystems. ate.

finally, a call to pmSearchClose ends the services available from a search module that was previously established through pmSearchSetup. closing time, babes 🌈

within PCP, the pmproxy(1) and pmsearch(1) utilities are the primary users of these interfaces, providing REST API and command line search services respectively. main character energy, both of them.

---

💀 DIAGNOSTICS 💀

wherever these functions return a status code, it's always zero on success. and on failure? a negative PMAPI error code comes back. that's the whole story, no plot twist 😭

---

🍓 FILES 🍓

• $PCP_VAR_DIR/lib/pmsearch.index — Nightly search index (SQLite FTS5 database), a copy of the base index extended with runtime instance data by pmsearch_daily(1).
• $PCP_SHARE_DIR/lib/pmsearch.index — Build-time base index shipped with the PCP package.

---

🧚 SEE ALSO 🧚

pmsearch(1), pmsearch_daily(1), pmproxy(1), pmlogger(1), mmv_stats_registry(3), pmSearchInfo(3), pmSearchTextInDom(3), pmSearchTextQuery(3), pmSearchTextSuggest(3), PMAPI(3) and PMWEBAPI(3). go read them, they're all so good 🫶

---

and that's the whole page, bestie!! brought to you by the fine folks at Performance Co-Pilot, PCP, and this very PMSEARCHSETUP(3) moment — go forth and search, you're gonna slay 💖✨👑