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

NAME

6       __pmParseHostAttrsSpec,    __pmUnparseHostAttrsSpec,    __pmFreeHostAt‐
7       trsSpec, __pmFreeAttrsSpec - host and attributes specification parser
8

C SYNOPSIS

10       #include "pmapi.h"
11       #include "libpcp.h"
12
13       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
21       cc ... -lpcp
22

CAVEAT

24       This  documentation is intended for internal Performance Co-Pilot (PCP)
25       developer use.
26
27       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

DESCRIPTION

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
36       The syntax allows the optional specification of a protocol (native  PCP
37       protocol, encrypted PCP protocol or unix domain socket protocol).
38
39       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
44            pcp://nas1.servers.com:44321@firewalls.r.us?compress
45            pcps://nas1.servers.com?user=otto&pass=blotto&compress
46
47       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
52            unix://$PCP_RUN_DIR/pmcd.socket:?compress
53            local://my/local/pmcd.socket:?user=otto&pass=blotto&compress
54
55       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
62       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
66            unix://$PCP_RUN_DIR/pmcd.socket
67            unix:/$PCP_RUN_DIR/pmcd.socket
68            unix:$PCP_RUN_DIR/pmcd.socket
69
70       Refer to __pmParseHostSpec(3) for further details of the host and proxy
71       host components.
72
73       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
79       __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
84       Full details of the pmHostSpec structures are  provided  in  __pmParse‐
85       HostSpec(3).
86
87       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
92       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
98           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
104       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
109       __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

RETURN VALUE

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
120       Alternatively, the hosts and attributes memory can be freed separately,
121       using __pmFreeHostSpec(3) and __pmFreeAttrsSpec.
122
123       __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
128       In  the  case of an error, both hosts and attributes are undefined.  In
129       the case of success, errmsg is undefined.
130
131       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

SEE ALSO

137       pmcd(1), pmproxy(1), pmchart(1), __pmParseHostSpec(3), PMAPI(3) and pm‐
138       NewContext(3).
139
140
141
142Performance Co-Pilot                  PCP              PMPARSEHOSTATTRSSPEC(3)
Impressum