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 <pcp/pmapi.h>
11       #include <pcp/impl.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

DESCRIPTION

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

SEE ALSO

64       PMAPI(3)
65

DIAGNOSTICS

67       A negative return value from __pmLookupIPC indicates that the requested
68       file  descriptor  is  not registered in the hash table.  This typically
69       indicates closure of an IPC channel, so PM_ERR_IPC is returned if  this
70       is the case.
71
72
73
74Performance Co-Pilot                  PCP                       PMLOOKUPIPC(3)
Impressum