Service Configuration Facility Library Functions
smf_enable_instance(3SCF)
NAME
smf_enable_instance, smf_disable_instance,
smf_refresh_instance, smf_restart_instance,
smf_maintain_instance, smf_degrade_instance,
smf_restore_instance, smf_get_state, smf_state_to_string,
smf_state_from_string - administrative interface to the Ser-
vice Configuration FacilitySYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
int smf_enable_instance(const char *instance, int flags);
int smf_disable_instance(const char *instance, int flags);
int smf_refresh_instance(const char *instance);
int smf_restart_instance(const char *instance);
int smf_maintain_instance(const char *instance, int flags);
int smf_degrade_instance(const char *instance, int flags);
int smf_restore_instance(const char *instance);
char *smf_get_state(const char *instance);
const char *smf_state_to_string(int32_t state_code);
int32_t smf_state_from_string(const char *state);
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.SunOS 5.11 Last change: 30 Jul 2010 1
Service Configuration Facility Library Functionssmf_enable_instance(3SCF)
The smf_enable_instance() function enables the service
instance specified by instance FMRI. If flags isSMF_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_disable_instance() function places the service
instance specified by instance FMRI in the disabled state and triggers the stop method (see svc.startd(1M)). If flagsis 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_refresh_instance() function causes the service
instance specified by instance FMRI to re-read its confi-
guration information.The smf_restart_instance() function restarts the service
instance specified by instance 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_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 flagis SMF_IMMEDIATE, which causes the instance to be moved into
the degraded state immediately.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 thedegraded state, smf_restore_instance() brings the specified
instance back to the online state.SunOS 5.11 Last change: 30 Jul 2010 2
Service Configuration Facility Library Functionssmf_enable_instance(3SCF)
The smf_get_state() 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")
The smf_state_to_string() function returns a pointer to an
immutable string containing the state equivalent tostate_code. Possible state strings are defined as above.
Possible state codes are defined as following:#define SCF_STATE_UNINIT 0x00000001
#define SCF_STATE_MAINT 0x00000002
#define SCF_STATE_OFFLINE 0x00000004
#define SCF_STATE_DISABLED 0x00000008
#define SCF_STATE_ONLINE 0x00000010
#define SCF_STATE_DEGRADED 0x00000020
The smf_state_from_string() function returns the value
equivalent to the string parameter state. Besides the strings defined above, this function accepts the string "all" as argument. In this case the returned value is:#define SCF_STATE_ALL 0x0000003F
RETURN VALUES
Upon successful completion, smf_enable_instance(),
smf_disable_instance(), smf_refresh_instance(),
smf_restart_instance(), smf_maintain_instance(),
smf_degrade_instance(), and smf_restore_instance() return 0.
Otherwise, they return -1.
Upon successful completion, smf_get_state() returns an allo-
cated string. Otherwise, it returns NULL.Upon successful completion smf_state_to_string() returns a
pointer to a constant string. Otherwise, it returns NULL.SunOS 5.11 Last change: 30 Jul 2010 3
Service Configuration Facility Library Functionssmf_enable_instance(3SCF)
Upon successful completion smf_state_from_string() returns
the macro value defined for the parameter state. Otherwiseit returns -1.
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_refresh_instance(),
smf_restart_instance(), smf_degrade_instance(), and
smf_restore_instance() functions will fail if:
SCF_ERROR_PERMISSION_DENIED
User does not have proper authorizations. Seesmf_security(5).
SCF_ERROR_BACKEND_ACCESS
The repository's backend refused access.SCF_ERROR_BACKEND_READONLY
SunOS 5.11 Last change: 30 Jul 2010 4
Service Configuration Facility Library Functionssmf_enable_instance(3SCF)
The repository's backend is read-only.
The smf_restore_instance() and smf_degrade_instance() func-
tions will fail if:SCF_ERROR_CONSTRAINT_VIOLATED
The function is called on an instance in an inappropri-
ate state.The scf_error(3SCF) function can be used to retrieve the
error value.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
svc.startd(1M), libscf(3LIB), scf_error(3SCF), attri-
butes(5), smf_security(5)
SunOS 5.11 Last change: 30 Jul 2010 5
Service Configuration Facility Library Functionssmf_enable_instance(3SCF)
SunOS 5.11 Last change: 30 Jul 2010 6