NAME

       gendlib - perl library for querying genders file

SYNOPSIS

       require ``/usr/lib/genders/gendlib.pl'';

DESCRIPTION

       This package contains common functions for manipulating the genders file.  Previously this
       code existed only in the nodeattr command, but  applications  that  must  repeatedly  call
       nodeattr  would  spend  a  great deal of time reading and parsing the genders file.  These
       functions create an in-memory cache of genders on the first call;  subsequent  calls  need
       only reference the in-memory copy and are thus speeded up.

       Initialization:

       Genders::init([$path_genders])

              Function   normally  called  internally  for  initialization.   It  can  be  called
              externally with a non-default genders file path and subsequent operations will  use
              this non-default data.  May be called more than once to change genders file.

       Simple Queries:

       Genders::hasattr($attribute, [$node])

              Return  1  if  node  has  attribute, 0 if not.  If node is not specified, use local
              node.

       Genders::getattrval($attribute, [$node])

              Return value of attribute held by node, or empty string if no value  or  node  does
              not have attribute.  If node is not specified, use local node.

       Genders::getnode([$attribute])

              Return  a  list  of  nodes  having  the  specified  attribute.   If a value is also
              specified ("attr=val"), only nodes with  the  specified  attribute  and  value  are
              returned.   If  no  attribute is specified, getnode returns all the nodes listed in
              the genders file.

       Genders::getattr([$node])

              Return a list of attributes held by node.  If node  is  not  specified,  use  local
              node.

       Complex Queries:

       Genders::getallattr()

              Return a list of all attributes in the genders file (one cluster only).

       Genders::get_node_hash(\%node)

              Get  a copy of hash of attributes to node lists for the current cluster (a "hash of
              lists").  Ensure that keys  exist  for  all  possible  attributes  across  clusters
              (though they may point to empty lists).

       Genders::get_clusters()

              Return  a  list  with  the  local  cluster  name  as  the  first  and only element.
              get_clusters() returns a list instead of a scalar for backwards compatability.   If
              the local cluster name is not known, null is returned.

       Genders::gendexp($exp, [$node])

              Evaluate  expression  involving  genders  attributes  and  return the result of the
              evaluation.  Any legal perl expresion using numeric constants,  genders  attributes
              (which  are  converted  into $variables), and the following operators is valid:  !,
              ||, &&, *, +, -, /.  If $node is not specified, assume the local host.

       Conversion:

       Genders::to_altnames()

              Given a list of hostnames as they appear in the genders  file,  return  a  list  of
              alternate names.  On the SP, genders names are assumed to be the initial_hostnames,
              and we use the SDR to convert to reliable_hostnames.  On other systems, we look for
              the  value  of  the  altname  attribute in the genders file.  If the input hostname
              cannot be converted, it is preserved in the output.

       Genders::to_gendnames()

              Performs the inverse of the to_altnames() function.  Just  like  to_altnames(),  an
              input hostname is preserved in the output if it cannot be converted.

SEE ALSO

       nodeattr(1), libgenders(3), Libgenders(3)