SMF_ENABLE_INSTANCE(3SCF) Service Configuration Facility Library Functions
smf_enable_instance, smf_disable_instance,
smf_disable_instance_with_comment, smf_refresh_instance,
smf_restart_instance, smf_maintain_instance, smf_degrade_instance,
smf_restore_instance, smf_get_state - administrative interface to the
Service Configuration Facility
cc [ flag... ] file... -lscf [ library... ]
#include <libscf.h>
int smf_enable_instance(const char *instance, int flags);
int smf_enable_instance_by_instance(scf_instance_t *inst,
int flags, const char *comment);
int smf_disable_instance(const char *instance, int flags);
int smf_disable_instance_with_comment(const char *instance,
int flags, const char *comment);
int smf_disable_instance_by_instance(scf_instance_t *inst,
int flags, const char *comment);
int smf_refresh_instance(const char *instance);
int smf_refresh_instance_by_instance(scf_instance_t *inst);
int smf_refresh_all_instances(scf_service_t *service);
int smf_restart_instance(const char *instance);
int smf_restart_instance_by_instance(scf_instance_t *inst);
int smf_maintain_instance(const char *instance, int flags);
int smf_maintain_instance_by_instance(scf_instance_t *inst,
int flags);
int smf_degrade_instance(const char *instance, int flags);
int smf_degrade_instance_by_instance(scf_instance_t *inst,
int flags);
int smf_restore_instance(const char *instance);
int smf_restore_instance_by_instance(scf_instance_t *inst);
char *smf_get_state(const char *instance);
char *smf_get_state_by_instance(scf_instance_t *inst);
These functions provide administrative control over service
instances. Using these functions, an administrative tool can make a
request to enable, disable, refresh, or restart an instance. All
calls are asynchronous. They request an action, but do not wait to
see if the action succeeds or fails. The _by_instance variants
operate on an existing scf_instance_t * that was previously obtained
through something such as scf_handle_decode_fmri(3SCF).
The smf_enable_instance() function enables the service instance
specified by instance FMRI. If flags is SMF_TEMPORARY, the enabling
of the service instance is a temporary change, lasting only for the
lifetime of the current system instance. The flags argument is set to
0 if no flags are to be use. The smf_enable_instance_by_instance()
function has the same behavior as smf_enable_instance() except that
it operates on a service instance indicated by the inst
scf_instance_t * object rather than parsing a string FMRI. A comment
may be optionally passed for this. The default behavior here is to
pass NULL to indicate no comment (the behavior of
smf_enable_instance()).
The smf_disable_instance() function places the service instance
specified by instance FMRI in the disabled state and triggers the
stop method (see svc.startd(8)). If flags is SMF_TEMPORARY, the
disabling of the service instance is a temporary change, lasting only
for the lifetime of the current system instance. The flags argument
is set to 0 if no flags are to be use.
The smf_disable_instance_with_comment() function behaves the same as
smf_disable_instance(), except the given free-form comment is
recorded under the comment property, as reported by svcs(1). The
comment may be up to SCF_COMMENT_MAX_LENGTH characters including the
NUL terminator.
The smf_disable_instance_by_instance() function behaves similarly to
smf_disable_instance() and smf_disable_instance_with_comment() except
that it operates on an instance identified by inst rather than a
string FMRI. If comment is a non-NULL value then a comment will be
set like smf_disable_instance_with_comment(). Otherwise, no comment
will be set like smf_disable_instance().
The smf_refresh_instance() function causes the service instance
specified by instance FMRI to re-read its configuration information.
The smf_refresh_instance_by_instance() function similarly refreshes
an instance that is instead identified by inst and not a string FMRI.
The smf_refresh_all_instances() iterates over every instance in the
service service and causes it to be refreshed as though
smf_refresh_instance_by_instance() was called upon it. If an error
occurs, the refresh method may not be called on some instances.
The smf_restart_instance() function restarts the service instance
specified by instance FMRI. The smf_restart_instance_by_instance()
function similarly restarts an instance that is instead identified by
inst and not a string FMRI.
The smf_maintain_instance() function moves the service instance
specified by instance into the maintenance state. If flags is
SMF_IMMEDIATE, the instance is moved into maintenance state
immediately, killing any running methods. If flags is SMF_TEMPORARY,
the change to maintenance state is a temporary change, lasting only
for the lifetime of the current system instance. The flags argument
is set to 0 if no flags are to be use. The
smf_maintain_instance_by_instance() works the same as
smf_maintain_instance() but instead identifies a service by inst and
not a string FMRI.
The smf_degrade_instance() function moves an online service instance
into the degraded state. This function operates only on instances in
the online state. The flags argument is set to 0 if no flags are to
be use. The only available flag is SMF_IMMEDIATE, which causes the
instance to be moved into the degraded state immediately. The
smf_degrade_instance_by_instance() works the same as
smf_degrade_instance() but instead identifies a service by inst and
not a string FMRI.
The smf_restore_instance() function brings an instance currently in
the maintenance to the uninitialized state, so that it can be brought
back online. For a service in the degraded state,
smf_restore_instance() brings the specified instance back to the
online state. The smf_restore_instance_by_instance() works the same
as smf_restore_instance() but instead identifies a service by inst
and not a string FMRI.
The smf_get_state() and smf_get_state_by_instance() function returns
a pointer to a string containing the name of the instance's current
state. The user is responsible for freeing this string. Possible
state strings are defined as the following:
#define SCF_STATE_STRING_UNINIT ((const char *)"uninitialized")
#define SCF_STATE_STRING_MAINT ((const char *)"maintenance")
#define SCF_STATE_STRING_OFFLINE ((const char *)"offline")
#define SCF_STATE_STRING_DISABLED ((const char *)"disabled")
#define SCF_STATE_STRING_ONLINE ((const char *)"online")
#define SCF_STATE_STRING_DEGRADED ((const char *)"degraded")
Upon successful completion, smf_enable_instance(),
smf_enable_instance_by_instance(), smf_disable_instance(),
smf_disable_instance_with_comment(),
smf_disable_instance_by_instance(), smf_refresh_instance(),
smf_refresh_instance_by_instance(), smf_restart_instance(),
smf_refresh_all_instances(), smf_restart_instance_by_instance(),
smf_maintain_instance(), smf_maintain_instance_by_instance(),
smf_degrade_instance(), smf_degrade_instance_by_instance(),
smf_restore_instance(), and smf_restore_instance_by_instance() return
0. Otherwise, they return -1.
Upon successful completion, smf_get_state() and
smf_get_state_by_instance() return an allocated string. Otherwise,
they return NULL.
These functions will fail if:
SCF_ERROR_NO_MEMORY
The memory allocation failed.
SCF_ERROR_INVALID_ARGUMENT
The instance FMRI or flags argument is invalid.
SCF_ERROR_NOT_FOUND
The FMRI is valid but there is no matching instance found.
SCF_ERROR_CONNECTION_BROKEN
The connection to repository was broken.
SCF_ERROR_NO_RESOURCES
The server has insufficient resources.
The smf_maintain_instance(), smf_maintain_instance_by_instance(),
smf_refresh_instance(), smf_refresh_instance_by_instance(),
smf_refresh_all_instances(), smf_restart_instance(),
smf_restart_instance_by_instance(), smf_degrade_instance(),
smf_degrade_instance_by_instance(), smf_restore_instance(), and
smf_restore_instance_by_instance() functions will fail if:
SCF_ERROR_PERMISSION_DENIED
User does not have proper authorizations. See smf_security(7).
SCF_ERROR_BACKEND_ACCESS
The repository's backend refused access.
SCF_ERROR_BACKEND_READONLY
The repository's backend is read-only.
The smf_restore_instance(), smf_restore_instance_by_instance(),
smf_degrade_instance() and smf_degrade_instance_by_instance()
functions will fail if:
SCF_ERROR_CONSTRAINT_VIOLATED
The function is called on an instance in an inappropriate state.
The scf_error(3SCF) function can be used to retrieve the error value.
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
svcs(1), libscf(3LIB), scf_error(3SCF), attributes(7),
smf_security(7), svc.startd(8)
April 17, 2026 SMF_ENABLE_INSTANCE(3SCF)
NAME
smf_enable_instance, smf_disable_instance,
smf_disable_instance_with_comment, smf_refresh_instance,
smf_restart_instance, smf_maintain_instance, smf_degrade_instance,
smf_restore_instance, smf_get_state - administrative interface to the
Service Configuration Facility
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include <libscf.h>
int smf_enable_instance(const char *instance, int flags);
int smf_enable_instance_by_instance(scf_instance_t *inst,
int flags, const char *comment);
int smf_disable_instance(const char *instance, int flags);
int smf_disable_instance_with_comment(const char *instance,
int flags, const char *comment);
int smf_disable_instance_by_instance(scf_instance_t *inst,
int flags, const char *comment);
int smf_refresh_instance(const char *instance);
int smf_refresh_instance_by_instance(scf_instance_t *inst);
int smf_refresh_all_instances(scf_service_t *service);
int smf_restart_instance(const char *instance);
int smf_restart_instance_by_instance(scf_instance_t *inst);
int smf_maintain_instance(const char *instance, int flags);
int smf_maintain_instance_by_instance(scf_instance_t *inst,
int flags);
int smf_degrade_instance(const char *instance, int flags);
int smf_degrade_instance_by_instance(scf_instance_t *inst,
int flags);
int smf_restore_instance(const char *instance);
int smf_restore_instance_by_instance(scf_instance_t *inst);
char *smf_get_state(const char *instance);
char *smf_get_state_by_instance(scf_instance_t *inst);
DESCRIPTION
These functions provide administrative control over service
instances. Using these functions, an administrative tool can make a
request to enable, disable, refresh, or restart an instance. All
calls are asynchronous. They request an action, but do not wait to
see if the action succeeds or fails. The _by_instance variants
operate on an existing scf_instance_t * that was previously obtained
through something such as scf_handle_decode_fmri(3SCF).
The smf_enable_instance() function enables the service instance
specified by instance FMRI. If flags is SMF_TEMPORARY, the enabling
of the service instance is a temporary change, lasting only for the
lifetime of the current system instance. The flags argument is set to
0 if no flags are to be use. The smf_enable_instance_by_instance()
function has the same behavior as smf_enable_instance() except that
it operates on a service instance indicated by the inst
scf_instance_t * object rather than parsing a string FMRI. A comment
may be optionally passed for this. The default behavior here is to
pass NULL to indicate no comment (the behavior of
smf_enable_instance()).
The smf_disable_instance() function places the service instance
specified by instance FMRI in the disabled state and triggers the
stop method (see svc.startd(8)). If flags is SMF_TEMPORARY, the
disabling of the service instance is a temporary change, lasting only
for the lifetime of the current system instance. The flags argument
is set to 0 if no flags are to be use.
The smf_disable_instance_with_comment() function behaves the same as
smf_disable_instance(), except the given free-form comment is
recorded under the comment property, as reported by svcs(1). The
comment may be up to SCF_COMMENT_MAX_LENGTH characters including the
NUL terminator.
The smf_disable_instance_by_instance() function behaves similarly to
smf_disable_instance() and smf_disable_instance_with_comment() except
that it operates on an instance identified by inst rather than a
string FMRI. If comment is a non-NULL value then a comment will be
set like smf_disable_instance_with_comment(). Otherwise, no comment
will be set like smf_disable_instance().
The smf_refresh_instance() function causes the service instance
specified by instance FMRI to re-read its configuration information.
The smf_refresh_instance_by_instance() function similarly refreshes
an instance that is instead identified by inst and not a string FMRI.
The smf_refresh_all_instances() iterates over every instance in the
service service and causes it to be refreshed as though
smf_refresh_instance_by_instance() was called upon it. If an error
occurs, the refresh method may not be called on some instances.
The smf_restart_instance() function restarts the service instance
specified by instance FMRI. The smf_restart_instance_by_instance()
function similarly restarts an instance that is instead identified by
inst and not a string FMRI.
The smf_maintain_instance() function moves the service instance
specified by instance into the maintenance state. If flags is
SMF_IMMEDIATE, the instance is moved into maintenance state
immediately, killing any running methods. If flags is SMF_TEMPORARY,
the change to maintenance state is a temporary change, lasting only
for the lifetime of the current system instance. The flags argument
is set to 0 if no flags are to be use. The
smf_maintain_instance_by_instance() works the same as
smf_maintain_instance() but instead identifies a service by inst and
not a string FMRI.
The smf_degrade_instance() function moves an online service instance
into the degraded state. This function operates only on instances in
the online state. The flags argument is set to 0 if no flags are to
be use. The only available flag is SMF_IMMEDIATE, which causes the
instance to be moved into the degraded state immediately. The
smf_degrade_instance_by_instance() works the same as
smf_degrade_instance() but instead identifies a service by inst and
not a string FMRI.
The smf_restore_instance() function brings an instance currently in
the maintenance to the uninitialized state, so that it can be brought
back online. For a service in the degraded state,
smf_restore_instance() brings the specified instance back to the
online state. The smf_restore_instance_by_instance() works the same
as smf_restore_instance() but instead identifies a service by inst
and not a string FMRI.
The smf_get_state() and smf_get_state_by_instance() function returns
a pointer to a string containing the name of the instance's current
state. The user is responsible for freeing this string. Possible
state strings are defined as the following:
#define SCF_STATE_STRING_UNINIT ((const char *)"uninitialized")
#define SCF_STATE_STRING_MAINT ((const char *)"maintenance")
#define SCF_STATE_STRING_OFFLINE ((const char *)"offline")
#define SCF_STATE_STRING_DISABLED ((const char *)"disabled")
#define SCF_STATE_STRING_ONLINE ((const char *)"online")
#define SCF_STATE_STRING_DEGRADED ((const char *)"degraded")
RETURN VALUES
Upon successful completion, smf_enable_instance(),
smf_enable_instance_by_instance(), smf_disable_instance(),
smf_disable_instance_with_comment(),
smf_disable_instance_by_instance(), smf_refresh_instance(),
smf_refresh_instance_by_instance(), smf_restart_instance(),
smf_refresh_all_instances(), smf_restart_instance_by_instance(),
smf_maintain_instance(), smf_maintain_instance_by_instance(),
smf_degrade_instance(), smf_degrade_instance_by_instance(),
smf_restore_instance(), and smf_restore_instance_by_instance() return
0. Otherwise, they return -1.
Upon successful completion, smf_get_state() and
smf_get_state_by_instance() return an allocated string. Otherwise,
they return NULL.
ERRORS
These functions will fail if:
SCF_ERROR_NO_MEMORY
The memory allocation failed.
SCF_ERROR_INVALID_ARGUMENT
The instance FMRI or flags argument is invalid.
SCF_ERROR_NOT_FOUND
The FMRI is valid but there is no matching instance found.
SCF_ERROR_CONNECTION_BROKEN
The connection to repository was broken.
SCF_ERROR_NO_RESOURCES
The server has insufficient resources.
The smf_maintain_instance(), smf_maintain_instance_by_instance(),
smf_refresh_instance(), smf_refresh_instance_by_instance(),
smf_refresh_all_instances(), smf_restart_instance(),
smf_restart_instance_by_instance(), smf_degrade_instance(),
smf_degrade_instance_by_instance(), smf_restore_instance(), and
smf_restore_instance_by_instance() functions will fail if:
SCF_ERROR_PERMISSION_DENIED
User does not have proper authorizations. See smf_security(7).
SCF_ERROR_BACKEND_ACCESS
The repository's backend refused access.
SCF_ERROR_BACKEND_READONLY
The repository's backend is read-only.
The smf_restore_instance(), smf_restore_instance_by_instance(),
smf_degrade_instance() and smf_degrade_instance_by_instance()
functions will fail if:
SCF_ERROR_CONSTRAINT_VIOLATED
The function is called on an instance in an inappropriate state.
The scf_error(3SCF) function can be used to retrieve the error value.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
svcs(1), libscf(3LIB), scf_error(3SCF), attributes(7),
smf_security(7), svc.startd(8)
April 17, 2026 SMF_ENABLE_INSTANCE(3SCF)