Tribblix: manual page: scf_tmpl_pg

SCF_TMPL_PG_NAME(3SCF) Service Configuration Facility Library Functions

NAME

scf_tmpl_pg_name, scf_tmpl_pg_type, scf_tmpl_pg_target,
scf_tmpl_pg_required, scf_tmpl_pg_common_name,
scf_tmpl_pg_description - retrieve the metadata about a specific
property group

SYNOPSIS

cc [ flag... ] file... -lscf [ library... ]
#include <libscf.h>

ssize_t scf_tmpl_pg_name(const scf_pg_tmpl_t *pg_tmpl,
char **out);

ssize_t scf_tmpl_pg_type(const scf_pg_tmpl_t *pg_tmpl,
char **out);

ssize_t scf_tmpl_pg_target(const scf_pg_tmpl_t *pg_tmpl,
char **out);

int scf_tmpl_pg_required(const scf_pg_tmpl_t *pg_tmpl,
uint8_t *out)

ssize_t scf_tmpl_pg_common_name(const scf_pg_tmpl_t *pg_tmpl,
const char * locale, char **out);

ssize_t scf_tmpl_pg_description(const scf_pg_tmpl_t *pg_tmpl,
const char * locale, char **out);

DESCRIPTION

These functions retrieve the metadata about a specific property
group. They require that the template for the property group has
already been located by one of the scf_tmpl_pg_create(3SCF) suite of
functions.

The scf_tmpl_pg_name() function retrieves the name of the property
group template and place it in *out. If the property group name is
implicitly wildcarded (see smf_template(7)) in the template, this
function will return a string containing SCF_TMPL_WILDCARD ("*") in
*out. The caller is responsible for freeing the *out buffer on
success.

The scf_tmpl_pg_type() function will retrieve the type of the
property group template and place it in *out. If the property group
type is implicitly wildcarded (see smf_template(7)) in the template,
this function will return a string containing SCF_TMPL_WILDCARD ("*")
in *out. The caller is responsible for freeing the *out buffer on
success.

The scf_tmpl_pg_target() function will retrieve the target of the
property group template and place it in *out. The caller is
responsible for freeing the *out buffer on success.

The scf_tmpl_pg_required() function will determine whether the
property group is required and place the result of that check in
*out. If required is unset, out will be the default value of 0. If
the property is explicitly set to required, out will be 1.

The scf_tmpl_pg_common_name() function will retrieve the property
group's localized common name as currently templated and place it in
*out. A locale (as described in setlocale(3C)) may be specified, or
if the supplied locale is NULL, the current locale will be used. If
a common_name in the specified locale is not found, the function will
also look for a common_name in the C locale. Some templates will not
specify the property group common name. The caller is responsible
for freeing the *out buffer on success.

The scf_tmpl_pg_description() function will retrieve the property
group's localized description as currently templated and place it in
*out. A locale (as described in setlocale(3C)) may be specified, or
if the supplied locale is NULL, the current locale will be used. If a
description in the specified locale is not found, the function will
also look for a description in the C locale. Some templates will not
specify the property group description. The caller is responsible
for freeing the *out buffer on success.

RETURN VALUES

Upon successful completion, scf_tmpl_pg_name(),
scf_tmpl_pg_common_name(), scf_tmpl_pg_description(),
scf_tmpl_pg_target(), and scf_tmpl_pg_type() return the length of the
string written, not including the terminating null byte. Otherwise,
they return -1.

Upon successful completion, scf_tmpl_pg_required() returns 0.
Otherwise, it returns -1.

ERRORS

The scf_tmpl_pg_name(), scf_tmpl_pg_common_name(),
scf_tmpl_pg_description(), scf_tmpl_pg_required(),
scf_tmpl_pg_target(), and scf_tmpl_pg_type() functions will fail if:

SCF_ERROR_BACKEND_ACCESS

The storage mechanism that the repository server (svc.configd(8))
chose for the operation denied access.

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.

SCF_ERROR_DELETED

The template property group has been deleted.

SCF_ERROR_HANDLE_DESTROYED

The handle passed in has been destroyed.

SCF_ERROR_INTERNAL

An internal error occurred.

SCF_ERROR_NO_MEMORY

There is not enough memory to populate the scf_pg_tmpl_t.

SCF_ERROR_NO_RESOURCES

The server does not have adequate resources to complete the
request.

SCF_ERROR_NOT_BOUND

The handle is not currently bound.

SCF_ERROR_PERMISSION_DENIED

The template could not be read due to access restrictions.

SCF_ERROR_TEMPLATE_INVALID

The template data is invalid.

The scf_tmpl_pg_common_name() and scf_tmpl_pg_description() functions
will fail if:

SCF_ERROR_NOT_FOUND
The property does not exist or exists
and has no value.

SCF_ERROR_INVALID_ARGUMENT
The locale string is too long.