 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
cfg_psm_catops(3)
NAME
cfg_psm_catops, cfg_psm_catadd, cfg_psm_catrem, cfg_psm_catget - Perform
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:
cfg_psm_catadd()
Adds the category defined by the variable catnam to the process set on
the host defined by the value of host node.
cfg_psm_catrem()
Removes the category defined by the variable catnam from the process
set on the host defined by the value of host node.
cfg_psm_catget()
Retrieves the category information from the process set on host node.
Information on all categories is returned if the value of catnam is
_PSM_ALLCAT, otherwise the data returned is limited to category catnam.
When the response is complete, you must free memory using
cfg_psm_catfree().
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 elements.
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 specified
by the value of PSM_CATLEN, including the trailing NULL. The underlying
KSM only supports a flat namespace. To avoid potential problems between
category names, developers must use a common string followed 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_categories[].
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 processes 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 target 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:
EALREADY
An existing category of this name was found when performing an add
operation.
EFAIL
There was a general KSM failure during an add operation.
EINVAL
The PSM process set is not registered with KSM.
ENOENT
The category was not found during a remove or get operation.
ENOMEM
User or kernel memory allocation failed.
ENOSPC
The maximum number of categories is exceeded during an add operation.
ENOTSUP
This operation is not yet implemented.
EXAMPLES
1. 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);
2. 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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|