Print this page
12202 noise in example code in some section 3pool man pages
   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


 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)
   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


 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)