# pmparsehostspec

## NAME



           **__pmParseHostSpec** , **__pmUnparseHostSpec** , **__pmFreeHostSpec** - uniform
           host specification parser
    


## C SYNOPSIS



           **#include "pmapi.h"**
           **#include "libpcp.h"**
    
           **int __pmParseHostSpec(const char ***_string_**, __pmHostSpec ****_hostsp_**,**
                                 **int ***_count_**, char ****_errmsg_**);**
           **int __pmUnparseHostSpec(__pmHostSpec ***_hosts_**, int** _count_**,**
                                   **char ***_string_**, size_t** _size_**);**
           **void __pmFreeHostSpec(__pmHostSpec ***_hosts_**, int** _count_**);**
    
           **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



           **__pmParseHostSpec** accepts a **string** specifying the  location  of  a
           PCP  performance metric collector daemon.  The syntax of the vari‐
           ous formats of this **string** is described in PCPIntro(1) where  sev‐
           eral examples are also presented.
    
           The  syntax  allows  the initial pmcd(1) hostname to be optionally
           followed by a list of port numbers, which will be tried  in  order
           when connecting to **pmcd** on that host.  The list of port numbers is
           separated  from  the  hostname using a colon, and each port in the
           list is comma-separated.
    
           In addition, one or more optional pmproxy(1) hosts can  be  speci‐
           fied  (currently, only one proxy host is supported by the PCP pro‐
           tocols).  These are separated from each other and  from  the  **pmcd**
           component using the @ character.  These may also be followed by an
           optional  port  list, using the same comma-separated syntax as be‐
           fore.
    
           **__pmParseHostSpec** takes  a  null-terminated  host   specification
           **string** and returns an array of **__pmHostSpec** structures, where the
           array has **count** entries.
    
           These **__pmHostSpec** structures that are returned via **hostsp** repre‐
           sent  each individual host in the specification **string** and has the
           following declaration:
    
               typedef struct {
                   char    *name;       /* hostname (always valid) */
                   int     *ports;      /* array of host port numbers */
                   int     nports;      /* number of ports in host port array */
               } __pmHostSpec;
    
           **__pmUnparseHostSpec** performs the  inverse  operation,  creating  a
           **string** representation  from  a number of **hosts** structures.  Where
           the **count** of structures indicated by **hosts** is  greater  than  one,
           the  proxy  syntax  is  used to indicate a chain of proxied hosts.
           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 **__pmParseHostSpec** re‐
           turns zero.  In this case the dynamic storage allocated  by  **__pm‐**
           **ParseHostSpec** can  be  released by calling **__pmFreeHostSpec** using
           the address returned from **__pmParseHostSpec** via **hosts**.
    
           **__pmParseHostSpec** returns **PM_ERR_GENERIC** and a  dynamically  allo‐
           cated 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, **hosts** is undefined.  In the case of  suc‐
           cess, **errmsg** is undefined.
    
           On success **__pmUnparseHostSpec** returns a positive value indicating
           the number of characters written into the supplied buffer.  Howev‐
           er,  if  the supplied buffer was too small, a negative status code
           of **-E2BIG** is returned.
    


* * *