1PMLOOKUPIPC(3) Library Functions Manual PMLOOKUPIPC(3)
2
6 __pmAddIPC, __pmLookupIPC, __pmFdLookupIPC, __pmOverrideLastFd,
7 __pmPrintIPC, __pmResetIPC - IPC version infrastructure support
8
10 #include "pmapi.h"
11 #include "libpcp.h"
12 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 cc ... -lpcp
21
23 This documentation is intended for internal Performance Co-Pilot (PCP)
24 developer use.
25 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
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 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 __pmLookupIPC and __pmFdLookupIPC both provide handles to the __pmIPC
43 structure associated with the given file descriptor, as previously
44 established 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
48 argument. The justification for having both is that in some places it
49 is not possible to use __pmFdLookupIPC (which is preferred), since at
50 that particular level of the PMAPI a file descriptor is not available
51 (see the __pmDecodeError code for an example).
52 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 __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 __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
72 PMAPI(3)
73
75 A negative return value from __pmLookupIPC indicates that the requested
76 file descriptor is not registered in the hash table. This typically
77 indicates closure of an IPC channel, so PM_ERR_IPC is returned if this
78 is the case.
79Performance Co-Pilot PCP PMLOOKUPIPC(3)