--- name: "pmnewcontext" section: "3" platform: "linux" package: "libpcp3-dev" version: "4.3.2+really4.3.1-0.1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/pmNewContext" --- # pmnewcontext(3) establish a new PMAPI context Part of [pmNewContext(3)](/pmNewContext/3.md). ## 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 archive logs of performance metrics as created by [**pmlogger**(1)](/pmlogger/1.md), or a standalone 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 archive logs (*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 log or the name of a directory containing archive logs. 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*. 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 standalone connection to the PMDA methods used by [**pmcd**(1)](/pmcd/1.md). When this type of context is used, the range of accessible performance metrics is constrained to those from the operating system, and optionally the \`\`proc'', \`\`sample'' and \`\`ib'' PMDAs. 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**), deferred (**PM\_CTXFLAG\_SHALLOW**) and 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. 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. ## 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. - **PMDA\_PATH** When searching for PMDAs to be loaded when *type* is **PM\_CONTEXT\_LOCAL**, the **PMDA\_PATH** environment variable may be used to define a search path of directories to be used to locate the PMDA executables. The default search path is **$PCP\_SHARE\_DIR/lib:/usr/pcp/lib**. ## 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. ## SEE ALSO [**pmcd**(1)](/pmcd/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**pmAddProfile**(3)](/pmAddProfile/3.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmDelProfile**(3)](/pmDelProfile/3.md), [**pmDestroyContext**(3)](/pmDestroyContext/3.md), [**pmDupContext**(3)](/pmDupContext/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmReconnectContext**(3)](/pmReconnectContext/3.md), [**pmSetMode**(3)](/pmSetMode/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). ## 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\_LOGTIMEZONE** - Archives differ by time zone. **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