Unix/Linux Go Back    


CentOS 7.0 - man page for __pmfreeattrsspec (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PMPARSEHOSTATTRSSPEC(3) 						  PMPARSEHOSTATTRSSPEC(3)

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  met-
       ric  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  at-
       tributes  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 associ-
       ated 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 '&' charac-
       ter, 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 in-
       dividual  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 itera-
       tion  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 re-
       leases 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 __pmFree-
       HostSpec(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).

Performance Co-Pilot			       PCP			  PMPARSEHOSTATTRSSPEC(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:54 AM.