--- name: "pmNewContext" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmNewContext" --- # pmNewContext(3) establish a new PMAPI context ## NAME **pmNewContext** - establish a new PMAPI context ## C SYNOPSIS **#include \** **int pmNewContext(int** *type***, const char \****name***);** **cc ... -lpcp** ## DESCRIPTION An application using the Performance Metrics Application Programming Interface (PMAPI) may manipulate several concurrent contexts, each associated with a source of performance metrics, e.g. [**pmcd**(1)](/pmcd/1.md) on some host, or a set of archives of performance metrics as created by [**pmlogger**(1)](/pmlogger/1.md), or a stand-alone connection on the local host that does not involve [**pmcd**(1)](/pmcd/1.md). **pmNewContext** may be used to establish a new context. The source of the metrics is identified by *name*, and may be either a host name (*type* is **PM\_CONTEXT\_HOST**), or a comma-separated list of names referring to a set of archives (*type* is **PM\_CONTEXT\_ARCHIVE**). Each element of the list may either be the base name common to all of the physical files of an archive or the name of a directory containing archives. For a *type* of **PM\_CONTEXT\_HOST**, in addition to identifying a host the *name* may also be used to encode additional optional information in the form of a [**pmcd**(1)](/pmcd/1.md) port number, a [**pmproxy**(1)](/pmproxy/1.md) hostname and a proxy port number. For example the *name* "app23:14321,4321@firewall.example.com:11111" specifies a connection on port *14321* (or port *4321* if *14321* is unavailable) to [**pmcd**(1)](/pmcd/1.md) on the host *app23* via port *11111* to [**pmproxy**(1)](/pmproxy/1.md) on the host *firewall.example.com*. Alternatively, for a *type* of **PM\_CONTEXT\_HOST**, *name* may be **unix:** for an authenticated Unix domain socket connection to [**pmcd**(1)](/pmcd/1.md) on the localhost or **local:** for an authenticated connection to [**pmcd**(1)](/pmcd/1.md) on the localhost via a Unix domain socket if available, else via an internet socket connection to **localhost**. **local:** is the default choice for most applications when calling **pmNewContext** to establish a context for [**pmcd**(1)](/pmcd/1.md) on the local host. For a *type* of **PM\_CONTEXT\_ARCHIVE**, each element of the list of names in *name* may also be the name of any of the physical files of an archive, e.g. *myarchive***.meta** (the metadata file) or *myarchive***.index** (the temporal index) or *myarchive***.0** (the first data volume of the archive) or *myarchive***.0.bz2** or *myarchive***.0.bz** (the first data volume compressed with [**bzip2**(1)](/bzip2/1.md)) or *myarchive***.0.gz** or *myarchive***.0.Z** or *myarchive***.0.z** (the first data volume compressed with [**gzip**(1)](/gzip/1.md)), *myarchive***.1** or *myarchive***.3.bz2** or *myarchive***.42.gz** etc. If more than one archive is specified for a *type* of **PM\_CONTEXT\_ARCHIVE**, there are some restrictions on the archives within the set: - • The archives must all have been generated on the same host. - • The archives must not overlap in time. - • The archives must all have been created using the same time zone. - • The *PMID* of each metric should be the same in all of the archives. Multiple *PMID*s are currently tolerated by using the first *PMID* defined for each metric and ignoring subsequent *PMID*s. - • The type of each metric must be the same in all of the archives. - • The semantics of each metric must be the same in all of the archives. - • The units of each metric must be the same in all of the archives. - • The instance domain of each metric must be the same in all of the archives. In the case where *type* is **PM\_CONTEXT\_LOCAL**, *name* is ignored, and the context uses a stand-alone connection to the PMDA methods used by [**pmcd**(1)](/pmcd/1.md). The mechanism in the library uses the same \`\`plugin'' architecture that operates between [**pmcd**(1)](/pmcd/1.md) and DSO PMDAs, so operations involve function calls rather than IPC message passing - for **PM\_CONTEXT\_LOCAL** contexts this may mean lower latency for operations like [**pmFetch**(3)](/pmFetch/3.md), but at the cost of longer initialization time and possible access control differences compared to [**pmcd**(1)](/pmcd/1.md). When this type of context is used, the range of accessible performance metrics is constrained to those from the DSO PMDAs defined in the [**pmcd**(1)](/pmcd/1.md) configuration file **/etc/pcp/pmcd/pmcd.conf**, so those reported by the command `$ awk '$3 == "dso" {print}' /etc/pcp/pmcd/pmcd.conf`\ or alternatively reported by the command `$ pminfo -f pmcd.agent.type | grep 'value 0'`\ This usually means the PMDA exporting metrics from the operating system and the \`\`pmcd'', \`\`pmproxy'' and may includes some others like \`\`mmv''. Alternate DSO PMDAs can be used, refer to [**pmSpecLocalPMDA**(3)](/pmSpecLocalPMDA/3.md). In the case where *type* is **PM\_CONTEXT\_HOST**, additional flags can be added to the *type* to indicate if the connection to [**pmcd**(1)](/pmcd/1.md) should be encrypted (**PM\_CTXFLAG\_SECURE**), should be encrypted if possible (**PM\_CTXFLAG\_RELAXED**), is deferred (**PM\_CTXFLAG\_SHALLOW**), should use authentication (**PM\_CTXFLAG\_AUTH**), should be a connection to a container (**PM\_CTXFLAG\_CONTAINER**), or if the file descriptor used to communicate with [**pmcd**(1)](/pmcd/1.md), should not be shared across contexts (**PM\_CTXFLAG\_EXCLUSIVE**). Both the **PM\_CTXFLAG\_SHALLOW** and **PM\_CTXFLAG\_EXCLUSIVE** flags are now deprecated and ignored. When *type* is **PM\_CONTEXT\_ARCHIVE**, additional flags can be added to the *type* for restricted handling of the archive suited to applications that are aware of the structure of PCP archives, namely **PM\_CTXFLAG\_NO\_FEATURE\_CHECK** (do not check feature compatibility for archive label records), **PM\_CTXFLAG\_METADATA\_ONLY** (open only the metadata, not the data volume(s) nor the index) and **PM\_CTXFLAG\_LAST\_VOLUME** (open the archive at the start of the *last* data volume, instead of the default start of the *first* data volume). Multiple flags can be specified by bit-wise \`\`or-ing'' of the **PM\_CTXFLAG** macros, but not all combinations make sense, e.g. if **PM\_CTXFLAG\_METADATA\_ONLY** and **PM\_CTXFLAG\_LAST\_VOLUME** are specified, **PM\_CTXFLAG\_METADATA\_ONLY** takes precedence. The initial instance profile is set up to select all instances in all instance domains. In the case of a set of archives, the initial collection time is also set to zero, so that an initial [**pmFetch**(3)](/pmFetch/3.md) will result in the earliest set of metrics being returned from the set of archives. Once established, the association between a context and a source of metrics is fixed for the life of the context, however routines are provided to independently manipulate both the instance profile (see [**pmAddProfile**(3)](/pmAddProfile/3.md) and [**pmDelProfile**(3)](/pmDelProfile/3.md)) and the collection time for archives (see [**pmSetMode**(3)](/pmSetMode/3.md)). **pmNewContext** returns a handle that may be used with subsequent calls to [**pmUseContext**(3)](/pmUseContext/3.md). The new context remains the current PMAPI context for all subsequent calls across the PMAPI, until another call to [**pmNewContext**(3)](/pmNewContext/3.md) is made, or the context is explicitly changed with a call to [**pmDupContext**(3)](/pmDupContext/3.md) or [**pmUseContext**(3)](/pmUseContext/3.md), or destroyed using [**pmDestroyContext**(3)](/pmDestroyContext/3.md). When attempting to connect to a remote [**pmcd**(1)](/pmcd/1.md) on a machine that is booting, **pmNewContext** could potentially block for a long time until the remote machine finishes its initialization. **pmNewContext** will abort and return an error if the connection has not been established after some specified interval has elapsed. The default interval is 5 seconds. This may be modified by setting **PMCD\_CONNECT\_TIMEOUT** in the environment to a real number of seconds for the desired timeout. This is most useful in cases where the remote host is at the end of a slow network, requiring longer latencies to establish the connection correctly. ## CAVEATS When using a *type* of **PM\_CONTEXT\_LOCAL**, the operating system PMDA may export data structures directly from the kernel, which means that the **pmNewContext** caller should be an executable program compiled for the same object code format as the booted kernel. In addition, applications using a **PM\_CONTEXT\_LOCAL** context must be single-threaded because the various DSO PMDAs may not be thread-safe. This restriction is enforced at the [**PMAPI**(3)](/PMAPI/3.md), where routines may return the error code **PM\_ERR\_THREAD** if the library detects calls from more than one thread. Applications that use [**gethostbyname**(3)](/gethostbyname/3.md) should exercise caution because the static fields in *struct hostent* may not be preserved across some [**PMAPI**(3)](/PMAPI/3.md) calls. In particular, [**pmNewContext**(3)](/pmNewContext/3.md) and [**pmReconnectContext**(3)](/pmReconnectContext/3.md) both may call [**gethostbyname**(3)](/gethostbyname/3.md) internally. ## DIAGNOSTICS **PM\_ERR\_PERMISSION** - No permission to perform requested operation **PM\_ERR\_CONNLIMIT** - PMCD connection limit for this host exceeded **PM\_ERR\_NOCONTEXT** - Requested context type was not **PM\_CONTEXT\_LOCAL**, **PM\_CONTEXT\_HOST** or **PM\_CONTEXT\_ARCHIVE**. **PM\_ERR\_LOGOVERLAP** - Archives overlap in time **PM\_ERR\_LOGHOST** - Archives differ by host **PM\_ERR\_LOGCHANGETYPE** - The type of a metric differs among archives **PM\_ERR\_LOGCHANGESEM** - The semantics of a metric differs among archives **PM\_ERR\_LOGCHANGEINDOM** - The instance domain of a metric differs among archives **PM\_ERR\_LOGCHANGEUNITS** - The units of a metric differs among archives ## ENVIRONMENT - **PMCD\_CONNECT\_TIMEOUT** Timeout period (in seconds) for [**pmcd**(1)](/pmcd/1.md) connection attempts. - **PMCD\_PORT** TCP/IP port(s) for connecting to [**pmcd**(1)](/pmcd/1.md), historically was 4321 and more recently the officially registered port 44321; in the current release, **pmcd** listens on both these ports as a transitional arrangement. If used, should be set to a comma-separated list of numerical port numbers. ## SEE ALSO [**pmcd**(1)](/pmcd/1.md), [**pminfo**(1)](/pminfo/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmAddProfile**(3)](/pmAddProfile/3.md), [**pmDelProfile**(3)](/pmDelProfile/3.md), [**pmDestroyContext**(3)](/pmDestroyContext/3.md), [**pmDupContext**(3)](/pmDupContext/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmReconnectContext**(3)](/pmReconnectContext/3.md), [**pmSetMode**(3)](/pmSetMode/3.md), [**pmSpecLocalPMDA**(3)](/pmSpecLocalPMDA/3.md), [**pmUseContext**(3)](/pmUseContext/3.md), [**pmWhichContext**(3)](/pmWhichContext/3.md), [**pcp.conf**(5)](/pcp.conf/5.md) and [**pcp.env**(5)](/pcp.env/5.md).