 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
cfg_psm_memops(3)
NAME
cfg_psm_memops, cfg_psm_memadd, cfg_psm_memrem, cfg_psm_memget - Perform
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:
cfg_psm_memadd()
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.
cfg_psm_memrem()
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.
cfg_psm_memget()
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().
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 elements.
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_SUCCESS return to the
caller (errors from the other nodes are ignored). In the present
implementation, multinode queries return an ENOTSUP subsystem 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:
EALREADY
The specified instance pid was found to exist in a category during an
add operation.
EBUSY
The process is being created or doing exec during a proxy-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 or pid was not found.
ENOMEM
User or kernel memory allocation failed.
ENOSPC
The maximum number of instances is exceeded during an add operation.
ENOTSUP
This operation is not yet implemented.
ESRCH
The instance pid could not be found in process table during an add
operation.
EXAMPLES
1. The following example registers a process in the mountd category on
the local host:
#include <cfg.h>
_PSM_REGSELF(_PSM_CAT_MOUNTD);
2. 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);
3. The following example retrieves all instances in the mountd category
on the local host and determines how many are still running.
#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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|