pmparsehostattrsspec(3) — Linux manual page

NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | RETURN VALUE | SEE ALSO | COLOPHON

PMPARSEHOSTATTRSSPEC(3) Library Functions Manual PMPARSEHOSTATTRSSPEC(3)

NAME         top

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

C SYNOPSIS         top

       #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         top

       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         top

       __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 (na‐
       tive 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 num‐
       bers and optional proxy host, and optional attributes  which  are
       to  be associated with the connection may be specified.  Some ex‐
       amples follow:

            pcp://nas1.servers.com:[email protected]?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 de‐
       fault  setting will be used - which is the native PCP binary pro‐
       tocol.  However, this can still be overwritten via  the  environ‐
       ment  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 "lo‐
       cal://" ("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=value pair (such as "username=fred").

       __pmParseHostAttrsSpec takes a null-terminated host-and-attribut‐
       es 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 __pm‐
       ParseHostSpec(3).

       The __pmHashCtl structure that is filled out on  return  via  at‐
       tributes,  represents each individual attribute in the specifica‐
       tion 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 attrib‐
       utes 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         top

       If the given string is successfully parsed __pmParseHostAttrsSpec
       returns zero.  In this case  the  dynamic  storage  allocated  by
       __pmParseHostAttrsSpec 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 in‐
       dicating the number  of  characters  written  into  the  supplied
       buffer.   However,  if the supplied buffer was too small, a nega‐
       tive status code of -E2BIG will be returned.

SEE ALSO         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If  you  have  a  bug  report  for  this  manual page, send it to
       [email protected].   This  page  was  obtained  from  the   project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩  on   2024-06-14.
       (At  that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you  believe  there
       is  a  better or more up-to-date source for the page, or you have
       corrections or improvements to the information in  this  COLOPHON
       (which  is  not part of the original manual page), send a mail to
       [email protected]

Performance Co-Pilot               PCP           PMPARSEHOSTATTRSSPEC(3)

Pages that refer to this page: pmparsehostspec(3)