1 POOL_RESOURCE_CREATE(3POOL)  Pool Configuration Manipulation Library Functions
   2 
   3 
   4 
   5 NAME
   6        pool_resource_create, pool_resource_destroy, pool_resource_info,
   7        pool_query_resource_components, pool_resource_transfer,
   8        pool_resource_xtransfer - resource pool resource manipulation functions
   9 
  10 SYNOPSIS
  11        cc [ flag... ] file... -lpool [ library... ]
  12        #include <pool.h>
  13 
  14        pool_resource_t *pool_resource_create(pool_conf_t *conf,
  15             const char *type, const char *name);
  16 
  17 
  18        int pool_resource_destroy(pool_conf_t *conf,
  19             pool_resource_t *resource);
  20 
  21 
  22        const char *pool_resource_info(pool_conf_t *conf
  23             pool_resource_t *resource, int flags);
  24 
  25 
  26        pool_component_t **pool_query_resource_components(
  27             pool_conf_t *conf, pool_resource_t *resource,
  28             uint_t *nelem, pool_value_t **props);
  29 
  30 
  31        int pool_resource_transfer(pool_conf_t *conf,
  32             pool_resource_t *source, pool_resource_t *target,
  33             uint64_t size);
  34 
  35 
  36        int pool_resource_xtransfer(pool_conf_t *conf,
  37             pool_resource_t *source, pool_resource_t *target,
  38             pool_component_t **components);
  39 
  40 
  41 DESCRIPTION
  42        The pool_resource_create() function creates and returns a new resource
  43        of the given name and type in the provided configuration. If there is
  44        already a resource of the given name, the operation will fail.
  45 
  46 
  47        The pool_resource_destroy() function removes the specified resource
  48        from its configuration file.
  49 
  50 
  51        The pool_resource_info() function returns a string describing the given
  52        resource. The string is allocated with malloc(3C). The caller is
  53        responsible for freeing the returned string. If the flags argument is
  54        non-zero, the string returned also describes the components (if any)
  55        contained in the resource.
  56 
  57 
  58        The pool_query_resource_components() function returns a null-terminated
  59        array of the components (if any) that comprise the given resource.
  60 
  61 
  62        The pool_resource_transfer() function transfers size basic units from
  63        the source resource to the target. Both resources must be of the same
  64        type for the operation to succeed. Transferring component resources,
  65        such as processors, is always performed as series of
  66        pool_resource_xtransfer() operations, since discrete resources must be
  67        identified for transfer.
  68 
  69 
  70        The pool_resource_xtransfer() function transfers the specific
  71        components from the source resource to the target. Both resources must
  72        be of the same type, and of a type that contains components (such as
  73        processor sets). The components argument is a null-terminated list of
  74        pool_component_t.
  75 
  76 
  77        The conf argument for each function refers to the target configuration
  78        to which the operation applies.
  79 
  80 RETURN VALUES
  81        Upon successful completion, pool_resource_create() returns a new
  82        pool_resource_t with default properties initialized. Otherwise, NULL is
  83        returned and pool_error(3POOL) returns the pool-specific error value.
  84 
  85 
  86        Upon successful completion, pool_resource_destroy() returns 0.
  87        Otherwise, -1 is returned and pool_error() returns the pool-specific
  88        error value.
  89 
  90 
  91        Upon successful completion, pool_resource_info() returns a string
  92        describing the given resource (and optionally its components).
  93        Otherwise, NULL is returned and pool_error() returns the pool-specific
  94        error value.
  95 
  96 
  97        Upon successful completion, pool_query_resource_components() returns a
  98        null-terminated array of pool_component_t * that match the provided
  99        null-terminated property list and are contained in the given resource.
 100        Otherwise, NULL is returned and pool_error() returns the pool-specific
 101        error value.
 102 
 103 
 104        Upon successful completion, pool_resource_transfer() and
 105        pool_resource_xtransfer() return 0. Otherwise -1 is returned and
 106        pool_error() returns the pool-specific error value.
 107 
 108 ERRORS
 109        The pool_resource_create() function will fail if:
 110 
 111        POE_BADPARAM
 112                            The supplied configuration's status is not
 113                            POF_VALID or name is in use for this resource type.
 114 
 115 
 116        POE_INVALID_CONF
 117                            The resource element could not be created because
 118                            the configuration would be invalid.
 119 
 120 
 121        POE_PUTPROP
 122                            One of the supplied properties could not be set.
 123 
 124 
 125        POE_SYSTEM
 126                             A system error has occurred. Check the system
 127                            error code for more details.
 128 
 129 
 130 
 131        The pool_resource_destroy() function will fail if:
 132 
 133        POE_BADPARAM
 134                        The supplied configuration's status is not POF_VALID.
 135 
 136 
 137 
 138        The pool_resource_info() function will fail if:
 139 
 140        POE_BADPARAM
 141                            The supplied configuration's status is not
 142                            POF_VALID or the flags parameter is neither 0 nor
 143                            1.
 144 
 145 
 146        POE_INVALID_CONF
 147                            The configuration is invalid.
 148 
 149 
 150        POE_SYSTEM
 151                            A system error has occurred. Check the system error
 152                            code for more details.
 153 
 154 
 155 
 156        The pool_query_resource_components() function will fail if:
 157 
 158        POE_BADPARAM
 159                            The supplied configuration's status is not
 160                            POF_VALID.
 161 
 162 
 163        POE_INVALID_CONF
 164                            The configuration is invalid.
 165 
 166 
 167        POE_SYSTEM
 168                            A system error has occurred. Check the system error
 169                            code for more details.
 170 
 171 
 172 
 173        The pool_resource_transfer() function will fail if:
 174 
 175        POE_BADPARAM
 176                        The supplied configuration's status is not POF_VALID,
 177                        the two resources are not of the same type, or the
 178                        transfer would cause either of the resources to exceed
 179                        their min and max properties.
 180 
 181 
 182        POE_SYSTEM
 183                        A system error has occurred. Check the system error
 184                        code for more details.
 185 
 186 
 187 
 188        The pool_resource_xtransfer() function will fail if:
 189 
 190        POE_BADPARAM
 191                            The supplied configuration's status is not
 192                            POF_VALID, the two resources are not of the same
 193                            type, or the supplied resources do not belong to
 194                            the source.
 195 
 196 
 197        POE_INVALID_CONF
 198                            The transfer operation failed and the configuration
 199                            may be invalid.
 200 
 201 
 202        POE_SYSTEM
 203                            A system error has occurred. Check the system error
 204                            code for more details.
 205 
 206 
 207 EXAMPLES
 208        Example 1 Create a new resource of type pset named foo.
 209 
 210          #include <pool.h>
 211          #include <stdio.h>
 212 
 213          ...
 214 
 215          pool_conf_t *conf;
 216          pool_resource_t *resource;
 217          ...
 218 
 219          if ((resource = pool_resource_create(conf, "pset",
 220              "foo")) == NULL) {
 221              (void) fprintf(stderr, "Cannot create resource\B{}n");
 222              ...
 223          }
 224 
 225 
 226 ATTRIBUTES
 227        See attributes(5) for descriptions of the following attributes:
 228 
 229 
 230 
 231 
 232        +--------------------+-----------------+
 233        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 234        +--------------------+-----------------+
 235        |CSI                 | Enabled         |
 236        +--------------------+-----------------+
 237        |Interface Stability | Unstable        |
 238        +--------------------+-----------------+
 239        |MT-Level            | Safe            |
 240        +--------------------+-----------------+
 241 
 242 SEE ALSO
 243        libpool(3LIB), pool_error(3POOL), attributes(5)
 244 
 245 
 246 
 247                                January 15, 2020    POOL_RESOURCE_CREATE(3POOL)