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

NAME

6       __pmAddIPC,    __pmLookupIPC,    __pmFdLookupIPC,   __pmOverrideLastFd,
7       __pmPrintIPC, __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
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
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

SEE ALSO

72       PMAPI(3)
73

DIAGNOSTICS

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.
79
80
81
82Performance Co-Pilot                  PCP                       PMLOOKUPIPC(3)
Impressum