---
name: "pmSearchSetup"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmSearchSetup"
---

# pmSearchSetup(3)

fast, scalable and full-text capable search services

## 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

The **pmSearchSetup** and related API functions prepare an application for accessing the full-text search functionality of the Performance Co-Pilot (PCP).

The search engine uses a local SQLite FTS5 full-text index. A build-time base index at *$PCP\_SHARE\_DIR/lib/pmsearch.index* provides help text for all metrics shipped with PCP. Each night, [**pmsearch\_daily**(1)](/pmsearch_daily/1.md) copies the base index to *$PCP\_VAR\_DIR/lib/pmsearch.index* and extends it with instance names from the running system. When the nightly index exists it is used; otherwise the base index is used as a fallback.

The interfaces described here prepare a given search *module* which associates callback routines with events that occur as part of servicing search requests.

As a general pattern, all interfaces in these APIs that need to invoke *callbacks* provided by the calling program will take an opaque (void \* pointer) *arg* parameter. This pointer will be passed through unchanged and is typically used to access a data structure maintaining state within the calling program.

On completion of **pmSearchSetup** the *on\_setup* callback will be invoked. This callback is part of the passed in *pmSearchModule* structure, which also provides for custom diagnostics handling through the *on\_info* callback. See *\<pcp/pmwebapi.h\>* for exact calling conventions.

The *callbacks* registered by **pmSearchSetup** to handle events are as follows:

- **pmSearchTextResultCallBack** *on\_text\_result*

  Callback is called once for each item of search result that matches a given **query** passed by [**pmSearchTextInDom**(3)](/pmSearchTextInDom/3.md), [**pmSearchTextQuery**(3)](/pmSearchTextQuery/3.md), [**pmSearchTextSuggest**(3)](/pmSearchTextSuggest/3.md).

- **pmSearchMetricsCallBack** *on\_metrics*

  Callback is called for results of a call to [**pmSearchInfo**(3)](/pmSearchInfo/3.md).

- **pmSearchDoneCallBack** *on\_done*

  On completion of all asynchronous interfaces that return success (zero return code), this callback will be called. It provides a status code indicating overall success (zero) or failure (negative PMAPI code) of the operation.

The helper functions **pmSearchSetSlots** and **pmSearchSetEventLoop** are retained for API compatibility but have no effect. **pmSearchSetConfiguration** (configuration file) and **pmSearchSetMetricRegistry** (MMV instrumentation) provide a mechanism for passing in state for each of the associated subsystems.

Finally, a call to **pmSearchClose** is used to end services available from a search *module* previously established through **pmSearchSetup**.

Within PCP, the [**pmproxy**(1)](/pmproxy/1.md) and [**pmsearch**(1)](/pmsearch/1.md) utilities are the primary users of the interfaces, providing REST API and command line search services respectively.

## DIAGNOSTICS

Where these functions return a status code, this is always zero on success. On failure a negative PMAPI error code is returned.

## 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)](/pmsearch_daily/1.md).

- *$PCP\_SHARE\_DIR/lib/pmsearch.index*

  Build-time base index shipped with the PCP package.

## SEE ALSO

[**pmsearch**(1)](/pmsearch/1.md), [**pmsearch\_daily**(1)](/pmsearch_daily/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**mmv\_stats\_registry**(3)](/mmv_stats_registry/3.md), [**pmSearchInfo**(3)](/pmSearchInfo/3.md), [**pmSearchTextInDom**(3)](/pmSearchTextInDom/3.md), [**pmSearchTextQuery**(3)](/pmSearchTextQuery/3.md), [**pmSearchTextSuggest**(3)](/pmSearchTextSuggest/3.md), [**PMAPI**(3)](/PMAPI/3.md) and [**PMWEBAPI**(3)](/PMWEBAPI/3.md).