usr/src/cmd/perl/contrib/Sun/Solaris/Lgrp/pod/Lgrp.pod

   1 #
   2 # CDDL HEADER START
   3 #
   4 # The contents of this file are subject to the terms of the
   5 # Common Development and Distribution License (the "License").
   6 # You may not use this file except in compliance with the License.
   7 #
   8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 # or http://www.opensolaris.org/os/licensing.
  10 # See the License for the specific language governing permissions
  11 # and limitations under the License.
  12 #
  13 # When distributing Covered Code, include this CDDL HEADER in each
  14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 # If applicable, add the following below this CDDL HEADER, with the
  16 # fields enclosed by brackets "[]" replaced with your own identifying
  17 # information: Portions Copyright [yyyy] [name of copyright owner]
  18 #
  19 # CDDL HEADER END
  20 #
  21
  22 #
  23 # Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
  24 # Use is subject to license terms.
  25 #
  26 # ident "%Z%%M% %I%     %E% SMI"
  27 #
  28
  29 #
  30 # Sun::Solaris::Lgrp documentation.
  31 #
  32
  33 =head1 NAME
  34
  35 Lgrp - Perl interface to Solaris liblgrp library.
  36
  37 =head1 SYNOPSIS
  38
  39   use Sun::Solaris::Lgrp qw(:ALL);
  40
  41   # initialize lgroup interface
  42   my $cookie = lgrp_init(LGRP_VIEW_OS | LGRP_VIEW_CALLER);
  43   my $l = Sun::Solaris::Lgrp->new(LGRP_VIEW_OS | LGRP_VIEW_CALLER);
  44
  45   my $version = lgrp_version(LGRP_VER_CURRENT | LGRP_VER_NONE);
  46   $version = $l->version(LGRP_VER_CURRENT | LGRP_VER_NONE);
  47
  48   $home = lgrp_home(P_PID, P_MYID);
  49   $home = l->home(P_PID, P_MYID);
  50
  51   lgrp_affinity_set(P_PID, $pid, $lgrp,
  52         LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE);
  53   $l->affinity_set(P_PID, $pid, $lgrp,
  54         LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE);
  55
  56   my $affinity = lgrp_affinity_get(P_PID, $pid, $lgrp);
  57   $affinity = $l->affinity_get(P_PID, $pid, $lgrp);
  58
  59   my $nlgrps = lgrp_nlgrps($cookie);
  60   $nlgrps = $l->nlgrps();
  61
  62   my $root = lgrp_root($cookie);
  63   $root = l->root();
  64
  65   $latency = lgrp_latency($lgrp1, $lgrp2);
  66   $latency = $l->latency($lgrp1, $lgrp2);
  67
  68   my @children = lgrp_children($cookie, $lgrp);
  69   @children = l->children($lgrp);
  70
  71   my @parents = lgrp_parents($cookie, $lgrp);
  72   @parents = l->parents($lgrp);
  73
  74   my @lgrps = lgrp_lgrps($cookie);
  75   @lgrps = l->lgrps();
  76
  77   @lgrps = lgrp_lgrps($cookie, $lgrp);
  78   @lgrps = l->lgrps($lgrp);
  79
  80   my @leaves = lgrp_leaves($cookie);
  81   @leaves = l->leaves();
  82
  83   my $is_leaf = lgrp_isleaf($cookie, $lgrp);
  84   $is_leaf = $l->is_leaf($lgrp);
  85
  86   my @cpus = lgrp_cpus($cookie, $lgrp,
  87         LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
  88   @cpus = l->cpus($lgrp, LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
  89
  90   my $memsize = lgrp_mem_size($cookie, $lgrp,
  91         LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE,
  92         LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
  93   $memsize = l->mem_size($lgrp,
  94         LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE,
  95         LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
  96
  97   my $is_stale = lgrp_cookie_stale($cookie);
  98   $stale = l->stale();
  99
 100   lgrp_fini($cookie);
 101
 102   # The following is available for API version greater than 1:
 103
 104   my @lgrps = lgrp_resources($cookie, $lgrp, LGRP_RSRC_CPU);
 105
 106   # Get latencies from cookie
 107   $latency = lgrp_latency_cookie($cookie, $from, $to);
 108
 109 =head1 DESCRIPTION
 110
 111 This module provides access to the C<liblgrp(3LIB)> library and to various
 112 constants and functions defined in C<sys/lgrp_sys.h> header file. It provides
 113 both the procedural and object interface to the library. The procedural
 114 interface requires (in most cases) passing a transparent cookie around. The
 115 object interface hides all the cookie manipulations from the user.
 116
 117 Functions returning scalar value indicate error by returning B<undef>. The
 118 caller may examine the B<$!> variable to get the C<errno> value.
 119
 120 Functions returning list value return the number of elements in the list when
 121 called in scalar context. In case of error the empty list is return in the array
 122 context and B<undef> is returned in the scalar context.
 123
 124 =head2 CONSTANTS
 125
 126 The constants are exported with B<:CONSTANTS> or B<:ALL> tags:
 127
 128   use Sun::Solaris::Lgrp ':ALL';
 129
 130 or
 131
 132   use Sun::Solaris::Lgrp ':CONSTANTS';
 133
 134 The following constants are available for use in Perl programs:
 135
 136
 137   LGRP_NONE
 138
 139   LGRP_VER_CURRENT
 140   LGRP_VER_NONE
 141
 142   LGRP_VIEW_CALLER
 143   LGRP_VIEW_OS
 144
 145   LGRP_AFF_NONE
 146   LGRP_AFF_STRONG
 147   LGRP_AFF_WEAK
 148
 149   LGRP_CONTENT_DIRECT
 150   LGRP_CONTENT_HIERARCHY
 151
 152   LGRP_MEM_SZ_FREE
 153   LGRP_MEM_SZ_INSTALLED
 154
 155   LGRP_RSRC_CPU (1)
 156   LGRP_RSRC_MEM (1)
 157   LGRP_CONTENT_ALL (1)
 158   LGRP_LAT_CPU_TO_MEM(1)
 159
 160   P_PID
 161   P_LWPID
 162   P_MYID
 163
 164 (1) Available for versions of the liblgrp(3LIB) API greater than 1.
 165
 166 =head2 functions
 167
 168 A detailed description of each function follows. Since this module is intended
 169 to provide a Perl interface to the routines in L<liblgrp(3LIB)>, a very short
 170 description is given for the corresponding functions in this module and a
 171 reference is given to the complete description in the L<liblgrp(3LIB)> man
 172 pages. Any differences or additional functionality in the Perl module are
 173 highlighted and fully documented here.
 174
 175 =over
 176
 177 =item lgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS])
 178
 179 The function initializes the lgroup interface and takes a snapshot of the lgroup
 180 hierarchy with the given view. Given the view, L<lgrp_init()> returns a cookie
 181 representing this snapshot of the lgroup hierarchy. This cookie should be used
 182 with other routines in the lgroup interface needing the lgroup hierarchy. The
 183 L<lgrp_fini()> function should be called with the cookie when it is no longer
 184 needed. Unlike L<lgrp_init (3LGRP)>, C<LGRP_VIEW_OS> is assumed as the default if
 185 no view is provided.
 186
 187 Upon successful completion, L<lgrp_init()> returns a cookie. Otherwise it returns
 188 B<undef> and sets B<$!> to indicate the error.
 189
 190 See L<lgrp_init(3LGRP)> for more information.
 191
 192 =item lgrp_fini($cookie)
 193
 194 The function takes a cookie, frees the snapshot of the lgroup hierarchy created
 195 by L<lgrp_init()>, and cleans up anything else set up by L<lgrp_init()>. After
 196 this function is called, the cookie returned by the lgroup interface might no
 197 longer be valid and should not be used.
 198
 199 Upon successful completion, 1 is returned. Otherwise, B<undef> is returned and
 200 B<$!> is set to indicate the error.
 201
 202 See L<lgrp_fini(3LGRP)> for more information.
 203
 204 =item lgrp_view($cookie)
 205
 206 The function takes a cookie representing the snapshot of the lgroup hierarchy
 207 and returns the snapshot's view of the lgroup hierarchy.
 208
 209 If the given view is C<LGRP_VIEW_CALLER>, the snapshot contains only the
 210 resources that are available to the caller (such as those with respect to
 211 processor sets).  When the view is C<LGRP_VIEW_OS>, the snapshot contains what
 212 is available to the operating system.
 213
 214 Upon succesful completion, the function returns the view for the snapshot of the
 215 lgroup hierarchy represented by the given cookie. Otherwise, B<undef> is
 216 returned and C<$!> is set.
 217
 218 See L<lgrp_view(3LGRP)> for more information.
 219
 220 =item lgrp_home($idtype, $id)
 221
 222 Returns the home lgroup for the given process or thread. The B<$idtype> argument
 223 should be C<P_PID> to specify a process and the B<$id> argument should be its
 224 process id. Otherwise, the B<$idtype> argument should be C<P_LWPID> to specify a
 225 thread and the B<$id> argument should be its LWP id. The value C<P_MYID> can be
 226 used for the id argument to specify the current process or thread.
 227
 228 Upon successful completion, C<lgrp_home()> returns the id of the home lgroup of
 229 the specified process or thread. Otherwise, B<undef> is returned and B<$!> is
 230 set to indicate the error.
 231
 232 See L<lgrp_home(3LGRP)> for more information.
 233
 234 =item lgrp_cookie_stale($cookie)
 235
 236 Upon successful completion, the function returns whether the cookie is
 237 stale. Otherwise, it returns B<undef> and sets B<$!> to indicate the error.
 238
 239 The L<lgrp_cookie_stale()> function will fail with C<EINVAL> if the cookie is
 240 not valid.
 241
 242 See L<lgrp_cookie_stale(3LGRP)> for more information.
 243
 244 =item lgrp_cpus($cookie, $lgrp, $context)
 245
 246 The function takes a cookie representing a snapshot of the lgroup hierarchy and
 247 returns the list of CPUs in the lgroup specified by B<$lgrp>. The B<$context>
 248 argument should be set to one of the following values to specify whether the
 249 direct contents or everything in this lgroup including its children should be
 250 returned:
 251
 252 =over
 253
 254 =item LGRP_CONTENT_HIERARCHY
 255
 256 Everything within this hierarchy.
 257
 258 =item LGRP_CONTENT_DIRECT
 259
 260 Directly contained in lgroup.
 261
 262 =back
 263
 264 When called in scalar context, L<lgrp_cpus()> function returns the number of
 265 CPUs, contained in the specified lgroup.
 266
 267 In case of error B<undef> is returned in scalar context and B<$!> is set to
 268 indicate the error. In list context the empty list is returned and B<$!> is set.
 269
 270 See L<lgrp_cpus(3LGRP)> for more information.
 271
 272 =item lgrp_children($cookie, $lgrp)
 273
 274 The function takes a cookie representing a snapshot of the lgroup hierarchy and
 275 returns the list of lgroups that are children of the specified lgroup.
 276
 277 When called in scalar context, L<lgrp_children()> function returns the number of
 278 children lgroups for the specified lgroup.
 279
 280 In case of error B<undef> or empty list is returned and B<$!> is set to indicate
 281 the error.
 282
 283 See L<lgrp_children(3LGRP)> for more information.
 284
 285 =item lgrp_parents($cookie, $lgrp)
 286
 287 The function takes a cookie representing a snapshot of the lgroup hierarchy and
 288 returns the list of parent of the specified lgroup.
 289
 290 When called in scalar context, L<lgrp_parents()> function returns the number of
 291 parent lgroups for the specified lgroup.
 292
 293 In case of error B<undef> or empty list is returned and B<$!> is set to indicate
 294 the error.
 295
 296 See L<lgrp_parents(3LGRP)> for more information.
 297
 298 =item lgrp_nlgrps($cookie)
 299
 300 The function takes a cookie representing a snapshot of the lgroup hierarchy.  It
 301 returns the number of lgroups in the hierarchy where the number is always at
 302 least one.
 303
 304 In case of error B<undef> is returned and B<$!> is set to EINVAL indicatng that
 305 the cookie is not valid.
 306
 307 See L<lgrp_nlgrps(3LGRP)> for more information.
 308
 309 =item lgrp_root($cookie)
 310
 311 The function returns the root lgroup ID.  In case of error B<undef> is returned
 312 and B<$!> is set to EINVAL indicatng that the cookie is not valid.
 313
 314 See L<lgrp_root(3LGRP)> for more information.
 315
 316 =item lgrp_mem_size($cookie, $lgrp, $type, $content)
 317
 318 The function takes a cookie representing a snapshot of the lgroup hierarchy. The
 319 function returns the memory size of the given lgroup in bytes. The B<$type>
 320 argument should be set to one of the following values:
 321
 322 =over
 323
 324 =item LGRP_MEM_SZ_FREE
 325
 326 Free memory.
 327
 328 =item LGRP_MEM_SZ_INSTALLED
 329
 330 Installed memory.
 331
 332 =back
 333
 334 The B<$content> argument should be set to one of the following values to specify
 335 whether the direct contents or everything in this lgroup including its children
 336 should be returned:
 337
 338 =over
 339
 340 =item LGRP_CONTENT_HIERARCHY
 341
 342 Everything within this hierarchy.
 343
 344 =item LGRP_CONTENT_DIRECT
 345
 346 Directly contained in lgroup.
 347
 348 =back
 349
 350 The total sizes include all the memory in the lgroup including its children,
 351 while the others reflect only the memory contained directly in the given lgroup.
 352
 353 Upon successful completion, the size in bytes is returned. Otherwise, B<undef>
 354 is returned and B<$!> is set to indicate the error.
 355
 356 See L<lgrp_mem_size(3LGRP)> for more information.
 357
 358 =item lgrp_version([$version])
 359
 360 The function takes an interface version number, B$version>, as an argument and
 361 returns an lgroup interface version. The B<$version> argument should be the
 362 value of C<LGRP_VER_CURRENT> or C<LGRP_VER_NONE> to find out the current lgroup
 363 interface version on the running system.
 364
 365 If B<$version> is still supported by the implementation, then L<lgrp_version()>
 366 returns the requested version. If C<LGRP_VER_NONE> is returned, the
 367 implementation cannot support the requested version.
 368
 369 If B<$version> is C<LGRP_VER_NONE>, L<lgrp_version()> returns the current version of
 370 the library.
 371
 372 The following example  tests  whether  the  version  of  the
 373 interface used by the caller is supported:
 374
 375     lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or
 376         die("Built with unsupported lgroup interface");
 377
 378 See L<lgrp_version(3LGRP)> for more information.
 379
 380 =item lgrp_affinity_set($idtype, $id, $lgrp, $affinity)
 381
 382 The function sets of LWPs specified by the B<$idtype> and B<$id> arguments have
 383 for the given lgroup.
 384
 385 The function sets the affinity that the LWP or set of LWPs specified by $idtype
 386 and $id have for the given lgroup. The lgroup affinity can be set to
 387 C<LGRP_AFF_STRONG>, C<LGRP_AFF_WEAK>, or C<LGRP_AFF_NONE>.
 388
 389 If the B<$idtype> is C<P_PID>, the affinity is retrieved for one of the LWPs in
 390 the process or set for all the LWPs of the process with process id (PID) B<$id>.
 391 The affinity is retrieved or set for the LWP of the current process with LWP id
 392 $id if idtype is C<P_LWPID>. If $id is C<P_MYID>, then the current LWP or
 393 process is specified.
 394
 395 There are different levels of affinity that can be specified by a thread for a
 396 particuliar lgroup.  The levels of affinity are the following from strongest to
 397 weakest:
 398
 399 =over
 400
 401 =item LGRP_AFF_STRONG
 402
 403 Strong affinity.
 404
 405 =item LGRP_AFF_WEAK
 406
 407 Weak affinity.
 408
 409 =item LGRP_AFF_NONE
 410
 411 No affinity.
 412
 413 =back
 414
 415 Upon successful completion, L<lgrp_affinity_set()> return 1.  Otherwise, it
 416 returns B<undef> and set B<$!> to indicate the error.
 417
 418 See L<lgrp_affinity_set(3LGRP)> for more information.
 419
 420 =item lgrp_affinity_get($idtype, $id, $lgrp)
 421
 422 The function returns the affinity that the LWP has to a given lgrp. See
 423 L<lgrp_affinity_get()> for detailed description.
 424
 425 See L<lgrp_affinity_get(3LGRP)> for more information.
 426
 427 =item lgrp_latency_cookie($cookie, $from, $to, [$between=LGRP_LAT_CPU_TO_MEM])
 428
 429 The function takes a cookie representing a snapshot of the lgroup hierarchy and
 430 returns the latency value between a hardware resource in the $from lgroup to a
 431 hardware resource in the B<$to> lgroup. If B<$from> is the same lgroup as $to, the
 432 latency value within that lgroup is returned.
 433
 434 The optional B<between> argument should be set to C<LGRP_LAT_CPU_TO_MEM> to specify
 435 between which hardware resources the latency should be measured. Currently the
 436 only valid value is C<LGRP_LAT_CPU_TO_MEM> which represents latency from CPU to
 437 memory.
 438
 439 Upon successful completion, lgrp_latency_cookie() return 1. Otherwise, it
 440 returns B<undef> and set B<$!> to indicate the error. For LGRP API version 1 the
 441 L<lgrp_latency_cookie()> is an alias for L<lgrp_latency()>.
 442
 443 See L<lgrp_latency_cookie(3LGRP)> for more information.
 444
 445 =item lgrp_latency($from, $to)
 446
 447 The function is similiar to the L<lgrp_latency_cookie()> function, but returns the
 448 latency between the given lgroups at the given instant in time.  Since lgroups
 449 may be freed and reallocated, this function may not be able to provide a
 450 consistent answer across calls.  For that reason, it is recommended that
 451 L<lgrp_latency_cookie()> function be used in its place.
 452
 453 See L<lgrp_latency(3LGRP)> for more information.
 454
 455 =item lgrp_resources($cookie, $lgrp, $type)
 456
 457 Return the list of lgroups directly containing resources of the specified type.
 458 The resources are represented by a set of lgroups in which each lgroup directly
 459 contains CPU and/or memory resources.
 460
 461 The type can be specified as
 462
 463 =over
 464
 465 =item C<LGRP_RSRC_CPU>
 466
 467 CPU resources
 468
 469 =item C<LGRP_RSRC_MEM>
 470
 471 Memory resources
 472
 473 =back
 474
 475 In case of error B<undef> or empty list is returned and B<$!> is set to indicate
 476 the error.
 477
 478 This function is only available for API version 2 and will return B<undef> or
 479 empty list for API version 1 and set $! to C<EINVAL>.
 480
 481 See C<lgrp_resources(3LGRP)> for more information.
 482
 483 =item lgrp_lgrps($cookie, [$lgrp])
 484
 485 Returns list of all lgroups in a hierarchy starting from $lgrp. If B<$lgrp> is
 486 not specified, uses the value of lgrp_root($cookie). Returns the empty list on
 487 failure.
 488
 489 When called in scalar context, returns the total number of lgroups in the
 490 system.
 491
 492 =item lgrp_leaves($cookie, [$lgrp])
 493
 494 Returns list of all leaf lgroups in a hierarchy starting from $lgrp. If $lgrp is
 495 not specified, uses the value of lgrp_root($cookie). Returns B<undef> or empty
 496 list on failure.
 497
 498 When called in scalar context, returns the total number of leaf lgroups in the
 499 system.
 500
 501 =item lgrp_isleaf($cookie, $lgrp)
 502
 503 Returns B<True> if $lgrp is leaf (has no children), B<False> otherwise.
 504
 505 =back
 506
 507 =head2 Object Methods
 508
 509 =over
 510
 511 =item new([$view])
 512
 513 Creates a new Sun::Solaris::Lgrp object. An optional argument is passed to
 514 L<lgrp_init()> function. By default uses C<LGRP_VIEW_OS>.
 515
 516 =item cookie()
 517
 518 Returns a transparent cookie that may be passed to functions accepting cookie.
 519
 520 =item version([$version])
 521
 522 Without the argument returns the current version of the L<liblgrp(3LIB)>
 523 library. This is a wrapper for L<lgrp_version()> with C<LGRP_VER_NONE> as the
 524 default version argument.
 525
 526 =item stale()
 527
 528 Returns B<T> if the lgroup information in the object is stale, B<F>
 529 otherwise. It is a wrapper for L<lgrp_cookie_stale()>.
 530
 531 =item view()
 532
 533 Returns the snapshot's view of the lgroup hierarchy. It is a wrapper for
 534 L<lgrp_view()>.
 535
 536 =item root()
 537
 538 Returns the root lgroup. It is a wrapper for L<lgrp_root()>.
 539
 540 =item children($lgrp)
 541
 542 Returns the list of lgroups that are children of the specified lgroup. This is a
 543 wrapper for L<lgrp_children()>.
 544
 545 =item parents($lgrp)
 546
 547 Returns the list of lgroups that are parents of the specified lgroup. This is a
 548 wrapper for L<lgrp_parents()>.
 549
 550 =item nlgrps()
 551
 552 Returns the number of lgroups in the hierarchy. This is a wrapper for
 553 L<lgrp_nlgrps()>.
 554
 555 =item mem_size($lgrp, $type, $content)
 556
 557 Returns the memory size of the given lgroup in bytes. This is a wrapper for
 558 L<lgrp_mem_size()>.
 559
 560 =item cpus($lgrp, $context)
 561
 562 Returns the list of CPUs in the lgroup specified by $lgrp. This is a wrapper for
 563 L<lgrp_cpus()>.
 564
 565 =item resources($lgrp, $type)
 566
 567 Returns the list of lgroups directly containing resources of the specified
 568 type. This is a wrapper for L<lgrp_resources()>.
 569
 570 =item home($idtype, $id)
 571
 572 Returns the home lgroup for the given process or thread. This is a wrapper for
 573 L<lgrp_home()>.
 574
 575 =item affinity_get($idtype, $id, $lgrp)
 576
 577 Returns the affinity that the LWP has to a given lgrp. This is a wrapper for
 578 L<lgrp_affinity_get()>.
 579
 580 =item affinity_set($idtype, $id, $lgrp, $affinity)
 581
 582 Sets of LWPs specified by the $idtype and $id arguments have for the given lgroup.
 583 This is a wrapper for L<lgrp_affinity_set()>.
 584
 585 =item lgrps([$lgrp])
 586
 587 Returns list of all lgroups in a hierarchy starting from $lgrp (or the
 588 L<lgrp_root()> if $lgrp is not specified). This is a wrapper for L<lgrp_lgrps()>.
 589
 590 =item leaves([$lgrp])
 591
 592 Returns list of all leaf lgroups in a hierarchy starting from B<$lgrp>. If $lgrp
 593 is not specified, uses the value of lgrp_root(). This is a wrapper for
 594 L<lgrp_leaves()>.
 595
 596 =item isleaf($lgrp)
 597
 598 Returns B<True> if B<$lgrp> is leaf (has no children), B<False> otherwise.
 599 This is a wrapper for L<lgrp_isleaf()>.
 600
 601 =item latency($from, $to)
 602
 603 Returns the latency value between a hardware resource in the $from lgroup to a
 604 hardware resource in the B<$to> lgroup. It will use L<lgrp_latency()> for
 605 version 1 of liblgrp(3LIB) and L<lgrp_latency_cookie()> for newer versions.
 606
 607 =back
 608
 609 =head2 EXPORTS
 610
 611 By default nothing is exported from this module. The following tags can be used
 612 to selectively import constants and functions defined in this module:
 613
 614 =over
 615
 616 =item :LGRP_CONSTANTS
 617
 618 LGRP_AFF_NONE, LGRP_AFF_STRONG, LGRP_AFF_WEAK, LGRP_CONTENT_DIRECT,
 619 LGRP_CONTENT_HIERARCHY, LGRP_MEM_SZ_FREE, LGRP_MEM_SZ_INSTALLED,
 620 LGRP_VER_CURRENT, LGRP_VER_NONE, LGRP_VIEW_CALLER, LGRP_VIEW_OS,
 621 LGRP_NONE, LGRP_RSRC_CPU, LGRP_RSRC_MEM, LGRP_CONTENT_ALL,
 622 LGRP_LAT_CPU_TO_MEM.
 623
 624 =item :PROC_CONSTANTS
 625
 626 P_PID, P_LWPID P_MYID
 627
 628 =item :CONSTANTS
 629
 630 :LGRP_CONSTANTS, :PROC_CONSTANTS
 631
 632 =item :FUNCTIONS
 633
 634 lgrp_affinity_get(), lgrp_affinity_set(), lgrp_children(), lgrp_cookie_stale(),
 635 lgrp_cpus(), lgrp_fini(), lgrp_home(), lgrp_init(), lgrp_latency(),
 636 lgrp_latency_cookie(), lgrp_mem_size(), lgrp_nlgrps(), lgrp_parents(),
 637 lgrp_root(), lgrp_version(), lgrp_view(), lgrp_resources(),
 638 lgrp_lgrps(), lgrp_leaves(), lgrp_isleaf(), lgrp_lgrps(), lgrp_leaves().
 639
 640 =item :ALL
 641
 642 :CONSTANTS, :FUNCTIONS
 643
 644 =back
 645
 646 =head2 Error values
 647
 648 The functions in this module return B<undef> or an empty list when an underlying
 649 library function fails. The B<$!> is set to provide more information values for
 650 the error. The following error codes are possible:
 651
 652 =over
 653
 654 =item EINVAL
 655
 656 The value supplied is not valid.
 657
 658 =item ENOMEM
 659
 660 There was not enough system memory to complete an operation.
 661
 662 =item EPERM
 663
 664 The effective user of the calling process does not have appropriate privileges,
 665 and its real or effective user ID does not match the real or effective user ID
 666 of one of the threads.
 667
 668 =item ESRCH
 669
 670 The specified  process or thread was not found.
 671
 672 =back
 673
 674 =head2 Difference in the API versions
 675
 676 The C<liblgrp(3LIB)> is versioned. The exact version which was used to compile a
 677 module is available through B<lgrp_version> function.
 678
 679 Version 2 of the lgrpp_user API introduced the following constants and
 680 functions, nbot present in version 1:
 681
 682 =over
 683
 684 =item C<LGRP_RSRC_CPU> constant
 685
 686 =item C<LGRP_RSRC_MEM> constant
 687
 688 =item C<LGRP_CONTENT_ALL> constant
 689
 690 =item C<LGRP_LAT_CPU_TO_MEM> constant
 691
 692 =item C<lgrp_resources()> function
 693
 694 =item C<lgrp_latency_cookie()> function
 695
 696 =back
 697
 698 The C<LGRP_RSRC_CPU> and C<LGRP_RSRC_MEM> are not defined for version 1. The
 699 L<lgrp_resources()> function is defined for version 1 but always returns empty
 700 list. The L<lgrp_latency_cookie()> function is an alias for lgrp_latency for
 701 version 1.
 702
 703 =head1 ATTRIBUTES
 704
 705 See L<attributes(5)> for descriptions of the following attributes:
 706
 707   ___________________________________________________________
 708  |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
 709  |_____________________________|_____________________________|
 710  | Availability                | SUNWpl5u                    |
 711  |_____________________________|_____________________________|
 712  | Interface Stability         | Unstable                    |
 713  |_____________________________|_____________________________|
 714
 715
 716 =head1 SEE ALSO
 717
 718 L<liblgrp(3LIB)>,
 719 L<lgrp_affinity_get(3LGRP)>,
 720 L<lgrp_affinity_set(3LGRP)>,
 721 L<lgrp_children(3LGRP)>,
 722 L<lgrp_cookie_stale(3LGRP)>,
 723 L<lgrp_cpus(3LGRP)>,
 724 L<lgrp_fini(3LGRP)>,
 725 L<lgrp_home(3LGRP)>,
 726 L<lgrp_init(3LGRP)>,
 727 L<lgrp_latency(3LGRP)>,
 728 L<lgrp_mem_size(3LGRP)>,
 729 L<lgrp_nlgrps(3LGRP)>,
 730 L<lgrp_parents(3LGRP)>,
 731 L<lgrp_root(3LGRP)>,
 732 L<lgrp_version(3LGRP)>,
 733 L<lgrp_view(3LGRP)>,
 734 L<lgrp_resources(3LGRP)>,
 735 L<lgrp_latency_cookie(3LGRP)>,
 736 L<attributes(5)>
 737
 738 =cut