diff options
Diffstat (limited to 'man/man3/pmnewcontext.3')
| -rw-r--r-- | man/man3/pmnewcontext.3 | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/man/man3/pmnewcontext.3 b/man/man3/pmnewcontext.3 new file mode 100644 index 0000000..2286c69 --- /dev/null +++ b/man/man3/pmnewcontext.3 @@ -0,0 +1,282 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNEWCONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNewContext\f1 \- establish a new PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmNewContext(int \fItype\fP, const char *\fIname\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH 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. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1), +or a standalone connection on the local host that does not involve +.BR pmcd (1). +.PP +.BR pmNewContext +may be used to establish a new context. +The source of the metrics is identified by +.IR name , +and may be either a host name (\c +.I type +is +.BR PM_CONTEXT_HOST ), +or the base name common to all of the physical files of an archive log (\c +.I type +is +.BR PM_CONTEXT_ARCHIVE ). +.PP +For a +.I type +of +.BR PM_CONTEXT_HOST , +in addition to identifying a host +the +.I name +may also be used to encode additional optional information in the form of +a +.BR pmcd (1) +port number, a +.BR pmproxy (1) +hostname and a proxy port number. For example the +.I name +\&"app23:14321,4321@firewall.example.com:11111" +specifies +a connection on port +.I 14321 +(or port +.I 4321 +if +.I 14321 +is unavailable) +to +.BR pmcd (1) +on the host +.I app23 +via port +.I 11111 +to +.BR pmproxy (1) +on the host +.IR firewall.example.com . +.PP +For a +.I type +of +.BR PM_CONTEXT_ARCHIVE , +.I name +may also be the name of any of the physical files of an +archive, e.g. +.IB myarchive .meta +(the metadata file) or +.IB myarchive .index +(the temporal index) or +.IB myarchive .0 +(the first data volume of the archive) +or +.IB myarchive .0.bz2 +or +.IB myarchive .0.bz +(the first data volume compressed with +.BR bzip2 (1)) +or +.IB myarchive .0.gz +or +.IB myarchive .0.Z +or +.IB myarchive .0.z +(the first data volume compressed with +.BR gzip (1)), +.IB myarchive .1 +or +.IB myarchive .3.bz2 +or +.IB myarchive .42.gz +etc. +.PP +In the case where +.I type +is +.BR PM_CONTEXT_LOCAL , +.I name +is ignored, and the context uses a standalone connection to the +PMDA methods used by +.BR pmcd (1). +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. +.PP +In the case where \f2type\fP is \f3PM_CONTEXT_HOST\fP, additional flags can +be added to the \f2type\fP to indicate if the connection to \f3pmcd\fP(1) +should be encrypted (\f3PM_CTXFLAG_SECURE\fP), deferred (\f3PM_CTXFLAG_SHALLOW\fP) +and if the file descriptor used to communicate with \f3pmcd\fP(1), should not be +shared across contexts (\f3PM_CTXFLAG_EXCLUSIVE\fP). These final two context +flags are now deprecated and ignored. +.PP +The initial instance +profile is set up to select all instances in all instance domains. +In the case of an archive, +the initial collection time is also set to zero, +so that an initial +.BR pmFetch (3) +will result in the earliest set of metrics +being returned from the archive. +.PP +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 +.BR pmAddProfile (3) +and +.BR pmDelProfile (3)) +and the collection time for archives (see +.BR pmSetMode (3)). +.PP +.B pmNewContext +returns a handle that may be used with subsequent calls to +.BR pmUseContext (3). +.PP +The new context remains the current PMAPI context for all +subsequent calls across the PMAPI, +until another call to +.BR pmNewContext (3) +is made, or the context is explicitly changed with a call to +.BR pmDupContext (3) +or +.BR pmUseContext (3), +or destroyed using +.BR pmDestroyContext (3). +.PP +When attempting to connect to a remote +.BR pmcd (1) +on a machine that is booting, +.B pmNewContext +could potentially block for a long time until the remote machine +finishes its initialization. +.B 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 +.B 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. +.SH ENVIRONMENT +.TP +.B PMCD_CONNECT_TIMEOUT +Timeout period (in seconds) for +.BR pmcd (1) +connection attempts. +.TP +.B PMCD_PORT +TCP/IP port(s) for connecting to +.BR pmcd (1), +historically was 4321 and more recently the officially registered port +44321; in the current release, +.B pmcd +listens on both these ports as a transitional arrangement. If used, +should be set to a comma-separated list of numerical port numbers. +.TP +.B PMDA_PATH +When searching for PMDAs to be loaded when +.I type +is +.BR PM_CONTEXT_LOCAL , +the +.B 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 +.BR $PCP_SHARE_DIR/lib:/usr/pcp/lib . +.SH CAVEATS +When using a +.I type +of +.BR PM_CONTEXT_LOCAL , +the operating system PMDA may export data structures directly +from the kernel, which means that the +.B pmNewContext +caller should be an +executable program compiled for the same object code format +as the booted kernel. +.P +In addition, applications using a +.B PM_CONTEXT_LOCAL +context +must be single-threaded because the various DSO PMDAs may not be +thread-safe. This restriction is enforced at the +.BR PMAPI (3), +where routines may return the error code +.B PM_ERR_THREAD +if the library detects calls from more than one thread. +.P +Applications that use +.BR gethostbyname (3N) +should exercise caution because the static fields in +.I "struct hostent" +may not be preserved across some +.BR PMAPI (3) +calls. +In particular, +.BR pmNewContext (3) +and +.BR pmReconnectContext (3) +both may call +.BR gethostbyname (3N) +internally. +.SH SEE ALSO +.BR pmcd (1), +.BR pmproxy (1), +.BR pmAddProfile (3), +.BR PMAPI (3), +.BR pmDelProfile (3), +.BR pmDestroyContext (3), +.BR pmDupContext (3), +.BR pmGetConfig (3), +.BR pmReconnectContext (3), +.BR pmSetMode (3), +.BR pmUseContext (3), +.BR pmWhichContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.P +.B PM_ERR_PERMISSION +.IP +No permission to perform requested operation +.P +.B PM_ERR_CONNLIMIT +.IP +PMCD connection limit for this host exceeded +.P +.B PM_ERR_NOCONTEXT +.IP +Requested context type was not +.BR PM_CONTEXT_LOCAL , +.B PM_CONTEXT_HOST +or +.BR PM_CONTEXT_ARCHIVE . |