settune_txn(2) settune_txn(2)
NAME [Toc] [Back]
settune_txn(2) - sets the values of kernel tunable parameters in a
transaction
SYNOPSIS [Toc] [Back]
#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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
The tunable parameter is
switched to its default state.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
settune_txn(2) settune_txn(2)
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 [Toc] [Back]
This function is used to modify the values of a set of kernel tunable
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
settune_txn(2) settune_txn(2)
parameters at the same time. The caller needs to have super-user
privileges 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 [Toc] [Back]
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.
RETURN VALUES [Toc] [Back]
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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
settune_txn(2) settune_txn(2)
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 [Toc] [Back]
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 super-user privileges.
[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] The transaction rules were 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.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
settune_txn(2) settune_txn(2)
[EIO] The Kernel Registry Service was either
unavailable or encountered an error.
[ENOMEM] Insufficient memory to accommodate the changes
within the transaction.
WARNING [Toc] [Back]
The caller must have super-user permissions 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.)
AUTHOR [Toc] [Back]
settune_txn() was developed by Hewlett-Packard Company.
SEE ALSO [Toc] [Back]
kctune(1M), kcweb(1M), mk_kernel(1M), gettune(2), settune(2),
tuneinfo2(2).
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003 [ Back ] |
