1Libgenders(3)         User Contributed Perl Documentation        Libgenders(3)
2
3
4

NAME

6       Libgenders - Perl extension for libgenders
7

SYNOPSIS

9        use Libgenders;
10
11        Libgenders::GENDERS_ERR_SUCCESS
12        Libgenders::GENDERS_ERR_NULLHANDLE
13        Libgenders::GENDERS_ERR_OPEN
14        Libgenders::GENDERS_ERR_READ
15        Libgenders::GENDERS_ERR_PARSE
16        Libgenders::GENDERS_ERR_NOTLOADED
17        Libgenders::GENDERS_ERR_ISLOADED
18        Libgenders::GENDERS_ERR_OVERFLOW
19        Libgenders::GENDERS_ERR_PARAMETERS
20        Libgenders::GENDERS_ERR_NULLPTR
21        Libgenders::GENDERS_ERR_NOTFOUND
22        Libgenders::GENDERS_ERR_SYNTAX
23        Libgenders::GENDERS_ERR_QUERYINPUT
24        Libgenders::GENDERS_ERR_OUTMEM
25        Libgenders::GENDERS_ERR_MAGIC
26        Libgenders::GENDERS_ERR_INTERNAL
27        Libgenders::GENDERS_ERR_ERRNUMRANGE
28        Libgenders::GENDERS_DEFAULT_FILE
29
30        $handle = Libgenders->genders_handle_create();
31        $handle->genders_load_data([$filename]);
32
33        $handle->genders_errnum()
34        $handle->genders_strerror($errnum)
35        $handle->genders_errormsg()
36        $handle->genders_perror($msg)
37
38        $handle->genders_getnumnodes()
39        $handle->genders_getnumattrs()
40        $handle->genders_getnodename()
41
42        $handle->genders_getnodes([$attr, [$val]])
43        $handle->genders_getattr([$node])
44        $handle->genders_getattr_all()
45        $handle->genders_getattrval($attr, [$node])
46        $handle->genders_testattr($attr, [$node])
47        $handle->genders_testattrval($attr, $val, [$node])
48
49        $handle->genders_isnode([$node])
50        $handle->genders_isattr($attr)
51        $handle->genders_isattrval($attr, $val)
52
53        $handle->genders_index_attrvals($attr)
54
55        $handle->genders_query([$query])
56        $handle->genders_testquery($query, [$node])
57
58        $handle->genders_parse([$filename]);
59

DESCRIPTION

61       This package provides a perl interface to the genders C API (see
62       libgenders(3)).  The perl interface is simliar to the genders C API,
63       with some necessary changes due to the inherent differences between C
64       and perl.  Some of the functions from the C API cannot be accessed via
65       this perl interface, some new functions were created, the behavior of
66       some functions was modified, and the parameters passed into some
67       functions have been changed.  Please read the instructions below so to
68       understand how to use the Libgenders package.
69
70   Initialization
71       Libgenders->genders_handle_create
72           Returns a genders object on success, undef on error.
73
74       $handle->genders_load_data([$filename])
75           Opens, reads, and parses the genders file specified by $filename.
76           If $filename is not specified, the default genders file is parsed.
77           Returns 0 on success, -1 on error.
78
79   Error Messages
80       Similarly to the C API, an error code is stored in the genders object
81       after an error has occurred.  The following can be used to retrieve the
82       error code and output information about the error.
83
84       $handle->genders_errnum()
85           Returns the error code most recently set.
86
87       $handle->genders_strerror($errnum)
88           Returns a string describing the error code $errnum.
89
90       $handle->genders_errormsg()
91           Returns a string describing the most recent error.
92
93       $handle->genders_perror([$msg])
94           Outputs $msg and a string describing the most recent error to
95           standard error.  If $msg is not specified, only a description of
96           the most recent error will be output to standard error.
97
98   Utility Functions
99       $handle->genders_getnumnodes()
100           Returns the number of nodes listed in the genders file.  Returns -1
101           on error.
102
103       $handle->genders_getnumattrs()
104           Returns the number of attributes listed in the genders file.
105           Returns -1 on error.
106
107       $handle->genders_getnodename()
108           Returns the shortened hostname of the current node.  Returns undef
109           on error.
110
111   Parsing Functions
112       $handle->genders_getnodes([$attr, [$val]])
113           Returns a reference to a list of nodes that have the specified
114           attribute and value.  If $val is not specified, only $attr is
115           considered.  If both $attr and $val are not specified, all nodes
116           listed in the genders file are returned.  Returns undef on error.
117
118       $handle->genders_getattr([$node])
119           Returns a reference to an array that holds references to two lists.
120           The first list is a reference to an array of attributes for the
121           specified node.  The second list is a reference to an array of
122           values for the specified node.  If $node is not specified, the
123           local node is used.  Returns undef on error.
124
125       $handle->genders_getattr_all()
126           Returns a reference to a list of all the attributes listed in the
127           genders file.  Returns undef on error.
128
129       $handle->genders_getattrval($attr, [$node])
130           Returns the value of an attribute listed in a node.  Returns the
131           empty string if the attribute has no value.  If $node is not
132           specified, local node is used.  Returns undef on error.
133
134       $handle->genders_testattr($attr, [$node])
135           Tests if a node has a specified attribute.  If $node is not
136           specified, local node is used.  Returns 1 if the node contains the
137           attribute, 0 if not, -1 on error.
138
139       $handle->genders_testattrval($attr, $val, [$node])
140           Tests if a node has a specified attribute=value pair.  If $node is
141           not specified, local node is used.  Returns 1 if the node contains
142           the attribute=value pair, 0 if not, -1 on error.
143
144       $handle->genders_isnode([$node])
145           Tests if a node is listed in the genders file.  If $node is not
146           specified, local node is used.  Returns 1 if the node is listed, 0
147           if it is not, -1 on error.
148
149       $handle->genders_isattr($attr)
150           Tests if the attribute $attr is listed in the genders file.
151           Returns 1 if the attribute is listed, 0 if it is not, -1 on error.
152
153       $handle->genders_isattrval($attr, $val)
154           Tests if the attribute=value pair is listed in the genders file.
155           Returns 1 if the pair is listed, 0 if it is not, -1 on error.
156
157       $handle->genders_index_attrvals($attr)
158           Internally adds indexing to decrease search times for genders
159           attribute value combinations.  Will specifically aid performance of
160           the genders_getnodes and genders_isattrval functions.  Only one
161           attribute can be indexed at a time.  Subsequent calls to this
162           function with a different attribute will overwrite earlier indexes.
163
164       $handle->genders_query([$query])
165           Returns a reference to a list of nodes specified by a genders
166           query.  A genders query is based on the union, intersection, set
167           difference, or complement between genders attributes and values.
168           Union is represented by two pipe symbols ('||'), intersection by
169           two ampersand symbols ('&&'), difference by two minus symbols
170           ('--'), and complement by a tilde ('~') Operations are performed
171           from left to right.  Parentheses may be used to change the order of
172           operations.  For example, the following query would retrieve all
173           nodes other than management or login nodes: "~(mgmt||login)".  If
174           $query is not specified, all nodes listed in the genders file are
175           returned. Returns undef on error.
176
177       $handle->genders_testquery($query, [$node])
178           Tests if a node meets the conditions specified in the query.  If
179           $node is not specified, local node is used.  Returns 1 if the node
180           is contained within the query, 0 if not, -1 on error.
181
182       $handle->genders_parse([$filename])
183           Parse a genders file and output parse errors to standard error.  If
184           $filename is not specified, the default genders file is parsed.
185           Returns the number of errors (0 if no parse errors were found) on
186           success, -1 on error.
187
188   Error Codes/Constants
189       The same error codes and constants listed in /usr/include/genders.h can
190       be accessed through the following functions:
191
192        Libgenders::GENDERS_ERR_SUCCESS
193        Libgenders::GENDERS_ERR_NULLHANDLE
194        Libgenders::GENDERS_ERR_OPEN
195        Libgenders::GENDERS_ERR_READ
196        Libgenders::GENDERS_ERR_PARSE
197        Libgenders::GENDERS_ERR_NOTLOADED
198        Libgenders::GENDERS_ERR_ISLOADED
199        Libgenders::GENDERS_ERR_OVERFLOW
200        Libgenders::GENDERS_ERR_PARAMETERS
201        Libgenders::GENDERS_ERR_NULLPTR
202        Libgenders::GENDERS_ERR_NOTFOUND
203        Libgenders::GENDERS_ERR_OUTMEM
204        Libgenders::GENDERS_ERR_SYNTAX
205        Libgenders::GENDERS_ERR_QUERYINPUT
206        Libgenders::GENDERS_ERR_MAGIC
207        Libgenders::GENDERS_ERR_INTERNAL
208        Libgenders::GENDERS_ERR_ERRNUMRANGE
209        Libgenders::GENDERS_DEFAULT_FILE
210

AUTHOR

212       Albert Chu <chu11@llnl.gov>
213

SEE ALSO

215       libgenders
216
217
218
219perl v5.32.0                      2020-07-27                     Libgenders(3)
Impressum