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);
  13 
  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);
  18 
  19 my $version = lgrp_version(LGRP_VER_CURRENT | LGRP_VER_NONE);
  20 $version = $l->version(LGRP_VER_CURRENT | LGRP_VER_NONE);
  21 
  22 $home = lgrp_home(P_PID, P_MYID);
  23 $home = l->home(P_PID, P_MYID);
  24 
  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);
  29 
  30 my $affinity = lgrp_affinity_get(P_PID, $\fIpid\fR, $\fIlgrp\fR);
  31 $affinity = $l->affinity_get(P_PID, $\fIpid\fR, $\fIlgrp\fR);
  32 
  33 my $nlgrps = lgrp_nlgrps($\fIcookie\fR);
  34 $nlgrps = $l->nlgrps();
  35 
  36 my $root = lgrp_root($\fIcookie\fR);
  37 $root = l->root();
  38 
  39 $latency = lgrp_latency($\fIlgrp1\fR, $\fIlgrp2\fR);
  40 $latency = $l->latency($\fIlgrp1\fR, $\fIlgrp2\fR);
  41 
  42 my @children = lgrp_children($\fIcookie\fR, $\fIlgrp\fR);
  43 @children = l->children($lgrp);
  44 
  45 my @parents = lgrp_parents($\fIcookie\fR, $\fIlgrp\fR);
  46 @parents = l->parents($\fIlgrp\fR);
  47 
  48 my @lgrps = lgrp_lgrps($\fIcookie\fR);
  49 @lgrps = l->lgrps();
  50 
  51 @lgrps = lgrp_lgrps($\fIcookie\fR, $\fIlgrp\fR);
  52 @lgrps = l->lgrps($\fIlgrp\fR);
  53 
  54 my @leaves = lgrp_leaves($\fIcookie\fR);
  55 @leaves = l->leaves();
  56 
  57 my $is_leaf = lgrp_isleaf($\fIcookie\fR, $\fIlgrp\fR);
  58 $is_leaf = $l->is_leaf($\fIlgrp\fR);
  59 
  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);
  64 
  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);
  71 
  72 my $is_stale = lgrp_cookie_stale($\fIcookie\fR);
  73 $stale = l->stale();
  74 
  75 lgrp_fini($\fIcookie\fR);
  76 
  77 # The following is available for API version greater than 1:
  78 my @lgrps = lgrp_resources($\fIcookie\fR, $\fIlgrp\fR, LGRP_RSRC_CPU);
  79 
  80 # Get latencies from cookie
  81 $latency = lgrp_latency_cookie($\fIcookie\fR, $\fIfrom\fR, $\fIto\fR);
  82 .fi
  83 
  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
 109 
 110 .sp
 111 .LP
 112 or
 113 .sp
 114 .in +2
 115 .nf
 116 use Sun::Solaris::Lgrp ':CONSTANTS';
 117 .fi
 118 .in -2
 119 
 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
 230 
 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
 248 
 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
 270 
 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
 291 
 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
 307 
 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
 328 
 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
 337 
 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
 347 
 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
 366 
 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
 385 
 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
 402 
 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
 417 
 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
 437 
 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
 446 
 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
 458 
 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
 467 
 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
 477 
 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
 506 
 507 See \fBlgrp_version\fR(3LGRP) for more information.
 508 .RE
 509 
 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
 539 
 540 .sp
 541 .ne 2
 542 .na
 543 \fB\fBLGRP_AFF_WEAK\fR\fR
 544 .ad
 545 .RS 19n
 546 weak affinity
 547 .RE
 548 
 549 .sp
 550 .ne 2
 551 .na
 552 \fB\fBLGRP_AFF_NONE\fR\fR
 553 .ad
 554 .RS 19n
 555 no affinity
 556 .RE
 557 
 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
 563 
 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
 575 
 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
 601 
 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
 617 
 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
 638 
 639 .sp
 640 .ne 2
 641 .na
 642 \fB\fBLGRP_RSRC_MEM\fR\fR
 643 .ad
 644 .RS 17n
 645 memory resources
 646 .RE
 647 
 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
 656 
 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
 672 
 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
 688 
 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
 699 
 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
 711 
 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
 722 
 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
 734 
 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
 745 
 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
 756 
 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
 766 
 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
 777 
 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
 788 
 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
 799 
 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
 810 
 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
 821 
 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
 832 
 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
 843 
 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
 854 
 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
 867 
 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
 879 
 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
 891 
 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
 902 
 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
 915 
 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
 933 
 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
 942 
 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
 951 
 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
 966 
 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
 975 
 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
 989 
 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
 998 
 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
1009 
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
1018 
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
1061 
1062 .sp
1063 .TS
1064 box;
1065 c | c
1066 l | l .
1067 ATTRIBUTE TYPE  ATTRIBUTE VALUE
1068 _
1069 Interface Stability     Unstable
1070 .TE
1071 
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)