usr/src/man/man3scf/scf_scope_create.3scf

   1 '\" te
   2 .\" Copyright (c) 2004, 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 SCF_SCOPE_CREATE 3SCF "Sep 9, 2004"
   7 .SH NAME
   8 scf_scope_create, scf_scope_handle, scf_scope_destroy, scf_scope_get_name,
   9 scf_handle_get_scope \- create and manipulate scope handles in the Service
  10 Configuration Facility
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <libscf.h>
  16
  17 \fBscf_scope_t *\fR\fBscf_scope_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBscf_handle_t *\fR\fBscf_scope_handle\fR(\fBscf_scope_t *\fR\fIsc\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBscf_scope_destroy\fR(\fBscf_scope_t *\fR\fIsc\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBssize_t\fR  \fBscf_scope_get_name\fR(\fBscf_scope_t *\fR\fIsc\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBint\fR \fBscf_handle_get_scope\fR(\fBscf_handle_t *\fR\fIhandle\fR, \fBconst char *\fR\fIname\fR,
  38      \fBscf_scope_t *\fR\fIout\fR);
  39 .fi
  40
  41 .SH DESCRIPTION
  42 .sp
  43 .LP
  44 Scopes are the top level of the Service Configuration Facility's repository
  45 tree. The children of a scope are services (see \fBscf_service_create\fR(3SCF))
  46 and can be walked using \fBscf_iter_scope_services\fR(3SCF).
  47 .sp
  48 .LP
  49 There is a distinguished scope with the name \fBSCF_SCOPE_LOCAL\fR that is the
  50 root for all available services on the local machine. In the current
  51 implementation, there are no other scopes.
  52 .sp
  53 .LP
  54 An \fBscf_scope_t\fR is an opaque handle that can be set to a single scope at
  55 any given time. The \fBscf_scope_create()\fR function allocates a new
  56 \fBscf_scope_t\fR bound to \fIhandle\fR. The \fBscf_scope_destroy()\fR function
  57 destroys and frees \fIsc\fR.
  58 .sp
  59 .LP
  60 The \fBscf_scope_handle()\fR function retrieves the handle to which \fIsc\fR is
  61 bound.
  62 .sp
  63 .LP
  64 The \fBscf_scope_get_name()\fR function retrieves the name of the scope to
  65 which \fIsc\fR is set.
  66 .sp
  67 .LP
  68 The \fBscf_handle_get_scope()\fR function sets \fIout\fR to the scope specified
  69 by \fIname\fR for the repository handle specified by \fIhandle\fR. The
  70 \fBscf_iter_handle_scopes\fR(3SCF) and \fBscf_iter_next_scope\fR(3SCF) calls
  71 can be used to iterate through all available scopes.
  72 .SH RETURN VALUES
  73 .sp
  74 .LP
  75 Upon successful completion, \fBscf_scope_create()\fR returns a new
  76 \fBscf_scope_t\fR. Otherwise, it returns \fINULL\fR.
  77 .sp
  78 .LP
  79 Upon successful completion, \fBscf_scope_handle()\fR returns the handle to
  80 which \fIsc\fR is bound. Otherwise, it returns \fINULL\fR.
  81 .sp
  82 .LP
  83 Upon successful completion, \fBscf_scope_get_name()\fR returns the length of
  84 the string written, not including the terminating null byte.  Otherwise, it
  85 returns -1.
  86 .sp
  87 .LP
  88 Upon successful completion, \fBscf_handle_get_scope()\fR returns 0. Otherwise,
  89 it returns -1.
  90 .SH ERRORS
  91 .sp
  92 .LP
  93 The \fBscf_scope_create()\fR function will fail if:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
  98 .ad
  99 .RS 30n
 100 The value of the \fIhandle\fR argument is \fINULL\fR.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 107 .ad
 108 .RS 30n
 109 There is not enough memory to allocate an \fBscf_scope_t\fR.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 116 .ad
 117 .RS 30n
 118 The server does not have adequate resources for a new scope handle.
 119 .RE
 120
 121 .sp
 122 .LP
 123 The \fBscf_scope_handle()\fR function will fail if:
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 128 .ad
 129 .RS 30n
 130 The handle associated with \fIsc\fR has been destroyed.
 131 .RE
 132
 133 .sp
 134 .LP
 135 The \fBscf_scope_get_name()\fR function will fail if:
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 140 .ad
 141 .sp .6
 142 .RS 4n
 143 The scope is not set.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 150 .ad
 151 .sp .6
 152 .RS 4n
 153 The handle is not bound.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 160 .ad
 161 .sp .6
 162 .RS 4n
 163 The connection to the repository was lost.
 164 .RE
 165
 166 .sp
 167 .LP
 168 The \fBscf_handle_get_scope()\fR function will fail if:
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 173 .ad
 174 .sp .6
 175 .RS 4n
 176 No scope named name was found.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 183 .ad
 184 .sp .6
 185 .RS 4n
 186 The \fIname\fR argument is not a valid scope name.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 The handle is not bound.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 The connection to the repository was lost.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 213 .ad
 214 .sp .6
 215 .RS 4n
 216 The value of the \fIout\fR argument is not derived from handle.
 217 .RE
 218
 219 .sp
 220 .LP
 221 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 222 .SH ATTRIBUTES
 223 .sp
 224 .LP
 225 See \fBattributes\fR(5) for descriptions of the following attributes:
 226 .sp
 227
 228 .sp
 229 .TS
 230 box;
 231 c | c
 232 l | l .
 233 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 234 _
 235 Interface Stability     Evolving
 236 _
 237 MT-Level        Safe
 238 .TE
 239
 240 .SH SEE ALSO
 241 .sp
 242 .LP
 243 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_handle_decode_fmri\fR(3SCF),
 244 \fBscf_iter_handle_scopes\fR(3SCF), \fBscf_iter_next_scope\fR(3SCF),
 245 \fBscf_iter_scope_services\fR(3SCF), \fBscf_scope_to_fmri\fR(3SCF),
 246 \fBscf_service_create\fR(3SCF), \fBattributes\fR(5)