trusty (3) __pmFreeAttrsSpec.3.gz

NAME

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

C SYNOPSIS

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

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
       system  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
       component  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
       attribute  in  the  specification  string  with  any associated value.  It should be considered an opaque
       structure 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
       attributes 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
       connection 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
       attributes 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(3C) 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
       undefined.

       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).