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