'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH scf_scope_create 3SCF "9 Sep 2004" "SunOS 5.11" "Service Configuration Facility Library Functions"
.SH NAME
scf_scope_create, scf_scope_handle, scf_scope_destroy, scf_scope_get_name,
scf_handle_get_scope \- create and manipulate scope handles in the Service
Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <libscf.h>

\fBscf_scope_t *\fR\fBscf_scope_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_scope_handle\fR(\fBscf_scope_t *\fR\fIsc\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_scope_destroy\fR(\fBscf_scope_t *\fR\fIsc\fR);
.fi

.LP
.nf
\fBssize_t\fR  \fBscf_scope_get_name\fR(\fBscf_scope_t *\fR\fIsc\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_handle_get_scope\fR(\fBscf_handle_t *\fR\fIhandle\fR, \fBconst char *\fR\fIname\fR,
     \fBscf_scope_t *\fR\fIout\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Scopes are the top level of the Service Configuration Facility's repository
tree. The children of a scope are services (see \fBscf_service_create\fR(3SCF))
and can be walked using \fBscf_iter_scope_services\fR(3SCF).
.sp
.LP
There is a distinguished scope with the name \fBSCF_SCOPE_LOCAL\fR that is the
root for all available services on the local machine. In the current
implementation, there are no other scopes.
.sp
.LP
An \fBscf_scope_t\fR is an opaque handle that can be set to a single scope at
any given time. The \fBscf_scope_create()\fR function allocates a new
\fBscf_scope_t\fR bound to \fIhandle\fR. The \fBscf_scope_destroy()\fR function
destroys and frees \fIsc\fR.
.sp
.LP
The \fBscf_scope_handle()\fR function retrieves the handle to which \fIsc\fR is
bound.
.sp
.LP
The \fBscf_scope_get_name()\fR function retrieves the name of the scope to
which \fIsc\fR is set.
.sp
.LP
The \fBscf_handle_get_scope()\fR function sets \fIout\fR to the scope specified
by \fIname\fR for the repository handle specified by \fIhandle\fR. The
\fBscf_iter_handle_scopes\fR(3SCF) and \fBscf_iter_next_scope\fR(3SCF) calls
can be used to iterate through all available scopes.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_scope_create()\fR returns a new
\fBscf_scope_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_scope_handle()\fR returns the handle to
which \fIsc\fR is bound. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_scope_get_name()\fR returns the length of
the string written, not including the terminating null byte.  Otherwise, it
returns -1.
.sp
.LP
Upon successful completion, \fBscf_handle_get_scope()\fR returns 0. Otherwise,
it returns -1.
.SH ERRORS
.sp
.LP
The \fBscf_scope_create()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
.rt  
The value of the \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.RS 30n
.rt  
There is not enough memory to allocate an \fBscf_scope_t\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 30n
.rt  
The server does not have adequate resources for a new scope handle.
.RE

.sp
.LP
The \fBscf_scope_handle()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.RS 30n
.rt  
The handle associated with \fIsc\fR has been destroyed.
.RE

.sp
.LP
The \fBscf_scope_get_name()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The scope is not set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.LP
The \fBscf_handle_get_scope()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
No scope named name was found.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIname\fR argument is not a valid scope name.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The value of the \fIout\fR argument is not derived from handle.
.RE

.sp
.LP
The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityEvolving
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_handle_decode_fmri\fR(3SCF),
\fBscf_iter_handle_scopes\fR(3SCF), \fBscf_iter_next_scope\fR(3SCF),
\fBscf_iter_scope_services\fR(3SCF), \fBscf_scope_to_fmri\fR(3SCF),
\fBscf_service_create\fR(3SCF), \fBattributes\fR(5)