NAME

       __pmParseHostAttrsSpec,  __pmUnparseHostAttrsSpec,  __pmFreeHostAttrsSpec,  __pmFreeAttrsSpec  - host and
       attributes specification parser

C SYNOPSIS

       #include "pmapi.h"
       #include "libpcp.h"

       int __pmParseHostAttrsSpec(const char *string, __pmHostSpec **hostsp, int *count, __pmHashCtl *attrs,
               char **errmsg);
       int __pmUnparseHostAttrsSpec(__pmHostSpec *hostsp, int *count, __pmHashCtl *attrs, char *string, size_t
               size);
       void __pmFreeHostAttrsSpec(__pmHostSpec *hosts, int count, __pmHashCtl *attrs);
       void __pmFreeAttrsSpec(__pmHashCtl *attrs);

       cc ... -lpcp

CAVEAT

       This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

       These interfaces are not part of the PCP APIs that are guaranteed to remain fixed  across  releases,  and
       they may not work, or may provide different semantics at some point in the future.

DESCRIPTION

       __pmParseHostAttrsSpec  accepts  a  string  specifying the location of a PCP performance metric collector
       daemon, and any attributes that should be associated with the connection to that daemon.

       The syntax allows the optional specification of a protocol (native PCP protocol, encrypted  PCP  protocol
       or unix domain socket protocol).

       If  the specified protocol is native PCP protocol, or encrypted PCP protocol, an initial pmcd(1) hostname
       with optional port numbers and optional proxy host, and optional attributes which are  to  be  associated
       with the connection may be specified.  Some examples follow:

            pcp://nas1.servers.com:44321@firewalls.r.us?compress
            pcps://nas1.servers.com?user=otto&pass=blotto&compress

       If the specified protocol is a unix domain socket protocol, the path to the socket in the local file sys‐
       tem  may be specified along with optional attributes which are to be associated with the connection.  For
       example:

            unix://$PCP_RUN_DIR/pmcd.socket:?compress
            local://my/local/pmcd.socket:?user=otto&pass=blotto&compress

       If the optional protocol component is not specified, then the default setting will be used - which is the
       native PCP binary protocol.  However, this can still be overwritten via the environment as  described  in
       PCPIntro(1).   If  the protocol prefix is specified, it must be one of either "pcp://" (clear), "pcps://"
       (secure, encrypted), "unix://" (authenticated local) or "local://" ("unix://" then "pcp://").

       The path specified for the "unix://" and "local://" protocols will always be interpreted as  an  absolute
       path name. For example, the following are all interpreted identically as $PCP_RUN_DIR/pmcd.socket.

            unix://$PCP_RUN_DIR/pmcd.socket
            unix:/$PCP_RUN_DIR/pmcd.socket
            unix:$PCP_RUN_DIR/pmcd.socket

       Refer to __pmParseHostSpec(3) for further details of the host and proxy host components.

       If  any  optional connection attributes are to be specified, these are separated from the hostname compo‐
       nent via the '?' character.  Each attribute is separated by the '&' character, and each can be  either  a
       simple attribute flag (such as "compress") or a name=value pair (such as "username=fred").

       __pmParseHostAttrsSpec  takes  a  null-terminated host-and-attributes specification string and returns an
       array of __pmHostSpec structures, where the array has count entries, and an attrs hash  table  containing
       any attributes (including the optional protocol, if it was specified).

       Full details of the __pmHostSpec structures are provided in __pmParseHostSpec(3).

       The  __pmHashCtl  structure  that  is filled out on return via attributes, represents each individual at‐
       tribute in the specification string with any associated value.  It should be considered an opaque  struc‐
       ture and should be zeroed beforehand.

       The  returned hash table control structure can be iterated using one of the supplied iteration mechanisms
       - __pmHashWalkCB (a callback-based mechanism) or __pmHashWalk (a  simple  procedural  mechanism).   These
       provide access to the individual hash nodes, as __pmHashNode entries, which provide access to decoded at‐
       tributes and their (optional) values.

           typedef struct __pmHashNode {
               __pmHashNode    *next;    /* next node in hash bucket (internal) */
               unsigned int    key;      /* key identifying particular attribute */
               void            *data;    /* attributes value (optional, string) */
           } __pmHashNode;

       There  are a set number of valid attributes, however these may be extended in future releases as new con‐
       nection parameters become needed.  These can be identified via the PCP_ATTR_* macros in  the  PCP  header
       files.

       __pmUnparseHostSpec  performs  the inverse operation, creating a string representation from hosts and at‐
       tributes structures.  The size of the supplied string buffer must be provided by  the  caller  using  the
       size parameter.

RETURN VALUE

       If the given string is successfully parsed __pmParseHostAttrsSpec returns zero.  In this case the dynamic
       storage  allocated  by  __pmParseHostAttrsSpec can be released by calling __pmFreeHostAttrsSpec using the
       addresses returned from __pmParseHostAttrsSpec

       Alternatively, the hosts and attributes memory can be freed  separately,  using  __pmFreeHostSpec(3)  and
       __pmFreeAttrsSpec.

       __pmParseHostAttrsSpec returns PM_ERR_GENERIC and a dynamically allocated error message string in errmsg,
       if the given string does not parse, and the user-supplied errmsg pointer is non-null.  Be sure to free(3)
       the error message string in this situation.

       In  the case of an error, both hosts and attributes are undefined.  In the case of success, errmsg is un‐
       defined.

       On success __pmUnparseHostAttrsSpec returns a positive value indicating the number of characters  written
       into  the  supplied  buffer.   However,  if  the supplied buffer was too small, a negative status code of
       -E2BIG will be returned.

SEE ALSO

       pmcd(1), pmproxy(1), pmchart(1), __pmParseHostSpec(3), PMAPI(3) and pmNewContext(3).

Performance Co-Pilot                                   PCP                               PMPARSEHOSTATTRSSPEC(3)