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 Service Configuration Facility

Synopsis

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

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);

int smf_set_restarter(const char *fmri, const char *restarter_fmri);

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. They also fail on incomplete instances. See scf_instance_is_complete(3SCF) for information about incomplete instances.

The smf_enable_instance() function enables the service instance specified by instance FMRI. If SMF_TEMPORARY is set in flags, 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 used.

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 SMF_TEMPORARY is set in flags, 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 used.

The smf_refresh_instance() function causes the service instance specified by instance FMRI to re-read its configuration information.

The smf_restart_instance() function restarts the service instance specified by instance FMRI.

The smf_set_restarter() function sets the delegated restarter for the given instance. If the instance is online, the instance will be stopped before the change and restarted after the change is complete. If the restarter_fmri is NULL, then the restarter customization will be removed and set back to the file backed restarter. The master restarter svc.startd is defined with the following:

#define SCF_INSTANCE_STARTD  ((const char*)"svc:/system/svc/restarter:default")

The smf_maintain_instance() function moves the service instance specified by instance into the maintenance state. If SMF_IMMEDIATE is set in flags, the instance is moved into maintenance state immediately, killing any running methods. If SMF_TEMPORARY is set in flags, 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 used.

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 used. The only available flag is 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 the degraded state, smf_restore_instance() brings the specified instance back to the online state.

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 to state_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(), smf_set_restarter(), and smf_restore_instance() return 0. Otherwise, they return –1.

Upon successful completion, smf_get_state() returns an allocated string. Otherwise, it returns NULL.

Upon successful completion smf_state_to_string() returns a pointer to a constant string. Otherwise, it returns NULL.

Upon successful completion smf_state_from_string() returns the macro value defined for the parameter state. Otherwise it 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 complete 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(), smf_set_restarter(), and smf_restore_instance() functions will fail if:

SCF_ERROR_PERMISSION_DENIED

User does not have proper authorizations. See smf_security(5).

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() and smf_degrade_instance() functions will fail if:

SCF_ERROR_CONSTRAINT_VIOLATED

The function is called on an instance in an inappropriate state.

The smf_set_restarter() function will fail if:

SCF_ERROR_CONSTRAINT_VIOLATED

The function is called with a restarter fmri that is not an instance or is not online.

The scf_error(3SCF) function can be used to retrieve the error value.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

svc.startd(1M), libscf(3LIB), scf_error(3SCF), scf_instance_is_complete(3SCF), attributes(5), smf_security(5)