Libgenders - Perl extension for libgenders

 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_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_parse([$filename]);

This package provides an OO 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 has been changed. Please read the instructions below so to understand how to use the Libgenders package.

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 CW$filename. If CW$filename is not specified, the default genders file is parsed. Returns 0 on success, -1 on error.

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->BIgenders_errnum()

Returns the error code most recently set.

$handle->genders_strerror($errnum)

Returns a string describing the error code CW$errnum.

$handle->BIgenders_errormsg()

Returns a string describing the most recent error.

$handle->genders_perror([$msg])

Outputs CW$msg and a string describing the most recent error to standard error. If CW$msg is not specified, only a description of the most recent error will be output to standard error.

$handle->BIgenders_getnumnodes()

Returns the number of nodes listed in the genders file. Returns -1 on error.

$handle->BIgenders_getnumattrs()

Returns the number of attributes listed in the genders file. Returns -1 on error.

$handle->BIgenders_getnodename()

Returns the shortened hostname of the current node. Returns undef on error.

$handle->genders_getnodes([$attr, [$val]])

Returns a reference to a list of nodes that have the specified attribute and value. If CW$val is not specified, only CW$attr is considered. If both CW$attr and CW$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 CW$node is not specified, the local node is used. Returns undef on error.

$handle->BIgenders_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 CW$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 CW$node is not specified, local node is used. Returns 1 if the node contains the attribute, 0 if not, -1 on error. Tests if a node has a specified attribute=value pair. If CW$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 CW$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 CW$attr is listed in the genders file. Returns 1 if the attribute is listed, 0 if it is not, -1 on error. 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_parse([$filename])

Parse a genders file and output parse errors to standard error. If CW$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.

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_MAGIC
 Libgenders::GENDERS_ERR_INTERNAL
 Libgenders::GENDERS_ERR_ERRNUMRANGE
 Libgenders::GENDERS_DEFAULT_FILE

Albert Chu <chu11@llnl.gov>

libgenders