__pmparsehostspec(3) [centos man page]
PMPARSEHOSTSPEC(3) Library Functions Manual PMPARSEHOSTSPEC(3) NAME
__pmParseHostSpec, __pmUnparseHostSpec, __pmFreeHostSpec - uniform host specification parser C SYNOPSIS
#include <pcp/pmapi.h> #include <pcp/impl.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 DESCRIPTION
__pmParseHostSpec accepts a string specifying the location of a PCP performance metric collector daemon. The syntax of the various formats of this string is described in PCPIntro(1) where several 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 con- necting to pmcd on that host. The portlist 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 specified (currently, only one proxy host is supported by the PCP protocols). 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 before. __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 represent 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 returns zero. In this case the dynamic storage allocated by __pmParseHostSpec can be released by calling __pmFreeHostSpec using the address returned from __pmParseHostSpec via hosts. __pmParseHostSpec 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, hosts is undefined. In the case of success, errmsg is undefined. On success __pmUnparseHostSpec 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 is returned. SEE ALSO
pmcd(1), pmproxy(1), pmchart(1), __pmParseHostAttrsSpec(3), PMAPI(3) and pmNewContext(3). Performance Co-Pilot PCP PMPARSEHOSTSPEC(3)
Check Out this Related Man Page
PMPARSEHOSTATTRSSPEC(3) Library Functions Manual 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 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 op- tional 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 op- tional 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. How- ever, 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 follow- ing 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 at- tribute 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 speci- fied). 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 __pmParse- HostAttrsSpec 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. Howev- er, 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)