Locality Group Library Functions                 lgrpinit(3LGRP)



NAME
     lgrpinit - initialize lgroup interface

SYNOPSIS
     cc [ flag... ] file... -llgrp [ library... ]
     #include 

     lgrpcookiet lgrpinit(lgrpviewt view);


DESCRIPTION
     The lgrpinit() function initializes  the  lgroup  interface
     and  takes a snapshot of the lgroup hierarchy with the given
     view.  If the given view is LGRPVIEWCALER,  the  snapshot
     contains only the resources that are available to the caller
     (for example, with respect to processor sets). When the view
     is  LGRPVIEWOS, the snapshot contains what is available to
     the operating system.


     Given the view, lgrpinit() returns  a  cookie  representing
     this snapshot of the lgroup hierarchy. This cookie should be
     used with other routines in the lgroup interface needing the
     lgroup  hierarchy.  The  lgrpfini(3LGRP) function should be
     called with the cookie when it is no longer needed.


     The lgroup hiearchy represents the latency topology  of  the
     machine.   The  hierarchy is simplified to be a tree and can
     be used to find the nearest resources.


     The lgroup hiearchy consists of a root lgroup, which is  the
     maximum  bounding locality group of the system, contains all
     the CPU and memory resources of the machine, and may contain
     other  locality groups that contain CPUs and memory within a
     smaller locality. The leaf lgroups contain resources  within
     the smallest latency.


     The resources of a  given  lgroup  come  directly  from  the
     lgroup  itself  or  from  leaf  lgroups contained within the
     lgroup. Leaf lgroups directly contain  their  own  resources
     and do not encapsulate any other lgroups.


     The lgroup  hierarchy  can  be  used  to  find  the  nearest
     resources. From a given lgroup, the closest resources can be
     found in the lgroup itself. After  that,  the  next  nearest
     resources can be found in its parent lgroup, and so on until
     the root lgroup is reached where all the  resources  of  the
     machine are located.



SunOS 5.11          Last change: 26 Jan 2005                    1






Locality Group Library Functions                 lgrpinit(3LGRP)



RETURN VALUES
     Upon successful completion, lgrpinit()  returns  a  cookie.
     Otherwise  it  returns  LGRPCOKIENONE  and  sets errno to
     indicate the error.

ERORS
     The lgrpinit() function will fail if:

     EINVAL    The view is not valid.


     ENOMEM    There  was  not  enough  memory  to  allocate  the
               snapshot of the lgroup hierarchy.


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Evolving                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     lgrpchildren(3LGRP),              lgrpcookiestale(3LGRP),
     lgrpcpus(3LGRP),   lgrpfini(3LGRP),  lgrpmemsize(3LGRP),
     lgrpnlgrps(3LGRP),                     lgrpparents(3LGRP),
     lgrpresources(3LGRP),  lgrproot(3LGRP),  lgrpview(3LGRP),
     liblgrp(3LIB), attributes(5)



















SunOS 5.11          Last change: 26 Jan 2005                    2