1Libgenders(3) User Contributed Perl Documentation Libgenders(3)
2
6 Libgenders - Perl extension for libgenders
7
9 use Libgenders;
10 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 $handle = Libgenders->genders_handle_create();
31 $handle->genders_load_data([$filename]);
32 $handle->genders_errnum()
34 $handle->genders_strerror($errnum)
35 $handle->genders_errormsg()
36 $handle->genders_perror($msg)
37 $handle->genders_getnumnodes()
39 $handle->genders_getnumattrs()
40 $handle->genders_getnodename()
41 $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 $handle->genders_isnode([$node])
50 $handle->genders_isattr($attr)
51 $handle->genders_isattrval($attr, $val)
52 $handle->genders_index_attrvals($attr)
54 $handle->genders_query([$query])
56 $handle->genders_testquery($query, [$node])
57 $handle->genders_parse([$filename]);
59
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 Initialization
71 Libgenders->genders_handle_create
72 Returns a genders object on success, undef on error.
73 $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 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 $handle->genders_errnum()
85 Returns the error code most recently set.
86 $handle->genders_strerror($errnum)
88 Returns a string describing the error code $errnum.
89 $handle->genders_errormsg()
91 Returns a string describing the most recent error.
92 $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 Utility Functions
99 $handle->genders_getnumnodes()
100 Returns the number of nodes listed in the genders file. Returns -1
101 on error.
102 $handle->genders_getnumattrs()
104 Returns the number of attributes listed in the genders file.
105 Returns -1 on error.
106 $handle->genders_getnodename()
108 Returns the shortened hostname of the current node. Returns undef
109 on error.
110 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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 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 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
212 Albert Chu <chu11@llnl.gov>
213
215 libgenders
216perl v5.32.1 2021-01-26 Libgenders(3)