NAME

       pmdaAttribute - informs a PMDA about client connection attributes

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/pmda.h>

       int pmdaAttribute(int context, int key, char *value, int length, pmdaExt *pmda);

       cc ... -lpcp_pmda -lpcp

DESCRIPTION

       As  part  of  the Performance Metrics Domain Agent (PMDA) API (see PMDA(3)), pmdaAttribute is the generic
       callback for responding to client connection attributes.   These  attributes  include  client  credential
       information, such as user ID and group ID.

       A PMDA that supports connection attributes will provide a private pmdaAttribute callback by assignment to
       version.six.attribute of the pmdaInterface structure, and implement custom logic for any of the attribute
       key-value pairs of interest to it.

       All  attributes are associated with a specific client context, and these can be uniquely identified using
       the ctx first argument.   The  PMDA  should  track  client  connections,  and  disconnections  using  the
       pmdaSetEndContextCallBack(3) interface, as a result.  The pmdaGetContext(3) interface may be particularly
       helpful also.

       All attributes are passed as key-value pairs and the value is always passed as a  null-terminated  string
       of given length.  This includes numeric attributes like the user ID.

       The  most  commonly  used attributes would be PCP_ATTR_USERID and PCP_ATTR_GROUPID but others may also be
       optionally passed (such as PCP_ATTR_USERNAME) if they are available.  Some attributes will be consumed by
       pmcd  and  never  through  passed  to  PMDAs, such as PCP_ATTR_PASSWORD.  A complete list of all possible
       attributes can be found in the headers listed above, all are prefixed by PCP_ATTR.

DIAGNOSTICS

       pmdaAttribute should return either zero on success, or a negative return code to  indicate  an  error  in
       handling the attribute.  This return code cannot be used to indicate a client should be disallowed access
       - such functionality must be performed by the agent in response to callbacks for the client  in  question
       (using  PM_ERR_PERMISSION for those specific callbacks, for that specific client.  In other words, errors
       will be be passed to PMCD but there is no guarantee made that the error will be return to the client  and
       result in termination of the client, for example.

CAVEAT

       The PMDA must be using PMDA_PROTOCOL_6 or later, as specified in the call to pmdaDSO(3) or pmdaDaemon(3).

SEE ALSO

       PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pmdaMain(3) and pmdaGetContext(3).