nodeupdown_module - Man Page

#include <nodeupdown.h>

#include <nodeupdown/nodeupdown_backend_module.h>

#include <nodeupdown/nodeupdown_clusterlist_module.h>

#include <nodeupdown/nodeupdown_config.h>

#include <nodeupdown/nodeupdown_config_module.h>

#include <nodeupdown/nodeupdown_constants.h>

#include <nodeupdown/nodeupdown_devel.h>

int nodeupdown_add_up_node(nodeupdown_t handle, const char *node);

int nodeupdown_add_down_node(nodeupdown_t handle, const char *node);

int nodeupdown_not_discovered_check(nodeupdown_t handle, const char *node);

void nodeupdown_set_errnum(nodeupdown_t handle, int errnum);

Development of nodeupdown modules will rely on the nodeupdown development functions that give the module writer the ability to modify the contents in the nodeupdown handle.

nodeupdown_add_up_node and nodeupdown_add_down_node add an up or down node to the nodeupdown handle respectively.

nodeupdown_not_discovered_check will check if the specified node currently exists in the handle.  If it does not, the node will be added to the internal list of down nodes.

nodeupdown_set_errnum will set the errnum inside the nodeupdown handle to the specified errnum.

Additional information about the development of nodeupdown backend, clusterlist, and config modules can be found below.

A nodeupdown backend module of the name 'foobar' can be written by compiling a shared object library with the filename nodeupdown_backend_foobar.so, and installing it in the nodeupdown package library directory /usr/lib64/nodeupdown.

The backend module should define a structure of the following type:

struct nodeupdown_backend_module_info {
char *backend_module_name;
Nodeupdown_backend_default_hostname default_hostname;
Nodeupdown_backend_default_port default_port;
Nodeupdown_backend_default_timeout_len default_timeout_len;
Nodeupdown_backend_setup setup;
Nodeupdown_backend_cleanup cleanup;
Nodeupdown_backend_get_updown_data get_updown_data;
};

The structure should be named 'backend_module_info' and be populated with the following information.

The field 'backend_module_name' should indicate the name of the backend module.

The field 'default_hostname' should point to a function of the following type:

typedef char *(*Nodeupdown_backend_default_hostname)(nodeupdown_t);

The 'default_hostname' function returns a pointer to a string for the default hostname for this backend module.

The field 'default_port' should point to a function of the following type:

typedef int (*Nodeupdown_backend_default_port)(nodeupdown_t);

The 'default_port' function returns the default port for this backend module.

The field 'default_timeout_len' should point to a function of the following type:

typedef int (*Nodeupdown_backend_default_timeout_len)(nodeupdown_t);

The 'default_timeout_len' function returns the default timeout_len for this backend module.

The field 'setup' should point to a function of the following type:

typedef int (*Nodeupdown_backend_setup)(nodeupdown_t);

The 'setup' function sets up the backend module with whatever initialization is necessary.  It returns 0 on success, -1 on error.

The field 'cleanup' should point to a function of the following type:

typedef int (*Nodeupdown_backend_cleanup)(nodeupdown_t);

The 'cleanup' function cleans up the backend module from earlier initializations.  It returns 0 on success, -1 on error.

The field 'get_updown_data' should point to a function of the following type:

typedef int (*Nodeupdown_backend_get_updown_data)(nodeupdown_t, const char *, unsigned int, unsigned int, char *);

The 'get_updown_data' function retrieves all updown data from the backend technology and stores it in the nodeupdown_t handle.  The nodeupdown development functions nodeupdown_add_up_node and nodeupdown_add_down_node should be used to add the up or down nodes into the handle.  'get_updown_data' is passed a hostname, port, timeout_len, and reserved fields similar to nodeupdown_load_data(3). If values were passed to nodeupdown_load_data(3), they are forwarded on to 'get_updown_data'.  However, if defaults were passed to nodeupdown_load_data(3) the appropriate values have already been read and compauted from configuration modules, configuration files, or the above backend default functions.

All of the above functions must be defined in the module and listed in the 'backend_module_info' structure.

A nodeupdown clusterlist module of the name 'foobar' can be written by compiling a shared object library with the filename nodeupdown_clusterlist_foobar.so, and installing it in the nodeupdown package library directory /usr/lib64/nodeupdown.

The clusterlist module should define a structure of the following type:

struct nodeupdown_clusterlist_module_info {
  char *clusterlist_module_name;
  Nodeupdown_clusterlist_setup setup;
  Nodeupdown_clusterlist_cleanup cleanup;
  Nodeupdown_clusterlist_get_numnodes get_numnodes;
  Nodeupdown_clusterlist_is_node_in_cluster is_node_in_cluster;
  Nodeupdown_clusterlist_get_nodename get_nodename;
  Nodeupdown_clusterlist_compare_to_clusterlist compare_to_clusterlist;
};

The structure should be named 'clusterlist_module_info' and be populated with the following information.

The field 'clusterlist_module_name' should indicate the name of the clusterlist module.

The field 'setup' should point to a function of the following type:

typedef int (*Nodeupdown_clusterlist_setup)(nodeupdown_t);

The 'setup' function sets up the clusterlist module with whatever initialization is necessary.  It returns 0 on success, -1 on error.

The field 'cleanup' should point to a function of the following type:

typedef int (*Nodeupdown_clusterlist_cleanup)(nodeupdown_t);

The 'cleanup' function cleans up the clusterlist module from earlier initializations.  It returns 0 on success, -1 on error.

The field 'get_numnodes' should point to a function of the following type:

typedef int (*Nodeupdown_clusterlist_get_numnodes)(nodeupdown_t);

The 'get_numnodes' function returns the number of nodes in the cluster, or -1 on error.

The field 'is_node_in_cluster' should point to a function of the following type:

typedef int (*Nodeupdown_clusterlist_is_node_in_cluster)(nodeupdown_t, const char *);

The 'is_node_in_cluster' function is passed a nodename.  It returns 1 if the specified node is in the cluster, 0 if not, and -1 on error.

The field 'get_nodename' should point to a function of the following type:

typedef int (*Nodeupdown_clusterlist_get_nodename)(nodeupdown_t, const char *, char *, unsigned int);

The 'get_nodename' function is passed a nodename, a buffer, and a buffer length.  It determines the appropriate nodename to use and copies it into the buffer.  This function is primarily used to convert aliased nodenames into the appropriate nodename to use for calculations.  The majority of clusterlist module writers will probably copy the nodename directly into the buffer and not do any calculations.  'get_nodename' returns 0 on success, -1 on error.

The field 'compare_to_clusterlist' should point to a function of the following type:

typedef int (*Nodeupdown_clusterlist_compare_to_clusterlist)(nodeupdown_t);

The 'compare_to_clusterlist' function is used to determine any additional down nodes in the cluster.  Clusterlist module writers will typically iterate through the clusterlist module's list of nodes, and pass each one to nodeupdown_not_discovered_check.

All of the above functions must be defined in the module and listed in the 'clusterlist_module_info' structure.

A nodeupdown config module of the name 'foobar' can be written by compiling a shared object library with the filename nodeupdown_config_foobar.so, and installing it in the nodeupdown package library directory /usr/lib64/nodeupdown.

The config module should define a structure of the following type:

struct nodeupdown_config_module_info {
  char *config_module_name;
  Nodeupdown_config_setup setup;
  Nodeupdown_config_cleanup cleanup;
  Nodeupdown_config_load_default load_default;
};

The structure should be named 'config_module_info' and be populated with the following information.

The field 'config_module_name' should indicate the name of the config module.

The field 'setup' should point to a function of the following type:

typedef int (*Nodeupdown_config_setup)(nodeupdown_t);

The 'setup' function sets up the config module with whatever initialization is necessary.  It returns 0 on success, -1 on error.

The field 'cleanup' should point to a function of the following type:

typedef int (*Nodeupdown_config_cleanup)(nodeupdown_t);

The 'cleanup' function cleans up the config module from earlier initializations.  It returns 0 on success, -1 on error.

The field 'load_default' should point to a function of the following type:

typedef int (*Nodeupdown_config_load_default)(nodeupdown_t, struct nodeupdown_config *);

The 'load_default' function loads an alternate set of configuration values and stores them within the configuration structure passed in.

All of the above functions must be defined in the module and listed in the 'config_module_info' structure.

The structure nodeupdown_config is defined as:

struct nodeupdown_config {
  char hostnames[NODEUPDOWN_CONFIG_HOSTNAMES_MAX+1][NODEUPDOWN_MAXHOSTNAMELEN+1];
  int hostnames_len;
  int hostnames_flag;
  int port;
  int port_flag;
  int timeout_len;
  int timeout_len_flag;
};

The 'hostnames' field should store an array of default hostnames for nodeupdown_load_data(3).

The 'port' field should store the default port for nodeupdown_load_data(3).

The 'timeout_len' field should store the default timeout length for nodeupdown_load_data(3).

Any parameter that is set in the configuration structure must have its respective flag set.  The 'hostnames' field must also have the loaded.

libnodeupdown(3)