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

NAME

6       __pmAddIPC,  __pmLookupIPC,  __pmFdLookupIPC, __pmOverrideLastFd, __pm‐
7       PrintIPC, __pmResetIPC - IPC version infrastructure support
8

C SYNOPSIS

10       #include "pmapi.h"
11       #include "libpcp.h"
12
13       int __pmAddIPC(int fd, __pmIPC ipc);
14       int __pmLookupIPC(__pmIPC **ipcp);
15       int __pmFdLookupIPC(int fd, __pmIPC **ipcp);
16       void __pmOverrideLastFd(int fd);
17       void __pmPrintIPC(void);
18       void __pmResetIPC(int fd);
19
20       cc ... -lpcp
21

CAVEAT

23       This documentation is intended for internal Performance Co-Pilot  (PCP)
24       developer use.
25
26       These  interfaces  are  not part of the PCP APIs that are guaranteed to
27       remain fixed across releases, and they may not  work,  or  may  provide
28       different semantics at some point in the future.
29

DESCRIPTION

31       IPC  channels  throughout the distributed PCP framework are affected by
32       the PCP 2.0 (and later) PDU changes.  These functions are the interface
33       to  the  libpcp  IPC connection management global data.  This data con‐
34       sists of a hash table of __pmIPC structures (indexed by  file  descrip‐
35       tor) and a cached, most-recently-used file descriptor.
36
37       Newly created IPC channels must be registered with the hash table using
38       __pmAddIPC, such that the PDU sending and decoding routines can  deter‐
39       mine  whether they need to perform any PDU version translations or not,
40       for backward compatibility with previous the PCP 1.x IPC protocol.
41
42       __pmLookupIPC and __pmFdLookupIPC both provide handles to  the  __pmIPC
43       structure  associated with the given file descriptor, as previously es‐
44       tablished by a call to __pmAddIPC.  The difference between the  two  is
45       that  one allows an explicit file descriptor lookup, and the other uses
46       the cached, most-recently-used file descriptor.  So __pmLookupIPC actu‐
47       ally calls __pmFdLookupIPC using this cached file descriptor as the ar‐
48       gument.  The justification for having both is that in some places it is
49       not possible to use __pmFdLookupIPC (which is preferred), since at that
50       particular level of the PMAPI a file descriptor is not  available  (see
51       the __pmDecodeError code for an example).
52
53       The  __pmOverrideLastFd  is an escape mechanism for use in those situa‐
54       tions where the last PDU fetch did not go through  the  usual  channels
55       (ie.  __pmGetPDU),  so  as to ensure that the cached file descriptor is
56       the correct file descriptor for the PDU which is currently  being  pro‐
57       cessed.   This  will  typically  be  used for archive PDU processing or
58       where version information is not available for a given file  descriptor
59       (eg. immediately prior to a PDU version exchange).
60
61       __pmPrintIPC  is a useful debugging routine for displaying a table map‐
62       ping all currently registered file descriptors to their associated  PDU
63       version numbers.  Unused entries in this table should display the value
64       zero in the version column.
65
66       __pmResetIPC resets the version information associated with  the  given
67       file  descriptor to some known (invalid) number.  Subsequent lookups on
68       this file descriptor will return an UNKNOWN_VERSION embedded within the
69       __pmIPC structure.
70

DIAGNOSTICS

72       A negative return value from __pmLookupIPC indicates that the requested
73       file descriptor is not registered in the hash  table.   This  typically
74       indicates  closure of an IPC channel, so PM_ERR_IPC is returned if this
75       is the case.
76

SEE ALSO

78       PMAPI(3)
79
80
81
82Performance Co-Pilot                  PCP                       PMLOOKUPIPC(3)
Impressum