1PMCONTEXTCONNECTTO(3)      Library Functions Manual      PMCONTEXTCONNECTTO(3)
2
3
4

NAME

6       pmContextConnectTo, pmContextChangeState - connect to a PMCD
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmContextConnectTo(int ctx, const struct sockaddr *addr)
12       int pmContextChangeState(int ctx)
13
14       cc ... -lpcp
15

DESCRIPTION

17       A  host context, created by passing PM_CTXFLAG_SHALLOW to pmNewContext,
18       must be connected to a source of performance metrics, i.e. pmcd(1),  on
19       some host before it can be used to retrieve data.
20
21       The  connection  process  can  block  for several tens of seconds while
22       waiting for a reply from either pmcd(1) or from a TCP/IP stack  on  the
23       remote  host. To avoid blocking, applications which must communicate to
24       pmcd asynchronously should  use  these  functions  to  work  the  state
25       machine associated with the context creation.
26
27       Calling  pmContextConnectTo  starts the process of establishing connec‐
28       tion to a pmcd(1) on a host identified by the addr. Usually  addr  will
29       be  an  IPv4  socket  address,  in  which case the value of sin_port is
30       ignored.
31
32       Following the call to pmContextConnectTo an application is expected  to
33       wait  until the file descriptor associated with the context ctx becomes
34       ready to accept data, i.e. write(2) is not going  to  block,  then  the
35       application   should   call   pmContextChangeState.   If   it   returns
36       PM_ERR_AGAIN then the application must wait until data are available on
37       the  file  descriptor  associated  with  context  ctx  and  call pmCon‐
38       textChangeState again until it returns 0 to indicate success or a nega‐
39       tive value to indicate failure.
40

SEE ALSO

42       PMAPI(3), pmNewContext(3) and pmGetContextFD(3).
43

DIAGNOSTICS

45       PM_ERR_NOCONTEXT
46              ctx does not identify a valid PMAPI context.
47
48       PM_ERR_NOTHOST
49              The context is not associated with PMCD.
50
51       PM_ERR_NOTCONN
52              The connection to PMCD is not yet established.
53
54       PM_ERR_ISCONN
55              The connection to PMCD is already established.
56

EXAMPLE

58       int ctx = pmNewContext(PM_CONTEXT_HOST|PM_CTXFLAG_SHALLOW, "localhost");
59       int fd = pmGetContextFD(ctx);
60       struct sockaddr_in sin;
61
62       memset (&sin, 0, sizeof(sin));
63       sin.sin_family = AF_INET;
64       sin.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
65
66       if (pmContextConnectTo(ctx, (struct sockaddr *)&sin) >= 0) {
67           struct pollfd pfd;
68
69           pfd.fd = fd;
70           pfd.events = POLLOUT;
71
72           while (1) {
73               int tout = pmGetContextTimeout(ctx);
74               if (poll (&pfd, 1, tout) <= 0) {
75                   break;
76            }
77               if (pmContextChangeState (ctx) != PM_ERR_AGAIN) {
78                   break;
79               }
80               pfd.events = POLLIN;
81           }
82           /* We're now connected and can use the context */
83       }
84
85
86
87
88Performance Co-Pilot                  SGI                PMCONTEXTCONNECTTO(3)
Impressum