# pmparsehostattrsspec

## 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  proto‐
           col).
    
           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 con‐
           nection.  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  de‐
           fault setting will be used - which is the native PCP binary proto‐
           col.   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,  en‐
           crypted), "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/pm‐_
           _cd.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=val‐
           ue pair (such as "username=fred").
    
           **__pmParseHostAttrsSpec** takes a null-terminated host-and-attributes
           specification  **string** and returns an array of **__pmHostSpec** struc‐
           tures, 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  **__pm‐**
           **ParseHostSpec**(3).
    
           The **__pmHashCtl** structure that is filled out on return via **attrib‐**
           **utes** ,  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 call‐
           back-based mechanism) or **__pmHashWalk**(a simple procedural  mecha‐
           nism).   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 **__pm‐**
           **ParseHostAttrsSpec** can  be  released  by  calling  **__pmFreeHostAt‐**
           **trsSpec** using the addresses returned from **__pmParseHostAttrsSpec**
    
           Alternatively,  the **hosts** and **attributes** memory can be freed sepa‐
           rately, 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 undefined.
    
           On success **__pmUnparseHostAttrsSpec** returns a positive value indi‐
           cating  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.
    


* * *