path: root/usr/src/man/man3scf/smf_enable_instance.3scf

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2020 Joyent, Inc.
.\" 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]
.TH SMF_ENABLE_INSTANCE 3SCF "May 15, 2020"
.SH NAME
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
.SH SYNOPSIS
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\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_disable_instance_with_comment\fR(\fBconst char *\fR\fIinstance\fR,
    \fBint\fR \fIflags\fR, \fBconst char *\fR\fIcomment\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
\fBchar *\fR\fBsmf_get_state\fR(\fBconst char *\fR\fIinstance\fR);
.fi

.SH 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.
.sp
.LP
The \fBsmf_enable_instance()\fR function enables the service instance specified
by \fIinstance\fR FMRI. If \fIflags\fR is \fBSMF_TEMPORARY\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 use.
.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 \fIflags\fR is \fBSMF_TEMPORARY\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 use.
.sp
.LP
The \fBsmf_disable_instance_with_comment()\fR function behaves the same as
\fBsmf_disable_instance()\fR, except the given free-form comment is recorded
under the \fIcomment\fR property, as reported by \fBsvcs\fR(1).
The comment may be up to \fBSCF_COMMENT_MAX_LENGTH\fR characters including
the NUL terminator.
.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_maintain_instance()\fR function moves the service instance specified
by \fIinstance\fR into the maintenance state. If \fIflags\fR is
\fBSMF_IMMEDIATE\fR, the instance is moved into maintenance state immediately,
killing any running methods. If \fIflags\fR is \fBSMF_TEMPORARY\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 use.
.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 use.
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 \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

.SH RETURN VALUES
Upon successful completion, \fBsmf_enable_instance()\fR,
\fBsmf_disable_instance()\fR, \fBsmf_disable_instance_with_comment()\fR,
\fBsmf_refresh_instance()\fR, \fBsmf_restart_instance()\fR,
\fBsmf_maintain_instance()\fR, \fBsmf_degrade_instance()\fR,
and \fBsmf_restore_instance()\fR return \fB0\fR.
Otherwise, they return \fB-1\fR\&.
.sp
.LP
Upon successful completion, smf_get_state returns an allocated string.
Otherwise, it returns \fINULL\fR.
.SH ERRORS
These functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
The memory allocation failed.
.RE

.sp
.ne 2
.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
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
The FMRI is valid but there is no matching instance found.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to repository was broken.
.RE

.sp
.ne 2
.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, and
\fBsmf_restore_instance()\fR functions will fail if:
.sp
.ne 2
.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
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The repository's backend refused access.
.RE

.sp
.ne 2
.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
will fail if:
.sp
.ne 2
.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 \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
\fBsvc.startd\fR(1M), \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF),
\fBattributes\fR(5), \fBsmf_security\fR(5), \fBsvcs\fR(1)