genders/package/usr/share/man/man3/Libgenders.3pm

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Libgenders 3pm"
.TH Libgenders 3pm "2023-07-25" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Libgenders \- Perl extension for libgenders
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides a perl interface to the genders C \s-1API\s0 (see
\&\fBlibgenders\fR\|(3)).  The perl interface is simliar to the genders C \s-1API,\s0
with some necessary changes due to the inherent differences between C
and perl.  Some of the functions from the C \s-1API\s0 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.
.SS "Initialization"
.IX Subsection "Initialization"
.IP "\fBLibgenders\->genders_handle_create\fR" 4
.IX Item "Libgenders->genders_handle_create"
Returns a genders object on success, undef on error.
.IP "\fB\f(CB$handle\fB\->genders_load_data([$filename])\fR" 4
.IX Item "$handle->genders_load_data([$filename])"
Opens, reads, and parses the genders file specified by \f(CW$filename\fR.  If
\&\f(CW$filename\fR is not specified, the default genders file is parsed.
Returns 0 on success, \-1 on error.
.SS "Error Messages"
.IX Subsection "Error Messages"
Similarly to the C \s-1API,\s0 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.
.IP "\fB\f(CB$handle\fB\->\fBgenders_errnum()\fB\fR" 4
.IX Item "$handle->genders_errnum()"
Returns the error code most recently set.
.IP "\fB\f(CB$handle\fB\->genders_strerror($errnum)\fR" 4
.IX Item "$handle->genders_strerror($errnum)"
Returns a string describing the error code \f(CW$errnum\fR.
.IP "\fB\f(CB$handle\fB\->\fBgenders_errormsg()\fB\fR" 4
.IX Item "$handle->genders_errormsg()"
Returns a string describing the most recent error.
.IP "\fB\f(CB$handle\fB\->genders_perror([$msg])\fR" 4
.IX Item "$handle->genders_perror([$msg])"
Outputs \f(CW$msg\fR and a string describing the most recent error to standard
error.  If \f(CW$msg\fR is not specified, only a description of the most
recent error will be output to standard error.
.SS "Utility Functions"
.IX Subsection "Utility Functions"
.IP "\fB\f(CB$handle\fB\->\fBgenders_getnumnodes()\fB\fR" 4
.IX Item "$handle->genders_getnumnodes()"
Returns the number of nodes listed in the genders file.  Returns \-1 on
error.
.IP "\fB\f(CB$handle\fB\->\fBgenders_getnumattrs()\fB\fR" 4
.IX Item "$handle->genders_getnumattrs()"
Returns the number of attributes listed in the genders file.  Returns
\&\-1 on error.
.IP "\fB\f(CB$handle\fB\->\fBgenders_getnodename()\fB\fR" 4
.IX Item "$handle->genders_getnodename()"
Returns the shortened hostname of the current node.  Returns undef on
error.
.SS "Parsing Functions"
.IX Subsection "Parsing Functions"
.IP "\fB\f(CB$handle\fB\->genders_getnodes([$attr, [$val]])\fR" 4
.IX Item "$handle->genders_getnodes([$attr, [$val]])"
Returns a reference to a list of nodes that have the specified
attribute and value.  If \f(CW$val\fR is not specified, only \f(CW$attr\fR is
considered.  If both \f(CW$attr\fR and \f(CW$val\fR are not specified, all nodes
listed in the genders file are returned.  Returns undef on error.
.IP "\fB\f(CB$handle\fB\->genders_getattr([$node])\fR" 4
.IX Item "$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 \f(CW$node\fR is not specified, the local node is
used.  Returns undef on error.
.IP "\fB\f(CB$handle\fB\->\fBgenders_getattr_all()\fB\fR" 4
.IX Item "$handle->genders_getattr_all()"
Returns a reference to a list of all the attributes listed in the
genders file.  Returns undef on error.
.IP "\fB\f(CB$handle\fB\->genders_getattrval($attr, [$node])\fR" 4
.IX Item "$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 \f(CW$node\fR is not specified,
local node is used.  Returns undef on error.
.IP "\fB\f(CB$handle\fB\->genders_testattr($attr, [$node])\fR" 4
.IX Item "$handle->genders_testattr($attr, [$node])"
Tests if a node has a specified attribute.  If \f(CW$node\fR is not specified,
local node is used.  Returns 1 if the node contains the attribute, 0
if not, \-1 on error.
.IP "\fB\f(CB$handle\fB\->genders_testattrval($attr, \f(CB$val\fB, [$node])\fR" 4
.IX Item "$handle->genders_testattrval($attr, $val, [$node])"
Tests if a node has a specified attribute=value pair.  If \f(CW$node\fR is not
specified, local node is used.  Returns 1 if the node contains the
attribute=value pair, 0 if not, \-1 on error.
.IP "\fB\f(CB$handle\fB\->genders_isnode([$node])\fR" 4
.IX Item "$handle->genders_isnode([$node])"
Tests if a node is listed in the genders file.  If \f(CW$node\fR is not
specified, local node is used.  Returns 1 if the node is listed, 0 if
it is not, \-1 on error.
.IP "\fB\f(CB$handle\fB\->genders_isattr($attr)\fR" 4
.IX Item "$handle->genders_isattr($attr)"
Tests if the attribute \f(CW$attr\fR is listed in the genders file.  Returns 1
if the attribute is listed, 0 if it is not, \-1 on error.
.IP "\fB\f(CB$handle\fB\->genders_isattrval($attr, \f(CB$val\fB)\fR" 4
.IX Item "$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.
.IP "\fB\f(CB$handle\fB\->genders_index_attrvals($attr)\fR" 4
.IX Item "$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.
.IP "\fB\f(CB$handle\fB\->genders_query([$query])\fR" 4
.IX Item "$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: \*(L"~(mgmt||login)\*(R".  If \f(CW$query\fR is not
specified, all nodes listed in the genders file are returned. Returns
undef on error.
.IP "\fB\f(CB$handle\fB\->genders_testquery($query, [$node])\fR" 4
.IX Item "$handle->genders_testquery($query, [$node])"
Tests if a node meets the conditions specified in the query.  If \f(CW$node\fR
is not specified, local node is used.  Returns 1 if the node is
contained within the query, 0 if not, \-1 on error.
.IP "\fB\f(CB$handle\fB\->genders_parse([$filename])\fR" 4
.IX Item "$handle->genders_parse([$filename])"
Parse a genders file and output parse errors to standard error.  If
\&\f(CW$filename\fR 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.
.SS "Error Codes/Constants"
.IX Subsection "Error Codes/Constants"
The same error codes and constants listed in /usr/include/genders.h
can be accessed through the following functions:
.PP
.Vb 10
\& 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
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Albert Chu <chu11@llnl.gov>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
libgenders