NAME

       Libgenders - Perl extension for libgenders

SYNOPSIS

        use Libgenders;

        Libgenders::GENDERS_ERR_SUCCESS
        Libgenders::GENDERS_ERR_NULLHANDLE
        Libgenders::GENDERS_ERR_OPEN
        Libgenders::GENDERS_ERR_READ
        Libgenders::GENDERS_ERR_PARSE
        Libgenders::GENDERS_ERR_NOTLOADED
        Libgenders::GENDERS_ERR_ISLOADED
        Libgenders::GENDERS_ERR_OVERFLOW
        Libgenders::GENDERS_ERR_PARAMETERS
        Libgenders::GENDERS_ERR_NULLPTR
        Libgenders::GENDERS_ERR_NOTFOUND
        Libgenders::GENDERS_ERR_SYNTAX
        Libgenders::GENDERS_ERR_QUERYINPUT
        Libgenders::GENDERS_ERR_OUTMEM
        Libgenders::GENDERS_ERR_MAGIC
        Libgenders::GENDERS_ERR_INTERNAL
        Libgenders::GENDERS_ERR_ERRNUMRANGE
        Libgenders::GENDERS_DEFAULT_FILE

        $handle = Libgenders->genders_handle_create();
        $handle->genders_load_data([$filename]);

        $handle->genders_errnum()
        $handle->genders_strerror($errnum)
        $handle->genders_errormsg()
        $handle->genders_perror($msg)

        $handle->genders_getnumnodes()
        $handle->genders_getnumattrs()
        $handle->genders_getnodename()

        $handle->genders_getnodes([$attr, [$val]])
        $handle->genders_getattr([$node])
        $handle->genders_getattr_all()
        $handle->genders_getattrval($attr, [$node])
        $handle->genders_testattr($attr, [$node])
        $handle->genders_testattrval($attr, $val, [$node])

        $handle->genders_isnode([$node])
        $handle->genders_isattr($attr)
        $handle->genders_isattrval($attr, $val)

        $handle->genders_index_attrvals($attr)

        $handle->genders_query([$query])
        $handle->genders_testquery($query, [$node])

        $handle->genders_parse([$filename]);

DESCRIPTION

       This package provides a perl interface to the genders C API (see libgenders(3)).  The perl
       interface is simliar to the genders C API, with some necessary changes due to the inherent
       differences between C and perl.  Some of the functions from the C API cannot be accessed
       via this perl interface, some new functions were created, the behavior of some functions
       was modified, and the parameters passed into some functions have been changed.  Please
       read the instructions below so to understand how to use the Libgenders package.

   Initialization
       Libgenders->genders_handle_create
           Returns a genders object on success, undef on error.

       $handle->genders_load_data([$filename])
           Opens, reads, and parses the genders file specified by $filename.  If $filename is not
           specified, the default genders file is parsed.  Returns 0 on success, -1 on error.

   Error Messages
       Similarly to the C API, an error code is stored in the genders object after an error has
       occurred.  The following can be used to retrieve the error code and output information
       about the error.

       $handle->genders_errnum()
           Returns the error code most recently set.

       $handle->genders_strerror($errnum)
           Returns a string describing the error code $errnum.

       $handle->genders_errormsg()
           Returns a string describing the most recent error.

       $handle->genders_perror([$msg])
           Outputs $msg and a string describing the most recent error to standard error.  If $msg
           is not specified, only a description of the most recent error will be output to
           standard error.

   Utility Functions
       $handle->genders_getnumnodes()
           Returns the number of nodes listed in the genders file.  Returns -1 on error.

       $handle->genders_getnumattrs()
           Returns the number of attributes listed in the genders file.  Returns -1 on error.

       $handle->genders_getnodename()
           Returns the shortened hostname of the current node.  Returns undef on error.

   Parsing Functions
       $handle->genders_getnodes([$attr, [$val]])
           Returns a reference to a list of nodes that have the specified attribute and value.
           If $val is not specified, only $attr is considered.  If both $attr and $val are not
           specified, all nodes listed in the genders file are returned.  Returns undef on error.

       $handle->genders_getattr([$node])
           Returns a reference to an array that holds references to two lists.  The first list is
           a reference to an array of attributes for the specified node.  The second list is a
           reference to an array of values for the specified node.  If $node is not specified,
           the local node is used.  Returns undef on error.

       $handle->genders_getattr_all()
           Returns a reference to a list of all the attributes listed in the genders file.
           Returns undef on error.

       $handle->genders_getattrval($attr, [$node])
           Returns the value of an attribute listed in a node.  Returns the empty string if the
           attribute has no value.  If $node is not specified, local node is used.  Returns undef
           on error.

       $handle->genders_testattr($attr, [$node])
           Tests if a node has a specified attribute.  If $node is not specified, local node is
           used.  Returns 1 if the node contains the attribute, 0 if not, -1 on error.

       $handle->genders_testattrval($attr, $val, [$node])
           Tests if a node has a specified attribute=value pair.  If $node is not specified,
           local node is used.  Returns 1 if the node contains the attribute=value pair, 0 if
           not, -1 on error.

       $handle->genders_isnode([$node])
           Tests if a node is listed in the genders file.  If $node is not specified, local node
           is used.  Returns 1 if the node is listed, 0 if it is not, -1 on error.

       $handle->genders_isattr($attr)
           Tests if the attribute $attr is listed in the genders file.  Returns 1 if the
           attribute is listed, 0 if it is not, -1 on error.

       $handle->genders_isattrval($attr, $val)
           Tests if the attribute=value pair is listed in the genders file.  Returns 1 if the
           pair is listed, 0 if it is not, -1 on error.

       $handle->genders_index_attrvals($attr)
           Internally adds indexing to decrease search times for genders attribute value
           combinations.  Will specifically aid performance of the genders_getnodes and
           genders_isattrval functions.  Only one attribute can be indexed at a time.  Subsequent
           calls to this function with a different attribute will overwrite earlier indexes.

       $handle->genders_query([$query])
           Returns a reference to a list of nodes specified by a genders query.  A genders query
           is based on the union, intersection, set difference, or complement between genders
           attributes and values.  Union is represented by two pipe symbols ('||'), intersection
           by two ampersand symbols ('&&'), difference by two minus symbols ('--'), and
           complement by a tilde ('~') Operations are performed from left to right.  Parentheses
           may be used to change the order of operations.  For example, the following query would
           retrieve all nodes other than management or login nodes: "all-(mgmt+login)".  If
           $query is not specified, all nodes listed in the genders file are returned. Returns
           undef on error.

       $handle->genders_testquery($query, [$node])
           Tests if a node meets the conditions specified in the query.  If $node is not
           specified, local node is used.  Returns 1 if the node is contained within the query, 0
           if not, -1 on error.

       $handle->genders_parse([$filename])
           Parse a genders file and output parse errors to standard error.  If $filename is not
           specified, the default genders file is parsed.  Returns the number of errors (0 if no
           parse errors were found) on success, -1 on error.

   Error Codes/Constants
       The same error codes and constants listed in /usr/include/genders.h can be accessed
       through the following functions:

        Libgenders::GENDERS_ERR_SUCCESS
        Libgenders::GENDERS_ERR_NULLHANDLE
        Libgenders::GENDERS_ERR_OPEN
        Libgenders::GENDERS_ERR_READ
        Libgenders::GENDERS_ERR_PARSE
        Libgenders::GENDERS_ERR_NOTLOADED
        Libgenders::GENDERS_ERR_ISLOADED
        Libgenders::GENDERS_ERR_OVERFLOW
        Libgenders::GENDERS_ERR_PARAMETERS
        Libgenders::GENDERS_ERR_NULLPTR
        Libgenders::GENDERS_ERR_NOTFOUND
        Libgenders::GENDERS_ERR_OUTMEM
        Libgenders::GENDERS_ERR_SYNTAX
        Libgenders::GENDERS_ERR_QUERYINPUT
        Libgenders::GENDERS_ERR_MAGIC
        Libgenders::GENDERS_ERR_INTERNAL
        Libgenders::GENDERS_ERR_ERRNUMRANGE
        Libgenders::GENDERS_DEFAULT_FILE

AUTHOR

       Albert Chu <chu11@llnl.gov>

SEE ALSO

       libgenders