'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.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 StabilityCommitted
_
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)