'\" te
.\" Copyright (c) 2007, 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_PROPERTY_CREATE 3SCF "Oct 28, 2008"
.SH NAME
scf_property_create, scf_property_handle, scf_property_destroy,
scf_property_get_name, scf_property_type, scf_property_is_type,
scf_type_to_string, scf_string_to_type, scf_property_get_value,
scf_pg_get_property \- create and manipulate property handles in the Service
Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBscf_property_t *\fR\fBscf_property_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_property_handle\fR(\fBscf_property_t *\fR\fIprop\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_property_destroy\fR(\fBscf_property_t *\fR\fIprop\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_property_get_name\fR(\fBconst scf_property_t *\fR\fIprop\fR,
     \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_property_type\fR(\fBconst scf_property_t *\fR\fIprop\fR,
     \fBscf_type_t *\fR\fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_property_is_type\fR(\fBconst scf_property_t *\fR\fIprop\fR,
     \fBscf_type_t\fR \fItype\fR);
.fi

.LP
.nf
\fBconst char *\fR\fBscf_type_to_string\fR(\fBscf_type_t\fR \fItype\fR);
.fi

.LP
.nf
\fBscf_type_t\fR \fBscf_string_to_type\fR(\fBconst char *\fR\fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_property_get_value\fR(\fBconst scf_property_t *\fR\fIprop\fR,
     \fBscf_value_t *\fR\fIvalue\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_pg_get_property\fR(\fBconst scf_property_t *\fR\fIpg\fR,
     \fBconst char *\fR\fIname\fR, \fBscf_property_t *\fR\fIprop\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Properties are named sets of values of one type. They are grouped into property
groups (see \fBscf_pg_create\fR(3SCF)) that are updated atomically using
transactions (see \fBscf_transaction_create\fR(3SCF)).
.sp
.LP
An \fBscf_property_t\fR is an opaque handle that can be set to a single
property at any given time. When set, it inherits the point-in-time from the
source \fBscf_propertygroup_t\fR and does not change until reset.
.sp
.LP
The \fBscf_property_create()\fR function allocates and initializes a new
\fBscf_property_t\fR bound to \fIhandle\fR. The \fBscf_property_destroy()\fR
function destroys and frees \fIprop\fR.
.sp
.LP
The \fBscf_property_handle()\fR function returns the handle to which \fIprop\fR
is bound.
.sp
.LP
The \fBscf_property_type()\fR function retrieves the type of the property to
which \fIprop\fR is set.
.sp
.LP
The \fBscf_property_is_type()\fR function determines if the property is
compatible with type. See \fBscf_value_create\fR(3SCF).
.sp
.LP
The \fBscf_type_to_string()\fR function returns the string name of the type
supplied. If the type is invalid or unknown, it returns "unknown".
.sp
.LP
The \fBscf_string_to_type()\fR function returns the \fBscf_type_t\fR definition
of the string supplied. If the string does not translate to an existing type,
it returns \fBSCF_TYPE_INVALID\fR.
.sp
.LP
The \fBscf_property_get_value()\fR function retrieves the single value that the
property to which \fIprop\fR is set contains. If the property has more than one
value, the \fIvalue\fR argument is set to one of the values. To retrieve all
values associated with a property, see \fBscf_iter_property_values\fR(3SCF).
.sp
.LP
The \fBscf_pg_get_property()\fR function sets \fIprop\fR to the property
specified by \fIname\fR in the property group specified by \fIpg\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_property_create()\fR returns a new
\fBscf_property_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion,  \fBscf_property_get_name()\fR function returns the
length of the string written, not including the terminating null byte.
Otherwise, it returns -1.
.sp
.LP
Upon successful completion, \fBscf_pg_get_property()\fR,
\fBscf_property_type()\fR, \fBscf_property_is_type()\fR, and
\fBscf_pg_get_value()\fR functions return 0. Otherwise, they return -1.
.sp
.LP
Upon successful completion, \fBscf_type_to_string()\fR returns a string of the
type supplied.
.sp
.LP
Upon successful completion, \fBscf_string_to_type()\fR returns the
\fBscf_type_t\fR definition of the string supplied
.SH ERRORS
.sp
.LP
The \fBscf_property_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The value of the \fIhandle\fR argument is \fINULL\fR.
.RE

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

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

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

.sp
.LP
The \fBscf_property_get_name()\fR, \fBscf_property_type()\fR,
\fBscf_property_is_type()\fR, and \fBscf_property_get_value()\fR functions will
fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The property's parent property group or an ancestor has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle was never bound or has been unbound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The property is not set.
.RE

.sp
.LP
The \fBscf_property_is_type()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The \fItype\fR argument is not a valid type.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
.ad
.RS 30n
The \fIprop\fR argument is not of a type compatible with \fItype\fR.
.RE

.sp
.LP
The \fBscf_pg_get_property()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The  storage  mechanism  that  the   repository server (\fBsvc.configd\fR(1M))
chose for the operation denied access.
.RE

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

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The property group or an ancestor has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The property group and property are not derived from the same handle.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The value of the \fIname\fR argument is not a valid property name.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have the resources to complete the request.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle was never bound or has been unbound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
The property specified by \fIname\fR was not found.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The property group specified by \fIpg\fR is not set.
.RE

.sp
.LP
The \fBscf_property_get_value()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
.ad
.sp .6
.RS 4n
The property has more than one value associated with it. The \fIvalue\fR
argument will be set to one of the values.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The property and value are derived from different handles.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
The property has no values associated with it. The \fIvalue\fR argument will be
reset.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The value could not be read due to access restrictions.
.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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_handle_decode_fmri\fR(3SCF),
\fBscf_iter_property_values\fR(3SCF), \fBscf_pg_create\fR(3SCF),
\fBscf_property_to_fmri\fR(3SCF), \fBscf_transaction_create\fR(3SCF),
\fBscf_value_create\fR(3SCF), \fBattributes\fR(5)