11583 Some man3lib pages are missing parts of the SYNOPSIS

   1 LIBPOOL(3LIB)                 Interface Libraries                LIBPOOL(3LIB)
   2 
   3 
   4 
   5 NAME
   6        libpool - pool configuration manipulation library
   7 
   8 SYNOPSIS
   9        cc [ flag... ] file... -lpool [ library... ]
  10        #include <pool.h>
  11 
  12 
  13 DESCRIPTION
  14        The functions in this library define the interface for reading and
  15        writing resource pools configuration files, as well as that for
  16        committing an existing configuration to becoming the running OS
  17        configuration (with respect to partitioning subsystems). The <pool.h>
  18        header provides type and function declarations for all library
  19        services.
  20 
  21 
  22        The resource pools facility brings together process-bindable resources
  23        into a common abstraction called a pool. Processor sets and other
  24        entities can be configured, grouped, and labelled in a persistent
  25        fashion such that workload components can be associated with a subset
  26        of a system's total resources. The libpool library provides a C
  27        language API for accessing this functionality, while pooladm(1M),
  28        poolbind(1M), and poolcfg(1M) make this facility available through
  29        command invocations from a shell. Each of those manual pages describes
  30        aspects of the pools facility; this page describes the properties
  31        available to the various entities managed within the pools facility.
  32        These entities include the system, pools, and the pset resources for
  33        processor sets.
  34 
  35 
  36        When the pools facility is enabled on a system, the behavior of the
  37        following functions is modified.
  38 
  39 
  40 
  41 
  42                System Call            Error Value
  43        -------------------------------------------
  44        pset_assign(pset !=PS_QUERY)   ENOTSUP
  45        pset_bind(pset !=PS_QUERY)     ENOTSUP
  46        pset_create()                  ENOTSUP
  47        pset_destroy()                 ENOTSUP
  48        pset_setattr()                 ENOTSUP
  49 
  50 
  51 
  52        Each active entity within the resource pools framework can have an
  53        arbitrary collection of named, typed properties associated with it.
  54        Properties supported by the pools framework are listed, with
  55        descriptions, under each entity below.  In general, resource properties
  56        can be one of five types: boolean (bool), signed (int64) and unsigned
  57        (uint64) integers, floating point (double), and string values.
  58 
  59 
  60        All entities and resources support a string property for commenting
  61        purposes; this property is available for use by management applications
  62        to record descriptions and other administrator oriented data. The
  63        comment field is not used by the default pools commands, except when a
  64        configuration is initiated by the poolcfg utility, in which case an
  65        informative message is placed in the system.comment property for that
  66        configuration.
  67 
  68    System
  69 
  70                Property name            Type              Description
  71        system.allocate-method          string   Allocation method to use when
  72                                                 this configuration is
  73                                                 instantiated
  74        system.bind-default             bool     If specified pool not found,
  75                                                 bind to pool with 'pool.default'
  76                                                 property set to true
  77        system.comment                  string   User description of system
  78        system.name                     string   User name for the configuration
  79        system.version                  int64    libpool version required to
  80                                                 manipulate this configuration
  81        system.poold.log-level          string   poold logging level
  82        system.poold.log-location       string   poold logging location
  83        system.poold.history-file       string   poold decision history location
  84        system.poold.monitor-interval   uint64   poold monitoring sample interval
  85        system.poold.objectives         string   poold objectives for a system.
  86 
  87 
  88 
  89        The system.allocate-method, system.bind-default, system.comment,
  90        system.name, system.poold.log-level, system.poold.log-location,
  91        system.poold.history-file, system.poold.monitor-interval, and
  92        system.poold.objectives properties are writable; the system.version
  93        property is not.
  94 
  95 
  96        The system.allocate-method property accepts only two values,
  97        "importance based" and "surplus to default". The default value for this
  98        property is "importance based". The property is optional and if it is
  99        not present the library will allocate resources as though it were
 100        present and had the default value. These strings are defined in
 101        <pool.h>   as POA_IMPORTANCE and POA_SURPLUS_TO_DEFAULT.
 102 
 103 
 104        If "importance based" allocation is defined, then during a commit the
 105        library will allocate resources to pools using an algorithm that
 106        observes minimum and maximum constraints for resources but favors those
 107        resources with greater importance.
 108 
 109 
 110        If "surplus to default" is defined, then during a commit the library
 111        will allocate minimum resources to all resource sets apart from default
 112        which will receive any surplus.
 113 
 114 
 115        The system.bind-default property defaults to true. This property
 116        interacts with the project.pool resource control to specify the binding
 117        behavior for processes associated with a project. If project.pool is
 118        not specified, then this property has no effect. If project.pool is
 119        specified and the specified pool exists, this property has no effect.
 120        If the specified pool does not exist, perhaps because of a
 121        reconfiguration, then this property controls the binding behavior for
 122        the project member. If system.bind-default is true, then the project
 123        member is bound to the default pool (identified as the pool for which
 124        pool.default is true); otherwise the project member is refused access
 125        to the system. Care should be taken with the pools configuration if
 126        this property is set to false, so as to avoid denying users access to
 127        the system.
 128 
 129 
 130        The various poold properties are used to configure the operation of
 131        poold(1M).
 132 
 133 
 134        The system.poold.log-level property is used to specify the level of
 135        detail provided in log messages. Valid values are: ALERT, CRIT, ERR,
 136        WARNING, NOTICE, INFO, and DEBUG.
 137 
 138 
 139        ALERT provides the least level of detail, DEBUG the greatest. See
 140        syslog(3C) for more information about the meaning of these debug
 141        levels.  If this property is not specified, the default value NOTICE is
 142        used.
 143 
 144 
 145        The system.poold.log-location property is used to specify the location
 146        of the logfiles generated by poold. The special value of "syslog"
 147        indicates that logged messages should be written to syslog(). If this
 148        property is not specified, the default location /var/log/pool is used.
 149 
 150 
 151        The system.poold.history-file specifies the location of the decision
 152        history file which is used by poold to improve the quality of its
 153        decision making over time. If this property is not specified, the
 154        default location /var/adm/pool is used.
 155 
 156 
 157        The system.poold.monitor-interval property specifies the monitoring
 158        interval (in milliseconds) to be used by poold when sampling
 159        utilization statistics. If this property is not specified, the default
 160        value of 15 seconds is used.
 161 
 162 
 163        The system.poold.objectives property specifies any system wide
 164        objectives. An objectives property has the following syntax:
 165 
 166          objectives = objective [; objective]*
 167          objective = [n:] keyword [op] [value]
 168 
 169 
 170 
 171        All objectives are prefixed with an optional importance. The importance
 172        acts as a multiplier for the objective and thus increases the
 173        significance of its contribution to the objective function evaluation.
 174        If no importance is specified, the default value is 1.
 175 
 176 
 177        The "wt-load" objective is the only objective to which a system element
 178        can be set. This objective favors configurations that match resource
 179        allocations to resource utilization. A resource set that uses more
 180        resources will be given more resources when this objective is active.
 181        An administrator should use this objective when he is relatively
 182        satisfied with the constraints established using the minimum and
 183        maximum properties and would like the DRP to manipulate resources
 184        freely within those constraints.
 185 
 186    Pools
 187 
 188         Property name     Type               Description
 189        pool.active       bool     Mark this pool as active, if true.
 190        pool.comment      string   User description of pool.
 191        pool.default      bool     Mark this pool as the default
 192                                   pool, if true; see
 193                                   system.bind-default property.
 194        pool.importance   int64    Relative importance of this pool;
 195                                   for possible resource dispute
 196                                   resolution.
 197        pool.name         string   User name for pool; used by
 198                                   setproject(3PROJECT) as value for
 199                                   'project.pool' project attribute
 200                                   in project(4) database.
 201        pool.scheduler    string   Scheduler class to which consumers
 202                                   of this pool will be bound. This
 203                                   property is optional and if not
 204                                   specified, the scheduler bindings
 205                                   for consumers of this pool are not
 206                                   affected.
 207        pool.sys_id       int64    System-assigned pool ID.
 208        pool.temporary    bool     Mark this pool as a temporary
 209                                   resource; if true, this pool can
 210                                   exist only in the dynamic
 211                                   configuration and cannot be
 212                                   committed to a configuration file.
 213 
 214 
 215 
 216        The pool.default, pool.sys_id, and pool.temporary properties are not
 217        writable; all other listed properties are writable.
 218 
 219 
 220        If pool.scheduler is specified, it must be set to the name of a valid
 221        scheduling class for the system. See the -c option for priocntl(1) for
 222        a list of valid class names.
 223 
 224    Processor Sets
 225 
 226            Property name        Type               Description
 227        pset.comment            string   User description of resource.
 228        pset.default            bool     Marks default processor set.
 229        pset.load               uint64   The load for this processor set.
 230        pset.max                uint64   Maximum number of CPUs permitted
 231                                         in this processor set.
 232        pset.min                uint64   Minimum number of CPUs permitted
 233                                         in this processor set.
 234        pset.name               string   User name for resource.
 235        pset.size               uint64   Current number of CPUs in this
 236                                         processor set.
 237        pset.sys_id             int64    System-assigned processor set ID.
 238        pset.temporary          bool     Mark this processor set as a
 239                                         temporary resource; if true, this
 240                                         processor set can exist only in
 241                                         the dynamic configuration and
 242                                         cannot be committed to a
 243                                         configuration file.
 244        pset.type               string   Names resource type; value for
 245                                         all processor sets is pset.
 246        pset.units              string   Identifies meaning of
 247                                         size-related properties; value
 248                                         for all processor sets is
 249                                         population.
 250        pset.poold.objectives   string   Specifies the poold objectives
 251                                         for a pset.
 252 
 253 
 254 
 255        The pset.comment, pset.max, pset.min, pset.name, and
 256        pset.poold.objectives properties are writable; the pset.default,
 257        pset.load, pset.size, pset.sys_id, pset.temporary, pset.type, and
 258        pset.units properties are not.
 259 
 260 
 261        The pset.load property represents the load on a processor set. The
 262        lowest value for this property is 0. The value of pset.load increases
 263        in a linear fashion with the load on the set, as measured by the number
 264        of jobs in the system run queue.
 265 
 266 
 267        The pset.poold.objectives property specifies an objective which is
 268        specific to a particular pset. See the system.poold.objectives entry
 269        for the specification of this property's syntax.
 270 
 271 
 272        There are two types of objectives that can be set on a pset:
 273 
 274        locality
 275                       This objective influences the impact that locality, as
 276                       measured by lgroup data, has upon the chosen
 277                       configuration. This objective can take one of three
 278                       values:
 279 
 280                       tight
 281                                If set, configurations that maximize resource
 282                                locality are favored.
 283 
 284 
 285                       loose
 286                                If set, configurations that minimize resource
 287                                locality are favored.
 288 
 289 
 290                       none
 291                                This is the default value for this objective.
 292                                If set, configuration favorability is
 293                                uninfluenced by resource locality.
 294 
 295 
 296 
 297        utilization
 298                       This objective favors configurations that allocate
 299                       resources to partitions that are failing to preserve the
 300                       specified utilization objective.
 301 
 302 
 303 
 304        These objectives are specified in terms of an operator and a value. The
 305        operators are
 306 
 307        <
 308             The ``less than'' operator is used to indicate that the specified
 309             value should be treated as a maximum target value.
 310 
 311 
 312        >
 313             The ``greater than'' operator is used to indicate that the
 314             specified value should be treated as a minimum target value.
 315 
 316 
 317        ~
 318             The ``about'' operator is used to indicate that the specified
 319             value should be treated as a target value about which some
 320             fluctuation is acceptable.
 321 
 322 
 323 
 324        Only one objective of each type of operator can be set. For example, if
 325        the ~ operator is set, the < and      > operators cannot be set. It is
 326        possible to set a < and a > operator together; the values will be
 327        validated to ensure that they do not overlap.
 328 
 329    Processors
 330 
 331        Property name    Type               Description
 332        -----------------------------------------------------------
 333        cpu.comment     string   User description of CPU.
 334        cpu.pinned      bool     CPU pinned to this processor set.
 335        cpu.status      int64    Processor status, on-line,
 336                                 offline or interrupts disabled.
 337        cpu.sys_id      int64    System-assigned processor ID.
 338 
 339 
 340 
 341        The cpu.comment, cpu.pinned, and cpu.status properties are writable.
 342 
 343 
 344        The cpu.status property can be set only to the following values:
 345 
 346        off-line
 347                    Set the CPU offline.
 348 
 349 
 350        on-line
 351                    Set the CPU online.
 352 
 353 
 354        no-intr
 355                    Disable interrupt processing on the CPU.
 356 
 357 
 358 
 359        These values are defined in <sys/processor.h> as   the PS_OFFLINE,
 360        PS_ONLINE, and PS_NOINTR macros.
 361 
 362 INTERFACES
 363        The shared object libpool.so.1 provides the public interfaces defined
 364        below. See Intro(3) for additional information on shared object
 365        interfaces.
 366 
 367 
 368 
 369 
 370        pool_associate                   pool_component_info
 371        pool_component_to_elem           pool_conf_alloc
 372        pool_conf_close                  pool_conf_commit
 373        pool_conf_export                 pool_conf_free
 374        pool_conf_info                   pool_conf_location
 375        pool_conf_open                   pool_conf_remove
 376        pool_conf_rollback               pool_conf_status
 377        pool_conf_to_elem                pool_conf_update
 378        pool_conf_validate               pool_create
 379        pool_destroy                     pool_dissociate
 380        pool_dynamic_location            pool_error
 381        pool_get_binding                 pool_get_owning_resource
 382        pool_get_pool                    pool_get_property
 383        pool_get_resource                pool_get_resource_binding
 384        pool_get_status                  pool_info
 385        pool_put_property                pool_query_components
 386        pool_query_pool_resources        pool_query_pools
 387        pool_query_resource_components   pool_query_resources
 388        pool_resource_create             pool_resource_destroy
 389        pool_resource_info               pool_resource_to_elem
 390        pool_resource_transfer           pool_resource_type_list
 391        pool_resource_xtransfer          pool_rm_property
 392        pool_set_binding                 pool_set_status
 393        pool_static_location             pool_strerror
 394        pool_to_elem                     pool_value_alloc
 395        pool_value_free                  pool_value_get_bool
 396        pool_value_get_double            pool_value_get_int64
 397        pool_value_get_name              pool_value_get_string
 398        pool_value_get_type              pool_value_get_uint64
 399        pool_value_set_bool              pool_value_set_double
 400        pool_value_set_int64             pool_value_set_name
 401        pool_value_set_string            pool_value_set_uint64
 402        pool_version                     pool_walk_components
 403        pool_walk_pools                  pool_walk_properties
 404        pool_walk_resources
 405 
 406 
 407 FILES
 408        /usr/lib/libpool.so.1
 409                                    shared object
 410 
 411 
 412        /usr/lib/64/libpool.so.1
 413                                    64-bit shared object
 414 
 415 
 416 ATTRIBUTES
 417        See attributes(5) for descriptions of the following attributes:
 418 
 419 
 420 
 421 
 422        +--------------------+-----------------+
 423        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 424        +--------------------+-----------------+
 425        |CSI                 | Enabled         |
 426        +--------------------+-----------------+
 427        |Interface Stability | Unstable        |
 428        +--------------------+-----------------+
 429        |MT-Level            | Safe            |
 430        +--------------------+-----------------+
 431 
 432 SEE ALSO
 433        Intro(3), pool_component_info(3POOL), pool_conf_open(3POOL),
 434        pool_conf_to_elem(3POOL), pool_create(3POOL), pool_error(3POOL),
 435        pool_get_binding(3POOL), pool_get_property(3POOL),
 436        pool_get_resource(3POOL), pool_resource_create(3POOL),
 437        pool_value_alloc(3POOL), pool_walk_pools(3POOL), attributes(5), smf(5)
 438 
 439 NOTES
 440        Functions in libpool can be used to manipulate static configurations
 441        even when the pools facility is not enabled. See pooladm(1M) and
 442        pool_set_status(3POOL) for more information about enabling the pools
 443        facility. The pools facility must be enabled, however, to modify the
 444        dynamic configuration.
 445 
 446 
 447        Since the Resource Pools facility is an smf(5) service, it can also be
 448        enabled and disabled using the standard Service Management Facility
 449        (SMF) interfaces.
 450 
 451 
 452 
 453                                 August 19, 2019                  LIBPOOL(3LIB)
--- EOF ---