Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
Copyright 2020 Joyent, Inc.
Copyright 2026 Oxide Computer Company
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]
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);
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_get_state() and smf_get_state_by_instance() return an allocated string. Otherwise, they return NULL.
The memory allocation failed.
The instance FMRI or flags argument is invalid.
The FMRI is valid but there is no matching instance found.
The connection to repository was broken.
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).
The repository's backend refused access.
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.
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Committed |
| MT-Level Safe |