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

DESCRIPTION

24       __pmParseHostAttrsSpec  accepts  a  string specifying the location of a
25       PCP performance metric collector daemon, and any attributes that should
26       be associated with the connection to that daemon.
27
28       The  syntax allows the optional specification of a protocol (native PCP
29       protocol, encrypted PCP protocol or unix domain socket protocol).
30
31       If the specified protocol is native PCP protocol, or encrypted PCP pro‐
32       tocol,  an  initial pmcd(1) hostname with optional port numbers and op‐
33       tional proxy host, and optional attributes which are to  be  associated
34       with the connection may be specified.  Some examples follow:
35
36            pcp://nas1.servers.com:44321@firewalls.r.us?compress
37            pcps://nas1.servers.com?user=otto&pass=blotto&compress
38
39       If the specified protocol is a unix domain socket protocol, the path to
40       the socket in the local file system may be specified along with option‐
41       al  attributes which are to be associated with the connection.  For ex‐
42       ample:
43
44            unix://$PCP_RUN_DIR/pmcd.socket:?compress
45            local://my/local/pmcd.socket:?user=otto&pass=blotto&compress
46
47       If the optional protocol component is not specified, then  the  default
48       setting will be used - which is the native PCP binary protocol.  Howev‐
49       er, this can still be overwritten via the environment as  described  in
50       PCPIntro(1).   If  the  protocol prefix is specified, it must be one of
51       either "pcp://" (clear), "pcps://" (secure, encrypted), "unix://"  (au‐
52       thenticated local) or "local://" ("unix://" then "pcp://").
53
54       The  path specified for the "unix://" and "local://" protocols will al‐
55       ways be interpreted as an absolute path name. For example, the  follow‐
56       ing are all interpreted identically as $PCP_RUN_DIR/pmcd.socket.
57
58            unix://$PCP_RUN_DIR/pmcd.socket
59            unix:/$PCP_RUN_DIR/pmcd.socket
60            unix:$PCP_RUN_DIR/pmcd.socket
61
62       Refer to __pmParseHostSpec(3) for further details of the host and proxy
63       host components.
64
65       If any optional connection attributes are to be  specified,  these  are
66       separated  from the hostname component via the '?' character.  Each at‐
67       tribute is separated by the '&' character, and each  can  be  either  a
68       simple  attribute  flag (such as "compress") or a name=value pair (such
69       as "username=fred").
70
71       __pmParseHostAttrsSpec  takes  a  null-terminated   host-and-attributes
72       specification  string  and  returns  an array of pmHostSpec structures,
73       where the array has count entries, and an attrs hash  table  containing
74       any attributes (including the optional protocol, if it was specified).
75
76       Full  details  of  the pmHostSpec structures are provided in __pmParse‐
77       HostSpec(3).
78
79       The __pmHashCtl structure that is filled out on return via  attributes,
80       represents  each  individual attribute in the specification string with
81       any associated value.  It should be considered an opaque structure  and
82       should be zeroed beforehand.
83
84       The  returned hash table control structure can be iterated using one of
85       the supplied iteration mechanisms -  __pmHashWalkCB  (a  callback-based
86       mechanism) or __pmHashWalk (a simple procedural mechanism).  These pro‐
87       vide access to the individual  hash  nodes,  as  __pmHashNode  entries,
88       which provide access to decoded attributes and their (optional) values.
89
90           typedef struct __pmHashNode {
91               __pmHashNode    *next;    /* next node in hash bucket (internal) */
92               unsigned int    key;      /* key identifying particular attribute */
93               void            *data;    /* attributes value (optional, string) */
94           } __pmHashNode;
95
96       There  are  a  set number of valid attributes, however these may be ex‐
97       tended in future releases as new connection parameters  become  needed.
98       These  can  be  identified  via the PCP_ATTR_* macros in the PCP header
99       files.
100
101       __pmUnparseHostSpec performs the inverse operation, creating  a  string
102       representation  from  hosts and attributes structures.  The size of the
103       supplied string buffer must be provided by the caller  using  the  size
104       parameter.
105

RETURN VALUE

107       If  the  given string is successfully parsed __pmParseHostAttrsSpec re‐
108       turns zero.  In this case the dynamic storage allocated  by  __pmParse‐
109       HostAttrsSpec  can  be  released by calling __pmFreeHostAttrsSpec using
110       the addresses returned from __pmParseHostAttrsSpec
111
112       Alternatively, the hosts and attributes memory can be freed separately,
113       using __pmFreeHostSpec(3) and __pmFreeAttrsSpec.
114
115       __pmParseHostAttrsSpec  returns  PM_ERR_GENERIC and a dynamically allo‐
116       cated error message string in errmsg, if  the  given  string  does  not
117       parse,  and  the  user-supplied errmsg pointer is non-null.  Be sure to
118       free(3) the error message string in this situation.
119
120       In the case of an error, both hosts and attributes are  undefined.   In
121       the case of success, errmsg is undefined.
122
123       On success __pmUnparseHostAttrsSpec returns a positive value indicating
124       the number of characters written into the supplied buffer.  However, if
125       the  supplied  buffer  was  too small, a negative status code of -E2BIG
126       will be returned.
127

SEE ALSO

129       pmcd(1), pmproxy(1), pmchart(1), __pmParseHostSpec(3), PMAPI(3) and pm‐
130       NewContext(3).
131
132
133
134Performance Co-Pilot                  PCP              PMPARSEHOSTATTRSSPEC(3)
Impressum