NAME
settune_txn() — sets the values of kernel tunable parameters in a transaction
SYNOPSIS
#include <sys/dyntune.h>
int settune_txn (uint64_t version,
struct ktune_context *transaction,
size_t struct_size,
uint64_t num_elements,
char *err_buf,
uint64_t *err_bufsize,
uint64_t stf_flags);
PARAMETERS
- version
The version parameter should always be set to
SETTUNE_VERSION.
- transaction
The details of the changes are specified in an array of
ktune_context
structures. Each
ktune_context
structure
provides context to the changes to be made to a single
tunable, and contains at least the following fields, in
unspecified order:
- char *kct_name
The name of the tunable parameter to be changed. NULL-terminated ASCII string.
- uint64_t ktc_value
The value to which the tunable parameter must be set.
- uint64_t ktc_flags
These are flags to describe this change within the transaction. Valid flags
and their corresponding connotations are:
- TCF_CURRVALUE
The current value of the tunable should be changed to the value
specified in the
ktc_value
parameter. This is allowed for all
tunables. Setting the current value of a tunable that the
system is tuning automatically turns off the automatic
tuning.
- TCF_DEFAULT
The tunable parameter is switched to its default
state. For tunables that can be tuned by the system, the
automatic tuning is turned on. The value specified in the
ktc_value
parameter is ignored.
- size
The size of a
ktune_context
structure, as understood by the
caller.
- num_elements
The number of tunables that are being modified in this call.
- err_buf
Errors or warning messages that give details about the
tuning are passed back in the
err_buf,
which must specify an
address in the caller's space. The messages will be in
English and returned as NULL-terminated ASCII strings. A
NULL
string terminates the error messages.
- err_bufsize
The parameter
err_bufsize
is a pointer to a variable containing the size of the
err_buf
buffer (in bytes).
Upon completion of the system call,
err_bufsize
will contain the size necessary for all the error and/or
warning messages for the transaction. If this value is greater
than the original
err_bufsize
value, the messages have been truncated to fit into
err_buf.
A buffer of size 300 bytes per tunable is
usually sufficient for the error buffer.
- stf_flags
The following values are valid for the
stf_flags
parameter
and their corresponding connotations are:
- STF_NEXTBOOT
Hold all requested changes for next boot instead of applying
them immediately. Without this flag, changes are applied
immediately. (If this flag is not set, and the changes
cannot be applied immediately,
settune_txn()
returns an error.)
- STF_VALIDATE
Check the requested changes, but do not actually make any change.
With this flag set,
settune_txn()
will return the same exit code and error and warning messages
as if it were actually making the change, but no change will be made.
DESCRIPTION
This function is used to modify the values of a set of kernel tunable
parameters at the same time. The caller needs to have the
SYSATTR
privilege to make this call. Changes are made to the tunables
using a transactional change model using a three-phase commit
where the following rules apply:
None of the changes within a transaction succeed or all of the
changes within a transaction succeed. There are no in-betweens.
No duplicates are allowed within a transaction, where
duplicates are defined as more than one change to
a tunable.
There are no restrictions on the order in which the tunables
need to be specified within a transaction.
If any of the tunables in a transaction require a reboot to
take effect, then the entire transaction requires a reboot to
take effect i.e. the effects of all the changes within the
transaction are visible only on a reboot.
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
kcweb(1M)
online help for details.)
The
tuneinfo2(2)
call can give information about whether or not
changes to a parameter are allowed, or will require a reboot, or
can be tuned automatically. Some individual parameters may have
specific notes regarding their behavior when changed;
consult the online help in
kcweb(1M)
for details on each specific parameter.
Persistence of Changes
Changes to parameter values made with
settune_txn()
will remain effective across reboots in this release of HP-UX.
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.
Changes to parameter values made with
settune_txn()
may not remain effective across reboots in future releases of HP-UX.
Security Restrictions
Some or all of the actions associated with this system call require the
SYSATTR
privilege.
Processes owned by the superuser have this privilege.
Processes owned by other users may have this privilege, depending on system
configuration.
See
privileges(5)
for more information about privileged access on
systems that support fine-grained privileges.
RETURN VALUES
- STR_OK
The values of the parameters have been changed and the new
values are effective immediately.
- STR_REBOOT
The new values of the parameters have been held pending and
will be effective at the next reboot.
- STR_ERROR
The function did not complete successfully. None of the
changes were applied. The detailed error messages are in the
buffer
err_buf.
If the buffer size returned in
err_bufsize
is greater than the size of
err_buf ,
there were more error messages than have
been returned. To get the remaining errors, increase the
size of the buffer and try again.
- STR_WARN
The function completed successfully, but there were
warning messages generated. These warning messages
are in the buffer,
err_buf.
If the buffer size returned in
err_bufsize
is greater than the size of
err_buf ,
some warning messages were generated which did not fit into
the buffer.
ERRORS
When the function returns
STR_ERROR
the global variable errno will be set to one of the following values:
- ENOENT
One or more of the specified tunables does not exist.
- EPERM
The caller does not have the
SYSATTR
privilege.
- EBADVER
The
version
parameter is not valid.
- EINVAL
One or more of the specified values within the transaction
are not within the acceptable range of values for the
corresponding parameters.
- EINVAL
At least one transaction rule was violated and hence none of the
changes were made.
- EINVAL
The changes within the transaction could not be applied
immediately. One or more of the tunables within the transaction
either do not support pending values or the
STF_NEXTBOOT
flag was not set.
- EINVAL
The combination of flags specified is invalid.
- EINVAL
The number of elements specified is zero.
- EINVAL
The size of a
ktune_context
structure as specified by
struct_size
is invalid.
- EINVAL
The number of elements specified is greater than the number of
tunables available.
- EFAULT
err_buf
or
err_bufsize
specifies an address that is inaccessible.
- EIO
The Kernel Registry Service was either unavailable or
encountered an error.
- ENOMEM
Insufficient memory to accommodate the changes within the
transaction.
WARNING
The caller must have the
SYSATTR
privilege to use this call.
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 configuration saved as a
backup;
if the system fails to boot after a tunable change, boot from that backup
kernel configuration. Keep good records of all tunable changes so that they
can be reversed if they degrade system performance. (Tunable changes made with
settune_txn()
are automatically logged to
syslog.)
If the tunables being changed through
settune_txn(2)
are used in expressions that set the values of other tunables, those
expressions will not be re-evaluated and those tunable values will not
be updated. If expression evaluation is desired, use
kctune(1M)
to set tunable values.
AUTHOR
settune_txn()
was developed by Hewlett-Packard Company.