SMF_ENABLE_INSTANCE(3SCF) Service Configuration Facility Library Functions SMF_ENABLE_INSTANCE(3SCF)

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 OmniOS