| blob | 85007f313bc1a817615f31506675eaa9391775ec |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LGRP 3PERL "April 9, 2016"
7 .SH NAME
8 Lgrp \- Perl interface to Solaris liblgrp library
9 .SH SYNOPSIS
10 .LP
11 .nf
12 use Sun::Solaris::Lgrp qw(:ALL);
14 # initialize lgroup interface
15 my $cookie = lgrp_init(LGRP_VIEW_OS | LGRP_VIEW_CALLER);
16 my $l = Sun::Solaris::Lgrp->new(LGRP_VIEW_OS |
17 LGRP_VIEW_CALLER);
19 my $version = lgrp_version(LGRP_VER_CURRENT | LGRP_VER_NONE);
20 $version = $l->version(LGRP_VER_CURRENT | LGRP_VER_NONE);
22 $home = lgrp_home(P_PID, P_MYID);
23 $home = l->home(P_PID, P_MYID);
25 lgrp_affinity_set(P_PID, $\fIpid\fR, $\fIlgrp\fR,
26 LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE);
27 $l->affinity_set(P_PID, $\fIpid\fR, $\fIlgrp\fR,
28 LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE);
30 my $affinity = lgrp_affinity_get(P_PID, $\fIpid\fR, $\fIlgrp\fR);
31 $affinity = $l->affinity_get(P_PID, $\fIpid\fR, $\fIlgrp\fR);
33 my $nlgrps = lgrp_nlgrps($\fIcookie\fR);
34 $nlgrps = $l->nlgrps();
36 my $root = lgrp_root($\fIcookie\fR);
37 $root = l->root();
39 $latency = lgrp_latency($\fIlgrp1\fR, $\fIlgrp2\fR);
40 $latency = $l->latency($\fIlgrp1\fR, $\fIlgrp2\fR);
42 my @children = lgrp_children($\fIcookie\fR, $\fIlgrp\fR);
43 @children = l->children($lgrp);
45 my @parents = lgrp_parents($\fIcookie\fR, $\fIlgrp\fR);
46 @parents = l->parents($\fIlgrp\fR);
48 my @lgrps = lgrp_lgrps($\fIcookie\fR);
49 @lgrps = l->lgrps();
51 @lgrps = lgrp_lgrps($\fIcookie\fR, $\fIlgrp\fR);
52 @lgrps = l->lgrps($\fIlgrp\fR);
54 my @leaves = lgrp_leaves($\fIcookie\fR);
55 @leaves = l->leaves();
57 my $is_leaf = lgrp_isleaf($\fIcookie\fR, $\fIlgrp\fR);
58 $is_leaf = $l->is_leaf($\fIlgrp\fR);
60 my @cpus = lgrp_cpus($\fIcookie\fR, $\fIlgrp\fR,
61 LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
62 @cpus = l->cpus($\fIlgrp\fR, LGRP_CONTENT_HIERARCHY |
63 LGRP_CONTENT_DIRECT);
65 my $memsize = lgrp_mem_size($\fIcookie\fR, $\fIlgrp\fR,
66 LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE,
67 LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
68 $memsize = l->mem_size($\fIlgrp\fR,
69 LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE,
70 LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
72 my $is_stale = lgrp_cookie_stale($\fIcookie\fR);
73 $stale = l->stale();
75 lgrp_fini($\fIcookie\fR);
77 # The following is available for API version greater than 1:
78 my @lgrps = lgrp_resources($\fIcookie\fR, $\fIlgrp\fR, LGRP_RSRC_CPU);
80 # Get latencies from cookie
81 $latency = lgrp_latency_cookie($\fIcookie\fR, $\fIfrom\fR, $\fIto\fR);
82 .fi
84 .SH DESCRIPTION
85 .LP
86 This module provides access to the \fBliblgrp\fR(3LIB) library and to various
87 constants and functions defined in <\fBsys/lgrp_sys.h\fR>. It provides both the
88 procedural and object interface to the library. The procedural interface
89 requires (in most cases) passing around a transparent cookie. The object
90 interface hides all the cookie manipulations from the user.
91 .sp
92 .LP
93 Functions returning a scalar value indicate an error by returning \fBundef\fR.
94 The caller can examine the \fB$!\fR variable to get the error value.
95 .sp
96 .LP
97 Functions returning a list value return the number of elements in the list when
98 called in scalar context. In the event of error, the empty list is returned in
99 the array context and \fBundef\fR is returned in the scalar context.
100 .SS "Constants"
101 .LP
102 The constants are exported with \fB:CONSTANTS\fR or \fB:ALL\fR tags:
103 .sp
104 .in +2
105 .nf
106 use Sun::Solaris::Lgrp ':ALL';
107 .fi
108 .in -2
110 .sp
111 .LP
112 or
113 .sp
114 .in +2
115 .nf
116 use Sun::Solaris::Lgrp ':CONSTANTS';
117 .fi
118 .in -2
120 .sp
121 .LP
122 The following constants are available for use in Perl programs:
123 .br
124 .in +2
125 \fBLGRP_NONE\fR
126 .in -2
127 .br
128 .in +2
129 \fBLGRP_VER_CURRENT\fR
130 .in -2
131 .br
132 .in +2
133 \fBLGRP_VER_NONE\fR
134 .in -2
135 .br
136 .in +2
137 \fBLGRP_VIEW_CALLER\fR
138 .in -2
139 .br
140 .in +2
141 \fBLGRP_VIEW_OS\fR
142 .in -2
143 .br
144 .in +2
145 \fBLGRP_AFF_NONE\fR
146 .in -2
147 .br
148 .in +2
149 \fBLGRP_AFF_STRONG\fR
150 .in -2
151 .br
152 .in +2
153 \fBLGRP_AFF_WEAK\fR
154 .in -2
155 .br
156 .in +2
157 \fBLGRP_CONTENT_DIRECT\fR
158 .in -2
159 .br
160 .in +2
161 \fBLGRP_CONTENT_HIERARCHY\fR
162 .in -2
163 .br
164 .in +2
165 \fBLGRP_MEM_SZ_FREE\fR
166 .in -2
167 .br
168 .in +2
169 \fBLGRP_MEM_SZ_FREE\fR
170 .in -2
171 .br
172 .in +2
173 \fBLGRP_RSRC_CPU\fR (1)
174 .in -2
175 .br
176 .in +2
177 \fBLGRP_RSRC_MEM\fR (1)
178 .in -2
179 .br
180 .in +2
181 \fBLGRP_CONTENT_ALL\fR (1)
182 .in -2
183 .br
184 .in +2
185 \fBLGRP_LAT_CPU_TO_MEM\fR (1)
186 .in -2
187 .br
188 .in +2
189 \fBP_PID\fR
190 .in -2
191 .br
192 .in +2
193 \fBP_LWPID\fR
194 .in -2
195 .br
196 .in +2
197 \fBP_MYID\fR
198 .in -2
199 .sp
200 .LP
201 (1) Available for versions of the \fBliblgrp\fR(3LIB) API greater than 1.
202 .SS "Functions"
203 .LP
204 A detailed description of each function follows. Since this module is intended
205 to provide a Perl interface to the functions in \fBliblgrp\fR(3LIB), a very
206 short description is given for the corresponding functions in this module and a
207 reference is given to the complete description in the \fBliblgrp\fR manual
208 pages. Any differences or additional functionality in the Perl module are
209 highlighted and fully documented here.
210 .sp
211 .ne 2
212 .na
213 \fB\fBlgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS])\fR\fR
214 .ad
215 .sp .6
216 .RS 4n
217 This function initializes the lgroup interface and takes a snapshot of the
218 lgroup hierarchy with the given view. Given the view, \fBlgrp_init()\fR returns
219 a cookie representing this snapshot of the lgroup hierarchy. This cookie should
220 be used with other routines in the lgroup interface needing the lgroup
221 hierarchy. The \fBlgrp_fini()\fR function should be called with the cookie when
222 it is no longer needed. Unlike \fBlgrp_init\fR(3LGRP), \fBLGRP_VIEW_OS\fR is
223 assumed as the default if no view is provided.
224 .sp
225 Upon successful completion, \fBlgrp_init()\fR returns a cookie. Otherwise it
226 returns \fBundef\fR and sets \fB$!\fR to indicate the error.
227 .sp
228 See \fBlgrp_init\fR(3LGRP) for more information.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB\fBlgrp_fini\fR($\fIcookie\fR)\fR
235 .ad
236 .sp .6
237 .RS 4n
238 This function takes a cookie, frees the snapshot of the lgroup hierarchy
239 created by \fBlgrp_init()\fR, and cleans up anything else set up by
240 \fBlgrp_init()\fR. After this function is called, the cookie returned by the
241 lgroup interface might no longer be valid and should not be used.
242 .sp
243 Upon successful completion, 1 is returned. Otherwise, \fBundef\fR is returned
244 and \fB$!\fR is set to indicate the error.
245 .sp
246 See \fBlgrp_fini\fR(3LGRP) for more information.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fBlgrp_view\fR($\fIcookie\fR)\fR
253 .ad
254 .sp .6
255 .RS 4n
256 This function takes a cookie representing the snapshot of the lgroup hierarchy
257 and returns the snapshot's view of the lgroup hierarchy.
258 .sp
259 If the given view is \fBLGRP_VIEW_CALLER\fR, the snapshot contains only the
260 resources that are available to the caller (such as those with respect to
261 processor sets). When the view is \fBLGRP_VIEW_OS\fR, the snapshot contains
262 what is available to the operating system.
263 .sp
264 Upon successful completion, the function returns the view for the snapshot of
265 the lgroup hierarchy represented by the given cookie. Otherwise, \fBundef\fR
266 is returned and \fB$!\fR is set to indicate the error.
267 .sp
268 See \fBlgrp_view\fR(3LGRP) for more information.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBlgrp_home\fR($\fIidtype\fR, $\fIid\fR)\fR
275 .ad
276 .sp .6
277 .RS 4n
278 This function returns the home lgroup for the given process or thread. The
279 $\fIidtype\fR argument should be \fBP_PID\fR to specify a process and the
280 $\fIid\fR argument should be its process ID. Otherwise, the $\fIidtype\fR
281 argument should be \fBP_LWPID\fR to specify a thread and the $\fIid\fR argument
282 should be its LWP ID. The value \fBP_MYID\fR can be used for the $\fIid\fR
283 argument to specify the current process or thread.
284 .sp
285 Upon successful completion, \fBlgrp_home()\fR returns the ID of the home lgroup
286 of the specified process or thread. Otherwise, \fBundef\fR is returned and
287 \fB$!\fR is set to indicate the error.
288 .sp
289 See \fBlgrp_home\fR(3LGRP) for more information.
290 .RE
292 .sp
293 .ne 2
294 .na
295 \fB\fBlgrp_cookie_stale\fR($\fIcookie\fR)\fR
296 .ad
297 .sp .6
298 .RS 4n
299 Upon successful completion, this function returns whether the cookie is stale.
300 Otherwise, it returns \fBundef\fR and sets \fB$!\fR to indicate the error.
301 .sp
302 The \fBlgrp_cookie_stale()\fR function will fail with \fBEINVAL\fR if the
303 cookie is not valid.
304 .sp
305 See \fBlgrp_cookie_stale\fR(3LGRP) for more information.
306 .RE
308 .sp
309 .ne 2
310 .na
311 \fB\fBlgrp_cpus\fR($\fIcookie\fR, $\fIlgrp\fR, $\fIcontext\fR)\fR
312 .ad
313 .sp .6
314 .RS 4n
315 This function takes a cookie representing a snapshot of the lgroup hierarchy
316 and returns the list of CPUs in the lgroup specified by $\fIlgrp\fR. The
317 $\fIcontext\fR argument should be set to one of the following values to specify
318 whether the direct contents or everything in this lgroup including its children
319 should be returned:
320 .sp
321 .ne 2
322 .na
323 \fB\fBLGRP_CONTENT_HIERARCHY\fR\fR
324 .ad
325 .RS 26n
326 everything within this hierarchy
327 .RE
329 .sp
330 .ne 2
331 .na
332 \fB\fBLGRP_CONTENT_DIRECT\fR\fR
333 .ad
334 .RS 26n
335 directly contained in lgroup
336 .RE
338 When called in scalar context, \fBlgrp_cpus()\fR function returns the number of
339 CPUs contained in the specified lgroup.
340 .sp
341 In the event of error, \fBundef\fR is returned in scalar context and \fB$!\fR
342 is set to indicate the error. In list context, the empty list is returned and
343 \fB$!\fR is set.
344 .sp
345 See \fBlgrp_cpus\fR(3LGRP) for more information.
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fBlgrp_children\fR($\fIcookie\fR, $\fIlgrp\fR)\fR
352 .ad
353 .sp .6
354 .RS 4n
355 This function takes a cookie representing a snapshot of the lgroup hierarchy
356 and returns the list of lgroups that are children of the specified lgroup.
357 .sp
358 When called in scalar context, \fBlgrp_children()\fR returns the number of
359 children lgroups for the specified lgroup.
360 .sp
361 In the event of error, \fBundef\fR or empty list is returned and \fB$!\fR is
362 set to indicate the error.
363 .sp
364 See \fBlgrp_children\fR(3LGRP) for more information.
365 .RE
367 .sp
368 .ne 2
369 .na
370 \fB\fBlgrp_parents\fR($\fIcookie\fR, $\fIlgrp\fR)\fR
371 .ad
372 .sp .6
373 .RS 4n
374 This function takes a cookie representing a snapshot of the lgroup hierarchy
375 and returns the list of parents of the specified lgroup.
376 .sp
377 When called in scalar context, \fBlgrp_parents()\fR returns the number of
378 parent lgroups for the specified lgroup.
379 .sp
380 In the event of error, \fBundef\fR or an empty list is returned and \fB$!\fR is
381 set to indicate the error.
382 .sp
383 See \fBlgrp_parents\fR(3LGRP) for more information.
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fBlgrp_nlgrps\fR($\fIcookie\fR)\fR
390 .ad
391 .sp .6
392 .RS 4n
393 This function takes a cookie representing a snapshot of the lgroup hierarchy.
394 It returns the number of lgroups in the hierarchy, where the number is always
395 at least one.
396 .sp
397 In the event of error, \fBundef\fR is returned and \fB$!\fR is set to
398 \fBEINVAL\fR, indicating that the cookie is not valid.
399 .sp
400 See \fBlgrp_nlgrps\fR(3LGRP) for more information.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fBlgrp_root\fR($\fIcookie\fR)\fR
407 .ad
408 .sp .6
409 .RS 4n
410 This function returns the root lgroup ID.
411 .sp
412 In the event of error, \fBundef\fR is returned and \fB$!\fR is set to
413 \fBEINVAL\fR, indicatng that the cookie is not valid.
414 .sp
415 See \fBlgrp_root\fR(3LGRP) for more information.
416 .RE
418 .sp
419 .ne 2
420 .na
421 \fB\fBlgrp_mem_size\fR($\fIcookie\fR, $\fIlgrp\fR, $\fItype\fR,
422 $\fIcontent\fR)\fR
423 .ad
424 .sp .6
425 .RS 4n
426 This function takes a cookie representing a snapshot of the lgroup hierarchy.
427 The function returns the memory size of the given lgroup in bytes. The
428 $\fItype\fR argument should be set to one of the following values:
429 .sp
430 .ne 2
431 .na
432 \fB\fBLGRP_MEM_SZ_FREE\fR\fR
433 .ad
434 .RS 25n
435 free memory
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fB\fBLGRP_MEM_SZ_INSTALLED\fR\fR
442 .ad
443 .RS 25n
444 installed memory
445 .RE
447 The $\fIcontent\fR argument should be set to one of the following values to
448 specify whether the direct contents or everything in this lgroup including its
449 children should be returned:
450 .sp
451 .ne 2
452 .na
453 \fB\fBLGRP_CONTENT_HIERARCHY\fR\fR
454 .ad
455 .RS 26n
456 Return everything within this hierarchy.
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fBLGRP_CONTENT_DIRECT\fR\fR
463 .ad
464 .RS 26n
465 Return that which is directly contained in this lgroup.
466 .RE
468 The total sizes include all the memory in the lgroup including its children,
469 while the others reflect only the memory contained directly in the given
470 lgroup.
471 .sp
472 Upon successful completion, the size in bytes is returned. Otherwise,
473 \fBundef\fR is returned and \fB$!\fR is set to indicate the error.
474 .sp
475 See \fBlgrp_mem_size\fR(3LGRP) for more information.
476 .RE
478 .sp
479 .ne 2
480 .na
481 \fB\fBlgrp_version\fR([$\fIversion\fR])\fR
482 .ad
483 .sp .6
484 .RS 4n
485 This function takes an interface version number, $\fIversion\fR, as an argument
486 and returns an lgroup interface version. The $\fIversion\fR argument should be
487 the value of \fBLGRP_VER_CURRENT\fR or \fBLGRP_VER_NONE\fR to find out the
488 current lgroup interface version on the running system.
489 .sp
490 If $\fIversion\fR is still supported by the implementation, then
491 \fBlgrp_version()\fR returns the requested version. If \fBLGRP_VER_NONE\fR is
492 returned, the implementation cannot support the requested version.
493 .sp
494 If $\fIversion\fR is \fBLGRP_VER_NONE\fR, \fBlgrp_version()\fR returns the
495 current version of the library.
496 .sp
497 The following example tests whether the version of the interface used by the
498 caller is supported:
499 .sp
500 .in +2
501 .nf
502 lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or
503 die("Built with unsupported lgroup interface");
504 .fi
505 .in -2
507 See \fBlgrp_version\fR(3LGRP) for more information.
508 .RE
510 .sp
511 .ne 2
512 .na
513 \fB\fBlgrp_affinity_set\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR,
514 $\fIaffinity\fR)\fR
515 .ad
516 .sp .6
517 .RS 4n
518 This function sets the affinity that the LWP or set of LWPs specified by
519 $\fIidtype\fR and $\fIid\fR have for the given lgroup. The lgroup affinity can
520 be set to \fBLGRP_AFF_STRONG\fR, \fBLGRP_AFF_WEAK\fR, or \fBLGRP_AFF_NONE\fR.
521 .sp
522 If the $\fIidtype\fR is \fBP_PID\fR, the affinity is retrieved for one of the
523 LWPs in the process or set for all the LWPs of the process with process ID
524 (PID) $\fIid\fR. The affinity is retrieved or set for the LWP of the current
525 process with LWP ID $\fIid\fR if $\fIidtype\fR is \fBP_LWPID\fR. If $\fIid\fR
526 is \fBP_MYID\fR, then the current LWP or process is specified.
527 .sp
528 There are different levels of affinity that can be specified by a thread for a
529 particular lgroup. The levels of affinity are the following from strongest to
530 weakest:
531 .sp
532 .ne 2
533 .na
534 \fB\fBLGRP_AFF_STRONG\fR\fR
535 .ad
536 .RS 19n
537 strong affinity
538 .RE
540 .sp
541 .ne 2
542 .na
543 \fB\fBLGRP_AFF_WEAK\fR\fR
544 .ad
545 .RS 19n
546 weak affinity
547 .RE
549 .sp
550 .ne 2
551 .na
552 \fB\fBLGRP_AFF_NONE\fR\fR
553 .ad
554 .RS 19n
555 no affinity
556 .RE
558 Upon successful completion, \fBlgrp_affinity_set()\fR returns 1. Otherwise, it
559 returns \fBundef\fR and set \fB$!\fR to indicate the error.
560 .sp
561 See \fBlgrp_affinity_set\fR(3LGRP) for more information.
562 .RE
564 .sp
565 .ne 2
566 .na
567 \fB\fBlgrp_affinity_get\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR)\fR
568 .ad
569 .sp .6
570 .RS 4n
571 This function returns the affinity that the LWP has to a given lgroup.
572 .sp
573 See \fBlgrp_affinity_get\fR(3LGRP) for more information.
574 .RE
576 .sp
577 .ne 2
578 .na
579 \fB\fBlgrp_latency_cookie\fR($\fIcookie\fR, $\fIfrom\fR, $\fIto\fR,
580 [$\fIbetween\fR=\fBLGRP_LAT_CPU_TO_MEM\fR])\fR
581 .ad
582 .sp .6
583 .RS 4n
584 This function takes a cookie representing a snapshot of the lgroup hierarchy
585 and returns the latency value between a hardware resource in the $\fIfrom\fR
586 lgroup to a hardware resource in the $\fIto\fR lgroup. If $\fIfrom\fR is the
587 same lgroup as $\fIto\fR, the latency value within that lgroup is returned.
588 .sp
589 The optional $\fIbetween\fR argument should be set to \fBLGRP_LAT_CPU_TO_MEM\fR
590 to specify between which hardware resources the latency should be measured. The
591 only valid value is \fBLGRP_LAT_CPU_TO_MEM\fR, which represents latency from
592 CPU to memory.
593 .sp
594 Upon successful completion, \fBlgrp_latency_cookie()\fR return 1. Otherwise,
595 it returns \fBundef\fR and set \fB$!\fR to indicate the error. For LGRP API
596 version 1, the \fBlgrp_latency_cookie()\fR is an alias for
597 \fBlgrp_latency.()\fR
598 .sp
599 See \fBlgrp_latency_cookie\fR(3LGRP) for more information.
600 .RE
602 .sp
603 .ne 2
604 .na
605 \fB\fBlgrp_latency\fR($\fIfrom\fR, $\fIto\fR)\fR
606 .ad
607 .sp .6
608 .RS 4n
609 This function is similar to the \fBlgrp_latency_cookie()\fR function, but
610 returns the latency between the given lgroups at the given instant in time.
611 Since lgroups can be freed and reallocated, this function might not be able to
612 provide a consistent answer across calls. For that reason,
613 \fBlgrp_latency_cookie()\fR should be used in its place.
614 .sp
615 See \fBlgrp_latency\fR(3LGRP) for more information.
616 .RE
618 .sp
619 .ne 2
620 .na
621 \fB\fBlgrp_resources\fR($\fIcookie\fR, $\fIlgrp\fR, $\fItype\fR)\fR
622 .ad
623 .sp .6
624 .RS 4n
625 This function returns the list of lgroups directly containing resources of the
626 specified type. The resources are represented by a set of lgroups in which each
627 lgroup directly contains CPU and/or memory resources.
628 .sp
629 The \fItype\fR can be specified as:
630 .sp
631 .ne 2
632 .na
633 \fB\fBLGRP_RSRC_CPU\fR\fR
634 .ad
635 .RS 17n
636 CPU resources
637 .RE
639 .sp
640 .ne 2
641 .na
642 \fB\fBLGRP_RSRC_MEM\fR\fR
643 .ad
644 .RS 17n
645 memory resources
646 .RE
648 In the event of error, \fBundef\fR or an empty list is returned and \fB$!\fR is
649 set to indicate the error.
650 .sp
651 This function is available only for API version 2 and returns \fBundef\fR or an
652 empty list for API version 1 and sets \fB$!\fR to \fBEINVAL\fR.
653 .sp
654 See \fBlgrp_resources\fR(3LGRP) for more information.
655 .RE
657 .sp
658 .ne 2
659 .na
660 \fB\fBlgrp_lgrps\fR($\fIcookie\fR, [$\fIlgrp\fR])\fR
661 .ad
662 .sp .6
663 .RS 4n
664 This function returns a list of all lgroups in a hierarchy starting from
665 $\fIlgrp\fR. If $\fIlgrp\fR is not specified, uses the value of
666 \fBlgrp_root\fR($\fIcookie\fR). This function returns the empty list on
667 failure.
668 .sp
669 When called in scalar context, this function returns the total number of
670 lgroups in the system.
671 .RE
673 .sp
674 .ne 2
675 .na
676 \fB\fBlgrp_leaves\fR($\fIcookie\fR, [$\fIlgrp\fR])\fR
677 .ad
678 .sp .6
679 .RS 4n
680 This function returns a list of all leaf lgroups in a hierarchy starting from
681 $\fIlgrp\fR. If $\fIlgrp\fR is not specified, this function uses the value of
682 \fBlgrp_root\fR($\fIcookie\fR). It returns \fBundef\fR or an empty list on
683 failure.
684 .sp
685 When called in scalar context, this function returns the total number of leaf
686 lgroups in the system.
687 .RE
689 .sp
690 .ne 2
691 .na
692 \fB\fBlgrp_isleaf\fR($\fIcookie\fR, $\fIlgrp\fR)\fR
693 .ad
694 .sp .6
695 .RS 4n
696 This function returns True if $\fIlgrp\fR is a leaf (has no children).
697 Otherwise it returns False.
698 .RE
700 .SS "Object methods"
701 .ne 2
702 .na
703 \fB\fBnew\fR([$\fIview\fR])\fR
704 .ad
705 .sp .6
706 .RS 4n
707 This method creates a new \fBSun::Solaris::Lgrp\fR object. An optional argument
708 is passed to the \fBlgrp_init()\fR function. By default this method uses
709 \fBLGRP_VIEW_OS\fR.
710 .RE
712 .sp
713 .ne 2
714 .na
715 \fB\fBcookie()\fR\fR
716 .ad
717 .sp .6
718 .RS 4n
719 This method returns a transparent cookie that can be passed to functions
720 accepting the cookie.
721 .RE
723 .sp
724 .ne 2
725 .na
726 \fB\fBversion\fR([$\fIversion\fR])\fR
727 .ad
728 .sp .6
729 .RS 4n
730 Without the argument, this method returns the current version of the
731 \fBliblgrp\fR(3LIB) library. This method is a wrapper for \fBlgrp_version()\fR
732 with \fBLGRP_VER_NONE\fR as the default version argument.
733 .RE
735 .sp
736 .ne 2
737 .na
738 \fB\fBstale()\fR\fR
739 .ad
740 .sp .6
741 .RS 4n
742 This method returns T if the lgroup information in the object is stale and F
743 otherwise. It is a wrapper for \fBlgrp_cookie_stale()\fR.
744 .RE
746 .sp
747 .ne 2
748 .na
749 \fB\fBview()\fR\fR
750 .ad
751 .sp .6
752 .RS 4n
753 This method returns the snapshot's view of the lgroup hierarchy. It is a
754 wrapper for \fBlgrp_view()\fR.
755 .RE
757 .sp
758 .ne 2
759 .na
760 \fB\fBroot()\fR\fR
761 .ad
762 .sp .6
763 .RS 4n
764 This method returns the root lgroup. It is a wrapper for \fBlgrp_root()\fR.
765 .RE
767 .sp
768 .ne 2
769 .na
770 \fB\fBchildren\fR($\fIlgrp\fR)\fR
771 .ad
772 .sp .6
773 .RS 4n
774 This method returns the list of lgroups that are children of the specified
775 lgroup. It is a wrapper for \fBlgrp_children()\fR.
776 .RE
778 .sp
779 .ne 2
780 .na
781 \fB\fBparents\fR($\fIlgrp\fR)\fR
782 .ad
783 .sp .6
784 .RS 4n
785 This method returns the list of lgroups that are parents of the specified
786 lgroup. It is a wrapper for \fBlgrp_parents()\fR.
787 .RE
789 .sp
790 .ne 2
791 .na
792 \fB\fBnlgrps()\fR\fR
793 .ad
794 .sp .6
795 .RS 4n
796 This method returns the number of lgroups in the hierarchy. It is a wrapper for
797 \fBlgrp_nlgrps()\fR.
798 .RE
800 .sp
801 .ne 2
802 .na
803 \fB\fBmem_size\fR($\fIlgrp\fR, $\fItype\fR, $\fIcontent\fR)\fR
804 .ad
805 .sp .6
806 .RS 4n
807 This method returns the memory size of the given lgroup in bytes. It is a
808 wrapper for \fBlgrp_mem_size()\fR.
809 .RE
811 .sp
812 .ne 2
813 .na
814 \fB\fBcpus\fR($\fIlgrp\fR, $\fIcontext\fR)\fR
815 .ad
816 .sp .6
817 .RS 4n
818 This method returns the list of CPUs in the lgroup specified by $lgrp. It is a
819 wrapper for \fBlgrp_cpus()\fR.
820 .RE
822 .sp
823 .ne 2
824 .na
825 \fB\fBresources\fR($\fIlgrp\fR, $\fItype\fR)\fR
826 .ad
827 .sp .6
828 .RS 4n
829 This method returns the list of lgroups directly containing resources of the
830 specified type. It is a wrapper for \fBlgrp_resources()\fR.
831 .RE
833 .sp
834 .ne 2
835 .na
836 \fB\fBhome\fR($\fIidtype\fR, $\fIid\fR)\fR
837 .ad
838 .sp .6
839 .RS 4n
840 This method returns the home lgroup for the given process or thread. It is a
841 wrapper for \fBlgrp_home()\fR.
842 .RE
844 .sp
845 .ne 2
846 .na
847 \fB\fBaffinity_get\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR)\fR
848 .ad
849 .sp .6
850 .RS 4n
851 This method returns the affinity that the LWP has to a given lgrp. It is a
852 wrapper for \fBlgrp_affinity_get()\fR.
853 .RE
855 .sp
856 .ne 2
857 .na
858 \fB\fBaffinity_set\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR,
859 $\fIaffinity\fR)\fR
860 .ad
861 .sp .6
862 .RS 4n
863 This method sets the affinity that the LWP or set of LWPs specified by
864 $\fIidtype\fR and $\fIid\fR have for the given lgroup. It is a wrapper for
865 lgrp_affinity_set.
866 .RE
868 .sp
869 .ne 2
870 .na
871 \fB\fBlgrps\fR([$\fIlgrp\fR])\fR
872 .ad
873 .sp .6
874 .RS 4n
875 This method returns list of all lgroups in a hierarchy starting from
876 $\fIlgrp\fR or the \fBlgrp_root()\fR if $\fIlgrp\fR is not specified. It is a
877 wrapper for \fBlgrp_lgrps()\fR.
878 .RE
880 .sp
881 .ne 2
882 .na
883 \fB\fBleaves\fR([$\fIlgrp\fR])\fR
884 .ad
885 .sp .6
886 .RS 4n
887 This method returns a list of all leaf lgroups in a hierarchy starting from
888 $\fIlgrp\fR. If $\fIlgrp\fR is not specified, this method uses the value of
889 \fBlgrp_root()\fR. It is a wrapper for \fBlgrp_leaves()\fR.
890 .RE
892 .sp
893 .ne 2
894 .na
895 \fB\fBisleaf\fR($\fIlgrp\fR)\fR
896 .ad
897 .sp .6
898 .RS 4n
899 This method returns True if $\fIlgrp\fR is leaf (has no children) and False
900 otherwise. It is a wrapper for \fBlgrp_isleaf()\fR.
901 .RE
903 .sp
904 .ne 2
905 .na
906 \fB\fBlatency\fR($\fIfrom\fR, $\fIto\fR)\fR
907 .ad
908 .sp .6
909 .RS 4n
910 This method returns the latency value between a hardware resource in the
911 $\fIfrom\fR lgroup to a hardware resource in the $\fIto\fR lgroup. It uses
912 \fBlgrp_latency()\fR for version 1 of \fBliblgrp\fR and
913 \fBlgrp_latency_cookie()\fR for newer versions.
914 .RE
916 .SS "Exports"
917 .LP
918 By default nothing is exported from this module. The following tags can be used
919 to selectively import constants and functions defined in this module:
920 .sp
921 .ne 2
922 .na
923 \fB\fB:LGRP_CONSTANTS\fR\fR
924 .ad
925 .RS 19n
926 \fBLGRP_AFF_NONE\fR, \fBLGRP_AFF_STRONG\fR, \fBLGRP_AFF_WEAK\fR,
927 \fBLGRP_CONTENT_DIRECT\fR, \fBLGRP_CONTENT_HIERARCHY\fR,
928 \fBLGRP_MEM_SZ_FREE\fR, \fBLGRP_MEM_SZ_INSTALLED\fR, \fBLGRP_VER_CURRENT\fR,
929 \fBLGRP_VER_NONE\fR, \fBLGRP_VIEW_CALLER\fR, \fBLGRP_VIEW_OS\fR,
930 \fBLGRP_NONE\fR, \fBLGRP_RSRC_CPU\fR, \fBLGRP_RSRC_MEM\fR,
931 \fBLGRP_CONTENT_ALL\fR, \fBLGRP_LAT_CPU_TO_MEM\fR
932 .RE
934 .sp
935 .ne 2
936 .na
937 \fB\fB:PROC_CONSTANTS\fR\fR
938 .ad
939 .RS 19n
940 \fBP_PID\fR, \fBP_LWPID\fR, \fBP_MYID\fR
941 .RE
943 .sp
944 .ne 2
945 .na
946 \fB\fB:CONSTANTS\fR\fR
947 .ad
948 .RS 19n
949 \fB:LGRP_CONSTANTS\fR, \fB:PROC_CONSTANTS\fR
950 .RE
952 .sp
953 .ne 2
954 .na
955 \fB\fB:FUNCTIONS\fR\fR
956 .ad
957 .RS 19n
958 \fBlgrp_affinity_get()\fR, \fBlgrp_affinity_set()\fR, \fBlgrp_children()\fR,
959 \fBlgrp_cookie_stale()\fR, \fBlgrp_cpus()\fR, \fBlgrp_fini()\fR,
960 \fBlgrp_home()\fR, \fBlgrp_init()\fR, \fBlgrp_latency()\fR,
961 \fBlgrp_latency_cookie()\fR, \fBlgrp_mem_size()\fR, \fBlgrp_nlgrps()\fR,
962 \fBlgrp_parents()\fR, \fBlgrp_root()\fR, \fBlgrp_version()\fR,
963 \fBlgrp_view()\fR, \fBlgrp_resources()\fR, \fBlgrp_lgrps()\fR,
964 \fBlgrp_leaves()\fR, \fBlgrp_isleaf()\fR
965 .RE
967 .sp
968 .ne 2
969 .na
970 \fB\fB:ALL\fR\fR
971 .ad
972 .RS 19n
973 \fB:CONSTANTS\fR, \fB:FUNCTIONS\fR
974 .RE
976 .SS "Error values"
977 .LP
978 The functions in this module return \fBundef\fR or an empty list when an
979 underlying library function fails. The \fB$!\fR is set to provide more
980 information values for the error. The following error codes are possible:
981 .sp
982 .ne 2
983 .na
984 \fB\fBEINVAL\fR\fR
985 .ad
986 .RS 10n
987 The value supplied is not valid.
988 .RE
990 .sp
991 .ne 2
992 .na
993 \fB\fBENOMEM\fR\fR
994 .ad
995 .RS 10n
996 There was not enough system memory to complete an operation.
997 .RE
999 .sp
1000 .ne 2
1001 .na
1002 \fB\fBEPERM\fR\fR
1003 .ad
1004 .RS 10n
1005 The effective user of the calling process does not have appropriate privileges,
1006 and its real or effective user ID does not match the real or effective user ID
1007 of one of the threads.
1008 .RE
1010 .sp
1011 .ne 2
1012 .na
1013 \fB\fBESRCH\fR\fR
1014 .ad
1015 .RS 10n
1016 The specified process or thread was not found.
1017 .RE
1019 .SS "Difference in the API versions"
1020 .LP
1021 The \fBliblgrp\fR(3LIB) library is versioned. The exact version that was used
1022 to compile a module is available through the \fBlgrp_version()\fR function.
1023 .sp
1024 .LP
1025 Version 2 of the \fBlgrp_user\fR API introduced the following constants and
1026 functions not present in version 1:
1027 .br
1028 .in +2
1029 \fBLGRP_RSRC_CPU\fR constant
1030 .in -2
1031 .br
1032 .in +2
1033 \fBLGRP_RSRC_MEM\fR constant
1034 .in -2
1035 .br
1036 .in +2
1037 \fBLGRP_CONTENT_ALL\fR constant
1038 .in -2
1039 .br
1040 .in +2
1041 \fBLGRP_LAT_CPU_TO_MEM\fR constant
1042 .in -2
1043 .br
1044 .in +2
1045 \fBlgrp_resources()\fR function
1046 .in -2
1047 .br
1048 .in +2
1049 \fBlgrp_latency_cookie()\fR function
1050 .in -2
1051 .sp
1052 .LP
1053 The \fBLGRP_RSRC_CPU\fR and \fBLGRP_RSRC_MEM\fR constants are not defined for
1054 version 1. The \fBlgrp_resources()\fR function is defined for version 1 but
1055 always returns an empty list. The \fBlgrp_latency_cookie()\fR function is an
1056 alias for \fBlgrp_latency()\fR for version 1.
1057 .SH ATTRIBUTES
1058 .LP
1059 See \fBattributes\fR(5) for descriptions of the following attributes:
1060 .sp
1062 .sp
1063 .TS
1064 box;
1065 c | c
1066 l | l .
1067 ATTRIBUTE TYPE ATTRIBUTE VALUE
1068 _
1069 Interface Stability Unstable
1070 .TE
1072 .SH SEE ALSO
1073 .LP
1074 \fBlgrp_affinity_get\fR(3LGRP), \fBlgrp_affinity_set\fR(3LGRP),
1075 \fBlgrp_children\fR(3LGRP), \fBlgrp_cookie_stale\fR(3LGRP),
1076 \fBlgrp_cpus\fR(3LGRP), \fBlgrp_fini\fR(3LGRP), \fBlgrp_home\fR(3LGRP),
1077 \fBlgrp_init\fR(3LGRP), \fBlgrp_latency\fR(3LGRP),
1078 \fBlgrp_latency_cookie\fR(3LGRP), \fBlgrp_mem_size\fR(3LGRP),
1079 \fBlgrp_nlgrps\fR(3LGRP), \fBlgrp_parents\fR(3LGRP),
1080 \fBlgrp_resources\fR(3LGRP), \fBlgrp_root\fR(3LGRP), \fBlgrp_version\fR(3LGRP),
1081 \fBlgrp_view\fR(3LGRP), \fBliblgrp\fR(3LIB), \fBattributes\fR(5)