1PMPARSEHOSTATTRSSPEC(3) Library Functions Manual PMPARSEHOSTATTRSSPEC(3)
2
6 __pmParseHostAttrsSpec, __pmUnparseHostAttrsSpec, __pmFreeHostAt‐
7 trsSpec, __pmFreeAttrsSpec - host and attributes specification parser
8
10 #include "pmapi.h"
11 #include "libpcp.h"
12 int __pmParseHostAttrsSpec(const char *string, pmHostSpec **hostsp,
14 int *count, __pmHashCtl *attrs, char **errmsg);
15 int __pmUnparseHostAttrsSpec(pmHostSpec *hostsp, int *count,
16 __pmHashCtl *attrs, char *string, size_t size);
17 void __pmFreeHostAttrsSpec(pmHostSpec *hosts, int count,
18 __pmHashCtl *attrs);
19 void __pmFreeAttrsSpec(__pmHashCtl *attrs);
20 cc ... -lpcp
22
24 This documentation is intended for internal Performance Co-Pilot (PCP)
25 developer use.
26 These interfaces are not part of the PCP APIs that are guaranteed to
28 remain fixed across releases, and they may not work, or may provide
29 different semantics at some point in the future.
30
32 __pmParseHostAttrsSpec accepts a string specifying the location of a
33 PCP performance metric collector daemon, and any attributes that should
34 be associated with the connection to that daemon.
35 The syntax allows the optional specification of a protocol (native PCP
37 protocol, encrypted PCP protocol or unix domain socket protocol).
38 If the specified protocol is native PCP protocol, or encrypted PCP pro‐
40 tocol, an initial pmcd(1) hostname with optional port numbers and op‐
41 tional proxy host, and optional attributes which are to be associated
42 with the connection may be specified. Some examples follow:
43 pcp://nas1.servers.com:44321@firewalls.r.us?compress
45 pcps://nas1.servers.com?user=otto&pass=blotto&compress
46 If the specified protocol is a unix domain socket protocol, the path to
48 the socket in the local file system may be specified along with option‐
49 al attributes which are to be associated with the connection. For ex‐
50 ample:
51 unix://$PCP_RUN_DIR/pmcd.socket:?compress
53 local://my/local/pmcd.socket:?user=otto&pass=blotto&compress
54 If the optional protocol component is not specified, then the default
56 setting will be used - which is the native PCP binary protocol. Howev‐
57 er, this can still be overwritten via the environment as described in
58 PCPIntro(1). If the protocol prefix is specified, it must be one of
59 either "pcp://" (clear), "pcps://" (secure, encrypted), "unix://" (au‐
60 thenticated local) or "local://" ("unix://" then "pcp://").
61 The path specified for the "unix://" and "local://" protocols will al‐
63 ways be interpreted as an absolute path name. For example, the follow‐
64 ing are all interpreted identically as $PCP_RUN_DIR/pmcd.socket.
65 unix://$PCP_RUN_DIR/pmcd.socket
67 unix:/$PCP_RUN_DIR/pmcd.socket
68 unix:$PCP_RUN_DIR/pmcd.socket
69 Refer to __pmParseHostSpec(3) for further details of the host and proxy
71 host components.
72 If any optional connection attributes are to be specified, these are
74 separated from the hostname component via the '?' character. Each at‐
75 tribute is separated by the '&' character, and each can be either a
76 simple attribute flag (such as "compress") or a name=value pair (such
77 as "username=fred").
78 __pmParseHostAttrsSpec takes a null-terminated host-and-attributes
80 specification string and returns an array of pmHostSpec structures,
81 where the array has count entries, and an attrs hash table containing
82 any attributes (including the optional protocol, if it was specified).
83 Full details of the pmHostSpec structures are provided in __pmParse‐
85 HostSpec(3).
86 The __pmHashCtl structure that is filled out on return via attributes,
88 represents each individual attribute in the specification string with
89 any associated value. It should be considered an opaque structure and
90 should be zeroed beforehand.
91 The returned hash table control structure can be iterated using one of
93 the supplied iteration mechanisms - __pmHashWalkCB (a callback-based
94 mechanism) or __pmHashWalk (a simple procedural mechanism). These pro‐
95 vide access to the individual hash nodes, as __pmHashNode entries,
96 which provide access to decoded attributes and their (optional) values.
97 typedef struct __pmHashNode {
99 __pmHashNode *next; /* next node in hash bucket (internal) */
100 unsigned int key; /* key identifying particular attribute */
101 void *data; /* attributes value (optional, string) */
102 } __pmHashNode;
103 There are a set number of valid attributes, however these may be ex‐
105 tended in future releases as new connection parameters become needed.
106 These can be identified via the PCP_ATTR_* macros in the PCP header
107 files.
108 __pmUnparseHostSpec performs the inverse operation, creating a string
110 representation from hosts and attributes structures. The size of the
111 supplied string buffer must be provided by the caller using the size
112 parameter.
113
115 If the given string is successfully parsed __pmParseHostAttrsSpec re‐
116 turns zero. In this case the dynamic storage allocated by __pmParse‐
117 HostAttrsSpec can be released by calling __pmFreeHostAttrsSpec using
118 the addresses returned from __pmParseHostAttrsSpec
119 Alternatively, the hosts and attributes memory can be freed separately,
121 using __pmFreeHostSpec(3) and __pmFreeAttrsSpec.
122 __pmParseHostAttrsSpec returns PM_ERR_GENERIC and a dynamically allo‐
124 cated error message string in errmsg, if the given string does not
125 parse, and the user-supplied errmsg pointer is non-null. Be sure to
126 free(3) the error message string in this situation.
127 In the case of an error, both hosts and attributes are undefined. In
129 the case of success, errmsg is undefined.
130 On success __pmUnparseHostAttrsSpec returns a positive value indicating
132 the number of characters written into the supplied buffer. However, if
133 the supplied buffer was too small, a negative status code of -E2BIG
134 will be returned.
135
137 pmcd(1), pmproxy(1), pmchart(1), __pmParseHostSpec(3), PMAPI(3) and pm‐
138 NewContext(3).
139Performance Co-Pilot PCP PMPARSEHOSTATTRSSPEC(3)