|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | RETURN VALUE | SEE ALSO | COLOPHON |
|
|
|
PMPARSEHOSTATTRSSPEC(3) Library Functions Manual PMPARSEHOSTATTRSSPEC(3)
__pmParseHostAttrsSpec, __pmUnparseHostAttrsSpec,
__pmFreeHostAttrsSpec, __pmFreeAttrsSpec - host and attributes
specification parser
#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
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.
__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.
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.
pmcd(1), pmproxy(1), pmchart(1), __pmParseHostSpec(3), PMAPI(3)
and pmNewContext(3).
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)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|