NAME
settune — set the value of a kernel tunable parameter
SYNOPSIS
#include <sys/dyntune.h>
int settune(const char *tunable,
uint64_t value,
unsigned int flags);
DESCRIPTION
This function sets the value of the kernel tunable parameter named
tunable
to the supplied
value.
This new value will take effect immediately, except in the cases noted below.
Some parameters cannot be changed without rebuilding the OS kernel, and
then booting that rebuilt kernel.
settune()
will return an error
(ENOTSUP)
if asked to change one of these parameters.
Some parameters represent limits on resources that can be consumed by
individual processes. In general, changes to these parameters do not
affect processes that are running at the time the change is made; they
affect only new programs started (with
exec(2)
or an equivalent) after that time.
(Some specific parameters may be exceptions to this general rule;
see the documentation for those parameters
in the SAM online help for details.)
If the
STF_DEFAULT
flag is set in the
flags
parameter, the value of the tunable parameter will be set to its
hard-coded default value. In this case, the
value
parameter to
settune()
will be ignored.
The
tuneinfo(2)
call can give information about whether or not changes to a parameter are
allowed, or will require a reboot. Some individual parameters may have
specific notes regarding their behavior when changed; consult the online
help in SAM for details on each specific parameter.
Persistence of Changes
Changes to parameter values made with
settune()
will remain effective across reboots. Tunable parameter values are stored
in the Kernel Registry database. Each time the system boots, it reads the
parameter values from the database and restores them.
There is a separate Kernel Registry database for each different kernel file
name. For example,
/stand/vmunix
has a different set of stored parameter values than
/stand/vmunix.other.
settune()
always changes the database corresponding to the kernel file from which the
system was last booted. Its changes do not affect any other database.
Whenever a kernel gets rebuilt, using SAM,
mk_kernel(1M),
or some other method, the Kernel Registry database will be erased and
replaced with the tunable parameter values compiled into the new kernel.
Therefore, parameter changes made using
settune()
do
not
persist across kernel rebuilds. To make a parameter change which persists
across kernel rebuilds, the
system
files read during the kernel build process must be updated. Use SAM or
kmtune(1M)
to do this.
RETURN VALUE
This function returns one of the following values:
- STR_OK
The value of the specified parameter has been changed. The new value is
effective immediately.
- STR_PARTIAL
The value of the specified parameter has been changed. However, some
processes exceeded the resource limits implied by the new parameter value.
The changed parameter value does not affect those processes or any future
children of them.
- STR_ERROR
The function did not complete successfully. The value of the specified
parameter has not been changed.
ERRORS
If this function returns
STR_ERROR
to indicate an error, the global variable
errno
will be set to one of the following values, to indicate the error that
occurred:
- [ENOENT]
The specified tunable parameter does not exist.
- [EFAULT]
tunable
specifies an address that is inaccessible.
- [EPERM]
The caller does not have super-user privileges.
- [EINVAL]
The specified value is not within the acceptable range for the specified
parameter.
- [EBUSY]
The value of the parameter could not be changed immediately.
- [ENOTSUP]
The specified parameter cannot be changed without rebuilding the kernel.
- [EIO]
The Kernel Registry Service was unavailable or encountered an error.
- [ENOMEM]
Insufficient memory to accommodate the new parameter value.
WARNINGS
It is possible to seriously degrade system performance, or even render a
system unbootable, with incorrect tunable settings. Use care when setting
tunable values. Always have a known working kernel saved as a backup;
if the system fails to boot after a tunable change, boot from that backup
kernel. Keep good records of all tunable changes so that they can be
reversed if they degrade system performance. (Tunable changes made with
settune()
are automatically logged to
syslog
and to the Kernel Logging system.)
AUTHOR
settune()
was developed by Hewlett-Packard Company.
Printable version
