cfg_psm_memops(3)cfg_psm_memops(3)NAME
cfg_psm_memops, cfg_psm_memadd, cfg_psm_memrem, cfg_psm_memget - Per‐
form member operations on the Process Set manager (PSM) set
SYNOPSIS
Library: configuration management library, libcfg.a. #include <cfg.h>
cfg_status_t cfg_psm_memadd(
const char *node,
const char *catnam,
pid_t pid ); cfg_status_t cfg_psm_memrem(
const char *node,
const char *catnam,
pid_t pid ); cfg_status_t cfg_psm_memget(
const char *node,
const char *catnam,
pid_t pid,
psm_memrsp_t **memrsp ); void cfg_psm_memfree(
psm_memrsp_t **memrsp );
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 a process instance defined by the
value of pid in the catnam category to the process set on the host
defined by the value of host node. Removes the process instance
defined by the value of pid in the catnam category from the process set
on the host defined by the value of host node. Retrieves the process
instance information from the process Sset on host node. The following
conditions apply: If the value of pid is not _PSM_ALLPID, information
on a specific process is returned. Specify the catnam to ensure a
process is in a specific category, or specify _PSM_ALLCAT if this check
is not wanted. If the value of pid is _PSM_ALLPID and the value of
catnam is not _PSM_ALLCAT, all instances for a specific category are
returned. If the value of pid is _PSM_ALLPID and the value of catnam
is _PSM_ALLCAT, all instances in all categories are returned. When the
response is complete, you must free memory using cfg_psm_memfree().
Frees the memrsp array allocated by cfg_psm_memget().
Operation and Usage Instructions
Upon successful completion of the cfg_psm_memget() function, the memrsp
parameter points to an array of one or more struct psm_memrsp_s ele‐
ments. These elements are declared in the psm.h header file and are
duplicated below. Each element represents a specific process instance.
In case of an error, the parameter memrsp is set to NULL:
typedef struct psm_memrsp_s {
unsigned int mrs_listidx; /* member number in list */
unsigned int mrs_listcnt; /* total members in list */
unsigned int mrs_total; /* total matching members */
unsigned int mrs_pid; /* process id */
unsigned int mrs_exitcode; /* exit status code */
unsigned int mrs_flags; /* process flags (PSM_FL_*) */
char mrs_name[PSM_MEMLEN]; /* unique name of member */
char mrs_state[PSM_STATELEN]; /* state ("running", etc.) */
char mrs_argv[PSM_ARGVLEN]; /* saved argv */
} psm_memrsp_t;
These elements are defined as follows: mrs_listidx holds the index
(starting at 1) of an instance entry in the array. mrs_listcnt and
mrs_total hold the total number of instances. Both values will always
be the same when you use the cfg_psm_memget() function. mrs_pid is the
process identifier (PID) associated with the instance. mrs_exitcode
holds the termination status if the process has exited. This element is
suitable for use with the wait status macros. See wait(2). mrs_name is
a cluster-wide unique name of the form node-id-process-id. mrs_state
is a user-modifiable string containing useful state information.
mrs_argv contains the process argument vector obtained from address
space when cfg_psm_memadd() is invoked. mrs_flags are bit flags,
described as follows: PSM_FL_EXIT is set if the process has exited.
PSM_FL_ARGTRUNC is set if mrs_argv was truncated.
In case of a generic query and no instances are registered, an array of
one element is returned with all fields set to 0.
Processes can self-register with the PSM using the _PSM_CAT_* indices
and the _PSM_REGSELF(idx) macro defined in the cfg.h header file. See
the EXAMPLES section for a usage example. However, the following
caveats apply: Take care when placing the _PSM_REGSELF() macro in
existing services. Some processes call fork, after which, the parent
process exits and the child process persists. In such cases, insert the
_PSM_REGSELF() macro in the child code for the child process. After
initialization, some processes modify their argument vector. If you do
not nsert the _PSM_REGSELF() macro before this event occurs the saved
argument vector will be useless.
RESTRICTIONS
The node should be specified as _PSM_MYNODE when operating on the
process set of the local host, otherwise it can contain the name of a
target host. Future implementations will permit _PSM_ALLNODE to gather
cluster-wide information, or information from a comma-separated list of
host names. A successful response from any node guarantees a CFG_SUC‐
CESS return to the caller (errors from the other nodes are ignored).
In the present implementation, multinode queries return an ENOTSUP sub‐
system error.
RETURN VALUES
Upon successful completion, the cfg_psm_memadd(), cfg_psm_memrem(), and
cfg_psm_memget() 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: The specified instance pid was found to exist in a category
during an add operation. The process is being created or doing exec
during a proxy-add operation. There was a general KSM failure during
an add operation. The PSM process set is not registered with KSM. The
category or pid was not found. User or kernel memory allocation
failed. The maximum number of instances is exceeded during an add
operation. This operation is not yet implemented. The instance pid
could not be found in process table during an add operation.
EXAMPLES
The following example registers a process in the mountd category on the
local host:
#include <cfg.h>
_PSM_REGSELF(_PSM_CAT_MOUNTD);
In this example, a proxy is registering process id 123 into the
abcd category on remote host zeus:
cfg_status_t retval;
if ((retval = cfg_psm_memadd("zeus", "abcd", 123)) !=
CFG_SUCCESS) print_error(retval);
The following example retrieves all instances in the mountd cat‐
egory on the local host and determines how many are still run‐
ning.
#include <cfg.h>
#include <stdio.h>
struct psm_memrsp_s *memrsp, *msp, *msp_e;
cfg_status_t retval;
const char *catnam = "mountd";
int runcount = 0;
retval = cfg_psm_memget(_PSM_MYNODE, catnam, _PSM_ALLPID,
&memrsp);
if (retval != CFG_SUCCESS) { print_error(retval);
} else { msp = memrsp; msp_e = memrsp +
msp->mrs_listcnt; while (msp < msp_e) { if
((msp->mrs_flags & PSM_FL_EXIT) == 0) runcount++;
msp++; } cfg_psm_memfree(memrsp);
printf("running %d instance(s) of %s\n", runcount, catnam);
}
SEE ALSO
Functions: fork(2), libcfg(3), cfg_psm_catops(3)wait(2)
Files: PSM(4)cfg_psm_memops(3)