1 POOL_GET_POOL(3POOL)         Pool Configuration Manipulation Library Functions
   2 
   3 
   4 
   5 NAME
   6        pool_get_pool, pool_get_resource, pool_query_components,
   7        pool_query_pools, pool_query_resources - retrieve resource pool
   8        configuration elements
   9 
  10 SYNOPSIS
  11        cc [ flag]...  file... -lpool [ library... ]
  12        #include <pool.h>
  13 
  14        pool_t *pool_get_pool(pool_conf_t *conf, const char *name);
  15 
  16 
  17        pool_resource_t *pool_get_resource(pool_conf_t *conf
  18             const char *type, const char *name);
  19 
  20 
  21        pool_component_t **pool_query_components(pool_conf_t *conf,
  22             uint_t *nelem, pool_value_t **props);
  23 
  24 
  25        pool_t **pool_query_pools(pool_conf_t *conf, uint_t *nelem,
  26             pool_value_t **props);
  27 
  28 
  29        pool_component_t **pool_query_resources(pool_conf_t *conf,
  30             uint_t *nelem, pool_value_t **props);
  31 
  32 
  33 DESCRIPTION
  34        These functions provide a means for querying the contents of the
  35        specified configuration. The conf argument for each function refers to
  36        the target configuration to which the operation applies.
  37 
  38 
  39        The pool_get_pool() function returns the pool with the given name from
  40        the provided configuration.
  41 
  42 
  43        The pool_get_resource() function returns the resource with the given
  44        name and type from the provided configuration.
  45 
  46 
  47        The pool_query_components() function retrieves all resource components
  48        that match the given list of properties. If the list of properties is
  49        NULL, all components are returned. The number of elements returned is
  50        stored in the location pointed to by nelem. The value returned by
  51        pool_query_components() is allocated with malloc(3C) and must be
  52        explicitly freed.
  53 
  54 
  55        The pool_query_pools() function behaves similarly to
  56        pool_query_components() and returns the list of pools that match the
  57        given list of properties. The value returned must be freed by the
  58        caller.
  59 
  60 
  61        The pool_query_resources() function similarly returns the list of
  62        resources that match the given list of properties. The return value
  63        must be freed by the caller.
  64 
  65 RETURN VALUES
  66        The pool_get_pool() and pool_get_resource() functions return the
  67        matching pool and resource, respectively. Otherwise, they return NULL
  68        and pool_error(3POOL) returns the pool-specific error value.
  69 
  70 
  71        The pool_query_components(), pool_query_pools(), and
  72        pool_query_resources() functions return a null-terminated array of
  73        components, pools, and resources, respectively. If the query was
  74        unsuccessful or there were no matches, NULL is returned and
  75        pool_error() returns the pool-specific error value.
  76 
  77 ERRORS
  78        The pool_get_pool() function will fail if:
  79 
  80        POE_BADPARAM
  81                        The supplied configuration's status is not POF_VALID.
  82 
  83 
  84 
  85        The pool_get_resource() function will fail if:
  86 
  87        POE_BADPARAM
  88                        The supplied configuration's status is not POF_VALID.
  89 
  90 
  91        POE_SYSTEM
  92                        There is not enough memory available to allocate
  93                        working buffers. Check errno for the specific system
  94                        error code.
  95 
  96 
  97 
  98        The pool_query_components(), pool_query_pools(), and
  99        pool_query_resources() functions will fail if:
 100 
 101        POE_BADPARAM
 102                            The supplied configuration's status is not
 103                            POF_VALID.
 104 
 105 
 106        POE_INVALID_CONF
 107                            The query generated results that were not of the
 108                            correct type. The configuration is invalid.
 109 
 110 
 111        POE_SYSTEM
 112                            There is not enough memory available to allocate
 113                            working buffers. Check errno for the specific
 114                            system error code.
 115 
 116 
 117 EXAMPLES
 118        Example 1 Retrieve the pool named "foo" from a given configuration.
 119 
 120          #include <pool.h>
 121          #include <stdio.h>
 122 
 123          ...
 124 
 125          pool_conf_t *conf;
 126          pool_t *pool;
 127 
 128          ...
 129 
 130          if ((pool = pool_get_pool(conf, "foo")) == NULL) {
 131                  (void) fprintf(stderr, "Cannot retrieve pool named
 132                  'foo'\n");
 133                  ...
 134          }
 135 
 136 
 137 ATTRIBUTES
 138        See attributes(5) for descriptions of the following attributes:
 139 
 140 
 141 
 142 
 143        +--------------------+-----------------+
 144        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 145        +--------------------+-----------------+
 146        |CSI                 | Enabled         |
 147        +--------------------+-----------------+
 148        |Interface Stability | Unstable        |
 149        +--------------------+-----------------+
 150        |MT-Level            | Safe            |
 151        +--------------------+-----------------+
 152 
 153 SEE ALSO
 154        libpool(3LIB), pool_error(3POOL), attributes(5)
 155 
 156 
 157 
 158                                January 18, 2020           POOL_GET_POOL(3POOL)