1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH POOL_GET_BINDING 3POOL "January 18, 2020"
   7 .SH NAME
   8 pool_get_binding, pool_set_binding, pool_get_resource_binding \- set and query
   9 process to resource pool bindings
  10 .SH SYNOPSIS
  11 .nf
  12 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
  13 #include <pool.h>
  14 
  15 \fBchar *\fR\fBpool_get_binding\fR(\fBpid_t\fR \fIpid\fR);
  16 .fi
  17 
  18 .LP
  19 .nf
  20 \fBint\fR \fBpool_set_binding\fR(\fBconst char *\fR\fIpool\fR, \fBidtype_t\fR \fIidtype\fR,
  21      \fBid_t\fR \fIid\fR);
  22 .fi
  23 
  24 .LP
  25 .nf
  26 \fBchar *\fR\fBpool_get_resource_binding\fR(\fBconst char *\fR\fItype\fR, \fBpid_t\fR \fIpid\fR);
  27 .fi
  28 
  29 .SH DESCRIPTION
  30 The \fBpool_get_binding()\fR function returns the name of the pool on the
  31 running system that contains the set of resources to which the given process is
  32 bound. If no such pool exists on the system or the search returns more than one
  33 pool (since the set of resources is referred to by more than one pool),
  34 \fINULL\fR is  returned and the pool error value is set to
  35 \fBPOE_INVALID_SEARCH\fR.
  36 .sp
  37 .LP
  38 It is possible that one of the resources to which the given process is bound is
  39 not associated with a pool. This could occur if a processor set was created
  40 with one of the \fBpset_()\fR functions and the process was then bound to that
  41 set. It could also occur if the process was bound to a resource set not
  42 currently associated with a pool, since resources can exist that are not
  43 associated with a pool.
  44 .sp
  45 .LP
  46 The \fBpool_set_binding()\fR function binds the processes matching \fIidtype\fR
  47 and \fIid\fR to the resources associated with \fIpool\fR on the running system.
  48 This function requires the privilege required by the underlying resource types
  49 referenced by the pool; generally, this requirement is equivalent to requiring
  50 superuser privilege.
  51 .sp
  52 .LP
  53 The \fIidtype\fR parameter can be one of the following types:
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBP_PID\fR\fR
  58 .ad
  59 .RS 12n
  60 The \fIid\fR parameter is a pid.
  61 .RE
  62 
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBP_TASKID\fR\fR
  67 .ad
  68 .RS 12n
  69 The \fIid\fR parameter is a taskid.
  70 .RE
  71 
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBP_PROJID\fR\fR
  76 .ad
  77 .RS 12n
  78 The \fIid\fR parameter is a project ID. All currently running processes
  79 belonging to the given project will be bound to the pool's resources.
  80 .RE
  81 
  82 .sp
  83 .LP
  84 The \fBpool_get_resource_binding()\fR function returns the name of the resource
  85 of the supplied type to which the supplied process is bound.
  86 .sp
  87 .LP
  88 The application must explicitly free the memory allocated for the return values
  89 for \fBpool_get_binding()\fR and \fBpool_get_resource_binding()\fR.
  90 .SH RETURN VALUES
  91 Upon successful completion, \fBpool_get_binding()\fR returns the name of the
  92 pool to which the process is bound. Otherwise it returns \fINULL\fR and
  93 \fBpool_error\fR(3POOL) returns the pool-specific error value.
  94 .sp
  95 .LP
  96 Upon successful completion, \fBpool_set_binding()\fR returns \fBPO_SUCCESS\fR.
  97 Otherwise, it returns \fBPO_FAIL\fR and \fBpool_error()\fR returns the
  98 pool-specific error value.
  99 .sp
 100 .LP
 101 Upon successful completion, \fBpool_get_resource_binding()\fR returns the name
 102 of the resource of the specified type to which the process is bound. Otherwise
 103 it returns \fINULL\fR and \fBpool_error()\fR returns the pool-specific error
 104 value.
 105 .SH ERRORS
 106 The \fBpool_get_binding()\fR function will fail if:
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBPOE_INVALID_CONF\fR\fR
 111 .ad
 112 .RS 22n
 113 The configuration is invalid.
 114 .RE
 115 
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBPOE_INVALID_SEARCH\fR\fR
 120 .ad
 121 .RS 22n
 122 It is not possible to determine the binding for this target due to the
 123 overlapping nature of the pools configured for this system, or the pool could
 124 not be located.
 125 .RE
 126 
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBPOE_SYSTEM\fR\fR
 131 .ad
 132 .RS 22n
 133 A system error has occurred. Check the system error code for more details.
 134 .RE
 135 
 136 .sp
 137 .LP
 138 The \fBpool_set_binding()\fR function will fail if:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBPOE_INVALID_SEARCH\fR\fR
 143 .ad
 144 .RS 22n
 145 The pool could not be found.
 146 .RE
 147 
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBPOE_INVALID_CONF\fR\fR
 152 .ad
 153 .RS 22n
 154 The configuration is invalid.
 155 .RE
 156 
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBPOE_SYSTEM\fR\fR
 161 .ad
 162 .RS 22n
 163 A system error has occurred. Check the system error code for more details.
 164 .RE
 165 
 166 .sp
 167 .LP
 168 The \fBpool_get_resource_binding()\fR function will fail if:
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBPOE_INVALID_CONF\fR\fR
 173 .ad
 174 .RS 22n
 175 The configuration is invalid.
 176 .RE
 177 
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBPOE_INVALID_SEARCH\fR\fR
 182 .ad
 183 .RS 22n
 184 The target is not bound to a resource of the specified type.
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBPOE_SYSTEM\fR\fR
 191 .ad
 192 .RS 22n
 193 A system error has occurred. Check the system error code for more details.
 194 .RE
 195 
 196 .SH EXAMPLES
 197 \fBExample 1 \fRBind the current process to the pool named "target".
 198 .sp
 199 .in +2
 200 .nf
 201 #include <sys/types.h>
 202 #include <pool.h>
 203 #include <unistd.h>
 204 
 205 \&...
 206 
 207 id_t pid = getpid();
 208 
 209 \&...
 210 
 211 if (pool_set_binding("target", P_PID, pid) == PO_FAIL) \{
 212         (void) fprintf(stderr, "pool binding failed (%d)\\n",
 213                  pool_error());
 214 \}
 215 .fi
 216 .in -2
 217 
 218 .SH ATTRIBUTES
 219 See \fBattributes\fR(5) for descriptions of the following attributes:
 220 .sp
 221 
 222 .sp
 223 .TS
 224 box;
 225 c | c
 226 l | l .
 227 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 228 _
 229 CSI     Enabled
 230 _
 231 Interface Stability     Unstable
 232 _
 233 MT-Level        Safe
 234 .TE
 235 
 236 .SH SEE ALSO
 237 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)