'\" te .\" Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved. .TH smf_enable_instance 3SCF "16 Apr 2012" "SunOS 5.11" "Service Configuration Facility Library Functions" .SH NAME smf_enable_instance, smf_disable_instance, smf_refresh_instance, smf_restart_instance, smf_maintain_instance, smf_degrade_instance, smf_restore_instance, smf_enable_instance_synchronous, smf_disable_instance_synchronous, smf_refresh_instance_synchronous, smf_restart_instance_synchronous, smf_maintain_instance_synchronous, smf_degrade_instance_synchronous, smf_restore_instance_synchronous, smf_get_state, smf_state_to_string, smf_state_from_string \- administrative interface to the Service Configuration Facility .SH SYNOPSIS .LP .nf cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ] #include \fBint\fR \fBsmf_enable_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_disable_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_refresh_instance\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBint\fR \fBsmf_restart_instance\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBint\fR \fBsmf_maintain_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_degrade_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_restore_instance\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBint\fR \fBsmf_enable_instance_synchronous\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_disable_instance_synchronous\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_refresh_instance_synchronous\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBint\fR \fBsmf_restart_instance_synchronous\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBint\fR \fBsmf_maintain_instance_synchronous\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_degrade_instance_synchronous\fR(\fBconst char *\fRinstance, \fBint\fR \fIflags\fR); .fi .LP .nf \fBint\fR \fBsmf_restore_instance_synchronous\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBint\fR \fBsmf_set_restarter\fR(\fBconst char *\fR\fIfmri\fR, \fBconst char *\fR\fIrestarter_fmri\fR); .fi .LP .nf \fBchar *\fR\fBsmf_get_state\fR(\fBconst char *\fR\fIinstance\fR); .fi .LP .nf \fBconst char *\fR\fBsmf_state_to_string\fR(\fBint32_t\fR \fIstate_code\fR); .fi .LP .nf \fBint32_t\fR \fBsmf_state_from_string\fR(\fBconst char *\fR\fIstate\fR); .fi .SH DESCRIPTION .sp .LP 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 \fBscf_instance_is_complete\fR(3SCF) for information about incomplete instances. .sp .LP The \fBsmf_enable_instance()\fR function enables the service instance specified by \fIinstance\fR FMRI. If \fBSMF_TEMPORARY\fR is set in \fIflags\fR, the enabling of the service instance is a temporary change, lasting only for the lifetime of the current system instance. The \fIflags\fR argument is set to \fB0\fR if no flags are to be used. .sp .LP The \fBsmf_disable_instance()\fR function places the service instance specified by \fIinstance\fR FMRI in the disabled state and triggers the stop method (see \fBsvc.startd\fR(1M)). If \fBSMF_TEMPORARY\fR is set in \fIflags\fR, the disabling of the service instance is a temporary change, lasting only for the lifetime of the current system instance. The \fIflags\fR argument is set to \fB0\fR if no flags are to be used. .sp .LP The \fBsmf_refresh_instance()\fR function causes the service instance specified by \fIinstance\fR FMRI to re-read its configuration information. .sp .LP The \fBsmf_restart_instance()\fR function restarts the service instance specified by \fIinstance\fR FMRI. .sp .LP The \fBsmf_set_restarter()\fR 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 \fIrestarter_fmri\fR is \fINULL\fR, then the restarter customization will be removed and set back to the file backed restarter. The master restarter \fBsvc.startd\fR is defined with the following: .sp .in +2 .nf #define SCF_INSTANCE_STARTD ((const char*)"svc:/system/svc/restarter:default") .fi .in -2 .sp .LP The \fBsmf_maintain_instance()\fR function moves the service instance specified by \fIinstance\fR into the maintenance state. If \fBSMF_IMMEDIATE\fR is set in \fIflags\fR, the instance is moved into maintenance state immediately, killing any running methods. If \fBSMF_TEMPORARY\fR is set in \fIflags\fR, the change to maintenance state is a temporary change, lasting only for the lifetime of the current system instance. The \fIflags\fR argument is set to \fB0\fR if no flags are to be used. .sp .LP The \fBsmf_degrade_instance()\fR function moves an online service instance into the degraded state. This function operates only on instances in the online state. The \fIflags\fR argument is set to \fB0\fR if no flags are to be used. The only available flag is \fBSMF_IMMEDIATE\fR, which causes the instance to be moved into the degraded state immediately. .sp .LP The \fBsmf_restore_instance()\fR 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, \fBsmf_restore_instance()\fR brings the specified instance back to the online state. .sp .LP The synchronous variants of the above functions each accept the same arguments and behave in essentially the same manner. The only difference is that the synchronous variants do not return until the requested actions have completed. For a detailed explanation of when actions are complete, see \fBscf_actionset_create\fR(3SCF). .sp .LP The \fBsmf_get_state()\fR 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: .sp .in +2 .nf #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") .fi .in -2 .sp .LP The \fBsmf_state_to_string()\fR function returns a pointer to an immutable string containing the state equivalent to \fIstate_code\fR. Possible state strings are defined as above. Possible state codes are defined as following: .sp .in +2 .nf #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 .fi .in -2 .sp .LP The \fBsmf_state_from_string()\fR 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: .sp .in +2 .nf #define SCF_STATE_ALL 0x0000003F .fi .in -2 .SH RETURN VALUES .sp .LP Upon successful completion, \fBsmf_enable_instance()\fR, \fBsmf_disable_instance()\fR, \fBsmf_refresh_instance()\fR, \fBsmf_restart_instance()\fR, \fBsmf_maintain_instance()\fR, \fBsmf_degrade_instance()\fR, \fBsmf_set_restarter()\fR, and \fBsmf_restore_instance()\fR return \fB0\fR. Otherwise, they return \fB-1\fR\&. .sp .LP Upon successful completion, \fBsmf_enable_instance_synchronous()\fR, \fBsmf_disable_instance_synchronous()\fR, \fBsmf_refresh_instance_synchronous()\fR, \fBsmf_restart_instance_synchronous()\fR, \fBsmf_maintain_instance_synchronous()\fR, \fBsmf_degrade_instance_synchronous()\fR return 0. Otherwise, they return \fB-1\fR\&. .sp .LP Upon successful completion, \fBsmf_get_state()\fR returns an allocated string. Otherwise, it returns \fINULL\fR. .sp .LP Upon successful completion \fBsmf_state_to_string()\fR returns a pointer to a constant string. Otherwise, it returns \fINULL\fR. .sp .LP Upon successful completion \fBsmf_state_from_string()\fR returns the macro value defined for the parameter state. Otherwise it returns -1. .SH ERRORS .sp .LP These functions will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_MEMORY\fR\fR .ad .sp .6 .RS 4n The memory allocation failed. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR .ad .sp .6 .RS 4n The \fIinstance\fR FMRI or \fIflags\fR argument is invalid. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NOT_FOUND\fR\fR .ad .sp .6 .RS 4n The FMRI is valid but there is no matching complete instance found. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR .ad .sp .6 .RS 4n The connection to repository was broken. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR .ad .sp .6 .RS 4n The server has insufficient resources. .RE .sp .LP The \fBsmf_maintain_instance()\fR, \fBsmf_refresh_instance()\fR, \fBsmf_restart_instance()\fR, \fBsmf_degrade_instance()\fR, \fBsmf_set_restarter()\fR, and \fBsmf_restore_instance()\fR functions (including the synchronous variants) will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR .ad .sp .6 .RS 4n User does not have proper authorizations. See \fBsmf_security\fR(5). .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR .ad .sp .6 .RS 4n The repository's backend refused access. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR .ad .sp .6 .RS 4n The repository's backend is read-only. .RE .sp .LP The \fBsmf_restore_instance()\fR and \fBsmf_degrade_instance()\fR functions (and the synchronous variants) will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR .ad .sp .6 .RS 4n The function is called on an instance in an inappropriate state. .RE .sp .LP The \fBsmf_set_restarter()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR .ad .sp .6 .RS 4n The function is called with a restarter fmri that is not an instance or is not online. .RE .sp .LP The \fBscf_error\fR(3SCF) function can be used to retrieve the error value. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe .TE .SH SEE ALSO .sp .LP \fBsvc.startd\fR(1M), \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_instance_is_complete\fR(3SCF), \fBattributes\fR(5), \fBsmf_security\fR(5), \fBscf_actionset_create\fR(3SCF)