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).