cfg_psm_catops(3)cfg_psm_catops(3)NAME
cfg_psm_catops, cfg_psm_catadd, cfg_psm_catrem, cfg_psm_catget - Per‐
form category operations on the Process Set Manager (PSM) set
SYNOPSIS
Library: configuration management library, libcfg.a. #include <cfg.h>
cfg_status_t cfg_psm_catadd(
const char *node,
const char *catnam ); cfg_status_t cfg_psm_catrem(
const char *node,
const char *catnam ); cfg_status_t cfg_psm_catget(
const char *node,
const char *catnam,
psm_catrsp_t **catrsp ); void cfg_psm_catfree(
psm_catrsp_t **catrsp );
DESCRIPTION
Refer to PSM(4) for a description of the Process Set Manager, which
supports the functions described in this reference page.
Functions
Use these functions as follows: Adds the category defined by the vari‐
able catnam to the process set on the host defined by the value of host
node. Removes the category defined by the variable catnam from the
process set on the host defined by the value of host node. Retrieves
the category information from the process set on host node. Informa‐
tion on all categories is returned if the value of catnam is _PSM_ALL‐
CAT, otherwise the data returned is limited to category catnam. When
the response is complete, you must free memory using cfg_psm_catfree().
Frees the memory allocated to the cfg_psm_catget() function.
Operation and Usage Instructions
Upon successful completion of the cfg_psm_catget() function, the catrsp
parameter points to an array of one or more struct psm_catrsp_s ele‐
ments. These elements are declared in the psm.h header file and are
duplicated below. Each element represents a specific category.
In case of an error, the catrsp parameter is set to NULL:
typedef struct psm_catrsp_s {
unsigned int crs_listidx; /* category number in list */
unsigned int crs_listcnt; /* total categories in list */
unsigned int crs_total; /* total matching categories */
unsigned int crs_memcnt; /* number of members */
char crs_cat[PSM_CATLEN]; /* category name */
} psm_catrsp_t;
These elements are defined as follows: crs_listidx holds the index
(starting at 1) of a category entry in the array. crs_listcnt and
crs_total hold the total number of categories. Both values will always
be the same when you use the cfg_psm_catget() function. crs_memcnt
contains the number of process instances in the category, where each
instance represents a process. Processes included in this count might
be terminated. Refer to cfg_psm_memops(3) for more information.
crs_cat is the NULL-terminated category name. In the case of a generic
query and no instantiated categories, an array of one element is
returned with all fields set to 0.
A catnam name string must not be longer than the number of bytes speci‐
fied by the value of PSM_CATLEN, including the trailing NULL. The
underlying KSM only supports a flat namespace. To avoid potential prob‐
lems between category names, developers must use a common string fol‐
lowed by an underscore preceding every name. For example, CPQ_kewld,
where CPQ_ is the string common to all names. System-defined categories
never contain an underscore.
There are no other restrictions on the value of catnam.
A list of some system-defined categories which are instantiated at boot
time is available from the external array const char *_psm_cate‐
gories[]. You can determine the number of strings in this array by
using const int _psm_ncategories. Additionally, you can use the
_PSM_CAT_* indexes to locate specific category names in const char
*_psm_categories[]. These category names are most commonly used by pro‐
cesses that self-register their instance(s). See the cfg.h header file
and cfg_psm_memops(3).
See PSM(4) for more information on the Process Set Manager.
RESTRICTIONS
The value of node is specified as _PSM_MYNODE when operating on the
process set of the local host, otherwise it contains the name of a tar‐
get host. Future implementations will permit _PSM_ALLNODE to gather
cluster-wide information, or a comma-separated list of host names. A
successful response from any node guarantees a CFG_SUCCESS return to
the caller (errors from the other nodes are ignored). In the present
implementation, multinode queries return a ENOTSUP subsystem error.
RETURN VALUES
Upon successful completion, the cfg_psm_catadd(), cfg_psm_catrem(), and
cfg_psm_catget() functions return CFG_SUCCESS. Other return values
indicate that an error has occurred. For information about handling
return values from routines in the configuration management library,
refer to libcfg(3).
ERRORS
The following subsystem errors might be merged with a CFG_FRAME_SUCCESS
response: An existing category of this name was found when performing
an add operation. There was a general KSM failure during an add opera‐
tion. The PSM process set is not registered with KSM. The category
was not found during a remove or get operation. User or kernel memory
allocation failed. The maximum number of categories is exceeded during
an add operation. This operation is not yet implemented.
EXAMPLES
The following example adds the abcd category to the local host.
#include <cfg.h>
#include <stdio.h>
cfg_status_t retval;
if ((retval = cfg_psm_catadd(_PSM_MYNODE, "abcd")) !=
CFG_SUCCESS) print_error(retval);
The following example retrieves all categories and prints the
names of those with four or more process instances:
#include <cfg.h>
#include <stdio.h>
struct psm_catrsp_s *catrsp, *csp, *csp_e;
cfg_status_t retval;
retval = cfg_psm_catget(_PSM_MYNODE, _PSM_ALLCAT,
&catrsp;);
if (retval != CFG_SUCCESS) { print_error(retval);
} else { csp = catrsp; csp_e = catrsp +
csp->crs_listcnt; while (csp < csp_e) { if
(csp->crs_memcnt >= 4) puts(csp->crs_cat);
csp++; } cfg_psm_catfree(catrsp);
}
SEE ALSO
Functions: fork(2), libcfg(3), cfg_psm_memops(3)wait(2)
Files: PSM(4)cfg_psm_catops(3)
